GENRC

NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
OPTIONS
PID SOURCES
ENVIRONMENT
AUTHORS
BUG REPORTS
COPYRIGHT

---

NAME

genrc - generic system initialization script helper

SYNOPSIS

genrc [-hv] [-F PIDFILE] [-P SOURCE] [-c COMMAND] [-g GROUP[,GROUP...]] [-p PROGRAM] [-t SECONDS] [-u USER] [--command=COMMAND] [--create-pidfile=PIDFILE] [--group=GROUP[,GROUP...]] [--help] [--no-reload] [--pid-from=SOURCE] [--pidfile=PIDFILE] [--program=PROGRAM] [--restart-on-exit=[!]STATUS[,STATUS...]] [--restart-on-signal=[!]SIG[,SIG...]] [--sentinel] [--signal-reload=SIG] [--signal-stop=SIG] [--timeout=SECONDS] [--user=USER] [--usage] [--verbose] { start | stop | restart | reload | status }

DESCRIPTION

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.

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 --command option, or by the GENRC_COMMAND environment variable. If both the variable is set and the option is supplied, the later takes precedence over the former.

The --program option or the GENRC_PROGRAM 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 COMMAND is used.

If --program is given, but --command is not, its value will be used as the command to run.

The program operation modes are:

start
If given start argument, genrc runs the supplier command. Before, it checks if the program is not already running and refuses to start its second copy if so.

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 daemon, in UNIX sense). If it is not the case, use the --sentinel option. With this option, genrc 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, genrc will pipe its standard output and error to syslog facility daemon. The standard output will be logged with the priority info and the error with the priority err.

If the --create-pidfile=FILENAME option is given together with --sentinel, the PID of the subsidiary command will be stored in FILE. The file will be unlinked after the subsidiary command terminates. Unless the --pid-from option is given, --pid-from=FILE:FILENAME will be assumed.

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 --restart-on-exit and --restart-on-signal 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:
--restart-on-exit=’!0’ --restart-on-signal=’!TERM,QUIT’

If restarts are requested, genrc will control how often it has to restart the program using the same algorithm as init (8). Namely, if the program is restarted more than 10 times within two minutes, genrc will disable subsequent restarts for the next 5 minutes. If the --create-pidfile option was used, the PID of the controlling genrc process will be stored in the file during that interval. If the SIGHUP signal is delivered during the sleep interval, the sleep will be broken prematurely and the program restarted again.

status
In status mode genrc verifies if the COMMAND is already running and outputs its status on the standard output. To this effect, it uses an abstraction called PID source, which allows it to determine the PID of the program by its name of command line.

The default PID source is the Linux /proc filesystem (or, if it is not available, the output of ps -ef), which is scanned for the name of the program (given by --program or --command options).

The source to use can be supplied with the --pid-from option (or the --pidfile option, which is equivalent to --pid-from=FILE:). See the section PID SOURCES for a detailed discussion of available sources.

stop
In the stop mode genrc stops the command by sending it SIGTERM (or another signal as supplied with the --signal-stop option). If the PID source returns multiple PIDs, by default only parent PID is selected. However, genrc can be instructed to signal all PIDs instead (see the a flag in the description of PROC or PS PID source).

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 --timeout option.

restart
Restarts the program. It is equivalent to running genrc stop immediately followed by genrc start.

reload
Attempt to reload (or reconfigure) the program by sending it the SIGHUP signal (or another signal, as given with the --signal-reload option). The --no-reload or --signal-reload=0 option disables this behavior, making this mode equivalent to genrc restart.

EXAMPLE

Following is a sample rc.ntpd file for Slackware:

#! /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" "$@"

OPTIONS

-c, --command=COMMAND

Command line to run.

--create-pidfile=NAME

When used together with --sentinel, the PID of the command being run will be stored in file NAME. The --pid-from=FILE:NAME will be assumed, unless the --pid-from is given explicitly (or the GENRC_PID_FROM variable is set).

-F, --pidfile=NAME

Name of the PID file (same as --pid-from=FILE:NAME)

-h, --help

Display a short help list.

-g, --group=GROUP[,GROUP...]

Run program with this GROUP privileges. If the argument is a list of groups, the first group becomes the principal, and the rest of them supplementary groups. Each GROUP 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 --user option.

--no-reload

Makes reload equivalent to restart.

-p, --program=PROGRAM

Name of the program to run.

-P, --pid-from=SOURCE

Where to look for PIDs of the running programs.

--restart-on-exit=[!]STATUS[,STATUS...]

This option takes effect when used together with --sentinel. 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. --restart-on-exit=’!0,1’ means restart unless the program exit code is 0 or 1. Note the use of quotation to prevent the ! from being interpreted by the shell.

--restart-on-signal=[!]SIG[,SIG...]

This option takes effect when used together with --sentinel. If the program terminates due to receiving one of the signals from this list, it will be immediately restarted. Each SIG is either a signal number, or a signal name, as listed in signal(7). The SIG prefix can be omitted from the signal name. Names are case-insensitive. Thus, 1, HUP, SIGHUP, and sighup all stand for the same signal.

The exclamation mark at the start of the list complements the signal set, so that e.g. --restart-on-signal=’!TERM,QUIT,INT’ will restart the program unless it terminates on one of the listed signals.

--sentinel

PROGRAM 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 daemon, priorities info and err, correspondingly.

See the options --restart-on-exit and --restart-on-signal for details on how to restart the program.

--signal-reload=SIG

Signal to send on reload (default: SIGHUP). Setting it to 0 is equivalent to --no-reload.

--signal-stop=SIG

Signal to send in order to terminate the program (default: SIGTERM).

-t, --timeout=SECONDS

Time to wait for the program to start up or terminate.

--usage

Display a short usage summary.

-u, --user=USER

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 --group option is also given, the primary and supplementary groups of USER will be used.

--version

Display program version and exit.

-v, --verbose

Print verbose messages (e.g. "Starting PROGNAME").

PID SOURCES

FILE:FILENAME

Read PID from the file FILENAME.

CONFIG:LANG:FILENAME:FQRN

Name of the PID file is stored in relation FQRN of the configuration file FILENAME, written in language LANG. Recognizable LANG values are:

	BIND		ISC BIND configuration file.
	DHCPD		ISC DHCPD configuration file.
	GIT		Git-style configuration file.
	GRECS		GRECS-style configuration file. This is a generalization of a structured configuration file format.
	META1		META1 configuration file.
	PATH		Configuration specified as fully-qualified keyword-value pairs (similar to .Xdefaults).

GREP:FILE:s/RX/REPL/[FLAGS][;...]

Grep for the first line in FILE that matches RX. If found, process replace the matched portion according to REPL and FLAGS. Use the resulting string as PID. More sed expressions can be supplied, separated with semicolons.

PROC[:[EXE][:FLAGS]]

Look for matching program in /proc/PID/*. If EXE is not supplied or empty, program name from --program will be used. FLAGS are:

	e		exact match
	g		glob pattern match
	x		extended POSIX regexp match (default)
	p		PCRE match
	i		case-insensitive match
	c		match entire command line
	r		match real executable name (instead of argv0)
	a		signal all matching PIDs

PS:[:[EXE][:FLAGS]]

Look for matching program in the output of ps -ef. EXE and FLAGS are as described above.

ENVIRONMENT

Influential environment variables and corresponding options:

Variable Option

	GENRC_COMMAND=COMMAND	--command=COMMAND
	GENRC_PROGRAM=NAME	--program=NAME
	GENRC_PID_FROM=SOURCE	--pid-from=SOURCE
	GENRC_TIMEOUT=SECONDS	--timeout=SECONDS
	GENRC_SENTINEL=1	--sentinel
	GENRC_CREATE_PIDFILE=NAME	--create-pidfile=NAME
	GENRC_USER=NAME	--user=NAME
	GENRC_GROUP=GROUPS	--group=GROUPS

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org>.

COPYRIGHT

Copyright © 2018 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

---