Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  op-
       tion, or	as set in the PERP_BASE	environmental variable,	or in the cur-
       rent 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 en-
	      countered.

       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 de-
	      fined 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  op-
	      tion  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 op-
	      tion 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=perpls&sektion=8&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help