persistent process supervision
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)