DIETS Getting Started Guide

M. Ranganathan <mranga@nist.gov>

NIST Advanced Networking Technologies Division

Introduction

The Department of Commerce ISSI Evaluation and test system (DIETS). DIETS is a tool set for conformance and performance testing of the ISSI specification [TIA 102 BACA]. DIETS emulates all the call flows in the ISSI Conformance test document. This is a quick getting started guide. More detailed information can be found here


User Guide

Architecture Document

Intended Audience

The DIETS tool set is intended assist those who are building or evaluating ISSI systems. A familiarity with the ISSI Specification [ TIA 102 BACA ] and the ISSI Conformance test procedures is assumed.

Prerequisites

DIETS developed in the java programming language. You do not need familiarity with java to use DIETS. However, you will need to install JRE 1.6 before you run DIETS. After you have installed JRE 1.6, you can install DIETS from the self installer. If you want to run the Packet capture tool.


Install jpcap ( the java packet capture library )


Get it from http://netresearch.ics.uci.edu/kfujii/jpcap/doc/index.html

If you want to make source code modifications or to run from ant, you will need to download the source code bundle and to install ant.

Installation

DIETS is a distributed test tool. Install the DIETS tool on each machine where you intend to run it. After you have done this, under windows, you will notice an addition to your start menu. Under linux (KDE) you will notice a link on your desktop.


You will need root privileges under linux if you wish to do packet montioring.


You can launch DIETS as follows :



  1. Using the DIETS console. This gives you a convenient user interface to configure the system and run tests but takes away some flexibiity.

  2. Using ant. This is suitable for developers and it gives you more flexibility. You will need to download the source code distribution if you want to operate DIETS using ant.

The DIETS Console

You can use the DIETS console to launch all the services and tools provided by the DIETS tool set. To do this, under windows, you can click on start console item in the start menu. Before you can launch tests or run the packet monitor, you have to set the local IP address and port where you want to run the daemon. Follow the instructions in the help button of the console.

Under linux you can use the shell script


sh startup/start-diets-configmanager.sh

Set the $JAVA_HOME variable to point to where you have installed JAVA 1.6.

Launching DIETS tools and services as independent processes

Launching DIETS as independent tools gives a greater degree of control and flexibility. The following instructions are intended for developers. It presupposes familiarity with java tools.

Launching from ant

You will need the source code bundle to launch DIETS from ant. Install apache ant and make sure it is in on your classpath.


Edit log4j.properties and set all log levels to ERROR (for performance)


The tester can run in standalone mode or distribtued mode and with or without packet monitoring. Further details are given below.


The emulator takes a properties file at startup. This file contains a number of java startup properties which are explained below.

Startup Properties

The properties file has startup arguments for DIETS.


Here are the properties that can be specified in this file:

diets.configuration=filename
        specifies the name of an xml file where the global tester
        configuration is specified. This is a REQUIRED property for
        both itat and DIETS. This file instructs the front end of DIETS
        (DIETSGUI) where the back end tester daemons and packet monitors
        are waiting for commands.

itat.systemTopology = filename
        specifies the name of the system topology file where the IP
        addresses of the RFSSs ( emulated and real ) are specified. 
        Note that for emulated RFSSs you will see @node tags that link to
        the daemon addresses where you will be starting the daemons. 
        We explain this in greater detail below. This is a required
        parameter for the packet monitor (ITAT). When a test suite
        is loaded and run DIETS will use the systemtopology that is
        in that test suite directory. ITAT is not aware of the testsuite
        that is being run but it needs to know about the system layout and
        RFSS mappings to IP addresses - hence it needs the systemtopology
        parameter.  ALL the @nodes defined in the systemtopology.xml
        file must be mapped to a DIETS <conformance-tester> daemon (i.e. 
        there must be at least one <conformance-tester> with a corresponding
        refId tag. Note that a given <conformance-tester> tag can be mapped
        to several <refid> tags. That is, you can emulate multiple RFSSs
        in a given conformance tester instantiation and there must be at least
        one <conformance-tester> for each of the emulated RFSSs.

diets.testsuite = name 
        specifes the test suite name. This is the name of a subdirectory
        in the testsuites directory that contains the test suite of
        interest. Note that the testsuite is the name of a subdirectory in the 
        testsuites directory.
        
                                        
diets.stadalone ( true | false ) 
        Specifies specifies whether to start DIETS in standalone mode. In
        standalone mode, the GUI and back ends are combined.

diets.notest (true | false ) 
        Specifies whether or not to evaluate the pass fail predicate at the
        end of a test. The default value for this is "true"

dietsgui.width integer
        Specifies a preferred width for the GUI 

dietsgui.height integer
        Specifies a preferred height for the GUI

dietsgui.traceSource=(packet-monitor|conformance-tester) Tells DIETSGUI where 
        to get the trace source from. If nothing is specified here, 
        DIETSGUI will fetch traces from the conformance-tester 
        nodes specified in diets.configuration. If there are no such
        nodes, then DIETS will fetch the traces from the configured
        packet-monitors.

itatgui.width integer
        Specifies a preferred width for the ITAT GUI

itatgui.height integer
        Specifies a preferred height for the ITAT GUI.


For a quick startup to see what the tool looks like you can try

ant -Dstartup="startup/diets-standalone.properties" diets

In the following notes we assume that the startup file being used is startup/diets.properties.


You will use something like this for conformance testing.


Here's what the contents of that file looks like:


diets.testsuite=conformance
diets.configuration=testerconfig/distributed-configuration.xml
itat.systemTopology=testsuite/conformance/systemtopology.xml

The parameters prefixed with diets are relevant to the DIETS test tool and the parameters prefixed with itat are relevant to the packet monitor.

Manual Configuration of DIETS



You can edit the configuration properties using your favorite text editor or using the DIETS cosole. To start the diets console from ant :

ant startup 

If you prefer, you can edit the configuration file you have specified in the startup properties (e.g. testerconfig/distributed-configuration.xml ) and change addresses to the network addresses of machines where you plan to run the DIETS daemon and the packet monitor. Note that you need one <conformance-tester> tag for each location where you plan to start the DIETS daemon and one <packet-monitor> tag for each location where you plan to start a packet monitor. There should be only one packet monitor per subnet if you want to display sensible traces.


Edit the systemTopology for the test suite you are running (e.g. testscripts/conformance/systemtopology.xml) that is specified or implied in the startup properties file and specify actual IP addressesfor where you want to run your actual components. Change the "emulated" flag to false for these components. Note that emulated components are linked using @node to the addresses in the tester configuration file. Your Implementation Under Test (IUT) will require an actual IP address to be specified.


Next you would want to make sure that the Subscriber Units and groups that are needed by the test suite are known to your implementation under test. Make sure the groups. SUs and RFSSs specified in the global topology file for the test suite you are running (e.g. testsuites/conformance/testscripts/globaltopology.xml ) are known to your system under test. You would need to edit your configuration databases to make sure it is so.


IMPORTANT -  Each emulator node must have an identical image of the  configuration file (distributed-configuration.xml in our example). You must specify the IP addresses where your DIETS deaemons will run in that file.

IMPORTANT - Do not share the file system for the different emulator nodes as each node generates its own reference trace.

Distributed mode with packet monitoring

This is the most general case to run. The tester runs in client-server mode here. One or more nodes can be IUT and you run a packet monitor (independent process) to monitor message exchanges and gather traces.

Here the tester back end can be distributed over several machines. Each instance looks in issi-tester-configuration.xml in order to learn what emulated components are started there and starts the necessary emulated components. Similarly the packet monitor looks in that file and fires up.


1. Edit the files testerconfig/issi-tester-configuration.xml. The IP addresses specified there indicate where the back end testers and packet monitor runs.


To run it in this mode, you need to start the back end on each of the IP addresses and ports that are in the issi-tester-configuration.xml file and you need to start packet monitors on the location specified in the packet-monitor tags of the configuration file. You should have only one packet monitor per subnet

Here is how you start the back end:


Using ant, run the target


ant -Dstartup="startup/diets.properties"  daemon  

2. Here is how you start the packet monitor. Using ant, invoke

ant -Dstartup="startup/diets.properties"  packetmonitor


If you are running on multiple subnets you will need to define and start a packet monitor configuration for each subnet and start the packet monitor for that subnet as above.

3. Next you start the packet monitor front end.

ant -Dstartup="startup/diets.properties" itatgui

4. Next start the test launcher (DIETSGUI).

 ant -Dstartup="startup/diets.properties" dietsgui


IMPORTANT 
Note that the startup parameter is the same for each invocation above.


Select the test case and click on the appropriate button to generate 
traces and run the test.

Each trace gathering step runs for 30 seconds.

IMPORTANT -- You must generate the trace before running the test.

IMPORTANT -- You must generate the trace before running the test.

IMPORTANT -- Each DIETS daemon instance generates its own reference
        trace. You do not have to distribute the traces between daemons
        manually. Do not share the file system for the different
        DIETS instances or the traces will interfere.

Distributed mode without packet monitoring

You do not need packet monitoring capability for conformance testing. In this case DIETS will log packets in "applicaiton space"


However, note that this will only work when there is a SINGLE unit under test ( which is the case for conformance testing).

Standalone Mode

You can run in standalone mode if your IUT can deal with RFSSs running on ports other than 5060. In this case everything runs as a single process and this is the simplest case to run.


Here the tester runs as a single process. A template configuration file where everything starts on a single node is given in testerconfig/local-configuration.xml

        ant  -Dstartup="startup/diets-local.properties" diets

Then select a test and run it. You can gather traces using the "generate traces button"


Each trace gathering step runs for 30 seconds.


IMPORTANT -- You must generate the trace before running the test.

Packet Monitor Only

Edit issi-tester-configuration.xml and systemtopology.xml


For each IP address where the packet monitor back end is supposed to run ( one per subnet ), start it using ant :


ant -Dstartup="startup/diets.properties" packetmonitor

Start the packet monitor front end:


ant -Dstartup="startup/diets.properties" itatgui

To Build

Make sure all dependent classpaths work.

Edit ant-buildconfig.properties

Fix up according to your enviornment 

ant compile 

Credits

DIETS is a joint work of NIST and the Institute for Telecommunication Sciences (ITS). Both are agencies of the US Department of Commerce. DIETS is sponsored by funding from NIST Office of Law Enforcement Standards (OLES).

Implementation

M. Ranganathan (NIST / ANTD)  -- Architecture, Design, Development
Kameron Behnam (ITS) – Requirements gathering and interface with P25 Industry group

With contributions from (Ex team members):

Steve Quirolgico (NIST / Security Division)

Project Management

Dereck Orr ( NIST / OLES Program Manager )
Doug Montgomery ( NIST / ANTD )
D.J. Atkinson  ( NTIA / ITS ) 

Copyright

DIETS is in the public domain ( see coprights directory for full statement). You may use DIETS in any product or project without acknowledgment, but you are requested to acknowledge our contributions.