Bug#40766: marked as done ([PROPOSED] Rewrite of "Configuration files" section)
Your message dated Sat, 6 Nov 1999 21:13:58 +0000 (GMT)
with message-id <E11kD9q-0000Vf-00@polya>
and subject line Fixed in debian-policy 3.1.0.0
has caused the attached Bug report to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere. Please contact me immediately.)
Darren Benham
(administrator, Debian Bugs database)
--------------------------------------
Received: (at submit) by bugs.debian.org; 5 Jul 1999 04:17:39 +0000
Received: (qmail 8103 invoked by alias); 5 Jul 1999 04:17:39 -0000
Delivered-To: bugs@debian.org
Received: (qmail 8096 invoked from network); 5 Jul 1999 04:17:37 -0000
Received: from adsl-216-62-156-206.dsl.hstntx.swbell.net (HELO molehole.sg) (mail@216.62.156.206)
by master.debian.org with SMTP; 5 Jul 1999 04:17:37 -0000
Received: from steveg by molehole.sg with local (Exim 2.05 #1 (Debian))
id 1110C6-0007ix-00; Sun, 4 Jul 1999 23:17:26 -0500
Date: Sun, 4 Jul 1999 23:17:26 -0500
From: Steve Greenland <stevegr@debian.org>
To: bugs@debian.org
Subject: [PROPOSED] Rewrite of "Configuration files" section
Message-ID: <19990704231725.A29644@molehole>
Reply-To: Steve Greenland <stevegr@debian.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Mailer: Mutt 0.95.3i
Organization: Not my strong point
Sender: Steve Greenland <steveg@molehole.dhis.org>
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.
=====================================================================
---------------------------------------
Received: (at 40766-done) by bugs.debian.org; 6 Nov 1999 21:31:44 +0000
Received: (qmail 17140 invoked from network); 6 Nov 1999 21:15:11 -0000
Received: from mserv1c.u-net.net (195.102.240.33)
by master.debian.org with SMTP; 6 Nov 1999 21:15:11 -0000
Received: from [195.102.196.44] (helo=polya)
by mserv1c.u-net.net with esmtp (Exim 2.10 #35)
id 11kD9x-0005Qp-00; Sat, 6 Nov 1999 21:14:05 +0000
Received: from jdg by polya with local (Exim 3.03 #1 (Debian))
id 11kD9q-0000Vf-00; Sat, 06 Nov 1999 21:13:58 +0000
Subject: Fixed in debian-policy 3.1.0.0
To: 8221-done@bugs.debian.org, 17621-done@bugs.debian.org,
19179-done@bugs.debian.org, 24695-done@bugs.debian.org,
32448-done@bugs.debian.org, 32449-done@bugs.debian.org,
33076-done@bugs.debian.org, 40766-done@bugs.debian.org,
40767-done@bugs.debian.org, 41095-done@bugs.debian.org,
41121-done@bugs.debian.org, 41232-done@bugs.debian.org,
41547-done@bugs.debian.org, 41829-done@bugs.debian.org,
42358-done@bugs.debian.org, 42447-done@bugs.debian.org,
42849-done@bugs.debian.org, 43651-done@bugs.debian.org,
44620-done@bugs.debian.org, 44643-done@bugs.debian.org,
44922-done@bugs.debian.org, 45307-done@bugs.debian.org,
45318-done@bugs.debian.org, 45561-done@bugs.debian.org,
46516-done@bugs.debian.org, 48570-done@bugs.debian.org
Date: Sat, 6 Nov 1999 21:13:58 +0000 (GMT)
X-Mailer: ELM [version 2.4ME+ PL60 (25)]
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Message-Id: <E11kD9q-0000Vf-00@polya>
From: Julian Gilbey <J.D.Gilbey@qmw.ac.uk>
These bugs have been fixed in debian-policy 3.1.0.0; changelog follows.
Julian
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Julian Gilbey, Dept of Maths, QMW, Univ. of London. J.D.Gilbey@qmw.ac.uk
Debian GNU/Linux Developer, see http://www.debian.org/~jdg
Changes: debian-policy (3.1.0.0) unstable; urgency=low
.
* Add instructions on /usr/doc -> /usr/share/doc symlinks (closes:
#45561, #42447, #48570)
* Added source dependencies (closes: #41232)
* Deprecated /etc/rc.boot (closes: #32448, #32449)
* Update-rc.d now only legal way to automatically access /etc/rc?.d
directoried (closes: #41547)
* FHS compliant location of examples (closes: #42849)
* Added ispell-dictionary to virtual-packages.list (following new
suggestions: no objections => accept) (closes: #8221)
* Added man-browser to virtual-packages.list (closes: #24695)
* Added ident-server to virtual-packages.list (closes: #45307)
* Alphabeticised virtual packages list ;)
* Corrected GPL reference in proposal.sgml
* Clarification of "extra" priority (closes: #33076)
* Remove buggy and seriously problematic licenses from list of contrib
package criteria (closes: #45318)
* Move docs to /usr/share/doc with a compatibility symlink (closes:
#41829)
* Update to FHS 2.1 draft #3 (for /var/state etc. changes).
* Correct /var/lib/games -> /var/games (closes: #42358)
* Added MIME subpolicy (closes: #46516)
* Added support for VISUAL (closes: #41121)
* Clarify non-dependence on /usr/local (closes: #44922)
* Modified description of mail spool locking (closes: #43651)
* Clarified wording of conffiles and configuration files (closes:
#40766, #40767)
* Changed description of release numbers (closes: #44620)
* Added changelog.html -> changelog requirement (closes: $40934)
* packaging-manual now correctly installs its docs (closes: #44643)
* The packaging manual now discusses version numbers based on dates
(closes: #17621)
* Mention ls -f for testing order in which files appear on disk (closes:
#19179)
* Change order of '.' and '+' in description of version numbers (closes:
#41095)
* s/fields/field names/ in section 4.1 of packaging manual for clarity
* Add Build-Depends-Indep: field to control file
Reply to: