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

FreeBSD Manual Pages


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

       perpboot	- startup utility for perpd(8) and an associated logger

       perpboot	[-hV] [-dx] [ basedir ]

       perpboot	 is  a utility for starting and	monitoring a perpd(8) instance
       on basedir with an associated logger.  If  basedir  is  not  specified,
       perpboot	 will  use the environmental variable PERP_BASE.  If PERP_BASE
       is not set or empty, perpboot will use a	compiled-in value for basedir,
       normally	/etc/perp.

       Within basedir, perpboot	switches into a	subdirectory named .boot/.  It
       then forks two child processes to exec ./rc.log and ./rc.perp,  with  a
       pipe connected between their respective stdin and stdout.

       Normally	 ./rc.log will be an executable	script that execs into a stdin
       logger, such as tinylog(8) or sissylog(8).  Similarly,  ./rc.perp  will
       be  an  executable script that ultimately execs into perpd(8).  See the
       examples	section	below for sample scripts.

       perpboot	sets up	its ./rc.log and ./rc.perp child processes with	an en-
       vironment that:

	      o	  closes all extraneous	file descriptors

	      o	  redirects unused stdin, stdout, and stderr to	/dev/null

	      o	  redirects  the  stdin	of ./rc.log to the stdout of ./rc.perp
		  (and vice versa)

	      o	  redirects the	stderr of ./rc.perp to stdout (with the	effect
		  that both stdout and stderr of ./rc.perp are captured	by the

	      o	  sets the environmental variable PERP_BASE to the value  used
		  for basedir

       By  default,  perpboot  itself  acts  as	lightweight supervisor for the
       ./rc.log	and ./rc.perp child processes.	If perpboot notices  that  ei-
       ther of these processes has died, it will try to	restart	them.

       -d     Detach.	Normally  perpboot itself runs in the foreground.  The
	      -d option	causes perpboot	to detach from the controlling	termi-
	      nal and run as a background process.  This option	is useful when
	      starting perpboot	from within a BSD-type	boot  script  such  as

       -h     Help.  Print a brief usage message to stderr and exit.

       -V     Version.	Print the version number to stderr and exit.

       -x     Exit.  Normally perpboot stays resident as a system process that
	      monitors its ./rc.log and	./rc.perp child	processes.  The	-x op-
	      tion  causes  perpboot to	start ./rc.log and then	replace	itself
	      with the ./rc.perp process.   This  option  is  used  to	reduce
	      process  overhead	 and/or	when you don't feel the	need to	retain
	      perpboot as a supervisor.	 As one	example, this option might  be
	      used  within an inittab(5) specification configured with the ac-
	      tion specified as	``respawn''.

       An example ./rc.log script may look like	this:

	      exec tinylog -k 8	-s 100000 -t ${LOGDIR}

       This script execs into an instance of tinylog(8)	maintaining a  rotated
       set  of	log  files in /var/log/perpd with a maximum of 8 keep files, a
       maximum log size	of 100000 bytes, and with timestamp prepended entries.

       An example ./rc.perp script:

	      exec perpd -a 6 $PERP_BASE

       Here the	script execs into perpd(8) with	autoscanning set to 6 seconds.
       Note  also  that	 the  environmental  variable PERP_BASE	is defined and
       available for the ./rc.perp and ./rc.log	scripts.

       These simple scripts could be customized	and embellished	 considerably.
       For example, the	./rc.log script	could:

	      o	  check/create existence/permissions of	log directory

	      o	  drop privilege before	running	tinylog(8) -- see runuid(8)

       Similarly, the ./rc.perp	script could perform other initializations be-
       fore the	perpd(8) exec:

	      o	  check/create existence and symlink for /etc/perp/.control

	      o	  clean	out stale control directories/files in /etc/perp/.con-

       perpd itself may	be invoked in the way that best	suits the init(8) sys-
       tem and boot scripts of the host	environment.  A	sysv-compatible	system
       may use an inittab(5) file configured with this entry:

	      PB:23456:respawn:/usr/sbin/perpboot -x /etc/perp

       This  example  shows the	-x option, with	the effect that	init(8)	itself
       will monitor the	perpd(8) process and respawn it	if it dies.

       A BSD-type system may use an rc.local file with this entry:

	      if [ -x /usr/sbin/perpboot ]; then
		  echo -n ' perpd'
		    /usr/sbin/runenv -i	/etc/perp/.boot/perp.env \
			/usr/sbin/perpboot -d /etc/perp

       In this example,	the -d option is used to  run  perpboot	 as  a	daemon

       This  example  is  further embellished to show the use of the runenv(8)
       runtool to setup	a clean	environment for	the perpd(8) process  and  its

	      The default base operating directory for perpd(8).

	      Directory	containing the startup scripts used by perpboot.

	      Control script used by perpboot to start a logger	for perpd(8).

	      Control script used by perpboot to start up perpd(8).

	      If  no basedir argument is given at the command-line on startup,
	      perpboot checks for a value defined by PERP_BOOT.	  If  this  is
	      not  defined or empty, perpboot uses a compiled-in default, nor-
	      mally /etc/perp.

       If perpboot gets	the SIGTERM signal, it performs	a shutdown sequence on
       its child processes:

	      o	  sends	SIGTERM	and SIGCONT to the ./rc.perp process and waits
		  for it to terminate

	      o	  closes its own copy  of  the	input  pipe  to	 the  ./rc.log
		  process and waits for	the logger to terminate

	      o	  exits	0

       Otherwise,  when	perpboot runs as a lightweight supervisor (without the
       -x option), it traps all	the other signals it can and relays  them  di-
       rectly to the ./rc.perp child process with kill(2).

       The perpboot utility is a purpose-specific modification of rundeux(8).

       Wayne Marshall,

       See  the	 perp-setup(8) utility for an ``automagic'' configuration of a
       perpboot	installation.

       perp_intro(8),  perp-setup(8),  perpctl(8),  perpd(8),	perpetrate(5),
       perphup(8), perpls(8), perpok(8), perpstat(8), sissylog(8), tinylog(8),

perp-2.07			 January 2013			   perpboot(8)


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

home | help