Package: doc-debian Version: 3.1.5 Severity: wishlist Tags: patch In §11.6 ‘It looks as if Debian does not use rc.local to customize the boot process; what facilities are provided?’, the two sentences
Scripts beginning with 'S' in /etc/rcN.d/ are executed when runlevel N is entered. Scripts beginning with a 'K' are executed when leaving runlevel N. imply that /etc/rcN.d/K* scripts are run when leaving runlevel N, whereas the previous subsection (§11.5) implies that /etc/rcN.d/K* scripts are run when entering runlevel N (before running the /etc/rcN.d/S* scripts). I believe §11.5 is correct and §11.6 is incorrect. (See /etc/init.d/rc and description of Default-Stop at http://refspecs.linux-foundation.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/initscrcomconv.html.) I suggest changing to: When entering runlevel N, first /etc/rcN.d/K* scripts are run with an argument of ‘stop’ to kill the services corresponding with those K* scripts, and then /etc/rcN.d/S* scripts are run with an argument of ‘start’ to start the services corresponding to those S* scripts. Now that I look at the section, I notice a few other changes that might be made: - Rebooting the system is a bit heavy-handed. I suggest changing the "Reboot the system" bullet point to: Consider rebooting the system to check that the service starts correctly (assuming that you've asked for it to be started in the default runlevel). Otherwise, manually start it by running /etc/init.d/foo start - I suggest changing the description of the `19' argument to change "containing" to "whose number is", and explicitly mentioning the corollary about numbers less than 19, and adding "have completed" as we do so to clarify what we mean by "called before >19 scripts are started": after all scripts whose number is less than 19 have completed, and before all scripts whose number is greater than 19. - The argument ‘defaults’ does not mean simply to start the service in runlevels 2 through 5; rather, it means (in sysv-rc) to use the start/stop runlevels specified in the LSB comments, starting the service in runlevels 2 through 5 if no Default-Start is specified, and stopping the service in runlevels 0,1,6 if no Default-Stop is specified. file-rc's update-rc.d, OTOH, doesn't parse the LSB comments (at least in version 0.8.10), so the argument ‘defaults’ simply means to start the service in runlevels 2 through 5 *and* to stop the service in runlevels 0,1,6. - The details about symlinks in /etc/rc?.d directories are specific to sysv-rc, and are wrong for file-rc. It would be nice to start with generic text about the script being started or stopped in various runlevels, and then (optionally) at the end of the section have details as they apply to sysv-rc. Thus, the existing to set up links between the (command-line-specified) directories rc?.d and /etc/init.d/foo. Here, '?' is a number from 0 through 6 and corresponds to each of the System V runlevels. would become to specify which runlevels should start the service, and which runlevels should stop the service. Then move the foo example paragraph to just after the list (i.e. before any coverage of sysv-rc details). The foo paragraph would change ‘installing the links with’ to simply ‘running’. I'm inclined to drop the details about sysv-rc altogether: that's for the sysv-rc package to describe, or for a separate question: indeed, the previous question already pretty much covers it. I attach a patch to make these changes (choosing to drop the sysv-rc details from this question rather than making the S/K changes that I described at the beginning of this message). Note that the patch introduces UTF-8 single-quote characters (‘ ’), I hope that's OK; otherwise s/‘/‘/g;s/’/’/g. pjrm.
diff -dur doc-debian-3.1.5/FAQ/customizing.sgml doc-debian-3.1.5-pjrm/FAQ/customizing.sgml --- doc-debian-3.1.5/FAQ/customizing.sgml 2007-01-17 20:17:16.000000000 +1100 +++ doc-debian-3.1.5-pjrm/FAQ/customizing.sgml 2008-01-19 10:49:33.000000000 +1100 @@ -102,25 +102,26 @@ <list> <item>Enter the script <tt>foo</tt> into the directory <tt>/etc/init.d/</tt>. <item>Run the Debian command <tt>update-rc.d</tt> with appropriate - arguments, to set up links between the (command-line-specified) directories - rc?.d and <tt>/etc/init.d/foo</tt>. Here, '?' is a number from 0 through 6 - and corresponds to each of the System V runlevels. - <item>Reboot the system. + arguments, to specify which runlevels should start the service, and which + runlevels should stop the service. + <item>Consider rebooting the system to check that the service starts + correctly (assuming that you've asked for it to be started in the + default runlevel). Otherwise, manually start it by running + ‘<tt>/etc/init.d/foo start</tt>’. </list> -<p>The command <tt>update-rc.d</tt> will set up links between files in -the directories rc?.d and the script in <tt>/etc/init.d/</tt>. -Each link will begin with a 'S' or a 'K', followed by a number, followed -by the name of the script. Scripts beginning with 'S' in -<tt>/etc/rcN.d/</tt> are executed when runlevel <tt>N</tt> is entered. -Scripts beginning with a 'K' are executed when leaving runlevel <tt>N</tt>. - <p>One might, for example, cause the script <tt>foo</tt> to execute at -boot-up, by putting it in <tt>/etc/init.d/</tt> and installing the links with -<tt>update-rc.d foo defaults 19</tt>. The argument 'defaults' refers -to the default runlevels, which are 2 through 5. The argument '19' ensures -that <tt>foo</tt> is called before any scripts containing numbers 20 -or larger. +boot-up, by putting it in <tt>/etc/init.d/</tt> and running +<tt>update-rc.d foo defaults 19</tt>. The argument ‘<tt>defaults</tt>’ refers +to the default runlevels, which means (at least in absence of any LSB comment +block to the contrary) to start the service in runlevels 2 through 5, +and to stop the service in runlevels 0, 1 and 6. +(Any LSB Default-Start and Default-Stop directives in <tt>foo</tt> take +precedence when using the sysv-rc version of update-rc.d, but are +ignored by the current (v0.8.10) file-rc version of update-rc.d.) +The argument ‘<tt>19</tt>’ ensures that <tt>foo</tt> is called after all +scripts whose number is less than 19 have completed, and before all scripts +whose number is 20 or greater. <sect id="interconffiles">How does the package management system deal with packages that contain configuration files for other packages?
