Packaging:SysVInitScript

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 them into /etc/rc.d/init.d. A rpm macro exists for this directory,. Note: The  macro does not exist on Fedora 9 or older releases, or on RHEL 5 or older. For those releases, you should use the deprecated  macro.

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/ 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/ config file.

Init scripts should also have 0755 permissions.

Initscripts in addition to systemd unit files
In Fedora 15+, SysV initscripts are no longer the default, they have been obsoleted by systemd unit files. There are guidelines for systemd here: Packaging:Systemd.

However, packagers who wish to include SysV initscripts may also do so, but they MUST be placed into a separate $name-sysvinit subpackage. Please note that the base package MUST contain the systemd unit file. In this scenario, use the following scriptlet:

%triggerpostun -n packagename-sysvinit -- packagename < 1.0-2 /sbin/chkconfig --add httpd >/dev/null 2>&1 || :

Please note that in the example, "1.0-2" is the version in which the package switched to systemd unit files by default.

Initscripts in spec file scriptlets
Requires(post): chkconfig Requires(preun): chkconfig Requires(preun): initscripts ... %post /sbin/chkconfig --add
 * 1) This is for /sbin/service
 * 1) This adds the proper /etc/rc*.d links for the script

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

'if [ $1 -eq 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 condrestart >/dev/null 2>&1 || : fi
 * 1) This is for /sbin/service

'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 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.


 * 1) !/bin/sh
 * 2) chkconfig:   
 * 3) description: 
 * 1) chkconfig:   
 * 2) description: 


 * 1) BEGIN INIT INFO
 * 2) Provides:
 * 3) Required-Start:
 * 4) Required-Stop:
 * 5) Should-Start:
 * 6) Should-Stop:
 * 7) Default-Start:
 * 8) Default-Stop:
 * 9) Short-Description:
 * 10) Description:
 * 11) END INIT INFO

. /etc/rc.d/init.d/functions
 * 1) Source function library.

exec="/path/to/ " prog=" " config=""

[ -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: " # if not running, start it up here, usually something like "daemon $exec" retval=$? echo [ $retval -eq 0 ] && touch $lockfile return $retval }

stop { echo -n $"Stopping $prog: " # stop it here, often "killproc $prog" retval=$? echo [ $retval -eq 0 ] && rm -f $lockfile return $retval }

restart { stop start }

reload { restart }

force_reload { restart }

rh_status { # run checks to determine if the service is running or use generic 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  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.


 * 1) chkconfig:


 * 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.
 * is the "priority" weight for starting the service. Services are started in numerical order, starting at 0.
 * is the "priority" weight for stopping the service. Services are stopped in numerical order, starting at 0. By default, you should set the equal to 100 -.

For example:
 * 1) chkconfig: 2345 20 80

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:
 * 1) chkconfig: - 20 80

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


 * 1) description:

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:
 * 1) description: Saves and restores system entropy pool for \
 * 2)              higher quality random number generation.

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:

Boundary Comments
The LSB Header is bounded by comments, specifically, the beginning of the header is marked with:
 * 1) BEGIN INIT INFO

The end of the LSB Header is marked with:
 * 1) 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  line in the LSB Header.

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


 * 1) Provides: boot_facility_1 [boot_facility_2...]

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.

In Fedora, a  line listing the name of the service that the initscript starts is not needed as the name of the service is implicitly Provided.

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


 * 1) Required-Start: boot_facility_1 [boot_facility_2...]

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  line in the LSB Header lists any boot facilities which should NOT be stopped before shutting down this service.


 * 1) Required-Stop: boot_facility_1 [boot_facility_2...]

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


 * 1) Should-Start: boot_facility_1 [boot_facility_2...]

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


 * 1) Should-Stop: boot_facility_1 [boot_facility_2...]

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  line

# Default-Start: line
The  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.


 * 1) Default-Start: run_level_1 [run_level_2...]

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:


 * 1) Default-Start: 3 4 5

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

# Default-Stop: line
The  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  line.


 * 1) Default-Stop: run_level_1 [run_level_2...]

Each Fedora SysV-style initscript which needs to start by default in any runlevel must include this line in the LSB Header (if the  line is present, then there must also be a   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  line in the LSB Header must specify runlevels 0, 1, 2, and 6:


 * 1) Default-Stop: 0 1 2 6

Note that the runlevels must be explicitly set in the  line, there are no automatic default settings derived from the   line.

# Short-Description: line
The  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.


 * 1) Short-Description: This service is a mail server.

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

# Description: line
The  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:
 * 1) Description: Bluetooth services for service discovery, authentication,
 * 2)              Human Interface Devices, etc.

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

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


 * 1) BEGIN INIT INFO
 * 2) Provides: OurDB
 * 3) Required-Start: $local_fs $network $remote_fs
 * 4) Required-Stop: $local_fs $network $remote_fs
 * 5) Default-Start: 2 3 4 5
 * 6) Default-Stop: 0 1 6
 * 7) Short-Description: start and stop OurDB
 * 8) Description: OurDB is a very fast and reliable database
 * 9)              engine used for illustrating init scripts
 * 10) END INIT INFO

LSB Headers are not required for Fedora SysV-style initscripts, but if it is used in the initscript, then,  , and   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
 * 1) Source function library.

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 ]  [ --user ] [+/-nicelevel] program [arguments]  [&]

--check : Check that is running, as opposed to simply the first argument passed to daemon. --user : Run command as user

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=$?        ;;

...