Comment conventions for init scripts

LSB applications which need to execute script(s) at bootup and/or shutdown may provide one or more init.d files. These files are installed by the install_initd program described below, which copies it into a standard directory and makes whatever other adjustments (creation of symlinks, creation of entries in a database, etc.) are necessary so that the script can be run at boot-time. [1]

In the init.d file, information about the shell script shall be delimited by the lines "### BEGIN INIT INFO" and "### END INIT INFO". These delimiter lines may containg trailing whitespace, which shall be ignored. Inside this block there shall be lines of the form "# {keyword}: [arg1] [arg2] ...". (All lines inside this block start with a hash ('#') character in the first column, so that shell treats them as comments.) There must be exactly one space character between "#" and the keyword.[2] The following keywords, with their arguments are defined in this specification:

	# Provides: boot_facility_1 [ boot_facility_2 ...]
	# Required-Start: boot_facility_1 [ boot_facility_2 ...]
	# Required-Stop: boot_facility_1 [ boot_facility_2 ...]
	# Default-Start: run_level_1 [ run_level_2 ...]
	# Default-Stop: run_level_1 [ run_level_2 ...]
	# Short-Description: short_description
	# Description: multiline_description

Additional keywords may be defined in future LSB specifications. Distributions may define local extensions by using the prefix "X-[distribution name]" --- for example, "X-RedHat-foobardecl", or "X-Debian-xyzzydecl".

An init.d shell script may declare using the "Required-Start: " header that it must not be run until certain boot facilities are provided. This information is used by the installation tool or the boot-time boot-script execution facility to assure that init scripts are run in the correct order. When an init script is run with a "start" argument, the boot facility or facilities specified in the "Provides" header shall be considered present, and hence init scripts which require those boot facilities would then be eligble to be run. When an init script is run with a "stop" argument, the boot facilities specified in the "Provides" header are considered no longer present. There are naming conventions for boot facilities and system facilities, as described in a following section.

Similarly, the "Required-Stop:" header defines which facilities must still be available during the shutdown of that service. Hence, the init script system should avoid stopping shell scripts which provide those facilities until this shell script is stopped.

The "Default-Start" and "Default-Stop" headers define which run levels should by default run the script with a start or stop argument, respectively, to start or stop the services controlled by the init script.

The "Short-Description" and "Description" header fields are used to provide text which describes the actions of the init script. The "short_description" shall be a relatively short, pithy description of the init script, where as the "multiline_description" can be a much longer piece of text that may span mulitple lines. In a multiline description, 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.

The comment conventions described in this session are only required for use by LSB-compliant applications; system init scripts as provided by LSB-compliant run-time environments are not required to use the scheme outlined here. [3]

Notes

[1]

This specification does not require, but is designed to allow, the development of a system which runs boot scripts in parallel. Hence, enforced-serialization of scripts is avoided unless it is explicitly necessary.

[2]

More than one space, or a tab character, indicates the continuation line.

[3]

While these comment conventions do not prohibited in system init scripts, they do not provide sufficient functionality for most distributions' needs. Extensions which would addressed these needs (for example, "Should-Start:" and "Should-Stop:") would have substantially complicated the design of the install_initd script, which is why they were not included in this specification. Future versions of this specification may extend these comment conventions to add this functionality, if and when reference implementations which implement these extensions become available for use by distributions.