From: Radek Pazdera rpazdera@redhat.com
* 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@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