[Pkg-sysvinit-commits] r122 - in sysvinit/trunk/debian: . sysv-rc/man8

Mon Nov 14 12:48:58 UTC 2005

Author: jdthood-guest
Date: 2005-11-14 12:48:56 +0000 (Mon, 14 Nov 2005)
New Revision: 122

Modified:
   sysvinit/trunk/debian/changelog
   sysvinit/trunk/debian/sysv-rc/man8/update-rc.d.8
Log:
Improve update-rc.d.8

Modified: sysvinit/trunk/debian/changelog
===================================================================

--- sysvinit/trunk/debian/changelog	2005-11-14 09:50:19 UTC (rev 121)
+++ sysvinit/trunk/debian/changelog	2005-11-14 12:48:56 UTC (rev 122)
@@ -10,6 +10,8 @@
     fixed on machines with locked root accounts too, by pressenting a
     shell in these cases. Patch from Ubuntu and Thom May.
     (Closes: #326678)
+  [ Thomas Hood ]
+  * Improve update-rc.d man page
 
  -- Petter Reinholdtsen <pere at debian.org>  Mon, 14 Nov 2005 09:14:51 +0100
 

Modified: sysvinit/trunk/debian/sysv-rc/man8/update-rc.d.8
===================================================================
--- sysvinit/trunk/debian/sysv-rc/man8/update-rc.d.8	2005-11-14 09:50:19 UTC (rev 121)
+++ sysvinit/trunk/debian/sysv-rc/man8/update-rc.d.8	2005-11-14 12:48:56 UTC (rev 122)
@@ -1,6 +1,6 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
 .\" Authors: Ian Jackson, Miquel van Smoorenburg
-.TH UPDATE\-RC.D 8 "23 December 2003" "Debian Project" "sysv-rc"
+.TH UPDATE\-RC.D 8 "14 November 2005" "Debian Project" "sysv-rc"
 .SH NAME
 update\-rc.d \- install and remove System-V style init script links
 .SH SYNOPSIS
@@ -18,29 +18,28 @@
 .RI [ -n ]
 .I name
 .BR start | stop
-.IR "NN runlevel runlevel " ...
+.IR "NN runlevel" " [" runlevel "]..."
 .B .
 .BR start | stop
-.IR "NN runlevel runlevel " ...
+.IR "NN runlevel" " [" runlevel "]..."
 .BR . " ..."
 .SH DESCRIPTION
 .B update-rc.d
-automatically updates the System V style init script links
+updates the System V style init script links
 .BI /etc/rc runlevel .d/ NNname
-to scripts
+whose target is the script
 .BI /etc/init.d/ name \fR.
-These are run by
+These links are run by
 .B init
-when changing runlevels and are generally used to start and stop
+when it changes runlevels; they are generally used to start and stop
 system services such as daemons.
 .I runlevel
 is one of the runlevels supported by
-.BR init ", " 0123456789S ,
-and
+.BR init ", namely, " 0123456789S ", and "
 .I NN
-is the two-digit sequence code used by
+is the two-digit sequence number that determines where in the sequence
 .B init
-to decide which order to run the scripts in.
+will run the scripts.
 
 This manpage documents only the usage and behaviour of
 .BR update-rc.d .
@@ -49,57 +48,101 @@
 .BR init (8)
 and the
 .IR "Debian Policy Manual" .
+.P
+Please note that this program was designed for use
+in package maintainer scripts and, accordingly,
+has only the very limited functionality required by such scripts.
+System administrators are not encouraged to use
+.BR update-rc.d
+to manage runlevels.
+They should edit the links directly or
+use runlevel editors such as
+.B sysv-rc-conf
+and
+.B bum
+instead.
 .SH INSTALLING INIT SCRIPT LINKS
 When run with either the
 .BR defaults ", " start ", or " stop
-options, update-rc.d makes links
+options,
+.B update-rc.d
+makes links
 .BI /etc/rc runlevel .d/[SK] NNname
-pointing to the script
-.BI /etc/init.d/ name\fR,
+that point to the script
+.BR /etc/init.d/ \fIname\fR.
 
 If any files
 .BI /etc/rc runlevel .d/[SK]?? name
 already exist then
 .B update-rc.d
-does nothing.  This is so that the system administrator can rearrange
-the links, provided that they leave at least one link remaining,
-without having their configuration overwritten.
-
+does nothing.
+The program was written this way so that it will never
+change an existing configuration, which may have been
+customized by the system administrator.
+The program will only install links if none are present,
+i.e.,
+if it appears that the service has never been installed before.
+.P
+A common system administration error is to delete the links
+with the thought that this will "disable" the service, i.e.,
+that this will prevent the service from being started.
+However, if all links have been deleted then the next time
+the package is upgraded, the package's
+.I postinst
+script will run
+.B update-rc.d
+again and this will reinstall links at their factory default locations.
+The correct way to disable services is to configure the
+service as stopped in all runlevels in which it is started by default.
+In the System V init system this means renaming
+the service's symbolic links
+from
+.B S
+to
+.BR K .
+.P
 If
 .B defaults
 is used then
 .B update-rc.d
 will make links to start the service in runlevels
 .B 2345
-and stop the service in runlevels
+and to stop the service in runlevels
 .BR 016 .
-By default all the links will have sequence code 20, but
+By default all the links will have sequence number 20, but
 this can be overridden by supplying one 
 .I NN
 or two
 .I SS
 and
 .I KK
-arguments; one argument overrides the sequence code for both start and
-stop links whereas of two arguments the first overrides the code for
-start links and the second that for stop links.
-
+arguments;
+a single argument overrides the sequence number
+for both start and stop links
+whereas a pair of arguments overrides the sequence numbers
+for start and stop links, respectively.
+.P
+As a rule of thumb, the sequence number of the stop link 
+should 100 minus the sequence number of the start link;
+this causes services to be stopped in the opposite order
+to that in which they are started.
+Obviously, therefore, the default stop sequence number
+should be 80.
+Defaulting to 20, as
+.B update-rc.d
+does, is an old bug that cannot be fixed because
+of the risk of breaking things.
+.P
 Instead of
 .B defaults
-the runlevels in which to start and stop the service may be specified
-explicitly using a series of sets of arguments:
-
-Each of these sets starts with an argument
+one can give one or more sets of arguments specifying
+particular runlevels in which to start or stop the service.
+Each of these sets of arguments starts with the keyword
 .BR start " or " stop
-to specify whether start or stop links are to be created by that set.
-Then follows
+and a sequence number
 .IR NN ,
-the sequence code number for all the links in the set, and one or more
-runlevel numbers as a single argument each.  The set is terminated by
-an argument
-.B .
-(a single full stop).
-
+followed by one or more runlevel numbers.
+The set is terminated by a solitary full stop character.
 When explicit specification, rather than
 .BR defaults ,
 is used there will usually be one
@@ -112,7 +155,7 @@
 sets or several
 .B stop
 sets may be specified.
-
+.P
 The script
 .BI /etc/init.d/ name
 must exist before
@@ -125,27 +168,22 @@
 .BI /etc/rc runlevel .d
 directories to the script
 .BI /etc/init.d/ name\fR.
-The script must have been deleted already -
+The script must have been deleted already.
+If the script is still present then
 .B update-rc.d
-checks for this.
+aborts with an error message.
+.P
 .B update-rc.d
 is usually called from a package's post-removal script when that
-script detects that its first argument is
-.BR purge ,
-indicating that the user has requested the configuration for the
-package to be removed.
+script is given the
+.B purge
+argument.
 Any files in the
 .BI /etc/rc runlevel .d
 directories that are not symbolic links to the script
 .BI /etc/init.d/ name
 will be left untouched.
 
-Note to system administrators: When a package is upgraded, links will
-be re-added unless there is at least one
-.BI /etc/rc runlevel .d/[SK]?? name
-file present. So
-to remove links and have that removal survive a package upgrade, leave
-stop links in runlevels 2 through 5.
 .SH OPTIONS
 .TP
 .I -n
@@ -164,23 +202,32 @@
 .nf
 .B "   update-rc.d foobar start 20 2 3 4 5 . stop 20 0 1 6 ."
 .fi
+More typical command using explicit argument sets:
+.nf
+.B "   update-rc.d foobar start 30 2 3 4 5 . stop 70 0 1 6 ."
+.fi
 Remove all links for a script (assuming foobar has been deleted
 already):
 .nf
 .B "   update-rc.d foobar remove"
 .fi
-Remove all links for a script that is still present, but leave stop
-links to ensure this survives package upgrades:
+Example of disabling a service:
 .nf
 .B "   update-rc.d -f foobar remove"
 .B "   update-rc.d foobar stop 20 2 3 4 5 ."
 .fi
+Example of a command for installing a system initialization-and-shutdown script:
+.nf
+.B "   update-rc.d foobar start 45 S . start 31 0 6 ."
+.fi
+Example of a command for disabling a system initialization-and-shutdown script:
+.nf
+.B "   update-rc.d -f foobar remove"
+.B "   update-rc.d foobar stop 45 S ."
+.fi
+
 .SH BUGS
-
-There should be a way for the system administrator to specify at least
-the default start and stop runlevels to be used by
-.B defaults
-and possibly to override other things as well.
+See http://bugs.debian.org/sysv-rc.
 .SH FILES
 .TP
 .B /etc/init.d/


