diff --git a/policy.sgml b/policy.sgml index 6eac491..574a8ca 100644 --- a/policy.sgml +++ b/policy.sgml @@ -7362,389 +7362,537 @@ rmdir /usr/local/share/emacs 2>/dev/null || true - - System run levels and init.d scripts + + Init systems + +

+ The default init system in Debian with Linux kernels is systemd, run when + systemd-sysv is installed. + A number of other init systems are available in Debian, including + in particular System V init, run when sysvinit-core + is installed (and also the default for non-Linux kernels). + Both of these packages provide the init + metapackage. +

- - Introduction +

+ Packages must integrate with the default init system and may integrate + with others as well. + + +

+ To integrate with systemd, packages provide so-called unit files + (described at ) or init.d scripts. +

+ + +

+ To integrate with upstart, packages provide so-called job files + (described at ) or init.d scripts. +

+ + +

+ To integrate with System V init, packages provide init.d + scripts (described at ). +

+ + +

+ Integration with other init systems in Debian, most of which do not + use init.d scripts, is not covered here; and Debian + Policy has no interface or usage contracts for those init systems. +

+ + + These files provide init-system-specific information about how and when to + run services, about boot-time and shutdown-time "milestones" or "targets", + and about tasks that run as part of the boot-up or shutdown procedures. + For packages that do not require any of these things, integration is + a no-op, of course. +

+ +

+ The least common denominator of these are the init.d + scripts. + systemd places restrictions upon them, forbidding some of the more esoteric + possible mechanisms that System V init historically allowed. + However, a script that is compliant with this Policy should be + usable with systemd. Many of the things that systemd prohibits are + inherently problematic, irrespective of systemd. +

+ +

+ Packages should use the same names for files across different init systems. + However, this is not always possible. For example, an init.d + script can start and manage several services, whereas one would have + individual systemd unit files for each of the individual services (and + possibly more unit files for sockets if the services are socket-activated). + Similarly, packages may be constrained by what upstream does. + It is recommended that packages adopt the same names, though; not the least + because this enables a package to take advantage of the fact that a systemd + unit file that shares a name with a init.d script will be used + in preference to that script. Note that the Alias= setting + in systemd unit files can be used to alleviate some problematic cases. +

+ + + systemd unit files

- The /etc/init.d directory contains the scripts - executed by init at boot time and when the - init state (or "runlevel") is changed (see ). + The /usr/lib/systemd/system directory contains (package-supplied) + systemd unit files that define systemd-managed services, sockets, + mount points, automount entries, and other items. + Administrators do not make local modifications to these files.

-

- There are at least two different, yet functionally - equivalent, ways of handling these scripts. For the sake - of simplicity, this document describes only the symbolic - link method. However, it must not be assumed by maintainer - scripts that this method is being used, and any automated - manipulation of the various runlevel behaviors by - maintainer scripts must be performed using - update-rc.d as described below and not by - manually installing or removing symlinks. For information - on the implementation details of the other method, - implemented in the file-rc package, please refer - to the documentation of that package. +

+ Instead, local modifications made by administrators take the form of files + in the /etc/systemd/system directory, which override + package-supplied units entirely, and files in *.conf + subdirectories of that directory, which override parts of the package-supplied + units. (See .) + Conversely, packages must not make modifications to these files.

-

- These scripts are referenced by symbolic links in the - /etc/rcn.d directories. When changing - runlevels, init looks in the directory - /etc/rcn.d for the scripts it should - execute, where n is the runlevel that - is being changed to, or S for the boot-up +

+ A limited exception to this rule is that packages are permitted to make + once-off conversions, during an upgrade, from information in a + /etc/defaults/package file to systemd unit + override snippets in /etc/systemd/system/*/*.conf + files. + This has the disadvantage of creating two separate and not + synchronized sets of administrator-defined service parameterization + information, one for systemd units and one for init.d scripts. +

-

- The names of the links all have the form - Smmscript or - Kmmscript where - mm is a two-digit number and script - is the name of the script (this should be the same as the - name of the actual script in /etc/init.d). +

+ The requirements of apply to unit files under + /run/systemd of course.

-

- When init changes runlevel first the targets - of the links whose names start with a K are - executed, each with the single argument stop, - followed by the scripts prefixed with an S, each - with the single argument start. (The links are - those in the /etc/rcn.d directory - corresponding to the new runlevel.) The K links - are responsible for killing services and the S - link for starting services upon entering the runlevel. -

- -

- For example, if we are changing from runlevel 2 to - runlevel 3, init will first execute all of the K - prefixed scripts it finds in /etc/rc3.d, and then - all of the S prefixed scripts in that directory. - The links starting with K will cause the - referred-to file to be executed with an argument of - stop, and the S links with an argument - of start. -

- -

- The two-digit number mm is used to determine - the order in which to run the scripts: low-numbered links - have their scripts run first. For example, the - K20 scripts will be executed before the - K30 scripts. This is used when a certain service - must be started before another. For example, the name - server bind might need to be started before - the news server inn so that inn - can set up its access lists. In this case, the script - that starts bind would have a lower number - than the script that starts inn so that it - runs first: - -/etc/rc2.d/S17bind -/etc/rc2.d/S70inn - +

+ For details of unit files please consult the man pages + , + , + , + , + and + . +

+ + + constraints upon unit files + +

+ + +

+ The Type= setting in a service unit file describes the readiness + notification mechanism employed by the daemon. + Readiness protocols are a communication mechanism between daemons and + systemd that allow systemd to delay starting client processes until a server + process is ready to service their requests. systemd supports several such + protocols. + fork()ing at startup and then exit()ing the main process + is one such readiness protocol, denoted by Type=forking. + Unit files should not use this unless the daemon is genuinely using this as + a readiness signal and main process exit() is genuinely a readiness + notification. + Most daemons are not in fact signalling readiness with this. + Rather, they are operating in a convenience mode used when daemons are run from an + /etc/rc script. No Debian init system uses the + /etc/rc mechanism. Such daemons should be run with whatever + configuration options or command-line options instruct them not to + gratuitously fork(); and the service unit files should use a more + appropriate Type= setting that denotes the readiness protocol that + they actually employ, if any. +

+ + +

+ Service unit files must not (directly or indirectly) run commands to mask, unmask, + enable, disable, start, or stop either themselves or other services in their + Exec...= settings. + Such actions must rather be properly expressed with dependency descriptions. +

+

+ Services also must not (directly or indirectly) invoke other init.d + scripts in their Exec...= settings, as this can cause incorrect + init system operation. + (See for one way that this can cause service + control commands to be indirectly executed.) + If an init.d script provides additional verbs, that functionality + must be factored out of the script and placed elsewhere before it can be used + by a service unit file. +

+ + +

+ Unit files must not install to specific run level () targets, + because their meanings are the province of local administrators; + but must instead use the standard targets such as multi-user.target and + graphical.target. +

+ + +

+ + + + recommendations for unit files + +

+ + +

+ Restart=always should be avoided for socket-activated services, + as it prevents them from being able to deactivate when idle. + For such services, prefer Restart=on-failure or Restart=on-abort. +

+ + +

+ Sockets and their associated services can be started and stopped independently. + When upgrading a package, it is important to account for this in maintainer + scripts, and if appropriate stop both. + Otherwise, a client connecting to the socket could cause systemd to on-demand + activate the service right at the point of the maintainer script where the service + is deactivated for upgrading and in an intermediate state where it is not correctly + configured for running. +

+

+ The same consideration applies to D-Bus activated services. +

+

+ Please note that the update-rc.d and invoke-rc.d + in the sysv-rc package (See .) + only operate upon service units and not on the associated socket units. +

+ + +

+ Service units should, whereever the daemons do not require privileged access, + run services as an unprivileged user and group. + Optimally, that user should not own any files and directories to which + the daemon does not strictly need ownership access.In other words, + the user should not be able to change any access permissions except where + that is a part of the daemon's function. This means not running services + with the accounts of real, human, users, of course. + Maintainer scripts should of course add and delete any such users and groups + that are specific to the package, at package installation and removal. +

+ + +

+ + + + + + non-unit systemd-related package files + +

+ Packages can ship additional items for systemd, including tmpfiles.d + files, sysctl.d files, and binfmt.d files amonst others. + Packages must not ship any such files under /etc, nor may they make any + modifications to such files under /etc. + The files in that subtree are the province of the local system administrator. + All such files must be shipped in the appropriate subdirectories of /usr/lib.

- The two runlevels 0 (halt) and 6 (reboot) are slightly - different. In these runlevels, the links with an - S prefix are still called after those with a - K prefix, but they too are called with the single - argument stop. + These or work-alike mechanisms may not be available with other init systems. + However, Policy does not exclude packages from using, and depending upon, a + (hypothetical example) upstart-tmpfilesd for achieving the + same ends when integrated with the upstart init system.

+ - - Writing the scripts + + upstart job files

- Packages that include daemons for system services should - place scripts in /etc/init.d to start or stop - services at boot time or during a change of runlevel. - These scripts should be named - /etc/init.d/package, and they should - accept one argument, saying what to do: + The /etc/init directory contains job files used by the + the upstart init system. +

- - start - start the service, +

+ Dependency-based boot managers for init.d scripts, such as + startpar, may avoid running a given script + entirely when an equivalent upstart job is present, to avoid + unnecessary forking of no-op init scripts. In this case, the + boot manager should integrate with upstart to detect when the + upstart job in question is started or stopped to know when the + dependency has been satisfied. +

+ +

+ Other interactions between init.d scripts and upstart are described at + . +

+ - stop - stop the service, + + runlevels and /etc/inittab - restart - stop and restart the service if it's already running, - otherwise start the service +

+ System V init's configuration file is /etc/inittab, which + describes a set of "runlevels" and the default runlevel that the system + boots into. + systemd has a mechanism that emulates System V init runlevels, but no init + system other than Systemm V init uses or supplies the /etc/inittab + file itself. In order to operate correctly with the (Linux) default and indeed + all but one of the init systems, packages must not use + /etc/inittab. +

- reload -

cause the configuration of the service to be - reloaded without actually stopping and restarting - the service, +

+ Maintainer scripts may not assume that a distinct current run level can be + determined; because this is not necessarily the case with the default + init system. + In general, maintainer scripts should avoid any mention of run levels at all. + + update-rc.d no longer has the ability to explicitly configure + run levels on the command line. They must instead be part of the LSB Header + in an init.d script (). + +

+ - force-reload - cause the configuration to be reloaded if the - service supports this, otherwise restart the - service. - + + BSD-style rc: rc.boot and rc.local - The start, stop, restart, and - force-reload options should be supported by all - scripts in /etc/init.d, the reload - option is optional. -

- -

- The init.d scripts must ensure that they will - behave sensibly (i.e., returning success and not starting - multiple copies of a service) if invoked with start - when the service is already running, or with stop - when it isn't, and that they don't kill unfortunately-named - user processes. The best way to achieve this is usually to - use start-stop-daemon with the --oknodo - option. -

- -

- Be careful of using set -e in init.d - scripts. Writing correct init.d scripts requires - accepting various error exit statuses when daemons are already - running or already stopped without aborting - the init.d script, and common init.d - function libraries are not safe to call with set -e - in effect - /lib/lsb/init-functions, which assists in writing - LSB-compliant init scripts, may fail if set -e is - in effect and echoing status messages to the console fails, - for example. - . For init.d scripts, it's often easier - to not use set -e and instead check the result of - each command separately. -

- -

- If a service reloads its configuration automatically (as - in the case of cron, for example), the - reload option of the init.d script - should behave as if the configuration has been reloaded - successfully. -

- -

- The /etc/init.d scripts must be treated as - configuration files, either (if they are present in the - package, that is, in the .deb file) by marking them as - conffiles, or, (if they do not exist in the .deb) - by managing them correctly in the maintainer scripts (see - ). This is important since we want - to give the local system administrator the chance to adapt - the scripts to the local system, e.g., to disable a - service without de-installing the package, or to specify - some special command line options when starting a service, - while making sure their changes aren't lost during the next - package upgrade. -

- -

- These scripts should not fail obscurely when the - configuration files remain but the package has been - removed, as configuration files remain on the system after - the package has been removed. Only when dpkg - is executed with the --purge option will - configuration files be removed. In particular, as the - /etc/init.d/package script itself is - usually a conffile, it will remain on the system - if the package is removed but not purged. Therefore, you - should include a test statement at the top of the - script, like this: - -test -f program-executed-later-in-script || exit 0 - +

+ Two Debian bootstrap mechanisms have their roots in non-System-V bootstrap + mechanisms, the /etc/rc.local file and the /etc/rc.boot + directory. + The latter was a place where scripts to be run at boot-up could be placed. + On BSD operating systems, /etc/rc.boot is a file. + It is entirely deprecated and packages must not use it. + No Debian init system now supports this mechanism.

- Often there are some variables in the init.d - scripts whose values control the behavior of the scripts, - and which a system administrator is likely to want to - change. As the scripts themselves are frequently - conffiles, modifying them requires that the - administrator merge in their changes each time the package - is upgraded and the conffile changes. To ease - the burden on the system administrator, such configurable - values should not be placed directly in the script. - Instead, they should be placed in a file in - /etc/default, which typically will have the same - base name as the init.d script. This extra file - should be sourced by the script when the script runs. It - must contain only variable settings and comments in SUSv3 - sh format. It may either be a - conffile or a configuration file maintained by - the package maintainer scripts. See - for more details. -

- -

- To ensure that vital configurable values are always - available, the init.d script should set default - values for each of the shell variables it uses, either - before sourcing the /etc/default/ file or - afterwards using something like the : - ${VAR:=default} syntax. Also, the init.d - script must behave sensibly and not fail if the - /etc/default file is deleted. -

- -

- Files and directories under /run, including ones - referred to via the compatibility paths /var/run - and /var/lock, are normally stored on a temporary - filesystem and are normally not persistent across a reboot. - The init.d scripts must handle this correctly. - This will typically mean creating any required subdirectories - dynamically when the init.d script is run. - See for more information. + Packages must not use the former; as the name suggests it is for local + administrator bootstrap tasks. + Both systemd and System V init will run an rc.local + file if it exists and is executable as a program. This is a + subtle difference from some historical systems, where rc.local + need only be sourceable by the default shell.

+ - - Interfacing with the initscript system + + System V rc

- Maintainers should use the abstraction layer provided by - the update-rc.d and invoke-rc.d - programs to deal with initscripts in their packages' - scripts such as postinst, prerm - and postrm. + System V init implements changing between run levels + through one of several rc programs + which in turn invoke init.d + scripts (described in ). + Packages that wish to provide the System V rc + interface to the System V init system must provide + the following programs: + + +

+ /etc/init.d/rcS, + a program that runs startup elements of the rc system. +

+ + +

+ /etc/init.d/rc, + a program that init invokes to enter/leave + each run level. +

+ + +

+ /usr/sbin/invoke-rc.d, + a program used by maintainer scripts to start, stop, enable, + and disable scripts, subject to local policy overrides. + (See .) +

+ + +

+ /usr/sbin/update-rc.d + a program that is used to set/change what scripts run as + each run level is entered and left, and in what order. + (See .) +

+ +

- Directly managing the /etc/rc?.d links and directly - invoking the /etc/init.d/ initscripts should - be done only by packages providing the initscript - subsystem (such as sysv-rc and - file-rc). + All init systems must provide the latter two, either themselves + or through cooperation with an rc package. + Only System V init itself also requires the former two from rc + packages.

- - Managing the links +

+ There are three different rc packages in Debian, + sysv-rc, file-rc, and + openrc. + These record what scripts are enabled in each runlevel in + differing ways. Please refer to their documentation for the + details. + systemd has a fourth mechanism that is largely compatible with + sysv-rc, but which has several differences, + such as masking and the overriding priority that is given to service units. +

+ +

+ In general, therefore, maintainer scripts must not assume that + the symbolic link mechanisms (described in previous editions of + the Debian Policy Manual) take effect or even exist at all. + Maintainer scripts scripts such as postinst, + prerm and postrm. must use only the + supplied update-rc.d and invoke-rc.d + programs for interacting with the init.d script system. +

+ +

+ Only the rc packages themselves, and their various adjunct + packages, have any business (in maintainer scripts) with the + /etc/rcn.d directories (of + openrc and sysv-rc) or the + /etc/runlevel.conf file (of file-rc). +

+ + + systemd and upstart and rc

- The program update-rc.d is provided for - package maintainers to arrange for the proper creation and - removal of /etc/rcn.d symbolic links, - or their functional equivalent if another method is being - used. This may be used by maintainers in their packages' - postinst and postrm scripts. + In Debian 8, systemd and upstart do not provide their own + invoke-rc.d and update-rc.d. + The commands in the sysv-rc package have been + augmented to detect the running init system and take the appropriate + actions for enabling, disabling, starting, and stopping services. + These augmentations do not exist in the + invoke-rc.d and update-rc.d + in the file-rc and openrc packages. +

+ +

+ Administrators are encouraged to prefer the service command + to invoking init.d scripts directly, + because it attempts to minimize (even though it cannot totally + eradicate) the amount of login session state, including settings that can + potentially break service operations, that leaks from the administrator's + shell running the service command to the daemon process(es) + started by the init.d script. + Better still is to use the systemctl or initctl + commands, of course.

- You must not include any /etc/rcn.d - symbolic links in the actual archive or manually create or - remove the symbolic links in maintainer scripts; you must - use the update-rc.d program instead. (The - former will fail if an alternative method of maintaining - runlevel information is being used.) You must not include - the /etc/rcn.d directories themselves - in the archive either. (Only the sysvinit - package may do so.) + init.d scripts for which + an equivalent upstart job is available must query the output of + the command initctl version for the string + upstart and avoid running in favor of the native + upstart job, using a test such as this: + +if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart +then + exit 1 +fi +

- By default update-rc.d will start services in - each of the multi-user state runlevels (2, 3, 4, and 5) - and stop them in the halt runlevel (0), the single-user - runlevel (1) and the reboot runlevel (6). The system - administrator will have the opportunity to customize - runlevels by simply adding, moving, or removing the - symbolic links in /etc/rcn.d if - symbolic links are being used, or by modifying - /etc/runlevel.conf if the file-rc method - is being used. + Avoiding running in favour of a native systemd unit is slightly simpler. + If an init.d script sources /lib/lsb/init-functions, + the script will automatically redirect invocations to systemctl.

+ + + + Enabling and disabling scripts with update-rc.d +

- To get the default behavior for your package, put in your - postinst script + The program update-rc.d is provided (by each + init/rc system) for package maintainers to arrange for + enabling and disabling the running of init.d scripts. + This may be used by maintainers in their packages' + postinst and postrm scripts. + Maintainer scripts must not attempt to enable and disable + scripts directly. +

+ +

+ By default update-rc.d will enable services in the + multi-user state, meaning that they will be started in that state + and stopped in the halt, rescue, poweroff, and reboot states. +

+ +

+ To get the default behavior for your package, put update-rc.d package defaults - and in your postrm + in your postinst script and put if [ "$1" = purge ]; then update-rc.d package remove fi - . Note that if your package changes runlevels - or priority, you may have to remove and recreate the links, - since otherwise the old links may persist. Refer to the - documentation of update-rc.d. -

- -

- This will use a default sequence number of 20. If it does - not matter when or in which order the init.d - script is run, use this default. If it does, then you - should talk to the maintainer of the sysvinit - package or post to debian-devel, and they will - help you choose a number. + + in your postrm.

For more information about using update-rc.d, - please consult its man page . + please consult its man page + .

- - Running initscripts -

- The program invoke-rc.d is provided to make - it easier for package maintainers to properly invoke an - initscript, obeying runlevel and other locally-defined - constraints that might limit a package's right to start, - stop and otherwise manage services. This program may be - used by maintainers in their packages' scripts. -

+ + Starting and stopping scripts with invoke-rc.d

- The package maintainer scripts must use - invoke-rc.d to invoke the - /etc/init.d/* initscripts, instead of - calling them directly. + The program invoke-rc.d is provided for properly + invoking an init.d script, obeying runlevels, masks, and + other init-system-defined and locally-defined constraints that might + limit a package's right to start, stop and otherwise manage services. + Maintainer scripts must use this program and must not attempt to enable + and disable scripts directly.

- By default, invoke-rc.d will pass any - action requests (start, stop, reload, restart...) to the - /etc/init.d script, filtering out requests - to start or restart a service out of its intended - runlevels. + For compatibility with the default init system, maintainer scripts + must not run invoke-rc.d with any action requests other + than the conventional start, stop, reload, force-reload, and restart.

- Most packages will simply need to change: - /etc/init.d/<package> - <action> in their postinst - and prerm scripts to: + Instead of using: + /etc/init.d/<package> <action> + in a package's postinst and prerm scripts + packages must have something like: - if which invoke-rc.d >/dev/null 2>&1; then - invoke-rc.d package <action> - else - /etc/init.d/package <action> - fi +if which invoke-rc.d >/dev/null 2>&1; then + invoke-rc.d package <action> +else + /etc/init.d/package <action> +fi

- A package should register its initscript services using + A package should register its init.d services using update-rc.d before it tries to invoke them - using invoke-rc.d. Invocation of - unregistered services may fail. + using invoke-rc.d. + Invocation of unregistered services may fail on some init systems.

@@ -7755,225 +7903,374 @@ test -f program-executed-later-in-script || exit 0 - - Boot-time initialization + + init.d scripts -

- There used to be another directory, /etc/rc.boot, - which contained scripts which were run once per machine - boot. This has been deprecated in favour of links from - /etc/rcS.d to files in /etc/init.d as - described in . Packages must not - place files in /etc/rc.boot. +

+ The /etc/init.d directory contains scripts that are executed + directly by systemd and upstart, and indirectly by System V init by way + of one of several rc systems (described in + ).

- - - Example + + Writing the scripts -

- An example on which you can base your - /etc/init.d scripts is found in - /etc/init.d/skeleton. -

+

+ Packages that include daemons for system services may + place scripts in /etc/init.d to start or stop + services at boot time or during a change of runlevel. + These scripts should be named + /etc/init.d/package, and they should + accept one argument, saying what to do: + + + start + start the service, + + stop + stop the service, + + restart + stop and restart the service if it's already running, + otherwise start the service + + 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. + - - + The start, stop, restart, and + force-reload options should be supported by all + scripts in /etc/init.d, the reload + option is optional. +

- - Console messages from init.d scripts +

+ An example on which you can base your + /etc/init.d scripts is found in + /etc/init.d/skeleton. +

-

- This section describes the formats to be used for messages - written to standard output by the /etc/init.d - scripts. The intent is to improve the consistency of - Debian's startup and shutdown look and feel. For this - reason, please look very carefully at the details. We want - the messages to have the same format in terms of wording, - spaces, punctuation and case of letters. -

+

+ The init.d scripts must ensure that they will + behave sensibly (i.e., returning success and not starting + multiple copies of a service) if invoked with start + when the service is already running, or with stop + when it isn't, and that they don't kill unfortunately-named + user processes. The best way to achieve this is to switch from + an init.d script to a service unit + () or a job file () + of course. Whilst remaining an init.d script + however, the best usually for achieving this is to use + start-stop-daemon with the --oknodo + option. +

-

- Here is a list of overall rules that should be used for - messages generated by /etc/init.d scripts. -

+

+ Be careful of using set -e in init.d + scripts. Writing correct init.d scripts requires + accepting various error exit statuses when daemons are already + running or already stopped without aborting + the init.d script, and common init.d + function libraries are not safe to call with set -e + in effect + /lib/lsb/init-functions, which assists in writing + LSB-compliant init scripts, may fail if set -e is + in effect and echoing status messages to the console fails, + for example. + . For init.d scripts, it's often easier + to not use set -e and instead check the result of + each command separately. +

-

- - - The message should fit in one line (fewer than 80 - characters), start with a capital letter and end with - a period (.) and line feed ("\n"). - +

+ If a service reloads its configuration automatically (as + in the case of cron, for example), the + reload option of the init.d script + should behave as if the configuration has been reloaded + successfully. +

- - If the script is performing some time consuming task in - the background (not merely starting or stopping a - program, for instance), an ellipsis (three dots: - ...) should be output to the screen, with no - leading or tailing whitespace or line feeds. - +

+ The /etc/init.d scripts must be treated as + configuration files, either (if they are present in the + package, that is, in the .deb file) by marking them as + conffiles, or, (if they do not exist in the .deb) + by managing them correctly in the maintainer scripts (see + ). This is important since we want + to give the local system administrator the chance to adapt + the scripts to the local system, e.g., to disable a + service without de-installing the package, or to specify + some special command line options when starting a service, + while making sure their changes aren't lost during the next + package upgrade. +

- - The messages should appear as if the computer is telling - the user what it is doing (politely :-), but should not - mention "it" directly. For example, instead of: - +

+ These scripts should not fail obscurely when the + configuration files remain but the package has been + removed, as configuration files remain on the system after + the package has been removed. Only when dpkg + is executed with the --purge option will + configuration files be removed. In particular, as the + /etc/init.d/package script itself is + usually a conffile, it will remain on the system + if the package is removed but not purged. Therefore, you + should include a test statement at the top of the + script, like this: + +test -f program-executed-later-in-script || exit 0 + +

+ +

+ Often there are some variables in the init.d + scripts whose values control the behavior of the scripts, + and which a system administrator is likely to want to + change. As the scripts themselves are frequently + conffiles, modifying them requires that the + administrator merge in their changes each time the package + is upgraded and the conffile changes. To ease + the burden on the system administrator, such configurable + values should not be placed directly in the script. + Instead, they should be placed in a file in + /etc/default, which typically will have the same + base name as the init.d script. This extra file + should be sourced by the script when the script runs. It + must contain only variable settings and comments in SUSv3 + sh format. It may either be a + conffile or a configuration file maintained by + the package maintainer scripts. See + for more details. +

+ +

+ To ensure that vital configurable values are always + available, the init.d script should set default + values for each of the shell variables it uses, either + before sourcing the /etc/default/ file or + afterwards using something like the : + ${VAR:=default} syntax. Also, the init.d + script must behave sensibly and not fail if the + /etc/default file is deleted. +

+ +

+ Files and directories under /run, including ones + referred to via the compatibility paths /var/run + and /var/lock, are normally stored on a temporary + filesystem and are normally not persistent across a reboot. + The init.d scripts must handle this correctly. + This will typically mean creating any required subdirectories + dynamically when the init.d script is run. + See for more information. +

+ + + + Console messages from init.d scripts + +

+ This section describes the formats to be used for messages + written to standard output by the /etc/init.d + scripts. The intent is to improve the consistency of + Debian's startup and shutdown look and feel. For this + reason, please look very carefully at the details. We want + the messages to have the same format in terms of wording, + spaces, punctuation and case of letters. +

+ +

+ Here is a list of overall rules that should be used for + messages generated by /etc/init.d scripts. +

+ +

+ + + The message should fit in one line (fewer than 80 + characters), start with a capital letter and end with + a period (.) and line feed ("\n"). + + + + If the script is performing some time consuming task in + the background (not merely starting or stopping a + program, for instance), an ellipsis (three dots: + ...) should be output to the screen, with no + leading or tailing whitespace or line feeds. + + + + The messages should appear as if the computer is telling + the user what it is doing (politely :-), but should not + mention "it" directly. For example, instead of: + I'm starting network daemons: nfsd mountd. - - the message should say - + + the message should say + Starting network daemons: nfsd mountd. - - - -

+ + + +

-

- init.d script should use the following standard - message formats for the situations enumerated below. -

+

+ init.d script should use the following standard + message formats for the situations enumerated below. +

-

- - -

When daemons are started

+

+ + +

When daemons are started

-

- If the script starts one or more daemons, the output - should look like this (a single line, no leading - spaces): - +

+ If the script starts one or more daemons, the output + should look like this (a single line, no leading + spaces): + Starting description: daemon-1 ... daemon-n. - - The description should describe the - subsystem the daemon or set of daemons are part of, - while daemon-1 up to daemon-n - denote each daemon's name (typically the file name of - the program). -

+ + The description should describe the + subsystem the daemon or set of daemons are part of, + while daemon-1 up to daemon-n + denote each daemon's name (typically the file name of + the program). +

-

- For example, the output of /etc/init.d/lpd - would look like: - +

+ For example, the output of /etc/init.d/lpd + would look like: + Starting printer spooler: lpd. - -

+ +

-

- This can be achieved by saying - +

+ This can be achieved by saying + echo -n "Starting printer spooler: lpd" start-stop-daemon --start --quiet --exec /usr/sbin/lpd echo "." - - in the script. If there are more than one daemon to - start, the output should look like this: - + + in the script. If there are more than one daemon to + start, the output should look like this: + echo -n "Starting remote file system services:" echo -n " nfsd"; start-stop-daemon --start --quiet nfsd echo -n " mountd"; start-stop-daemon --start --quiet mountd echo -n " ugidd"; start-stop-daemon --start --quiet ugidd echo "." - - This makes it possible for the user to see what is - happening and when the final daemon has been started. - Care should be taken in the placement of white spaces: - in the example above the system administrators can - easily comment out a line if they don't want to start - a specific daemon, while the displayed message still - looks good. -

- + + This makes it possible for the user to see what is + happening and when the final daemon has been started. + Care should be taken in the placement of white spaces: + in the example above the system administrators can + easily comment out a line if they don't want to start + a specific daemon, while the displayed message still + looks good. +

+ - -

When a system parameter is being set

+ +

When a system parameter is being set

-

- If you have to set up different system parameters - during the system boot, you should use this format: - +

+ If you have to set up different system parameters + during the system boot, you should use this format: + Setting parameter to "value". - -

+ +

-

- You can use a statement such as the following to get - the quotes right: - +

+ You can use a statement such as the following to get + the quotes right: + echo "Setting DNS domainname to \"$domainname\"." - -

+ +

-

- Note that the same symbol (") is used - for the left and right quotation marks. A grave accent - (`) is not a quote character; neither is an - apostrophe ('). -

- +

+ Note that the same symbol (") is used + for the left and right quotation marks. A grave accent + (`) is not a quote character; neither is an + apostrophe ('). +

+ - -

When a daemon is stopped or restarted

+ +

When a daemon is stopped or restarted

-

- When you stop or restart a daemon, you should issue a - message identical to the startup message, except that - Starting is replaced with Stopping - or Restarting respectively. -

+

+ When you stop or restart a daemon, you should issue a + message identical to the startup message, except that + Starting is replaced with Stopping + or Restarting respectively. +

-

- For example, stopping the printer daemon will look like - this: - +

+ For example, stopping the printer daemon will look like + this: + Stopping printer spooler: lpd. - -

- + +

+ - -

When something is executed

+ +

When something is executed

-

- There are several examples where you have to run a - program at system startup or shutdown to perform a - specific task, for example, setting the system's clock - using netdate or killing all processes - when the system shuts down. Your message should look - like this: - +

+ There are several examples where you have to run a + program at system startup or shutdown to perform a + specific task, for example, setting the system's clock + using netdate or killing all processes + when the system shuts down. Your message should look + like this: + Doing something very useful...done. - - You should print the done. immediately after - the job has been completed, so that the user is - informed why they have to wait. You can get this - behavior by saying - + + You should print the done. immediately after + the job has been completed, so that the user is + informed why they have to wait. You can get this + behavior by saying + echo -n "Doing something very useful..." do_something echo "done." - - in your script. -

- + + in your script. +

+ - -

When the configuration is reloaded

+ +

When the configuration is reloaded

-

- When a daemon is forced to reload its configuration - files you should use the following format: - +

+ When a daemon is forced to reload its configuration + files you should use the following format: + Reloading description configuration...done. - - where description is the same as in the - daemon starting message. -

- - -

+ + where description is the same as in the + daemon starting message. +

+ + +

+ + + @@ -8383,74 +8680,6 @@ exec /usr/lib/foo/foo "$@"

- - Alternate init systems -

- A number of other init systems are available now in Debian that - can be used in place of sysvinit. Alternative - init implementations must support running SysV init scripts as - described at for compatibility. -

-

- Packages may integrate with these replacement init systems by - providing implementation-specific configuration information about - how and when to start a service or in what order to run certain - tasks at boot time. However, any package integrating with other - init systems must also be backwards-compatible with - sysvinit by providing a SysV-style init script - with the same name as and equivalent functionality to any - init-specific job, as this is the only start-up configuration - method guaranteed to be supported by all init implementations. An - exception to this rule is scripts or jobs provided by the init - implementation itself; such jobs may be required for an - implementation-specific equivalent of the /etc/rcS.d/ - scripts and may not have a one-to-one correspondence with the init - scripts. -

- - Event-based boot with upstart - -

- Packages may integrate with the upstart event-based - boot system by installing job files in the - /etc/init directory. SysV init scripts for which - an equivalent upstart job is available must query the output of - the command initctl version for the string - upstart and avoid running in favor of the native - upstart job, using a test such as this: - -if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart -then - exit 1 -fi - -

-

- Because packages shipping upstart jobs may be installed on - systems that are not using upstart, maintainer scripts must - still use the common update-rc.d and - invoke-rc.d interfaces for configuring runlevels - and for starting and stopping services. These maintainer - scripts must not call the upstart start, - restart, reload, or stop - interfaces directly. Instead, implementations of - invoke-rc.d must detect when upstart is running and - when an upstart job with the same name as an init script is - present, and perform the requested action using the upstart job - instead of the init script. -

-

- Dependency-based boot managers for SysV init scripts, such as - startpar, may avoid running a given init script - entirely when an equivalent upstart job is present, to avoid - unnecessary forking of no-op init scripts. In this case, the - boot manager should integrate with upstart to detect when the - upstart job in question is started or stopped to know when the - dependency has been satisfied. -

- - -