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/