Add documentation.

1 files changed, 291 insertions, 0 deletions

diff --git a/src/genrc.8 b/src/genrc.8
new file mode 100644
index 0000000..1255b45
--- /dev/null
+++ b/src/genrc.8
@@ -0,0 +1,291 @@
+.\" 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 15, 2018" "GENRC" "Genrc User Manual"
+.SH NAME
+genrc \- generic system initialization script helper
+.SH SYNOPSIS
+.nh
+\fBgenrc\fR\
+ [\fB\-h\fR]\
+ [\fB\-F\fR \fIPIDFILE\fR]\
+ [\fB\-P\fR \fISOURCE\fR]\
+ [\fB\-c\fR \fICOMMAND\fR]\
+ [\fB\-p\fR \fIPROGRAM\fR]\
+ [\fB\-t\fR \fISECONDS\fR]\
+ [\fB\-\-command=\fICOMMAND\fR]\
+ [\fB\-\-help\fR]\
+ [\fB\-\-no\-reload\fR]\
+ [\fB\-\-pid\-from=\fISOURCE\fR]\
+ [\fB\-\-pidfile=\fIPIDFILE\fR]\
+ [\fB\-\-program=\fIPROGRAM\fR]\
+ [\fB\-\-sentinel\fR]\
+ [\fB\-\-signal\-reload=\fISIG\fR]\
+ [\fB\-\-signal\-stop=\fISIG\fR]\
+ [\fB\-\-timeout=\fISECONDS\fR]\
+ [\fB\-\-usage\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\-\-pidfile=\fIFILE\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.
+.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\-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\-\-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\-\-sentinel\fR
+\fIPROGRAM\fR runs in foreground; disconnect from the controlling
+terminal, run it and act as a sentinel.
+.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\-\-version\fR
+Display program version and exit.
+.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
+	\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
+.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:
+