[1eb440]: doc / man1 / ltp-pan.1 Maximize Restore History

Download this file

ltp-pan.1    263 lines (234 with data), 11.4 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
.\"
.\" $Id: ltp-pan.1,v 1.1 2009/05/19 09:39:11 subrata_modak Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like. Any license provided herein, whether implied or
.\" otherwise, applies only to this software file. Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA 94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.TH PAN 1 "21 Jan 2011" "LTP" "Linux Test Project"
.SH NAME
ltp-pan \- A light-weight driver to run tests and clean up their pgrps
.SH SYNOPSIS
\fBltp-pan -n tagname [-SyAehp] [-t #s|m|h|d \fItime\fB] [-s \fIstarts\fB] [\fI-x nactive\fB] [\fI-l logfile\fB] [\fI-a active-file\fB] [\fI-f command-file\fB] [\fI-d debug-level\fB] [\fI-o output-file\fB] [\fI-O buffer_directory\fB] [\fI-r report_type\fB] [\fI-C fail-command-file\fB] [cmd]
.SH 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 \fB-y\fP option was used then it will begin
scheduling again, otherwise it will exit. It does not propagate the SIGUSR2.
.TP 1i
\fB-A\fP
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 \fI-e\fP option is implied when this option is used.
.TP 1i
\fB-a \fIactive_file\fB
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.
.TP 1i
\fB-C \fIfail-command-file\fB
The file to which all failed test commands will be saved. You can use it later with \fI-f\fP option if you want to run only the failed test cases.
.TP 1i
\fB-d \fIdebug-level\fB
See the source for settings.
.TP 1i
\fB-e\fP
Pan will exit non-zero if any of its commands exited non-zero. By default
ltp-pan ignores command exit statuses.
.TP 1i
\fB-f \fIcommand-file\fB
The file that has a collection of commands that ltp-pan will execute.
.TP 1i
\fB-h\fP
Print some simple help.
.TP 1i
\fB-l \fIlogfile\fB
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.
.TP 1i
\fB-n \fItagname\fB
The tagname by which this ltp-pan process will be known by the zoo tools. This
is a required argument.
.TP 1i
\fB-o \fIoutput_file\fB
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.
.TP 1i
\fB-O \fIbuffer_directory\fB
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.
.TP 1i
\fB-p\fP
Enables printing results in human readable format.
.TP 1i
\fB-r \fIreport_type\fB
This controls the type of output that ltp-pan will produce. Supported formats are \fIrts\fP and \fInone\fP. The default is \fIrts\fP.
.TP 1i
\fB-S\fP
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 \fI-s\fP is not
specified then the default setting for \fI-s\fP is equal to the total number
of commands.
.TP 1i
\fB-s \fIstarts\fB
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
\fI-S\fP for an exception). If this is specified and is less than the value
specified for \fI-x\fP then it is bumped up to be equal to the value of
\fI-x\fP (in other words, \fI-x\fP is always satisfied).
.TP 1i
\fB-t #s|m|h|d \fItime\fB
Indicates the length that ltp-pan should run tests. By default this is not set. If specified,
the \fI-s\fP flag is automatically set to 0 (infinite). Presumably, you want as many
tests ran during this timeframe. Duration is measured in \fIs\fPeconds, \fIm\fPinutes,
\fIh\fPours, or \fId\fPays.
.TP 1i
\fB-x \fInactive\fB
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.
.TP 1i
\fB-y\fP
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 \fI-y\fP had not been specified.
.in -1i
.SH EXAMPLES
In practice, the ZOO environment variable is generally prefered over the
\fI-a\fP 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
.br
$ ltp-pan -n ex1 -s 10 -x 3 echo hello
The next example will use this command file. Call this /tmp/cmds1.
.br
----------cut------
.br
fido ls /bin
.br
rover echo hello wally
.br
gidget sleep 2
.br
lassie ls /etc
.br
----------cut------
.br
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
.SH 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.
.br
----------cut------
.br
larry ltp-pan -n ex4b -s10 -A -l ex4_%f.log echo hello
.br
curly ltp-pan -n ex4c -S -A -f /tmp/cmds1 -l ex4_%f.log
.br
moe echo done here
.br
----------cut------
.br
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
.SH ENVIRONMENT
.TP
ZOO
If set, should name the directory where the active file should be placed.
This is ignored if \fI-a\fP is specified.
.SH FILES
.TP
active
Default name of active file if \fI-a\fP is not specified. This is prefixed
by the directory name found in the ZOO environment variable.
.TP
PAN_STOP_FILE
The creation of this file in the defined \fITMP\fP 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 (\fI-t\fP). By doing a 'touch' on this file, testing
is ended, i.e. touch /tmp/runalltests-2345/PAN_STOP_FILE
.SH "SEE ALSO"
Zoo tools - ltp-bump(1)
.SH DIAGNOSTICS
By default it exits zero unless signaled, regardless of the exit status of any
of the commands it is running. If \fI-A\fP or \fI-e\fP are specified it exits non-zero if
it is signaled or if any of the commands it is running should exit non-zero.