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)