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:

    •   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/

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)