persistent process supervision
perpboot(8)             persistent process supervision             perpboot(8)

       perpboot - startup utility for perpd(8) and an associated logger

       perpboot [-hV] [-dx] [ basedir ]

       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

              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.

       -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

       -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''.

       An example ./rc.log script may look like this:

              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:

              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-

       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

       In  this  example,  the  -d  option is used to run perpboot as a daemon

       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

              The default base operating directory for perpd(8).

              Directory containing the startup scripts used by perpboot.

              Control script used by perpboot to start a logger for  perpd(8).

              Control script used by perpboot to start up perpd(8).

              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.

       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).

       The  perpboot utility is a purpose-specific modification of rundeux(8).

       Wayne Marshall,

       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),

perp-2.07                        January 2013                      perpboot(8)