Debian Policy Manual - chapter 5
Customized programs


5.1 Architecture specification strings

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.


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


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

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.


5.4 Web servers and applications

This section describes the locations and URLs that have to 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 can 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/doc/package 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 use the /usr/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.


5.5 Mail transport 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 FSSTND). The mail spool is part of the base system and not part of the MTA package.

All Debian MUAs and MTAs have to use the maillock and mailunlock functions provided by the liblockfile packages to lock and unlock mail boxes. These functions implement a NFS-safe locking mechanism. (It is ok if MUAs and MTAs don't link against liblockfile but use a compatible mechanism. Please compare the mechanisms very carefully!)

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

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

5.7 Programs for the X Windows system

Some programs can be configured with or without support for X Windows. Typically these binaries produced when configured 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 (for the X11R6 libraries). Users who wish to use the program can install just the relatively small xlib6g package, 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 conffile. If the local system administrator wants to customise X applications globally, the file /etc/X11/Xresources should be used.

If you package a program that requires a non-free Motif library, it would be good if you can provide a "foo-smotif" and a "foo-dmotif" package, containing a (against Motif libraries) statically and a dynamically linked version, respectively. This way, users without Motif can use the package too, while users that have Motif installed get the advantages of a dynamically linked version.

However, if your package works reliably with lesstif, you should package it with lesstif, and not with Motif at all.

Note, that packages that require non-free Motif libraries can't go into the main section. If your package is free otherwise, it should go into contrib. Otherwise it has to go into non-free.


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

5.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, 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 FSSTND, binaries of games should be installed in the directory /usr/games. This also applies to games that use the X windows system. Manual pages for games (X and non-X games) should be installed in /usr/man/man6.


Debian Policy Manual - Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz.
Contents; abstract; next; back.
version 2.5.0.0, 1998-10-30
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