persistent process supervision
perpctl(8)              persistent process supervision              perpctl(8)



NAME
       perpctl - runtime control utility for perpd(8) services

SYNOPSIS
       perpctl [-hV] [-b basedir ] [-g] [-L] [-q] cmd sv [ sv ...  ]

DESCRIPTION
       perpctl  sends  the  command  specified  in cmd to the perpd(8) control
       interface for each service argument sv.

       The argument cmd may be given as a single word of any length, but  only
       the  first  letter is considered.  The available commands include (with
       mnemonic in parentheses):

       A (Activate)
              Sets the sticky bit on each sv service  directory  argument  and
              sends  SIGHUP  to  perpd(8).   The effect is to activate each sv
              service.

       X ([e]Xit)
              Unsets the sticky bit on each sv service directory argument  and
              sends  SIGHUP  to perpd(8).  The effect is to bring down each sv
              service and remove it from the set of services perpd(8) is moni-
              toring.

       d (down)
              If  the  service  is  running, send it a sequence of SIGTERM and
              SIGCONT signals to bring it down.  perpd(8) will flag  the  ser-
              vice  as  wanting  down:  if  the  service  stops it will not be
              restarted.

       u (up)
              If the service is not already running, start it.  perpd(8)  will
              flag  the service as wanting up: if the service stops it will be
              restarted.

       o (once)
              If the service is not already running, start it.  perpd(8)  will
              flag  the  service to run once: if the service stops it will not
              be restarted.

       p (pause)
              Send the service a SIGSTOP signal.  Normally this suspends  exe-
              cution  of  the  service.   perpd(8)  will  flag  the service as
              paused.

       c (continue)
              Send the service a SIGCONT signal.  Normally  a  paused  service
              will  then  resume execution.  perpd(8) will remove a pause flag
              on the service.

       a (alarm)
       h (hup)
       i (interrupt)
       k (kill)
       q (quit)
       t (term)
       w (winch)
       1 (usr1)
       2 (usr2)
              Send the service a corresponding signal: SIGALRM,  SIGHUP,  SIG-
              INT, SIGKILL, SIGQUIT, SIGTERM, SIGWINCH, SIGUSR1 or SIGUSR2.

       D (meta-Down)
       U (meta-Up)
              When  given  in  upper-case,  the  d  (down) and u (up) commands
              described above are applied to both the main and log services.

       The signal/control commands listed above are applied to an active  ser-
       vice  process  running  from  the ``start'' target of its perpetrate(5)
       runscript.   perpd(8)  will  otherwise  ignore  any  of  the   commands
       described  above  if  received while a service is resetting, except for
       the commands c (continue/SIGCONT) or k (kill/SIGKILL).

OPTIONS
       -b basedir
              Base directory.  Sets the base directory containing the sv argu-
              ments.   If  not  set,  perpctl will look for a value set in the
              environmental variable PERP_BASE.  If neither of these  is  set,
              perpctl will operate on the current working directory.

       -g     Group.   Apply  the  requested  command  to the process group id
              (pgid) of each sv service.  Normally the signal is applied  only
              to  the  single  process  id of the service.  perpd(8) runs each
              main and log process in its own separate process group;  the  -g
              option  directs  perpd(8) to signal all process running with the
              pgid of the service.  May be combined with the -L option to sig-
              nal all processes in the process group of the logging service.

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

       -L     Logger.   Apply  the  cmd argument to the active logging service
              found in sv services.  By default, the cmd argument  is  applied
              to  the  main  service.  The -L option is not allowed when using
              any of the meta-commands D, U, or X.

       -q     Quiet.  Normally after successfully applying the cmd to each sv,
              perpctl reports a brief message to stderr.  The -q option may be
              used to suppress these messages.

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

DIAGNOSTICS
       For  each sv successfully processed, perpctl prints a line to stderr in
       the form:

              sv: ok

       For each sv not successfully processed, perpctl prints a brief diagnos-
       tic to stderr and continues processing any remaining sv.

EXIT STATUS
       perpctl exits with one of the following values:

       0      Success.   The  cmd was successfully delivered to all sv service
              arguments.

       100    Usage error.  For unknown options, missing arguments,  or  other
              command-line  errors.   Prints  a  brief  diagnostic  message to
              stderr on exit.

       111    System error.  One or more errors were  encountered  while  pro-
              cessing.  These may include unexpected failures of system calls,
              privilege and/or resource problems, or configuration  errors  in
              the  base  directory.   A brief diagnostic message is printed to
              stderr for each error encountered.

AUTHOR
       Wayne Marshall, http://b0llix.net/perp/

SEE ALSO
       perp_intro(8),  perpboot(8),   perpd(8),   perpetrate(5),   perphup(8),
       perpls(8), perpok(8), perpstat(8), sissylog(8), tinylog(8)



perp-2.07                        January 2013                       perpctl(8)