Bug#919507: Reboot required patch for Debian policy

[Russ Allbery]

"Karl O. Pinc"  writes:

> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 59c92ec..8276bfe 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -1040,3 +1040,33 @@ Debian, so this section has been removed.
> activate the trigger. In that case, it can be done by calling
> ``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
> maintainer script after creating, modifying, or removing the file.
> +
> +.. index::
> +   pair: signaling; reboot
> +
> +.. _s-signalingreboot
> +
> +Signaling that a reboot is required
> +---
> +
> +.. index::
> +   single: reboot-required
> +   single: reboot-required.pkgs
> +
> +Programs can signal that a reboot is required by ``touch``\ing
> +``/run/reboot-required``.  It is conventional to add the name of the
> +package(s) requiring the reboot to
> +``/run/reboot-required.pkgs``. Programs should not add a package name
> +to ``/run/reboot-required.pkgs`` if it is already present there.
> +
> +.. index:
> +   single: postinst
> +
> +The ``/run/reboot-required`` mechanism is used when a reboot is
> +needed to fully apply the changes introduced by package
> +installation or upgrade.  Typically it is the ``postinst``
> +maintainer script that touches ``/run/reboot-required``, at the end
> +of a successful configuration of the package.
> +
> +There are no guarantees provided by the ``/var/reboot-required``
> +convention as to when or whether the requested reboot will occur.

This looks good to me as well.  Seconded.

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

Bug#919507: Reboot required patch for Debian policy

[Holger Levsen]

On Sun, Jan 20, 2019 at 05:09:39PM -0600, Karl O. Pinc wrote:
> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 59c92ec..8276bfe 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -1040,3 +1040,33 @@ Debian, so this section has been removed.
> activate the trigger. In that case, it can be done by calling
> ``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
> maintainer script after creating, modifying, or removing the file.
> +
> +.. index::
> +   pair: signaling; reboot
> +
> +.. _s-signalingreboot
> +
> +Signaling that a reboot is required
> +---
> +
> +.. index::
> +   single: reboot-required
> +   single: reboot-required.pkgs
> +
> +Programs can signal that a reboot is required by ``touch``\ing
> +``/run/reboot-required``.  It is conventional to add the name of the
> +package(s) requiring the reboot to
> +``/run/reboot-required.pkgs``. Programs should not add a package name
> +to ``/run/reboot-required.pkgs`` if it is already present there.
> +
> +.. index:
> +   single: postinst
> +
> +The ``/run/reboot-required`` mechanism is used when a reboot is
> +needed to fully apply the changes introduced by package
> +installation or upgrade.  Typically it is the ``postinst``
> +maintainer script that touches ``/run/reboot-required``, at the end
> +of a successful configuration of the package.
> +
> +There are no guarantees provided by the ``/var/reboot-required``
> +convention as to when or whether the requested reboot will occur.

seconded, thanks.


-- 
tschau,
Holger

---
   holger@(debian|reproducible-builds|layer-acht).org
   PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C


signature.asc
Description: PGP signature

Bug#919507: Reboot required patch for Debian policy

[Sean Whitton]

Hello,

On Sat 09 Feb 2019 at 08:47PM -06, Karl O. Pinc wrote:

> Anyway, do whatever you think best.

Having read it a few more times I think both are valid, and will use
your patch unmodified.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

On Sat, 09 Feb 2019 17:59:18 -0700
Sean Whitton  wrote:

> >> The ``/run/reboot-required`` mechanism is used when a reboot is
> >> needed to fully apply the changes introduced by a package
> >> installation or upgrade.  Typically it is the ``postinst``
> >> maintainer script that touches ``/run/reboot-required``, at the
> >> end of a successful configuration of the package.  
> >
> > I used your text, removing an "a".  
> 
> Hmm, may I ask whether you are a native speaker of English?  I am, and
> it reads better with the 'a', to me.  But don't worry, you do not need
> to prepare a new diff, as I can fix that when committing.

Yup.  I'm a native English speaker.

You made me curious.  I guess it depends on whether the
noun-ification (gerund -- https://en.wikipedia.org/wiki/Gerund)
of the verb "reboot" is "reboot" or "rebooting".

Without an "a" in the above: ...used when rebooting is
needed...

Since reboot is only recently a word, and English is whack,
who knows what's right.  I suppose I think "reboot" is both a
noun and a verb because "boot" is both a noun and a verb.
(Boot him out.  I gave him the boot.  In the latter both
senses work.)

Anyway, do whatever you think best.

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein

Bug#919507: Reboot required patch for Debian policy

[Sean Whitton]

control: tag 1 +patch

Hello Karl,

Thank you for the new patch.

On Sun 20 Jan 2019 at 05:09PM -06, Karl O. Pinc wrote:

> I'm 99% confident that _a_ purpose of reboot-required.pkgs
> is to provide a list of the packages requiring a reboot
> to a human.  And notification did not seem to be via logs.
> I can't say if the file has any other purpose.
>
> Regardless of the above, I've made your change as suggested.
> The important thing I want to convey is that reboot-required.pkgs
> does not affect the reboot signal.  It does something supplementary.
> Better not to over-specify.

Indeed.

> It is also worth nothing at this point that kubernetes appears
> to be touching reboot-required and adding to reboot-required.pkgs, but
> doing so in non-package-installation related code.  AFAICT.  At least
> that's what I recall now after a short glance through the code
> some time ago.  This is why I added the bit about regular
> programs being able to signal for reboot.

Okay.

>> The ``/run/reboot-required`` mechanism is used when a reboot is
>> needed to fully apply the changes introduced by a package
>> installation or upgrade.  Typically it is the ``postinst``
>> maintainer script that touches ``/run/reboot-required``, at the
>> end of a successful configuration of the package.
>
> I used your text, removing an "a".

Hmm, may I ask whether you are a native speaker of English?  I am, and
it reads better with the 'a', to me.  But don't worry, you do not need
to prepare a new diff, as I can fix that when committing.

> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 59c92ec..8276bfe 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -1040,3 +1040,33 @@ Debian, so this section has been removed.
> activate the trigger. In that case, it can be done by calling
> ``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
> maintainer script after creating, modifying, or removing the file.
> +
> +.. index::
> +   pair: signaling; reboot
> +
> +.. _s-signalingreboot
> +
> +Signaling that a reboot is required
> +---
> +
> +.. index::
> +   single: reboot-required
> +   single: reboot-required.pkgs
> +
> +Programs can signal that a reboot is required by ``touch``\ing
> +``/run/reboot-required``.  It is conventional to add the name of the
> +package(s) requiring the reboot to
> +``/run/reboot-required.pkgs``. Programs should not add a package name
> +to ``/run/reboot-required.pkgs`` if it is already present there.
> +
> +.. index:
> +   single: postinst
> +
> +The ``/run/reboot-required`` mechanism is used when a reboot is
> +needed to fully apply the changes introduced by package
> +installation or upgrade.  Typically it is the ``postinst``
> +maintainer script that touches ``/run/reboot-required``, at the end
> +of a successful configuration of the package.
> +
> +There are no guarantees provided by the ``/var/reboot-required``
> +convention as to when or whether the requested reboot will occur.

Seconded.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

Hi Sean,

On Sun, 20 Jan 2019 15:02:05 -0700
Sean Whitton  wrote:

> > It is clear to me that a reboot will occur whenever
> > /var/run/reboot-required exists, regardless of the
> > state of /var/run/reboot-required.pkgs.
> >
> > It is not clear to me where reboot-required.pkgs is used.  
> 
> Your current patch suggests that the purpose of reboot-required.pkgs
> is to inform users of which package needs a reboot.  I take it this
> is your guess as to the file's purpose?  How sure are you about
> this?  We shouldn't write something in Policy that we don't properly
> understand.
> 
> > +To inform users as to which package(s)
> > +require a reboot, add the name of the package(s) requiring the
> > reboot +to ``/run/reboot-required.pkgs``. Programs should not add a
> > package +name to ``/run/reboot-required.pkgs`` if it is already
> > present there.  
> 
> I suggest "It is conventional to append the package name to
> ``/run/reboot-required.pkgs``" to avoid saying what the file is for,
> since we're not sure.

I did look through the "reboot-required.pkgs" hits
at codesearch.debian.org.  At this point I can't recall exactly which
packages I looked at and which I didn't but I looked at better
than 50% of them.  

(My general approach to researching all issues
related to this bug report is to look at the code involving
scripting languages but not bother to track, say, #define
references through compiled code.)

Everywhere I've looked for reboot-required.pkgs I've found
code equivalent to:

  echo "Rebooting due to the following packages:"
  cat /var/run/reboot-required.pkgs

I'm 99% confident that _a_ purpose of reboot-required.pkgs
is to provide a list of the packages requiring a reboot
to a human.  And notification did not seem to be via logs.
I can't say if the file has any other purpose.

Regardless of the above, I've made your change as suggested.
The important thing I want to convey is that reboot-required.pkgs
does not affect the reboot signal.  It does something supplementary.
Better not to over-specify.


It is also worth nothing at this point that kubernetes appears
to be touching reboot-required and adding to reboot-required.pkgs, but
doing so in non-package-installation related code.  AFAICT.  At least
that's what I recall now after a short glance through the code
some time ago.  This is why I added the bit about regular
programs being able to signal for reboot.

> > +An expected time to signal that a reboot is required is upon
> > +installation or upgrade of a package.  Signaling is called for
> > when a +reboot is needed to fully apply the changes a package
> > introduces.  The +appropriate place to manipulate reboot related
> > files is expected to be +in the ``postinst`` maintainer script when
> > it is called as ``postinst +configure
> > most-recently-configured-version`` because this is when it +is
> > known that the package successfully installed and configured.  
> 
> Expressions like "expected" and "is called for" sound like they are
> normative, but it seems like your aim in this paragraph is to describe
> the purpose of a feature, rather than to specify how it may and may
> not be used.

Yes. 

>  Let's try to avoid giving the impression of normativity.
> 
> How about:
> 
> The ``/run/reboot-required`` mechanism is used when a reboot is
> needed to fully apply the changes introduced by a package
> installation or upgrade.  Typically it is the ``postinst``
> maintainer script that touches ``/run/reboot-required``, at the
> end of a successful configuration of the package.

I used your text, removing an "a".

> 
> > +Note that the Operating System is not guaranteed to act on these
> > +files.  When, and whether, a reboot occurs is dependent upon the
> > +installation and configuration of a package which provides a reboot
> > +feature.  The same is true of user notifications involving
> > reboot.  
> 
> It seems obvious that touching ``/run/reboot-required`` does not
> trigger a reboot, and typical Debian systems never reboot by
> themselves.  IMO this paragraph is unnecessarily verbose.  How about:
> 
> There are no guarantees provided by the ``/var/reboot-required``
> convention as to when the required reboot will occur.
> 

Shorter is better.  I tweaked slightly.

Attached: reboot-required_v5.patch

Thanks for all the editing!

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 59c92ec..8276bfe 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -1040,3 +1040,33 @@ Debian, so this section has been removed.
activate the trigger. In that case, it can be done by calling
``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
maintainer script after creating, modifying, or removing the file.
+
+.. index::
+   pair: signaling; reboot
+
+.. _s-signalingreboot
+
+Signaling that a reboot is required

Bug#919507: Reboot required patch for Debian policy

[Sean Whitton]

Hello Karl,

Thank you for the updated patch.

On Sat 19 Jan 2019 at 05:33PM -0600, Karl O. Pinc wrote:

>> Are you sure that adding the package name to the .pkgs file is
>> required? I've not seen that file on my system; it seems that only
>> /run/reboot-required is used.  Balint said that the .pkgs is an Ubuntu
>> thing; are you sure it has been upstreamed into Debian?
>
> Yes:
> https://sources.debian.org/src/unattended-upgrades/1.9/kernel/postinst.d/unattended-upgrades/#L10
>
> I can't say what's _required_.  I'm following Balint's wording.

Okay.

> It is clear to me that a reboot will occur whenever
> /var/run/reboot-required exists, regardless of the
> state of /var/run/reboot-required.pkgs.
>
> It is not clear to me where reboot-required.pkgs is used.

Your current patch suggests that the purpose of reboot-required.pkgs is
to inform users of which package needs a reboot.  I take it this is your
guess as to the file's purpose?  How sure are you about this?  We
shouldn't write something in Policy that we don't properly understand.

> +To inform users as to which package(s)
> +require a reboot, add the name of the package(s) requiring the reboot
> +to ``/run/reboot-required.pkgs``. Programs should not add a package
> +name to ``/run/reboot-required.pkgs`` if it is already present there.

I suggest "It is conventional to append the package name to
``/run/reboot-required.pkgs``" to avoid saying what the file is for,
since we're not sure.

> +An expected time to signal that a reboot is required is upon
> +installation or upgrade of a package.  Signaling is called for when a
> +reboot is needed to fully apply the changes a package introduces.  The
> +appropriate place to manipulate reboot related files is expected to be
> +in the ``postinst`` maintainer script when it is called as ``postinst
> +configure most-recently-configured-version`` because this is when it
> +is known that the package successfully installed and configured.

Expressions like "expected" and "is called for" sound like they are
normative, but it seems like your aim in this paragraph is to describe
the purpose of a feature, rather than to specify how it may and may not
be used.  Let's try to avoid giving the impression of normativity.

How about:

The ``/run/reboot-required`` mechanism is used when a reboot is
needed to fully apply the changes introduced by a package
installation or upgrade.  Typically it is the ``postinst``
maintainer script that touches ``/run/reboot-required``, at the end
of a successful configuration of the package.

> +Note that the Operating System is not guaranteed to act on these
> +files.  When, and whether, a reboot occurs is dependent upon the
> +installation and configuration of a package which provides a reboot
> +feature.  The same is true of user notifications involving reboot.

It seems obvious that touching ``/run/reboot-required`` does not trigger
a reboot, and typical Debian systems never reboot by themselves.  IMO
this paragraph is unnecessarily verbose.  How about:

There are no guarantees provided by the ``/var/reboot-required``
convention as to when the required reboot will occur.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

On Sat, 19 Jan 2019 11:10:09 -0700
Sean Whitton  wrote:

> On Fri 18 Jan 2019 at 12:04PM -0600, Karl O. Pinc wrote:

> > +Maintainer scripts can signal that a reboot is required to fully
> > apply +the changes to the system by touching
> > ``/run/reboot-required`` and +adding the package name to
> > ``/run/reboot-required.pkgs``. Maintainer +scripts should not add
> > the package name to +``/run/reboot-required.pkgs`` if it is already
> > present there.  
> 
> Are you sure that adding the package name to the .pkgs file is
> required? I've not seen that file on my system; it seems that only
> /run/reboot-required is used.  Balint said that the .pkgs is an Ubuntu
> thing; are you sure it has been upstreamed into Debian?

Yes:
https://sources.debian.org/src/unattended-upgrades/1.9/kernel/postinst.d/unattended-upgrades/#L10

I can't say what's _required_.  I'm following Balint's wording.

It is clear to me that a reboot will occur whenever
/var/run/reboot-required exists, regardless of the
state of /var/run/reboot-required.pkgs.

It is not clear to me where reboot-required.pkgs is used.
But see:
 https://codesearch.debian.net/search?q=run%2Freboot-required.pkgs

(Returns:
 lynis, unattended-upgrades, hobbit-plugins, reboot-notifier, kubernetes
)

I am adding some wording about the purpose of reboot-required.pkgs,
based on the results of the above search.

I'm also adding wording which says that the OS may or may not
actually reboot.

> > +
> > +The appropriate place to do this is expected to be when the
> > +``postinst`` script is called as ``postinst configure
> > +most-recently-configured-version``.
> > +
> > +Ordinary programs may manipulate these files to signal that a
> > reboot +is required.
> > +  
> 
> This is a bit awkward.  You describe this feature in terms of
> maintainer scripts and then say that programs can use it too.  It
> would be better to put it in ch. 9 or ch. 10, I think, and describe
> it in more general terms.

All right.  I'll put it in ch 9 at the bottom.  I think it belongs
there _and_ it won't mess with section numbering.

(I had had it in the middle of chapter 6 because it seemed
an appropriate place -- before all the details.)

Attached is reboot_required_v4.patch

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein

P.S.  Never changing section numbering seems a hard row to hoe.

diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 59c92ec..78d3136 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -1040,3 +1040,39 @@ Debian, so this section has been removed.
activate the trigger. In that case, it can be done by calling
``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
maintainer script after creating, modifying, or removing the file.
+
+.. index::
+   pair: signaling; reboot
+
+.. _s-signalingreboot
+
+Signaling that a reboot is required
+---
+
+.. index::
+   single: reboot-required
+   single: reboot-required.pkgs
+
+Programs can signal that a reboot is required by ``touch``\ing
+``/run/reboot-required``.  To inform users as to which package(s)
+require a reboot, add the name of the package(s) requiring the reboot
+to ``/run/reboot-required.pkgs``. Programs should not add a package
+name to ``/run/reboot-required.pkgs`` if it is already present there.
+
+.. index:
+   single: postinst
+
+An expected time to signal that a reboot is required is upon
+installation or upgrade of a package.  Signaling is called for when a
+reboot is needed to fully apply the changes a package introduces.  The
+appropriate place to manipulate reboot related files is expected to be
+in the ``postinst`` maintainer script when it is called as ``postinst
+configure most-recently-configured-version`` because this is when it
+is known that the package successfully installed and configured.
+
+Note that the Operating System is not guaranteed to act on these
+files.  When, and whether, a reboot occurs is dependent upon the
+installation and configuration of a package which provides a reboot
+feature.  The same is true of user notifications involving reboot.
+
+

Bug#919507: Reboot required patch for Debian policy

[Sean Whitton]

Hello Karl,

Thank you for your patch!

On Fri 18 Jan 2019 at 12:04PM -0600, Karl O. Pinc wrote:

> +Signaling that a reboot is required
> +---

By inserting the text here you will cause other sections of Policy to be
renumbered.  It should be added later in the chapter to avoid that.  But
don't worry, I can fix that when applying the patch.

> +Maintainer scripts can signal that a reboot is required to fully apply
> +the changes to the system by touching ``/run/reboot-required`` and
> +adding the package name to ``/run/reboot-required.pkgs``. Maintainer
> +scripts should not add the package name to
> +``/run/reboot-required.pkgs`` if it is already present there.

Are you sure that adding the package name to the .pkgs file is required?
I've not seen that file on my system; it seems that only
/run/reboot-required is used.  Balint said that the .pkgs is an Ubuntu
thing; are you sure it has been upstreamed into Debian?

> +
> +The appropriate place to do this is expected to be when the
> +``postinst`` script is called as ``postinst configure
> +most-recently-configured-version``.
> +
> +Ordinary programs may manipulate these files to signal that a reboot
> +is required.
> +

This is a bit awkward.  You describe this feature in terms of maintainer
scripts and then say that programs can use it too.  It would be better
to put it in ch. 9 or ch. 10, I think, and describe it in more general
terms.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

On Fri, 18 Jan 2019 09:35:05 -0300
Felipe Sateler  wrote:

> /var/run is a compatibility symlink to /run. This paragraph should
> reference /run directly.

Fixed in attached patch: reboot_required_v3.patch

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 707f2d4..fe39c56 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -92,6 +92,31 @@ for failure, since the package management system looks for the exit
 status of these scripts and determines what action to take next based on
 that datum.
 
+.. index::
+   pair: signaling; reboot
+
+.. _s-signalingreboot
+
+Signaling that a reboot is required
+---
+
+.. index::
+   single: reboot-required
+   single: reboot-required.pkgs
+
+Maintainer scripts can signal that a reboot is required to fully apply
+the changes to the system by touching ``/run/reboot-required`` and
+adding the package name to ``/run/reboot-required.pkgs``. Maintainer
+scripts should not add the package name to
+``/run/reboot-required.pkgs`` if it is already present there.
+
+The appropriate place to do this is expected to be when the
+``postinst`` script is called as ``postinst configure
+most-recently-configured-version``.
+
+Ordinary programs may manipulate these files to signal that a reboot
+is required.
+
 .. _s-mscriptsinstact:
 
 Summary of ways maintainer scripts are called

Bug#919507: Reboot required patch for Debian policy

[Felipe Sateler]

On Thu, 17 Jan 2019 16:13:19 -0600 "Karl O. Pinc"  wrote:

> diff --git a/policy/ch-maintainerscripts.rst
> b/policy/ch-maintainerscripts.rst index 707f2d4..5942123 100644 ---
> a/policy/ch-maintainerscripts.rst +++ b/policy/ch-maintainerscripts.rst
> @@ -92,6 +92,32 @@ for failure, since the package management system looks
for the exit
>  status of these scripts and determines what action to take next based
>  on that datum.
>
> +.. index::
> +   pair: signaling; reboot +
> +.. _s-signalingreboot +
> +Signaling that a reboot is required
> +---
> +
> +.. index::
> +   single: reboot-required +   single: reboot-required.pkgs +
> +Maintainer scripts can signal that a reboot is required to fully apply
> +the changes to the system by touching ``/var/run/reboot-required`` and
> +adding the package name to
> +``/var/run/reboot-required.pkgs``. Maintainer scripts should not add
> +the package name to ``/var/run/reboot-required.pkgs`` if it is already
> +present there.

/var/run is a compatibility symlink to /run. This paragraph should
reference /run directly.

Saludos,

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

Hi,

Attached is: reboot_required_v2.patch

On Thu, 17 Jan 2019 09:10:16 -0600
"Karl O. Pinc"  wrote:

> Documents /var/run/reboot-required and
> /var/run/reboot-required.pkgs.

Like v1 of the patch but adds index entries.
It's not clear if this is desirable because
they would be the only index entries.

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 707f2d4..5942123 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -92,6 +92,32 @@ for failure, since the package management system looks for the exit
 status of these scripts and determines what action to take next based on
 that datum.
 
+.. index::
+   pair: signaling; reboot
+
+.. _s-signalingreboot
+
+Signaling that a reboot is required
+---
+
+.. index::
+   single: reboot-required
+   single: reboot-required.pkgs
+
+Maintainer scripts can signal that a reboot is required to fully apply
+the changes to the system by touching ``/var/run/reboot-required`` and
+adding the package name to
+``/var/run/reboot-required.pkgs``. Maintainer scripts should not add
+the package name to ``/var/run/reboot-required.pkgs`` if it is already
+present there.
+
+The appropriate place to do this is expected to be when the
+``postinst`` script is called as ``postinst configure
+most-recently-configured-version``.
+
+Ordinary programs may manipulate these files to signal that a reboot
+is required.
+
 .. _s-mscriptsinstact:
 
 Summary of ways maintainer scripts are called

Bug#919507: Reboot required patch for Debian policy

[Karl O. Pinc]

Hi,

Attached is: reboot_required_v1.patch

Documents /var/run/reboot-required and
/var/run/reboot-required.pkgs.

Regards,

Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 707f2d4..76adcf3 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -92,6 +92,25 @@ for failure, since the package management system looks for the exit
 status of these scripts and determines what action to take next based on
 that datum.
 
+.. _s-signalingreboot
+
+Signaling that a reboot is required
+---
+
+Maintainer scripts can signal that a reboot is required to fully apply
+the changes to the system by touching ``/var/run/reboot-required`` and
+adding the package name to
+``/var/run/reboot-required.pkgs``. Maintainer scripts should not add
+the package name to ``/var/run/reboot-required.pkgs`` if it is already
+present there.
+
+The appropriate place to do this is expected to be when the
+``postinst`` script is called as ``postinst configure
+most-recently-configured-version``.
+
+Ordinary programs may manipulate these files to signal that a reboot
+is required.
+
 .. _s-mscriptsinstact:
 
 Summary of ways maintainer scripts are called