Demonstration 1

Purpose

Demonstration 1 contains a simple example of an ETCE Test Directory. We'll use it to show the basic ETCE workflow and to introduce these main ideas:

• An ETCE Test defines the way a sequence of applications is executed on a set of hosts. In an EMANE context, an ETCE Test corresponds to an EMANE emulation.
• An ETCE Test is defined in an ETCE Test Directory - a directory of application configurations organized by host that includes test.xml and steps.xml ETCE files.
• The etce-test application operates on ETCE Test Directories - to list and execute the underlying Tests.
• Executing a Test results in configurations and outputs written in a structured way to the ETCE Work Directory.

To learn to use ETCE means to learn to create ETCE Test Directories, to run etce-test and to navigate the ETCE Work Directory to troubleshoot or analyze test outputs.

Activity 1 - Listing Tests

Each of the demonstration subdirectories in the ETCE Tutorial is an ETCE Test Directory. Running etce-test list on the parent tutorial directory lists the names of all of the ETCE Test Directories underneath.

[etceuser@host]$ git clone https://github.com/adjacentlink/python-etce-tutorial
Cloning into 'python-etce-tutorial'...
remote: Enumerating objects: 126, done.
remote: Counting objects: 100% (126/126), done.
remote: Compressing objects: 100% (50/50), done.
remote: Total 126 (delta 69), reused 121 (delta 64), pack-reused 0
Receiving objects: 100% (126/126), 107.93 KiB | 0 bytes/s, done.
Resolving deltas: 100% (69/69), done.
Checking connectivity... done.

[etceuser@host]$ ls -1 python-etce-tutorial
01.hello_etce
02.hello_lxc
03.emane
04.templates
config
COPYING
README.md
scripts
start_demo.sh
stop_demo.sh

[etceuser@host]$ etce-test list python-etce-tutorial
01.hello_etce
02.hello_lxc
03.emane
04.templates

Running with the -v (verbose) option and adding a test name prints the test's location and description information. overlays prints the names of template variables present in the test configuration - we'll cover this later.

[etceuser@host]$ etce-test list -v python-etce-tutorial 01.hello_etce
-------------
01.hello_etce
-------------
location:
  python-etce-tutorial/01.hello_etce
description:

    Demonstrate a minimal test with
    a single field node (localhost)
    and a single step (say.hello).

overlays:

Activity 2 - Required Files

An ETCE Test Directory requires two top level configuration files test.xml and steps.xml.

[etceuser@host]$ tree python-etce-tutorial/01.hello_etce/
python-etce-tutorial/01.hello_etce/
|__ doc
|   |__ hostfile
|__ localhost
|   |__ hello.args
|__ steps.xml
|__ test.xml

At its most basic test.xml contains name and description elements to document the test:

<test>
  <name>01.hello_etce</name>

  <description>
    Demonstrate a minimal test with
    a single field node (localhost)
    and a single step (say.hello).
  </description>
</test>

steps.xml specifies the user defined sequence of steps that make up the test. Each step element requires a name and encloses one or more run or stop elements that are associated with an application. The wrapper attribute names the ETCE Wrapper to invoke to run or stop the associated application on the test hosts. More on Wrappers later.

Demonstration 1 has one step that calls run on a wrapper named utils.hello.

<steps>
  <step name="say.hello">
    <run wrapper="utils.hello"/>
  </step>
</steps>

The 01.hello Test Directory also contains two sub-directories. doc is an ETCE reserved name for a Test Directory subdirectory to store documents that are not treated as test configuration. More precisely, ETCE does not treat files in doc as template configuration files for generating configuration files for multiple nodes.

localhost is a host subdirectory and contains configuration files for applications that run on the test participant localhost node. It contains one file, hosts.args, which, we'll see, is associated with the utils.hello wrapper named in steps.xml.

Activity 3 - Run The Demo

The top level tutorial directory contains a start-demo.sh script for running the demos. We'll use this script initially as it calls 2 or 3 different applications in the correct order. Later, we'll invoke the commands separately.

[etceuser@host]$ cd python-etce-tutorial

[etceuser@host]$ ./start_demo.sh -h
usage: start_demo.sh [-e ENVFILE] [-p SSHPORT] [-k SSHKEYFILE] SSHUSER DEMODIR

The script requires two parameters. SSHUSER names the user account to use to connect to the test's hosts via SSH to run the test applications. DEMODIR is the test directory to execute.

Demonstration 1 executes on localhost only and does not invoke any privileged applications, so use your user name (in place of etceuser).

[etceuser@host]$ ./start_demo.sh etceuser 01.hello_etce
sshuser=etceuser
demodir=01.hello_etce

Checking ssh connections on port 22 ...
host

TestCollection:
  01.hello_etce

Enter passphrase for /home/etceuser/.ssh/id_rsa:
===============
BEGIN "01.hello_etce" trial 1
Skipping host "localhost". Source and destination are the same.
Trial Start Time: 2019-05-09T16:01:20
----------
testprepper run 2019-05-09T16:01:20 data/etcedemo-01.hello_etce-20190509T160038/template data/etcedemo-01.hello_etce-20190509T160038/data
[localhost]
[localhost] Publishing 01.hello_etce to /tmp/etce/current_test
----------
step: say.hello 2019-05-09T16:01:20 data/etcedemo-01.hello_etce-20190509T160038/data
[localhost] /bin/echo "Hello ETCE!"
trial time: 0000001
----------
Collecting "01.hello_etce" results.
Skipping host "localhost". Source and destination are the same.
----------
END "01.hello_etce" trial 1
===============
Result Directories:
        /tmp/etce/data/etcedemo-01.hello_etce-20190509T160038

Activity 4 - Examine the Output