runtools_intro(8) runtools runtools_intro(8)
NAME
runtools_intro - overview of the runtools utilities
DESCRIPTION
The runtools package provides a set of utilities for configuring and
constraining the process execution environment of other programs. Most
of the utilities exec into the process environment they create. That
is, they are designed to replace themselves with some other program. A
few of the utilities act as lightweight supervisors, remaining resident
themselves while monitoring some other process or processes. The run-
tools utilities include:
runargs(8)
Runs a program with arguments specified in an argfile.
runargv0(8)
Runs a program with an alias in place of the 0th argument.
runchoom(8)
Runs a program with linux ``oom killer'' abatement.
rundetach(8)
Runs a program in the background, detached from the controlling
terminal.
rundeux(8)
Runs and supervises a program with an associated logger.
runenv(8)
Runs a program with an environment defined in either an envfile
or an envdir.
runfile(8)
Runs a program described in an argvfile.
runlimit(8)
Runs a program with modified resource limits.
runlock(8)
Runs a program with an associated lockfile, optionally contain-
ing the pid of the process.
runpause(8)
Runs a program after waiting some delay or receiving a signal.
runsession(8)
Runs a program in a new session and process group.
runtool(8)
Multipurpose utility for running a program in a configured
process environment, combining many of the functions of other
runtools within a single executable.
runtrap(8)
Runs and supervises a program with an associated signal trapper.
runuid(8)
Runs a program with specific user and group permissions.
EXEC CHAINS
The runtools utilities are designed primarily for use within the run-
scripts of service supervisors, such as perpd(8) and daemontools. In
this case, they will normally be used to define and constrain such
things as resources, privileges, environmental variables, file descrip-
tors, etc. They may be used to provide carefully regulated execution
environments for long-running programs, for security and resource opti-
mization.
Most of the utilities in the runtools package are very small programs
designed to do one simple thing. Because the effects of multiple run-
tools are often required, it is customary to use whatever runtools are
needed in an ``exec chain''. An exec chain is a sequence of runtools
commands, one calling another, often in a specific order, with the
final command execing into the actual program intended. The following
perpetrate(5) snippet shows an example in sh(1) syntax:
if test ${1} = 'start' ; then
exec runenv -i ./envfile \
runlimit -c 0 -f 2000000 -m 30000000 \
runuid fooman \
/usr/sbin/foo -f
fi
In the example above, the program /usr/sbin/foo is ultimately desired
as the long-running process. An exec chain is used to:
o define the environment for ``foo'' with runenv(8)
o constrain corefiles, file size, and memory usage with runlimit(8)
o drop privilege to the user account ``fooman'' with runuid(8)
Each of the runtools programs execs into the next, until finally the
runuid(8) utility execs into /usr/sbin/foo.
EXIT STATUS
The runtools that exec themselves into another program will exit with
the following values:
0 program was invoked and completed successfully. In this case,
the exit code is returned by the program, rather than by the
runtools program itself.
100 The runtools program failed because of a usage error, such as an
invalid command-line option or argument. In this case, the run-
tools program prints a brief error message and usage help to
stderr on exit.
111 The runtools program failed due to some system or resource
error. In this case, the runtools program prints a brief diag-
nostic message to stderr on exit.
1-127 program was invoked by the runtools utility and then terminated
with its own non-zero exit status.
AUTHOR
Wayne Marshall, http://b0llix.net/perp/
SEE ALSO
runargs(8), runargv0(8), runchoom(8), rundetach(8), rundeux(8),
runenv(8), runfile(8), runlimit(8), runlock(8), runpause(8),
runsession(8), runtool(8), runtrap(8), runuid(8), perp_intro(8),
perpd(8), perpetrate(5)
runtools-2.07 January 2013 runtools_intro(8)