Conventions for Init Scripts
Initscripts must meet the LSB Base Core Specifications: http://refspecs.linux-foundation.org/LSB_3.2.0/LSB-Core-generic/LSB-Core-generic/tocsysinit.html
See first
Quick Notes
- keep the old chkconfig header, until the transition is complete and known to work
- add the LSB comment block
- chkconfig processes both the LSB comment block and the chkconfig: header, LSB overrides
- Default-Start means the service is enabled by default after chkconfig --add
- check if the standard actions are implemented
- check the exit status of every action
- do not yet implement the LSB functions like log_***_msg()
- we don't follow LSB section 20.4. Installation and Removal of Init Scripts
Unanswered questions
- http://www.redhat.com/archives/fedora-devel-list/2007-July/msg00365.html
- Are there default values for Default-Start/Default-Stop? Eg. if "Default-Start: 2 3 4 5" is specified, does "Default-Stop: 0 1 6" need to be added? What happens if Default-Stop is not added?
- If there's no Default-Start, is Default-Stop needed?
- Is "Default-Stop: 0 1 2 3 4 5 6" the same as leaving Default-Stop out?
- Which keywords are required? None/all/subset?
Init Script Actions
Conforming applications which need to execute commands on changes to the system run level (including boot and shutdown), may install one or more init scripts. Init scripts provided by conforming applications shall accept a single argument which selects the action:
- start start the service
- stop stop the service
- restart stop and restart the service if the service is already running, otherwise start the service
- try-restart restart the service if the service is already running
- reload cause the configuration of the service to be reloaded without actually stopping and restarting the service
- force-reload cause the configuration to be reloaded if the service supports this, otherwise restart the service if it is running
- status print the current status of the service
The start, stop, restart, force-reload, and status actions shall be supported by all init scripts; the reload and the try-restart actions are optional. Other init-script actions may be defined by the init script.
Init scripts shall ensure that they will behave sensibly if invoked with start when the service is already running, or with stop when not running, and that they do not kill similarly-named user processes. The best way to achieve this is to use the init-script functions provided by /lib/lsb/init-functions (see Init Script Functions)
If a service reloads its configuration automatically (as in the case of cron, for example), the reload action of the init script shall behave as if the configuration was reloaded successfully. The restart, 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.
If the status action is requested, the init script will return the following exit status codes.
- 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
For all other init-script actions, the init script shall return an exit status of zero if the action was successful. Otherwise, the exit status shall be non-zero, as defined below. 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 try-restart on a service already stopped or not running
In case of an error while processing any init-script action except for status, the init script shall print an error message and exit with a 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
Error and status messages should be printed with the logging functions (see Init Script Functions) log_success_msg(), log_failure_msg() and log_warning_msg(). Scripts may write to standard error or standard output, but implementations need not present text written to standard error/output to the user or do anything else with it.
Comment Conventions for Init Scripts
Conforming applications may install one or more init scripts. These init scripts must be activated by invoking the install_initd command. Prior to package removal, the changes applied by install_initd must be undone by invoking remove_initd. See Installation and Removal of Init Scripts for more details.
install_initd and remove_initd determine actions to take by decoding a specially formatted block of lines in the script. This block shall be delimited by the lines
<!--# BEGIN INIT INFO --> <!--# END INIT INFO -->
The delimiter lines may contain trailing whitespace, which shall be ignored. All lines inside the block shall begin with a hash character '#' in the first column, so the shell interprets them as comment lines which do not affect operation of the script. The lines shall be of the form:
# {keyword}: arg1 [arg2...]
with exactly one space character between the '#' and the keyword, with a single exception. In lines following a line containing the Description keyword, and until the next keyword or block ending delimiter is seen, a line where the '#' is followed by more than one space or a tab character shall be treated as a continuation of the previous line.
The information extracted from the block is used by the installation tool or the init-script system to assure that init scripts are run in the correct order. It is unspecified whether the information is evaluated only when install_initd runs, when the init scripts are executed, or both. The information extracted includes run levels, defined in Run Levels, and boot facilities, defined in Facility Names.
The following keywords, with their arguments, are defined:
Provides: boot_facility_1 [boot_facility_2...] boot facilities provided by this init script. When an init script 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 init script is run with a stop argument, the boot facilities specified by the Provides keyword are deemed no longer present.
Required-Start: boot_facility_1 [boot_facility_2...] facilities which must be available during startup of this service. The init-script system should insure init scripts which provide the Required-Start facilities are started before starting this script.
Required-Stop: boot_facility_1 [boot_facility_2...] facilities which must be available during the shutdown of this service. The init-script system should avoid stopping init scripts which provide the Required-Stop facilities until this script is stopped.
Should-Start: boot_facility_1 [boot_facility_2...] facilities which, if present, should be available during startup of this service. This allows for weak dependencies which do not cause the service to fail if a facility is not available. The service may provide reduced functionality in this situation. Conforming applications should not rely on the existence of this feature.
Should-Stop: boot_facility_1 [boot_facility_2...] facilities which should be available during shutdown of this service.
Default-Start: run_level_1 [run_level_2...] , Default-Stop: run_level_1 [run_level_2...] which run levels should by default run the init script with a start (stop) argument to start (stop) the services controlled by the init script. For example, if a service should run in runlevels 3, 4, and 5 only, specify "Default-Start: 3 4 5" and "Default-Stop: 0 1 2 6".
Short-Description: short_description provide a brief description of the actions of the init script. Limited to a single line of text.
Description: multiline_description provide a more complete description of the actions of the init script. May span mulitple lines. In a multiline description, each continuation line shall 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.
Additional keywords may be defined in future versions of this specification. Also, implementations may define local extensions by using the prefix X-implementor. For example, X-RedHat-foobardecl, or X-Debian-xyzzydecl.
Example:
<!--# BEGIN INIT INFO --> <!--# END INIT INFO -->
The comment conventions described in this section are only required for init scripts installed by conforming applications. Conforming runtime implementations are not required to use this scheme in their system provided init scripts.
Facility Names
Boot facilities are used to indicate dependencies in initialization scripts, as defined in Comment Conventions for Init Scripts. Facility names are assigned to scripts by the Provides: keyword. Facility names that begin with a dollar sign ('$') are reserved system facility names.
Conforming applications shall not provide facilities that begin with a dollar sign. Implementations shall provide the following 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 by other conforming applications. These facilities shall be named using the same conventions defined for naming init scripts (see Script Names). Commonly, the facility provided by a conforming init script will have the same name as the name assigned to the init script.
Init Script Functions
Each conforming init script shall execute the commands in the file /lib/lsb/init-functions in the current environment (see shell special built-in command dot). This file shall cause the following shell script commands to be defined in an unspecified manner.
Conforming scripts shall not specify the "exit on error" option (i.e. set -e) when sourcing this file, or calling any of the commands thus made available.
The start_daemon, killproc and pidofproc functions shall use the following algorithm for determining the status and the process identifiers of the specified program.
- If the -p pidfile option is specified, and the named pidfile exists, a single line at the start of the pidfile shall be read. If this line contains one or more numeric values, separated by spaces, these values shall be used. If the -p pidfile option is specified and the named pidfile does not exist, the functions shall assume that the daemon is not running.
- Otherwise, /var/run/basename.pid shall be read in a similar fashion. If this contains one or more numeric values on the first line, these values shall be used. Optionally, implementations may use unspecified additional methods to locate the process identifiers required.
The method used to determine the status is implementation defined, but should allow for non-binary programs.
Conforming implementations may use other mechanisms besides those based on pidfiles, unless the -p pidfile option has been used. Conforming applications should not rely on such mechanisms and should always use a pidfile. When a program is stopped, it should delete its pidfile. Multiple process identifiers shall be separated by a single space in the pidfile and in the output of pidofproc.
start_daemon [-f] [-n nicelevel] [-p pidfile] pathname [args...] runs the specified program as a daemon. The start_daemon function shall check if the program is already running using the algorithm given above. If so, it shall not start another copy of the daemon unless the -f option is given. The -n option specifies a nice level. See nice. start_daemon shall return the LSB defined exit status codes. It shall return 0 if the program has been successfully started or is running and not 0 otherwise.
killproc [-p pidfile] pathname [signal] The killproc function shall stop the specified program. The program is found using the algorithm given above. If a signal is specified, using the -signal_name or -signal_number syntaxes as specified by the kill command, the program is sent that signal. Otherwise, a SIGTERM followed by a SIGKILL after an unspecified number of seconds shall be sent. If a program has been terminated, the pidfile should be removed if the terminated process has not already done so. The killproc function shall return the LSB defined exit status codes. If called without a signal, it shall return 0 if the program has been stopped or is not running and not 0 otherwise. If a signal is given, it shall return 0 only if the program is running.
pidofproc [-p pidfile] pathname The pidofproc function shall return one or more process identifiers for a particular daemon using the algorithm given above. Only process identifiers of running processes should be returned. Multiple process identifiers shall be separated by a single space.
The pidofproc function shall return the LSB defined exit status codes for "status". It shall return 0 if the program is running and not 0 otherwise.
log_success_msg message The log_success_msg function shall cause the system to write a success message to an unspecified log file. The format of the message is unspecified. The log_success_msg function may also write a message to the standard output.
log_failure_msg message The log_failure_msg function shall cause the system to write a failure message to an unspecified log file. The format of the message is unspecified. The log_failure_msg function may also write a message to the standard output.
log_warning_msg message The log_warning_msg function shall cause the system to write a warning message to an unspecified log file. The format of the message is unspecified. The log_warning_msg function may also write a message to the standard output.
See also
Fedora New Init System [[Navigation(siblings)]