NAME
ltp-pan - A light-weight driver to run tests and clean up their pgrps
SYNOPSIS
ltp-pan -n tagname [-SyAehp] [-t #s|m|h|d time] [-s starts] [-x
nactive] [-l logfile] [-a active-file] [-f command-file] [-d debug-
level] [-o output-file] [-O buffer_directory] [-r report_type] [-C
fail-command-file] [cmd]
DESCRIPTION
Pan will run a command, as specified on the commandline, or collection
of commands from a command-file. By default ltp-pan runs one command,
choosing it at random from the whole set of commands available to it.
The ltp-pan’s name in the active file is specified by the tagname.
When a command terminates ltp-pan will kill any orphans that may have
been left behind in its pgrp. If ltp-pan is signaled it will kill any
active commands and, again, clean up any orphans.
Pan uses the signal ratchet found in other zoo tools. The first time
ltp-pan is signaled it sends a SIGTERM to the active pgrps; the second
time it sends SIGHUP; the third time a SIGINT; after that it always
sends SIGKILL.
Pan will not terminate until all the active commands and everything in
their pgrps is dead. It will loop around at 5 second intervals,
triggering its own signal ratchet, until it succeeds in killing the
pgrps.
When the ltp-pan starts up it places its own tagname and commandline in
the active file and begins scheduling commands. After a command is
started ltp-pan puts an entry for it into the active file with its
indicated tagname. If the command was specified on the command line,
rather than in the command-file, then its tagname will be "cmdln".
When a process terminates ltp-pan frees the active file entry. If a
command terminates and leaves an orphaned pgrp then ltp-pan will put an
entry into the active file called "panorphan" which will be removed
only when the orphaned pgrp is cleaned up. Before ltp-pan exits it
will ensure that all orphaned pgrps are dead (see above) and then it
will remove its own tagname from the active file.
The command-file is a file containing tag/command pairs. Each line in
the file begins with a tag identifying the command, followed by white
space, and then the command and its arguments. A line beginning with
the # character is a comment. Pan recognizes the token "%f" in a
command’s arguments and replaces it with a unique identifier--add this
to filename arguments to prevent two instances of the command from
interfering with each other.
When ltp-pan receives a SIGUSR2 it stops scheduling new tests and waits
for the active tests to terminate. If the -y option was used then it
will begin scheduling again, otherwise it will exit. It does not
propagate the SIGUSR2.
-A The all-stop flag. If any command exits non-zero ltp-pan
will shutdown its scheduler and signal any active pgrps. The
ltp-pan will exit non-zero after everything is shut down. By
default ltp-pan ignores command exit statuses. The -e option
is implied when this option is used.
-a active_file
A file containing the tagnames, pids, and commands being run.
If this is not specified then the ZOO environment variable
will be read for the name of a directory where the active
file will be placed, and in this case the active file’s name
will be "active". A single active file may be shared by any
number of Zoo tools.
-C fail-command-file
The file to which all failed test commands will be saved.
You can use it later with -f option if you want to run only
the failed test cases.
-d debug-level
See the source for settings.
-e Pan will exit non-zero if any of its commands exited non-
zero. By default ltp-pan ignores command exit statuses.
-f command-file
The file that has a collection of commands that ltp-pan will
execute.
-h Print some simple help.
-l logfile
Name of a log file to be used to store exit information for
each of the commands (tags) that are run. This log file may
not be shared with other Zoo tools or other ltp-pan
processes.
-n tagname
The tagname by which this ltp-pan process will be known by
the zoo tools. This is a required argument.
-o output_file
The file to which all test output will be saved. Normally
all test output is sent to standard output. This includes
each test’s standard output and standard error.
-O buffer_directory
A directory where ltp-pan can place temporary files to
capture test output. This will prevent output from several
tests mixing together in the output file.
-p Enables printing results in human readable format.
-r report_type
This controls the type of output that ltp-pan will produce.
Supported formats are rts and none. The default is rts.
-S Causes ltp-pan to run commands (tags) sequentially, as they
are listed in the command-file. By default it chooses tags
randomly. If a command is specified on the commandline and a
command-file is also specified, then the commandline tag will
be the last command. If this is specified and -s is not
specified then the default setting for -s is equal to the
total number of commands.
-s starts Indicates the number of commands (tags) that should be run
before terminating. Set this to zero to run forever. By
default this is set to 1 (but see -S for an exception). If
this is specified and is less than the value specified for -x
then it is bumped up to be equal to the value of -x (in other
words, -x is always satisfied).
-t #s|m|h|d time
Indicates the length that ltp-pan should run tests. By
default this is not set. If specified, the -s flag is
automatically set to 0 (infinite). Presumably, you want as
many tests ran during this timeframe. Duration is measured in
seconds, minutes, hPours,OR dPays.
-x nactive
Indicates the number of commands (tags) that should be kept
active at any one time. If this is greater than 1 then it is
possible to have multiple instances of the same tag active at
once. By default this is 1.
-y Causes the ltp-pan scheduler to go idle if a signal is
received or if a command exits non-zero. All active commands
and their pgrps will be killed. After everything is dead the
scheduler will restart again where it left off. If the
signal is SIGUSR1 then ltp-pan will behave as if -y had not
been specified.
EXAMPLES
In practice, the ZOO environment variable is generally prefered over
the -a option. All examples assume this is being set.
The following creates a ltp-pan named "ex1" with an active file in
/tmp/active. It runs the command "echo hello", keeping 3 copies
running at all times, running 10 copies before terminating.
$ export ZOO=/tmp
$ ltp-pan -n ex1 -s 10 -x 3 echo hello
The next example will use this command file. Call this /tmp/cmds1.
----------cut------
fido ls /bin
rover echo hello wally
gidget sleep 2
lassie ls /etc
----------cut------
Using the above command file, /tmp/cmds1, run one command at a time,
sequentially, running each command only once. If one command should
fail then terminate immediately. An exit log is kept for all the
commands.
$ ltp-pan -n ex3 -S -A -f /tmp/cmds1 -l ex3.log
Here is just a simple stress case. In this case the test will run for
24 hours, printing the output as a human readable format, with the test
output at /tmp/output-file and all failed test commands (if you have
any) at /tmp/fail-command-file.
$ ltp-pan -n stress -e -p -q -S -t 24h -a stress -l logfile -f command-
file -o /tmp/output-file -C /tmp/fail-command-file
LAYERING
Pan is often used in layers. This section extends the above examples
to show how this is done.
The next example will use this command file. Call this /tmp/cmds2.
Note that the embedded ltp-pans inside this file have exit logs, and
that %f is used to give each ltp-pan a unique log file name.
----------cut------
larry ltp-pan -n ex4b -s10 -A -l ex4_%f.log echo hello
curly ltp-pan -n ex4c -S -A -f /tmp/cmds1 -l ex4_%f.log
moe echo done here
----------cut------
The following will run commands from the command file, keeping two at a
time running, choosing them sequentially, and terminating if any of
them exits non-zero.
$ ltp-pan -n ex4 -x2 -A -S -f /tmp/cmds2
Now run the commands in /tmp/cmds2, but this time we want to recover if
one of the commands should exit non-zero. In this example it is
possible for the "larry" or "curly" tags to exit non-zero. When this
happens the ltp-pan will kill all active tags, making sure both larry
and curly are dead, and then will continue scheduling--ensuring that
our "done here" message comes out no matter what.
$ ltp-pan -n ex5 -x2 -A -S -y -f /tmp/cmds2
ENVIRONMENT
ZOO If set, should name the directory where the active file should
be placed. This is ignored if -a is specified.
FILES
active Default name of active file if -a is not specified. This is
prefixed by the directory name found in the ZOO environment
variable.
PAN_STOP_FILE
The creation of this file in the defined TMP directory will
cause ltp-pan to execute one more loop and stop. This is useful
when testing needs to be stopped before its scheduled stop time
(-t). By doing a ’touch’ on this file, testing is ended, i.e.
touch /tmp/runalltests-2345/PAN_STOP_FILE
SEE ALSO
Zoo tools - ltp-bump(1)
DIAGNOSTICS
By default it exits zero unless signaled, regardless of the exit status
of any of the commands it is running. If -A or -e are specified it
exits non-zero if it is signaled or if any of the commands it is
running should exit non-zero.