NAME

       launchtool - run a command supervising its execution.

SYNOPSIS

       launchtool [options] [command]

DESCRIPTION

       launchtool  is a tool that runs a user-supplied command and can supervise its execution in
       many ways, such as controlling its environment,  blocking  signals,  logging  its  output,
       changing  user  and group permissions, limiting resource usage, restarting it if it fails,
       running it continuously and turning it into a daemon.

       launchtool is fully configurable, both through the  commandline  and  using  configuration
       files.   Configuration  files can be made executable and start with “#!/usr/bin/launchtool
       -C”, to create daemons using simpler commands.

INVOCATION

       launchtool executes the  command  it  finds  in  the  commandline,  via  switches  or  the
       configuration  file.  All non-switch parameters are concatenated to the command, that will
       be executed using “/bin/sh -c”.

       launchtool default mode of execution is to run the command normally and  return  its  exit
       status.  All  features  are disabled by default and activated using commandline options or
       values in the configuration file.  Commandline options override configuration files.

       launchtool sessions are identified by a tag that is used both to mark the  command  output
       in logfiles and to identify running sessions to check if they have already been started or
       send them a signal without specifying the process PID.

OPTIONS

       launchtool follows the usual GNU command line syntax, with long options starting with  two
       dashes (`-').

       -?, --help
              Display a detailed help message with a summary of all options.

       --usage
              Display a brief usage message.

       -k, --kill[=signal]
              Kill  a  running launchtool with the specified signal (15 by default) and exit.  No
              signal name parsing is (yet) provided, so the  signal  must  be  specified  by  its
              number.

       --check
              Check if another launchtool is running, then exit.

       --showcfg
              Process config files and commandline, show the resulting configuration and exit.

       -V, --version
              Print version and exit.

       -t, --tag=tag, “tag”
              Tag used to identify the session

       -C, --config=file
              Read configuration data from “file”.  Defaults to /etc/launchtool/<tag>.conf

       -v, --verbose, “verbose”
              Enable verbose output.

       --no-verbose
              Disable verbose output.

       --debug, “debug”
              Enable debug output (includes --verbose output).

       --no-debug
              Disable debug output.

       -c, --command=cmd, “command”
              Command to execute.

       --visible-tag=tag, “visible tag”
              Tag to use for pidfiles and logfiles instead of “launchtool-<tag>”.

       -d, --daemon, “daemon”
              Fork to background and detach from terminal, becoming a daemon.

       -n, --no-daemon
              Don't become a daemon.

       --pidfile, “pidfile”
              Create a pidfile (default when --daemon is used).

       --no-pidfile
              Don't create a pidfile (default when --daemon is not used).

       --piddir=dir, “piddir”
              Directory where pidfiles are stored (default to /var/run).

       --chroot=dir, “root dir”
              Chroot to this directory before running the command.

       --chdir=dir, “start dir”
              Chdir  to  this  directory  before  running  the  command (default to '.' or '/' if
              --daemon is present).

       -u, --user=user, “user”
              User privileges to run the command with.

       -g, --group=group, “group”
              Group privileges to run the command with.

       --umask=mask, “umask”
              Set this umask before running the command.

       -L, --infinite-runs, “infinite runs”
              Never give up restarting the command if it fails.

       --no-infinite-runs
              Give up restarting the command after a certain number of failures.

       --wait-times=t1,t2,... , “wait times”
              List of times (in seconds) to wait after a program failure  before  restarting  it.
              If not specified, failed commands will not be restarted.

       --good-running-time=seconds, “good running time”
              Minimum running time needed to restart for the first wait time.

       --forwarded-signals=sig1,sig2,... , “forwarded signals”
              List of signals (in name or in number) to be forwarded to the command.

       --blocked-signals=sig1,sig2,... , “blocked signals”
              List of signals (in name or in number) to be blocked before running the command.

       --limit-cpu=seconds, “cpu limit”
              CPU time limit for the command (see setrlimit(2)).

       --limit-file-size=1024b-blocks, “file size limit”
              File size limit for the command (see setrlimit(2)).

       --limit-data-memory=1024b-blocks, “data memory limit”
              Data memory size limit for the command (see setrlimit(2)).

       --limit-process-count=count, “process count limit”
              Process count limit for the command (see setrlimit(2)).

       --limit-open-files=count, “open files limit”
              Open files limit for the command (see setrlimit(2)).

       --limit-core-size=1024b-blocks, “core size limit”
              Core file size limit for the command (see setrlimit(2)).

       --restrict-environment, “restrict environment”
              Restrict the child environment.

       --no-restrict-environment
              Copy all environment variables to the child environment.

       --allowed-env-vars=var1,var2,... , “allowed env vars”
              List  of  environment  variables  to be copied to the child when the environment is
              restricted.

       --log-launchtool-output=target, “launchtool output”
              Target  of  the  launchtool  output  (ignore,  stdout,  stderr,  file:filename   or
              syslog:identity,facility,level).

       --log-launchtool-errors=target, “launchtool errors”
              Target  of  the launchtool error messages (ignore, stdout, stderr, file:filename or
              syslog:identity,facility,level).

       --log-child-output=target, “command output”
              Target  of  the  child   output   (ignore,   stdout,   stderr,   file:filename   or
              syslog:identity,facility,level).

       --log-child-errors=target, “command errors”
              Target  of  the  child  error  messages  (ignore,  stdout, stderr, file:filename or
              syslog:identity,facility,level).

       --silent-restart-status=value, “silent restart status”
              Return value used by the child to explicitly request a restart (feature disabled if
              not specified).

       --silent-restart-time=seconds, “silent restart time”
              Time to wait before restarting the child after an explicit restart request.

       --stats, “stats”
              Produce some statistics when the command terminates (implied by --verbose).

       --no-stats
              Do not produce statistics when the command terminates.

LOGGING TARGETS

       Logging targets are specified with a target name and its optional parameters, separated by
       a colon (“:”).

       Possible target configurations are:

       ignore Output is just discarded.

       stdout Output goes to the standard output stream.

       stderr Output goes to the standard error stream.

       file:filename
              Output goes to the file “filename”.

       syslog:identity,facility,level
              Output goes to syslog, with the given identity (a string identifying  the  logger),
              facility (see syslog(3)) and level (see syslog(3)).

CONFIGURATION FILE

       The  configuration  file  is  a  sequence  of  “key = value” lines.  Empty lines and lines
       starting with '#' are ignored.

       The possible keys have been listed in  the  OPTIONS  section  next  to  the  corresponding
       commandline switch.

       Boolean (yes/no) values can take the values “yes”, “no”, “true”, “false”, “0” and “1”.

EXAMPLES

       # Running a command normally

       launchtool -t tag 'echo "Hello, world!"'

       # Run a command restarting it if it fails:

       launchtool -t tag --wait-times=1,1,1,3,3,3,10,10,10 'my_wonderful_server'

       # Run a command, with restrictions, restarting it if it fails, as a daemon

       launchtool -t myserver -d --user=myserver    --chroot=/var/myserver \
            --limit-process-count=5 --limit-open-files=10 \
            --wait-times=1,1,1,3,3,3,10,10,10 \
            --infinite-runs --stats \
            --log-launchtool-output=syslog:myserver,LOG_DAEMON,LOG_INFO \
            --log-launchtool-errors=syslog:myserver,LOG_DAEMON,LOG_ERR \
            --log-child-output=syslog:myserver,LOG_DAEMON,LOG_INFO \
            --log-child-errors=syslog:myserver,LOG_DAEMON,LOG_ERR \
            'my_experimental_server'

       # Same thing, using a configuration file

       tag = myserver
       command = my_wonderful_server
       daemon = yes
       stats = yes
       user = myserver
       root dir = /var/myserver
       process count limit = 5
       open files limit = 10
       wait times = 1,1,1,3,3,3,10,10,10
       infinite runs = yes
       launchtool output = syslog:myserver,LOG_DAEMON,LOG_INFO
       launchtool errors = syslog:myserver,LOG_DAEMON,LOG_ERR
       command output = syslog:myserver,LOG_DAEMON,LOG_INFO
       command errors = syslog:myserver,LOG_DAEMON,LOG_ERR

       # Transform a shell command in a polling daemon
       # Make the file /tmp/have_mobile exist only if my cell phone is present in the
       # IRDA discovery list

       launchtool -t celldetect -d --silent-restart-time=5 --silent-restart-status=0 --user=nobody \
            "if grep -q SIEMENS /proc/sys/net/irda/discovery; then touch /tmp/have_mobile; else rm -f /tmp/have_mobile; fi ; exit 0"

       # Ceck if the celldetect daemon is running

       launchtool -t celldetect --check

       # Kill the celldetect daemon launched with the command above

       launchtool -t celldetect -k

       # Same polling daemon, with an executable configuration file

       #!/usr/bin/launchtool -C
       tag = celldetect
       command = if grep -q SIEMENS /proc/sys/net/irda/discovery; then touch /tmp/have_mobile; else rm -f /tmp/have_mobile; fi ; exit 0
       daemon = yes
       user = nobody
       silent restart time = 5
       silent restart status = 0

       # Ceck if the celldetect daemon is running, using the executable configuration
       # file

       celldetect --check

       # Kill the celldetect daemon using the executable configuration file

       celldetect -k

SEE ALSO

       syslog(3), setrlimit(2).

AUTHOR

       launchtool has been written by Enrico Zini <enrico@debian.org>.

                                         october 03, 2002                           LAUNCHTOOL(1)