LNST Task API

After some time of writing LNST tasks in XML you probably keep repeating:

"XML is such a bad language to write sequence of commands, it's so limited. This should be done differently!!"

And you're quite right. We got tired of this, too. Therefore we've added a new feature that allows you to use your own python program that drives the test execution with ability to access all of the LNST infrastructure - machine properties, command execution, template functions, background execution - from the program. Besides the LNST infrastructure you can benefit from the Python language facilities as loops, conditional executions and whatever Python provides in it's library.

Note that the machine requirements description still needs to be provided as an XML code in the recipe.

1. Usage in LNST recipe

Let's assume that your Python program you're using for the task execution is called task_check_ping.py. To include it in the recipe use following code:

<lnstrecipe>
    <machines>
        <machine id="1">
            <interfaces>
                <eth network="ttnet" id="testiface"/>
                    <addresses>
                        <address value="192.168.100.240/24"/>
                    </addresses>
                </eth>
            </interfaces>
        </machine>
        <machine id="2">
            <interfaces>
                <eth network="ttnet" id="testiface" type="eth">
                    <addresses>
                        <address value="192.168.100.215/24"/>
                    </addresses>
                </eth>
            </interfaces>
        </machine>
    </machines> 

    <!-- This is it! -->
    <task python="task_check_ping.py"/>
</lnstrecipe>

1.1 Content of the task_check_ping.py

    # Mandatory import, the ctl handle contains the API
    from lnst.Controller.Task import ctl

    # Get handles for the machines
    m1 = ctl.get_machine("1")
    m2 = ctl.get_machine("2")

    # Set a config option (persistent=True)
    m1.config("/proc/sys/net/ipv4/conf/all/forwarding", "0", True)

    # run a shell command
    devname = m2.get_devname("testiface")
    m1.run("echo %s" % devname, timeout=30)

    # prepare a module for execution
    ping_mod = ctl.get_module("IcmpPing", addr=m2.get_ip("testiface", 0),
                              count=40, interval=0.2, limit_rate=95)

    # run the module twice on machine one
    ping_test = m1.run(ping_mod, timeout=30)
    ping_test = m1.run(ping_mod, bg=True, timeout=30)

    # make the controller wait
    ctl.wait(5)

    # interrupt the process
    ping_test.intr()

As you can see all that you need to do to access the LNST API is simply importing the Controller handle

   from lnst.Controller.Task import ctl

Let's have a closer look on the API itself.

2. Controller API

The controller handle provides following methods

• get_machine(self, machine_id) to get a machine API handle for the machine from the recipe spec with a specific id
• get_module(self, name, **kwargs) to get a test module API handle
• wait() to make controller wait for a specific amount of seconds

The get_machine() method returns a handle that is needed when you want to access the information about the interfaces or run a command on the machine. See the Machine API for details on how to do that or look at the examples below.

The get_module() simply returns the Test Module handle that can be run on a test machine. This method takes an optional keyword argument list to initialize the Test Module.

Finally the wait() method is an equivalent for the <ctl_wait> tag in the recipe xml. It takes one parameter seconds and it's value tells the controller how long it should wait before it continues in the task execution.

Examples

Controller API's get_machine() example

   m1 = ctl.get_machine("1")
   m2 = ctl.get_machine("2")

   ifc_ip = m2.get_ip("testiface")
   ifc_hwaddr = m2.get_hwaddr("testiface")

   m1.run("ping -c 5" + ifc_ip)
   m1.run("arp -n | grep -i " + ifc_hwaddr)

Controller API's get_module() example

Following example shows the IcmpPing module initialization and it's execution on the test machine.

   m1 = ctl.get_machine("1")
   m2 = ctl.get_machine("2")

   ping_module = ctl.get_module("IcmpPing", addr=m2.get_ip("testiface", 0),
                              count=40, interval=0.2, limit_rate=95)
   m1.run(ping_module)

Controller API's wait() example

   logging.info("I'll wait for 10 seconds")
   ctl.wait(10)
   logging.info("Task execution continues ...")

3. Machine API

Machine API provides following methods

• config(self, option, value, persistent=False) to configure values under /proc or /sys directories
• run(self, what, **kwargs) to run commands or test modules on the test machines
• get_devname(self, interface_id) to get the name of the interface on the test machine, e.g. eth0
• get_hwaddr(self, interface_id) to get the hardware address of the interface, e.g. 00:11:22:33:44:55:FF
• get_ip(self, interface_id, addr_number=0) to get the IP address of the interface, e.g. 192.168.1.10

The config() is the equivalent of the <config> command used in the recipe xml. It takes three parameters, the option defining the path to the file under /proc or /sys directory, the value containing the value to set the option to and persistent flag to make the value persistent between individual tasks.

The run() is the equivalent of the <run> command used in the recipe xml. The parameter what is used to pass either Test Module handle obtained thorugh the Machine API's get_module() method or string containing a command to be run on the command line. This method takes following keyword arguments that modify its behaviour. For the usage see the examples section below.

bg	boolean	if set to True the command will be run in background
expect	["pass"|"fail"]	if set to "fail" the command is expected to fail - in other words if it succeeds this is considered as the testcase failed
timeout	integer	time limit in seconds
tool	string	run from a tool (the same as from in recipe xml)

Last three methods get_devname(), get_hwaddr(), get_ip() are used to get information about configured test interfaces. All of them take one common parameter interface_id to identify the interface id that is set in the recipe xml. Method get_ip() takes an optional parameter addr_number that is used as index to the address list if more than one address has been set for the interface.

Examples

Machine API's config() example

    m1 = ctl.get_machine("1")

    m1.config("/proc/sys/net/ipv4/conf/all/forwarding", "0", True)

Machine API's run() examples

First example shows how to run the netcat tool on a test machine's command line.

    m1 = ctl.get_machine("1")

    ifc_ipaddr = m1.get_ip("testiface")
    m1.run("nc -l %s" % ifc_ipaddr)

As you could note the example above is not very useful since it would block the task execution so the following example modifies it a bit so the program is run in the background.

    m1 = ctl.get_machine("1")

    ifc_ipaddr = m1.get_ip("testiface")
    nc_cmd = m1.run("nc -l %s" % ifc_ipaddr, bg=True)

    ctl.wait(30)

    nc_cmd.kill()

Still not very useful, right? So, next example further extends the previous example and shows how to run a Test Module from the LNST Test Module library, in this example it is NetCat module as the client counterpart wrapper to the netcat tool

    m1 = ctl.get_machine("1")
    m2 = ctl.get_machine("2")

    listen_port = 1234

    ifc_ipaddr = m1.get_ip("testiface")
    nc_cmd = m1.run("nc -l %s %s" % (ifc_ipaddr, listen_port), bg=True)

    nc_module = ctl.get_module("NetCat", addr=ifc_ipaddr, port=listen_port, duration=30)
    m2.run(nc_module)

    nc_cmd.wait()

The last example shows how to run 3rd party tools. We'll be using the tcp_conn tool packaged within LNST.

4. Module API

5. Process API