FreeBSD Manual Pages
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 en- vironment 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 ei- ther 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 op- tion 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 ac- tion 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 be- fore the perpd(8) exec: • check/create existence and symlink for /etc/perp/.control • 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: • 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 di- rectly 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)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | FILES | ENVIRONMENT | SIGNALS | NOTES | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=perpboot&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>