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

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

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 shall be exactly one space character between "#" and the keyword.

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

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 ...]
	# Should-Start: boot_facility_1 [ boot_facility_2 ...]
	# Should-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 shall 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 shall 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 "Should-Start:" header defines which facilities if present should be started before this service. This allows for weak dependencies which do not cause the service to fail if a facility is not available. But may cause reduced functionality of the service. Compliant applications should not rely on the existence of this feature.

The "Should-Stop:" header defines which facilities should be still available during the shutdown of that service.

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.

Note: For example, if you want a service to run in runlevels 3, 4, and 5 (only), specify "Default-Start: 3 4 5" and "Default-Stop: 0 1 2 6".

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

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.