[ previous ] [ Abstract ] [ Copyright Notice ] [ Contents ] [ next ]

Debian Policy Manual
Chapter 12 Customized programs


12.1 Architecture specification strings

If a program needs to specify an architecture specification string in some place, the following format should 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.


12.2 Daemons

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

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 a package updates.


12.3 Using pseudo-ttys and modifying wtmp, utmp and lastlog

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


12.4 Editors and pagers

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 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 should be used, respectively.

These two files are managed through `alternatives.' That is, 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 us of the EDITOR and PAGER variables, that program may 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 launch the appropriate program or fall 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.

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. [22]


12.5 Web servers and applications

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

  1. Cgi-bin executable files are installed in the directory
         		  /usr/lib/cgi-bin/<cgi-bin-name>
    

    and should be referred to as

         		  http://localhost/cgi-bin/<cgi-bin-name>
    
  2. Access to html documents

    Html documents for a package are stored in /usr/share/doc/package but should be accessed via symlinks as /usr/doc/package[23] and can be referred to as

         		  http://localhost/doc/<package>/<filename>
    
  3. Web Document Root

    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-root is unavoidable then use

         		  /var/www
    

    as the Document Root. This might be just a symbolic link to the location where the sysadmin has put the real document root.


12.6 Mail transport, delivery and user agents

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) 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[24]. Using the functions maillock and mailunlock provided by the liblockfile*[25] packages is the recommended way to realize this.

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


12.7 News system configuration

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 should appear as the organization header for all messages posted by NNTP clients on the machine

/etc/news/server
Contains the FQDN of the upstream NNTP server, or localhost if the local machine is an NNTP server.

Other global files may be added as required for cross-package news configuration.


12.8 Programs for the X Window System

Programs that may 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, unless the package in question is of standard or higher priority, in which case X-specific binaries may be split into a separate package, or alternative versions of the package with X support may be provided.

Packages which 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. [26]

Packages that provide a terminal emulator for the X Window System which support a terminal type with a terminfo description provided in the ncurses-base package 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.

Packages that provide window managers 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 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.

  1. Fonts of any type supported by the X Window System should be be in a separate binary package from any executables, libraries, or documentation (except that specific to the fonts shipped); if a program or library is unusable without one or more specific fonts, the package containing the program or library should declare a dependency on the package(s) containing the font(s) it requires.
  2. BDF fonts should be converted to PCF fonts with the bdftopcf utility (available in the xutils package, gzipped, and placed in a directory that corresponds to their resolution:
  3. Speedo fonts should be placed in /usr/X11R6/lib/X11/fonts/Speedo/.
  4. Type 1 fonts should be placed in /usr/X11R6/lib/X11/fonts/Type1/. If font metric files are available, they may be placed here as well.
  5. Subdirectories of /usr/X11R6/lib/X11/fonts/ other than those listed above should be neither created nor used. (The PEX and cyrillic directories are excepted for historical reasons, but installation of files into these directories remains discouraged.)
  6. Font packages may, instead of placing files directly in the X font directories listed above, provide symbolic links in the font directory which point to the files' actual location in the filesystem. Such a location should comply with the FHS.
  7. Font packages should not contain both 75dpi and 100dpi versions of a font. If both are available, they should be provided in separate binary packages with "-75dpi" or "-100dpi" appended to the names of the packages containing the corresponding fonts.
  8. Fonts destined for the misc subdirectory should not be included in the same package as 75dpi or 100dpi fonts; instead, they should be provided in a separate package with "-misc" appended to its name.
  9. Font packages must not provide the files fonts.dir, fonts.alias, or fonts.scale in a font directory.
  10. Font packages must declare a dependency on xutils and, in the package post-installation and post-removal scripts, invoke the mkfontdir command on each directory into which they installed fonts.
  11. Font packages that provide one or more fonts.scale files as described above must declare a versioned dependency on xutils (>= 4.0.2) and invoke update-fonts-scale on each directory into which they installed fonts before invoking mkfontdir on that directory. This invocation must occur in both the post-installation and post-removal scripts.
  12. Font packages that provide one or more fonts.alias files as described above must declare a versioned dependency on xutils (>= 4.0.2) and, in the package post-installation and post-removal scripts, invoke update-fonts-alias on each directory into which they installed fonts.
  13. Font packages must not provide alias names for the fonts they include which collide with alias names already in use by fonts already packaged.
  14. Font packages must not provide fonts with the same XLFD registry name as another font already packaged.

Application defaults files must be installed in the directory /usr/X11R6/lib/X11/app-defaults/. [27] They should not be registered as conffiles or otherwise treated as configuration files. Customization of programs' X resources may 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. 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 installing package to destroy a previously-existing /etc/X11/Xresources file which had been customized by the system administrator. [28]

Packages using the X Window System should abide by the FHS standard whenever possible; they should install binaries, libraries, manual pages, and other files in FHS-mandated locations wherever possible. This means that files must not be installed into /usr/X11R6/bin/, /usr/X11R6/lib/, or /usr/X11R6/man/ unless this is necessary for the package to operate properly. 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 (symlinks from the X11R6 directories to 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 FHS-compliant locations.

Programs that require the non-DFSG-compliant OSF/Motif library 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 OSF/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 OSF/Motif in his or her possession.


12.9 Emacs lisp programs

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.


12.10 Games

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


[ previous ] [ Abstract ] [ Copyright Notice ] [ Contents ] [ next ]
Debian Policy Manual
version 3.5.0.0, 2001-01-28
Ian Jackson ijackson@gnu.ai.mit.edu
Christian Schwarz schwarz@debian.org
revised: David A. Morris bweaver@debian.org
The Debian Policy mailing List debian-policy@lists.debian.org