Differences between revisions 11 and 12
Revision 11 as of 2006-07-08 11:03:38
Size: 6916
Editor: ?CarlosVillegas
Comment:
Revision 12 as of 2006-07-08 13:31:23
Size: 8864
Editor: ?CarlosVillegas
Comment:
Deletions are marked like this. Additions are marked like this.
Line 24: Line 24:
Most of this page has been pulled 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].
Line 55: Line 55:
and begin with a hash character '#' in the first column, except for the lines following the Description keyword. The following keywords are defined 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
Line 62: Line 62:
    will be started at a later stage. Normally you can use the script name as boot facility but also use the name of the
    service(s) that the script replaces.
    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.
Line 66: Line 67:
'''Required-Start: boot_facility_1 [boot_facility_2...],Required-Stop: boot_facility_1 [boot_facility_2...]''' '''Required-Start: boot_facility_1 [boot_facility_2...]''' 
Line 68: Line 69:
    defines services needed to start this service. These services must start before this service. Required-Stop are
    services used by this service, and this service should stop before the listed services are stopped.
    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.
Line 71: Line 73:
'''Should-Start: boot_facility_1 [boot_facility_2...],Should-Stop: boot_facility_1 [boot_facility_2...]''' '''Required-Stop: boot_facility_1 [boot_facility_2...]'''
Line 73: Line 75:
    defines the services that if present should start before this service, but this service can start if the listed
    services are missing. Should-Stop are services that if present should be stopped after this service.
   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.
Line 76: Line 77:
''''Default-Start: run_level_1 [run_level_2...],Default-Stop: run_level_1 [run_level_2...]'''
Line 78: Line 78:
    Default-Start is the run levels where this service should be started by default, and Default-Stop is the run levels
    where this service should be stopped by default.
'''Should-Start: boot_facility_1 [boot_facility_2...]'''
Line 81: Line 80:
'''Short-Description: short_description, Description: multiline_description'''     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.
Line 83: Line 82:
    Description and short-description are fairly obvious. '''Should-Stop: boot_facility_1 [boot_facility_2...]'''
Line 85: Line 84:
For dependency tracking, the required-''' and should-''' are important, and the rest is unused. The default runlevels are used by 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.     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.
Line 87: Line 86:
There are some "virtual"/system service names, listed in the
[http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/facilname.html [LSB 3.0]].

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

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
[http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html [LSB 3.1]].
Line 99: Line 113:
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].


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].
Line 105: Line 124:
Answer: There is header specified in the LSB allowing this to be expressed.
It is allowed to add extra (X-) headers, so we could add this expression if
needed.
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.

Question: Is it possible to add extra keywords?

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.
Line 112: Line 136:
Answer: There is no such standard-defined header.  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 ourself.
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, w
e 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. 
Line 120: Line 146:
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. 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.

How to LSBize an Init Script

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]]. LSB-compliant init scripts need to:

and should also follow [http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.4 Debian Policy, chapter 9.4 Console messages from init.d scripts])

Full informantion on the actions (and return codes) that LSB scripts have to honor are available at [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.

Run-time dependencies

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])

Add a block like this in the init.d script (example based on xdebconfigurator):

### BEGIN INIT INFO
# Provides:          xdebconfigurator
# Required-Start:    $syslog
# Required-Stop:     $syslog
# Should-Start:      $local_fs
# Should-Stop:       $local_fs
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Generate xfree86 configuration at boot time
# Description:       Preseed X configuration and use dexconf to
#                    generate a new configuration file.
### END INIT INFO

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

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

where all traling spaces shall be ignored. On the other hand, all lines inside the block shall 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 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.

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

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

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 [http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html [LSB 3.1]]. These are:

$local_fs

all local filesystems are mounted

$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

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.

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

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


Frequent questions

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

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.

Question: Is it possible to add extra keywords?

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.

Question: Is it possible to specify that a given script should start before another script?

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.