Bug#40767: [PROPOSED] wording cleanup w.r.t. conffile/configuration file
package: debian-policy
version: 3.0.0.0
(NOTE: This is not a repeat of of 'Bug#40766: [PROPOSED] Rewrite of
"Configuration files" section')
This proposal is to clean up the wording of several sections in the
document that discuss "conffiles" and "configuration files", as well
as a few other minor rewordings that I noted on the way. The path I
took was to change almost all of the references to "mark (or tag) as a
conffile" to "treat as a configuration file", based on my belief that
*any* configuration file should have consistent behavior (local mods
preserved, not removed except when the package is purged, etc.), and
that dpkg's "conffile" mechanism is simply a way to conveniently achieve
this. By using "treat as a configuration file", this allows a package to
(for example) create its /etc/init.d/<package> file during installation,
if it so desires, so long as the sysadmin can modify it without losing
changes.
I believe these changes are independent of the re-write of section 4.7
"Configuration files", and should be dealt with seperately.
Anyway, here's the (text) diff; I'm also keeping an sgml diff for use
when the proposal is accepted. (Many of the diff sections actually only
vary by a few words in the first couple of lines, but the change in
linelength causes the rest of the paragraph to show different as well.)
================================================================
--- policy.text.orig Sun Jul 4 23:37:54 1999
+++ policy.text Sun Jul 4 23:37:45 1999
@@ -980,11 +980,13 @@
should behave as if the configuration has been reloaded successfully.
These scripts should not fail obscurely when the configuration files
- remain but the package has been removed, as the default in `dpkg' is
- to leave configuration files on the system after the package has been
- removed. Only when it is executed with the `--purge' option will dpkg
- remove configuration files. Therefore, you should include a `test'
- statement at the top of the script, like this:
+ remain but the package has been removed, as configuration files remain
+ on the system after the package has been removed. Only when dpkg is
+ executed with the `--purge' option will configuration files be
+ removed. In particular, the init script itself is usually a
+ configuration file (see Section 3.3.5, `Notes'), and will remain on
+ the system if the package is removed but not purged. Therefore, you
+ should include a `test' statement at the top of the script, like this:
test -f <program-executed-later-in-script> || exit 0
@@ -1054,10 +1056,12 @@
them with `update-rc.d', as above.
_Do not_ include the `/etc/rc<n>.d/*' symbolic links in `dpkg''s
- conffiles list! _This will cause problems!_ _Do_, however, include the
- `/etc/init.d' scripts in conffiles. (This is important since we want
+ conffiles list! _This will cause problems!_ _Do_, however, treat the
+ `/etc/init.d' scripts as configuration files, either by marking them
+ as conffiles or managing them correctly in the maintainer scripts (see
+ Section 4.7, `Configuration files'). (This is important since we want
to give the local system administrator the chance to adapt the scripts
- to the local system--e.g., to disable a service without De-installing
+ to the local system--e.g., to disable a service without de-installing
the package, or to specify some special command line options when
starting a service--while making sure her changes aren't lost during
the next package upgrade.)
@@ -1132,7 +1136,7 @@
3.4. Cron jobs
--------------
- Packages may not touch the configuration file `/etc/crontab', nor may
+ Packages may not modify the configuration file `/etc/crontab', nor may
they modify the files in `/var/spool/cron/crontabs'.
If a package wants to install a job that has to be executed via cron,
@@ -1143,26 +1147,28 @@
/etc/cron.weekly
/etc/cron.monthly
- As these directory names say, the files within them are executed on a
- daily, weekly, or monthly basis, respectively.
-
- If a certain job has to be executed more frequently than `daily,' the
- package should install a file `/etc/cron.d/<package-name>' tagged as
- configuration file. This file uses the same syntax as `/etc/crontab'
- and is processed by `cron' automatically. (Note, that scripts in the
- `/etc/cron.d' directory are not handled by `anacron'. Thus, you should
- only use this directory for jobs which may be skipped if the system is
- not running.)
+ As these directory names imply, the files within them are executed on
+ a daily, weekly, or monthly basis, respectively. The exact times are
+ listed in /etc/crontab.
All files installed in any of these directories have to be scripts
(shell scripts, Perl scripts, etc.) so that they can easily be
- modified by the local system administrator. In addition, they have to
- be registered as configuration file.
+ modified by the local system administrator. In addition, they must be
+ treated as configuration files.
- The scripts in these directories have to check, if all necessary
- programs are installed before they try to execute them. Otherwise,
- problems will arise when a package was removed (but not purged), since
- the configuration files are kept on the system in this situation.
+ If a certain job has to be executed more frequently than `daily,' the
+ package should install a file `/etc/cron.d/<package-name>'. This file
+ uses the same syntax as `/etc/crontab' and is processed by `cron'
+ automatically. The file must also be treated as a configuration file.
+ (Note, that entries in the `/etc/cron.d' directory are not handled by
+ `anacron'. Thus, you should only use this directory for jobs which may
+ be skipped if the system is not running.)
+
+ The scripts or crontab entries in these directories should check if
+ all necessary programs are installed before they try to execute them.
+ Otherwise, problems will arise when a package was removed but not
+ purged since configuration files are kept on the system in this
+ situation.
3.5. Console messages
@@ -1738,8 +1744,8 @@
this was deemed not enough.
A better scheme is to use logrotate, a GPL'd program developed by Red
- Hat, which centralizes log management. It has both a config file
- (`/etc/logrotate.conf') and a directory where packages can drop
+ Hat, which centralizes log management. It has both a configuration
+ file (`/etc/logrotate.conf') and a directory where packages can drop
logrotation info (`/etc/logrotate.d').
Log files should usually be named `/var/log/<package>.log'. If you
@@ -2082,13 +2088,14 @@
_Application defaults_ files have to be installed in the directory
`/usr/X11R6/lib/X11/app-defaults/'. They are considered as part of the
program code. Thus, they should not be modified and should not be
- tagged as _conffile_s. If the local system administrator wants to
- customize X applications globally, a file with the same name as that
- of the package should be placed in the `/etc/X11/Xresources/'
- directory instead. _Important:_ packages that install files into the
- `/etc/X11/Xresources/' directory _must_ declare a conflict with `xbase
- (<< 3.3.2.3a-2)'; if this is not done it is possible for the package
- to destroy a previously-existing `/etc/X11/Xresources' _file_.
+ tagged as _conffile_s nor otherwise treated as configuration files. If
+ the local system administrator wants to customize X applications
+ globally, a file with the same name as that of the package should be
+ placed in the `/etc/X11/Xresources/' directory instead. _Important:_
+ packages that install files into the `/etc/X11/Xresources/' directory
+ _must_ declare a conflict with `xbase (<< 3.3.2.3a-2)'; if this is not
+ done it is possible for the package to destroy a previously-existing
+ `/etc/X11/Xresources' _file_.
No package should ever install files into the directories
`/usr/bin/X11/', `/usr/doc/X11/', `/usr/include/X11/', or
================================================================
Reply to: