runtool(8)

NAME
runtool - run a program in a configured process environment

SYNOPSIS
runtool [-hV] [-0 argv0 ] [<-a | -A> argfile ] [-c chdir ] [-C chroot ] [-d] [<-e | -E> envfile ] [-F fdset ] [-L [:] lockfile | -P [:] pidlock ] [-m umask ] [-R <a|c|d|f|m|o|p|r|s|t>=< num |!>[: ... ]] [- s] [-S altpath ] [-u user ] [-U user ] [-W] [-z secs ] program [ args ... ]

DESCRIPTION
runtool modifies a process environment according to its options, then runs program with any additional args.

If program does not contain a ``/'' slash character, runtool will perform a shell-like search for the executable using the PATH variable in the current environment.

OPTIONS
runtool combines the functions of several individual runtools_intro(8) into a single utility. The corresponding utility is noted in each option description, and may be referenced there for more complete information.

-0 argv0
    runargv0(8). Sets up program to run with an argv[0] of argv0.

<-a|-A> argfile
    runargs(8). Runs program with arguments specified in argfile. The -a form of the option sets up any arguments taken from argfile to preceed any arguments given by args. The -A form of the option inverts this order, so that any options taken from argfile will follow any arguments given by args.

-c chdir
    chdir(2). Changes the current working directory to chdir before running program.

-C chroot
    chroot(2). Sets up the root directory to chroot before running program.

-d  rundetach(8). Detaches from the controlling terminal to run program in the background.

<-e|-E> envfile
    runenv(8). Sets up the environmental variables in the process of program according to definitions in envfile. The -e form of the option merges any variables defined in envfile with the existing environment. The -E form of the option defines the new environment exclusively according to envfile and ignores any existing environment. As with runenv(8), the argument envfile may be either a file or a directory.

-F fdset
    Sets up file descriptors according to the specification fdset, given as a single contiguous string in the form:

        <fd> <op> <target> [: ...]

    Where:

    fd: single ascii file descriptor numeral, 0..9

    op: a single character from the set `<', `>', '+', or '='

    target:
        Depends on op as follows: If op is redirection operator '<', `>', or '+', target is an absolute pathname (must begin with `/'), or the special character `%'. Otherwise, if op is the duplication operator '=', target is a single ascii file descriptor numeral, 0..9, or the special character '!'.

    The operator character `<' is used to specify redirection of input to fd from the file argument given in target. The operator characters `>' and `+' are used to specify redirection of output from fd to the file argument given by target. The `>' redirection causes target to be overwritten, while the `+' operator appends to any target that may already exist. The special target character `%' may be used as shorthand to represent the file /dev/null for either input or output redirection.

    The operator character `=' is used to specify duplication of the file descriptor given in fd to the file descriptor given in target. The special target character `!' is used to close the file descriptor given in fd.

    Normally the fdset argument string will be enclosed in quotes to protect it from shell processing.

-L [:]lockfile
    runlock(8). Sets up a lockfile before running program. If the name of the lockfile is prefixed by the `:' character, runtool will block until a lock can be acquired. Otherwise, runtool will exit immediately if an existing lock is found on the lockfile. To write the pid of the process into lockfile, use the -P option instead.

-m umask
    umask(2). Sets up the file creation mask for program.

-P [:]pidlock
    runlock(8). Same as the description for the -L option, except that the pid for the process is written into the lock file pidlock.

-R rlims
    runlimit(8). Sets up the soft resource limits for program where rlims is given as a single contiguous string in the form:

        <rlim> = <value> [: ...]

    Where:

    rlim:
        single character in the set `a', `c', `d', `f', `m', `o', `p', `r', `s', or `t'.

    `=':
        the literal character `='.

    value:
        A positive numeric value for the resource limit, or the special character `!' used to specify ``unlimited'', that is, sets the soft limit equal to the current hard limit.

    The rlim arguments and their meanings are described in the runlimit(8) manual. Multiple rlimit specifications may be concatenated with the `:' character. Normally the rlims argument string will be enclosed in quotes to protect it from shell processing.

-s  runsession(8). Runs program in a separate session and new process group.

-S altpath
    runtool will use a PATH-like string given in altpath to search for the executable program, rather than within the PATH variable. The altpath is only used to search for program, and does not affect any PATH variable that may already be set, nor does altpath persist in the environment of program.

-u user
    runuid(8). Sets up program to run as the user-id and group-id of the system account given by user.

-U user
    runenv(8). Sets up the two variables UID and GID in the environment of program with the user-id and group-id of the system account given by user. IMPORTANT: This option does not, by itself, change the permissions with which program runs. It only sets up a couple of environmental variables that some programs may use to subsequently change their own permissions.

-z secs
    runpause(8). Sleep for secs seconds, or until interrrupted by a signal, before running program. An argument of 0 will cause runtool to pause indefinitely, or until interrupted by a signal, before running program.

runtool also provides the following standard runtools_intro(8) options:

-h  Help. Print a brief usage message to stderr and exit.

-V  Version. Print the version number to stderr and exit.

OPERATING SEQUENCE
The order in which runtool applies its operations is independent of the order in which the options are given on the command line. The sequence that runtool takes is:

•   process argfile and argv0

•   process envfile

•   process -U user

•   detach

•   setsid

•   acquire lockfile/pidlock

•   set umask

•   setup file descriptors according to fdset

•   setup resource limits

•   chdir

•   chroot

•   setuid

•   sleep

•   finally execute program

When necessary to achieve a different sequence of operations, more than one runtool invocation may be combined in an exec chain, and/or combined in an exec chain with one or more of the other purpose-specific utilities of the runtools_intro(8) suite.

EXIT STATUS
runtool exits with one of the following values:

0   program was invoked and completed successfully. In this case, the exit code is returned by the program, rather than by runtool itself.

100 runtool failed because of a usage error, such as an invalid command-line option or argument. In this case, runtool prints a brief error message and usage help to stderr on exit.

111 runtool failed due to some system or resource error. In this case, runtool prints a brief diagnostic message to stderr on exit.

1-127
    program was invoked and failed with its own non-zero exit status.

AUTHOR
Wayne Marshall, http://b0llix.net/perp/

SEE ALSO
runtools_intro(8), runargs(8), runargv0(8), runchoom(8), rundetach(8), rundeux(8), runenv(8), runfile(8), runlimit(8), runlock(8), runpause(8), runsession(8), runtrap(8), runuid(8)