Skip to content

Installation Guide

Jump to bottom
jtluka edited this page Apr 10, 2017 · 24 revisions

This document describes a few ways of installing LNST. There are two options supported by our team at the moment. You can download the current RPM packages or use Python's distutils to install LNST directly from the sources.

In case you would like to create a package for a different distribution, don't hesitate to contact us. We'll be happy to help you! We can also include your package in the installation options listed bellow.

LNST dependencies are:

  • python2.6 for the main application to work
  • python-pyroute2
    • if your distro does not provide a pyroute2 rpm use the following command to install it (requires python-setuptools package): /bin/easy_install pyroute2
  • bzip2
  • tar

The controller also needs:

  • python-lxml
  • python-requests if you want to connect to PerfRepo

Slave machines also require following packages for deploying test tools:

  • gcc
  • make
  • ethtool
  • iproute
  • bridge-utils
  • dbus-python

Optional dependencies are:

  • tcpdump
  • nc (netcat)
  • iperf
  • netperf
  • iptables
  • NetworkManager if you want LNST to use it for configuration
  • libvirt if you want support for dynamically created test networks
  • libteam if you want lnst to be able to configure team devices
  • NetworkManager-team if you want to configure team devices using NetworkManager (Fedora 22+)
  • kernel-modules-extra (for Fedora, or a package that provides netem kernel module) if you want to use netem for simulating WAN behaviour
  • Open vSwitch if you want support for configuration of Open vSwitch bridge devices. If you have Open vSwitch installed you also need to have the database initialized otherwise LNST will fail during configuration. To do this refer to official Open vSwitch web page or if you're using a Fedora/RHEL distribution run this command:
$ ovsdb-tool create /etc/openvswitch/conf.db

These are either used by optional framework features or are required by tests modules distributed with LNST.

1. RPM for Fedora

LNST is available in Fedora repositories. There are three main packages lnst, lnst-ctl and lnst-slave, and one optional package lnst-recipes that contains the set of testing recipes that we maintain in the upstream repository.

1.1 lnst

The lnst package is a package used both by lnst-ctl and lnst-slave that contains common modules and functionality. It should be installed as a dependency of both the lnst-ctl and lnst-slave packages automatically.

1.2 lnst-ctl

Firstly it is necessary to install lnst-ctl to the controller machine, i.e., your own computer (or possibly a dedicated machine), that will be used to command and control its slaves.

# yum install lnst-ctl

1.2 lnst-slave

In the second step, you need to install lnst-slave package to all your test machines, i.e., virtual guests or physical machines dedicated for testing.

# yum install lnst-slave

After you've installed lnst-slave you will need to configure a few things on the slave machine so that everything works properly:

  1. stop firewalld if you're running Fedora 19+: systemctl stop firewalld.service you can also disable it permanently: systemctl disable firewalld.service

  2. clear iptables in case there are rules defined: iptables -F

  3. if you're running NetworkManager on your slave machines, you need to configure it so that it doesn't automatically try to connect unused interfaces. To do this, add line no-auto-default=* to the file /etc/NetworkManager/NetworkManager.conf under section [main]

Please bear in mind that disabling firewalls is a potential security risk and running lnst-slave on a machine is in itself a BIG security risk since it allows execution of code with root privileges. For this reason we STRONGLY RECOMEND that you use lnst in a secure test environment and not on publicly reachable machines.

This is basically everything you need to do. To start up the lnst-slave daemon directly you can use the following command:

# systemctl start lnst-slave.service

You can also set the daemon to launch automatically at start up by running the command:

# systemctl enable lnst-slave.service

Or you can run the service on the foreground like this:

# lnst-slave

2. Python's distutils

If you don't use Fedora you will need to install LNST directly from the sources. This method might seem a bit harder at first glance, but you will soon discover it is almost as easy as using the RPM.

2.1 Obtaining the Source Package

You can either get a snapshot directly from git (if you feel adventurous) or get a more stable release from the Downloads Section on LNST wiki.

2.2 Installation Using setup.py

After extracting the sources you will find a file called setup.py in the root directory of LNST source tree. This is the installation script you can use to install LNST.

$ su
# cd lnst/
# ./setup.py install

This will install code for both lnst-ctl and lnst-slave. Installing them separately using distutils is currently unsupported. You need to do this for all the machines involved, i.e., both the controller and the slaves.

lnst-slave service file will not be installed automatically. Init systems vary through distributions which led to the decision to exclude installation of service files or init scripts from distutils to maintain greater portability. A generic systemd service file (used for Fedora) is available in the source tree in dist/ directory. The following series of commands will install the service file and start the service:

# install -D -m 0644 dist/lnst-slave.service /lib/systemd/system/lnst-slave.service
# systemctl daemon-reload
# systemctl start lnst-slave.service

If your distribution does not use systemd, please refer to the documentation of your respective build system.

3. After Installation

Here are some tips for things you might be interested in after the installation.

3.1 Man pages

Both commands lnst-ctl and lnst-slave have a man page:

$ man 2 lnst-ctl
$ man 2 lnst-slave

3.2 Machine Pool Configuration

It is now required to setup a pool of test machines on the controller to be able to use LNST. The pool is a network of dedicated test machines (physical or virtual) that will be used for testing. LNST uses the pool to select suitable machines for your recipe. This will not only make your recipes portable to other sites with different pool setups (provided they match the requirements of your recipe), but it will also make it easier for you to use LNST!

For information about how to set up your machine pool go to the following article: Setup your machine pool

Clone this wiki locally