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:

closes all extraneous file descriptors
redirects unused stdin, stdout, and stderr to /dev/null
redirects the stdin of ./rc.log to the stdout of ./rc.perp (and vice versa)
redirects the stderr of ./rc.perp to stdout (with the effect that both stdout and stderr of ./rc.perp are captured by the logger)
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 terminal 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:

check/create existence/permissions of log directory
drop privilege before running tinylog(8) -- see runuid(8)

Similarly, the ./rc.perp script could perform other initializations before the perpd(8) exec:

check/create existence and symlink for /etc/perp/.control
clean out stale control directories/files in /etc/perp/.control

perpd itself may be invoked in the way that best suits the init(8) system 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, normally /etc/perp.

SIGNALS

If perpboot gets the SIGTERM signal, it performs a shutdown sequence on its child processes:

sends SIGTERM and SIGCONT to the ./rc.perp process and waits for it to terminate
closes its own copy of the input pipe to the ./rc.log process and waits for the logger to terminate
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/