From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:26:46 +0000 (+0000) Subject: * Finished chapter 11 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=3859c47d25c8053e87bceb111ac57c1b700b623d;p=debian%2Fdebian-policy.git * Finished chapter 11 Author: jdg Date: 2001/05/17 11:25:40 * Finished chapter 11 * Add a dpkg-statoverride description section (non-policy) closes: Bug#89473 * Fix the ldconfig usage description (remove "only if") closes: Bug#89674 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-124 --- diff --git a/debian/changelog b/debian/changelog index c5d6e6a..9dc9305 100644 --- a/debian/changelog +++ b/debian/changelog @@ -16,6 +16,9 @@ debian-policy (3.5.4.1) unstable; urgency=low * Improved mkdir example in 10.1.2 closes: Bug#92744 * Made the "where examples live" entry in the upgrading-checklist clearer (add "for use by scripts") + * Add a dpkg-statoverride description section closes: Bug#89473 + * Fix the ldconfig usage description (remove "only if") + closes: Bug#89674 -- diff --git a/policy.sgml b/policy.sgml index 8d0b210..1ca7586 100644 --- a/policy.sgml +++ b/policy.sgml @@ -2831,7 +2831,6 @@ Package: libc6

-

The new package's files are unpacked, overwriting any that may be on the system already, for example any @@ -2888,13 +2887,14 @@ Package: libc6 - -

+

+

If the package is being upgraded, call old-postrm upgrade new-version -

+ +

If this fails, dpkg will attempt: @@ -2908,6 +2908,7 @@ Package: libc6

+

This is the point of no return - if dpkg gets this far, it won't back off @@ -3006,11 +3007,11 @@ Package: libc6

- Details of configuration + Details of configuration

When we configure a package (this happens with dpkg - --install, or with --configure), we first + --install and dpkg --configure), we first update any conffiles and then call: postinst configure most-recently-configured-version @@ -3031,8 +3032,8 @@ Package: libc6

- Details of removal and/or configuration purging - + Details of removal and/or + configuration purging

@@ -3070,9 +3071,10 @@ Package: libc6

- The conffiles and any backup files (~-files, - #*# files, %-files, - .dpkg-{old,new,tmp}, etc.) are removed.

+ The conffiles and any backup files + (~-files, #*# files, + %-files, .dpkg-{old,new,tmp}, etc.) + are removed.

@@ -3741,9 +3743,9 @@ Replaces: mail-transport-agent

must call ldconfig in its postinst - script if and only if the first argument is configure - and should call it in the postrm script if the - first argument is remove. + script if the first argument is configure and should + call it in the postrm script if the first + argument is remove.

@@ -4626,7 +4628,7 @@ test -f program-executed-later-in-script || exit 0 scripts whose values control the bahaviour of the scripts, and which a system administrator is likely to want to change. As the scripts themselves are frequently - conffiles, modifying them requires that the + conffiles, modifying them requires that the administrator merge in their changes each time the package is upgraded and the conffile changes. To ease the burden on the system administrator, such configurable @@ -5795,21 +5797,25 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

configuration file -

- A file that affects the operation of program, or + +

+ A file that affects the operation of a program, or provides site- or host-specific information, or - otherwise customizes the behavior of program. + otherwise customizes the behavior of a 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.

+ desired) to conform to local policy or to 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).

+ (see ). +

@@ -5817,14 +5823,16 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

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.

+ 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 + (such as most of the files in /etc/default and /etc/cron.{daily,weekly,monthly}) is de-facto a - configuration file and should be treated as such.

+ configuration file and should be treated as such. +

@@ -5851,15 +5859,20 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq behavior: -

local changes must be preserved during a package - upgrade

+

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

-

configuration files must be preserved when the +

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

+ package is purged. +

-

+ +

The easy way to achieve this behavior is to make the @@ -5882,199 +5895,226 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq 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 different. The second is that - dpkg might break the hard link while - upgrading conffiles. + unwittingly become unlinked and different. The second + is that dpkg might break the hard link + while upgrading conffiles.

- 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 + 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 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 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.

+ responsibility of the package maintainer to provide + maintainer scripts which correctly create, update and + maintain the file and remove it on purge. (See 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 otherwise be + good citizens. +

-

- 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 with a symbolic link - from /usr/share/doc/package/examples - if they are examples, and should be - perfectly ordinary dpkg-handled files - (not conffiles). -

+

+ 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 + 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.

- + every time the package is upgraded. +

Sharing configuration files

- Packages which specify the same file as - `conffile' must be tagged as conflicting - with each other. -

+ Packages which specify the same file as a + conffile must be tagged as conflicting + with each other. (This is an instance of the general rule + about not sharing files. Note that neither alternatives + nor diversions are likely to be appropriate in this case.) +

- The maintainer scripts must not alter the conffile of - any package, including the one the scripts belong - to.

+ The maintainer scripts must not alter a conffile + of any package, including the one the scripts + belong to. +

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 must 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.

+ the package which handles that file as a configuration + file. Other packages that use the configuration file must + 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 be done: - +

- have one of the related packages (the "core" - package) manage the configuration file with - maintainer scripts as described in the previous - section.

+ One of the related packages (the "owning" package) + will manage the configuration file with maintainer + scripts as described in the previous section. +

-

- the core package should also provide a program that - the other packages may use to modify the - configuration file.

+ +

+ The owning package should also provide a program + that the other packages may use to modify the + configuration file. +

- 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.

+ The related packages must use the provided program + to make any desired 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. (This is in addition to the fact that the + configuration file may not even be present in the + latter scenario.) +

-

+ +

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.)

+ and which manages the shared configuration files. (The + sgml-base package is a good example.) +

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.

+ The files in /etc/skel will automatically be + copied into new user accounts by adduser. + No other program should reference the files in + /etc/skel. +

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).

+ should be installed in /etc/skel and treated as a + configuration file. +

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.

+ themselves automatically, that is) are a bad thing. + Furthermore, programs should be configured by the Debian + default installation as behave as closely to the upstream + default behaviour 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 - may a default per-user file be placed in - /etc/skel.

+ configured in some way in order to operate sensibly, that + should be done using a site-wide configuration file placed + 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 may 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.

+ This is particularly true because there is no easy (or + necessarily desirable) mechanism for ensuring that the + appropriate dotfiles are copied into the accounts of + existing users when a package is installed. +

Log files -

- The traditional approach to log files has been to set up ad - hoc log rotation schemes using simple shell scripts and - cron. While this approach is highly customizable, it - requires quite a lot of sysadmin work. Even though the - original Debian system helped a little by automatically - installing a system which can be used as a template, 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 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 have many - log files, or need a separate directory for permissions + log files, or need a separate directory for permission reasons (/var/log is writable only by root), you should usually create a directory named - /var/log/package.

+ /var/log/package and place your log + files there. +

- Log files must be rotated occasionally so - that they don't grow indefinitely; the best way to do this - is to drop a script into the directory + Log files must be rotated occasionally so that they don't + grow indefinitely; the best way to do this is to drop a log + rotation configuration file into the directory /etc/logrotate.d and use the facilities provided by - logrotate. Here is a good example for a logrotate config + logrotate. + +

+ The traditional approach to log files has been to set up + ad hoc log rotation schemes using simple shell + scripts and cron. While this approach is highly + customizable, it requires quite a lot of sysadmin work. + Even though the original Debian system helped a little + by automatically installing a system which can be used + as a template, this was deemed not enough. +

+ +

+ The use of logrotate, a program developed + by Red Hat, is better, as it centralizes log management. + It has both a configuration file + (/etc/logrotate.conf) and a directory where + packages can drop their individual log rotation + configurations (/etc/logrotate.d). +

+ + Here is a good example for a logrotate config file (for more information see ): + section="8">): /var/log/foo/* { rotate 12 @@ -6085,20 +6125,20 @@ postrotate endscript } - Which rotates all files under `/var/log/foo', saves 12 - compressed generations, and sends a HUP signal at the end of - rotation. - + This rotates all files under /var/log/foo, saves 12 + compressed generations, and forces the daemon to reload its + configuration information after the log rotation.

Log files should be removed when the package is - purged (but not when it is only removed), by checking the - argument to the postrm script (see the Debian - Packaging Manual for details).

+ purged (but not when it is only removed). This should be + done by the postrm script when it is called + with the argument purge (see ). +

- Permissions and owners @@ -6108,19 +6148,22 @@ endscript However, if you do so you must make sure that what is done is secure and you should try to be as consistent as possible with the rest of the system. You should probably also - discuss it on debian-devel first.

+ discuss it on debian-devel first. +

Files should be owned by root.root, and made writable only by the owner and universally readable (and - executable, if appropriate).

+ executable, if appropriate), that is mode 644 or 755. +

Directories should be mode 755 or (for group-writability) mode 2775. The ownership of the directory should be consistent with its mode: if a directory is mode 2775, it should be owned by the group that needs write access to - it.

+ it. +

Setuid and setgid executables should be mode 4755 or 2755 @@ -6128,30 +6171,44 @@ endscript They should not be made unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no extra security, because anyone can find the binary in the freely available - Debian package, it is merely inconvenient. For the same + Debian package; it is merely inconvenient. For the same reason you should not restrict read or execute permissions - on non-set-id executables.

+ on non-set-id executables. +

Some setuid programs need to be restricted to particular sets of users, using file permissions. In this case they - should be owned by the uid to which they are set-id, and - by the group which should be allowed to execute them. - They should have mode 4754; there is no point in making + should be owned by the uid to which they are set-id, and by + the group which should be allowed to execute them. They + should have mode 4754; again there is no point in making them unreadable to those users who must not be allowed to - execute them.

+ execute them. +

- You must not arrange that the system administrator can only + It is possible to arrange that the system administrator can reconfigure the package to correspond to their local - security policy by changing the permissions on a binary. - Ordinary files installed by dpkg (as opposed - to conffiles and other similar objects) have their - permissions reset to the distributed permissions when the - package is reinstalled. Instead you should consider (for - example) creating a group for people allowed to use the - program(s) and making any setuid executables executable - only by that group.

+ security policy by changing the permissions on a binary: + they can do this by using dpkg-statoverride, as + described below. + +

+ Ordinary files installed by dpkg (as + opposed to conffiles and other similar objects) + normally have their permissions reset to the distributed + permissions when the package is reinstalled. However, + the use of dpkg-statoverride overrides this + default behaviour. If you use this method, you should + remember to describe dpkg-statoverride in + the package documentation; being a relatively new + addition to Debian, it is probably not yet well-known. +

+ + Another method you should consider is to create a group for + people allowed to use the program(s) and make any setuid + executables executable only by that group. +

If you need to create a new user or group for your package @@ -6164,37 +6221,105 @@ endscript

If you need a statically allocated id, you must ask for a - user or group id from the base system - maintainer, and must not release the package until you - have been allocated one. Once you have been allocated one - you must make the package depend on a version of the base - system with the id present in /etc/passwd or - /etc/group, or alternatively arrange for your - package to create the user or group itself with the - correct id (using adduser) in its pre- or - post-installation script (the latter is to be preferred if - it is possible).

- -

- On the other hand, the program might be able to determine the - uid or gid from the group name at runtime, so that a - dynamic id can be used. In this case you should choose an - appropriate user or group name, discussing this on - debian-devel and checking with the base - system maintainer that it is unique and that they do not - wish you to use a statically allocated id instead. When - this has been checked you must arrange for your package to - create the user or group if necessary using - adduser in the pre- or post-installation - script (again, the latter is to be preferred if it is - possible).

- -

- Note that changing the numeric value of an id associated with a name - is very difficult, and involves searching the file system for all - appropriate files. You need to think carefully whether a static or - dynamic id is required, since changing your mind later will cause - problems.

+ user or group id from the base-passwd maintainer, + and must not release the package until you have been + allocated one. Once you have been allocated one you must + either make the package depend on a version of the + base-passwd package with the id present in + /etc/passwd or /etc/group, or arrange for + your package to create the user or group itself with the + correct id (using adduser) in its + preinst or postinst. (Doing it in + the postinst is to be preferred if it is + possible, otherwise a pre-dependency will be needed on the + adduser package.) +

+ +

+ On the other hand, the program might be able to determine + the uid or gid from the user or group name at runtime, so + that a dynamically allocated id can be used. In this case + you should choose an appropriate user or group name, + discussing this on debian-devel and checking + with the base system maintainer that it is unique and that + they do not wish you to use a statically allocated id + instead. When this has been checked you must arrange for + your package to create the user or group if necessary using + adduser in the preinst or + postinst script (again, the latter is to be + preferred if it is possible). +

+ +

+ Note that changing the numeric value of an id associated + with a name is very difficult, and involves searching the + file system for all appropriate files. You need to think + carefully whether a static or dynamic id is required, since + changing your mind later will cause problems. +

+ + The use of dpkg-statoverride +

+ This section is not intended as policy, but as a + description of the use of dpkg-statoverride. +

+ +

+ dpkg-statoverride is a replacement for the + deprecated suidmanager package. Packages which + previously used suidmanager should have a + Conflicts: suidmanager (<< 0.50) entry (or even + (<< 0.52)), and calls to suidregister + and suidunregister should now be simply removed + from the maintainer scripts. +

+ +

+ If a system administrator wishes to have a file (or + directory or other such thing) installed with owner and + permissions different from those in the distributed Debian + package, he can use the dpkg-statoverride + program to instruct dpkg to use the different + settings every time the file is installed. Thus the + package maintainer should distribute the files with their + normal permissions, and leave it for the system + administrator to make any desired changes. For example, a + daemon which is normally required to be setuid root, but + in certain situations could be used without being setuid, + should be installed setuid in the .deb. Then the + local system administrator can change this if they wish. + If there are two standard ways of doing it, the package + maintainer can use debconf to find out the + preference, and call dpkg-statoverride in the + maintainer script if necessary to accommodate the system + administrator's choice. +

+ +

+ Given the above, dpkg-statoverride is + essentially a tool for system administrators and would not + normally be needed in the maintainer scripts. There is + one type of situation, though, where calls to + dpkg-statoverride would be needed in the + maintainer scripts, and that involves packages which use + dynamically allocated user or group ids. In such a + situation, something like the following idiom can be very + helpful in the package's postinst, where + sysuser is a dynamically allocated id: + +for i in /usr/bin/foo /usr/sbin/bar +do + if ! dpkg-statoverride --list $i >/dev/null + then + dpkg-statoverride --update --add sysuser root 4755 $i + fi +done + + The corresponding dpkg-statoverride --remove + calls can then be made unconditionally when the package is + purged. +

+ diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 8ea7413..7d529ac 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -58,6 +58,8 @@ picking your way through this list. - [Clarified note in 3.5.3.0 upgrading checklist regarding examples and templates: this refers only to those examples used by scripts; see section 11.7.3 for the whole story] + - Included a new section 11.9.1 describing the use of + dpkg-statoverride; this does not have the weight of policy 3.5.4.0 Apr 01