EPEL:SysVInitScripts

Fedora SysV Initscripts

This document describes the guidelines for SysV-style Initscripts, for use and inclusion in Fedora packages.

Initscripts on the filesystem

Packages with SysV-style initscripts must put any them into /etc/rc.d/init.d. A rpm macro exists for this directory, %_initrddir.

In the past, some packages were putting files in /etc/init.d instead of /etc/rc.d/init.d. (/etc/init.d is a symlink to /etc/rc.d/init.d)

This split made it more difficult to use yum install against the initscript filename and path. Since /etc/init.d is the symlink (and because the Filesystem Hierarchy Standard does not mandate a location), Fedora requires that all SysV-style initscripts must go into the full /etc/rc.d/init.d directory.

Initscript packaging

Initscripts must not be marked as %config files.

Although init files live in /etc, they are scripts to be executed, not configured. Any configuration should be made available through /etc/sysconfig/<service> rather than in the init script itself. A valid exception to this rule would be existing packages where configuration is still done via the init file. In this case, the init file could be marked as %config following the rules from the Configuration files section to preserve a users configuration upon upgrade, hopefully so that the user can migrate said configuration to a new /etc/sysconfig/<service> config file.

Init scripts should also have 0755 permissions.

Initscripts in spec file scriptlets

Requires(post): chkconfig
Requires(preun): chkconfig
Requires(preun): initscripts
...
%post
/sbin/chkconfig --add <script>

%preun
if [ $1 = 0 ] ; then
/sbin/service <script> stop >/dev/null 2>&1
/sbin/chkconfig --del <script>
fi

'if [ $1 = 0 ] ' checks that this is the actual deinstallation of the package, as opposed to just removing the old package on upgrade. These statements stop the service, and remove the /etc/rc*.d links.

Requires(postun): initscripts
...
%postun
if [ "$1" -ge "1" ] ; then
/sbin/service <script> condrestart >/dev/null 2>&1 || :
fi

'if [ "$1" -ge "1" ] checks that this is an upgrade of the package. If so, restart the service if it's running. (This may not be appropriate for all services.)

Why don't we....

• run 'chkconfig <service> on'?

If a service should be enabled by default, make this the default in the init script. Doing otherwise will cause the service to be turned on on upgrades if the user explicitly disabled it.

Note that the default for most network-listening scripts is off. This is done for better security. We have multiple tools that can enable services, including GUIs.

• start the service after installation?

Installations can be in changeroots, in an installer context, or in other situations where you don't want the services started.

Initscript template

Below is the template for Fedora SysV-style initscripts. The sections are explained in detail below.

#!/bin/sh
#
#

<!--# BEGIN INIT INFO
-->
<!--# END INIT INFO
-->

. /etc/rc.d/init.d/functions

exec="/path/to/<daemonname>"
prog="<service name>"
config="<path to major config file>"

[ -e /etc/sysconfig/$prog ]  && . /etc/sysconfig/$prog

lockfile=/var/lock/subsys/$prog

start() {
[ -x $exec ]  || exit 5
[ -f $config ]  || exit 6
echo -n $"Starting $prog: "
retval=$?
echo
[ $retval -eq 0 ]  && touch $lockfile
return $retval
}

stop() {
echo -n $"Stopping $prog: "
retval=$?
echo
[ $retval -eq 0 ]  && rm -f $lockfile
return $retval
}

restart() {
stop
start
}

reload() {
restart
}

force_reload() {
restart
}

rh_status() {
status $prog
}

rh_status_q() {
rh_status >/dev/null 2>&1
}


case "$1" in
start)
rh_status_q && exit 0
$1
;;
stop)
rh_status_q || exit 0
$1
;;
restart)
$1
;;
reload)
rh_status_q || exit 7
$1
;;
force-reload)
force_reload
;;
status)
rh_status
;;
condrestart|try-restart)
rh_status_q || exit 0
restart
;;
*)
echo $"Usage: $0 {start|stop|status|restart|condrestart|try-restart|reload|force-reload}"
exit 2
esac
exit $?

Chkconfig Header

Every Fedora SysV-style initscript must contain a chkconfig header. This header is composed of two parts, a "# chkconfig:" line, and a "# description:" line.

# chkconfig: line

The chkconfig: line in a SysV-style initscript is used to determine the runlevels in which the service should be started by default. It is also used to set the "priority", or order in which the services are started within a runlevel. All Fedora SysV-style initscripts must have this line.

• <startlevellist> is a list of the runlevels for which the service should be started by default. Only services which are really required for a vital system should define runlevels here. If no runlevels are defined, a - should be used in place of the runlevels list.
• <startpriority> is the "priority" weight for starting the service. Services are started in numerical order, starting at 0.
• <endpriority> is the "priority" weight for stopping the service. Services are stopped in numerical order, starting at 0. By default, you should set the <endpriority> equal to 100 - <startpriority>.

For example:

This means that the service will start by default on runlevels 2, 3, 4, and 5, with a startup priority of 20, and a shutdown priority of 80.

More commonly, the service is off by default on all runlevels, which looks like this:

# description: line

The second line in the chkconfig header contains a description for the service. All Fedora SysV-style initscripts must have this line.

The description of service may be more than one line long, continued with '\' characters. The initial comment and following whitespace on any additional lines are ignored, but should be used.

For example:

LSB Header

LSB Headers are not required for Fedora SysV-style initscripts, but they may be used. There is no requirement in the LSB certification for any system scripts to be LSB compliant, and it can cause issues with ordering.

If LSB Headers are used in a Fedora SysV-style initscript, it must follow these guidelines.

The LSB Header is composed of the following sections:

• # Provides:
• # Required-Start:
• # Required-Stop:
• # Should-Start:
• # Should-Stop:
• # Default-Start:
• # Default-Stop:
• # Short-Description:
• # Description:

Boundary Comments

The LSB Header is bounded by comments, specifically, the beginning of the header is marked with:

<!--# BEGIN INIT INFO
-->

The end of the LSB Header is marked with:

<!--# END INIT INFO
-->

All LSB Header entries must have these boundary comments.

Facility Names

Boot facilities are used to indicate dependencies in initialization scripts. Facility names are assigned to scripts by the Provides: keyword. Facility names that begin with a dollar sign ('$') are reserved system facility names. Facility names are only recognized in the context of the initscript comment block (LSB Header) and are not available in the body of the init script. In particular, the use of the leading '$' character does not imply system facility names are subject to shell variable expansion, since they appear inside comments.

LSB compliant init implementations are supposed to provide the following system facility names:

• $local_fs:: all local file systems are mounted
• $network:: basic networking support is available. Example: a server program could listen on a socket.
• $named:: IP name-to-address translation, using the interfaces described in this specification, are available to the level the system normally provides them. Example: if a DNS query daemon normally provides this facility, then that daemon has been started.
• $portmap:: daemons providing SunRPC/ONCRPC portmapping service as defined in RFC 1833: Binding Protocols for ONC RPC Version 2 (if present) are running.
• $remote_fs:: all remote file systems are available. In some configurations, file systems such as /usr may be remote. Many applications that require $local_fs will probably also require $remote_fs.
• $syslog:: system logger is operational.
• $time:: the system time has been set, for example by using a network-based time program such as ntp or rdate, or via the hardware Real Time Clock.

Other (non-system) facilities may be defined in the # Provides: line in the LSB Header.

# Provides: line

The # Provides: line in the LSB Header lists any boot facilities that this service provides. Other services can reference these boot facilities in their # Required-Start: and # Required-Stop: lines.

When an initscript is run with a start argument, the boot facility or facilities specified by the Provides keyword shall be deemed present and hence init scripts which require those boot facilities should be started later. When an initscript is run with a stop argument, the boot facilities specified by the Provides keyword are deemed no longer present.

All Fedora SysV-style initscripts that use LSB Headers must have a # Provides: line, listing the name of the service that the initscript starts. Other boot facilities may be added as needed.

Example:

# Required-Start: line

The # Required-Start: line in the LSB Header lists any boot facilities which must be available during startup of this service.

This line is optional, if an initscript has no need for requiring other boot facilities before starting, it should be omitted.

# Required-Stop: line

The # Required-Stop: line in the LSB Header lists any boot facilities which should NOT be stopped before shutting down this service.

This line is optional, if an initscript has no need for requiring that other boot facilities must be stopped only after it has shutdown, then the line should be omitted.

# Should-Start: line

The # Should-Start: line in the LSB Header lists any facilities, which, if present, should be available during startup of this service. The intent is to allow for "optional" dependencies which do not cause the service to fail if a facility is not available.

This line is optional, if an initscript has no use for starting other optional dependencies before hand, it should be omitted.

# Should-Stop: line

The # Should-Stop: line in the LSB Header lists any facilities, which, if present, should only be stopped after shutting down this service. The intent is to allow for "optional" dependencies which do not cause the service to fail if a facility is not available.

This line is optional, if an initscript has no use for preventing other optional dependencies from stopping until after it has shutdown, the line should be omitted.

How LSB Provides actually work in Fedora

Fedora uses chkconfig for script enablement (chkconfig --add) and script activation/deactivation (chkconfig on/chkconfig off). When these tasks occur, the LSB dependencies are read, and the start and stop priorities of the scripts are then adjusted to satisfy those dependencies.

What this means:

• LSB header dependencies are honored (albeit in a static mechanism)
• If you use LSB headers, your start and stop priority may end up being different than what is in the # chkconfig: line

# Default-Start: line

The # Default-Start: line in the LSB Header lists the runlevels for which the service will be enabled by default. These runlevels are space-separated, unlike the Chkconfig header.

Each Fedora SysV-style initscript which needs to start by default in any runlevel must include this line in the LSB Header, and it must match the list of runlevels defined for startup in the Chkconfig header. Only services which are really required for a vital system should define runlevels here. If the service does not start by default in any runlevel, this line should be omitted.

For example, if a service starts by default in runlevels 3, 4, and 5 only, the LSB Header in the initscript would specify:

More commonly, the service does not start by default in any runlevel. In this case, the line should be omitted.

# Default-Stop: line

The # Default-Stop: line in the LSB Header lists the runlevels for which the service will not be started by default. These runlevels are space-separated, and must contain all of the numeric runlevels not used in the # Default-Start: line.

Each Fedora SysV-style initscript which needs to start by default in any runlevel must include this line in the LSB Header (if the # Default-Start: line is present, then there must also be a # Default-Stop: line.). If the service does not start by default in any runlevel, this line should be omitted.

For example, if a service starts by default in runlevels 3, 4, and 5 only, then the # Default-Stop: line in the LSB Header must specify runlevels 0, 1, 2, and 6:

Note that the runlevels must be explicitly set in the # Default-Stop: line, there are no automatic default settings derived from the # Default-Start: line.

# Short-Description: line

The # Short-Description: line in the LSB Header provides a brief summary of the actions of the init script. This must be no longer than a single, 80 character line of text.

All Fedora SysV-style initscripts must contain the # Short-Description: line in the LSB Header. It can be considered roughly equivalent to the Summary: field in an RPM spec file.

# Description: line

The # Description: line in the LSB Header provides a more complete description of the actions of the initscript. It may span mulitple lines, where each continuation line must begin with a '#' followed by tab character or a '#' followed by at least two space characters. The multiline description is terminated by the first line that does not match this criteria.

Example:

All Fedora SysV-style initscripts must contain the # Description: line in the LSB Header. It can be considered roughly equivalent to the %description section in an RPM spec file. It must contain the same text as the # description: line in the chkconfig header.

LSB Header Example

Here is a complete LSB Header to illustrate the correct use of the LSB Headers:

<!--# BEGIN INIT INFO
-->
<!--# END INIT INFO
-->

LSB Headers are not required for Fedora SysV-style initscripts, but if it is used in the initscript, then #Provides:, # Short-Description:, and # Description: are required to be present.

Initialization of Environment Variables

Since initscripts may be run manually by a system administrator with non-standard environment variable values for PATH, USER, LOGNAME, etc., init scripts should not depend on the values of these environment variables. They should be set to known/default values if they are needed.

Required Actions

All SysV-style initscripts in Fedora must have implementations of the following actions:

• start: starts the service
• stop: stops the service
• restart: stop and restart the service if the service is already running, otherwise just start the service
• condrestart (and try-restart): restart the service if the service is already running, if not, do nothing
• reload: reload the configuration of the service without actually stopping and restarting the service (if the service does not support this, do nothing)
• force-reload: reload the configuration of the service and restart it so that it takes effect
• status: print the current status of the service
• usage: by default, if the initscript is run without any action, it should list a "usage message" that has all actions (intended for use)

condrestart and try-restart

Fedora SysV-style initscripts must support both the condrestart and try-restart action. These two actions are intended to serve an identical purpose, and must not differ in behavior. In fact, it is highly recommended that packagers implement condrestart and try-restart as equivalent options in the case statement:

condrestart|try-restart)
rh_status_q || exit 0
restart
;;

Initscripts must be on their best behavior

Fedora SysV-style initscripts must behave sensibly if they are started when the service is already running, or stopped when the service is not running. They must not kill unrelated (but perhaps, similarly-named) user processes as a result of their normal actions. The best way to achieve this is to use the init-script functions provided by /etc/rc.d/init.d/functions :

. /etc/rc.d/init.d/functions

If a service reloads its configuration automatically (as in the case of cron, for example), the reload action of the initscript must behave as if the configuration was reloaded successfully. The restart, condrestart, try-restart, reload and force-reload actions may be atomic; that is if a service is known not to be operational after a restart or reload, the script may return an error without any further action.

Exit Codes for the Status Action

If the status action is requested, the initscript must return the correct exit status code, from this list:

0:	program is running or service is OK
1:	program is dead and /var/run pid file exists
2:	program is dead and /var/lock lock file exists
3:	program is not running
4:	program or service status is unknown
5-99:	reserved for future LSB use
100-149:	reserved for distribution use
150-199:	reserved for application use
200-254:	reserved

Fedora does not currently define any distribution specific status codes.

Exit Codes for non-Status Actions

For all other initscript actions, the init script must return an exit status of zero if the action was successful. In addition to straightforward success, the following situations are also to be considered successful:

• restarting a service (instead of reloading it) with the force-reload argument
• running start on a service already running
• running stop on a service already stopped or not running
• running restart on a service already stopped or not running
• running condrestart or try-restart on a service already stopped or not running

In case of an error while processing any non-Status initscript action, the initscript must print an error message and exit with the appropriate non-zero status code:

1:	generic or unspecified error (current practice)
2:	invalid or excess argument(s)
3:	unimplemented feature (for example, "reload")
4:	user had insufficient privilege
5:	program is not installed
6:	program is not configured
7:	program is not running
8-99:	reserved for future LSB use
100-149:	reserved for distribution use
150-199:	reserved for application use
200-254:	reserved

Fedora does not currently define any distribution specific status codes.

Other Actions

You are not prohibited from adding other commands, but you should list all commands which you intend to be used interactively to the usage message.

Functions in /etc/init.d/functions

Here are some commonly used functions provided by /etc/init.d/functions:

daemon function

Starts a daemon, if it is not already running. Does other useful things like keeping the daemon from dumping core if it terminates unexpectedly.

daemon  [ --check <name> ]  [ --user <username>] 
[+/-nicelevel]  program [arguments]  [&] 

--check <name>:
Check that <name> is running, as opposed to simply the
first argument passed to daemon().
--user <username>:
Run command as user <username>

killproc function

Sends a signal to the program; by default it sends a SIGTERM, and if the process doesn't die, it sends a SIGKILL a few seconds later. It also tries to remove the pidfile, if it finds one.

killproc program [signal] 

pidofproc function

Tries to find the pid of a program; checking likely pidfiles, and using the pidof program. Used mainly from within other functions in this file, but also available to scripts.

pidofproc program

status function

Prints status information. Assumes that the program name is the same as the servicename.

status program

Note that this is different from the Status action, this is a function that is usually used when the Status action is executed:

case "$1" in

...

status)
status hcid
RETVAL=$?
;;

...