persistent process supervision
perpok(8)               persistent process supervision               perpok(8)

       perpok - check a perpd(8) service

       perpok [-hV] [-b basedir ] [-u secs ] [-v] sv

       perpok  is  used to check that the service sv is actively running under
       supervision of perpd(8).

       The argument sv should be a service definition directory supervised  by
       perpd(8).   perpok  will look for sv in the directory given with the -b
       option, or as set in the PERP_BASE environmental variable,  or  in  the
       current directory if neither of the previous is given.

       perpok  returns  0  to  indicate success if the definition directory sv
       exists and is under the active supervision of perpd(8).

       The -u option may be given to specify a minimum  uptime  in  secs.   In
       this  case,  perpok  will further check that the main service itself is
       running, is not resetting, does not want down, and that its uptime  has
       been  at  least  secs seconds.  If all these conditions are met, perpok
       returns 0 to indicate success.

       If the conditions for success are not met, perpok exits non-zero.

       perpok is intended primarily  as  a  utility  for  boolean  testing  in
       scripting  environments.   See  the perpstat(8) and perpls(8) utilities
       for more detailed status reporting.

       -b basedir
              Base directory.  Sets the base directory containing the  service
              definition sv.  If not set, perpok will use the value set in the
              variable PERP_BASE, or the current directory if neither of these
              are  defined.   On  a  normal system, the base directory will be

       -h     Help.  Print a brief usage message to stderr and exit.

       -u secs
              Uptime.  Normally perpok checks only that the  sv  directory  is
              active  (exists  and  is  sticky), and that perpd(8) is actively
              supervising it.  This option extends  the  checks  performed  by
              perpok  to  test that the main service itself is running, is not
              resetting, does not want down, and that its uptime has  been  at
              least secs seconds.  Normally it is sensible to set secs to some
              small value, such as 2 or 3, which is just long enough to  check
              that the service is not cycling on restarts.

       -V     Version.  Print the version number to stderr and exit.

       -v     Verbose.  Normally perpok exits silently, as it is designed pri-
              marily for runscripts that might use it to perform simple depen-
              dency  checks prior to starting their own services.  This option
              causes perpok to print a message  reporting  either  success  or
              failure to stderr on exit.

       perpok  may  be used as a basic dependency checking utility within ser-
       vice runscripts:

              if test ${1} = "start" ; then
                if ! perpok -u3 foo ; then
                  echo "dependency foo not running"
                  exit 1
                # otherwise foo ok, continue to start service:
                exec /usr/bin/bar ...

       This example shows a runscript for a ``bar'' service that  uses  perpok
       to  require  a dependency on another service named ``foo''.  If foo has
       not been running for at least 3 seconds, the  runscript  exits  immedi-
       ately.  The perpd(8) supervisor running this service will then continue
       to try restarting it at one second intervals, until the  perpok  depen-
       dency check succeeds.

       Note that, when using perpok in a normal collection of services running
       under perpd(8), PERP_BASE will always be  properly  predefined  in  the
       runscript environment.

       perpok exits with the following values:

       0      Success.  The service sv is active and a perpd(8) supervisor has
              been found running for it.  Additionally, if the -u  option  has
              been  given, the main service itself has been found running, not
              resetting, not wanting down, and with an uptime of at least secs

       1      Failure.   The  service directory sv was found not to be active,
              or a perpd(8) supervisor was not found running for  it,  or  the
              additional  constraints  imposed for uptime checking with the -u
              option were not met.

       100    Usage error.  For unknown options, missing arguments, or  if  sv
              does not name a directory.  Prints a brief diagnostic message to
              stderr on exit.

       111    System error.  Unexpected failures during system  calls,  privi-
              lege  and/or  resource  problems, or configuration errors in the
              perpd(8) system.  Prints a brief diagnostic message to stderr on

       For  use  as  a dependency tool, perpok by itself is of course limited.
       As illustrated in the example section above, perpok may find  a  depen-
       dency  running  okay at startup, but there is no guarantee that it will
       continue to run for as long as the dependent service requires it.

       A collection of services running under perpd(8) tends to  be  reliable,
       so  that  the use of perpok for basic dependency checking at startup is
       normally adequate.  Interrelated services may also use perpok in combi-
       nation  with  runscript reset targets to implement a system of stricter
       dependency controls.

       Wayne Marshall,

       perp_intro(8),  perpboot(8),   perpctl(8),   perpd(8),   perpetrate(5),
       perphup(8), perpls(8), perpstat(8), sissylog(8), tinylog(8)

perp-2.07                        January 2013                        perpok(8)