If a program needs to specify an architecture specification string in some place, the following format should be used: arch-os[45].
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 with other Linux distributions. We also don't use something like 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 must not be modified by other packages.
If a package requires a new entry in one of these files, the maintainer should
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 must not be modified by the
package's scripts except via the update-inetd
script or the
DebianNet.pm Perl module. See their documentation for details on
how to add entries.
If a package wants to install an example entry into
/etc/inetd.conf, the entry must 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
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 which need to modify those files must be installed 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 must use the EDITOR or PAGER environment variable to determine the editor or pager the user wishes to use. If these variables are not set, the programs /usr/bin/editor and /usr/bin/pager should be used, respectively.
These two files are managed through the dpkg
`alternatives'
mechanism. Thus every package providing an editor or pager must call the
update-alternatives
script to register these programs.
If it is very hard to adapt a program to make use of the EDITOR or PAGER variables, that program may be configured to use /usr/bin/sensible-editor and /usr/bin/sensible-pager as the editor or pager program respectively. These are two scripts provided in the Debian base system that check the EDITOR and PAGER variables and launch the appropriate program, and fall back to /usr/bin/editor and /usr/bin/pager if the variable is not set.
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.
It is not required for a package to depend on editor and pager, nor is it required for a package to provide such virtual packages.[46]
This section describes the locations and URLs that should be used by all web servers and web applications in the Debian system.
/usr/lib/cgi-bin/cgi-bin-name
and should be referred to as
http://localhost/cgi-bin/cgi-bin-name
HTML documents for a package are stored in /usr/share/doc/package and can be referred to as
http://localhost/doc/package/filename
The web server should restrict access to the document tree so that only clients on the same host can read the documents. If the web server does not support such access controls, then it should not provide access at all, or ask about providing access during installation.
Web Applications should try to avoid storing files in the Web Document Root. Instead they should use the /usr/share/doc/package directory for documents and register the Web Application via the menu package. If access to the web document root is unavoidable then use
/var/www
as the Document Root. This might be just a symbolic link to the location where the system administrator has put the real document root.
Debian packages which process electronic mail, whether mail user agents (MUAs) or mail transport agents (MTAs), must ensure 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/mail and the interface to send a mail message is /usr/sbin/sendmail (as per the FHS). On older systems, the mail spool may be physically located in /var/spool/mail, but all access to the mail spool should be via the /var/mail symlink. 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 (such as IMAP daemons) must lock the mailbox in an NFS-safe way. This means that fcntl() locking must be combined with dot locking. To avoid deadlocks, a program should use fcntl() first and dot locking after this, or alternatively implement the two locking methods in a non blocking way[47]. Using the functions maillock and mailunlock provided by the liblockfile*[48] packages is the recommended way to realize this.
Mailboxes are generally mode 660 user.mail unless the system administrator 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 root.mail, and MUAs should be setgid mail to do the locking mentioned above (and must obviously 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 must come with a newaliases
program, even if it does
nothing, but older MTA packages did not do this so programs should not fail if
newaliases
cannot be found. Note that because of this, all MTA
packages must have Provides, Conflicts and
Replaces: mail-transport-agent control file fields.
The convention of writing forward to address in the mailbox itself is not supported. Use a .forward file instead.
The rmail
program used by UUCP for incoming mail should be
/usr/sbin/rmail. Likewise, rsmtp
, for receiving
batch-SMTP-over-UUCP, should be /usr/sbin/rsmtp if it is
supported.
If your package needs to know what hostname to use on (for example) 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).
Such package should check for the existence of this file when it is being
configured. If it exists, it should be used without comment, although an MTA's
configuration script may wish to prompt the user even if it finds that this
file exists. If the file does not exist, the package should prompt the user
for the value (preferably using debconf
) 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 could say
something like:
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:
Other global files may be added as required for cross-package news configuration.
Programs that can be configured with support for the X Window System must be configured to do so and must declare any package dependencies necessary to satisfy their runtime requirements when using the X Window System. If such a package is of higher priority than the X packages on which it depends, it is required that either the X-specific components be split into a separate package, or that an alternative version of the package, which includes X support, be provided, or that the package's priority be lowered.
Packages that provide an X server that, directly or indirectly, communicates with real input and display hardware should declare in their control data that they provide the virtual package xserver.[49]
Packages that provide a terminal emulator for the X Window System which meet the criteria listed below should declare in their control data that they provide the virtual package x-terminal-emulator. They should also register themselves as an alternative for /usr/bin/x-terminal-emulator, with a priority of 20.
To be an x-terminal-emulator, a program must:
Packages that provide a window manager should declare in their control data that they provide the virtual package x-window-manager. They should also register themselves as an alternative for /usr/bin/x-window-manager, with a priority calculated as follows:
Packages that provide fonts for the X Window System[51] must do a number of things to ensure that they are both available without modification of the X or font server configuration, and that they do not corrupt files used by other font packages to register information about themselves.
bdftopcf
utility
(available in the xutils package, gzipped, and placed
in a directory that corresponds to their resolution:
update-fonts-scale
on each directory
into which they installed fonts before invoking
update-fonts-dir
on that directory. This invocation must occur in
both the postinst
(for all arguments) and postrm
(for
all arguments except upgrade) scripts.
update-fonts-alias
on each directory
into which they installed fonts. This invocation must occur in both the
postinst
(for all arguments) and postrm
(for all
arguments except upgrade) scripts.
update-fonts-dir
on each directory into
which they installed fonts. This invocation must occur in both the
postinst
(for all arguments) and postrm
(for all
arguments except upgrade) scripts.
Application defaults files must be installed in the directory /etc/X11/app-defaults/ (use of a localized subdirectory of /etc/X11/ as described in the X Toolkit Intrinsics - C Language Interface manual is also permitted). They must be registered as conffiles or handled as configuration files. Packages must not provide the directory /usr/X11R6/lib/X11/app-defaults/.
Customization of programs' X resources may also be supported with the provision of a file with the same name as that of the package placed in the /etc/X11/Xresources/ directory, which must registered as a conffile or handled as a configuration file.[53] Important: packages that install files into the /etc/X11/Xresources/ directory must conflict with xbase (<< 3.3.2.3a-2); if this is not done it is possible for the installing package to destroy a previously-existing /etc/X11/Xresources file which had been customized by the system administrator.
Packages using the X Window System should not be configured to install files
under the /usr/X11R6/ directory unless they use
imake
. The /usr/X11R6/ directory hierarchy should be
regarded as deprecated for all packages except the X Window System itself, and
those which use the imake
program it provides, in which case the
packages may transition out of the /usr/X11R6/ directory at the
maintainer's discretion.[54]
Programs that use GNU autoconf
and automake
are
usually easily configured at compile time to use /usr/ instead of
/usr/X11R6/, and this should be done whenever possible.
Configuration files for window managers and display managers should be placed
in a subdirectory of /etc/X11/ corresponding to the package name
due to these programs' tight integration with the mechanisms of the X Window
System. Application-level programs should use the /etc/ directory
unless otherwise mandated by policy. The installation of files into
subdirectories of /usr/X11R6/include/X11/ and
/usr/X11R6/lib/X11/ is permitted but discouraged; package
maintainers should determine if subdirectories of /usr/lib/ and
/usr/share/ can be used instead. (The use of symbolic links from
the X11R6 directories to other FHS-compliant locations is
encouraged if the program is not easily configured to look elsewhere for its
files.) Packages must not provide or install files into the directories
/usr/bin/X11/, /usr/include/X11/ or
/usr/lib/X11/. Files within a package should, however, make
reference to these directories, rather than their X11R6-named
counterparts /usr/X11R6/bin/, /usr/X11R6/include/X11/
and /usr/X11R6/lib/X11/, if the resources being referred to have
not been moved to other FHS-compliant locations.
Programs that require the non-DFSG-compliant OSF/Motif or OpenMotif libraries[55] should be compiled against and tested with LessTif (a free re-implementation of Motif) instead. If the maintainer judges that the program or programs do not work sufficiently well with LessTif to be distributed and supported, but do so when compiled against Motif, then two versions of the package should be created; one linked statically against Motif and with -smotif appended to the package name, and one linked dynamically against Motif and with -dmotif appended to the package name. Both Motif-linked versions are dependent upon non-DFSG-compliant software and thus cannot be uploaded to the main distribution; if the software is itself DFSG-compliant it may be uploaded to the contrib distribution. While known existing versions of Motif permit unlimited redistribution of binaries linked against the library (whether statically or dynamically), it is the package maintainer's responsibility to determine whether this is permitted by the license of the copy of Motif in his or her possession.
Perl programs and modules should follow the current Perl policy as defined in
the file found on ftp.debian.org
in /debian/doc/package-developer/perl-policy.txt.gz
or your local mirror. In addition, it is included in the
debian-policy package.
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 mode 755, owner root and group root.
Each game decides on its own security policy.
Games which require protected, privileged access to high-score files, savegames, etc., may 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. You should 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.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org