perpetrate(5)           persistent process supervision           perpetrate(5)



NAME
       perpetrate - conventions for runscripts

DESCRIPTION
       perpd(8)  operates  on  a  pair  of ``runscripts'' that are executed to
       start and reset a service and an optional logger.

       The runscripts recognized by perpd(8) are:

       rc.log
              Optional.  Controls the logger for the main service.

       rc.main
              Required.  Controls the main service.

       The arguments, structure, and conventions for rc.log  and  rc.main  are
       identical.  The illustrations below will usually be shown with rc.main,
       but are equally applicable to rc.log unless noted otherwise.

       perpd(8) will invoke service runscripts from within the service defini-
       tion directory.  For example, given some service definition directory

              /etc/perp/foo

       perpd(8)  will switch into foo before invoking a runscript.  This means
       that foo will be the current working  directory  within  the  runscript
       environment.

       Runscripts  are  normally implemented as executable shell scripts, pre-
       pared and installed by the system administrator.  A runscript  will  be
       executed at least twice during the life cycle of a service:

              o   to start the service

              o   after the service exits

       A  runscript  will  accordingly be structured to handle either of these
       events.

       Runscripts are invoked in the general form:

              ./rc.main target svname [ args...  ]

       The argument target will be set to one of two literal  strings,  either
       ``start''  or  ``reset'',  depending on whether perpd(8) is starting or
       resetting the service.  The svname argument will be set to the basename
       of  the  service  definition directory, such as ``foo'' for the service
       directory foo.  Any additional arguments depend on the target.

       When using a ``start'' target, perpd(8) will invoke the runscript  like
       this:

              ./rc.main start svname

       This  follows  the  general form with no additional arguments.  Given a
       ``start'' target, a runscript process should  perform  any  initializa-
       tions  the  service  requires,  and then proceed to replace itself (its
       process ID) with the desired service  running  in  the  foreground.   A
       Bourne-compatible script such as sh(1) will replace itself by using the
       exec command to start the service.  This  provides  perpd(8)  with  the
       process ID it needs for the actual running service, so that the service
       may be properly monitored and controlled.

       Normally the ``start'' target will result in a  persistent  process,  a
       long-running  program  that  starts  at system boot and continues until
       system shutdown.  A runscript called with  a  ``start''  target  should
       generally  not return or exit, unless some error is encountered in ini-
       tializing or starting the service.

       As long-running as a service may be, whenever it  does  exit,  for  any
       reason, perpd(8) will call the runscript again with a ``reset'' target.
       A ``reset'' target will invoke the runscript with additional  arguments
       in  either  one  of  two forms, depending on whether the service exited
       normally, or was terminated by a signal:

              ./rc.main reset svname exit exitcode
       or
              ./rc.main reset svname signal signum signame

       In the first case, where a service has terminated normally,  the  addi-
       tional  arguments  include