If a package contains a binary or library which links to a shared library, we must ensure that when the package is installed on the system, all of the libraries needed are also installed. This requirement led to the creation of the shlibs system, which is very simple in its design: any package which provides a shared library also provides information on the package dependencies required to ensure the presence of this library, and any package which uses a shared library uses this information to determine the dependencies it requires. The files which contain the mapping from shared libraries to the necessary dependency information are called shlibs files.

Thus, when a package is built which contains any shared libraries, it must provide a shlibs file for other packages to use, and when a package is built which contains any shared libraries or compiled binaries, it must run dpkg-shlibdeps on these to determine the libraries used and hence the dependencies needed by this package.

In the past, the shared libraries linked to were determined by calling ldd, but now objdump is used to do this. The only change this makes to package building is that dpkg-shlibdeps must also be run on shared libraries, whereas in the past this was unnecessary. The rest of this footnote explains the advantage that this method gives.

We say that a binary foo directly uses a library libbar if it is explicitly linked with that library (that is, it uses the flag -lbar during the linking stage). Other libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load them automatically when it loads libbar. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries.

Unfortunately, the ldd program shows both the directly and indirectly used libraries, meaning that the dependencies determined included both direct and indirect dependencies. The use of objdump avoids this problem by determining only the directly used libraries.

A good example of where this helps is the following. We could update libimlib with a new version that supports a new graphics format called dgf (but retaining the same major version number). If we used the old ldd method, every package that uses libimlib would need to be recompiled so it would also depend on libdgf or it wouldn't run due to missing symbols. However with the new system, packages using libimlib can rely on libimlib itself having the dependency on libdgf and so they would not need rebuilding.

In the following sections, we will first describe where the various shlibs files are to be found, then how to use dpkg-shlibdeps, and finally the shlibs file format and how to create them if your package contains a shared library.

There are several places where shlibs files are found. The following list gives them in the order in which they are read by dpkg-shlibdeps. (The first one which gives the required information is used.)

debian/shlibs.local

This lists overrides for this package. Its use is described below (see ).

Put a call to dpkg-shlibdeps into your debian/rules file. If your package contains only compiled binaries and libraries (but no scripts), you can use a command such as: dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ debian/tmp/usr/lib/* Otherwise, you will need to explicitly list the compiled binaries and libraries.

If you are using debhelper, the dh_shlibdeps program will do this work for you. It will also correctly handle multi-binary packages.

This command puts the dependency information into the debian/substvars file, which is then used by dpkg-gencontrol. You will need to place a ${shlib:Depends} variable in the Depends field in the control file for this to work.

If dpkg-shlibdeps doesn't complain, you're done. If it does complain you might need to create your own debian/shlibs.local file, as explained below (see ).

If you have multiple binary packages, you will need to call dpkg-shlibdeps on each one which contains compiled libraries or binaries. In such a case, you will need to use the -T option to the dpkg utilities to specify a different substvars file. For more details on this and other options, see .

Each shlibs file has the same format. Lines beginning with # are considered to be comments and are ignored. Each line is of the form: library-name soname-version-number dependencies ...

We will explain this by reference to the example of the zlib1g package, which (at the time of writing) installs the shared library /usr/lib/libz.so.1.1.3.

library-name is the name of the shared library, in this case libz. (This must match the name part of the soname, see below.)

soname-version-number is the version part of the soname of the library. The soname is the thing that must exactly match for the library to be recognized by the dynamic linker, and is usually of the form name.so.major-version, in our example, libz.so.1.

This can be determined using the command objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME

dependencies has the same syntax as a dependency field in a binary package control file. It should give details of which packages are required to satisfy a binary built against the version of the library contained in the package. See for details.

In our example, if the first version of the zlib1g package which contained a minor number of at least 1.3 was 1:1.1.3-1, then the shlibs entry for this library could say: libz 1 zlib1g (>= 1:1.1.3) The version-specific dependency is to avoid warnings from the dynamic linker about using older shared libraries with newer binaries.

If your package provides a shared library, you should create a shlibs file following the format described above. It is usual to call this file debian/shlibs (but if you have multiple binary packages, you might want to call it debian/shlibs.package instead). Then let debian/rules install it in the control area: install -m644 debian/shlibs debian/tmp/DEBIAN or, in the case of a multi-binary package: install -m644 debian/shlibs.package debian/package/DEBIAN/shlibs An alternative way of doing this is to create the shlibs file in the control area directly from debian/rules without using a debian/shlibs file at all,

This is what dh_makeshlibs in the debhelper suite does.

As dpkg-shlibdeps reads the DEBIAN/shlibs files in all of the binary packages being built from this source package, all of the DEBIAN/shlibs files should be installed before dpkg-shlibdeps is called on any of the binary packages.

This file is intended only as a temporary fix if your binaries or libraries depend on a library whose package does not yet provide a correct shlibs file.

We will assume that you are trying to package a binary foo. When you try running dpkg-shlibdeps you get the following error message (-O displays the dependency information on stdout instead of writing it to debian/substvars, and the lines have been wrapped for ease of reading): $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar (soname 1, path /usr/lib/libbar.so.1, dependency field Depends) shlibs:Depends=libc6 (>= 2.2.2-2) You can then run ldd on the binary to find the full location of the library concerned: $ ldd foo libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000) libc.so.6 => /lib/libc.so.6 (0x40032000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) So the foo binary depends on the libbar shared library, but no package seems to provide a *.shlibs file handling libbar.so.1 in /var/lib/dpkg/info/. Let's determine the package responsible: $ dpkg -S /usr/lib/libbar.so.1 bar1: /usr/lib/libbar.so.1 $ dpkg -s bar1 | grep Version Version: 1.0-1 This tells us that the bar1 package, version 1.0-1, is the one we are using. Now we can file a bug against the bar1 package and create our own debian/shlibs.local to locally fix the problem. Including the following line into your debian/shlibs.local file: libbar 1 bar1 (>= 1.0-1) should allow the package build to work.

As soon as the maintainer of bar1 provides a correct shlibs file, you should remove this line from your debian/shlibs.local file. (You should probably also then have a versioned Build-Depends on bar1 to help ensure that others do not have the same problem building your package.)

This section describes the formats to be used 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. For this reason, please look very carefully at the details. We want the messages to have the same format in terms of wording, 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 is not covered specifically in the sections below.

Every message should fit in one line (fewer than 80 characters), start with a capital letter and end with a period (.) and line feed ("\n").

There are standard message formats for the following situations. They should be used by the init.d scripts.

When daemons are started

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-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 --exec /usr/sbin/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. You should 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.

Packages must not modify the configuration file /etc/crontab, and they must not 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 of the package in one or more 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 must be scripts (e.g., shell scripts or Perl scripts) so that they can easily be modified by the local system administrator. In addition, they should 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. 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.

Menu entries should follow the current menu policy found in the menu-policy files in the debian-policy package. It may also be found on the Debian FTP site ftp.debian.org as the file /debian/doc/package-developer/menu-policy.txt.gz, or in the equivalent location on your local mirror.

The Debian menu package provides a standard interface between packages providing applications and documents, and menu programs (either X window managers or text-based menu programs such 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 also refer to the Debian Menu System documentation 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 found in the mime-policy files in the debian-policy package. It may also be found on the Debian FTP site ftp.debian.org as the file /debian/doc/package-developer/mime-policy.txt.gz, or in the equivalent location on your local mirror.

MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) 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 so that all applications interpret a keyboard event the same way, all programs in the Debian distribution must be configured to comply with the following guidelines.

The following keys must have the specified interpretations: <--

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 the following cases:

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.

A program must not 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 usually depends on environment variables for its configuration, the program should 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 must be replaced by a small `wrapper' shell script which sets the environment variables if they are not already defined, and calls the original program.

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

Furthermore, as /etc/profile is a configuration file of the base-files package, other packages must not put any environment variables or other commands into that file.

Two different packages must not 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' or the `Conflicts' mechanism. See and respectively.) If this case happens, one of the programs must be renamed. The maintainers should report this to the debian-devel mailing list and try to find a consensus about which program will have to be renamed. If a consensus cannot be reached, both programs must be renamed.

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

Note that by default 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 -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.

Debugging symbols are useful for error diagnosis, investigation of core dumps (which may be submitted by users in bug reports), or testing and developing the software. Therefore it is recommended to support building the package with debugging information through the following interface: If the environment variable DEB_BUILD_OPTIONS contains the string debug, compile the software with debugging information (usually this involves adding the -g flag to CFLAGS). This allows the generation of a build tree with debugging information. If the environment variable DEB_BUILD_OPTIONS contains the string nostrip, do not strip the files at installation time. This allows one to generate a package with debugging information included.

Rationale: Using -g by default causes wasted CPU cycles since the information is stripped away anyway; this can have a significant impact on the efficiency of the autobuilders. Having a standard way to build a debugging variant also makes it easier to build debugging bins and libraries since it provides a documented way of getting this type of build; one does not have to manually edit debian/rules or Makefiles.

It is up to the package maintainer to decide what compilation options are best for the package. Certain binaries (such as computationally-intensive programs) will 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 will need to be compiled twice.

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

You might also want to use the options --remove-section=.comment and --remove-section=.note on both shared libraries and executables, and --strip-debug on static libraries.

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.

Shared object files (often .so files) that are not public libraries, that is, they are not meant to be linked to by third party executables (binaries of other packages), should be installed in subdirectories of the /usr/lib directory. Such files are exempt from the rules that govern ordinary shared libraries, except that they must not be installed executable and should be stripped.

A common example are the so-called ``plug-ins'', internal shared objects that are dynamically loaded by programs using .

Packages containing shared libraries that may be linked to by other packages' binaries, but which for some compelling reason can not be installed in /usr/lib directory, may install the shared library files in subdirectories of the /usr/lib directory, in which case they should arrange to add that directory in /etc/ld.so.conf in the package's post-installation script, and remove it in the package's post-removal script.

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 files). 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 (such as library dependency information for static linking). Also, they're essential for programs using libltdl.

Although libtool is fully capable of linking against shared libraries which don't have .la files, as it is 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 version 1.4 (and to a lesser extent libtool version 1.3), the .la files 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 should include the .la files in the -dev package, unless the package relies on libtool's libltdl library, in which case the .la files must go in the run-time library package.

You must 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: librarynamesoversion, where soversion is the version number in the soname of the shared library

The soname is the shared object name: 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. For example, if the soname of the library is libfoo.so.6, the library package would be called libfoo6.

If you prefer only to support one development version at a time you may name the development package libraryname-dev; otherwise you may need to use dpkg's Conflicts mechanism (see ) to ensure that the user only installs one development version at a time (as different development versions are likely to have the same header files in them, which would cause a filename clash if both were installed). Typically the development version should also have an exact version dependency on the runtime library, to make sure that compilation and linking happens correctly. The ${Source-Version} substitution variable can be useful for this purpose.

Packages which use the shared library should have a dependency on the name of the shared library package, librarynamesoversion. When the soname changes you can have both versions of the library installed while migrating 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 soversion in the package name), or if the development package is small you may include them in there.

If you have several shared libraries built from the same source tree you may lump them all together into a single shared library package, provided that you change all of 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).

Shared libraries should not be installed executable, since the dynamic linker does not require this and trying to execute a shared library usually 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 should use set -e or check the exit status of every command.

The standard shell interpreter /bin/sh can be a symbolic link to any POSIX compatible shell, if echo -n does not generate a newline.

Debian policy specifies POSIX behavior for /bin/sh, but echo -n has widespread use in the Linux community (in particular including this policy, the Linux kernel source, many Debian scripts, etc.). This echo -n mechanism is valid but not required under POSIX, hence this explicit addition. Also, rumour has it that this shall be mandated under the LSB anyway.

You may wish to 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, which can be found at .

It can also be found on or on the ftp site ftp.cpan.org as /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot.

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

The Debian base system 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, you can 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.)

Packages must not 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 must call MAKEDEV in the postinst script, after asking the user for permission to do so.

Packages must not remove any device files in the postrm or any other script. This is left to the system administrator.

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

Log files should usually be named /var/log/package.log. If you have many log files, or need a separate directory for permission reasons (/var/log is writable only by root), you should usually create a directory named /var/log/package and place your log files there.

Log files must be rotated occasionally so that they don't grow indefinitely; the best way to do this is to drop a log rotation configuration file into the directory /etc/logrotate.d and use the facilities provided by logrotate.

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.

The use of logrotate, a program developed by Red Hat, is better, as it centralizes log management. It has both a configuration file (/etc/logrotate.conf) and a directory where packages can drop their individual log rotation configurations (/etc/logrotate.d).

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 should 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), that is mode 644 or 755.

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; again there is no point in making them unreadable to those users who must not be allowed to execute them.

It is possible to arrange that the system administrator can reconfigure the package to correspond to their local security policy by changing the permissions on a binary: they can do this by using dpkg-statoverride, as described below.

Ordinary files installed by dpkg (as opposed to conffiles and other similar objects) normally have their permissions reset to the distributed permissions when the package is reinstalled. However, the use of dpkg-statoverride overrides this default behaviour. If you use this method, you should remember to describe dpkg-statoverride in the package documentation; being a relatively new addition to Debian, it is probably not yet well-known.

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, as in this case you need a statically allocated id).

If you need a statically allocated id, you must ask for a user or group id from the base-passwd maintainer, and must not release the package until you have been allocated one. Once you have been allocated one you must either make the package depend on a version of the base-passwd package with the id present in /etc/passwd or /etc/group, or arrange for your package to create the user or group itself with the correct id (using adduser) in its preinst or postinst. (Doing it in the postinst is to be preferred if it is possible, otherwise a pre-dependency will be needed on the adduser package.)

On the other hand, the program might be able to determine the uid or gid from the user or group name at runtime, so that a dynamically allocated id can be used. In this case you should 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 preinst or postinst 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 should be used: arch-os

The following architectures and operating systems are currently recognised by dpkg-archictecture. The architecture, arch, is one of the following: alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sh, sheb, sparc and sparc64. The operating system, os, is one of: linux, gnu, freebsd and openbsd. 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 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.

The Debian base system already provides an editor and a pager program,

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

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

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

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 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: /etc/news/organization

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

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.

You should 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'.

Each program, utility, and function should have an associated manpage included in the same package. It is suggested that all configuration files also have a manual page included as well.

If no manual page is available for a particular program, utility, function or configuration file and this is reported as a bug to the Debian Bug Tracking System, a symbolic link from the requested manual page to the manual page may 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]/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. You should not create hard links in the manual page directories, nor 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). If you do not create any links (whether symlinks, hard links, or .so directives) in the filesystem to the alternate names of the manpage, then you should not rely on man finding your manpage under those names based solely on the information in the manpage's header.

Supporting this in man often requires unreasonable processing time to find a manual page or to report that none exists, and moves knowledge into man's database that would be better left in the filesystem. This support is therefore deprecated and will cease to be present in the future.

Info documents should be installed in /usr/share/info. They should be compressed with gzip -9.

Your package should call install-info to update the Info dir file in its postinst script when called with a configure argument, for example: 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 should remove the entries in the prerm script when called with a remove argument: install-info --quiet --remove /usr/share/info/foobar.info

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

Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. Text documentation should be installed in the 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!

Files in /usr/share/doc should not be referenced by any program, and the system administrator should be able to delete them without causing any programs to break. Any files that are referenced by programs but are also useful as standalone documentation should be installed under /usr/share/package/ with symbolic links from /usr/share/doc/package/.

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

The debhelper script dh_installdocs does this automatically.

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

If your package comes with extensive documentation in a markup 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.

Other formats such as PostScript may be provided at the package maintainer's discretion.

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/package/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 should explain briefly what modifications were made in the Debian version of the package compared to the upstream one. It should name the original authors of the package and the Debian maintainer(s) who were involved with its creation.

A copy of the file which will be installed in /usr/share/doc/package/copyright should be in debian/copyright in the source package.

/usr/share/doc/package may be a symbolic link to another directory in /usr/share/doc only if the two packages both come from the same source and the first package Depends 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 respectively, rather than quoting them in the copyright file.

You should 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 with symbolic links to them from /usr/share/doc/package/examples, or the latter directory itself may be a symbolic link to the former.

Packages that are not Debian-native must contain a compressed copy of the debian/changelog file from the Debian source tree in /usr/share/doc/package with the name changelog.Debian.gz. If an upstream changelog is available, it should be accessible as /usr/share/doc/package/changelog.gz in plain text. If the upstream changelog is distributed in HTML, it should be made available in that form as /usr/share/doc/package/changelog.html.gz and a plain text changelog.gz should be generated from it using, for example, lynx -dump -nolist. If the upstream changelog files do not already conform to this naming convention, then this may be achieved either by renaming the files, or by adding a symbolic link, at the maintainer's discretion.

Rationale: People should not have to look in places for upstream changelogs merely because they are given different names or are distributed in HTML format.

All of these files 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.