Skip to content

Quick Start Guide

Jump to bottom
Radek Pazdera edited this page Aug 14, 2013 · 16 revisions

Warning: This page needs reviewing!

If this is your first visit to this Wiki and you are not sure what LNST is yet, we suggest you first take a look at the Introductory Guide where you will find the basic information about our project and what it can do.

This document will very quickly guide you through all the steps you need to take in order to successfully run a single LNST recipe. It is intended to demonstrate the functionality so that you can determine if this is something you are looking for or not. For that reason we won't be going into many details on how some parts work, though we will provide links to more in-depth pages.

Requirements for this guide are:

  • two slave machines that are connected to the same network segment
  • controller machine that has a separate connection to both slave machines

We recommend running Fedora 19+ on all of the machines.

1. Installation

If you are running Fedora 18+ run this command to install LNST on the controller:

yum install lnst-ctl

and on the slave machines run this:

yum install lnst-slave

Alternatively, if you are not running Fedora 18+ or if you want any further information regarding the installation, please refer to the Installation Guide.

For the purposes of this introduction we can use the default configuration of both the slaves and the controller, therefore we will not be discussing configuration. However if you want to see how to configure LNST, take a look at the Configuration Guide.

2. Create a Machine Pool

In order to be able to run a test, you need to set up a machine pool. Machine Pools are used by the controller to lookup machines suitable for your test. They need to be set up properly so that the controller can execute your recipes. There is no need to set up anything regarding the machine pool on the slave machines so everything in this section is done on the controller itself.

First you need to tell LNST where it will find the pool we are going to create. For that, create a configuration file lnst-ctl.conf inside the directory ~/.lnst/ on your controller, if the directory doesn't exist create it as well:

mkdir ~/.lnst
cd ~/.lnst/
touch lnst-ctl.conf

After that tell LNST to use the directory ~/.lnst/pool/ as a pool directory, by placing this inside the configuration file:

[environment]
machine_pool_dirs = ~/.lnst/pool/

Now to create the pool itself, start by creating the pool directory, on the controller machine:

mkdir ~/.lnst/pool

Inside it create two files slave1.xml and slave2.xml with these contents:

<slavemachine>
    <params>
        <param name="hostname" value="HOSTNAME"/>
    </params>
    <interfaces>
        <eth network="A" id="1">
            <params>
                <param name="hwaddr" value="HWADDR"/>
            </params>
        </eth>
    </interfaces>
</slavemachine>

In both files replace HOSTNAME with hostnames or IP addresses of the slave machines and HWADDR with MAC addresses of the network interfaces that are used for the connection between the slaves. The fact that both interfaces have the same network attribute indicates they are both connected to the same physical network segment (e.g. they are connected to the same switch, bridge, or possibly directly to each other).

At this point the machine pool is ready; further information on setting up machine pools can be found the MachinePool Setup Guide.

3. Create a recipe

Now all that you need to run a test with LNST is a recipe. An LNST recipe is an XML file describing the test that LNST should run. For the purposes of this guide we will be using this recipe:

<lnstrecipe>
  <machines>
    <machine id="slave1">
        <params/>
        <interfaces>
            <eth id="testifc1" network="A">
                <addresses>
                    <address value="192.168.200.2/24"/>
                </addresses>
            </eth>
        </interfaces>
    </machine>

    <machine id="slave2">
        <params/>
        <interfaces>
            <eth id="testifc2" network="A">
                <addresses>
                    <address value="192.168.200.3/24"/>
                </addresses>
            </eth>
        </interfaces>
    </machine>
  </machines>

  <task>
    <run module="IcmpPing" machine_id="slave1">
      <options>
        <option name="addr" value="{ip(slave2,testifc2)}"/>
        <option name="count" value="10"/>
      </options>
    </run>
  </task>
</lnstrecipe>

Copy it and put it into a file named, for example, recipe.xml.

The recipe consists of two parts:

  • environment description seen in the contents of the tag machines specifies two slave machines, each with one network interface connected to the same network A, we also configure these interfaces to have specific IP addresses.
  • the description of actions can be seen in the tag task which tells LNST to run the test IcmpPing on machine slave1 with the target being the network interface of machine slave2.

This is a basic recipe performing a Ping check between two machines, for more information on creating your own recipes you can visit the page Recipes.

4. Run the recipe and get the results

If you followed all the previous steps, you should have everything important prepared and are ready to run the test. First start the lnst-slave service on both slave machines:

systemctl start lnst-slave.service

And now, finally, run the test on the controller:

lnst-ctl recipe.xml run

For more information on running LNST visit the page LNST Invocation.

If you've done everything correctly you should see the test being executed and get some results about what happened. These results can also be found on the controller in the default location for storing logs which is ~/.lnst/logs/.

As an example, the results from this test should look something like this:

$ lnst-ctl recipe.xml run
16/01 14:41:35       (127.0.0.1) INFO: Provisioning initialized
16/01 14:41:35       (127.0.0.1) INFO:   machine slave1 uses slave1
16/01 14:41:35       (127.0.0.1) INFO:   machine slave2 uses slave2
16/01 14:41:35       (127.0.0.1) INFO: Preparing machine slave1
16/01 14:41:35       (127.0.0.1) INFO: Connecting to RPC on machine 192.168.122.109
16/01 14:41:36       (127.0.0.1) INFO: Skipping cleanup on machine slave1
16/01 14:41:36       (127.0.0.1) INFO: Initializing provisioned system (slave1)
16/01 14:41:36       (127.0.0.1) INFO: Configuring interface testifc1 on 192.168.122.109
16/01 14:41:35 (192.168.122.109) INFO: Initializing 'eth' device class
16/01 14:41:36       (127.0.0.1) INFO: Preparing machine slave2
16/01 14:41:36       (127.0.0.1) INFO: Connecting to RPC on machine 192.168.122.30
16/01 14:41:37       (127.0.0.1) INFO: Skipping cleanup on machine slave2
16/01 14:41:37       (127.0.0.1) INFO: Initializing provisioned system (slave2)
16/01 14:41:37       (127.0.0.1) INFO: Configuring interface testifc2 on 192.168.122.30
16/01 14:41:36  (192.168.122.30) INFO: Initializing 'eth' device class
16/01 14:41:37       (127.0.0.1) INFO: Executing command: [type (test), machine_id (slave1), value (IcmpPing)]
16/01 14:41:46       (127.0.0.1) INFO: Result data: {'rate': 100}
16/01 14:41:45 (192.168.122.109) INFO: Cleaning up 'eth' device class.
16/01 14:41:45  (192.168.122.30) INFO: Cleaning up 'eth' device class.
16/01 14:41:46       (127.0.0.1) INFO: ====================== SUMMARY ======================
16/01 14:41:46       (127.0.0.1) INFO: *PASS* recipe.xml
16/01 14:41:46       (127.0.0.1) INFO: =====================================================

If you see something similar to this then congratulations to you, you have just successfully finished your first LNST test. If you want to continue using LNST we suggest you read the rest of the documentation. You can also visit the page Quick Guides for more simple tests you can quickly try with LNST.

If you encounter any problems you can find us on our IRC channel or mailing list.

Clone this wiki locally