7:53 a.m.
commit 6961b4fb124c38908453d17899718403ed18ee7f
Author: Jan Tluka <jtluka(a)redhat.com>
Date: Thu May 3 17:18:02 2012 +0200
Adding documentation for LNST framework.
This is quite up-to-date documentation about the LNST. It has been
around for quite a long time but thanks to Radek we have the new bits
documented as well.
Documentation/LNSTIntro.html | 535 +++++++++++++++++++++
Documentation/README | 24 +
Documentation/controller-slave-communication.dia | Bin 0 -> 3304 bytes
Documentation/lnst_intro_images.sh | 15 +
Documentation/machineconfig-netconfig-mapping.dia | Bin 0 -> 3745 bytes
Documentation/real-hardware-setup.dia | Bin 0 -> 2925 bytes
6 files changed, 574 insertions(+), 0 deletions(-)
---
diff --git a/Documentation/LNSTIntro.html b/Documentation/LNSTIntro.html
new file mode 100644
index 0000000..227b560
--- /dev/null
+++ b/Documentation/LNSTIntro.html
@@ -0,0 +1,535 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="content-type" content="text/html;
charset=UTF-8" />
+ <title>LNST - Linux Network Stack Test</title>
+ <meta name="generator" content="Amaya, see
http://www.w3.org/Amaya/" />
+</head>
+
+<body>
+<h1>LNST Project</h1>
+
+<p></p>
+
+<h2>About</h2>
+
+<p>LNST is an automated testing framework focused on the Linux network stack
+testing. It supports bonding, vlan, bridging and macvlan.</p>
+
+<h3><em>People</em></h3>
+<ul>
+ <li>Jiří Pírko (jpirko) – author of the project, kernel developer</li>
+ <li>Jiří Župka (jzupka) – contributor, framework infrastructure implementation,
+ quality engineer</li>
+ <li>Jan Tluka (jtluka) – contributor, test development, Beaker
+ integration, quality engineer</li>
+ <li>Radek Pazdera - contributor, framework infrastructure implementation, test
development, quality engineer
+</ul>
+
+<h3><em>Communication channels</em></h3>
+
+<ul>
+ <li>We are on irc: #lnst @ freenode (irc://irc.freenode.net#lnst)</li>
+ <li>The development mailing list: <a
href="https://fedorahosted.org/mailman/listinfo/lnst-developers"...
+ </ul>
+
+
+<h3><em>Goals</em></h3>
+<ul>
+ <li>QE: extend our current network code coverage in Tier tests</li>
+ <li>Devel: create a tool/test environment to easily catch regressions in
+ network stack during development</li>
+</ul>
+
+<h3><em>Target audience</em></h3>
+<ul>
+ <li>developers (to catch regressions)</li>
+ <li>quality engineers (to develop new tests)</li>
+</ul>
+
+<h3><em>Topology</em></h3>
+
+<p>In the following picture you can see an example of the network topology
+along with the roles and communication paths. There are 3 basic entities, </p>
+<ul>
+ <li>controller </li>
+ <li>test machines</li>
+ <li>network infrastructure (network switches)</li>
+</ul>
+
+<p></p>
+
+<p style="text-align:left;margin-left:0;margin-right:auto;"><img
+alt="Roles and communication paths" src="real-hardware-setup.png"
+style="display: block; text-align: center; margin-left: auto; margin-right:
auto"
+width="712" height="279" /></p>
+
+<p></p>
+
+<p>In the picture you can see two network connections drawn in different
+colors. </p>
+
+<p>The green one is the <strong>controller path</strong> and is used to
setup
+network interfaces on machine1 and machine2 through the <strong>controller
+interfaces</strong> (eth3 on both test machines). The <strong>controller
+path</strong> is also used to do setup of the test switch and live changes on
+it such as vlan and bonding configuration, port disconnection, etc.</p>
+
+<p>The red one is the <strong>test path</strong> and is used for
network
+traffic generated in tests executed on test machines.</p>
+
+<p></p>
+<hr />
+
+<h2>Getting the source</h2>
+
+<p>You can access the sources at the following urls:</p>
+<ul>
+ <li><a
+
href="http://git.fedorahosted.org/git/?p=lnst.git">http://gi...
+</ul>
+
+<p>In your comand line checkout the code:</p>
+<pre>$ git clone git://git.fedorahosted.org/lnst.git</pre>
+
+<p></p>
+<hr />
+
+<h2>Source code structure</h2>
+
+<p></p>
+<pre>[./]
+ netconfig.py (tool to configure network interfaces based on xml
description)
+ nettestctl.py (tool to control remote machines/execute tests)
+ nettestslave.py (app that runs on remote machine and
+ accepts commands from controller (nettestctl.py))
+ switchconfig.py
+ swswitch.py
+
+[./Common] (common code for the framework)
+ Daemon.py
+ ExecCmd.py
+ LoggingServer.py
+ Logs.py
+ ProcessManager.py
+ ShellProcess.py
+ SlaveUtils.py
+ SshUtils.py
+ TestsCommon.py
+ Utils.py
+ XmlRpc.py
+
+[./example_recipes] (inspiration for test setups – netconfigs, machineconfigs,
recipes)
+
+[./NetConfig] (network configuration class implementation)
+ NetConfigCommon.py
+ NetConfigDevice.py
+ NetConfigDevNames.py
+ NetConfigParse.py (netconfig xml parser)
+ NetConfig.py
+
+[./NetTest] (test execution class implementation)
+ NetTestCommand.py
+ NetTestController.py
+ NetTestParse.py
+ NetTestParse.pyc
+ NetTestResultSerializer.py
+ NetTestSlave.py
+
+[./Switch] (network switch configuration)
+ SwitchConfigParse.py
+ SwitchCtl.py
+ SwitchDriversCommon.py
+
+[./Tests] (implementation of network tests)
+ TestDummyFailing.py
+ TestIcmp6Ping.py
+ TestIcmpPing.py
+ TestIperf.py
+ TestNetCat.py
+ TestPktCounter.py
+ TestPktgenTx.py
+</pre>
+
+<p></p>
+<hr />
+
+<h2>Setting up the test environmnent</h2>
+
+<h3><em>Remote connection setup</em></h3>
+
+<p>Every test machine has to be configured to allow remote SSH connection. This
+can be achieved either using keys or specifying root password in XML files
+(described below). It's mandatory to have a dedicated control network interface
+for the SSH connection that is used to setup network on additional network
+interfaces and execute tests. It is also important to separate "controller
+path" and "test path" infrastructure, e.g. using two switches.</p>
+
+<p></p>
+
+<h3><em>Required packages</em></h3>
+
+<p>Basically you need to have python installed. If you use RHEL5 on a machine
+you need to install additional package <strong>python-ctypes</strong> from
EPEL
+repository on it.</p>
+<ul>
+ <li><a
+
href="http://fedoraproject.org/wiki/EPEL">http://fedoraproje...
+ <li>rpm -ivh <a
+
href="http://download.fedoraproject.org/pub/epel/5/i386/epel-release...
+ <li><a
+
href="http://download.fedoraproject.org/pub/epel/5/i386/epel-release...
+ install python-ctypes</li>
+</ul>
+
+<p></p>
+<hr />
+
+<h2>LNST Recipes</h2>
+
+<p>The LNST recipes contains all information to do a test run.</p>
+
+<p>It consists of:</p>
+<ul>
+ <li><span
style="background-color:#ffc0cb">machineconfigs</span></li>
+ <li><span
style="background-color:#90ee90">netconfigs</span></li>
+ <li><span style="background-color:#add8e6">command
sequences</span></li>
+</ul>
+
+<p>The following XML code is an example of the LNST recipe:</p>
+<pre><nettestrecipe>
+ <machines>
+ <machine id="1">
+ <span
style="background-color:#ffc0cb"><netmachineconfig
source="example_recipes/machine_configs/config-f14peanut.xml"/></span>
+ <span style="background-color:#90ee90"><netconfig
source="example_recipes/net_configs/netconfig1.xml"/></span>
+ </machine>
+ <machine id="2">
+ <span
style="background-color:#ffc0cb"><netmachineconfig
source="my_recipes/config-f15.xml"/></span>
+ <span style="background-color:#90ee90"><netconfig
source="my_recipes/netconfig2.xml"/></span>
+ </machine>
+ </machines>
+
+ <span
style="background-color:#add8e6"><command_sequence></span>
+ <span style="background-color:#add8e6"><command
type="exec" value="sleep 4"/></span></pre>
+<pre> <span style="background-color:#add8e6"><command
type="test" machine_id="1" value="IcmpPing"
timeout="30"></span>
+ <span
style="background-color:#add8e6"><options></span>
+ <span style="background-color:#add8e6"><option
type="recipe_eval" name="addr"
value="['machines'][2]['netconfig'][1]['addresses'][0]"/></span>
+ <span style="background-color:#add8e6"><option
name="count" value="40"/></span>
+ <span style="background-color:#add8e6"><option
name="interval" value="0.2"/></span>
+ <span style="background-color:#add8e6"><option
name="limit_rate" value="95"/></span>
+ <span
style="background-color:#add8e6"></options></span>
+ <span
style="background-color:#add8e6"></command></span>
+ <span
style="background-color:#add8e6"></command_sequence></span>
+</nettestrecipe></pre>
+
+<p></p>
+
+<p>Every test machine's network setup is defined by two configuration XML
+snippets – MachineConfig describing the machine's real hardware (available
+NICs) and NetConfig describing configuration of these devices (IP addresses,
+bonding setup, bridging, vlans, etc.)</p>
+
+<h3><em>MachineConfig</em></h3>
+
+<p>The MachineConfig</p>
+<ul>
+ <li>describes test machine's control interface and login information (for
+ root access) - <strong>info</strong> tag</li>
+ <li>describes available network interfaces of a test machine –
+ <strong>netdevice</strong> tags</li>
+</ul>
+
+<p>Example
(<em>example_recipes/machine_configs/config-f14peanut.xml</em>):</p>
+
+<p></p>
+<pre><netmachineconfig>
+ <info hostname="10.34.37.141" rootpass="aaa"/>
+ <netdevice type="eth" <span
style="background-color:#00ff00">phys_id="1"</span>
hwaddr="00:E0:4C:14:2E:5D"/>
+ <netdevice type="eth" <span
style="background-color:#00ff00">phys_id="2"</span>
hwaddr="00:30:4F:7F:FD:30"/>
+</netmachineconfig></pre>
+
+<p></p>
+
+<p>Test machine with this configuration will be accessible via IP address
+10.34.37.141 using root password 'aaa' (<strong>rootpass</strong>).
Two
+interfaces are made available for testing - one with MAC address
+00:E0:4C:14:2E:5D (<strong>hwaddr</strong>) exported as physical device
'1'
+(<strong>phys_id</strong>) and second with MAC address 00:30:4F:7F:FD:30
+exported as physical device '2' in LNST framework.</p>
+
+<p></p>
+
+<h3><em>NetConfig</em></h3>
+
+<p>Example
(<em>example_recipes/net_configs/netconfig1.xml</em>):</p>
+<pre><netconfig>
+ <netdevice id="1" type="eth" <span
style="background-color:#00ff00">phys_id="1"</span>/>
+ <netdevice id="2" type="eth" <span
style="background-color:#00ff00">phys_id="2"</span>/>
+ <netdevice id="3" <span
style="background-color:#add8e6">type="bond"</span>>
+ <options>
+ <option name="mode" value="1"/>
+ <option name="miimon" value="100"/>
+ <option name="primary" value="2"/>
+ </options>
+ <slaves>
+ <slave id="1"/>
+ <slave id="2"/>
+ </slaves>
+ <addresses>
+ <address value="192.168.101.1/24"/>
+ </addresses>
+ </netdevice>
+</netconfig></pre>
+
+<p></p>
+
+<p>This configuration snippet uses two physical devices
+(<strong>phys_id</strong>="1" and
<strong>phys_id</strong>="2") defined in the
+previous MachineConfig. It also defines third network device (<strong>netdevice
+id="3"</strong>) as <strong>bond</strong> device and adds the
two physical
+device as its <strong>slaves</strong>. Further options are defined in
+<strong>options</strong> element and IP address of the bond interface is
+defined in <strong>addresses</strong> element.</p>
+
+<p></p>
+
+<h3><em>Mapping of physical interfaces inside LNST
recipes</em></h3>
+
+<p></p>
+
+<p><img alt="machineconfig-netconfig-mapping"
+src="machineconfig-netconfig-mapping.png" width="793"
height="318" /></p>
+
+<p></p>
+
+<h3><em>Defining aliases</em></h3>
+<p>LNST allows you to define arbitrary <strong>aliases</strong> and
use
+them to access certain values from the whole recipe file while the value
+itself is included in the file only once. Definition of an alias occurs
+in the <code><define></code> tag anywhere in the
document:</p>
+<pre>
+<define>
+ <span style="background-color:#90ee90"><alias
name="ip_addr" value="192.168.0.1" /></span>
+ <span style="background-color:#add8e6"><alias
name="mask" value="24" /></span>
+</define>
+</pre>
+
+<p>Defined alias can be referenced from any element's attribute or text.
+For instance:</p>
+<pre>
+<netdevice id="2" type="eth">
+ <addresses>
+ <address value="<span
style="background-color:#90ee90">{$ip_addr}</span>/<span
style="background-color:#add8e6">{$mask}</span>"/>
+ </addresses>
+</netdevice>
+</pre>
+
+<h3><em>Command sequences</em></h3>
+
+<p>Command sequence in a LNST recipe is a list of commands that is executed
+on test machines or controller. </p>
+
+<p>Tasks can be of type:</p>
+<ul>
+ <li><strong>exec</strong> or</li>
+ <li><strong>test </strong>(can be run on test machines
only)</li>
+</ul>
+
+<p>The <strong>exec</strong> command is anything that you can enter on
a
+command line. E.g. </p>
+<ul>
+ <li>yum install tcpdump</li>
+ <li>echo 1 > /proc/net/ipv4/ip_forwarding</li>
+</ul>
+
+<p></p>
+
+<p>The <strong>test</strong> command is an implemented test. The code
of the
+test is present in Tests/Test<strong>IcmpPing</strong>.py in the example
below.
+You can pass variables to a test using <strong>option</strong> tag. The
options
+value can be obtained using <strong>get_opt()</strong> method. For further
+details see section <strong>Writing tests</strong> or look at code examples
+under <strong>Tests</strong> directory.</p>
+
+<p></p>
+
+<p>Example of a command sequence:</p>
+<pre><command_sequence>
+ <command type="exec" value="sleep 4"/>
+ <command type="test" machine_id="1"
value="IcmpPing" timeout="30">
+ <options>
+ <option name="addr" value="<span
style="background-color:#ffc0cb">{$recipe['machines'][2]['netconfig'][1]['addresses'][0]}</span>"
/>
+ <option name="count" value="40"/>
+ <option name="interval" value="0.2"/>
+ <option name="limit_rate" value="95"/>
+ </options>
+ </command>
+</command_sequence></pre>
+
+<p></p>
+
+<p>There are two commands in this example. </p>
+
+<p>First one would execute command sleep on the controller machine because
+attribute <strong>machine_id</strong> is not supplied (default behavior).
The
+<strong>machine_id</strong> attributes defines on which of the test machines
+command is run. It's value matches one of the machine ids defined in
+<strong><machine></strong> tag in LNST recipe.</p>
+
+<p>The second command would start <strong>IcmpPing</strong> test from
the
+LNST library on the first (<strong>id=1</strong>) test machine. </p>
+
+<p>You can also access the configuration of machines and their interfaces from
+the command sequence through a special alias <span
style="background-color:#ffc0cb"><strong>{$recipe}</strong></span>.
In the
+previous example, addr option of IcmpPing test will be set to <em>first</em>
+assigned address from netconfig of <em>first</em> device on
<em>second</em>
+machine.
+</p>
+
+<h3><em>Splitting recipes into multiple files</em></h3>
+<p>
+LNST also offers a possibility of splitting the recipe into several
+files. This can be achieved by supplying <strong>source</strong> argument
+to an arbitrary tag. The contents of that tag then will be loaded from the
+file specified in the attribute's value. For instance, the following
+machine configuration will be loaded from file <em>peanut.xml</em>:
+</p>
+<pre>
+<machine <span
style="background-color:#90ee90">source="machine_configs/peanut.xml"</span>
/>
+</pre>
+Example (<em>peanut.xml</em>):
+<pre>
+<machine id="1">
+ <netmachineconfig <span
style="background-color:#add8e6">source="example_recipes/machine_configs/config-f14peanut.xml"</span>
/>
+ <netconfig <span
style="background-color:#add8e6">source="example_recipes/net_configs/netconfig1.xml"</span>
/>
+</machine>
+</pre>
+<p>Note that parts of the included machine config are again external.</p>
+
+<hr />
+
+<h2>Writing a test</h2>
+
+<p>[TODO]</p>
+
+<p></p>
+<hr />
+
+<h2>Running in virtual environment</h2>
+
+<p></p>
+<ul>
+ <li>good for developing tests</li>
+ <li>easily reboot a panicked machine (virsh destroy <domain>;
virsh
+ start <domain></li>
+</ul>
+
+<p>Following is an example of libvirt xmls (reduced to network snippets only).
+MAC addresses marked with green color should be specified in the relevant
+machine configs. Don't forget to add dedicated control network interface that
+has to stay up during the whole testing. The configuration below expects that
+virt guests are accessible via host's network interface therefore they're set
+up as <strong>type='bridge'</strong>.</p>
+<pre><domain type='kvm'>
+ <name>rhel5.6-snap1</name>
+ ...
+ <devices>
+ ...
+ <interface type='bridge'> <!-- dedicated control
interface (therefore bridged) -->
+ <mac address='52:54:00:cc:f1:88'/>
+ <source bridge='br0'/>
+ <model type='virtio'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x03' function='0x0'/>
+ </interface>
+ <interface type='network'>
+ <mac address='<span
style="background-color:#ffffff"></span><span
style="background-color:#00ff00">52:54:00:3d:3e:9b</span>'/>
+ <source network='default'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x07' function='0x0'/>
+ </interface>
+ <interface type='network'>
+ <mac address='<span
style="background-color:#00ff00">52:54:00:44:1a:fb</span>'/>
+ <source network='default'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x08' function='0x0'/>
+ </interface>
+ ...
+ </devices>
+</domain>
+
+
+<domain type='kvm'>
+ <name>rhel6ga</name>
+ ...</pre>
+<pre> <devices>
+ ...
+ <interface type='bridge'>
+ <mac address='52:54:00:9f:be:73'/>
+ <source bridge='br0'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x07' function='0x0'/>
+ </interface>
+ <interface type='network'>
+ <mac address='<span
style="background-color:#00ff00">52:54:00:2f:cc:e1</span>'/>
+ <source network='default'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x03' function='0x0'/>
+ </interface>
+ <interface type='network'>
+ <mac address='<span
style="background-color:#00ff00">52:54:00:dd:44:f0</span>'/>
+ <source network='default'/>
+ <address type='pci' domain='0x0000' bus='0x00'
slot='0x08' function='0x0'/>
+ </interface>
+ ...
+ </devices>
+</domain></pre>
+<hr />
+
+<h2>The workflow - running LNST</h2>
+
+<h3><em>Running LNST using remote execution</em></h3>
+
+<p>On the controller machine run following command:</p>
+<pre>> ./nettestctl.py <span
style="color:#ff0000">-e</span> -c -r my_recipe.xml run</pre>
+
+<p>The <strong>-e</strong> option of the nettestctl.py command tells
the
+controller to make SSH connections to all machines specified in the xml file
+my_recipe.xml and start nettestslave.py processes on these machines. The
+nettestslave.py processes will start listening for XMLRPC connections through
+which the network interfaces will get configured. The <strong>-c</strong>
+option tells the controller to cleanup the test machines before any network
+configuration, that means removal of relevant kernel module (bonding, bridge,
+8021q, etc.).</p>
+
+<h3><em>Running LNST without remote execution</em></h3>
+
+<p>In this case you have to start nettestslave.py processes first on all
+machines that are defined in recipe by yourself. Let's assume there are
+2 machines participating in the test.</p>
+
+<p>On both of these machines you have to run following command:</p>
+<pre>$ ./nettestslave.py [-d]</pre>
+
+<p>If anything goes wrong it is a good practice to pass the debug option
+<strong>-d</strong> because you will get information about established
xmlrpc
+connection from the controller and also information about getting the network
+test interfaces ready and possible problems during the setup.</p>
+
+<p>After a successful startup you should get following line on the
output:</p>
+<pre>$ ./nettestslave.py
+03/05 12:32:20| (127.0.0.1) nettestslave:0063| INFO: Started</pre>
+
+<p>After that you need to start nettestctl.py on the controller to run the test
+in a recipe:</p>
+<pre>$ ./nettestctl.py -c -r my_recipe.xml run</pre>
+
+<h3><em>Using LNST to configure interfaces only</em></h3>
+
+<p>You can also use LNST to do just the network configuration of the test
+machines. None of the tests inside your recipe file will get executed.</p>
+
+<p>To do this pass <strong>config_only</strong> instead of
'run' argument to
+nettestctl.py script.</p>
+<pre>$ ./nettestctl.py -r my_recipe.xml <span
style="color:#ff0000"><span
style="background-color:#ffffff">config_only</span></span></pre>
+
+<p></p>
+</body>
+</html>
diff --git a/Documentation/README b/Documentation/README
new file mode 100644
index 0000000..000306a
--- /dev/null
+++ b/Documentation/README
@@ -0,0 +1,24 @@
+This directory contains useful documentation to help you understand how
+Linux Network Stack Test (LNST) works and show you some hints how to start
+using it.
+
+Description of the files in Documentation directory follows.
+
+
+LNSTIntro.html
+--------------
+
+General introduction to the LNST including all concepts required for
+understanding the framework.
+
+IMPORTANT NOTE:
+
+The document contains few interesting pictures that were stored in gzipped XML
+format and conversion to png is needed before viewing them. The pictures were
+created with Dia (program for drawing structured diagrams [1]). We have
+provided you a script named "lnst_intro_images.sh" to help you with the
+conversion. First install the dia package for your distribution and then
+just run the script and you'll be ready to read the document with all the
+fancy pictures.
+
+[1] http://live.gnome.org/Dia
diff --git a/Documentation/controller-slave-communication.dia
b/Documentation/controller-slave-communication.dia
new file mode 100644
index 0000000..b33fa28
Binary files /dev/null and b/Documentation/controller-slave-communication.dia differ
diff --git a/Documentation/lnst_intro_images.sh b/Documentation/lnst_intro_images.sh
new file mode 100755
index 0000000..0c584ae
--- /dev/null
+++ b/Documentation/lnst_intro_images.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+FILES="real-hardware-setup machineconfig-netconfig-mapping"
+
+if [ $# -gt 0 ] && [ $1 == "clean" ]; then
+ echo "Removing png files for LNSTIntro"
+ for f in $FILES; do
+ rm -f $f.png
+ done
+else
+ for f in $FILES; do
+ /usr/bin/dia -e $f.png $f.dia
+ done
+fi
+
diff --git a/Documentation/machineconfig-netconfig-mapping.dia
b/Documentation/machineconfig-netconfig-mapping.dia
new file mode 100644
index 0000000..17eeca5
Binary files /dev/null and b/Documentation/machineconfig-netconfig-mapping.dia differ
diff --git a/Documentation/real-hardware-setup.dia
b/Documentation/real-hardware-setup.dia
new file mode 100644
index 0000000..b049fa7
Binary files /dev/null and b/Documentation/real-hardware-setup.dia differ