perpls(8) persistent process supervision perpls(8)
NAME
perpls - persistent process service lister
SYNOPSIS
perpls [-hV] [-b basedir ] [-cGgrt] [ sv ... ]
DESCRIPTION
perpls is used to list the current status of each sv argument monitored
by an active perpd(8) supervisor.
perpls looks for sv in the directory basedir if 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. If no sv is
given, perpls reports on all the subdirectories found in the base
directory not beginning with `.'.
For each service sv, perpls prints a single line reporting on the sta-
tus of the service. The report for each service is given in a format
similar to the following:
# perpls foo
[+ +++ +++] foo uptime: 5s/5s pids: 278/269
The line begins with a ``panel'' for the service, followed by the name
of the service sv, followed by the current uptimes for the main/log
processes, followed by the pids for the main/log processes.
The ``panel'' is a compact representation of the service status. It is
displayed as a sequence of nine-characters within square brackets: a
single character for the status of the perpd(8) supervisor itself, fol-
lowed by a pair of triple-character sequences representing the main and
log processes under its supervision.
The following characters are used in the panel:
+ Ok. The process is up and running. In the first position,
shows that the perpd(8) supervisor itself is up and running. If
the panel is all `+', it means all systems are go.
. Down. The process is currently down.
# perpctl down foo && perpls foo
[+ ... +++] foo uptime: -s/90s pids -/269
! Attention. Appears in the first position of a triplet sequence
when the service is currently in a state it doesn't want to be
in. There is a problem somewhere, often indicating that a run-
script is not executable. For example, a service currently down
but ``wants'' to be up:
# perpctl down foo
# chmod -x foo/rc.main
# perpctl up foo && perpls foo
[+ !.. +++] foo uptime: -s/90s pids 299/269
o Once. Appears in the second position of a triplet sequence when
the process is up and running, but flagged to run only once:
# perpctl once foo && perpls foo
[+ +o+ +++] foo uptime: 90s/90s pids 278/269
p Paused. Appears in the third position of a triplet sequence
when the process is currently paused:
# perpctl pause foo && perpls foo
[+ ++p +++] foo uptime: 90s/90s pids 278/269
r Resetting. Appears in the third position of a triplet sequence
when the service is currently resetting:
# perpctl pause foo && perpls foo
[+ ++r +++] foo uptime: 1s/90s pids 299/269
- Not active/available. In the first position of the panel, indi-
cates the service definition sv is not active. The rest of the
panel will be filled by `-' characters, and no reporting will
appear for uptimes and pids.
# chmod -t foo && perpls foo
[- --- ---] foo
E Error. Appears only in the first position for overall status.
Displayed when a problem was encountered in finding the sv argu-
ment or its perpd(8) supervisor. The rest of the panel will be
filled by `-' characters, and followed by a diagnostic message
describing the error:
# perpls foo
[E --- ---] foo error: failure stat() on service directory (ENOENT)
Colorized Listings
On terminals with color support, perpls may display a ``colorized''
listing when given the -G option on the command line, or if PERPLS_COL-
ORS is defined with a capability string in the environment. The col-
orization is applied to the sv name in the report according to the sta-
tus found for the service. Colorization is based on ANSI (ISO 6429)
color sequences, selected from a capability table that defines the fol-
lowing entries (default values shown in parentheses):
df Default (df=00). Applied when a capability is otherwise unde-
fined.
na Not active (na=00). Applied when a service is not activated.
an Active-normal (an=01). Applied when the main service is active
and running normally.
ar Active-resetting (ar=01;33). Applied when the main service is
resetting.
ap Active-paused (ap=01;33). Applied when the main service is
paused.
ad Active-down (ad=01;34). Applied when the main service is down.
wu Want-up (wu=01;33). Applied when the main service is down but
wants up.
wd Want-down (wd=01;33). Applied when the main service is up but
wants down.
er Error (er=01;31). Applied when an error encountered.
ex Exception (ex=01;31). Applied when an exceptional condition
encountered.
In a default installation, the capability table will be predefined with
the following string:
"df=00:na=00:an=01:ar=01;33:ap=01;33:\
ad=01;34:wu=01;33:wd=01;33:er=01;31:ex=01;31"
OPTIONS
-b basedir
Base directory. Look for sv in basedir.
-c Current directory. Look for sv in the current directory, even
if PERP_BASE is defined in the environment.
-g No color. Do not colorize listing, even if PERPLS_COLORS is
defined in the environment.
-G Colorize. Display a colorized listing. Use the capability ta-
ble given by PERPLS_COLORS if defined in the environment, or use
a built-in capability table if PERPLS_COLORS is not defined.
-h Help. Print a brief usage message to stderr and exit.
-K Capability. Print the current capability table for colorized
listings and exit. The environment variable PERPLS_COLORS must
be defined. Otherwise this option must be combined with the -G
option to display the built-in capability table.
-r Reverse sort. Display the listing in reverse order. Normally
the listing appears in the order of sv given on the command
line, or in alphabetical order if no sv are given. The -r
option lists in the reverse of this order. This option may be
combined with the -t option.
-t Uptime. Display the listing ordered by uptime of the main ser-
vice, shortest uptimes first. May be combined with the -r
option to display longest uptimes first.
-V Version. Print the version number to stderr and exit.
AUTHOR
Wayne Marshall, http://b0llix.net/perp/
SEE ALSO
perp_intro(8), perpboot(8), perpctl(8), perpd(8), perpetrate(5),
perphup(8), perpok(8), perpstat(8), sissylog(8), tinylog(8)
perp-2.07 January 2013 perpls(8)