(debian-policy.info)Behavior

---

Next: Sharing configuration files Prev: Location Up: Configuration files

---

Enter node , (file) or (file)node

10.7.3 Behavior
---------------

Configuration file handling must conform to the following behavior:

   - local changes must be preserved during a package upgrade, and

   - configuration files must be preserved when the package is removed,
     and only deleted when the package is purged.

Obsolete configuration files without local changes should be removed by
the package during upgrade.  (1)

The easy way to achieve this behavior is to make the configuration file
a ‘conffile’.  This is appropriate only if it is possible to distribute
a default version that will work for most installations, although some
system administrators may choose to modify it.  This implies that the
default version will be part of the package distribution, and must not
be modified by the maintainer scripts during installation (or at any
other time).

In order to ensure that local changes are preserved correctly, no
package may contain or make hard links to conffiles.  (2)

The other way to do it is via the maintainer scripts.  In this case, the
configuration file must not be listed as a ‘conffile’ and must not be
part of the package distribution.  If the existence of a file is
required for the package to be sensibly configured it is the
responsibility of the package maintainer to provide maintainer scripts
which correctly create, update and maintain the file and remove it on
purge.  (See Note: Package maintainer scripts and installation
procedure. for more information.)  These scripts must be idempotent
(i.e., must work correctly if ‘dpkg’ needs to re-run them due to errors
during installation or removal), must cope with all the variety of ways
‘dpkg’ can call maintainer scripts, must not overwrite or otherwise
mangle the user’s configuration without asking, must not ask unnecessary
questions (particularly during upgrades), and must otherwise be good
citizens.

The scripts are not required to configure every possible option for the
package, but only those necessary to get the package running on a given
system.  Ideally the sysadmin should not have to do any configuration
other than that done (semi-)automatically by the ‘postinst’ script.

A common practice is to create a script called ‘package-configure’ and
have the package’s ‘postinst’ call it if and only if the configuration
file does not already exist.  In certain cases it is useful for there to
be an example or template file which the maintainer scripts use.  Such
files should be in ‘/usr/share/package’ or ‘/usr/lib/package’ (depending
on whether they are architecture-independent or not).  There should be
symbolic links to them from ‘/usr/share/doc/package/examples’ if they
are examples, and should be perfectly ordinary ‘dpkg’-handled files
(`not' configuration files).

These two styles of configuration file handling must not be mixed, for
that way lies madness: ‘dpkg’ will ask about overwriting the file every
time the package is upgraded.

   ---------- Footnotes ----------

   (1) The ‘dpkg-maintscript-helper’ tool, available from the dpkg
package, can help for this task.

   (2) Rationale: There are two problems with hard links.  The first is
that some editors break the link while editing one of the files, so that
the two files may unwittingly become unlinked and different.  The second
is that ‘dpkg’ might break the hard link while upgrading ‘conffile’s.