perpok(8) persistent process supervision perpok(8)
NAME
perpok - check a perpd(8) service
SYNOPSIS
perpok [-hV] [-b basedir ] [-u secs ] [-v] sv
DESCRIPTION
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.
OPTIONS
-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
/etc/perp.
-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.
EXAMPLES
perpok may be used as a basic dependency checking utility within ser-
vice runscripts:
#!/bin/sh
if test ${1} = "start" ; then
if ! perpok -u3 foo ; then
echo "dependency foo not running"
exit 1
fi
# otherwise foo ok, continue to start service:
exec /usr/bin/bar ...
fi
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.
EXIT STATUS
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
seconds.
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
exit.
CAVEATS
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.
AUTHOR
Wayne Marshall, http://b0llix.net/perp/
SEE ALSO
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)