Debian policy manual - chapter 3
Contents of the binary package


3.1 Control file requirements


3.1.1 Maintainer information

All packages must have a Maintainer field with the correct name and a working email address for the Debian maintainer of the package. If one person maintains several packages they should try to avoid having different forms of their name and address in different Maintainer fields.

3.1.2 Dependencies and virtual packages

Add a dependency for any shared libraries required by dynamically-linked executable binaries in your package, by using dpkg-shlibdeps.

All packages must use virtual package names where appropriate, and arrange to create new ones if necessary. They must not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.

The latest version of the authoritative list of virtual package names can be found on ftp.debian.org in /debian/doc/package-developer/virtual-package-names-list.text or your local mirror. The procedure for updating it is described at the top of the file.


3.1.3 Section and Priority

Decide whether your package can go in non-free, contrib or the main distribution - see Package copyright, chapter 2, and put an appropriate value for the distribution in the debian/changelog file.

The Priority and Section control file fields give information for classifying the package in dselect and say which directory to place it in the FTP archive.

They are ultimately the responsibility of the distribution maintainers; however, you should suggest values for them in your .changes information when you upload a package. You do this by including appropriate information in the debian/control file before building the packages.

For a list of the currently in-use sections, please see the FTP archive. Packages in the non-free and contrib areas should have section non-free and contrib, respectively.


3.1.3.1 Priority values

required
required packages are necessary for the proper functioning of the system. You must not remove these packages or your system may become totally broken and you may probably not even be able to use dpkg to put things back. Systems with only the required packages are probably unuseable, but they do have enough functionality to allow the sysadmin to boot and install more software.

important
Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who found it missing would go `What the F*!@<+ is going on, where is foo', it should be in important. This is an important criterion because we are trying to produce, amongst other things, a free Unix. Other packages without which the system will not run well or be useable should also be here. This does not include Emacs or X11 or TeX or any other large applications. The important packages are just a bare minimum of commonly-expected and necessary tools.

standard
These packages provide a reasonably small but not too limited character-mode system. This is what will install by default if the user doesn't select anything else. It doesn't include many large applications, but it does include Emacs (this is more of a piece of infrastructure than an application) and a reasonable subset of TeX and LaTeX (if this is possible without X).

optional[4]
This is all the software that you might reasonably want to install if you didn't know what it was or don't have specialised requirements. This is a much larger system and includes X11, a full TeX distribution, and lots of applications.

extra
This contains packages that conflict with others with higher priorities, or are only likely to be useful if you already know what they are or have specialised requirements.

Priority values are not case-sensitive.


3.1.3.2 Base packages

Some packages have Section: base and are in the base subdirectory on the FTP archives. These are the packages that are supplied on the base disks. They are the minimum sensible set for installing new packages (perhaps via a network).

Most of these packages should have Priority: required or at least Priority: important, and many will be essential (see below).


3.1.4 Pre-Depends and the Essential flag

Do not use Pre-Depends or Essential: yes unless your package is absolutely vital to the functioning of the system and the installation of other packages. Do not do either of these things without consultation with the distribution maintainers or on debian-devel.

Usually, neither of these fields should be used unless removing a package really will completely hose the system, making it impossible to recover by (re)installing packages with dpkg.

Essential should not be used for a shared library package - the dependencies will prevent its premature removal, and we need to be able to remove it when it has been superseded.

It is not necessary for other packages to declare any dependencies they have on other packages which are marked Essential.


3.1.5 Including Priority and Section in the .deb control file

If a user installs a package which is not part of the standard distribution, or without downloading and updating from a new Packages file, the information about the priority and section of a package will be absent, and the dselect package listing will have the package listed under `unclassified'. In order to improve this it is permissible to use the -is, -isp or -ip option to dpkg-gencontrol, so that the Section and/or Priority is copied into the actual control information in the .deb file. However, if you do this you should make sure you keep the information up to date so that users are not shown conflicting information.

3.1.6 Formatting of the Description control file field

Every Debian package should have an extended description.

The description should be written so that it tells the user what they need to know to decide whether to install the package. This description should not just be copied from the blurb for the program. Instructions for configuring or using the package should not be included - that is what installation scripts, manpages, Info files and /usr/doc/package are for. Copyright statements and other administrivia should not be included - that is what /usr/doc/package/copyright is for.

If you wish to include a list in your extended with entries which are a line or more each you must indent each entry by one space to make sure that it doesn't get wordwrapped. The start of each list entry should be marked with an asterisk, followed by a single space. You must wrap the list entries yourself to 75 columns, and should start continuation lines indented by three spaces so that they line up with the start of the text on the first line of each list entry.

See the programmers' manual for further requirements and pitfalls.


3.2 Locations of files

The location of all installed files and directories must comply fully with the Linux Filesystem Standard (FSSTND). The latest version of this document can be found alongside this manual or on tsx-11.mit.edu in /pub/linux/docs/linux-standards/fsstnd/. Specific questions about following the standard may be asked on debian-devel, or referred to Daniel Quinlan, the FSSTND coordinator, at quinlan@pathname.com.


3.2.1 Manpages

You must install manpages in nroff source form, in appropriate places under /usr/man. You should only use sections 1 to 9 (see the FSSTND for more details). You must not install a preformatted `cat page'.

If no manual page is available for a particular program, utility or function and this is reported as a bug on debian-bugs, a symbolic link from the requested manual page to the undocumented(7) manual page should be provided. This symbolic link can be created from debian/rules like this:

ln -s ../man7/undocumented.7.gz \
 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
This manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has (you can report it yourself, if you like). Do not close the bug report until a proper manpage is available.

You may forward a complaint about a missing manpage to the upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do not in general consider the lack of a manpage to be a bug, we do - if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open anyway.

Manpages should be installed compressed using gzip -9.

If one manpage needs to be accesssible via several names it is better to use a symbolic link than the .so feature, but there is no need to fiddle with the relevant parts of the upstream source to change from .so to symlinks - don't do it unless it's easy. Do not create hard links in the manual page directories, and do not put absolute filenames in .so directives. The filename in a .so in a manpage should be relative to the base of the manpage tree (usually /usr/man).


3.2.2 Info documents

Info documents should be installed in /usr/info. They should be compressed with gzip -9.

Your package must call install-info to update the Info dir file, in its post-installation script:

install-info --quiet --section Development Development \
  /usr/info/foobar.info

It is a good idea to specify a section for the location of your program; this is done with the --section switch. To determine which section to use, you should look at /usr/info/dir on your system and choose the most relevant (or create a new section if none of the current sections are relevant). Note that the --section flag takes two arguments; the first is a regular expression to match (case-insensitively) against an existing section, the second is used when creating a new one.

You must remove the entries in the pre-removal script:

install-info --quiet --remove /usr/info/foobar.info

If install-info cannot find a description entry in the Info file you will have to supply one. See install-info(8) for details.


3.2.3 Additional documentation

Any additional documentation that comes with the package can be installed at the discretion of the package maintainer. Text documentation should be installed in a directory /usr/doc/package[5] and compressed with gzip -9 unless it is small.

If a package comes with large amounts of documentation which many users of the package will not require you should create a separate binary package to contain it, so that it does not take up disk space on the machines of users who do not need or want it installed.

It is often a good idea to put text information files (READMEs, changelogs, and so forth) that come with the source package in /usr/doc/package in the binary package. However, you don't need to install the instructions for building and installing the package, of course!


3.2.4 Preferred documentation formats

The unification of Debian documentation is being carried out via HTML.

If your package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in the binary package, in the directory /usr/doc/package or its subdirectories.

Other formats such as PostScript may be provided at your option.


3.2.4.1 Examples

Any examples (configurations, source files, whatever), should be installed in a directory /usr/doc/package/examples. These files should not be referenced by any program - they're there for the benefit of the system administrator and users, as documentation only.

3.2.5 /usr/doc/package/changelog.Debian.gz and /usr/doc/package/changelog.upstream.gz.

This installed file must contain a copy of the debian/changelog file from your Debian source tree, and a copy of the upstream changelog file if there is one. They should usually be installed in /usr/doc/package as changelog.Debian.gz and changelog.gz respectively.

Both should be installed compressed using gzip -9, as they will become large with time even if they start out small.

If the package has only one changelog which is used both as the Debian changelog and the upstream one because there is no separate upstream maintainer then that changelog should usually be installed as /usr/doc/package/changelog.gz; if there is a separate upstream maintainer, but no upstream changelog, then the Debian changelog should still be called changelog.Debian.gz.


3.2.6 /usr/doc/package/copyright

This file must contain details of the authorship and copyright of the package. It must say where the upstream sources (if any) were obtained, and explain briefly what modifications were made in the Debian version of the package compared to the upstream one. It must name the original authors of the package and the Debian maintainer(s) who were involved with its creation.

It must contain the full text of the copyright notice and any acknowledgements for the program and the licence terms under which the program is distributed. If the package is distributed under the GNU General Public Licence, the GNU Library General Public Licence, the Regents of the University of California at Berkeley (BSD) licence or Larry Wall's Artistic Licence please say so instead of including a copy of the licence. The files BSD, GPL, LGPL and Artistic are be available in /usr/doc/copyright for you to refer to.

The copyright file should not be compressed unless it is very large.

Do not use the copyright file as a general README file. If your package has such a file it should be installed in /usr/doc/package/README or README.Debian or some other appropriate place.


3.2.7 Symbolic links

Most symbolic links should be relative, not absolute. Absolute links, in general, cause problems when a file system is not mounted where it "normally" resides (for example, when mounted via NFS).

In particular, symlinks from one part of /usr to another should be relative.

In certain cases, however, relative links may cause more problems. For example, links into /etc and /var should be absolute.

Note that when creating a relative link using ln it is not necessary for the target of the link to exist relative to the working directory you're running ln from; nor is it necessary to change directory to the directory where the link is to be made. Simply include the string that should appear as the target of the link (this will be a pathname relative to the directory in which the link resides) as the first argument to ln.

For example, in your Makefile or debian/rules, do things like:

ln -fs gcc $(prefix)/bin/cc 
ln -fs gcc debian/tmp/usr/bin/cc 
ln -fs ../sbin/sendmail $(prefix)/bin/runq 
ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

3.2.8 Logfiles

Logfiles should usually be named /var/log/package.log. If you have many logfiles, or need a separate directory for permissions reasons (/var/log is writeable only by root), you should usually create a directory named /var/log/package.

Make sure that any logfiles are rotated occasionally so that they don't grow indefinitely; the best way to do this is to use savelog program in an /etc/cron.daily, /etc/cron.weekly or /etc/cron.monthly script.

Make sure that any logfiles are removed when the package is purged (but not when it is only removed), by checking the argument to the postrm script (see the programmer's manual for details).


3.2.9 /usr/local - for the use of the system administrator

As mandated by the FSSTND no package should place any files in /usr/local, either by putting them in the filesystem archive to be unpacked by dpkg or by manipulating them in their maintainer scripts.

Every package that searches a number of directories or files for something (for example, looking for shared libraries in /lib or /usr/lib) should search an appropriate directory in /usr/local too.

In order that the system administrator may know where to place additional files a package should create an empty directory in the appropriate place in /usr/local by supplying it in the filesystem archive for unpacking by dpkg. The /usr/local directory itself and all the subdirectories created by the package should have permissions 2775 (group-writeable and set-group-id) and be owned by root.staff.

In the future it will be possible to tell dpkg not to unpack files matching certain patterns, so that system administrators who do not wish these directories in /usr/local do not need to have them.


3.3 Permissions and ownerships

The rules in this section are guidelines for general use. If necessary you may deviate from the details below. However, if you do so you must make sure that what is done is secure and you must try to be as consistent as possible with the rest of the system. You should probably also discuss it on debian-devel first.

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

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.

Setuid and setgid executables should be mode 4755 or 2755 respectively, and owned by the appropriate user or group. 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 reason you should not restrict read or execute permissions 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 them unreadable to those users who must not be allowed to execute them.

Do not arrange that the system administrator can only 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.

Shared libraries should be installed executable.


3.4 Configuration files

Any configuration files created or used by your package should reside in /etc. If there are several you should consider creating a subdirectory named after your package.

It is almost certain that any file in /etc that is in your package's filesystem archive should be listed in dpkg's conffiles control area file. (See the dpkg programmers' manual).


3.5 Maintainer scripts

The package installation scripts should avoid producing output which it is unnecessary for the user to see and should rely on dpkg to stave off boredom on the part of a user installing many packages. This means, amongst other things, using the --quiet option on install-info.

Packages should try to minimise the amount of prompting they need to do, and they should ensure that the user will only ever be asked each question once. This means that packages should try to use appropriate shared configuration files (such as /etc/papersize and /etc/news/server, rather than each prompting for their own list of required pieces of information.

It also means that an upgrade should not ask the same questions again, unless the user has used dpkg --purge to remove the package's configuration. The answers to configuration questions should be stored in an appropriate place in /etc so that the user can modify them, and how this has been done should be documented.

If a package has a vitally important piece of information to pass to the user (such as "don't run me as I am, you must edit the following configuration files first or you risk your system emitting badly-formatted messages"), it should display this in the postinst script and prompt the user to hit return to acknowledge the message. Copyright messages do not count as vitally important (they belong in /usr/doc/copyright); neither do instructions on how to use a program (these should be in on line documentation, where all the users can see them).

Any necessary prompting should almost always be confined to the post-installation script, and should be protected with a conditional so that unnecssary prompting doesn't happen if a package's installation fails and the postinst is called with abort-upgrade, abort-remove or abort-deconfigure.

Errors which occur during the execution of an installation script must be checked and the installation must not continue after an error.

The section below on scripts in general applies to package maintainer scripts too.


3.6 Scripts in general

All command scripts, including the package maintainer scripts inside the package and used by dpkg, should have a #! line naming the shell to be used to interpret them.

In the case of Perl scripts this should be #!/usr/bin/perl.

Shell scripts (sh and bash) should almost certainly start with set -e so that errors are detected. Every script must use set -e or check the exit status of every command.

Perl scripts should check for errors when making any system calls, including open, print, close, rename and system.

csh and tcsh should be avoided as scripting languages. See Csh Programming Considered Harmful, one of the comp.unix.* FAQs. It can be found on rtfm.mit.edu in /pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful. If an upstream package comes with csh scripts then you must make sure that they start with #!/bin/csh and make your package depend on the c-shell virtual package.


3.7 Shared library packages

Packages involving shared libraries should be split up into several binary packages.

For a straightforward library which has a development environment and a runtime kit including just shared libraries you need to create two packages: librarynamesoname[6] and librarynamesoname-dev.

If you prefer only to support one development version at a time you may name the development package libraryname-dev; otherwise you may wish to use dpkg's conflicts mechanism to ensure that the user only installs one development version at a time (after all, different development versions are likely to have the same header files in them, causing a filename clash if both are installed). Typically the development version will also need an exact version dependency on the runtime library, to make sure that compilation and linking happens correctly.

Packages which use the shared library should have a dependency on the name of the shared library package, librarynamesoname. When the soname changes you can have both versions of the library installed while moving from the old library to the new.

If your package has some run-time support programs which use the shared library you must not put them in the shared library package. If you do that then you won't be able to install several versions of the shared library without getting filename clashes. Instead, either create a third package for the runtime binaries (this package might typically be named libraryname-runtime - note the absence of the soname in the package name) or if the development package is small include them in there.

If you have several shared libraries built from the same source tree you can lump them all togther into a single shared library package, provided that you change all their sonames at once (so that you don't get filename clashes if you try to install different versions of the combined shared libraries package).

Follow the directions in the dpkg programmers' manual for putting the shared library in its package, and make sure you include a shlibs control area file with details of the dependencies for packages which use the library.


3.8 Application configuration files, dotfiles and /etc/skel

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.

Ideally the sysadmin should ideally not have to do any configuration other than that done (semi-)automatically by the postinst script.


3.9 Games

The permissions on /var/lib/games are 755 root.root.

Each game decides on its own security policy.

Games which require protected, privileged access to high-score files, savegames, &c, must be made set-group-id (mode 2755) and owned by root.games, and use files and directories with appropriate permissions (770 root.games, for example). They must not be made set-user-id, as this causes security problems.[7]

Some packages, for example some fortune cookie programs, are configured by the upstream authors to install with their data files or other static information made unreadable so that they can only be accessed through set-id programs provided. Do not do this in a Debian package: anyone can download the .deb file and read the data from it, so there is no point making the files unreadable. Not making the files unreadable also means that you don't have to make so many programs set-id, which reduces the risk of a security hole.


3.10 Allocating package-specific users and groups

If you need to create a new user or group for your package there are two possibilities. Firstly, you may need to make some files in the binary package be owned by this user or group, or you may need to compile the user or group id (rather than just the name) into the binary (though this latter should be avoided if possible). In this case 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 may 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 must 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 filesystem 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.


3.11 Installation of Emacs-lisp files

Generally, if a package includes an elisp helper file, it probably doesn't need to be byte-compiled. If the package is written primarily in emacs, it is probably complex enough that speed is an issue and should be byte compiled.

3.12 Use of dpkg-divert and update-alternatives

Do not use dpkg-divert on a file belonging to another package without consulting the maintainer of that package first.

In order for update-alternatives to work correctly all the packages which supply an instance of the `shared' command name (or, in general, filename) must use it. You can use Conflicts to force the deinstallation of other packages supplying it which do not (yet) use update-alternatives. It may in this case be appropriate to specify a conflict on earlier versions on something - this is an exception to the usual rule that this is not allowed.


Debian policy manual - Copyright ©1996 Ian Jackson.
Contents; abstract; next; back.
version 2.1.2.2 (dpkg 1.4.0.8), 3 February 1997
Ian Jackson ijackson@gnu.ai.mit.edu
revised: David A. Morris bweaver@debian.org