M. Ranganathan <mranga@nist.gov>
NIST Advanced Networking Technologies Division
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
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.
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.
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 :
Using the DIETS console. This gives you a convenient user interface to configure the system and run tests but takes away some flexibiity.
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.
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 as independent tools gives a greater degree of control and flexibility. The following instructions are intended for developers. It presupposes familiarity with java tools.
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.
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.
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.
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.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).
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.
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
Make sure all dependent classpaths work. Edit ant-buildconfig.properties Fix up according to your enviornment ant compile
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).
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)
Dereck Orr ( NIST / OLES Program Manager ) Doug Montgomery ( NIST / ANTD ) D.J. Atkinson ( NTIA / ITS )
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.