This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and contents of the Debian archive, several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution.

This manual does not describe the technical mechanisms involved in package creation, installation, and removal. This information can be found in the Debian Packaging Manual and the Debian System Administrators' Manual.

This document assumes familiarity with these other two manuals. Unfortunately, the System Administrators' Manual does not exist yet.

Much of the information presented in this manual will be useful even when building a package which is to be distributed in some other way or is for local use.

The current version of this document is always accessible from the Debian FTP server ftp.debian.org at /debian/doc/manuals/debian-policy.html.tar.gz or from the Debian WWW server at .

In addition, this manual is distributed via the Debian package debian-policy.

As the Debian GNU/Linux system is continuously evolving this manual is changed from time to time.

While the authors of this document tried hard not to include any typos or other errors these still occur. If you discover an error in this manual or if you want to tell us any comments, suggestions, or critics please send an email to the Debian Policy List, debian-policy@lists.debian.org, or submit a bug report against the debian-policy package.

The aims of this policy are:

We want to make as much software available as we can.

The Debian system can be configured to use either plain or shadow passwords.

Some user ids (UIDs) and group ids (GIDs) are reserved globally for use by certain packages. Because some packages need to include files which are owned by these users or groups, or need the ids compiled into binaries, these ids must be used on any Debian system only for the purpose for which they are allocated. This is a serious restriction, and we should avoid getting in the way of local administration policies. In particular, many sites allocate users and/or local system groups starting at 100.

Apart from this we should have dynamically allocated ids, which should by default be arranged in some sensible order--but the behavior should be configurable.

No package except base-passwd may modify /etc/passwd, /etc/shadow, or /etc/group.

The UID and GID ranges are as follows: 0-99:

Globally allocated by the Debian project, must be the same on every Debian system. These ids will appear in the passwd and group files of all Debian systems, new ids in this range being added automatically as the base-passwd package is updated.

Packages which need a single statically allocated uid or gid should use one of these; their maintainers should ask the base-passwd maintainer for ids.

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, it should place a file with the name if the package in one of the following directories: /etc/cron.daily /etc/cron.weekly /etc/cron.monthly 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 must be treated as configuration files.

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.

This section describes different formats for messages written to standard output by the /etc/init.d scripts. The intent is to improve the consistency of Debian's startup and shutdown look and feel.

Please look very careful at the details. We want to get the messages to look exactly the same way concerning spaces, punctuation, and case of letters.

Here is a list of overall rules that you should use when you create output messages. They can be useful if you have a non-standard message that isn't covered in the sections below.

Every message should cover one line, start with a capital letter and end with a period `.'.

The following formats must be used

when daemons get started.

Use this format if your script starts one or more daemons. The output should look like this (a single line, no leading spaces): Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>. The <description> should describe the subsystem the daemon or set of daemons are part of, while <daemon-1> up to <daemon-n> denote each daemon's name (typically the file name of the program).

For example, the output of /etc/init.d/lpd would look like: Starting printer spooler: lpd.

This can be achieved by saying echo -n "Starting printer spooler: lpd" start-stop-daemon --start --quiet lpd echo "." in the script. If you have more than one daemon to start, you should do the following: echo -n "Starting remote file system services:" echo -n " nfsd"; start-stop-daemon --start --quiet nfsd echo -n " mountd"; start-stop-daemon --start --quiet mountd echo -n " ugidd"; start-stop-daemon --start --quiet ugidd echo "." This makes it possible for the user to see what takes so long and when the final daemon has been started. Please be careful where to put spaces: In the example above the system administrator can easily comment out a line if he don't wants to start a specific daemon, while the displayed message still looks good.

Menu entries should follow the current menu policy as defined in the file ftp.debian.org in /debian/doc/package-developer/menu-policy.txt or your local mirror. In addition, it is included in the debian-policy package.

The Debian menu packages provides a unique interface between packages providing applications and documents, and menu programs (either X window managers or text-based menu programs as pdmenu).

All packages that provide applications that need not be passed any special command line arguments for normal operation should register a menu entry for those applications, so that users of the menu package will automatically get menu entries in their window managers, as well in shells like pdmenu.

Please refer to the Debian Menu System document that comes with the menu package for information about how to register your applications and web documents.

Packages which provide the ability to view/show/play, compose, edit or print MIME types should register themselves as such following the current MIME support policy as defined in the file found on ftp.debian.org in /debian/doc/package-developer/mime_policy.txt or your local mirror. In addition, it is included in the debian-policy package.

MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a mechanism for encoding files and data streams and providing meta-information about them, in particular their type (e.g. audio or video) and format (e.g. PNG, HTML, MP3).

Registration of MIME type handlers allows programs like mail user agents and web browsers to to invoke these handlers to view, edit or display MIME types they don't support directly.

To achieve a consistent keyboard configuration (i.e., all applications interpret a keyboard event the same way) all programs in the Debian distribution have to be configured to comply with the following guidelines.

Here is a list that contains certain keys and their interpretation: <--

delete the character to the left of the cursor

The following list explains how the different programs should be set up to achieve this:

`<--' generates KB_Backspace in X.

This will solve the problem except for:

Some terminals have a <-- key that cannot be made to produce anything except ^H. On these terminals Emacs help will be unavailable on ^H (assuming that the `stty erase' character takes precedence in Emacs, and has been set correctly). M-x help or F1 (if available) can be used instead.

No program may depend on environment variables to get reasonable defaults. (That's because these environment variables would have to be set in a system-wide configuration file like /etc/profile, which is not supported by all shells.)

If a program should depend on environment variables for its configuration, the program has to be changed to fall back to a reasonable default configuration if these environment variables are not present. If this cannot be done easily (e.g., if the source code of a non-free program is not available), the program should be replaced by a small `wrapper' shell script which sets the environment variables and calls the original program.

Here is an example of a wrapper script for this purpose: #!/bin/sh BAR=/var/lib/fubar export BAR exec /usr/lib/foo/foo "$@"

Furthermore, as /etc/profile is a configuration file of the bash package, no other package may put any environment variables or other commands into that file.

It is not allowed that two packages install programs with different functionality but with the same filenames. (The case of two programs having the same functionality but different implementations is handled via `alternatives.') If this case happens, one of the programs has to be renamed. The maintainers should report this to the developers' mailing and try to find a consensus about which package will have to be renamed. If a consensus can not be reached, both programs must be renamed.

Generally the following compilation parameters should be used: CC = gcc CFLAGS = -O2 -g -Wall # sane warning options vary between programs LDFLAGS = # none install -s # (or use strip on the files in debian/tmp)

Note that all installed binaries should be stripped, either by using the -s flag to install, or by calling strip on the binaries after they have been copied into debian/tmp but before the tree is made into a package.

The -g flag is useful on compilation so that you have available a full set of debugging symbols in your built source tree, in case anyone should file a bug report involving (for example) a core dump.

The -N flag should not be used. On a.out systems it may have been useful for some very small binaries, but for ELF it has no good effect.

It is up to the package maintainer to decide what compilation options are best for the package. Certain binaries (such as computationally-intensive programs) may function better with certain flags (-O3, for example); feel free to use them. Please use good judgment here. Don't use flags for the sake of it; only use them if there is good reason to do so. Feel free to override the upstream author's ideas about which compilation options are best--they are often inappropriate for our environment.

All libraries must have a shared version in the lib package and a static version in the lib-dev package. The shared version must be compiled with -fPIC, and the static version must not be. In other words, each *.c file is compiled twice.

You have to specify the gcc option -D_REENTRANT when building a library (either static or shared) to make the library compatible with LinuxThreads.

Note that all installed shared libraries should be stripped with strip --strip-unneeded <your-lib> (The option `--strip-unneeded' makes strip remove only the symbols which aren't needed for relocation processing.) Shared libraries can function perfectly well when stripped, since the symbols for dynamic linking are in a separate part of the ELF object file.

Note that under some circumstances it may be useful to install a shared library unstripped, for example when building a separate package to support debugging.

An ever increasing number of packages are using libtool to do their linking. The latest GNU libtools (>= 1.3a) can take advantage of the metadata in the installed libtool archive files (`*.la'). The main advantage of libtool's .la files is that it allows libtool to store and subsequently access metadata with respect to the libraries it builds. libtool will search for those files, which contain a lot of useful information about a library (e.g. dependency libraries for static linking). Also, they're essential for programs using libltdl.

Certainly libtool is fully capable of linking against shared libraries which don't have .la files, but being a mere shell script it can add considerably to the build time of a libtool using package if that shell-script has to derive all this information from first principles for each library every time it is linked. With the advent of libtool-1.4 (and to a lesser extent libtool-1.3), the .la files will also store information about inter-library dependencies which cannot necessarily be derived after the .la file is deleted.

Packages that use libtool to create shared libraries must include the .la files in the -dev packages, with the exception that if the package relies on libtool's libltdl library, in which case the .la files must go in the run-time library package. This is a good idea in general, and especially for static linking issues.

Please make sure that you use only released versions of shared libraries to build your packages; otherwise other users will not be able to run your binaries properly. Producing source packages that depend on unreleased compilers is also usually a bad idea.

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 (soname is the shared object name of the shared library--it's the thing that has to match exactly between building an executable and running it for the dynamic linker to be able run the program; usually the soname is the major number of the library) 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 together 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 Debian Packaging 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.

Shared libraries should not be installed executable, since ld.so does not require this and trying to execute a shared library results in a core dump.

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.

The standard shell interpreter `/bin/sh' may be a symbolic link to any POSIX compatible shell. Thus, shell scripts specifying `/bin/sh' as interpreter may only use POSIX features. If a script requires non-POSIX features from the shell interpreter, the appropriate shell has to be specified in the first line of the script (e.g., `#!/bin/bash') and the package has to depend on the package providing the shell (unless the shell package is marked `Essential', e.g., in the case of bash).

Restrict your script to POSIX features when possible so that it may use /bin/sh as its interpreter. If your script works with ash, it's probably POSIX compliant, but if you are in doubt, use /bin/bash.

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 , or or even on ftp.cpan.org /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. 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.

Any scripts which create files in world-writable directories (e.g., in /tmp) have to use a mechanism which will fail if a file with the same name already exists.

The Debian base distribution provides the tempfile and mktemp utilities for use by scripts for this purpose.

In general, symbolic links within a top-level directory should be relative, and symbolic links pointing from one top-level directory into another should be absolute. (A top-level directory is a sub-directory of the root directory `/'.)

In addition, symbolic links should be specified as short as possible, i.e., link targets like `foo/../bar' are deprecated.

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

A symbolic link pointing to a compressed file should always have the same file extension as the referenced file. (For example, if a file `foo.gz' is referenced by a symbolic link, the filename of the link has to end with `.gz' too, as in `bar.gz.')

No package may include device files in the package file tree.

If a package needs any special device files that are not included in the base system, it has to call makedev in the postinst script, after asking the user for permission to do so.

No package should remove any device files in the postrm or any other script. This is left to the system administrator.

Debian uses the serial devices /dev/tty*. Programs using the old /dev/cu* devices should be changed to use /dev/tty*.

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 reasons (/var/log is writable only by root), you should usually create a directory named /var/log/package.

Make sure that any log files are rotated occasionally so that they don't grow indefinitely; the best way to do this is to drop a script into the directory /etc/logrotate.d and use the facilities provided by logrotate. Here is a good example for a logrotate config file (for more information see ): /var/log/foo/* { rotate 12 weekly compress postrotate /etc/init.d/foo force-reload endscript } Which rotates all files under `/var/log/foo', saves 12 compressed generations, and sends a HUP signal at the end of rotation.

Make sure that any log files are 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).

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

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

If a program needs to specify an architecture specification string in some place, the following format has to be used: <arch>-<os> where `<arch>' is one of the following: i386, alpha, arm, m68k, powerpc, sparc and `<os>' is one of: linux, gnu. Use of gnu in this string is reserved for the GNU/Hurd operating system. .

Note, that we don't want to use `<arch>-debian-linux' to apply to the rule `architecture-vendor-os' since this would make our programs incompatible to other Linux distributions. Also note, that we don't use `<arch>-unknown-linux', since the `unknown' does not look very good.

The configuration files /etc/services, /etc/protocols, and /etc/rpc are managed by the netbase package and may not be modified by other packages.

If a package requires a new entry in one of these files, the maintainer has to get in contact with the netbase maintainer, who will add the entries and release a new version of the netbase package.

The configuration file /etc/inetd.conf may be modified by the package's scripts only via the update-inetd script or the DebianNet.pm Perl module.

If a package wants to install an example entry into /etc/inetd.conf, the entry has to be preceded with exactly one hash character (#). Such lines are treated as `commented out by user' by the update-inetd script and are not changed or activated during a package updates.

Some programs need to create pseudo-ttys. This should be done using Unix98 ptys if the C library supports it. The resulting program must not be installed setuid root, unless that is required for other functionality.

The files /var/run/utmp, /var/log/wtmp and /var/log/lastlog must be installed writeable by group utmp. Programs who need to modify those files must be installed install setgid utmp.

Some programs have the ability to launch an editor or pager program to edit or display a text document. Since there are lots of different editors and pagers available in the Debian distribution, the system administrator and each user should have the possibility to choose his/her preferred editor and pager.

In addition, every program should choose a good default editor/pager if none is selected by the user or system administrator.

Thus, every program that launches an editor or pager has to use the EDITOR or PAGER environment variables to determine the editor/pager the user wants to get started. If these variables are not set, the programs /usr/bin/editor and /usr/bin/pager have to be used, respectively.

These two files are managed through `alternatives.' That is, every package providing an editor or pager has to call the update-alternatives script to register these programs.

If it is very hard to adapt a program to make us of the EDITOR and PAGER variable, that program should be configured to use /usr/bin/sensible-editor and /usr/bin/sensible-pager as editor or pager program, respectively. These are two scripts provided in the Debian base system that check the EDITOR and PAGER variables and launches the appropriate program or falls back to /usr/bin/editor and /usr/bin/pager, automatically.

A program may also use the VISUAL environment variable to determine the user's choice of editor. If it exists, it should take precedence over EDITOR. This is in fact what /usr/bin/sensible-editor does.

Since the Debian base system already provides an editor and a pager program, there is no need for a package to depend on `editor' and `pager', nor is it necessary for a package to provide such virtual packages.

This section describes the locations and URLs that have to be used by all web servers and web application in the Debian system.

Cgi-bin executable files are installed in the directory /usr/lib/cgi-bin/<cgi-bin-name> and can be referred to as http://localhost/cgi-bin/<cgi-bin-name>

Debian packages which process electronic mail, whether mail-user-agents (MUAs) or mail-transport-agents (MTAs), must make sure that they are compatible with the configuration decisions below. Failure to do this may result in lost mail, broken From: lines, and other serious brain damage!

The mail spool is /var/spool/mail and the interface to send a mail message is /usr/sbin/sendmail (as per the FHS). The mail spool is part of the base system and not part of the MTA package.

All Debian MUAs, MTAs, MDAs and other mailbox accessing programs (like IMAP daemons) have to lock the mailbox in a NFS-safe way. This means that fcntl() locking has to be combined with dot locking. To avoid dead locks, a program has to use fcntl() first and dot locking after this or alternatively implement the two locking methods in a non blocking way

If it is not possible to establish both locks, the system shouldn't wait for the second lock to be established, but remove the first lock, wait a (random) time, and start over locking again.

Mailboxes are generally 660 user.mail unless the user has chosen otherwise. A MUA may remove a mailbox (unless it has nonstandard permissions) in which case the MTA or another MUA must recreate it if needed. Mailboxes must be writable by group mail.

The mail spool is 2775 mail.mail, and MUAs need to be setgid mail to do the locking mentioned above (and obviously need to avoid accessing other users' mailboxes using this privilege).

/etc/aliases is the source file for the system mail aliases (e.g., postmaster, usenet, etc.)--it is the one which the sysadmin and postinst scripts may edit. After /etc/aliases is edited the program or human editing it must call newaliases. All MTA packages should come with a newaliases program, even if it does nothing, but older MTA packages do not do this so programs should not fail if newaliases cannot be found.

The convention of writing forward to address in the mailbox itself is not supported. Use a .forward file instead.

The location for the rmail program used by UUCP for incoming mail is /usr/sbin/rmail, as per the FHS. Likewise, rsmtp, for receiving batch-SMTP-over-UUCP, is in /usr/sbin/rsmtp if it is supported.

If you need to know what name to use (for example) on outgoing news and mail messages which are generated locally, you should use the file /etc/mailname. It will contain the portion after the username and @ (at) sign for email addresses of users on the machine (followed by a newline).

A package should check for the existence of this file. If it exists it should use it without comment. (An MTA's prompting configuration script may wish to prompt the user even if it finds this file exists.) If it does not exist it should prompt the user for the value and store it in /etc/mailname as well as using it in the package's configuration. The prompt should make it clear that the name will not just be used by that package. For example, in this situation the INN package says: Please enter the `mail name' of your system. This is the hostname portion of the address to be shown on outgoing news and mail messages. The default is syshostname, your system's host name. Mail name [`syshostname']: where syshostname is the output of hostname --fqdn.

All the configuration files related to the NNTP (news) servers and clients should be located under /etc/news.

There are some configuration issues that apply to a number of news clients and server packages on the machine. These are: /etc/news/organization

A string which shall appear as the organization header for all messages posted by NNTP clients on the machine

Some programs can be configured with or without support for the X Window System. Typically, binaries produced with support for X will need the X shared libraries to run.

Such programs should be configured with X support, and should declare a dependency on xlib6g (which contains X shared libraries). Users who wish to use the program can install just the relatively small xfree86-common and xlib6g packages, and do not need to install the whole of X.

Do not create two versions (one with X support and one without) of your package.

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 conffiles 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/share/doc/X11/, /usr/include/X11/, or /usr/lib/X11/; these directories are actually symbolic links, which dpkg does not follow when unpacking a package. Instead, use /usr/X11R6/bin/, /usr/share/doc/package/ (i.e., place files with the rest of your package's documentation), /usr/X11R6/include/, and /usr/X11R6/lib/. This restriction governs only the paths used by the package as it is unpacked onto the system; it is permissible, and even preferable, for files within a package (shell scripts, for instance) to refer to the /usr/{bin,include,lib}/X11/ directories rather than their /usr/X11R6/ counterparts -- this way they do not have to be modified in the event that the X Window System packages install their files into a different directory in the future.

If you package a program that requires the (non-free) OSF/Motif library, you should try to determine whether the programs works reasonably well with the free re-implementation of Motif called LessTif. If so, build the package using the LessTif libraries; it can then go into the main section of the package repository and become an official part of the Debian distribution.

If however, the Motif-based program works insufficiently well with LessTif, you should instead provide "-smotif" and "-dmotif" versions (appending these identifiers to the name of the package), which are statically and dynamically linked against the Motif libraries, respectively. (All known versions of OSF/Motif permit redistribution of statically-linked binaries using the library, but check the license on your copy of Motif to be sure.) This two-package approach allows users without Motif to use the package, whereas users with Motif installed can enjoy the advantages of the dynamically-linked version (a considerable savings in disk space usage, download time, etc.). Neither "-smotif" nor "-dmotif" packages can go into the main section; if the licensing on the package is compatible with the Debian Free Software Guidelines, it may go into the contrib section; otherwise it must go into the non-free section.

Please refer to the `Debian Emacs Policy' (documented in debian-emacs-policy.gz of the emacsen-common package) for details of how to package emacs lisp programs.

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

Each game decides on its own security policy.

Games which require protected, privileged access to high-score files, savegames, etc., 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. (If an attacker can subvert any set-user-id game they can overwrite the executable of any other, causing other players of these games to run a Trojan horse program. With a set-group-id game the attacker only gets access to less important game data, and if they can get at the other players' accounts at all it will take considerably more effort.)

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.

As described in the FHS, binaries of games should be installed in the directory /usr/games. This also applies to games that use the X Window System. Manual pages for games (X and non-X games) should be installed in /usr/share/man/man6.

You must install manual pages in nroff source form, in appropriate places under /usr/share/man. You should only use sections 1 to 9 (see the FHS 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 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/share/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.

Manual pages should be installed compressed using gzip -9.

If one manpage needs to be accessible 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/share/man).

Info documents should be installed in /usr/share/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/share/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/share/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/share/info/foobar.info

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

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/share/doc/package, where package is the name of the package, 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/share/doc/package in the binary package. However, you don't need to install the instructions for building and installing the package, of course!

Former Debian releases placed all additional documentation in /usr/doc/package. To realize a smooth migration to /usr/share/doc/package, each package must maintain a symlink /usr/doc/package that points to the new location of its documentation in /usr/share/doc/packageThese symlinks will be removed in the future, but they have to be there for compatibility reasons until all packages have moved and the policy is changed accordingly.. The symlink must be created when the package is installed; it cannot be contained in the package itself due to problems with dpkg. One reasonable way to accomplish this is to put the following in the package's postinst: if [ "$1" = "configure" ]; then if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \ -a -d /usr/share/doc/#PACKAGE# ]; then ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE# fi fi And the following in the package's prerm: if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ -a -L /usr/doc/#PACKAGE# ]; then rm -f /usr/doc/#PACKAGE# fi

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

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

The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package, though.

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

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/<package-name>/copyright. This file must neither be compressed nor be a symbolic link.

In addition, the copyright file 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.

/usr/share/doc/<package-name> may be a symbolic link to a directory in /usr/share/doc only if two packages both come from the same source and the first package has a "Depends" relationship on the second. These rules are important because copyrights must be extractable by mechanical means.

Packages distributed under the UCB BSD license, the Artistic license, the GNU GPL, and the GNU LGPL should refer to the files /usr/share/common-licenses/BSD, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/GPL, and /usr/share/common-licenses/LGPL.

Why "licenses" and not "copyright"? Because /usr/doc/copyright used to contain all the copyright files, plus the four common licenses GPL, LGPL, Artistic and BSD. Now individual copyright files for packages are no longer in a common directory. Once /usr/doc/copyright is almost empty it makes sense to rename "copyright" to "licenses"

Why "common-licenses" and not "licenses"? Because if I put just "licenses" I'm sure I will receive a bug report saying "license foo is not included in the licenses directory. They are not all the licenses, just a few common ones. I could use /usr/share/doc/common-licenses but I think this is too long, and, after all, the GPL does not "document" anything, it is merely a license.

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

Any examples (configurations, source files, whatever), should be installed in a directory /usr/share/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. Architecture-specific example files should be installed in a directory /usr/lib/package/examples, and files in /usr/share/doc/package/examples symlink to files in it. Or the latter directory may be a symlink to the former.

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. The debian/changelog file should be installed in /usr/share/doc/package as changelog.Debian.gz. If the upstream changelog file is text formatted, it must be accessible as /usr/share/doc/package/changelog.gz. If the upstream changelog file is HTML formatted, it must be accessible as /usr/share/doc/package/changelog.html.gz. A plain text version of the changelog must be accessible as /usr/doc/package/changelog.gz (this can be created by lynx -dump -nolist). If the upstream changelog files do not already conform to this naming convention, then this may be achieved by either renaming the files or adding a symbolic link at the packaging developer's discretion.

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