perpboot(8) persistent process supervision perpboot(8)
NAME
perpboot - startup utility for perpd(8) and an associated logger
SYNOPSIS
perpboot [-hV] [-dx] [ basedir ]
DESCRIPTION
perpboot is a utility for starting and monitoring a perpd(8) instance
on basedir with an associated logger. If basedir is not specified,
perpboot will use the environmental variable PERP_BASE. If PERP_BASE
is not set or empty, perpboot will use a compiled-in value for basedir,
normally /etc/perp.
Within basedir, perpboot switches into a subdirectory named .boot/. It
then forks two child processes to exec ./rc.log and ./rc.perp, with a
pipe connected between their respective stdin and stdout.
Normally ./rc.log will be an executable script that execs into a stdin
logger, such as tinylog(8) or sissylog(8). Similarly, ./rc.perp will
be an executable script that ultimately execs into perpd(8). See the
examples section below for sample scripts.
perpboot sets up its ./rc.log and ./rc.perp child processes with an
environment that:
o closes all extraneous file descriptors
o redirects unused stdin, stdout, and stderr to /dev/null
o redirects the stdin of ./rc.log to the stdout of ./rc.perp
(and vice versa)
o redirects the stderr of ./rc.perp to stdout (with the effect
that both stdout and stderr of ./rc.perp are captured by the
logger)
o sets the environmental variable PERP_BASE to the value used
for basedir
By default, perpboot itself acts as lightweight supervisor for the
./rc.log and ./rc.perp child processes. If perpboot notices that
either of these processes has died, it will try to restart them.
OPTIONS
-d Detach. Normally perpboot itself runs in the foreground. The
-d option causes perpboot to detach from the controlling termi-
nal and run as a background process. This option is useful when
starting perpboot from within a BSD-type boot script such as
rc.local.
-h Help. Print a brief usage message to stderr and exit.
-V Version. Print the version number to stderr and exit.
-x Exit. Normally perpboot stays resident as a system process that
monitors its ./rc.log and ./rc.perp child processes. The -x
option causes perpboot to start ./rc.log and then replace itself
with the ./rc.perp process. This option is used to reduce
process overhead and/or when you don't feel the need to retain
perpboot as a supervisor. As one example, this option might be
used within an inittab(5) specification configured with the
action specified as ``respawn''.
EXAMPLES
An example ./rc.log script may look like this:
#!/bin/sh
LOGDIR=/var/log/perpd
exec tinylog -k 8 -s 100000 -t ${LOGDIR}
This script execs into an instance of tinylog(8) maintaining a rotated
set of log files in /var/log/perpd with a maximum of 8 keep files, a
maximum log size of 100000 bytes, and with timestamp prepended entries.
An example ./rc.perp script:
#!/bin/sh
exec perpd -a 6 $PERP_BASE
Here the script execs into perpd(8) with autoscanning set to 6 seconds.
Note also that the environmental variable PERP_BASE is defined and
available for the ./rc.perp and ./rc.log scripts.
These simple scripts could be customized and embellished considerably.
For example, the ./rc.log script could:
o check/create existence/permissions of log directory
o drop privilege before running tinylog(8) -- see runuid(8)
Similarly, the ./rc.perp script could perform other initializations
before the perpd(8) exec:
o check/create existence and symlink for /etc/perp/.control
o clean out stale control directories/files in /etc/perp/.con-
trol
perpd itself may be invoked in the way that best suits the init(8) sys-
tem and boot scripts of the host environment. A sysv-compatible system
may use an inittab(5) file configured with this entry:
PB:23456:respawn:/usr/sbin/perpboot -x /etc/perp
This example shows the -x option, with the effect that init(8) itself
will monitor the perpd(8) process and respawn it if it dies.
A BSD-type system may use an rc.local file with this entry:
if [ -x /usr/sbin/perpboot ]; then
echo -n ' perpd'
/usr/sbin/runenv -i /etc/perp/.boot/perp.env \
/usr/sbin/perpboot -d /etc/perp
fi
In this example, the -d option is used to run perpboot as a daemon
process.
This example is further embellished to show the use of the runenv(8)
runtool to setup a clean environment for the perpd(8) process and its
children.
FILES
/etc/perp/
The default base operating directory for perpd(8).
/etc/perp/.boot/
Directory containing the startup scripts used by perpboot.
/etc/perp/.boot/rc.log
Control script used by perpboot to start a logger for perpd(8).
/etc/perp/.boot/rc.perp
Control script used by perpboot to start up perpd(8).
ENVIRONMENT
PERP_BASE
If no basedir argument is given at the command-line on startup,
perpboot checks for a value defined by PERP_BOOT. If this is
not defined or empty, perpboot uses a compiled-in default, nor-
mally /etc/perp.
SIGNALS
If perpboot gets the SIGTERM signal, it performs a shutdown sequence on
its child processes:
o sends SIGTERM and SIGCONT to the ./rc.perp process and waits
for it to terminate
o closes its own copy of the input pipe to the ./rc.log
process and waits for the logger to terminate
o exits 0
Otherwise, when perpboot runs as a lightweight supervisor (without the
-x option), it traps all the other signals it can and relays them
directly to the ./rc.perp child process with kill(2).
NOTES
The perpboot utility is a purpose-specific modification of rundeux(8).
AUTHOR
Wayne Marshall, http://b0llix.net/perp/
SEE ALSO
See the perp-setup(8) utility for an ``automagic'' configuration of a
perpboot installation.
perp_intro(8), perp-setup(8), perpctl(8), perpd(8), perpetrate(5),
perphup(8), perpls(8), perpok(8), perpstat(8), sissylog(8), tinylog(8),
rundeux(8)
perp-2.07 January 2013 perpboot(8)