.\" This file is part of genrc.
.\" Copyright (C) 2018 Sergey Poznyakoff.
.\"
.\" Genrc is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Genrc is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with genrc.  If not, see <http://www.gnu.org/licenses/>. 
.TH GENRC 8 "May 20, 2018" "GENRC" "Genrc User Manual"
.SH NAME
genrc \- generic system initialization script helper
.SH SYNOPSIS
.nh
.na
\fBgenrc\fR\
 [\fB\-hv\fR]\
 [\fB\-F\fR \fIPIDFILE\fR]\
 [\fB\-P\fR \fISOURCE\fR]\
 [\fB\-c\fR \fICOMMAND\fR]\
 [\fB\-g\fR \fIGROUP\fR[,\fIGROUP\fR...]]\
 [\fB\-p\fR \fIPROGRAM\fR]\
 [\fB\-t\fR \fISECONDS\fR]\
 [\fB\-u\fR \fIUSER\fR]\
 [\fB\-\-command=\fICOMMAND\fR]\
 [\fB\-\-create\-pidfile=\fIPIDFILE\fR]\
 [\fB\-\-group=\fIGROUP\fR[,\fIGROUP\fR...]]\
 [\fB\-\-help\fR]\
 [\fB\-\-no\-reload\fR]\
 [\fB\-\-pid\-from=\fISOURCE\fR]\
 [\fB\-\-pidfile=\fIPIDFILE\fR]\
 [\fB\-\-program=\fIPROGRAM\fR]\
 [\fB\-\-restart\-on\-exit=\fR[\fB!\fR]\fISTATUS\fR[\fB,\fISTATUS\fR...]]\
 [\fB\-\-restart\-on\-signal=\fR[\fB!\fR]\fISIG\fR[\fB,\fISIG\fR...]]\
 [\fB\-\-sentinel\fR]\
 [\fB\-\-signal\-reload=\fISIG\fR]\
 [\fB\-\-signal\-stop=\fISIG\fR]\
 [\fB\-\-timeout=\fISECONDS\fR]\
 [\fB\-\-user=\fIUSER\fR]\
 [\fB\-\-usage\fR]\
 [\fB\-\-verbose\fR]\
 {\
 \fBstart\fR\
 |\
 \fBstop\fR\
 |\
 \fBrestart\fR\
 |\
 \fBreload\fR\
 |\
 \fBstatus\fR\
 }
.ad
.hy
.SH DESCRIPTION
.B genrc
is a generic helper program for writing system initialization
scripts. Depending on the operation mode, it starts, stops,
reconfigures or displays the status of a specific program.
.PP
The operation mode of the program is set by its only mandatory
argument. Other program settings are specified via the command
line options or environment variables. Most options have a
corresponding environment variable. For example, the command line
of the program to be run is given by the \fB\-\-command\fR option,
or by the \fBGENRC_COMMAND\fR environment variable. If both the
variable is set and the option is supplied, the later takes precedence
over the former.
.PP
The \fB\-\-program\fR option or the \fBGENRC_PROGRAM\fR environment
variable supplies the name of the program, which is used to determine
whether the program is already running. If not supplied, the first
word (in the shell sense) from \fICOMMAND\fR is used.
.PP
If \fB\-\-program\fR is given, but \fB\-\-command\fR is not, its value
will be used as the command to run.
.PP
The program operation modes are:
.SS start
If given \fBstart\fR argument, \fBgenrc\fR runs the supplier
command. Before, it checks if the program is not already running and
refuses to start its second copy if so.
.PP
It is supposed that the program to be run will detach from the
controlling terminal and continue running in the background (i.e. it
is a \fIdaemon\fR, in UNIX sense). If it is not the case, use the
\fB\-\-sentinel\fR option. With this option, \fBgenrc\fR will start
the command and will become daemon itself, controlling the execution
of the program. It will exit when the command terminates. So long as
the command runs, \fBgenrc\fR will pipe its standard output and error
to syslog facility \fBdaemon\fR. The standard output will be logged
with the priority \fBinfo\fR and the error with the priority
\fBerr\fR.
.PP
If the \fB\-\-create\-pidfile=\fIFILENAME\fR option is given together with
\fB\-\-sentinel\fR, the PID of the subsidiary command will be stored
in \fIFILE\fR. The file will be unlinked after the subsidiary command
terminates. Unless the \fB\-\-pid\-from\fR option is given,
\fB\-\-pid\-from=FILE:\fIFILENAME\fR will be assumed.
.PP
In sentinel mode, it is possible to restart the program if it
terminates with a specific exit code or on a specific signal. This is
controlled by the \fB\-\-restart\-on\-exit\fR and 
\fB\-\-restart\-on\-signal\fR options. Use this feature to ensure the
service provided by the program won't get terminated because of
hitting a bug or encountering an unforeseen external condition. For
example, the following two options will ensure that the program will
be terminated only if it exits with status 0 or it is terminated by
SIGTERM or SIGQUIT signal:
.EX
--restart-on-exit='!0' --restart-on-signal='!TERM,QUIT'
.EE
.PP
If restarts are requested, \fBgenrc\fR will control how often it has
to restart the program using the same algorithm as
.B init (8).
Namely, if the program is restarted more than 10 times within two
minutes, \fBgenrc\fR will disable subsequent restarts for the next
5 minutes. If the \fB\-\-create\-pidfile\fR option was used, the
PID of the controlling \fBgenrc\fR process will be stored in the
file during that interval. If the \fBSIGHUP\fR signal is delivered
during the sleep interval, the sleep will be broken prematurely and
the program restarted again.
.SS status
In \fBstatus\fR mode \fBgenrc\fR verifies if the \fICOMMAND\fR is
already running and outputs its status on the standard output. To this
effect, it uses an abstraction called \fIPID source\fR, which allows
it to determine the PID of the program by its name of command line.
.PP
The default PID source is the Linux \fB/proc\fR filesystem (or, if it
is not available, the output of \fBps -ef\fR), which is scanned for
the name of the program (given by \fB\-\-program\fR or
\fB\-\-command\fR options). 
.PP
The source to use can be supplied with the \fB\-\-pid\-from\fR option
(or the \fB\-\-pidfile option, which is equivalent to
\fB\-\-pid\-from=FILE:\fR). See the section \fBPID SOURCES\fR for a
detailed discussion of available sources.
.SS stop
In the \fBstop\fR mode \fBgenrc\fR stops the command by sending it
\fBSIGTERM\fR (or another signal as supplied with the
\fB\-\-signal\-stop\fR option). If the PID source returns multiple
PIDs, by default only parent PID is selected. However, \fBgenrc\fR can
be instructed to signal all PIDs instead (see the \fBa\fR flag in the
description of \fBPROC\fR or \fBPS\fR PID source).
.PP
After sending the signal, the program will wait for all processes to
terminate. It will report error if they don't terminate within 5
seconds. This timeout can be changed using the \fB\-\-timeout\fR
option.
.SS restart
Restarts the program. It is equivalent to running
.B genrc stop
immediately followed by
.BR "genrc start" .
.SS reload
Attempt to reload (or reconfigure) the program by sending it the
\fBSIGHUP\fR signal (or another signal, as given with the
\fB\-\-signal\-reload\fR option). The \fB\-\-no\-reload\fR or
\fB\-\-signal\-reload=0\fR option disables this behavior, making
this mode equivalent to
.BR "genrc restart" .
.SH EXAMPLE
Following is a sample \fBrc.ntpd\fR file for Slackware:
.sp
.EX
#! /bin/sh
PIDFILE=/var/run/ntpd.pid
exec /sbin/genrc \\
     \-\-command="/usr/sbin/ntpd \-g \-p $PIDFILE" \\
     \-\-no\-reload \\
     \-\-signal\-stop=SIGHUP \\
     \-\-pid\-from="FILE:$PIDFILE" "$@"
.EE
.SH OPTIONS
.TP
\fB\-c\fR, \fB\-\-command=\fICOMMAND\fR
Command line to run.
.TP
\fB\-\-create\-pidfile=\fINAME\fR
When used together with \fB\-\-sentinel\fR, the PID of the command
being run will be stored in file \fINAME\fR. The
\fB\-\-pid\-from=FILE:\fINAME\fR will be assumed, unless the
\fB\-\-pid\-from\fR is given explicitly (or the \fBGENRC_PID_FROM\fR
variable is set). 
.TP
\fB\-F\fR, \fB\-\-pidfile=\fINAME\fR
Name of the PID file (same as \fB\-\-pid\-from=FILE:\fINAME\fR)
.TP
\fB\-h\fR, \fB\-\-help\fR
Display a short help list.
.TP
\fB\-g\fR, \fB\-\-group=\fIGROUP\fR[,\fIGROUP\fR...]
Run program with this \fIGROUP\fR privileges. If the argument is a
list of groups, the first group becomes the principal, and the
rest of them supplementary groups. Each \fIGROUP\fR is either a group
name or a numeric group number prefixed with a plus sign. Whatever
notation is used, it must exist in the system group database.

See also the \fB\-\-user\fR option.
.TP
\fB\-\-no\-reload\fR
Makes \fBreload\fR equivalent to \fBrestart\fR.
.TP
\fB\-p\fR, \fB\-\-program=\fIPROGRAM\fR
Name of the program to run.
.TP
\fB\-P\fR, \fB\-\-pid\-from=\fISOURCE\fR
Where to look for PIDs of the running programs.
.TP
\fB\-\-restart\-on\-exit=\fR[\fB!\fR]\fISTATUS\fR[\fB,\fISTATUS\fR...]
This option takes effect when used together with
\fB\-\-sentinel\fR. If the program terminates with one of status
codes listed as the argument to this option, it will be immediately
restarted. The exclamation mark at the start of the list inverts the
set, e.g. \fB\-\-restart\-on\-exit='!0,1'\fR means restart unless the
program exit code is 0 or 1. Note the use of quotation to prevent the
\fB!\fR from being interpreted by the shell.
.TP
\fB\-\-restart\-on\-signal=\fR[\fB!\fR]\fISIG\fR[\fB,\fISIG\fR...]
This option takes effect when used together with
\fB\-\-sentinel\fR. If the program terminates due to receiving one of
the signals from this list, it will be immediately restarted. Each
\fISIG\fR is either a signal number, or a signal name, as listed in
.BR signal (7).
The \fBSIG\fR prefix can be omitted from the signal name. Names are
case-insensitive. Thus, \fB1\fR, \fBHUP\fR, \fBSIGHUP\fR, and
\fBsighup\fR all stand for the same signal.
.sp
The exclamation mark at the start of the list complements the signal
set, so that e.g. \fB\-\-restart\-on\-signal='!TERM,QUIT,INT'\fR will
restart the program unless it terminates on one of the listed signals.
.TP
\fB\-\-sentinel\fR
\fIPROGRAM\fR runs in foreground; disconnect from the controlling
terminal, start it and run in background until it terminates. The
program's stdout and stderr are sent to the syslog facility
\fBdaemon\fR, priorities \fBinfo\fR and \fBerr\fR, correspondingly.

See the options \fB\-\-restart\-on\-exit\fR and
\fB\-\-restart\-on\-signal\fR for details on how to restart the program.
.TP
\fB\-\-signal\-reload=\fISIG\fR
Signal to send on reload (default: \fBSIGHUP\fR). Setting it to 0 is
equivalent to \fB\-\-no\-reload\fR.
.TP
\fB\-\-signal\-stop=\fISIG\fR
Signal to send in order to terminate the program (default:
\fBSIGTERM\fR).
.TP
\fB\-t\fR, \fB\-\-timeout=\fISECONDS\fR
Time to wait for the program to start up or terminate.
.TP
\fB\-\-usage\fR
Display a short usage summary.
.TP
\fB\-u\fR, \fB\-\-user=\fIUSER\fR
Run with this user privileges. The argument is either a login
name or a numeric UID prefixed with the plus sign. Whatever form is
used, it must correspond to a valid user from the system user
database.

Unless \fB\-\-group\fR option is also given, the primary and
supplementary groups of \fIUSER\fR will be used.
.TP
\fB\-\-version\fR
Display program version and exit.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print verbose messages (e.g. "Starting \fIPROGNAME\fR").
.SH PID SOURCES
.TP
\fBFILE:\fIFILENAME\fR
Read PID from the file \fIFILENAME\fR.
.TP
\fBCONFIG:\fILANG\fB:\fIFILENAME\fB:\fIFQRN\fR
Name of the PID file is stored in relation \fIFQRN\fR of the configuration
file \fIFILENAME\fR, written in language \fILANG\fR. Recognizable
\fILANG\fR values are:
.RS
.TP
.B BIND
ISC BIND configuration file.
.TP
.B DHCPD
ISC DHCPD configuration file.
.TP
.B GIT
Git-style configuration file.
.TP
.B GRECS
GRECS-style configuration file. This is a generalization of a
structured configuration file format.
.TP
.B META1
META1 configuration file.
.TP
.B PATH
Configuration specified as fully-qualified keyword-value pairs
(similar to \fB.Xdefaults\fR).
.RE
.TP
\fBGREP:\fIFILE\fB:s/\fIRX\fB/\fIREPL\fB/[\fIFLAGS\fR][\fB;\fR...]
Grep for the first line in \fIFILE\fR that matches \fIRX\fR. If found, process
replace the matched portion according to \fIREPL\fR and \fIFLAGS\fR. Use
the resulting string as PID. More sed expressions can be supplied,
separated with semicolons.
.TP
\fBPROC\fR[\fB:\fR[\fIEXE\fR][\fB:\fIFLAGS\fR]]
Look for matching program in \fB/proc/\fIPID\fB/*\fR. If \fIEXE\fR is
not supplied or empty, program name from \fB\-\-program\fR will be
used. \fIFLAGS\fR are:
.RS
.TP
.B e
exact match
.TP
.B g
glob pattern match
.TP
.B x
extended POSIX regexp match (default)
.TP
.B p
PCRE match
.TP
.B i
case-insensitive match
.TP
.B c
match entire command line
.TP
.B r
match real executable name (instead of argv0)
.TP
.B a
signal all matching PIDs
.RE
.TP
\fBPS:\fR[\fB:\fR[\fIEXE\fR][:\fIFLAGS\fR]]
Look for matching program in the output of \fBps \-ef\fR. \fIEXE\fR
and \fIFLAGS\fR are as described above.
.SH ENVIRONMENT
Influential environment variables and corresponding options:
.sp
.nf
.ta 5n 35n
.ul
	Variable	Option
	\fBGENRC_COMMAND=\fICOMMAND\fR	\fB\-\-command=\fICOMMAND\fR
	\fBGENRC_PROGRAM=\fINAME\fR	\fB\-\-program=\fINAME\fR
	\fBGENRC_PID_FROM=\fISOURCE\fR	\fB\-\-pid\-from=\fISOURCE\fR
	\fBGENRC_TIMEOUT=\fISECONDS\fR	\fB\-\-timeout=\fISECONDS\fR
	\fBGENRC_SENTINEL=1\fR	\fB\-\-sentinel\fR
	\fBGENRC_CREATE_PIDFILE=\fINAME\fR	\fB\-\-create\-pidfile=\fINAME\fR
	\fBGENRC_USER=\fINAME\fR	\fB\-\-user=\fINAME\fR
	\fBGENRC_GROUP=\fIGROUPS\fR	\fB\-\-group=\fIGROUPS\fR	
.fi
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2018 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: