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 runtools 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 containing 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 runscripts 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 descriptors, etc. They may be used to provide carefully regulated execution environments for long-running programs, for security and resource optimization.

Most of the utilities in the runtools package are very small programs designed to do one simple thing. Because the effects of multiple runtools 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:

define the environment for ``foo'' with runenv(8)
constrain corefiles, file size, and memory usage with runlimit(8)
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 runtools 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 diagnostic 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/

NAME

DESCRIPTION

EXEC CHAINS

EXIT STATUS

AUTHOR

SEE ALSO