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

FreeBSD Manual Pages


home | help
perpok(8)		persistent process supervision		     perpok(8)

       perpok -	check a	perpd(8) service

       perpok [-hV] [-b	basedir	] [-u secs ] [-v] sv

       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 ex-
       ists 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.

       -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

       -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 su-
	      pervising	it.  This option extends the checks performed by  per-
	      pok  to test that	the main service itself	is running, is not re-
	      setting, 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.

       perpok  may  be used as a basic dependency checking utility within ser-
       vice runscripts:

	      if test ${1} = "start" ; then
		if ! perpok -u3	foo ; then
		  echo "dependency foo not running"
		  exit 1
		# otherwise foo	ok, continue to	start service:
		exec /usr/bin/bar ...

       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.

       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

       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

       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.

       Wayne Marshall,

       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)


Want to link to this manual page? Use this URL:

home | help