Differences between revisions 14 and 59 (spanning 45 versions)
Revision 14 as of 2006-07-24 10:35:06
Size: 9226
Editor: ZugSchlus
Comment: add question about exit status code, link to #208010
Revision 59 as of 2019-08-17 11:14:36
Size: 11325
Editor: GuillemJover
Comment: Fix typo
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## Auto-converted by kwiki2moinmoin v2005-10-07 #language en
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~
----
Line 3: Line 5:
This is a short documentation about how to make an Init Script LSB-compliant based on the [http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/tocsysinit.html [Chapter 20 of the LSB 3.1]].
'''Note: Debian discontinued LSB support in 2015, see [[DebianLsb]] and for example [[https://lwn.net/Articles/658809/|lwn.net: Debian dropping the Linux Standard Base]].''' This does not affect the Debian requirement to include LSB style dependency information in the init.d scripts used by non-systemd installations.

A [[LSBInitScripts/DependencyBasedBoot|status page]] for dependency based boot sequencing is
available.


This is a short documentation about how to make an Init Script LSB (Linux Standard Base)-compliant based on the [[http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/tocsysinit.html|Chapter 20 of the LSB 3.1]].
Line 6: Line 16:
 * provide, at least, the following actions: start, stop, restart, force-reload, and status. All of those, except for, status, are required by the [http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.3.2 Debian Policy, chapter 9.3.2 Writing the scripts]. "Status" support has been requested into policy, see [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=291148 #291148].  * provide, at least, the following actions: start, stop, restart, force-reload, and status. All of those, except for status, are required by the [[http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.3.2|Debian Policy, chapter 9.3.2 Writing the scripts]]. "Status" support has been requested into policy, see [[DebianBug:291148|#291148]] and [[LSBInitScripts/StatusSupport]].
Line 10: Line 20:
 * [optionally] Log messages using the Init.d functions: log_success_msg, log_failure_msg and log_warning_msg (This would introduce consistent output in scripts, as requested in [http://lists.debian.org/debian-devel/2005/06/msg00729.html]  * [optionally] Log messages using the Init.d functions: log_success_msg, log_failure_msg and log_warning_msg (This would introduce consistent output in scripts, as requested in [[http://lists.debian.org/debian-devel/2005/06/msg00729.html]]
Line 12: Line 22:
[http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.4 Debian Policy, chapter 9.4 Console messages from init.d scripts]) [[http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.4|Debian Policy, chapter 9.4 Console messages from init.d scripts]])
Line 14: Line 24:
Full informantion on the actions (and return codes) that LSB scripts have to honor Full information on the actions (and return codes) that LSB scripts have to honor
Line 16: Line 26:
[http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html        LSB 3.1, Chapter 20.2. Init Script Actions]. Maintainers should review that section and review / adjust their init.d scripts accordingly. [[http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html|LSB 3.1, Chapter 20.2. Init Script Actions]]. Maintainers should review that section and review / adjust their init.d scripts accordingly.
Line 20: Line 30:
By documenting the run-time dependencies for init.d scripts, it becomes
possible to verify the current boot order, and also to run boot scripts in
parallel to speed up the boot process (This is on the [http://wiki.debian.org/EtchTODOList TODO list for Etch])
Adding run-time dependencies was a release goal for Lenny, and dependency based boot sequencing is the default in Squeeze. There is [[LSBInitScripts/DependencyBasedBoot|a separate wiki page]] documenting that effort.
Line 24: Line 32:
By documenting the run-time dependencies for init.d scripts, it becomes possible to verify the current boot order, order the boot using these dependencies, and run boot scripts in parallel to speed up the boot process.
Line 25: Line 34:


Add a block like this in the init.d script (example based on xdebconfigurator):
Add a block like this in the init.d script:
Line 30: Line 37:
# Provides: xdebconfigurator
# Required-Start: $syslog
# Required-Stop: $syslog
# Should-Start: $local_fs
# Should-Stop: $local_fs
# Provides: scriptname
# Required-Start:  $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
Line 37: Line 42:
# Short-Description: Generate xfree86 configuration at boot time
# Description: Preseed X configuration and use dexconf to
# generate a new configuration file.
# Short-Description: Start daemon at boot time
# Description: Enable service provided by daemon.
Line 43: Line 47:
The block show above has a special rigid format delimited by the lines The block shown above has a special rigid format delimited by the lines
Line 50: Line 54:
where all traling spaces shall be ignored. On the other hand, all lines inside the block shall of the form where all trailing spaces shall be ignored. On the other hand, all lines inside the block shall be of the form
Line 62: Line 66:
    will be started at a later stage. Normally you can use the script name as boot facility but you can also use the name of the
    service(s) that the script replaces. Besides, consider using virtual facility names as described below if the script
    provides one or more of them.
    must be started at a later stage. Normally you should use the script name as boot facility (without .sh if the file name has such an ending) but one can in the exceptional case also use the name of the
    service(s) that the script replaces. Boot facilities provided by scripts must not start with '$'. (Virtual facility names listed below are defined outside the init.d scripts.) Facility names should be unique within the distribution, to avoid 'duplicate provides' errors when a package is installed.
Line 75: Line 78:
   defines facilites used by the service provided by the script. The facility provided by this script should stop before the listed facilities are stopped to avoid conflicts. Normally you would include here the same facilites as for the Required-Start keyword.    defines facilities used by the service provided by the script. The facility provided by this script should stop before the listed facilities are stopped to avoid conflicts. Normally you would include here the same facilities as for the Required-Start keyword.
Line 84: Line 87:
    defines the facilities that if present should be stopped after this service. Normally you would include here the same facilites as those used with the Should-Start keyword.     defines the facilities that if present should be stopped after this service. Normally you would include here the same facilities as those used with the Should-Start keyword.
Line 87: Line 90:
'''Default-Start: run_level_1 [run_level_2...],Default-Stop: run_level_1 [run_level_2...]''' '''Default-Start: run_level_1 [run_level_2...]'''

'''
Default-Stop: run_level_1 [run_level_2...]'''
Line 99: Line 104:
For dependency tracking, the provides, required- and should- keywords are important, and the rest is unused. The default runlevels are used by a program to order the init scripts (e.g. insserv) to keep track of which rc#.d directory to update when a service is added for the first time, and should reflect the intent of the service. '''X-Start-Before: boot_facility_1 [boot_facility_2...]'''

'''X-Stop-After: boot_facility_1 [boot_facility_2...]'''

    provide reverse dependencies, that appear as if the listed facilities had should-start and should-stop on the package with these headers.

'''X-Interactive: true'''

    Indicates that this init script can interact with the user, requesting some input (for example, a password). This make sure the script run alone when the boot system starts scripts in parallell and have direct access to the tty.


For dependency tracking, the provides, required- and should- keywords are important, and the rest is unused. The default runlevels are used by a program to order the init scripts (e.g. {{{insserv}}}) to keep track of which rc#.d directory to update when a service is added for the first time, and should reflect the intent of the service.
Line 102: Line 118:
[http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html [LSB 3.1]]. [[http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html|[LSB 3.1]]].
Line 105: Line 121:
|| $local_fs || all local filesystems are mounted || || $local_fs || all local filesystems are mounted. All scripts that write in /var/ need to depend on this, unless they already depend on $remote_fs. ||
Line 108: Line 124:
|| $portmap || daemons providing ["SunRPC"]/ONCRPC portmapping service as defined in RFC 1833 (if present) are running all remote ||
|| $remote_fs || filesystems are mounted. In some LSB run-time environments, filesystems such as /usr may be remote. Many applications that require $local_fs will probably require also require $remote_fs. ||
|| $portmap || daemons providing [[SunRPC]]/ONCRPC portmapping service as defined in RFC 1833 (if present) are running all remote ||
|| $remote_fs || all filesystems are mounted. In some LSB run-time environments, filesystems such as /usr may be remote. If the script need a mounted /usr/, it needs to depend on $remote_fs. Scripts depending on $remote_fs do not need to depend on $local_fs. During shutdown, scripts that need to run before sendsigs kills all processes should depend on $remote_fs. ||
Line 111: Line 127:
|| $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. ||
|| $all || facility supported by insserv to start a script after all the other scripts, at the end of the boot sequence. ||
|| $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. Note that just depending on ntp will not result in an accurate time just after ntp started. It usually takes minutes until ntp actually adjusts the time. Also note that standard insserv.conf just lists hwclock as $time. ||
|| $all || facility supported by {{{insserv}}} to start a script after all the scripts not depending on $all, at the end of the boot sequence.  This only work for start ordering, not stop ordering. Depending on a script depending on $all will give incorrect ordering, as the script depending on $all will be started after the script depending on it. ||
Line 114: Line 130:
Other (non-system) facilities may be defined by other applications. These facilities shall be named using the same [http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/etc.html#FHS-NAME-RULES conventions defined for naming init scripts]. Other (non-system) facilities may be defined by other applications. These facilities shall be named using the same [[http://refspecs.linuxfoundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/etc.html#FHS-NAME-RULES|conventions defined for naming init scripts]]. See [[LSBInitScripts/DebianVirtualFacilities|the list of proposed Debian specific virtual facilities]] for more information on this.
Line 117: Line 133:
Most of this section was originally based from a [http://lists.debian.org/debian-devel/2005/08/msg01172.html message by Petter Reinholdtsen] on [http://lists.debian.org/debian-devel Debian-devel]. Most of this section was originally based from a [[http://lists.debian.org/debian-devel/2005/08/msg01172.html|message by Petter Reinholdtsen]] on [[http://lists.debian.org/debian-devel|Debian-devel]].

BTS reports related to LSB headers are [[http://bugs.debian.org/cgi-bin/pkgreport.cgi?usertag=initscripts-ng-devel@lists.alioth.debian.org|usertagged]].
Line 123: Line 141:
Question: Is it possible to start a given init script as late as possible?  Is it possible to start a given init script as late as possible? :: yes, if you really want to do so, {{{insserv}}} recognises the $all virtual facility name such that the script will be executed at the end.
Line 125: Line 143:
Answer: yes, if you really want to do so, insserv recognises the $all
virtual facility name such that the script will be executed at the end.
 Is it possible to add extra keywords? :: If there is no current keyword you could use for your needs, the LSB allows for local extensions using the prefix X-. For example, X-Debian-foobardecl or X-Ubuntu-fastdecl.
Line 128: Line 145:
Question: Is it possible to add extra keywords?  Is it possible to specify that a given script should start before another script? :: There is no such standard-defined header, but there is a proposed extention implemented in the {{{insserv}}} package (since version 1.09.0-8). Use the X-Start-Before and X-Stop-After headers proposed by SuSe.
Line 130: Line 147:
Answer: If there is no current keyword you could use for your needs, the
LSB allows for local extensions using the prefix X-. For example,
X-Debian-foobardecl or X-Ubuntu-fastdecl.
 Shouldn't I wait until the Debian policy changes? :: The Debian policy changes are slow to introduce even for things (for an example, see [[DebianBug:291148|#291148]]) which most maintainers agree are good since we have to wait first for many packages to do things in the same way before turning it into policy. Since we want to be LSB compliant, init.d scripts can be adjusted '''now''' to be LSB compliant.
Line 134: Line 149:
Question: Is it possible to specify that a given script should start before
another script?
 What is a "proper" exit status code? :: Looking at [[DebianBug:208010|#208010,]] this seems rather controversial. Non-zero exit codes might even cause breakage, and the LSB conflicts with Debian policy here.
Line 137: Line 151:
Answer: There is no such standard-defined header. The LSB approach
would be to get the second script to include your given script in its
Required-Start arguments. Besides, we could define a debian specific
extention to express this, but there is no implementation using
such header, so we would have to implement it ourselves.

Question: Shouldn't I wait until the Debian policy changes?

The Debian policy changes are slow to introduce even for things (for an example, see
[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=291148 #291148]) which most
maintainers agree are good since we have to wait first for many packages to do things in the same way before turning it into policy. Since we want to be LSB compliant, init.d scripts can be adjusted '''now''' to be LSB compliant.

Question: What is a "proper" exit status code? Looking at [http://bugs.debian.org/208010/ #208010,] this seems rather controversial. Non-zero exit codes might even cause breakage, and the LSB conflicts with Debian policy here.
----
CategoryBootProcess

Translation(s): none


How to LSBize an Init Script

Note: Debian discontinued LSB support in 2015, see DebianLsb and for example lwn.net: Debian dropping the Linux Standard Base. This does not affect the Debian requirement to include LSB style dependency information in the init.d scripts used by non-systemd installations.

A status page for dependency based boot sequencing is available.

This is a short documentation about how to make an Init Script LSB (Linux Standard Base)-compliant based on the Chapter 20 of the LSB 3.1.

LSB-compliant init scripts need to:

and should also follow Debian Policy, chapter 9.4 Console messages from init.d scripts)

Full information on the actions (and return codes) that LSB scripts have to honor are available at LSB 3.1, Chapter 20.2. Init Script Actions. Maintainers should review that section and review / adjust their init.d scripts accordingly.

Run-time dependencies

Adding run-time dependencies was a release goal for Lenny, and dependency based boot sequencing is the default in Squeeze. There is a separate wiki page documenting that effort.

By documenting the run-time dependencies for init.d scripts, it becomes possible to verify the current boot order, order the boot using these dependencies, and run boot scripts in parallel to speed up the boot process.

Add a block like this in the init.d script:

### BEGIN INIT INFO
# Provides:          scriptname
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start daemon at boot time
# Description:       Enable service provided by daemon.
### END INIT INFO

The block shown above has a special rigid format delimited by the lines

### BEGIN INIT INFO
### END INIT INFO

where all trailing spaces shall be ignored. On the other hand, all lines inside the block shall be of the form

# {keyword}: arg1 [arg2...]

and begin with a hash character '#' in the first column followed by one single space, except for the lines following the Description keyword. The following keywords are defined

Provides: boot_facility_1 [boot_facility_2...]

  • defines boot facilities provided by this init script such that when the script is run with the start argument, the specified boot facilities will be deemed present and hence other init scripts which require those boot facilities must be started at a later stage. Normally you should use the script name as boot facility (without .sh if the file name has such an ending) but one can in the exceptional case also use the name of the service(s) that the script replaces. Boot facilities provided by scripts must not start with '$'. (Virtual facility names listed below are defined outside the init.d scripts.) Facility names should be unique within the distribution, to avoid 'duplicate provides' errors when a package is installed.

Required-Start: boot_facility_1 [boot_facility_2...]

  • defines facilities that must be available to start the script. Consider using virtual facility names as described below if adequate. If no boot facility is specified it means that this script can be started just after the bootstrap without local filesystems mounted, nor system logger, etc.

Required-Stop: boot_facility_1 [boot_facility_2...]

  • defines facilities used by the service provided by the script. The facility provided by this script should stop before the listed facilities are stopped to avoid conflicts. Normally you would include here the same facilities as for the Required-Start keyword.

Should-Start: boot_facility_1 [boot_facility_2...]

  • defines the facilities that if present should start before the service provided by the script. Nevertheless, the script can still start if the listed facilities are missing. This allows for weak dependencies which do not cause the service to fail if a facility is not available. Consider using virtual facility names as described below if adequate.

Should-Stop: boot_facility_1 [boot_facility_2...]

  • defines the facilities that if present should be stopped after this service. Normally you would include here the same facilities as those used with the Should-Start keyword.

Default-Start: run_level_1 [run_level_2...]

Default-Stop: run_level_1 [run_level_2...]

  • defines the run levels where the script should be started (stopped) by default. 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 multiple 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.

X-Start-Before: boot_facility_1 [boot_facility_2...]

X-Stop-After: boot_facility_1 [boot_facility_2...]

  • provide reverse dependencies, that appear as if the listed facilities had should-start and should-stop on the package with these headers.

X-Interactive: true

  • Indicates that this init script can interact with the user, requesting some input (for example, a password). This make sure the script run alone when the boot system starts scripts in parallell and have direct access to the tty.

For dependency tracking, the provides, required- and should- keywords are important, and the rest is unused. The default runlevels are used by a program to order the init scripts (e.g. insserv) to keep track of which rc#.d directory to update when a service is added for the first time, and should reflect the intent of the service.

There are some "virtual" facility names, listed in the [LSB 3.1]. These are:

$local_fs

all local filesystems are mounted. All scripts that write in /var/ need to depend on this, unless they already depend on $remote_fs.

$network

low level networking (ethernet card; may imply PCMCIA running)

$named

daemons which may provide hostname resolution (if present) are running. For example, daemons to query DNS, NIS+, or LDAP.

$portmap

daemons providing ?SunRPC/ONCRPC portmapping service as defined in RFC 1833 (if present) are running all remote

$remote_fs

all filesystems are mounted. In some LSB run-time environments, filesystems such as /usr may be remote. If the script need a mounted /usr/, it needs to depend on $remote_fs. Scripts depending on $remote_fs do not need to depend on $local_fs. During shutdown, scripts that need to run before sendsigs kills all processes should depend on $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. Note that just depending on ntp will not result in an accurate time just after ntp started. It usually takes minutes until ntp actually adjusts the time. Also note that standard insserv.conf just lists hwclock as $time.

$all

facility supported by insserv to start a script after all the scripts not depending on $all, at the end of the boot sequence. This only work for start ordering, not stop ordering. Depending on a script depending on $all will give incorrect ordering, as the script depending on $all will be started after the script depending on it.

Other (non-system) facilities may be defined by other applications. These facilities shall be named using the same conventions defined for naming init scripts. See the list of proposed Debian specific virtual facilities for more information on this.

Most of this section was originally based from a message by Petter Reinholdtsen on Debian-devel.

BTS reports related to LSB headers are usertagged.


Frequent questions

Is it possible to start a given init script as late as possible?

yes, if you really want to do so, insserv recognises the $all virtual facility name such that the script will be executed at the end.

Is it possible to add extra keywords?
If there is no current keyword you could use for your needs, the LSB allows for local extensions using the prefix X-. For example, X-Debian-foobardecl or X-Ubuntu-fastdecl.
Is it possible to specify that a given script should start before another script?

There is no such standard-defined header, but there is a proposed extention implemented in the insserv package (since version 1.09.0-8). Use the X-Start-Before and X-Stop-After headers proposed by ?SuSe.

Shouldn't I wait until the Debian policy changes?

The Debian policy changes are slow to introduce even for things (for an example, see #291148) which most maintainers agree are good since we have to wait first for many packages to do things in the same way before turning it into policy. Since we want to be LSB compliant, init.d scripts can be adjusted now to be LSB compliant.

What is a "proper" exit status code?

Looking at #208010, this seems rather controversial. Non-zero exit codes might even cause breakage, and the LSB conflicts with Debian policy here.


CategoryBootProcess