.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH LAUNCHTOOL 1 "october 03, 2002"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
launchtool \- run a command supervising its execution.
.SH SYNOPSIS
.B launchtool
.RI [ options ]
.RI [ command ]
.br
.SH DESCRIPTION
\fBlaunchtool\fP 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.
.P
\fBlaunchtool\fP is fully configurable, both through the commandline and using
configuration files.  Configuration files can be made executable and start with
\*(lq#!/usr/bin/launchtool -C\*(rq, to create daemons using simpler commands.

.SH INVOCATION
.P
\fBlaunchtool\fP 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 \*(lq/bin/sh -c\*(rq.
.P
\fBlaunchtool\fP 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.
.P
\fBlaunchtool\fP 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.

.SH OPTIONS
\fBlaunchtool\fP follows the usual GNU command line syntax, with long options
starting with two dashes (`-').
.TP
.B \-?, \-\-help
Display a detailed help message with a summary of all options.
.TP
.B \-\-usage
Display a brief usage message.
.TP
.B \-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.
.TP
.B \-\-check
Check if another launchtool is running, then exit.
.TP
.B \-\-showcfg
Process config files and commandline, show the resulting configuration and exit.
.TP
.B \-V, \-\-version
Print version and exit.
.TP
.B \-t, \-\-tag=tag, \*(lqtag\*(rq
Tag used to identify the session
.TP
.B \-C, \-\-config=file
Read configuration data from \*(lqfile\*(rq.  Defaults to /etc/launchtool/<tag>.conf
.TP
.B \-v, \-\-verbose, \*(lqverbose\*(rq
Enable verbose output.
.TP
.B \-\-no\-verbose
Disable verbose output.
.TP
.B \-\-debug, \*(lqdebug\*(rq
Enable debug output (includes --verbose output).
.TP
.B \-\-no\-debug
Disable debug output.
.TP
.B \-c, \-\-command=cmd, \*(lqcommand\*(rq
Command to execute.
.TP
.B \-\-visible\-tag=tag, \*(lqvisible tag\*(rq
Tag to use for pidfiles and logfiles instead of \*(lqlaunchtool-<tag>\*(rq.
.TP
.B \-d, \-\-daemon, \*(lqdaemon\*(rq
Fork to background and detach from terminal, becoming a daemon.
.TP
.B \-n, \-\-no\-daemon
Don't become a daemon.
.TP
.B \-\-pidfile, \*(lqpidfile\*(rq
Create a pidfile (default when --daemon is used).
.TP
.B \-\-no\-pidfile
Don't create a pidfile (default when --daemon is not used).
.TP
.B \-\-piddir=dir, \*(lqpiddir\*(rq
Directory where pidfiles are stored (default to /var/run).
.TP
.B \-\-chroot=dir, \*(lqroot dir\*(rq
Chroot to this directory before running the command.
.TP
.B \-\-chdir=dir, \*(lqstart dir\*(rq
Chdir to this directory before running the command (default to '.' or '/' if
--daemon is present).
.TP
.B \-u, \-\-user=user, \*(lquser\*(rq
User privileges to run the command with.
.TP
.B \-g, \-\-group=group, \*(lqgroup\*(rq
Group privileges to run the command with.
.TP
.B \-\-umask=mask, \*(lqumask\*(rq
Set this umask before running the command.
.TP
.B \-L, \-\-infinite-runs, \*(lqinfinite runs\*(rq
Never give up restarting the command if it fails.
.TP
.B \-\-no\-infinite-runs
Give up restarting the command after a certain number of failures.
.TP
.B \-\-wait\-times=t1,t2,... , \*(lqwait times\*(rq
List of times (in seconds) to wait after a program failure before restarting
it.  If not specified, failed commands will not be restarted.
.TP
.B \-\-good\-running\-time=seconds, \*(lqgood running time\*(rq
Minimum running time needed to restart for the first wait time.
.TP
.B \-\-forwarded\-signals=sig1,sig2,... , \*(lqforwarded signals\*(rq
List of signals (in name or in number) to be forwarded to the command.
.TP
.B \-\-blocked\-signals=sig1,sig2,... , \*(lqblocked signals\*(rq
List of signals (in name or in number) to be blocked before running the command.
.TP
.B \-\-limit\-cpu=seconds, \*(lqcpu limit\*(rq
CPU time limit for the command (see setrlimit(2)).
.TP
.B \-\-limit\-file\-size=1024b-blocks, \*(lqfile size limit\*(rq
File size limit for the command (see setrlimit(2)).
.TP
.B \-\-limit\-data\-memory=1024b-blocks, \*(lqdata memory limit\*(rq
Data memory size limit for the command (see setrlimit(2)).
.TP
.B \-\-limit\-process\-count=count, \*(lqprocess count limit\*(rq
Process count limit for the command (see setrlimit(2)).
.TP
.B \-\-limit\-open\-files=count, \*(lqopen files limit\*(rq
Open files limit for the command (see setrlimit(2)).
.TP
.B \-\-limit\-core\-size=1024b-blocks, \*(lqcore size limit\*(rq
Core file size limit for the command (see setrlimit(2)).
.TP
.B \-\-restrict\-environment, \*(lqrestrict environment\*(rq
Restrict the child environment.
.TP
.B \-\-no-restrict\-environment
Copy all environment variables to the child environment.
.TP
.B \-\-allowed\-env\-vars=var1,var2,... , \*(lqallowed env vars\*(rq
List of environment variables to be copied to the child when the environment is
restricted.
.TP
.B \-\-log\-launchtool\-output=target, \*(lqlaunchtool output\*(rq
Target of the launchtool output (ignore, stdout, stderr, file:filename or
syslog:identity,facility,level).
.TP
.B \-\-log\-launchtool\-errors=target, \*(lqlaunchtool errors\*(rq
Target of the launchtool error messages (ignore, stdout, stderr, file:filename or
syslog:identity,facility,level).
.TP
.B \-\-log\-child\-output=target, \*(lqcommand output\*(rq
Target of the child output (ignore, stdout, stderr, file:filename or
syslog:identity,facility,level).
.TP
.B \-\-log\-child\-errors=target, \*(lqcommand errors\*(rq
Target of the child error messages (ignore, stdout, stderr, file:filename or
syslog:identity,facility,level).
.TP
.B \-\-silent\-restart\-status=value, \*(lqsilent restart status\*(rq
Return value used by the child to explicitly request a restart (feature
disabled if not specified).
.TP
.B \-\-silent\-restart\-time=seconds, \*(lqsilent restart time\*(rq
Time to wait before restarting the child after an explicit restart request.
.TP
.B \-\-stats, \*(lqstats\*(rq
Produce some statistics when the command terminates (implied by --verbose).
.TP
.B \-\-no\-stats
Do not produce statistics when the command terminates.

.SH LOGGING TARGETS
Logging targets are specified with a target name and its optional parameters,
separated by a colon (\*(lq:\*(rq).
.P
Possible target configurations are:
.TP
.B ignore
Output is just discarded.
.TP
.B stdout
Output goes to the standard output stream.
.TP
.B stderr
Output goes to the standard error stream.
.TP
.B file:filename
Output goes to the file \*(lqfilename\*(rq.
.TP
.B 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)).

.SH CONFIGURATION FILE

The configuration file is a sequence of \*(lqkey = value\*(rq lines.  Empty lines and
lines starting with '#' are ignored.
.P
The possible keys have been listed in the OPTIONS section next to the
corresponding commandline switch.
.P
Boolean (yes/no) values can take the values \*(lqyes\*(rq, \*(lqno\*(rq, \*(lqtrue\*(rq, \*(lqfalse\*(rq, \*(lq0\*(rq
and \*(lq1\*(rq.

.SH EXAMPLES
.P
.nf
# 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
.fi

.SH SEE ALSO
.BR syslog (3),
.BR setrlimit (2).

.SH AUTHOR
\fBlaunchtool\fP has been written by Enrico Zini <enrico@debian.org>.