commit 3f3ce7907d21f7945780ddcff6a6d87117b0a413
Author: Radek Pazdera <rpazdera(a)redhat.com>
Date: Fri May 25 17:37:09 2012 +0200
Documentation: Update to reflect recent changes
* New section on 'System Configuration'
* Moved 'Defining aliases' and 'Splitting recipe into multiple files
under the 'Writing recipe' section
* New section on 'Template Functions'
* A few tiny formating changes
* Added a shade under all code segments to split them visualy
from the surrounding text
Signed-off-by: Radek Pazdera <rpazdera(a)redhat.com>
Documentation/LNSTIntro.html | 192 ++++++++++++++++++++++++++++++++++--------
1 files changed, 157 insertions(+), 35 deletions(-)
---
diff --git a/Documentation/LNSTIntro.html b/Documentation/LNSTIntro.html
index 227b560..baea586 100644
--- a/Documentation/LNSTIntro.html
+++ b/Documentation/LNSTIntro.html
@@ -6,6 +6,10 @@
<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/" />
+
+ <style>
+ pre {background-color: #eaeaea;}
+ </style>
</head>
<body>
@@ -119,6 +123,7 @@ traffic generated in tests executed on test machines.</p>
SshUtils.py
TestsCommon.py
Utils.py
+ XmlPreprocessor.py
XmlRpc.py
[./example_recipes] (inspiration for test setups – netconfigs, machineconfigs,
recipes)
@@ -148,9 +153,13 @@ traffic generated in tests executed on test machines.</p>
TestIcmp6Ping.py
TestIcmpPing.py
TestIperf.py
+ TestMulticast.py
TestNetCat.py
TestPktCounter.py
TestPktgenTx.py
+
+[./test_tools] (non-python testing tools and scripts)
+ multicast/
</pre>
<p></p>
@@ -203,7 +212,7 @@ repository on it.</p>
<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>
+ <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>
@@ -212,8 +221,8 @@ repository on it.</p>
</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"><command
type="exec" value="sleep 4"/></span>
+ <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>
@@ -303,28 +312,7 @@ defined in <strong>addresses</strong> element.</p>
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>
+<h4><strong></strong></h4>
<h3><em>Command sequences</em></h3>
@@ -388,6 +376,146 @@ assigned address from netconfig of <em>first</em> device
on <em>second</em>
machine.
</p>
+<h3><em>System Configuration</em></h3>
+<p>
+LNST provides a native way of changing system configuration of the slave machines from
within the recipe.
+This can be achieved by <strong>system_config</strong> command. There are two
versions
+of <strong>system_config</strong> command:
+</p>
+<h4>Inline version</h4>
+<pre>
+ <command <span
style="background-color:#add8e6">type="system_config"</span>
option="/proc/sys/net/ipv4/igmp_max_memberships" value="50"
machine_id="2" persistent="true" />
+</pre>
+
+<h4>Multiline version</h4>
+<pre>
+ <command <span
style="background-color:#add8e6">type="system_config"</span>
machine_id="1">
+ <options>
+ <option name="/proc/sys/net/ipv4/igmp_max_memberships"
value="10" />
+ <option name="/proc/sys/net/ipv4/igmp_max_mfs"
value="5" />
+ </options>
+ </commang>
+</pre>
+
+<p>
+ In the multiline version you can set a several options at once.
+</p>
+<p>
+ Unless <strong>persistent</strong> flag is set to
<strong>true</strong>, all modified
+ options are restored to their previous values <strong>at the end of the command
sequence</strong>.
+ The following examlpe illustrates how this works:
+<pre>
+ <command_sequence>
+ <command type="system_config" machine_id="1" <span
style="background-color:#ffc0cb">persistent="true"</span>>
+ <options>
+ <option name="/proc/sys/net/ipv4/igmp_max_memberships"
value="10" />
+ <option name="/proc/sys/net/ipv4/igmp_max_mfs"
value="5" />
+ </options>
+ </commang>
+ </command_sequence>
+ <command_sequence>
+ <command type="system_config"
option="/proc/sys/net/ipv4/igmp_max_memberships" value="50" />
+
+ execute some test here ...
+ </command_sequence> <span
style="background-color:#90ee90"><!-- At this point,
igmp_max_memberships is set back to 10 --></span>
+ <command_sequence>
+ <command type="system_config" machine_id="1" <span
style="background-color:#ffc0cb">persistent="true"</span>>
+ <options>
+ <option name="/proc/sys/net/ipv4/igmp_max_memberships"
value="20" />
+ <option name="/proc/sys/net/ipv4/igmp_max_mfs"
value="10" />
+ </options>
+ </commang>
+ </command_sequence>
+</pre>
+<p>
+ The first command sequence serves as a global system setup phase, persistent flag is
set to true,
+ so the options <strong>will not</strong> be restored when the command
sequence finishes.
+</p>
+<p>
+ In the second command sequence, one option is modified for purposes of the next test,
but it's
+ not marked persistent, so the change will be automatically reverted when the command
sequence
+ comes to end.
+</p>
+<p>
+ And the final command sequences issues a persistent command again, to make sure that
system is left
+ in a consistent state when recipe execution is over.
+</p>
+
+<hr />
+
+<h2>Writing a test</h2>
+<p>
+ This section introduces several features you can use when you decide to create your
own recipe.
+</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>Template functions</em></h3>
+<p>
+ Template functions are conceptually quite similar to aliases, but instead of a
assigned value, they
+ represent an action that will be executed when the recipe is parsed. They can be used
the same way
+ as aliases - inside of curly braces. Currently, there are three template functions
available in LNST:
+</p>
+<ul>
+ <li><strong>ip</strong>(<em>machine_id</em>,
<em>interface_id</em><em>[, address_id]</em>)
+ <p>
+ Returns IP address for a specific machine and interface.
+ Third argument is optional and can be used when there are
+ multiple IP addresses associated with a single interface.
+ </p>
+ </li>
+ <li><strong>hwaddr</strong>(<em>machine_id</em>,
<em>interface_id</em>)
+ <p>
+ Returns hardware address of specified interface.
+ </p>
+ </li>
+ <li><strong>devname</strong>(<em>machine_id</em>,
<em>interface_id</em>)
+ <p>
+ Returns device name of specified interface.
+ </p>
+ </li>
+</ul>
+<p>
+ All three above mentioned functions can be used for retrieving information from
machine
+ configs, therefore calling them is only valid within a command sequence. See the
following
+ example on how this templates can be used:
+</p>
+<pre>
+ <command type="system_config"
option="/proc/sys/net/ipv4/conf/<span
style="background-color:#ffc0cb">{devname(1,1)}</span>/forwarding"
value="1" machine_id="1" />
+ <command type="test" value="Multicast"
machine_id="1" timeout="30">
+ <options>
+ <option name="setup" value="max_groups" />
+ <option name="interface" value="<span
style="background-color:#ffc0cb">{ip(1,1)}</span>" />
+ <option name="condition" value="max_groups >
0" />
+ </options>
+ </command>
+</pre>
+<p>
+ Aliases can be passed to functions as parameters, but the preprocessor
+does not support nesting (e.g. function cannot have another function
+passed as an argument).
+</p>
+
<h3><em>Splitting recipes into multiple files</em></h3>
<p>
LNST also offers a possibility of splitting the recipe into several
@@ -408,12 +536,6 @@ Example (<em>peanut.xml</em>):
</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 />
@@ -460,8 +582,8 @@ up as <strong>type='bridge'</strong>.</p>
<domain type='kvm'>
<name>rhel6ga</name>
- ...</pre>
-<pre> <devices>
+ ...
+ <devices>
...
<interface type='bridge'>
<mac address='52:54:00:9f:be:73'/>
@@ -502,7 +624,7 @@ configuration, that means removal of relevant kernel module (bonding,
bridge,
<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
+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>
@@ -523,7 +645,7 @@ in a recipe:</p>
<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
+<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