This program emerged as a result of several decades of writing SysV-style initialization scripts and inspecting such scripts written by others.
SysV-style scripts are shell scripts executed during system startup and
shutdown. They are normally located in /etc/init.d directory
and symlinked to several /etc/rcn.d directories (where
n is a decimal runlevel number), where they are looked
up by the init
process. On other systems
(e.g. Slackware
), they are located in /etc/rc.d
directory.
Each such script accepts a single argument – a command verb –
and performs the requested action depending on it. For example,
start
instructs the script to start up a service it was written
for, stop
instructs it to shut it down, and so on. All command
verbs form a fixed set.
The genrc
tool is a generic helper program for writing
SysV-style scripts. Depending on the operation mode, it starts, stops,
reconfigures or displays current status of a specific program
(usually, a daemon), hereinafter referred to as service.
The operation mode of the program is requested by the command verb,
given as its only mandatory argument. Other program settings are
specified via command line options or, if explicitly requested on the
command line, environment variables.1 For example,
the command line of the service to start is given by the
--command option. If the use of environment is allowed,
it can also be supplied by the GENRC_COMMAND
environment
variable. See Environment Variables, for a detailed discussion of
environment variables and their use.
The --program option supplies the service program name, i.e. the name of the executable file to be run or monitored. If not given explicitly, the first word (in the shell sense) from the command is used.
The service run by genrc
is usually a daemon,
i.e. a program that, upon startup, detaches itself from the
controlling terminal and continues operating in background. However,
regular foreground programs can be used too. For such cases,
genrc
can itself work as a wrapper over the service,
running it in the background (see Sentinel).
Calling genrc
with appropriate command word allows you to
perform various operations on the service, such as inspecting
its state (running or not), stopping or restarting it, etc.
To give you the feel of what genrc
can do, here is an
example of startup script for ntpd
:
#! /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" "$@"
See below for the meaning of each particular option.
Up to version 1.5.3,
genrc
used environment by default. Since version 2.0 you
should explicitly give your consent to using the environment, by
supplying the --env command line option.