Demonstration 4

Purpose

Demonstration 3 brought ETCE into the EMANE domain. We focused on the structure of an ETCE Test Directory and the way that file naming and placement interacts with test execution steps.

While the directory layout of Demonstration 3 is easy to digest, the large number of files and, especially, files with only minor text differences makes such a layout impractical. Small test changes may require manual edits to many files, which is error prone. Replicate this over many tests and things quickly become unmaintainable.

Demonstration 4 repeats demo 3 but reduces the number of Test Directory files to a more manageable set by exploiting the configuration redundancy. The new files are standalone template files or are organized into entire template directories and use mako in a very similar way to what we've seen previously in the LXC Plan File. The new format requires an expanded test.xml file that indicates templates to ETCE and provides the template variable values for publishing the Test Directory to its final form.

Activity 1 - A Smaller Test Directory

Here is our Demonstration 4 Test Directory:

[etceuser@host]$ tree 04.templates
04.templates
|__ doc
|   |__ hostfile
|   |__ lxcplan.xml
|__ helper
|   |__ eelgenerator.xml
|   |__ eventservice.xml
|   |__ otestpoint-broker.xml
|   |__ scenario.eel
|__ node.tpl
|   |__ emaneshsnapshot.flag
|   |__ eventdaemon.xml
|   |__ gpsd.flag
|   |__ gpsdlocationagent.xml
|   |__ ieee80211abgmac.xml
|   |__ ieee80211abgnem.xml
|   |__ ieee80211pcr.xml
|   |__ mgen.script
|   |__ olsrd.conf
|   |__ otestpointd.xml
|   |__ otestpoint-recorder.xml
|   |__ platform.xml
|   |__ probe-emane-ieee80211abg.xml
|   |__ probe-emane-physicallayer.xml
|   |__ probe-emane-virtualtransport.xml
|   |__ transvirtual.xml
|__ steps.xml
|__ test.xml

The main change we see from the previous demo is that the ten node directories in 03.emane are replaced by one directory node.tpl. The tpl suffix indicates that node.tpl is a Template Directory. ETCE will treat every file in node.tpl as a file containing mako template strings that require values for publishing.

Let's also the list the test summary to look for changes:

[etceuser@host]$ etce-test list -v 04.templates
------------
04.templates
------------
location:
        04.templates
description:

    emane-tutorial demonstration 3 in ETCE Test Directory format
    and using templates.

overlays:
        etce_hostname
        etce_index
        etce_log_path
        eventservicedevice
        mgen_flow
        rtsthreshold

The important difference from the last demo is the expanded overlays section. In addition to the etce_log_path variable we saw there, we have five new ones: etce_hostname, etce_index, eventservicedevice, mgen_flow and rtsthreshold.

ETCE generates the overlays summary listing by searching through the Test Directory files to find mako template strings. Recall these are Python code snippets enclosed by a leading dollar sign and squiggly braces - ${some Python code here}. ETCE examines each template for variable names that will require values to convert the file into usable form - to change the mako templates into text. These are the names listed in the summary.

Where do we specify variable values? In test.xml. Here is 04.templates/test.xml:

<test>
  <name>04.templates</name>

  <description>
    emane-tutorial demonstration 3 in ETCE Test Directory format
    and using templates.
  </description>

  <overlays>
    <overlay name="eventservicedevice" value="backchan0"/>
  </overlays>

  <templates indices="1-10">
    <directory name="node">
      <overlay name="rtsthreshold" value="0"/>
      <overlaylist name="mgen_flow" values="1,2,3,4,5,6,7,8,9,10"/>
    </directory>
  </templates>
</test>

The new file adds an overlays and templates section to what we've seen previously. And we see three of our variables listed there.

The overlays and templates sections are independent - one can exist without the other. overlays strictly contains one or more overlay elements, each of which assigns a value to the named variable. Template variables defined here are visible to every file in the Test Directory. In our current example, an eventservicedevice mako template can be found in both the helper and node.tpl directories:

[etceuser@host]$ grep -R eventservicedevice 04.templates/*
04.templates/helper/eventservice.xml:  <param name="eventservicedevice" value="${eventservicedevice}"/>
04.templates/node.tpl/platform.xml:  <param name="eventservicedevice" value="${eventservicedevice}"/>
04.templates/node.tpl/eventdaemon.xml:  <param name="eventservicedevice" value="${eventservicedevice}"/>
04.templates/test.xml:    <overlay name="eventservicedevice" value="backchan0"/>

When the test is run, these will be replaced with the overlay value backchan0.

templates needs more explanation. The templates element requires a value for its indices attribute. indices is a list of one or more numbers separated by ',' or '-'. indices defines the list of values that the reserved variable etce_index will take when publishing the test. Some examples:

indices	etce_index values
1	1
1-10	1,2,3,4,5,6,7,8,9,10
1-4,7	1,2,3,4,7
1,4,7	1,4,7
1-4,5,6-10	1,2,3,4,5,6,7,8,9,10

The templates element may contain one or more file or directory children. In this case we have one directory element which points to our template directory node.tpl - the name attribute value does not include the tpl suffix, it is implied.

This is the important part - for each value of etce_index, ETCE will replicate the node.tpl directory and its contents filling in the mako fields based on the set values. Here is the nitty gritty for template directories. For each etce_index:

• ETCE builds a second variable, etce_hostname, by taking the root of the directory name (node) and appending the etce_index as a three character field. In the present case, node-001, node-002 and so on.
• In the destination directory, ETCE creates a subdirectory with the etce_hostname value. This becomes the target directory for the following steps.
• For each file in node.tpl, ETCE copies the file to the target directory replacing the mako template strings with text based on the set of variable values. The values available are the reserved variables etce_index, etce_hostname and etce_logpath, the values specified in the test.xml overlay section and the values specified as child overlay and overlaylist values to the directory element.

Here is the directory piece of test.xml once more:

    <directory name="node">
      <overlay name="rtsthreshold" value="0"/>
      <overlaylist name="mgen_flow" values="1,2,3,4,5,6,7,8,9,10"/>
    </directory>

Activity 2 - Publishing a Test

Activity 3 - Run The Demo