Dispatcher
Introduction
Dispatcher is a subsystem providing a proper initialization and shutdown of the TEN subsystems. It prepares the environment (creates directories for temporary files, exports environment variables, etc.), initiates building, if necessary, and initializes TEN applications according to options provided on the command line.
From user point of view Dispatcher is a BASH script that launches processes and TEN components according to specified command line options.
During its operation Dispatcher sets a few environment variables among which the most important are:
TE_BASE
Location of Test Environment sources. If the Dispatcher script is called from the source directory, this variable is exported automatically. Otherwise if building is necessary (i.e., TE is not pre-installed), TE_BASE should be exported manually.
TE_BUILD
This variable is exported automatically unless already exported. It is set to a start directory (a directory from which the Dispatcher script is called) or, if a file configure.ac is present in the start directory, to the (created if needed) build subdirectory of the start directory: [start directory]/build.
TE_INSTALL
This variable is passed as the value of the prefix option to the main configure script. Moreover, its value is used when path variables for the search of headers and libraries are constructed. It may be set manually. If it is empty, it is set to the directory where the Dispatcher script is located (if the installed Dispatcher script is used) or to ${TE_BUILD}/inst (if the Dispatcher script from the source directory is used).
TE_INSTALL_SUITE User may export this variable to specify the location of Test Suite executables (for Builder and Tester). If this variable is empty, it is set automatically to ${TE_INSTALL}/suites.
TE_TMP
This variable is set by Dispatcher to [start directory]/te_tmp by default. However, if it’s desirable to use some other directory for temporary files, it may be exported manually.
LD_LIBRARY_PATH This variable is exported by Dispatcher automatically and used for shared library search. It is set to ${TE_INSTALL}/[host platform]/lib.
PATH
Path to TEN executables is provided automatically by Dispatcher. It updates PATH variable by ${TE_INSTALL}/[host platform]/bin. Moreover, if scripts provided by Logger, Builder and storage library to Dispatcher are not installed yet, Dispatcher adds to PATH variable path to these scripts in the source directory.
TE_LOG_DIR Directory to store log files. Usually set to TE_RUN_DIR which in it’s turn is set to the current directory (PWD).
Start/stop sequence
The following sequence of events happen each time when you launch Test Environment with dispatcher.sh or run.sh script:
Dispatcher script starts with some command line options (for more information on Dispatcher options read Dispatcher Command Line Options);
Dispatcher runs te_log_init script to initialize script based logging facility. All further actions can be logged via script based interface (te_log_message script). Please note that Logger application hasn’t started yet;
Dispatcher starts Builder to prepare libraries and executables for all TE Subsystems (except Dispatcher), Test Packages, te_agents and bootable NUT image(s). te_engine_builder is passed a configuration file that describes a set of executables to be built with a set of options for building process.
Builder configuration file name specified via conf-builder option of Dispatcher.
(For information about Builder configuration file read Builder configuration file).
Please note that traces of building process are output into the console (they are not accumulated in log file);
As soon as Builder successfully built and installed all required components, Dispatcher starts launching Test Engine componentns. First component to start is Logger. Logger is passed a configuration file whose name can be specified via conf-logger Dispatcher command line option (for information about the format of Logger configuration file refer to Configuration File).
Logger starts listening for incoming log requests that can come from tests and other TEN components;
Dispatcher starts Remote Control Facility (RCF). Remote Control Facility (RCF) is passed a configuration file that describes te_agents to be started (for information about the format of Remote Control Facility (RCF) configuration file refer to RCF Configuration File).
As a part of initialization Remote Control Facility (RCF) establishes communication with te_agents using Test Protocol;
As soon as Remote Control Facility (RCF) has initialized, Logger starts a thread that is responsible for polling te_agents Test Agents in order to gather log messages accumulated on Test Agent side. Polling interval is configured via Logger configuration file;
Dispatcher starts Configurator. Configurator is passed a configuration file that describes configuration objects to register as well as object instances to add (for information about the format of Configurator configuration file refer to Configurator Configuration File). On start-up Configurator retrives configuration information from te_agents and initializes local trees of objects and instances;
Dispatcher starts Tester. Tester processes configuration file and if necessary asks Builder to build test suites (test executables). Then Tester processes test package description files and runs tests in corresponding order and with specified set of parameter values. (For information about Tester configuration file format refer to Configuration File section).
Before running tests, Tester asks Configurator to make a backup of configuration tree. When all tests are finished Tester restores the initial configuration from initial backup. To prevent tests from interfering, a backup is created and optionally restored before each test as well.
When Tester returns (all tests finished), Dispatcher stops Configurator;
Flushing of the log from all Test Agents is performed;
Dispatcher stops Remote Control Facility (RCF). During its shutdown, Remote Control Facility (RCF) performs a shutdown of all te_agents;
Dispatcher stops Logger. Dispatcher calls Report Generator tool to convert the log from a raw format to the text and/or HTML format;
Dispatcher script finishes its work.
Publishing logs to Bublik web application
Testing logs may be published to Bublik web application using Dispatcher option –publish or a standalone script scripts/publish_logs. A path to test suite and site specific logs publishing script should be passed via –publish option of Dispatcher or –script option of scripts/publish_logs. TE will then create a tar archive containing testing metadata (meta_data.json) and raw log bundle (raw_log_bundle.tpxz), and pass it as the only argument to the script that you provide.
It is assumed that your script will then copy the tar archive to log storage server, extract it there in a proper place and request Bublik web application to import logs from the corresponding URL.
Dispatcher Command Line Options
The Dispatcher script accepts a lot of command-line options. Some of them are its own options, and the rest are passed through to other TE subsystems. Here is the complete list of the dispatcher.sh script options as well as their descriptions obtained by calling it with help option:
Usage: dispatcher.sh [<generic options>="">] [[<test options>=""> tests ]...
Generic options:
-q Suppress part of output messages
force Never prompt
daemon[=<PID>] Run/use TE engine daemons
shutdown[=<PID>] Shut down TE engine daemons on exit
conf-dir=<directory> specify configuration file directory,
overrides previous value and conf-dirs
(${TE_BASE}/conf or . by default)
conf-dirs=<directories> specify list of configuration file directories
separated by colon (top priority first,
may be specified many times, appends to
conf-dir)
In configuration files options below <filename> is full name of the
configuration file or name of the file in the configuration directory.
conf-builder=<filename> te_engine_build config file ( by default)
conf-cs=<filename> :ref:`Configurator <doxid-group__te__engine__conf>` config file ( by default)
conf-logger=<filename> :ref:`Logger <doxid-group__te__engine__logger>` config file ( by default)
conf-rcf=<filename> :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>` config file ( by default)
conf-rgt=<filename> RGT config file (rgt.conf by default)
conf-tester=<filename> :ref:`Tester <doxid-group__te__engine__tester>` config file ( by default)
conf-nut=<filename> NUT config file ( by default)
script=<filename> Name of the file with shell script to be
included as source
live-log Run RGT in live mode
log-dir=<dirname> Directory where to save tmp_raw_log file
(used if TE_LOG_RAW is not set directly)
log-html=<dirname> Name of the directory with structured HTML logs
to be generated (do not generate by default)
log-plain-html=<filename> Name of the file with plain HTML logs
to be generated (do not generate by default)
log-txt=<filename> Name of the file with logs in text format
to be generated (log.txt by default)
log-txt-detailed-packets Include detailed packet dumps in text log.
log-junit=<filename> Name of the file with logs in JUnit format
to be generated.
no-builder Do not build TE and TA
no-nuts-build Do not build NUTs
no-tester Do not run :ref:`Tester <doxid-group__te__engine__tester>`
no-cs Do not run :ref:`Configurator <doxid-group__te__engine__conf>`
no-rcf Do not run :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>`
no-run Do not run :ref:`Logger <doxid-group__te__engine__logger>`, :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>`, :ref:`Configurator <doxid-group__te__engine__conf>` and :ref:`Tester <doxid-group__te__engine__tester>`
opts=<filename> Get additional command-line options from file
cs-print-trees Print configurator trees.
cs-log-diff Log backup diff unconditionally.
build-only Build TE, do not run :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>` and :ref:`Configurator <doxid-group__te__engine__conf>`,
build but do not run Test Suites
build=path Build package specified in the path.
build-log=path Build package with log level 0xFFFF.
build-nolog=path Build package with undefined log level.
build-cs Build :ref:`Configurator <doxid-group__te__engine__conf>`.
build-logger Build :ref:`Logger <doxid-group__te__engine__logger>`.
build-rcf Build :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>`.
build-tester Build :ref:`Tester <doxid-group__te__engine__tester>`.
build-lib-xxx Build host library xxx.
build-log-xxx Build package with log level 0xFFFF.
build-nolog-xxx Build package with undefined log level.
build-parallel[=num] Enable parallel build using num threads.
build-ta-none Don't build Test Agents.
build-ta-missing Build only new Test Agents.
build-ta-all Force build all Test Agents.
build-ta-for=<hostname> Rebuild agent (and all the libraries) used for <hostname>.
build-ta-rm-lock Remove lock from previous agent build even
if it is still in progress.
profile-build=<logfile> Gather timings for the build process into <logfile>
no-rcf-cc-simple Do not execute simple :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>` consistency checks.
tester-suite=<name>:<path> Specify path to the Test Suite.
tester-no-run Don't run any tests.
tester-no-build Don't build any Test Suites.
tester-no-trc Don't use Testing Results Comparator.
tester-no-cs Don't interact with :ref:`Configurator <doxid-group__te__engine__conf>`.
tester-no-cfg-track Don't track configuration changes.
tester-no-logues Disable prologues and epilogues globally.
tester-only-req-logues Run only prologues/epilogues under which
at least one test will be run according to
requirements passed in command line. This
may not work well if your prologues can add
requirements on their own in /local:/reqs:.
tester-req=<reqs-expr> Requirements to be tested (logical expression).
tester-no-reqs Ignore requirements, run all possible
iterations.
tester-quietskip Quietly skip tests which do not meet specified
requirements (default).
tester-verbskip Force :ref:`Tester <doxid-group__te__engine__tester>` to log skipped iterations.
tester-cmd-monitor Specify command monitor to be run for all
tests in form [ta,]time_to_wait:command
The following :ref:`Tester <doxid-group__te__engine__tester>` options get test path as a value:
<testpath> := / | <path-item> | <testpath>/<path-item>
<path-item> := <test-name>[:<args>][%<iter-select>][*<repeat>]
<args> := <arg>[,<args>]
<arg> := <param-name>=<values> | <param-name>~=<values>
<values> := <value> | { <values-list> }
<values-list> := <value>[,<values-list>]
<iter-select> := <iter-number>[+<step>] | <hash>
For example,
tester-run=mysuite/mypkg/mytest:p1={a1,a2}
requests to run all iterations of the test 'mytest' when its parameter
'p1' is equal to 'a1' or 'a2';
tester-run=mysuite/mypkg/mytest%3*10
requests to run 10 times third iteration of the same test.
tester-fake=<testpath> Don't run any test scripts, just emulate test
scenario.
tester-run=<testpath> Run test under the path.
tester-run-from=<testpath> Run tests starting from the test path.
tester-run-to=<testpath> Run tests up to the test path.
tester-exclude=<testpath> Exclude specified tests from campaign.
tester-vg=<testpath> Run test scripts under specified path using
valgrind.
tester-gdb=<testpath> Run test scripts under specified path using
gdb.
tester-random-seed=<number> Random seed to initialize pseudo-random number
generator
tester-verbose Increase verbosity of the :ref:`Tester <doxid-group__te__engine__tester>` (the first
level is set by default).
tester-quiet Decrease verbosity of the :ref:`Tester <doxid-group__te__engine__tester>`.
tester-out-tin Output Test Identification Numbers to terminal
tester-out-expected If result is expected (in accordance with TRC),
output the result together with OK
tester-interactive Interactive ask user for tests to run.
test-sigusr2-verdict Handle the SIGUSR2 signal in test and stop it by TEST_VERDICT.
By default the SIGUSR2 handled like SIGINT, it stops testing.
test-wof Wait before jump to cleanup on test failure. Useful to
take a look at what's configured etc. Requires some
nodes in the /local:/test: tree.
test-woc Wait before jump to cleanup regardless of test result.
logger-foreground Run Logger in the foreground (useful for Logger debugging).
logger-no-rcf Run Logger without interaction with RCF, i.e. without polling any
Test Agents (useful for Logger debugging).
logger-check Check that log messages received from other TE components are
properly formatted before storing them in the raw log file.
logger-listener=<confstr> Enable streaming live results to the specified listener.
Config string has the following format: <name>[:<runid>].
logger-meta-file=<path> Send meta information to listeners. This option may only be
specified once.
trc-log=<filename> Generate bzip2-ed TRC log
trc-db=<filename> TRC database to be used
trc-tag=<TAG> Tag to get specific expected results
trc-key2html=<filename> File with key substitutions when output to HTML
report
trc-ignore-log-tags Ignore tags from log
trc-html=<filename> Name of the file for HTML report
trc-brief-html=<filename> Name of the file for brief HTML report
trc-html-header=<filename> Name of the file with header for all HTML
reports.
trc-txt=<filename> Name of the file for text report
(by default, it is generated to stdout)
trc-quiet Do not output total statistics to stdout
trc-comparison=<method> Specify the method to match parameter values in TRC
exact (the default)
* casefold
normalised (XML-style space normalization)
tokens (the values are split into tokens which are
either sequences of XML name characters or single characters;
the matching is done on these lists; in additional, numeric
tokens are compared as numbers (so e.g. 10 and 0xa render equal)
trc-update Update TRC database
trc-init Initialize TRC database (be careful,
TRC database file will be rewritten)
vg-engine Run :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>`, :ref:`Configurator <doxid-group__te__engine__conf>`, :ref:`Logger <doxid-group__te__engine__logger>` and :ref:`Tester <doxid-group__te__engine__tester>` under
valgrind (without by default)
vg-cs Run :ref:`Configurator <doxid-group__te__engine__conf>` under valgrind
vg-logger Run :ref:`Logger <doxid-group__te__engine__logger>` under valgrind (without by default)
vg-rcf Run :ref:`Remote Control Facility (RCF) <doxid-group__te__engine__rcf>` under valgrind (without by default)
(without by default)
vg-tester Run :ref:`Tester <doxid-group__te__engine__tester>` under valgrind (without by default)
gdb-tester Run :ref:`Tester <doxid-group__te__engine__tester>` under gdb.
tce Do TCE processing for all TCE-enabled components
tce= Do TCE processing for specific components (comma-separated) or 'all'
no-meta Do not generate testing metadata.
publish=<script> Use a given script to publish testing logs
(metadata must be enabled to do this).
sniff-not-feed-conf Do not feed the sniffer configuration file
to :ref:`Configurator <doxid-group__te__engine__conf>`.
sniff=<TA/iface> Run sniffer on *iface* of the *TA*.
sniff-filter=<filter> Add for the sniffer filter(tcpdump-like
syntax). See 'man 7 pcap-filter'.
sniff-name=<name> Add for the sniffer a human-readable name.
sniff-snaplen=<val> Add for the sniffer restriction on maximum
number of bytes to capture for one packet.
By default: .
sniff-space=<val> Add for the sniffer restriction on maximum
overall size of temporary files, Mb.
By default: 64 Mb.
sniff-fsize=<val> Add for the sniffer restriction on maximum
size of the one temporary file, Mb.
By default: 16 Mb.
sniff-rotation=<x> Add for the sniffer restriction on number of
temporary files. This option excluded by
the sniff-ta-log-ofill-drop option.
By default: 4.
sniff-ofill-drop Change overfill handle method of temporary
files for the sniffer to tail drop.
By default overfill handle method is rotation.
sniff-log-dir=<path> Path to the :ref:`Test Engine <doxid-group__te__engine>` side capture files.
By default used: /home/aizrailev/te/caps.
sniff-log-name=<pattern> :ref:`Test Engine <doxid-group__te__engine>` side log file naming pattern, the
following format specifies are supported:
%a : agent name
%u : user name
%i : iface name
%s : sniffer name
%n : sniffer session sequence number
By default '%a_%i_%s_%n' is used. The pcap
extension will be added automatically.
sniff-log-osize=<val> Maximum :ref:`Test Engine <doxid-group__te__engine>` side logs cumulative size for all
sniffers, Mb.
By default: unlimited.
sniff-log-space=<val> Maximum :ref:`Test Engine <doxid-group__te__engine>` side logs cumulative size for one
sniffer, Mb. By default: 256 Mb.
sniff-log-fsize=<val> Maximum :ref:`Test Engine <doxid-group__te__engine>` side capture file size for each
sniffer in Mb.
By default: 64 Mb.
sniff-log-ofill-drop Change overfill handle method to tail drop.
By default overfill handle method is rotation.
sniff-log-period=<val> Period of taken logs from agents, milliseconds.
By default: 200 msec.
sniff-log-conv-disable Option to disable capture logs conversion
and merge with the main log.
Environment variables defining where raw log is stored:
.. code-block:: c
TE_LOG_RAW Where to save raw log file, by default tmp_raw_log
in directory specified by --log-dir (if provided)
or in the current directory.
TE_LOG_BUNDLE Where to save raw log bundle (tarball compressed
with pixz). If it is not set, raw log bundle is not
created.
The script exits with a status of zero if everything does smoothly and
all tests, if any tests are run, give expected results. A status of two
is returned, if some tests are run and give unexpected results.
A status of one indicates start up or any internal failure.