As discussed on debian-devel starting at [1], I would like a comment
added to Section 6.4 "Best practices for maintainer scripts" that
recommends preventing the postinst script from returning failure when a
service fails to start.

A general rule of thumb is that if the corrective action would not
otherwise require re-running dpkg, then the postinst should behave as if
the installation succeeded.

An example of a case where postinst should succeed is if the admin,
prior to an upgrade, modified a configuration file which resulted in the
service being unable to restart during the upgrade.

Another example is if the service requires another resource to be
available that might be on another machine (e.g. a database).

The rational is that the failure has nothing to do with the installation
process or the contents of the .deb.  The service might just as well
have failed on reboot even though it was correctly installed.

I will send a follow-up message that contains a condensed digest of the
thread beginning at [1].

...Marvin

[1] https://lists.debian.org/debian-devel/2015/09/msg00496.html

    Marvin> As discussed on debian-devel starting at [1], I would like a
    Marvin> comment added to Section 6.4 "Best practices for maintainer
    Marvin> scripts" that recommends preventing the postinst script from
    Marvin> returning failure when a service fails to start.

I strongly support this practice.

    Marvin> As discussed on debian-devel starting at [1], I would like a
    Marvin> comment added to Section 6.4 "Best practices for maintainer
    Marvin> scripts" that recommends preventing the postinst script from
    Marvin> returning failure when a service fails to start.

I strongly support this practice.

Here is a condensation of the discussion prior to filing this bug.  I
have removed all quotes of previous messages (e.g. msg [2] contained
quotes from msg [1] that have been removed).  I have tried to identify
when a message is a reply to parts of several messages or to a message
that is not the previous message in this digest.  When in doubt, refer
to the original message.

[1] https://lists.debian.org/debian-devel/2015/09/msg00496.html
* Marvin Renich <mrvn@renich.org> [150923 13:53]:

[2] https://lists.debian.org/debian-devel/2015/09/msg00508.html
* Jeroen Dekkers <jeroen@dekkers.ch> [150924 07:23]:

[3] https://lists.debian.org/debian-devel/2015/09/msg00511.html
* Marvin Renich <mrvn@renich.org> [150924 08:12]:

[4] https://lists.debian.org/debian-devel/2015/09/msg00518.html
* Henrique de Moraes Holschuh <hmh@debian.org> [150924 12:21]:

[5] https://lists.debian.org/debian-devel/2015/09/msg00519.html
* Paul Gevers <elbrus@debian.org> [150924 14:12]:

[6] https://lists.debian.org/debian-devel/2015/09/msg00525.html
* Marvin Renich <mrvn@renich.org> [150925 08:27]:

[7] https://lists.debian.org/debian-devel/2015/09/msg00532.html
* Eduard Bloch <edi@gmx.de> [150926 05:25]:

[8] https://lists.debian.org/debian-devel/2015/09/msg00542.html
* Jeroen Dekkers <jeroen@dekkers.ch> [150926 09:44]:

Sam Hartman <hartmans@debian.org> writes:

I'm also in favor.  However, this is a very substantial change to Debian
practice, and I'm not sure what process should be used for making this
kind of decision.  This wasn't a gap in our specification; rather, the
previous standard was explicitly chosen (by at least some folks).  Failure
to install was intentional and believed better since it didn't hide
service failures.

I feel like this would benefit from a broader discussion than just the
Policy list, but I'm not sure how to go about that, or what teams in
particular should weigh in.

But it had the major drawback that you could not fix the issue when the fix
required to install more packages, which is common.

So I am also in favor.

Cheers,

Yeah, but there's a significant factor that reduces things somewhat.
In the past, /etc/init.d/foo failing would often cause postinst to
break.
However, in the past, there were a lot of failures that were not
detected by the init.d script.
We have two intentional decisions conflicting:

1) systemd tries to be a lot better about reporting service status than
our previous infrastructure

2) We had the decision on a number of people to not hide failures by
causing installation to fail.

I actually think the folks in category 2 weren't typically hiding a lot
of service failures, because  it was fairly common for the init script
to mask that, but it did tend to hide failures like missing
configuration files etc.

I certainly know that when deploying units for krb5 I had to mask a
bunch more failures to get behavior consistent with the previous
packages.

Given the above, I think a discussion on -devel (which has happened) and
a discussion on-policy is sufficient.

* Russ Allbery <rra@debian.org> [151005 18:24]:

I understand that this was intentional, but it is not the only way to
make sure the user (admin) is informed of the failure.

It was suggested in the discussion on d-devel that some other
notification mechanism could be implemented instead of installation
failure.

I was thinking about a special dpkg trigger that would be handled
internally by dpkg.  Packages would, in their postinst, place a file
containing non-fatal but important failure information in a directory
owned by dpkg.  This info would be printed out by dpkg at the end of the
run, and would also be passed to front ends that asked.

Front ends such as aptitude could ask dpkg for these notifications.  If
a large installation needed to be split into multiple calls to dpkg, the
front end can aggregate the notifications and present them all at the
very end, in whatever way is native to the front end.

One of the other notifications that I, personally, would like to see
this used for is when a configuration file has changes that cannot be
handled automatically.  Currently you are asked in the middle of the
installation; this would not change at all.  But it would be nice to
have a summary at the end of all the config files that had incompatible
changes, regardless of how I answered the dpkg or ucf prompt.

The discussion started on d-devel; should it be moved back there?  The
overwhelming majority of opinion seems to be in favor of the change.

...Marvin

We have supported per-package behavior on this for a very long time,
maybe since forever (this is no joke).  We have had packages that
restart after the upgrade instead of stopping before, or that ignore
service start failures during upgrades for *years*.

All it takes is that the package maintainer actually stop to think about
it, consider which behavior is more appropriate to that specific
package, and adjust things appropriately.  There is a damn good reason
why policy does not use "must" to mandate service start/stop/restart
behavior across package updates.

The reason for this thread, an "undesired" behavior of stopping a
package upgrade if the service fails to start, which is the current
default, is both employed by the (likely few) packages that absolutely
depend on it to avoid worse damage down the service/package dependency
chain, as well as by packages that the maintainer did not even think
about the issue (and therefore might or might not need this behavior).

IMO, we should not just "change this default" in the *implementation*
(debhelper, etc), at least not without actually acessing the real risk
of the change.  It does not look like this kind of risk accessment was
done by anyone yet in the d-devel thread.  Just because we expect it to
be low, doesn't mean it doesn't exist or that it won't have a high
impact on the user if it happens.

If the need for this kind of provision in a possible policy text update
(possibly as a foot-note) is contentious, IMHO the matter needs to go
back to d-devel for further discussion.

* Henrique de Moraes Holschuh <hmh@debian.org> [151007 09:42]:

Agreed.

I enthusiastically agree!

Again, agreed.  I was not proposing to use "must", and would not support
such a proposal.

Right.  And the second case, which is at least perceived by me (and
apparently others) to be the vast majority of services, is what this
proposal is about.

Actually, I was not aware that dh had a helper for this that defaulted
to "fail upgrade if service fails", and so was not intending to propose
an automatic change in behavior based on a change to dh.  This part of
it certainly requires more thought and a thorough risk assessment.

My proposal, and what I still think we should do regardless of any
change or lack of change to dh, is to document, in a place that package
maintainers will see, that the "best practice" is to not fail the
install just because the service fails to start.

I don't see this as a contentious change; at least the part about
changing what is considered "best practice".  Changing dh hasn't, as far
as I can see, been discussed enough to know whether it is contentious or
not.  But, as you point out, a risk assessment followed by some
discussion on d-devel would be the first two steps.

I don't think a documentation change to "best practices" should be held
up by the dh issue.  Perhaps someone wants to clone this bug to the
debhelper package so the documentation change to developers-reference
and the potential implementation change to debhelper are tracked
independently.  If you would like me to do so, let me know.

...Marvin

control: tags -1 +moreinfo
thanks

hi,

I don't think there has been consent on the issue, thus I'm tagging it
moreinfo.

I'm also wondering whether to mark this bug as wontfix (until there is
consent) or to reassign to debian-policy or simply to close it.

    Holger> I don't think there has been consent on the issue, thus I'm
    Holger> tagging it moreinfo.

My reading of the TC and debian-devel discussion was that this was at
least a reasonable thing for maintainers to do,
and whether it should be done depended on the circumstances.

Holger, would you support adding a comment to 6.4 explaining how to do
it?
I'd write text but I'm honestly baffled how to accomplish this for
systemd units with dh.

* Holger Levsen <holger@layer-acht.org> [230208 08:15]:

I disagree.  Re-reading the messages to the bug report, We have
"strongly support" from Sam Hartman, and "also in favor" from Russ
Allbery and Bill Allombert.

The only objection was from Henrique de Moraes Holschuh based on lack of
risk assessment from the mistaken impression that what was being
proposed was a change to dh that would _automatically_ change existing
behavior of all dh-using packages.

What is being proposed in this bug is simply a change to the Developers
Reference to encourage package maintainers to allow dpkg installation to
succeed even if the service fails to start, unless the package
maintainer has a specific reason to do otherwise.

The bug report appears to me to have reached an overwhelming consensus
in favor.

...Marvin

can you give pointers?

I do agree with that. I'm more against a general recommendation, depending
on the circumstances, it's the right thing to do.

surely.

:)

hi,

btw, as pointed out on irc: I ment consensus, not consent. :)

not only based on that, but way more importantly that this would change
*years* of existing practice.

"patches welcome", especially for something which some perceive as simple
change!

    Holger> I do agree with that. I'm more against a general
    Holger> recommendation, depending on the circumstances, it's the
    Holger> right thing to do.

My recollection is this came before the TC, but I'm blanking on the bug
number.
But it seems like the sticking point is the general recommendation.

I'd love to figure out how to do this though and document for other
people (I have a Ubuntu bug open against krb5 that basically boils down
to this issue).

    >> Holger, would you support adding a comment to 6.4 explaining how
    >> to do it?

    Holger> surely.

    >> I'd write text but I'm honestly baffled how to accomplish this
    >> for systemd units with dh.

    Holger> :)

Marvin, do you have any clue how to accomplish?

The TC bug is 904558.
Busy with day job now.

retitle -1 turn #904558 into advice - how postinst should deal with failures
thanks

thank you very much for this pointer, that's a pretty good discussion,
which resulted in

-----------------------------

So, the TC declines to rule on what should maintscripts do when failing
to
(re)start a service (or otherwise encountering a similarly serious
problem).

-----------------------------
(read the full result at https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=904558#137 )

so I still think "#801065 discourage failing install or upgrade when service
fails to start" is the wrong recommendation for dev-ref.

That said, I'd still appreciate a patch that conveys the gist of #904558.

Could you clarify which 'existing practices' ?

Cheers,

O#n Wed, Feb 08, 2023 at 04:47:37PM +0000, Holger Levsen wrote:

Note that the TC declining to rule on an issue does not override the policy group right to make
a determination on that issue. So we are back to the situation before the referral to the TC.

Cheers,

how Debian packages behaved in the last decades.

do you think #801065 should be assigned from developers-reference to
debian-policy?

FWIW I think that it's the wrong thing to do if the "circumstances" include
reverse-dependencies on the package which expect to interact with the
service the package provides, as these packages may themselves do such
interaction in the maintainer script, resulting in cascading damage.

And the decision for whether there are reverse-dependencies on your package
is non-local and asynchronous.

Therefore I think it's always wrong for a package's postinst to exit 0 if:

 - it ships a service,
 - it is a new install or an upgrade on a system where the service was
   previously started successfully, and
 - the service fails to start in the postinst.

Steve Langasek <vorlon@debian.org> writes:

An interesting problem case is a package whose point is to run a service,
but which requires mandatory and not-automatable setup before the service
can usefully run.  After package installation, the service cannot start.
So the options are either attempt to start the service as normal in the
postinst but ignore the failure, or add some more complex logic to
postinst to attempt to determine whether the service has been set up
properly and only attempt to start the service if it has.

I think our packaging system doesn't handle this case that well.  I can
make good arguments for several possible behavior choices.  But obviously
one cannot have package installation fail because the service cannot be
started when the package has to be installed so that you can configure it
so that the service can start.

Just do not enable the systemd unit for the service by default for such
services.

If an admin has configured and enabled then the service will be
(re)started. If the admin has not done anything then the service will
not be started and there is no error to ignore.

You need to do that for "automatable setup" too if the automation means
debconf as the admin might not have answered to the questions, for
example when the package is installed in an automated setup ;-)

Ansgar

* Steve Langasek <vorlon@debian.org> [230212 00:03]:

I have to strongly disagree with this.  Suppose package A ships a
service, and package B depends on A and requires A's service to be
running in order for package B to be useful.  If I install A and disable
its service, and then install B, I would be very disappointed if B's
postinst script failed and left B in what dpkg considers an unconfigured
state.

Succeeding the install and requiring the user to manually run some
documented configuration steps is _so_ much more user friendly than
leaving a broken package (from dpkg's POV).  I intentionally disabled A,
so when I want to use B, I will take the necessary steps.  I would
expect that attempting to use B without completing the configuration
would produce a useful error message.

Package relationships and the idea of "properly configured" have gotten
much more complex (in a relatively small set of packages) since early
Debian days.  Packages whose configuration has complex requirements
should be installable without complete configuration and should be
resilient and provide good user feedback when run before being properly
set up.

I also think that such packages are the exception, rather than the rule,
and they are usually being administered by people capable of dealing
with postponing the configuration step.

...Marvin

Up until now the conversation has been about the semantics of exit codes for
package A's maintainer script.

You are now arguing that a package *B* is not allowed to fail on install if
the conditions for its full configuration have not been met.

And I absolutely disagree!  Your rationale that it's user-unfriendly to
leave a package in an unconfigured state, if followed to its logical
conclusion, applies to *any* package.  We might as well not care about
postinst exit codes at all!

This is not hyperbolic.  By imposing restrictions on the ability of packages
to raise error conditions, you are forcing the propagation of erroneous
system state up the dependency stack, breaking untold numbers of assumptions
in the reverse-dependencies.  Keeping the error handling *local* and forcing
the admin to correct the error before proceeding is part of what makes
Debian's system robust.

On 'apt dist-upgrade', having a failing maintainer script can be problematic
wrt the package manager's full state.  But there is no such counterargument
wrt robustness for the simple case of an 'apt install foo' failing its
initial configuration because the system preconditions are not met.

They are also capable of dealing with 'apt -f install'.

* Steve Langasek <vorlon@debian.org> [230214 13:09]:

You are right, I went off on a tangent.  I agree that if a package
installation script is unable to leave the package's own configuration
in a "usable" state (barring explicit misconfiguration prior to upgrade
by the sysadmin), that it should fail.

The condition in the original bug report was that the problem that
prevented the service from starting or restarting was orthogonal to
anything the installation script was doing.  In that case, the
installation script will leave the filesystem in an identical state
regardless of whether starting the service succeeds or fails.  The
package is installed and perfectly usable if and when the outside
condition, unrelated to the package installation, is fixed.

In these cases, there is nothing more that the installation scripts can
or should do, so there is no need to leave the package in a dpkg
half-configured state.

I think the real problem is that the ideas of "configured" and "running"
have been conflated specifically for services.  The same type of issue
with a user program would not cause a failure of installation.

The part of your message that I disagree with is

This implies that "the service is running" is part of "the service is
configured", which is where I disagree.

...Marvin

What Steve said is that if

- The service fails to start, *AND*
- The service was previously running (or this is a new install)

*THEN*

this is something that should make postinst fail.

The two preconditions are linked, and should not be looked at
separately.

If the service was *not* previously running, then that is a different
situation.

But if the service was previously running and now a restart fails, then
obviously[1] this is a problem with the upgrade that should be looked at
by the admin, which means it must be flagged to the admin somehow.

As I mentioned in the TC discussion, one can reasonably debate what the
best way is to flag such problems, but I think it's not reasonable to
say "let's just push it under the mat, it doesn't matter".

We currently only have one sure way of telling the admin that there is a
problem, and that is "fail postinst".

As such, I think any suggestion that we ignore a restart failure of a
service that was running before the dpkg run should be accompanied by a
plan on *how* to flag this failure to the admin in a way that the admin
will know that things failed. In the absence of that, the status quo of
"postinst should fail on a restart of a service" should probably be
retained.

[1] barring extreme corner cases of the style "the admin made broken
    changes but forgot to try a restart"

    Wouter> On Wed, Feb 15, 2023 at 02:38:10PM -0500, Marvin Renich wrote:
    >> > > > - the service fails to start in the postinst.
    >>
    >> This implies that "the service is running" is part of "the
    >> service is configured", which is where I disagree.

    Wouter> What Steve said is that if

    Wouter> - The service fails to start, *AND* - The service was
    Wouter> previously running (or this is a new install)

    Wouter> *THEN*

I think I disagree with Steve that postinst should fail on a new
install.

I think that failing postinst on a failed restart during upgrade is more
commonly the correct answer than ignoring the issue.
I also agree that it should be RECOMMENDED that if the restart fails
that be flagged to the admin somehow.

But in the case of krb5 and I think a few other services, there is not a
good way to detect at install time *whether* the service is sufficiently
configured to run from a systemd unit.  I could for example include a
ConditionPathExists on the Kerberos database.  That's wrong though
because in an LDAP deployment there will be no such database.

hello,

devref guidance, section 6.9.4. "Specific types of packages" has some recently
added guidance but is agnostic as to whether postinst should fail:

 * Packages providing services ("daemons") should be functional on a
  fresh install, to the extent that that is possible without
  compromising security [..]

my reading of the bug log is that the guidance needs to be nuanced. here's an
attempt to reconcile the various views in the discussion:

	Package maintainers are expected to apply judgment with regards to which
	postinst behavior is more appropriate to any given package. Here is some
	generic guidance:

	1. a service failing to start upon a fresh install should, in general,
	   fail postinst, if
	  1.1 the service configuration is straightforward and can be reasonably
	      expected to work as-is in typical Debian setups
	  1.2 the service has no external dependencies (e.g. a database which
	      may be not configured yet, or unreachable at the time of the
	      install)

	2. a service failing to restart upon an upgrade should, in general, fail
	  postinst if
	  2.1 postinst can verify with high confidence that the service was
	      running prior to the restart (which may not always be feasible)
	  2.2 the service has no external dependencies or postinst can verify
	      that they are functional
	  2.3 the service configuration has not changed in backwards
	      incompatible ways between the old and new package versions

fwiw I wonder whether this would be of much use. "typical Debian setups" is
ambiguous. verifying whether a remote service is unreachable is not always
straightforward. "backwards incompatible" is not always black and white.

thanks,
serafi

hi serafi,

if the postinst of a package fails, this is usually considered an RC bug, usually
detect by piuparts.d.o.

I think this is still useful, despite its not all black and white, maybe
especially because its not black and white.

tags 801065 + patch
tags 801065 - moreinfo
thanks

hi Holger, thanks for the feedback.
[..]

please find a lightly edited version attached as a patch.

thanks,
serafi

hi Serafi.

thanks for the updated patch. What I still miss is the information first,
that postinst scripts normally must not fail. Or is it there and just missing
from the patch/context?

hi Holger,

nope, you're right. please find attached a revised patch.

thanks,
serafi

Hi Serafi,

thanks, better, however:

I'd add the information here that it makes the package seriously buggy
if the package fails to install due to this, eg in piuparts testing but
also in other cases.
[...]
[...]

Honestly I fail to parse the English here, though from context of the bug
report I do get what you mean with these constructs.

Also, I dont think "a package is clearly broken" is correct, its the environment
or something else which is broken, not the package.

So how about something like:

``postinst`` scripts must normally not fail, except for very rare cases:

- failing to start upon a fresh install when:
   - the service configuration is straightforward and can be reasonably
     expected to work as-is in typical Debian setups
   - the service has no external dependencies (e.g. a database which may not
     yet be configured, or unreachable at install time)

NOTE: and now I see these are conditions when the packages must NOT fail.

So another attempt:


``postinst`` scripts must normally not fail, except for very rare cases.
These are cases where postinst must succeed:

on fresh installs:
   - the service configuration is straightforward and can be reasonably
     expected to work as-is in typical Debian setups
   - the service has no external dependencies (e.g. a database which may not
     yet be configured, or unreachable at install time)

on upgrades:
   - ``postinst`` can verify with high confidence (which may not always be
     feasible) that the service was running prior to the restart
   - the service has no external dependencies or ``postinst`` can verify that
     they are functional
   - the service configuration has not changed in backwards incompatible ways
     between the old and new package versions


what do you think?

On Sat Jun 13, 2026 at 11:01 AM CEST, Holger Levsen wrote:
[..]
[..]

that is definitely better :)