Bug#941194: initscripts: remove some implementation details

[Sean Whitton]

control: tag -1 +pending

Hello Russ, Ansgar,

Thank you for the valuable discussion.  I too second the below.

I compared the text to be removed and README.runlevels side-by-side, and
discovered that some ideas, explanation of which we are removing, are
implicitly assumed by README.runlevels.  I've filed a bug against
sysv-rc suggesting incorporation of that text.

On Thu 26 Sep 2019 at 09:01AM +02, Ansgar Burchardt wrote:

> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 1b63064..5a647fd 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -329,59 +329,18 @@ The ``/etc/init.d`` directory contains the scripts 
> executed by ``init``
>  at boot time and when the init state (or "runlevel") is changed (see
>  ``init(8)``).
>
> -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.
> -
> -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 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``).
> -
> -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
> -
> -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``.
> +``systemd`` uses dependency information contained within the init
> +scripts and symlinks in ``/etc/rcn.d`` to decide which scripts to run
> +and in which order. The ``sysv-rc`` runlevel system uses symlinks in
> +``/etc/rcn.d`` to decide which scripts to run and in which order, see
> +the ``README.runlevels`` file shipped with ``sysv-rc`` for
> +implementation details. Other alternatives might exist.
> +
> +Maintainer scripts must use ``update-rc.d`` as described below to
> +interact with the service manage for requests such as enabling or
> +disabling services. They should use ``invoke-rc.d`` as described below
> +to invoke initscripts for requests such as starting and stopping
> +service.
>
>  .. _s-writing-init:

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#941194: initscripts: remove some implementation details

[Russ Allbery]

Ansgar  writes:
> Russ Allbery writes:

>> I'm hesitant to remove all discussion of run levels because package
>> maintainers are still responsible for choosing a run level at which to
>> start their service and providing that run level as an argument to
>> update-rc.d.

> No, maintainer scripts call `update-rc.d  defaults`.  There is no
> runlevel involved.  The runlevel is only in the LSB init script magic
> comment.  However those aren't explained anywhere in Policy, even though
> the dependency part was more important than the runlevel part (IMHO)...

Oh, I see, the runlevels are only relevant for the disable and enable
commands, which are never used by packages.

Objection removed entirely.  Thanks!

>> How about, rather than moving it to a footnote, rephrasing it as follows?
>>
>> Except when the package has been removed but not purged, as described
>> above, the ``/etc/init.d`` script should not decide whether or not to
>> start the daemon based on configuration settings (such as settings in
>> ``/etc/default``) or silently exit successfully when the daemon could
>> not be started.

> I think this part isn't that interesting:

>> This causes inconsistent and confusing behavior such
>> as ``service  start`` returning success but not starting the
>> service; services with a dependency on this service starting even
>> though the service isn’t running; and init system status commands
>> claiming that the service was started.

> (It's a rationale, Policy usually doesn't have those.)

The lack of rationales is a bug in Policy.  We should have rationales;
otherwise, years later, it's difficult or impossible to understand what
the motivation was for some requirement.  (See also Chesterton's fence.)

Ideally we'd have some better way of representing them so that you could
enable or disable them when reading Policy if you want just the facts, but
I don't want to leave them out when we have them even though they can be a
bit wordy to include.

>> If the ``/etc/init.d`` script
>> is invoked with the ``start`` or ``restart`` arguments and the service
>> could not or should not be started, it should produce an appropriate
>> error message and exit with a non-zero status.
>>
>> and then moving this whole paragraph into 9.3.2, probably as the
>> second-to-last paragraph?

> Besides that I believe it's fine.

> 9.3.2 still has other interesting parts that I want to change (such as
> suggesting editing /etc/init.d/ is a good way to disable
> services).  For the conffile-disliking person it also contains the
> admission that conffiles are so user-unfriendly on upgrades that there
> are conffiles for conffiles, i.e. /etc/default/* ;-)

Yeah, I think that making init scripts conffiles was, in retrospect, a
mistake, although an understandable one and hard to avoid due to the lack
of any other override mechanism.

-- 
Russ Allbery (r...@debian.org)  

Bug#941194: initscripts: remove some implementation details

[Ansgar]

Russ Allbery writes:
> I'm hesitant to remove all discussion of run levels because package
> maintainers are still responsible for choosing a run level at which to
> start their service and providing that run level as an argument to
> update-rc.d.

No, maintainer scripts call `update-rc.d  defaults`.  There is no
runlevel involved.  The runlevel is only in the LSB init script magic
comment.  However those aren't explained anywhere in Policy, even though
the dependency part was more important than the runlevel part (IMHO)...

>>> Also the rationale for why `DISABLED=yes` (or similar) fits better
>>> into a footnote than the main text (IMHO).
>
>> I'm inclined to agree with you, but since Russ is keen to reduce the
>> number of footnotes in Policy, it would be good to hear from him here.
>
> I don't like footnotes; if something is important enough to say, I think
> it's usually important enough to put into the main text without making
> people click or jump around to find it.  But I think the current paragraph
> in Policy is poorly worded and not as general or as straightforward as it
> could be, and it's weirdly out of place in the update-rc.d section.
>
> How about, rather than moving it to a footnote, rephrasing it as follows?
>
> Except when the package has been removed but not purged, as described
> above, the ``/etc/init.d`` script should not decide whether or not to
> start the daemon based on configuration settings (such as settings in
> ``/etc/default``) or silently exit successfully when the daemon could
> not be started.

I think this part isn't that interesting:

> This causes inconsistent and confusing behavior such
> as ``service  start`` returning success but not starting the
> service; services with a dependency on this service starting even
> though the service isn’t running; and init system status commands
> claiming that the service was started.

(It's a rationale, Policy usually doesn't have those.)

> If the ``/etc/init.d`` script
> is invoked with the ``start`` or ``restart`` arguments and the service
> could not or should not be started, it should produce an appropriate
> error message and exit with a non-zero status.
>
> and then moving this whole paragraph into 9.3.2, probably as the
> second-to-last paragraph?

Besides that I believe it's fine.

9.3.2 still has other interesting parts that I want to change (such as
suggesting editing /etc/init.d/ is a good way to disable
services).  For the conffile-disliking person it also contains the
admission that conffiles are so user-unfriendly on upgrades that there
are conffiles for conffiles, i.e. /etc/default/* ;-)

Ansgar

Bug#941194: initscripts: remove some implementation details

[Russ Allbery]

Sean Whitton  writes:
> On Thu 26 Sep 2019 at 09:01AM +02, Ansgar Burchardt wrote:

>> Control: reassign -1 debian-policy
>>
>> The section on initscripts has too much implementation details about
>> /etc/rcn.d; these are better explained by external documentation.

> Are you saying that they are *currently* better explained by actually
> existing external documentation, or that it would be better to have them
> explained by external documentation instead of the Policy Manual?  If
> the former, could you point to that documentation, please?

I agree with removing the discussion of the symlink forest and how it is
managed.  We require use of update-rc.d and prohibits mucking about with
the symlinks.  Given that, I think the symlink forest is an implementation
detail of sysv-rc and we should remove the detailed documentation of it
from Policy and keep only the requirement to use update-rc.d and the
details required to invoke it correctly (which includes some discussion of
run levels).

I'm hesitant to remove all discussion of run levels because package
maintainers are still responsible for choosing a run level at which to
start their service and providing that run level as an argument to
update-rc.d.  I think Policy should include enough details to allow
package maintainers to make that decision.  That said, the current text
doesn't include any useful advice, so I'm okay with removing what
discussion there currently is and then reintroducing some better
documentation later when someone gets a chance to write it.

>> Also the rationale for why `DISABLED=yes` (or similar) fits better
>> into a footnote than the main text (IMHO).

> I'm inclined to agree with you, but since Russ is keen to reduce the
> number of footnotes in Policy, it would be good to hear from him here.

I don't like footnotes; if something is important enough to say, I think
it's usually important enough to put into the main text without making
people click or jump around to find it.  But I think the current paragraph
in Policy is poorly worded and not as general or as straightforward as it
could be, and it's weirdly out of place in the update-rc.d section.

How about, rather than moving it to a footnote, rephrasing it as follows?

Except when the package has been removed but not purged, as described
above, the ``/etc/init.d`` script should not decide whether or not to
start the daemon based on configuration settings (such as settings in
``/etc/default``) or silently exit successfully when the daemon could
not be started.  This causes inconsistent and confusing behavior such
as ``service  start`` returning success but not starting the
service; services with a dependency on this service starting even
though the service isn’t running; and init system status commands
claiming that the service was started.  If the ``/etc/init.d`` script
is invoked with the ``start`` or ``restart`` arguments and the service
could not or should not be started, it should produce an appropriate
error message and exit with a non-zero status.

and then moving this whole paragraph into 9.3.2, probably as the
second-to-last paragraph?

-- 
Russ Allbery (r...@debian.org)  

Bug#941194: initscripts: remove some implementation details

[Sean Whitton]

Hello,

On Sun 29 Sep 2019 at 10:21AM +02, Ansgar wrote:

> I think README.runlevels documents everything about how rcn.d scripts
> are called that Policy also documents (at least the part removed in my
> diff).

Okay, thanks for the feedback.

It would be good to have a third party review the other docs and confirm
that we're not deleting anything useful before proceeding on this.

Sorry to be so queasy about clean up activities.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#941194: initscripts: remove some implementation details

[Ansgar]

Sean Whitton writes:
> On Thu 26 Sep 2019 at 09:01AM +02, Ansgar Burchardt wrote:
>> The section on initscripts has too much implementation details about
>> /etc/rcn.d; these are better explained by external documentation.
>
> Are you saying that they are *currently* better explained by actually
> existing external documentation, or that it would be better to have them
> explained by external documentation instead of the Policy Manual?  If
> the former, could you point to that documentation, please?

>From my diff:

The ``sysv-rc`` runlevel system uses symlinks in ``/etc/rcn.d`` to
decide which scripts to run and in which order, see the
``README.runlevels`` file shipped with ``sysv-rc`` for
implementation details.

I think README.runlevels documents everything about how rcn.d scripts
are called that Policy also documents (at least the part removed in my
diff).

Ansgar

Bug#941194: initscripts: remove some implementation details

[Sean Whitton]

Hello,

On Thu 26 Sep 2019 at 09:01AM +02, Ansgar Burchardt wrote:

> Control: reassign -1 debian-policy
>
> The section on initscripts has too much implementation details about
> /etc/rcn.d; these are better explained by external documentation.

Are you saying that they are *currently* better explained by actually
existing external documentation, or that it would be better to have them
explained by external documentation instead of the Policy Manual?  If
the former, could you point to that documentation, please?

> Also the rationale for why `DISABLED=yes` (or similar) fits better
> into a footnote than the main text (IMHO).

I'm inclined to agree with you, but since Russ is keen to reduce the
number of footnotes in Policy, it would be good to hear from him here.

> (Policy also should say something about LSB headers in "Writing the
> scripts", but that will be a different patch.)

That would be great.

Thank you for taking the time to work on the readability of Policy.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#941194: initscripts: remove some implementation details

[Ansgar Burchardt]

Control: reassign -1 debian-policy

The section on initscripts has too much implementation details about
/etc/rcn.d; these are better explained by external documentation.
Also the rationale for why `DISABLED=yes` (or similar) fits better
into a footnote than the main text (IMHO).

(Policy also should say something about LSB headers in "Writing the
scripts", but that will be a different patch.)

Ansgar
>From 4bdc0bfa5a08ae0481a9820c1d4bfb8b933afcc4 Mon Sep 17 00:00:00 2001
From: Ansgar 
Date: Thu, 26 Sep 2019 08:49:28 +0200
Subject: [PATCH 1/2] move rationale to discourage old practice into footnote

---
 policy/ch-opersys.rst | 22 --
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 6e0c020..1b63064 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -554,16 +554,7 @@ administrator can enable autostarting the daemon using the 
command
 ``update-rc.d package enable``.
 
 An older practice, which should not be used, was to include a line
-like ``DISABLED=yes`` in the package's ``/etc/default`` file.  The
-package's init script would not start the service until the local
-system administrator changed this to ``DISABLED=no``, or similar.  The
-problem with this approach was that it hides from the init system
-whether or not the daemon should actually be started, which leads to
-inconsistent and confusing behavior: ``service  start`` may
-return success but not start the service; services with a dependency
-on this service will be started even though the service isn't running;
-and init system status commands may incorrectly claim that the service
-was started.
+like ``DISABLED=yes`` in the package's ``/etc/default`` file.  [#]_
 
 Note that if your package changes runlevels or priority, you may have to
 remove and recreate the links, since otherwise the old links may
@@ -1034,6 +1025,17 @@ Debian, so this section has been removed.
init scripts, may fail if ``set  -e`` is in effect and echoing 
status messages to the
console fails, for example.
 
+.. [#]
+   The package's init script would not start the service until the
+   local system administrator changed this to ``DISABLED=no``, or
+   similar.  The problem with this approach was that it hides from the
+   init system whether or not the daemon should actually be started,
+   which leads to inconsistent and confusing behavior: ``service
+start`` may return success but not start the service;
+   services with a dependency on this service will be started even
+   though the service isn't running; and init system status commands
+   may incorrectly claim that the service was started.
+
 .. [#]
Creating, modifying or removing a file in
``/usr/lib/mime/packages/`` using maintainer scripts will not
-- 
2.23.0

>From 82db1fc4300e2b6563f2436fadf3f964d567c65b Mon Sep 17 00:00:00 2001
From: Ansgar 
Date: Thu, 26 Sep 2019 08:54:03 +0200
Subject: [PATCH 2/2] refer to external documentation for implementation
 details of /etc/rcn.d

---
 policy/ch-opersys.rst | 65 ---
 1 file changed, 12 insertions(+), 53 deletions(-)

diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 1b63064..5a647fd 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -329,59 +329,18 @@ The ``/etc/init.d`` directory contains the scripts 
executed by ``init``
 at boot time and when the init state (or "runlevel") is changed (see
 ``init(8)``).
 
-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.
-
-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 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``).
-
-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

Bug#941194: initscripts: remove some implementation details

[Ansgar Burchardt]

Package: bugs.debian.org
Severity: normal
Tags: patch

The section on initscripts has too much implementation details about
/etc/rcn.d; these are better explained by external documentation.
Also the rationale for why `DISABLED=yes` (or similar) fits better
into a footnote than the main text (IMHO).

(Policy also should say something about LSB headers in "Writing the
scripts", but that will be a different patch.)

Ansgar
>From 4bdc0bfa5a08ae0481a9820c1d4bfb8b933afcc4 Mon Sep 17 00:00:00 2001
From: Ansgar 
Date: Thu, 26 Sep 2019 08:49:28 +0200
Subject: [PATCH 1/2] move rationale to discourage old practice into footnote

---
 policy/ch-opersys.rst | 22 --
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 6e0c020..1b63064 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -554,16 +554,7 @@ administrator can enable autostarting the daemon using the 
command
 ``update-rc.d package enable``.
 
 An older practice, which should not be used, was to include a line
-like ``DISABLED=yes`` in the package's ``/etc/default`` file.  The
-package's init script would not start the service until the local
-system administrator changed this to ``DISABLED=no``, or similar.  The
-problem with this approach was that it hides from the init system
-whether or not the daemon should actually be started, which leads to
-inconsistent and confusing behavior: ``service  start`` may
-return success but not start the service; services with a dependency
-on this service will be started even though the service isn't running;
-and init system status commands may incorrectly claim that the service
-was started.
+like ``DISABLED=yes`` in the package's ``/etc/default`` file.  [#]_
 
 Note that if your package changes runlevels or priority, you may have to
 remove and recreate the links, since otherwise the old links may
@@ -1034,6 +1025,17 @@ Debian, so this section has been removed.
init scripts, may fail if ``set  -e`` is in effect and echoing 
status messages to the
console fails, for example.
 
+.. [#]
+   The package's init script would not start the service until the
+   local system administrator changed this to ``DISABLED=no``, or
+   similar.  The problem with this approach was that it hides from the
+   init system whether or not the daemon should actually be started,
+   which leads to inconsistent and confusing behavior: ``service
+start`` may return success but not start the service;
+   services with a dependency on this service will be started even
+   though the service isn't running; and init system status commands
+   may incorrectly claim that the service was started.
+
 .. [#]
Creating, modifying or removing a file in
``/usr/lib/mime/packages/`` using maintainer scripts will not
-- 
2.23.0

>From 82db1fc4300e2b6563f2436fadf3f964d567c65b Mon Sep 17 00:00:00 2001
From: Ansgar 
Date: Thu, 26 Sep 2019 08:54:03 +0200
Subject: [PATCH 2/2] refer to external documentation for implementation
 details of /etc/rcn.d

---
 policy/ch-opersys.rst | 65 ---
 1 file changed, 12 insertions(+), 53 deletions(-)

diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 1b63064..5a647fd 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -329,59 +329,18 @@ The ``/etc/init.d`` directory contains the scripts 
executed by ``init``
 at boot time and when the init state (or "runlevel") is changed (see
 ``init(8)``).
 
-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.
-
-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 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``).
-
-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