Bug#40766: [PROPOSED] Rewrite of "Configuration files" section
package: debian-policy
version: 3.0.0.0
The configuration files section has long needed correction
and clarification. I propose we replace the existing section
(currently 4.7) with the following text. (I don't think I've
made any substantiative changes to actual policy, but I may
have shaded some borderline issues to be more to my liking.
This is all based on discussions in debian-policy from
April '98, subject "conffiles version configuration files"
(http://www.debian.org/Lists-Archives/debian-policy-9804/msg00076.html)
and late November/early December '98, subject
"Fix bad advice about conffile management"
(http://www.debian.org/Lists-Archives/debian-policy-9811/msg00223.html).
Some of the text was taken IanJ's message in the first thread.
I'd be glad to see corrections and critiques; it's long past time that
we got this section right (mostly my fault, since I volunteered to do it
about 6 months ago).
(note to Manoj and the other policy editors: I actually modified the
sgml source, and will keep it up to date as people make suggestions, and
will submit it to you if this proposal is accepted.)
=====================================================================
4.7. Configuration files
------------------------
4.7.1. Definitions
------------------
configuration file
A file that affects the operation of program, or provides site-
or host-specific information, or otherwise customizes the
behavior of program. Typically, configuration files are intended
to be modified by the system administrator (if needed or desired)
to conform to local policy or provide more useful site-specific
behavior.
conffile
A file listed in a package's `conffiles' file, and is treated
specially by dpkg (See the _Debian Packaging Manual_).
The distinction between these two is important; they are not
interchangeable concepts. Almost all conffiles are configuration
files, but many configuration files are not conffiles.
Note that a script that embeds configuration information (such as most
of the files in `/etc/init.d' and `/etc/cron.{hourly,weekly,monthly}')
is de-facto a configuration file and should be treated as such.
4.7.2. Location
---------------
Any configuration files created or used by your package should reside
in `/etc'. If there are several you should consider creating a
subdirectory of `/etc' named after your package.
If your packages creates or uses configuration files outside of
`/etc', and it is not feasible to modify the package to use the
`/etc', you should still put the files in `/etc' and create symbolic
links to those files from the location that the package requires.
4.7.3. Behavior
---------------
Configuration file handling must conform to the following behavior:
* local changes must be preserved during a package upgrade
* configuration files should be preserved when the package is
removed, and only deleted when the package is purged.
The easy way to achieve this behavior is to make the configuration
file a conffile. This is appropriate 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).
The other way to do it is to 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 write scripts which
correctly create, update, maintain and remove-on-purge the file. 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 otherwise be good citizens.
The scripts need not 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/doc if they are examples or
/usr/lib if they are templates, and should be perfectly ordinary
dpkg-handled files (_not_ conffiles).
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.
4.7.4. Sharing configuration files
----------------------------------
Only packages that are tagged _conflicting_ with each other may
specify the same file as `conffile'.
A package may not modify a conffile of another package.
If two or more packages use the same configuration file and it is
reasonable for both to be installed at the same time, one of these
packages must be defined as _owner_ of the configuration file, i.e. it
will be the package to list that distributes the file and lists it as
a `conffile'. Other packages that use the configuration file should
depend on the owning package if they require the configuration file to
operate. If the other package will use the configuration file if
present, but is capable of operating without it, no dependency need be
declared.
If it is desirable for two or more related packages to share a
configuration file _and_ for all of the related packages to be able to
modify that configuration file, then the following should done:
1. have one of the related packages (the "core" package) manage the
configuration file with maintainer scripts as described in the
previous section.
2. the core package should also provide a program that the other
packages may use to modify the configuration file.
3. the related packages must use the provided program to make any
modifications to the configuration file. They should either
depend on the core package to guarantee that the configuration
modifier program is available or accept gracefully that they
cannot modify the configuration file if it is not.
Sometimes it's appropriate to create a new package which provides the
basic infrastructure for the other packages and which manages the
shared configuration files. (Check out the `sgml-base' package as an
example.)
4.7.5. User configuration files ("dotfiles")
--------------------------------------------
Files in `/etc/skel' will automatically be copied into new user
accounts by `adduser'. They should not be referenced there by any
program.
Therefore, if a program needs a dotfile to exist in advance in `$HOME'
to work sensibly that dotfile should be installed in `/etc/skel' (and
listed in conffiles, if it is not generated and modified dynamically
by the package's installation scripts).
However, programs that require dotfiles in order to operate sensibly
(dotfiles that they do not create themselves automatically, that is)
are a bad thing, and programs should be configured by the Debian
default installation as close to normal as possible.
Therefore, if a program in a Debian package needs to be configured in
some way in order to operate sensibly that configuration should be
done in a site-wide global configuration file elsewhere in `/etc'.
Only if the program doesn't support a site-wide default configuration
and the package maintainer doesn't have time to add it should a
default per-user file be placed in `/etc/skel'.
`/etc/skel' should be as empty as we can make it. This is particularly
true because there is no easy mechanism for ensuring that the
appropriate dotfiles are copied into the accounts of existing users
when a package is installed.
=====================================================================
Reply to: