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

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


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


5.5 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/share/doc/package but should be accessed via symlinks as /usr/doc/package[3] 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/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.


5.6 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 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[4]. Using the functions maillock and mailunlock provided by the liblockfile*[5] 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 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.


5.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 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.8 Programs for the X Window System

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.


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


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


[ previous ] [ Abstract ] [ Copyright Notice ] [ Contents ] [ next ]
Debian Policy Manual
version 3.1.1.1, 1999-11-22
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