X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=policy.sgml;h=b1c1018af0a515ebfd9b33364516cb0c4bd378d5;hb=6b00973823cc99e6b50eab6489747d0b8c77e3e1;hp=d88c75455e35e7f53e465cf8336bd3bb95d23f96;hpb=c6e5ed4eb7ebf1d791b8a98cafd3db7c5b4e27c4;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index d88c754..b1c1018 100644 --- a/policy.sgml +++ b/policy.sgml @@ -4,2588 +4,7076 @@ %versiondata; ]> - - - - -Debian Policy Manual -<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ -<author>Christian Schwarz <email/schwarz@debian.org/ -<author>revised: David A. Morris <email/bweaver@debian.org/ -<version>version &version;, &date; - -<abstract> -This manual describes the policy requirements for the Debian GNU/Linux -distribution. This includes the structure and contents of the Debian -archive, several design issues of the operating system, as well as -technical requirements that each package must satisfy to be included -in the distribution. -</abstract> - -<copyright>Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz. -<p> - -This manual is free software; you may redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 2, or (at your option) any -later version. -<p> - -This is distributed in the hope that it will be useful, but -<em>without any warranty</em>; without even the implied warranty of -merchantability or fitness for a particular purpose. See the GNU -General Public License for more details. -<p> - -A copy of the GNU General Public License is available as -<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux -distribution or on the World Wide Web at -<url id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it -by writing to the Free Software Foundation, Inc., 59 Temple Place - -Suite 330, Boston, MA 02111-1307, USA. -<p> - -<toc sect> - -<chapt id="scope">About this manual -<p> - -<sect>Scope -<p> - -This manual describes the policy requirements for the Debian GNU/Linux -distribution. This includes the structure and contents of the Debian -archive, several design issues of the operating system, as well as -technical requirements that each package must satisfy to be included -in the distribution. -<p> - -This manual does <em/not/ describe the technical mechanisms involved -in package creation, installation, and removal. This information can -be found in the <em>Debian Packaging Manual</em> and the <em>Debian -System Administrators' Manual</em>. -<p> - -This document assumes familiarity with these other two manuals. -Unfortunately, the <em>System Administrators' Manual</em> does not -exist yet. -<p> - -Much of the information presented in this manual will be useful even -when building a package which is to be distributed in some other way -or is for local use. -<p> - -<sect>New versions of this document -<p> - -The current version of this document is always accessible from the -Debian FTP server at -<url id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz"> -or from the Debian WWW server at -<url id="http://www.debian.org/doc/manuals/debian-policy/"> -<p> - -There is also a home page for the <em>Debian Policy Manual</em> that -contains links to the current development version of this document as -well as an archive of old versions. The URL is -<url id="http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/"> -<p> - -In addition, this manual is distributed via the Debian package -<tt>debian-policy</tt> -<p> - -<sect>Feedback -<p> - -As the Debian GNU/Linux system is continuously evolving this manual is -changed from time to time. -<p> - -While the authors of this document tried hard not to include any typos -or other errors these still occur. If you discover an error in this -manual or if you want to tell us any comments, suggestions, or critics -please send an email to the Debian Policy Manager, Christian -Schwarz <email>schwarz@debian.org</email>, the developers' mailing -list <email>debian-devel@lists.debian.org</email>, or submit a bug report -against the <tt>debian-policy</tt> package. -<p> - -<chapt>The Debian Archive -<p> - -The Debian GNU/Linux system is maintained and distributed as a -collection of <em>packages</em>. Since there are so many of them (over -1000) they are split into <em>sections</em> and <em>priorities</em> to -simplify handling of them. -<p> - -The effort of the Debian project is to build a free operating system, -but not every package we want to make accessible is <em>free</em> in -our sense (see Debian Free Software Guidelines, below), or may be -imported/exported without restrictions. Thus, the archive is split -into the sections <em/main/, <em/non-us/, <em/non-free/, and -<em/contrib/. -<p> - -The <em/main/ section forms the <em>Debian GNU/Linux distribution</em>. -<p> - -Packages in the other sections are not considered as part of the -Debian distribution, though we support their use, and we provide -infrastructure for them (such as our bug-tracking system and mailing -lists). This Debian Policy Manual applies to these packages as well. -<p> - -<sect id="pkgcopyright">Package copyright and sections -<p> - -The aims of this policy are: -<p> - -<list compact> -<item> -We want to make as much software available as we can.<p> -<item> -We want to encourage everyone to write free software.<p> -<item> -We want to make it easy for people to produce CD-ROMs of our system -without violating any licenses, import/export restrictions, or any -other laws.<p> -</list> -<p> - -<sect1>The Debian Free Software Guidelines -<p> - -The Debian Free Software Guidelines (DFSG) as is our definition of `free' -software. -<p> - -<enumlist> -<item>Free Redistribution -<p> -The license of a Debian component may not restrict any party from -selling or giving away the software as a component of an aggregate -software distribution containing programs from several different -sources. The license may not require a royalty or other fee for such -sale. -<p> - -<item>Source Code -<p> - -The program must include source code, and must allow distribution in -source code as well as compiled form. -<p> - -<item>Derived Works -<p> - -The license must allow modifications and derived works, and must allow -them to be distributed under the same terms as the license of the original -software. -<p> - -<item>Integrity of The Author's Source Code -<p> - -The license may restrict source-code from being distributed in modified -form <em/only/ if the license allows the distribution of ``patch files'' -with the source code for the purpose of modifying the program at build -time. The license must explicitly permit distribution of software built -from modified source code. The license may require derived works to -carry a different name or version number from the original software. -(This is a compromise. The Debian group encourages all authors to not - restrict any files, source or binary, from being modified.) -<p> - -<item>No Discrimination Against Persons or Groups -<p> - -The license must not discriminate against any person or group of -persons. -<p> - -<item>No Discrimination Against Fields of Endeavor -<p> - -The license must not restrict anyone from making use of the program -in a specific field of endeavor. For example, it may not restrict the -program from being used in a business, or from being used for genetic -research. -<p> - -<item>Distribution of License -<p> - -The rights attached to the program must apply to all to whom the -program is redistributed without the need for execution of an -additional license by those parties. -<p> - -<item>License Must Not Be Specific to Debian -<p> - -The rights attached to the program must not depend on the program's -being part of a Debian system. If the program is extracted from Debian -and used or distributed without Debian but otherwise within the terms -of the program's license, all parties to whom the program is redistributed -should have the same rights as those that are granted in conjunction with -the Debian system. -<p> - -<item>License Must Not Contaminate Other Software -<p> - -The license must not place restrictions on other software that is -distributed along with the licensed software. For example, the -license must not insist that all other programs distributed on the -same medium must be free software. -<p> - -<item>Example Licenses -<p> -The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses -that we consider <em/free/. - -</enumlist> -<p> - -<sect1>The main section -<p> - -Every package in "main" must comply with the DFSG (Debian Free -Software Guidelines). -<p> - -In addition, the packages in "main" -<p> - -<list compact> -<item>must not require a package outside of "main" for compilation or -execution (thus, the package may not declare a "Depends" or -"Recommends" relationship on a non-main package), -<p> -<item>must not be so buggy that we refuse to support them, -<p> -<item>must meet all policy requirements presented in this manual. -</list> -<p> - -<sect1>The contrib section -<p> - -Every package in "contrib" must comply with the DFSG. -<p> - -Examples of packages which would be included in "contrib" are -<p> -<list compact> -<item>free packages which require "contrib", "non-free", or "non-US" - packages or packages which are not in our archive at all for - compilation or execution, -<p> -<item>wrapper packages or other sorts of free accessories for - non-free programs, -<p> -<item>packages which we don't want to support because they are too - buggy, and -<p> -<item>packages which fail to meet some other policy requirements in - a serious way. -</list> -<p> - -<sect1>The non-free section -<p> - -`Non-free' contains packages which are not compliant with the DFSG -or which are encumbered by patents or other legal issues that make -their distribution problematic. -<p> - -All packages in `non-free' must be electronically distributable across -international borders. -<p> - -<sect1>The non-us server -<p> - -Some programs with cryptographic program code must be stored on the -"non-us" server because of export restrictions of the U.S. -<p> - -This applies only to packages which contain cryptographic code. A package -containing a program with an interface to a cryptographic program or a -program that's dynamically linked against a cryptographic library can be -distributed if it is capable of running without the cryptography library -or program. -<p> - -<sect1>Further copyright considerations -<p> - -Every package must be accompanied by a verbatim copy of its copyright -and distribution license in the file -/usr/doc/<package-name>/copyright (see <ref id="copyrightfile"> -for details). -<p> - -We reserve the right to restrict files from being included anywhere in -our archives if -<p> -<list compact> -<item>their use or distribution would break a law, -<p> -<item>there is an ethical conflict in their distribution or use, -<p> -<item>we would have to sign a license for them, or -<p> -<item>their distribution would conflict with other project policies. -</list> -<p> - -Programs whose authors encourage the user to make donations are fine -for the main distribution, provided that the authors do not claim that -not donating is immoral, unethical, illegal or something similar; -otherwise they must go in contrib (or non-free, if even distribution -is restricted by such statements). -<p> - -Packages whose copyright permission notices (or patent problems) do -not allow redistribution even of only binaries, and where no special -permission has been obtained, cannot be placed on the Debian FTP site and -its mirrors at all. -<p> - -Note, that under international copyright law (this applies in -the United States, too) <em/no/ distribution or -modification of a work is allowed without an explicit notice saying -so. Therefore a program without a copyright notice <em/is/ -copyrighted and you may not do anything to it without risking being -sued! Likewise if a program has a copyright notice but no statement -saying what is permitted then nothing is permitted. -<p> - -Many authors are unaware of the problems that restrictive copyrights -(or lack of copyright notices) can cause for the users of their -supposedly-free software. It is often worthwhile contacting such -authors diplomatically to ask them to modify their license -terms. However, this is a politically difficult thing to do and you -should ask for advice on <tt/debian-devel/ first. -<p> - -When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be -prepared to provide us with the copyright statement. Software covered -by the GPL, public domain software and BSD-like copyrights are safe; -be wary of the phrases `commercial use prohibited' and `distribution -restricted'. -<p> - -<sect1>Subsections -<p> - -The packages in the <em/main/, <em/contrib/, and <em/non-free/ -sections are grouped further into <em>subsections</em> to simplify -handling of them. -<p> - -The section for each package is specified in the package's <em>control -record</em>. However, the maintainer of the Debian archive may -override this selection to assure the consistency of the Debian -distribution. -<p> - -Please check the current Debian distribution to see which sections are -available. -<p> - -<sect>Priorities -<p> - -Each package is given a certain <em>priority</em> value, which is -included in the package's <em>control -record</em>. This information is used in the Debian package management -tool to separate high-priority packages from less-important packages. -<p> - -The following <em>priority levels</em> are supported by the Debian -package management system, <prgn/dpkg/. -<p> - -<taglist> -<tag><tt/required/ -<item> -<tt/required/ packages are necessary for the proper functioning of the -system. You must not remove these packages or your system may become -totally broken and you may not even be able to use -<prgn/dpkg/ to put things back. Systems with only the <tt/required/ -packages are probably unusable, but they do have enough functionality -to allow the sysadmin to boot and install more software. - -<tag><tt/important/ -<item> -Important programs, including those which one would expect to find on -any Unix-like system. If the expectation is that an experienced Unix -person who found it missing would say `What the F*!@<+ is going on, -where is <prgn/foo/', it should be in <tt/important/. This is an -important criterion because we are trying to produce, amongst other -things, a free Unix. Other packages without which the system will not -run well or be usable should also be here. This does <em/not/ -include Emacs or X11 or TeX or any other large applications. The -<tt/important/ packages are just a bare minimum of commonly-expected -and necessary tools. - -<tag><tt/standard/ -<item> -These packages provide a reasonably small but not too limited -character-mode system. This is what will install by default if the -user doesn't select anything else. It doesn't include many large -applications, but it does include Emacs (this is more of a piece of -infrastructure than an application) and a reasonable subset of TeX and -LaTeX (if this is possible without X). - -<tag><tt/optional/ -<item> -(In a sense everything is optional that isn't required, but that's not -what is meant here.) This is all the software that you might -reasonably want to install if you didn't know what it was or don't -have specialised requirements. This is a much larger system and includes -X11, a full TeX distribution, and lots of applications. - -<tag><tt/extra/ -<item> -This contains packages that conflict with others with higher -priorities, or are only likely to be useful if you already know what -they are or have specialised requirements. - -</taglist> -<p> - -Packages may not depend on packages with lower priority values. -If this should happen, one of the priority values will have to -be adapted. -<p> - -<sect>Binary packages -<p> - -The Debian GNU/Linux distribution is based on the Debian package -management system, called <prgn/dpkg/. Thus, all packages in the -Debian distribution have to be provided in the <tt/.deb/ file format. -<p> - -<sect1>The package name -<p> - -Every package must have a name that's unique within the Debian -archive. -<p> - -Package names may only consist of lower case letters, digits (0-9), -plus (+) or minus (-) signs, and periods (.). -<p> - -The package name is part of the file name of the <tt/.deb/ file and is -included in the control field information. -<p> - -<sect1>The maintainer of a package -<p> - -Every package must have exactly one maintainer at a time. This person -is responsible that the license of the package's software complies with -the policy of the distribution this package is included in. -<p> - -The maintainer must be specified in the <tt/Maintainer/ control field -with the correct name and a working email address for the Debian -maintainer of the package. If one person maintains several packages -he/she should try to avoid having different forms of their name and -email address in different <tt/Maintainer/ fields. -<p> - -If the maintainer of a package quits from the Debian project the -Debian QA Group takes over the maintainership of the package until -someone else volunteers for that task. These packages are called -<em>orphaned packages</em>. -<p> - -<sect1>The description of a package -<p> - -Every Debian package should have an extended description stored in the -appropriate field of the control record. -<p> - -The description should be written so that it tells the user what they -need to know to decide whether to install the package. This -description should not just be copied from the blurb for the program. -Instructions for configuring or using the package should not be -included--that is what installation scripts, manual pages, Info files, -etc. are for. Copyright statements and other -administrivia should not be included--that is what the copyright file -is for. -<p> - -<sect1>Dependencies -<p> - -Every package has to specify the dependency information about other -packages, that are required for the first to work correctly. -<p> - -For example, for any shared libraries required by dynamically-linked -executable binary in a package a dependency entry has to be provided. -<p> - -It is not necessary for other packages to declare any dependencies -they have on other packages which are marked <tt/Essential/ (see below). -<p> - -Sometimes, a package requires another package to be installed -<em>and</em> configured before it can be installed. In this case, -you'll have to specify a <tt/Pre-Depends/ entry for the package. -<p> - -You must not specify a <tt/Pre-Depends/ entry for a package before -this has been discussed on the <tt/debian-devel/ mailing list and a -consensus about doing that has been reached. -<p> - -<sect1>Virtual packages -<p> - -Sometimes, there are several packages doing more-or-less the same -job. In this case, it's useful to define a <em>virtual package</em> -who's name describes the function the packages have. (The virtual -packages just exist logically, not physically--that's why they are -called <em>virtual</em>.) The packages with this particular function -will then <em>provide</em> the virtual package. Thus, any other -package requiring that function can simply depend on the virtual -package without having to specify all possible packages individually. -<p> - -All packages must use virtual package names where appropriate, and -arrange to create new ones if necessary. They must not use virtual -package names (except privately, amongst a cooperating group of -packages) unless they have been agreed upon and appear in the list of -virtual package names. -<p> - -The latest version of the authoritative list of virtual package names -can be found on <ftpsite>ftp.debian.org</> in -<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</> -or your local mirror. In addition, it is included in the -<tt>debian-policy</tt> package. The procedure for updating the list is -described at the top of the file. -<p> - -<sect1>Base packages -<p> - -The packages included in the <tt/base/ section have a special -function. They form a minimum subset of the Debian GNU/Linux system -that is installed before everything else on a new system. Thus, only -very few packages are allowed to go into the <tt/base/ section to keep -the required disk usage very small. -<p> - -Most of these packages should have the priority value <tt/required/ or -at least <tt/important/, and many of them will be tagged -<tt/essential/ (see below). -<p> - -You must not place any packages into the <tt/base/ section before this -has been discussed on the <tt/debian-devel/ mailing list and a -consensus about doing that has been reached. -<p> - -<sect1>Essential packages -<p> - -Some packages are tagged <tt/essential/. (They have <tt/Essential: -yes/ in their package control record.) This flag is used for packages -that are <em>essential</em> for a system. -<p> - -Since these packages can not easily be removed (you'll have to specify -an extra <em>force option</em> to <prgn/dpkg/) this flag should only -be used where absolutely necessary. - -A shared library package should not be tagged <em>essential</em>--the -dependencies will prevent its premature removal, and we need to be -able to remove it when it has been superseded. -<p> - -You must not tag any packages <tt/essential/ before this has been -discussed on the <tt/debian-devel/ mailing and a consensus about doing -that has been reached. -<p> - -<sect1>Maintainer scripts -<p> - -The package installation scripts should avoid producing output which -it is unnecessary for the user to see and should rely on <prgn/dpkg/ -to stave off boredom on the part of a user installing many packages. -This means, amongst other things, using the <tt/--quiet/ option on -<prgn/install-info/. -<p> - -Packages should try to minimise the amount of prompting they need to -do, and they should ensure that the user will only ever be asked each -question once. This means that packages should try to use appropriate -shared configuration files (such as <tt>/etc/papersize</> and -<tt>/etc/nntpserver</>), rather than each prompting for their own list -of required pieces of information. -<p> - -It also means that an upgrade should not ask the same questions again, -unless the user has used <tt/dpkg --purge/ to remove the package's -configuration. The answers to configuration questions should be -stored in an appropriate place in <tt>/etc</> so that the user can -modify them, and how this has been done should be documented. -<p> - -If a package has a vitally important piece of information to pass to -the user (such as "don't run me as I am, you must edit the following -configuration files first or you risk your system emitting -badly-formatted messages"), it should display this in the -<prgn/postinst/ script and prompt the user to hit return to -acknowledge the message. Copyright messages do not count as vitally -important (they belong in <tt>/usr/doc/copyright</>); neither do -instructions on how to use a program (these should be in on line -documentation, where all the users can see them). -<p> - -Any necessary prompting should almost always be confined to the -post-installation script, and should be protected with a conditional -so that unnecessary prompting doesn't happen if a package's -installation fails and the <prgn/postinst/ is called with -<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/. -<p> - -Errors which occur during the execution of an installation script -<em/must/ be checked and the installation <em/must not/ continue after -an error. -<p> - -Note, that <ref id="scripts">, in general applies to package -maintainer scripts, too. -<p> - -Do not use <prgn/dpkg-divert/ on a file belonging to another package -without consulting the maintainer of that package first. -<p> - -In order for <prgn/update-alternatives/ to work correctly all the -packages which supply an instance of the `shared' command name (or, in -general, filename) must use it. You can use <tt/Conflicts/ to force -the deinstallation of other packages supplying it which do not (yet) -use <prgn/update-alternatives/. It may in this case be appropriate to -specify a conflict on earlier versions on something--this is an -exception to the usual rule that this is not allowed. -<p> - -<sect>Source packages -<p> - -<sect1>Standards conformance -<p> - -You should specify the most recent version of the packaging standards -with which your package complies in the source package's -<tt/Standards-Version/ field. -<p> - -This value will be used to file bug reports automatically if your -package becomes too much out of date. -<p> - -The value corresponds to a version of the Debian manuals, as can be -found on the title page or page headers and footers (depending on the -format). -<p> - -The version number has four components--major and minor number and -major and minor patch level. When the standards change in a way that -requires every package to change the major number will be changed. -Significant changes that will require work in many packages will be -signaled by a change to the minor number. The major patch level will -be changed for any change to the meaning of the standards, however -small; the minor patch level will be changed when only cosmetic, -typographical or other edits which do not change the meaning are made, -or changes which do not affect the contents of packages. -<p> - -You should regularly, and especially if your package has become out of -date, check for the newest Policy Manual available and update your -package, if necessary. When your package complies with the new -standards you may update the <tt/Standards-Version/ source package -field and release it. -<p> - -<sect1>Changes to the upstream sources -<p> - -If changes to the source code are made that are generally applicable -please try to get them included in the upstream version of the package -by supplying the upstream authors with the changes in whatever form -they prefer. -<p> - -If you need to configure the package differently for Debian or for -Linux, and the upstream source doesn't provide a way to configure it -the way you need to, please add such configuration facilities (for -example, a new <prgn/autoconf/ test or <tt/#define/) and send the -patch to the upstream authors, with the default set to the way they -originally had it. You can then easily override the default in your -<tt>debian/rules</tt> or wherever is appropriate. -<p> - -Please make sure that the <prgn/configure/ utility detects the correct -architecture specification string (refer to <ref id="arch-spec"> for -details). -<p> - -If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/ -scripts are used, you should edit the <tt/.in/ files rather than -editing the <prgn/Makefile/ directly. This allows the user to -reconfigure the package if necessary. You should <em/not/ configure -the package and edit the generated <prgn/Makefile/! This makes it -impossible for someone else to later reconfigure the package. -<p> - -<sect1>Documenting your changes -<p> - -Document your changes and updates to the source package properly in -the <tt>debian/changelog</tt> file. -<p> - -A copy of the file which will be installed in -<tt>/usr/doc/<var/package//copyright</tt> should be in -<tt>debian/copyright</tt>. -<p> - -In non-experimental packages you may only use a format for -<tt>debian/changelog</> which is supported by the most recent released -version of <prgn/dpkg/. If your format is not supported and there is -general support for it you should contact the <prgn/dpkg/ maintainer -to have the parser script for your format included in the <prgn/dpkg/ -package. (You will need to agree that the parser and its -manpage may be distributed under the GNU GPL, just as the rest of -<prgn/dpkg/ is.) -<p> - -<sect1>Error trapping in makefiles -<p> - -When <prgn/make/ invokes a command in a makefile (including your -package's upstream makefiles and the <tt>debian/rules</>) it does so -using <tt/sh/. This means that <tt/sh/'s usual bad error handling -properties apply: if you include a miniature script as one of the -commands in your makefile you'll find that if you don't do anything -about it then errors are not detected and <prgn/make/ will blithely -continue after problems. -<p> - -Every time you put more than one shell command (this includes using a -loop) in a makefile command you <em/must/ make sure that errors are -trapped. For simple compound commands, such as changing directory and -then running a program, using <tt/&&/ rather than semicolon as -a command separator is sufficient. For more complex commands -including most loops and conditionals you must include a separate -<tt/set -e/ command at the start of every makefile command that's -actually one of these miniature shell scripts. -<p> - -<sect1>Obsolete constructs and libraries -<p> - -The include file <prgn/<varargs.h>/ is provided to support -end-users compiling very old software; the library <tt/libtermcap/ is -provided to support the execution of software which has been linked -against it (either old programs or those such as Netscape which are -only available in binary form). -<p> - -Debian packages should be ported to include <prgn/<stdarg.h>/ and -<tt/ncurses/ when they are built. -<p> - -<chapt>The Operating System -<p> - -<sect>Filesystem hierarchy -<p> - -<sect1>Linux Filesystem Structure -<p> - -The location of all installed files and directories must comply fully -with the Linux Filesystem Structure (FSSTND). The latest version of -this document can be found alongside this manual or on -<ftpsite/tsx-11.mit.edu/ in -<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific -questions about following the standard may be asked on -<prgn/debian-devel/, or referred to Daniel Quinlan, the FSSTND -coordinator, at <email/quinlan@pathname.com/. -<p> - -<sect1>Site-specific programs -<p> - -As mandated by the FSSTND no package should place any files in -<tt>/usr/local</>, either by putting them in the filesystem archive to -be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer -scripts. -<p> - -However, the package should create empty directories below -<tt>/usr/local</> so that the system administrator knows where to -place site-specific files. These directories should be removed on -package removal if they are empty. -<p> - -Note, that this applies only to directories <em/below/ -<tt>/usr/local</>, not <em/in/ <tt>/usr/local</>. The directory -<tt>/usr/local</> itself may only contain the sub-directories listed -in FSSTND, section 4.8. However, you may create directories below them -as you wish. You may not remove any of the directories listed in 4.8, -even if you created them. -<p> - -Since <tt>/usr/local</> may be mounted read-only from a remote server, -these directories have to be created and removed by the <tt/postinst/ -and <tt/prerm/ maintainer scripts. These scripts must not fail if -either of these operations fail. (In the future, it will be possible to -tell <prgn/dpkg/ not to unpack files matching certain patterns, so -that the directories can be included in the <tt/.deb/ packages and -system administrators who do not wish these directories in /usr/local -do not need to have them.) -<p> - -For example, the <prgn/emacs/ package will contain -<example> - mkdir -p /usr/local/lib/emacs/site-lisp || true -</example> -in the <tt/postinst/ script, and -<example> - rmdir /usr/local/lib/emacs/site-lisp && \ - rmdir /usr/local/lib/emacs || \ - true -</example> -in the <tt/prerm/ script. -<p> - -If you do create a directory in <tt>/usr/local</> for local additions -to a package, you must ensure that settings in <tt>/usr/local</tt> -take precedence over the equivalents in <tt>/usr</tt>. -<p> - -The <tt>/usr/local</> directory itself and all the subdirectories -created by the package should have permissions 2775 (group-writable -and set-group-id) and be owned by <tt/root.staff/. -<p> - -<sect>Users and groups -<p> - -The Debian system can be configured to use either plain or shadow -passwords. -<p> - -Some user ids (UIDs) and group ids (GIDs) are reserved globally for -use by certain packages. Because some packages need to include files -which are owned by these users or groups, or need the ids compiled -into binaries, these ids must be used on any Debian system only for -the purpose for which they are allocated. This is a serious -restriction, and we should avoid getting in the way of local -administration policies. In particular, many sites allocate users -and/or local system groups starting at 100. -<p> - -Apart from this we should have dynamically allocated ids, which should -by default be arranged in some sensible order--but the behaviour -should be configurable. -<p> - -No package except <tt>base-passwd</> may modify <tt>/etc/passwd</>, -<tt>/etc/shadow</>, or <tt>/etc/group</>. -<p> - -The UID and GID ranges are as follows: -<taglist> -<tag>0-99: -<item> -Globally allocated by the Debian project, must be the same on -every Debian system. These ids will appear in the <tt>passwd</> and -<tt>group</> -files of all Debian systems, new ids in this range being added -automatically as the <tt>base-passwd</> package is updated. -<p> - -Packages which need a single statically allocated uid or gid should -use one of these; their maintainers should ask the <tt>base-passwd</> -maintainer for ids. -<p> - -<tag>100-999: -<item> -Dynamically allocated system users and groups. Packages -which need a user or group, but can have this user or group allocated -dynamically and differently on each system, should use `<tt>adduser ---system</>' to create the group and/or user. <prgn>adduser</> will -check for the -existence of the user or group, and if necessary choose an unused id -based on the ranged specified in <tt>adduser.conf</>. -<p> - -<tag>1000-29999: -<item> -Dynamically allocated user accounts. By default <prgn>adduser</> -will choose UIDs and GIDs for user accounts in this range, though -<tt>adduser.conf</> may be used to modify this behaviour. -<p> - -<tag>30000-59999: -<item> -Reserved. -<p> - -<tag>60000-64999: -<item> -Globally allocated by the Debian project, but only created on -demand. The ids are allocated centrally and statically, but the actual -accounts are only created on users' systems on demand. -<p> - -These ids are for packages which are obscure or which require many -statically-allocated ids. These packages should check for and create -the accounts in <tt>/etc/passwd</> or <tt>/etc/group</> (using -<prgn>adduser</> if it has this facility) if necessary. Packages -which are likely to require further allocations should have a `hole' -left after them in the allocation, to give them room to grow. -<p> - -<tag>65000-65533: -<item> -Reserved. -<p> - -<tag>65534: -<item> -User `<tt>nobody</>.' -<p> - -<tag>65535: -<item> -<tt>(uid_t)(-1) == (gid_t)(-1)</>. NOT TO BE USED, because it is the -error return sentinel value. -<p> -</taglist> - -<sect>Files -<p> - -<sect1>Binaries -<p> - -It is not allowed that two packages 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.') If this case happens, one of the programs has to be -renamed. The maintainers should report this to the developers' mailing -and try to find a consensus about which package will have to be renamed. -If a consensus can not be reached, <em>both</> programs must be renamed. -<p> - -Generally the following compilation parameters should be used: -<example> - CC = gcc - CFLAGS = -O2 -g -Wall # sane warning options vary between programs - LDFLAGS = # none - install -s # (or use strip on the files in debian/tmp) -</example> -<p> - -Note that all installed binaries should be -stripped, either by using the <tt/-s/ flag to <prgn/install/, or by calling -<prgn/strip/ on the binaries after they have been copied into -<tt>debian/tmp</> but before the tree is made into a package. -<p> - -The <tt/-g/ flag is useful on compilation so that you have available a -full set of debugging symbols in your built source tree, in case -anyone should file a bug report involving (for example) a core dump. -<p> - -The <tt/-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. -<p> - -It is up to the package maintainer to decide what compilation options -are best for the package. Certain binaries (such as -computationally-intensive programs) may function better with certain -flags (<tt/-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. -<p> - -<sect1>Libraries -<p> - -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 -<tt/-fPIC/, and the static version must not be. In other words, each -<tt/*.c/ file is compiled twice. -<p> - -You have to specify the gcc option <tt>-D_REENTRANT</tt> when building -a library (either static or shared) to make the library compatible with -LinuxThreads. -<p> - -Note that all installed shared libraries should be stripped with -<example> - strip --strip-unneeded <your-lib> -</example> -(The option `--strip-unneeded' makes <tt>strip</tt> 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. -<p> - -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. -<p> - -Please 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. -<p> - -<sect1>Shared libraries -<p> - -Packages involving shared libraries should be split up into several -binary packages. -<p> - -For a straightforward library which has a development environment and -a runtime kit including just shared libraries you need to create two -packages: <tt/<var/libraryname/<var/soname// (<var/soname/ is -the shared object name of the shared library--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; usually the <var/soname/ -is the major number of the library) and -<tt/<var/libraryname/<var/soname/-dev/. -<p> - -If you prefer only to support one development version at a time you -may name the development package <tt/<var/libraryname/-dev/; otherwise -you may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that -the user only installs one development version at a time (after all, -different development versions are likely to have the same header -files in them, causing a filename clash if both are installed). -Typically the development version will also need an exact version -dependency on the runtime library, to make sure that compilation and -linking happens correctly. -<p> - -Packages which use the shared library should have a dependency on the -name of the shared library package, -<tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you -can have both versions of the library installed while moving from the -old library to the new. -<p> - -If your package has some run-time support programs which use the -shared library you must <em/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 <tt/<var/libraryname/-runtime/--note -the absence of the <var/soname/ in the package name) or if the -development package is small include them in there. -<p> - -If you have several shared libraries built from the same source tree -you can lump them all together into a single shared library package, -provided that you change all their <var/soname/s at once (so that you -don't get filename clashes if you try to install different versions of -the combined shared libraries package). -<p> - -Follow the directions in the <em>Debian Packaging Manual</em> for -putting the shared library in its package, and make sure you include a -<tt/shlibs/ control area file with details of the dependencies for -packages which use the library. -<p> - -Shared libraries should <em/not/ be installed executable, since -<prgn/ld.so/ does not require this and trying to execute a shared -library results in a core dump. -<p> - -<sect1 id=scripts>Scripts -<p> - -All command scripts, including the package maintainer scripts inside -the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming -the shell to be used to interpret them. -<p> - -In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>. -<p> - -Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly -start with <tt>set -e</> so that errors are detected. Every script -<em/must/ use <tt/set -e/ or check the exit status of <em/every/ -command. -<p> - -The standard shell interpreter `<tt>/bin/sh</tt>' may be a symbolic -link to any POSIX compatible shell. Thus, shell scripts specifying -`<tt>/bin/sh</tt>' as interpreter may only use POSIX features. If a -script requires non-POSIX features from the shell interpreter, the -appropriate shell has to be specified in the first line of the script -(e.g., `<tt>#!/bin/bash</tt>') and the package has to depend on the -package providing the shell (unless the shell package is marked -`Essential', e.g., in the case of <prgn/bash/). -<p> - -Restrict your script to POSIX features when possible so that it may -use <tt>/bin/sh</tt> as its interpreter. If your script works with -<prgn/ash/, it's probably POSIX compliant, but if you are in doubt, -use <tt>/bin/bash</tt>. -<p> - -Perl scripts should check for errors when making any system calls, -including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and -<tt/system/. -<p> - -<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages. -See <em>Csh Programming Considered Harmful</>, one of the -<tt/comp.unix.*/ FAQs. It can be found on <ftpsite>rtfm.mit.edu</> in -<ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</>. -If an upstream package comes with <prgn/csh/ scripts then you must -make sure that they start with <tt>#!/bin/csh</tt> and make your -package depend on the <prgn/c-shell/ virtual package. -<p> - -Any scripts which create files in world-writable directories (e.g., in -<tt>/tmp</tt>) have to use a mechanism which will fail if a file with -the same name already exists. -<p> - -The Debian base distribution provides the <prgn/tempfile/ and -<prgn/mktemp/ utilities for use by scripts for this purpose. -<p> - -<sect1>Symbolic links -<p> - -In general, symbolic links within a toplevel directory should be -relative, and symbolic links pointing from one toplevel directory into -another should be absolute. (A toplevel directory is a sub-directory -of the root directory `/'.) -<p> - -In addition, symbolic links should be specified as short as possible, -i.e., link targets like `foo/../bar' are deprecated. -<p> - -Note that when creating a relative link using <prgn/ln/ it is not -necessary for the target of the link to exist relative to the working -directory you're running <prgn/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 <prgn/ln/. -<p> - -For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things -like: -<example> - 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 -</example> -<p> - -A symbolic link pointing to a compressed file should always have the -same file extension as the referenced file. (For example, if a file -`<tt>foo.gz</tt>' is referenced by a symbolic link, the filename of -the link has to end with `<tt>.gz</tt>' too, as in `bar.gz.') -<p> - -<sect1>Device files -<p> - -No package may include device files in the package file tree. -<p> - -If a package needs any special device files that are not included in -the base system, it has to call <prgn/makedev/ in the <tt/postinst/ -script, after asking the user for permission to do so. -<p> - -No package should remove any device files in the <tt/postrm/ or any -other script. This is left to the system administrator. -<p> - -Debian uses the serial devices <tt>/dev/tty*</tt>. Programs using the -old <tt>/dev/cu*</tt> devices should be changed to use -<tt>/dev/tty*</tt>. -<p> - -<sect1>Configuration files -<p> - -Any configuration files created or used by your package should reside -in <tt>/etc</tt>. If there are several you should consider creating a -subdirectory named after your package. -<p> - -It is almost certain that any file in <tt>/etc</tt> that is in your -package's filesystem archive should be listed in <prgn/dpkg/'s -<tt/conffiles/ control area file. (See the <em>Debian Packaging -Manual</em>). -<p> - -Only packages that are tagged <em/conflicting/ with each other may -specify the same file as <tt/conffile/. A package may not modify a -configuration file of another package. -<p> - -If two or more packages use the same configuration file, one of these -packages has to be defined as <em/owner/ of the configuration file, -i.e., it has to list the file as <tt/conffile/ and has to provide -a program that modifies the configuration file. -<p> - -The other packages have to depend on the <em/owner/ package and use -that program to update the configuration file. -<p> - -Sometimes it's appropriate to build a new package, which just provides -the basic <em/infrastructure/ for the other packages and which manages -the shared configuration files. (Check out the <prgn/sgml-base/ -package as an example.) -<p> - -Files in <tt>/etc/skel</> will automatically be copied into new user -accounts by <prgn/adduser/. They should not be referenced there by -any program. -<p> - -Therefore, if a program needs a dotfile to exist in advance in -<tt/$HOME/ to work sensibly that dotfile should be installed in -<tt>/etc/skel</> (and listed in conffiles, if it is not generated and -modified dynamically by the package's installation scripts). -<p> - -However, programs that require dotfiles in order to operate sensibly -(dotfiles that they do not create themselves automatically, that is) -are a bad thing, and programs should be configured by the Debian -default installation as close to normal as possible. -<p> - -Therefore, if a program in a Debian package needs to be configured in -some way in order to operate sensibly that configuration should be -done in a site-wide global configuration file elsewhere in -<tt>/etc</>. Only if the program doesn't support a site-wide default -configuration and the package maintainer doesn't have time to add it -should a default per-user file be placed in <tt>/etc/skel</>. -<p> - -<tt>/etc/skel</> should be as empty as we can make it. This is -particularly true because there is no easy mechanism for ensuring that -the appropriate dotfiles are copied into the accounts of existing -users when a package is installed. -<p> - -Ideally the sysadmin should not have to do any configuration other -than that done (semi-)automatically by the <tt/postinst/ script. -<p> - -<sect1>Permissions and owners -<p> - -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 must try to -be as consistent as possible with the rest of the system. You should -probably also discuss it on <prgn/debian-devel/ first. -<p> - -Files should be owned by <tt/root.root/, and made writable only by -the owner and universally readable (and executable, if appropriate). -<p> - -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. -<p> - -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. -<p> - -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; there is no -point in making them unreadable to those users who must not be allowed -to execute them. -<p> - -Do not arrange that the system administrator can only reconfigure the -package to correspond to their local security policy by changing the -permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as -opposed to conffiles and other similar objects) have their permissions -reset to the distributed permissions when the package is reinstalled. -Instead you should consider (for example) creating a group for people -allowed to use the program(s) and making any setuid executables -executable only by that group. -<p> - -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). In this -case you need a statically allocated id. -<p> - -You must ask for a user or group id from the base system maintainer, -and must not release the package until you have been allocated one. -Once you have been allocated one you must make the package depend on a -version of the base system with the id present in <tt>/etc/passwd</tt> -or <tt>/etc/group</tt>, or alternatively arrange for your package to -create the user or group itself with the correct id (using -<tt/adduser/) in its pre- or post-installation script (the latter is -to be preferred if it is possible). -<p> - -On the other hand, the program may able to determine the uid or gid -from the group name at runtime, so that a dynamic id can be used. In -this case you must choose an appropriate user or group name, -discussing this on <prgn/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 <prgn/adduser/ in the pre- or post-installation script (again, -the latter is to be preferred if it is possible). -<p> - -Note that changing the numeric value of an id associated with a name -is very difficult, and involves searching the filesystem 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. -<p> - -<sect id="sysvinit">System run levels -<p> - -<sect1>Introduction -<p> - -The <tt>/etc/init.d</> directory contains the scripts executed by -<prgn/init/ at boot time and when init state (or `runlevel') is -changed (see <manref name=init section=8>). <p> - -These scripts are being referenced by symbolic links in the -<tt>/etc/rc<var/n/.d</> directories. When changing runlevels, -<prgn/init/ looks in the directory <tt>/etc/rc<var/n/.d</> for the -scripts it should execute, where <var/n/ is the runlevel that is being -changed to, or `S' for the boot-up scripts. <p> - -The names of the links all have the form <tt/S<var/mm/<var/script// or -<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and -<var/script/ is the name of the script (this should be the same as the -name of the actual script in <tt>/etc/init.d</>. - -When <prgn/init/ changes runlevel first the targets of the links whose -names starting with a <tt/K/ are executed, each with the single -argument <tt/stop/, followed by the scripts prefixed with an <tt/S/, -each with the single argument <tt/start/. The <tt/K/ links are -responsible for killing services and the <tt/S/ link for starting -services upon entering the runlevel. -<p> - -For example, if we are changing from runlevel 2 to runlevel 3, init -will first execute all of the <tt/K/ prefixed scripts it finds in -<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The -links starting with <tt/K/ will cause the referred-to file to be -executed with an argument of <tt/stop/, and the <tt/S/ links with an -argument of <tt/start/. -<p> - -The two-digit number <var/mm/ is used to decide which order to start -and stop things in--low-numbered links have their scripts run first. -For example, the <tt/K20/ scripts will be executed before the <tt/K30/ -scripts. This is used when a certain service must be started before -another. For example, the name server <prgn/bind/ might need to be -started before the news server <prgn/inn/ so that <prgn/inn/ can set -up its access lists. In this case, the script that starts <prgn/bind/ -should have a lower number than the script that starts <prgn/inn/ so -that it runs first: -<example> - /etc/rc2.d/S17bind - /etc/rc2.d/S70inn -</example> - -<sect1>Writing the scripts -<p> - -Packages can and should place scripts in <tt>/etc/init.d</> to start -or stop services at boot time or during a change of runlevel. These -scripts should be named <tt>/etc/init.d/<var/package/</>, and they -should accept one argument, saying what to do: - -<taglist> -<tag><tt/start/ -<item>start the service, -<p> -<tag><tt/stop/ -<item>stop the service, -<p> -<tag><tt/restart/ -<item>stop and restart the service, -<p> -<tag><tt/reload/ -<item>cause the configuration of the service to be -reloaded without actually stopping and restarting the service, -<p> -<tag><tt/force-reload/ -<item>cause the configuration to be reloaded if the service supports -this, otherwise restart the service. -</taglist> - -The <tt/start/, <tt/stop/, <tt/restart/, and <tt/force-reload/ options -must be supported by all scripts in <tt>/etc/init.d</>, the -<tt/reload/ option is optional. -<p> - -The <tt/init.d/ scripts should ensure that they will behave sensibly -if invoked with <tt/start/ when the service is already running, or -with <tt/stop/ when it isn't, and that they don't kill -unfortunately-named user processes. The best way to achieve this is -usually to use <prgn/start-stop-daemon/. -<p> - -If a service reloads its configuration automatically (as in the case -of <prgn/cron/, for example), the <tt/reload/ option of the -<tt/init.d/ script should behave as if the configuration has been -reloaded successfully. -<p> - -These scripts should not fail obscurely when the configuration files -remain but the package has been removed, as the default in <prgn/dpkg/ -is to leave configuration files on the system after the package has -been removed. Only when it is executed with the <tt/--purge/ option -will dpkg remove configuration files. Therefore, you should include a -<tt/test/ statement at the top of the script, like this: -<example> - test -f <var/program-executed-later-in-script/ || exit 0 -</example> - -<sect1>Managing the links -<p> - -A program is provided, <prgn/update-rc.d/, to make it easier for -package maintainers to arrange for the proper creation and removal of -<tt>/etc/rc<var/n/.d</> symbolic links from their <tt/postinst/ and -<tt/postrm/ scripts. -<p> - -You should use this script to make changes to <tt>/etc/rc<var/n/.d</> -and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in -the actual archive. -<p> - -By default <prgn/update-rc.d/ will start services in each of the -multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt -runlevel (0), the single-user runlevel (1) and the reboot runlevel -(6). The system administrator will have the opportunity to customize -runlevels by simply adding, moving, or removing the symbolic links in -<tt>/etc/rc<var/n/.d</>. -<p> - -To get the default behaviour for your package, put in your -<tt/postinst/ script -<example> - update-rc.d <var/package/ default >/dev/null -</example> -and in your <tt/postrm/ -<example> - if [ purge = "$1" ]; then - update-rc.d <var/package/ remove >/dev/null - fi -</example> -<p> - -This will use a default sequence number of 20. If it does not matter -when or in which order the script is run, use this default. If it -does, then you should talk to the maintainer of the <prgn/sysvinit/ -package or post to <tt>debian-devel</>, and they will help you choose -a number. -<p> - -For more information about using <tt/update-rc.d/, please consult its -manpage <manref name=update-rc.d section=8>. -<p> - -<sect1>Boot-time initialisation -<p> - -There is another directory, <tt>/etc/rc.boot</>, which contains -scripts which are run once per machine boot. This facility is -provided for initialisation of hardware devices, cleaning up of -leftover files, and so forth. -<p> - -For example, the <prgn/kbd/ package provides a script here for -initialising the keyboard layout and console font and mode. -<p> - -The files in <tt>/etc/rc.boot</> should <em/not/ be links into -<tt>/etc/init.d</>--they should be the scripts themselves. -<p> - -<tt/rc.boot/ should <em/not/ be used for starting general-purpose -daemons and similar activities. This should be done using the -<tt/rc<var/n/.d/ scheme, above, so that the services can be started -and stopped cleanly when the runlevel changes or the machine is to be -shut down or rebooted. -<p> - -<sect1>Notes -<p> - -<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in -the <tt/.deb/ filesystem archive! <em/This will cause problems!/ -You should create them with <prgn/update-rc.d/, as above. -<p> - -<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in -<prgn/dpkg/'s conffiles list! <em/This will cause problems!/ <em/Do/, -however, include the <tt>/etc/init.d</> scripts in conffiles. (This -is important since we want to give the local system administrator the -chance to adapt the scripts to the local system--e.g., to disable a -service without deinstalling the package, or to specify some special -command line options when starting a service--while making sure her -changes aren't lost during the next package upgrade.) <p> - -<sect1>Example -<p> - -The <prgn/bind/ DNS (nameserver) package wants to make sure that the -nameserver is running in multiuser runlevels, and is properly shut -down with the system. It puts a script in <tt>/etc/init.d</>, naming -the script appropriately <tt/bind/. As you can see, the script -interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/ -signal (causing it to reload its configuration); this way the user can -say <tt>/etc/init.d/bind reload</> to reload the name server. -<p> - -<example> - #!/bin/sh - # - # Original version by Robert Leslie <rob@mars.org>, edited by iwj and cs - - test -x /usr/sbin/named || exit 0 - - case "$1" in - start) - echo -n "Starting domain name service: named" - start-stop-daemon --start --quiet --exec /usr/sbin/named - echo "." - ;; - stop) - echo -n "Stopping domain name service: named" - start-stop-daemon --stop --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; - restart) - echo -n "Restarting domain name service: named" - start-stop-daemon --stop --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - start-stop-daemon --start --verbose --exec /usr/sbin/named - echo "." - ;; - force-reload|reload) - echo -n "Reloading configuration of domain name service: named" - start-stop-daemon --stop --signal 1 --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; - *) - echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2 - exit 1 - ;; - esac - - exit 0 -</example> -<p> - -Another example on which to base your <tt>/etc/init.d</> scripts is in -<tt>/etc/init.d/skeleton</>. -<p> - -If this package is happy with the default setup from -<prgn/update-rc.d/, namely an ordering number of 20 and having named -running in all runlevels, it can say in its <tt/postinst/: -<example> - update-rc.d bind default >/dev/null -</example> -And in its <tt/postrm/, to remove the links when the package is purged: -<example> - if [ purge = "$1" ]; then - update-rc.d acct remove >/dev/null - fi -</example> -<p> - -<sect>Cron jobs -<p> - -Packages may not touch the configuration file <tt>/etc/crontab</>, nor -may they modify the files in <tt>/var/spool/cron/crontabs</>. -<p> - -If a package wants to install a job that has to be executed via -cron, it should place a file with the name if the package in one -of the following directories: -<example> - /etc/cron.daily - /etc/cron.weekly - /etc/cron.monthly -</example> -As these directory names say, the files within them are executed on -a daily, weekly, or monthly basis, respectively. -<p> - -If a certain job has to be executed more frequently than `daily,' the -package should install a file -<tt>/etc/cron.d/<package-name></tt> tagged as configuration -file. This file uses the same syntax as <tt>/etc/crontab</tt> and is -processed by <prgn/cron/ automatically. (Note, that scripts in the -<tt>/etc/cron.d</tt> directory are not handled by -<prgn/anacron/. Thus, you should only use this directory for jobs -which may be skipped if the system is not running.) -<p> - -All files installed in any of these directories have to be scripts -(shell scripts, Perl scripts, etc.) so that they can easily be -modified by the local system administrator. In addition, they have to -be registered as configuration file. -<p> - -The scripts in these directories have to 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 -the configuration files are kept on the system in this situation. -<p> - -<sect>Console messages -<p> - -This section describes different formats for messages written to -standard output by the <tt>/etc/init.d</> scripts. The intent is to -improve the consistency of Debian's startup and shutdown look and -feel. -<p> - -Please look very careful at the details. We want to get the messages -to look exactly the same way concerning spaces, punctuation, and case -of letters. -<p> - -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 isn't -covered in the sections below. -<p> - -<list> -<item> - Every message should cover one line, start with a capital letter and - end with a period `.'. -<p> - -<item> - If you want to express that the computer is working on something - (performing a specific task, not starting or stopping a program), we - use an ``ellipsis'', namely three dots `...'. Note that we don't insert - spaces in front of or behind the dots. - If the task has been completed we write `done.' and a line feed. -<p> - -<item> - Design your messages as if the computer is telling you what he is - doing (let him be polite :-) but don't mention ``him'' directly. - For example, if you think of saying -<example> - I'm starting network daemons: nfsd mountd. -</example> - just say -<example> - Starting network daemons: nfsd mountd. -</example> -</list> -<p> - -The following formats must be used -<p> - -<list> -<item> - when daemons get started. -<p> - - Use this format if your script starts one or more daemons. - The output should look like this (a single line, no leading spaces): -<example> - Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>. -</example> - 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). -<p> - - For example, the output of /etc/init.d/lpd would look like: -<example> - Starting printer spooler: lpd. -</example> -<p> - - This can be achieved by saying -<example> - echo -n "Starting printer spooler: lpd" - start-stop-daemon --start --quiet lpd - echo "." -</example> - in the script. If you have more than one daemon to start, you should - do the following: -<example> - echo -n "Starting remote filesystem 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 "." -</example> - This makes it possible for the user to see what takes so long and when - the final daemon has been started. Please 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. -<p> - -<item> - when something needs to be configured. -<p> - - If you have to set up different parameters of the system upon boot up, - you can use this format: -<example> - Setting <parameter> to `<value>'. -</example> -<p> - - You can use the following echo statement to get the quotes right: -<example> - echo "Setting DNS domainname to \`"value"'." -</example> -<p> - - Note that the left quotation mark (`) is different from the right ('). - -<item> - when a daemon is stopped. -<p> - - When you stop a daemon you should issue a message similar to the startup - message, except that `Starting' is replaced with `Stopping'. -<p> - - So stopping the printer daemon will like like this: -<example> - Stopping printer spooler: lpd. -</example> - -<item> - when something is executed. -<p> - - There a several examples where you have to run a program at system - startup or shutdown to perform a specific task. For example, setting - the system's clock via `netdate' or killing all processes when the - system comes down. Your message should like this: -<example> - Doing something very useful...done. -</example> - You should print the `done.' right after the job has been completed, - so that the user gets informed why he has to wait. You can get this - behaviour by saying -<example> - echo -n "Doing something very useful..." - do_something - echo "done." -</example> - in your script. - -<item> - when the configuration is reloaded. -<p> - - When a daemon is forced to reload its configuration files you -should use the following format: -<example> - Reloading <daemon's-name> configuration...done. -</example> - -<item> - when none of the above rules apply. -<p> - - If you have to print a message that doesn't fit into the styles described - above, you can use something appropriate, but please have a look at the - overall rules listed above. -</list> -<p> - -<sect>Menus -<p> - -The Debian <tt/menu/ packages provides a unique interface between -packages providing applications and documents, and <em/menu programs/ -(either X window managers or text-based menu programs as -<prgn/pdmenu/). -<p> - -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 <tt/menu/ -package will automatically get menu entries in their window managers, -as well in shells like <tt/pdmenu/. -<p> - -Please refer to the <em>Debian Menu System</em> document that comes -with the <tt/menu/ package for information about how to register your -applications and web documents. -<p> - -<sect>Keyboard configuration -<p> - -To achieve a consistent keyboard configuration (i.e., all applications -interpret a keyboard event the same way) all programs in the Debian -distribution have to be configured to comply with the following -guidelines. -<p> - -Here is a list that contains certain keys and their interpretation: - -<taglist> -<tag><tt/<--/ -<item>delete the character to the left of the cursor -<p> -<tag><tt/Delete/ -<item>delete the character to the right of the cursor -<p> -<tag><tt/Control+H/ -<item>emacs: the help prefix -</taglist> - -The interpretation of any keyboard events should be independent of the -terminal that's used (either the console, X windows, rlogin/telnet -session, etc.). -<p> - -The following list explains how the different programs should be set -up to achieve this: -<p> - -<list compact> -<item>`<tt><--</tt>' generates KB_Backspace in X. -<p> -<item>`<tt/Delete/' generates KB_Delete in X. -<p> -<item>X translations are set up to make KB_Backspace generate ASCII DEL, - and to make KB_Delete generate <tt>ESC [ 3 ~</tt> (this is the vt220 escape - code for the `delete character' key). This must be done by loading - the resources using xrdb on all local X displays, not using the - application defaults, so that the translation resources used - correspond to the xmodmap settings. -<p> -<item>The Linux console is configured to make `<tt><--</tt>' generate DEL, and - `Delete' generate <tt>ESC [ 3 ~</tt> (this is the case at the moment). -<p> -<item>X applications are configured so that Backspace deletes left, and - Delete deletes right. Motif applications already work like this. -<p> -<item>stty erase <tt>^?</tt> . -<p> -<item>The `xterm' terminfo entry should have <tt>ESC [ 3 ~</tt> for kdch1, just - like TERM=linux and TERM=vt220. -<p> -<item>Emacs is programmed to map KB_Backspace or the `stty erase' - character to delete-backward-char, and KB_Delete or kdch1 to - delete-forward-char, and <tt>^H</tt> to help as always. -<p> -<item>Other applications use the `stty erase' character and kdch1 for the - two delete keys, with ASCII DEL being `delete previous character' - and kdch1 being `delete character under cursor'. -</list> -<p> - -This will solve the problem except for: -<p> - -<list compact> -<item>Some terminals have a <tt><--</tt> key that cannot be made to produce - anything except <tt>^H</tt>. On these terminals Emacs help will be - unavailable on <tt>^H</tt> (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. -<p> -<item>Some operating systems use <tt>^H</tt> for stty erase. However, modern - telnet versions and all rlogin versions propagate stty settings, - and almost all UNIX versions honour stty erase. Where the stty - settings are not propagated correctly things can be made to work by - using stty manually. -<p> -<item>Some systems (including previous Debian versions) use xmodmap to - arrange for both <tt><--</tt> and Delete to generate KB_Delete). We can - change the behaviour of their X clients via the same X resources - that we use to do it for our own, or have our clients be configured - via their resources when things are the other way around. On - displays configured like this Delete will not work, but <tt><--</tt> will. -<p> -<item>Some operating systems have different kdch1 settings in their - terminfo for xterm and others. On these systems the Delete key - will not work correctly when you log in from a system conforming to - our policy, but <tt><--</tt> will. -</list> -<p> - -<sect>Environment variables -<p> - -No program may 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.) -<p> - -If a program should depend on environment variables for its -configuration, the program has to 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 should be -replaced by a small `wrapper' shell script which sets the environment -variables and calls the original program. -<p> - -Here is an example of a wrapper script for this purpose: - -<example> + <!-- + Debian GNU/Linux Policy Manual. + Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz; + released under the terms of the GNU + General Public License, version 2 or (at your option) any later. + Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu + Revised November 27, 1996, David A. Morris, bweaver@debian.org + New sections March 15, 1997, Christian Schwarz, schwarz@debian.org + Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org + Maintainer since 1997, Christian Schwarz, schwarz@debian.org + Christoph Lameter contributed the "Web Standard" + The debian-policy mailing list has taken responsibility for the + contents of this document since September 1998, with the package + maintainers responsible for packaging administrivia only. + --> + + <book> + <titlepag> + <title>Debian Policy Manual + + 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 + + version &version;, &date; + + + This manual describes the policy requirements for the Debian + GNU/Linux distribution. This includes the structure and + contents of the Debian archive and several design issues of the + operating system, as well as technical requirements that each + package must satisfy to be included in the distribution. The + policy package itself is maintained by a group of maintainers + that have no editorial powers. At the moment, the list of + maintainers is: + + +

Julian Gilbey jdg@debian.org

+ + +

Manoj Srivastava srivasta@debian.org

+ + + + + + + + Copyright ©1996,1997,1998 Ian Jackson + and Christian Schwarz. + +

+ This manual is free software; you may redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version + 2, or (at your option) any later version. +

+ +

+ This is distributed in the hope that it will be useful, but + without any warranty; without even the implied + warranty of merchantability or fitness for a particular + purpose. See the GNU General Public License for more + details. +

+ +

+ A copy of the GNU General Public License is available as + /usr/share/common-licenses/GPL in the Debian GNU/Linux + distribution or on the World Wide Web at + . You can also + obtain it by writing to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +

+ + + + + + + About this manual + + Scope +

+ This manual describes the policy requirements for the Debian + GNU/Linux distribution. This includes the structure and + contents of the Debian archive and several design issues of the + operating system, as well as technical requirements that + each package must satisfy to be included in the + distribution. +

+ + +

+ This manual also describes Debian policy as it relates to + creating Debian packages. It is not a tutorial on how to build + packages, nor is it exhaustive where it comes to describing + the behavior of the packaging system. Instead, this manual + attempts to define the interface to the package management + system that the developers have to be conversant with. + +

+ Informally, the criteria used for inclusion is that the + material meet one of the following requirements: + + Standard interfaces + +

+ The material presented represents an interface to + the packaging system that is mandated for use, and + is used by, a significant number of packages, and + therefore should not be changed without peer + review. Package maintainers can then rely on this + interfaces not changing, and the package + management software authors need to ensure + compatibility with these interface + definitions. (Control file and changelog file + formats are examples.) +

+ + Chosen Convention + +

+ If there are a number of technically viable choices + that can be made, but one needs to select one of + these options for inter-operability. The version + number format is one example. +

+ + + Please note that these are not mutually exclusive; + selected conventions often become parts of standard + interfaces. +

+ +

+ +

+ The footnotes present in this manual are + merely informative, and are not part of Debian policy itself. +

+ + +

+ In this manual, the words must, should and + may, and the adjectives required, + recommended and optional, are used to + distinguish the significance of the various guidelines in + this policy document. Packages that do not conform to the + guidelines denoted by must (or required) + will generally not be considered acceptable for the Debian + distribution. Non-conformance with guidelines denoted by + should (or recommended) will generally be + considered a bug, but will not necessarily render a package + unsuitable for distribution. Guidelines denoted by + may (or optional) are truly optional and + adherence is left to the maintainer's discretion. +

+

+ These classifications are roughly equivalent to the bug + severities serious (for must or + required directive violations), minor, + normal or important + (for should or recommended directive + violations) and wishlist (for optional + items). +

Compare RFC 2119. Note, however, that these words are + used in a different way in this document.

+ +

+

+ Much of the information presented in this manual will be + useful even when building a package which is to be + distributed in some other way or is intended for local use + only. +

+ + + New versions of this document +

+ The current version of this document is always accessible + from the Debian FTP server ftp.debian.org + as + /debian/doc/package-developer/policy.txt.gz + (also available from the same directory are several other + formats: policy.html.tar.gz, policy.pdf.gz + and policy.ps.gz) or from the webpage.

+ +

+ In addition, this manual is distributed via the Debian package + debian-policy. +

+ +

+ The debian-policy package also includes the file + upgrading-checklist.txt which indicates policy + changes between versions of this document. +

+ + + Feedback + +

+ As the Debian GNU/Linux system is continuously evolving this + manual does so too. +

+

+ While the authors of this document have tried hard to avoid + typos and other errors, these do still occur. If you discover + an error in this manual or if you want to give any + comments, suggestions, or criticisms please send an email to + the Debian Policy List, + debian-policy@lists.debian.org, or submit a + bug report against the debian-policy package. +

+ + + + + The Debian Archive +

+ The Debian GNU/Linux system is maintained and distributed as a + collection of packages. Since there are so many of + them (currently well over 6000), they are split into + sections and given priorities to simplify + the handling of them. +

+

+ The effort of the Debian project is to build a free operating + system, but not every package we want to make accessible is + free in our sense (see the Debian Free Software + Guidelines, below), or may be imported/exported without + restrictions. Thus, the archive is split into the sections + main, non-free, contrib, + non-US/main, non-US/non-free, and + non-US/contrib. The sections are explained in detail + below. +

+ +

+ The main and the non-US/main sections + together form the Debian GNU/Linux distribution. +

+ +

+ Packages in the other sections are not considered to be part + of the Debian distribution, although we support their use and + provide infrastructure for them (such as our bug-tracking + system and mailing lists). This Debian Policy Manual applies + to these packages as well.

+ + + Package copyright and sections +

+ The aims of this section are: + + + +

to allow us to make as much software available as we + can,

+ + +

to allow us to encourage everyone to write free + software, and

+ + +

to allow us to make it easy for people to produce + CD-ROMs of our system without violating any licenses, + import/export restrictions, or any other laws.

+ + +

+ + The Debian Free Software Guidelines +

+ The Debian Free Software Guidelines (DFSG) form our + definition of `free software'. These are: + + Free Redistribution + + +

+ The license of a Debian component may not restrict any + party from selling or giving away the software as a + component of an aggregate software distribution + containing programs from several different + sources. The license may not require a royalty or + other fee for such sale. +

+ + Source Code + + +

+ The program must include source code, and must allow + distribution in source code as well as compiled form. +

+ + Derived Works + + +

+ The license must allow modifications and derived + works, and must allow them to be distributed under the + same terms as the license of the original software. +

+ + Integrity of The Author's Source Code + + +

+ The license may restrict source-code from being + distributed in modified form only if the + license allows the distribution of ``patch files'' + with the source code for the purpose of modifying the + program at build time. The license must explicitly + permit distribution of software built from modified + source code. The license may require derived works to + carry a different name or version number from the + original software. (This is a compromise. The Debian + Project encourages all authors to not restrict any + files, source or binary, from being modified.) +

+ + No Discrimination Against Persons or Groups + + +

+ The license must not discriminate against any person + or group of persons. +

+ + No Discrimination Against Fields of Endeavor + + +

+ The license must not restrict anyone from making use + of the program in a specific field of endeavor. For + example, it may not restrict the program from being + used in a business, or from being used for genetic + research. +

+ + Distribution of License + + +

+ The rights attached to the program must apply to all + to whom the program is redistributed without the need + for execution of an additional license by those + parties. +

+ + License Must Not Be Specific to Debian + + +

+ The rights attached to the program must not depend on + the program's being part of a Debian system. If the + program is extracted from Debian and used or + distributed without Debian but otherwise within the + terms of the program's license, all parties to whom + the program is redistributed must have the same + rights as those that are granted in conjunction with + the Debian system. +

+ + License Must Not Contaminate Other Software + + +

+ The license must not place restrictions on other + software that is distributed along with the licensed + software. For example, the license must not insist + that all other programs distributed on the same medium + must be free software. +

+ + Example Licenses + + +

+ The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are + examples of licenses that we consider free. +

+ + +

+ + + The main section +

+ Every package in main and non-US/main + must comply with the DFSG (Debian Free Software + Guidelines).

+ +

+ In addition, the packages in main + + +

+ must not require a package outside of main + for compilation or execution (thus, the package must + not declare a "Depends", "Recommends", or + "Build-Depends" relationship on a non-main + package), +

+ + +

+ must not be so buggy that we refuse to support them, + and +

+ + +

+ must meet all policy requirements presented in this + manual. +

+ + +

+

+ Similarly, the packages in non-US/main + + +

+ must not require a package outside of main + or non-US/main for compilation or + execution, +

+ + +

+ must not be so buggy that we refuse to support them, +

+ + +

+ must meet all policy requirements presented in this + manual. +

+ + +

+ + + The contrib section +

+ Every package in contrib and + non-US/contrib must comply with the DFSG. +

+ +

+ In addition, the packages in contrib and + non-US/contrib + + +

+ must not be so buggy that we refuse to support them, + and +

+ + +

+ must meet all policy requirements presented in this + manual. +

+ + +

+ +

+ Furthermore, packages in contrib must not require + a package in a non-US section for compilation or + execution. +

+ +

+ Examples of packages which would be included in + contrib or non-US/contrib are: + + +

+ free packages which require contrib, + non-free packages or packages which are not + in our archive at all for compilation or execution, + and +

+ + +

+ wrapper packages or other sorts of free accessories for + non-free programs. +

+ + +

+ + + The non-free section +

+ Packages must be placed in non-free or + non-US/non-free if they are not compliant with + the DFSG or are encumbered by patents or other legal + issues that make their distribution problematic. +

+

+ In addition, the packages in non-free and + non-US/non-free + + +

+ must not be so buggy that we refuse to support them, + and +

+ + +

+ must meet all policy requirements presented in this + manual that it is possible for them to meet. + +

+ It is possible that there are policy + requirements which the package is unable to + meet, for example, if the source is + unavailable. These situations will need to be + handled on a case-by-case basis. +

+ +

+ + +

+ + + + The non-US sections +

+ Some programs with cryptographic program code need to be + stored on the non-US server because of United + States export restrictions. Such programs must be + distributed in the appropriate non-US section, + either non-US/main, non-US/contrib or + non-US/non-free. +

+

+ This applies only to packages which contain cryptographic + code. A package containing a program with an interface to + a cryptographic program or a program that's dynamically + linked against a cryptographic library should not be + distributed via the non-US server if it is + capable of running without the cryptographic library or + program. +

+ + + Further copyright considerations +

+ Every package must be accompanied by a verbatim copy of + its copyright and distribution license in the file + /usr/share/doc/<package>/copyright + (see for further details). +

+

+ We reserve the right to restrict files from being included + anywhere in our archives if + + +

+ their use or distribution would break a law, +

+ + +

+ there is an ethical conflict in their distribution or + use, +

+ + +

+ we would have to sign a license for them, or +

+ + +

+ their distribution would conflict with other project + policies. +

+ + +

+ +

+ Programs whose authors encourage the user to make + donations are fine for the main distribution, provided + that the authors do not claim that not donating is + immoral, unethical, illegal or something similar; in such + a case they must go in non-free.

+ +

+ Packages whose copyright permission notices (or patent + problems) do not even allow redistribution of binaries + only, and where no special permission has been obtained, + must not be placed on the Debian FTP site and its mirrors + at all.

+ +

+ Note that under international copyright law (this applies + in the United States, too), no distribution or + modification of a work is allowed without an explicit + notice saying so. Therefore a program without a copyright + notice is copyrighted and you may not do anything + to it without risking being sued! Likewise if a program + has a copyright notice but no statement saying what is + permitted then nothing is permitted.

+ +

+ Many authors are unaware of the problems that restrictive + copyrights (or lack of copyright notices) can cause for + the users of their supposedly-free software. It is often + worthwhile contacting such authors diplomatically to ask + them to modify their license terms. However, this can be a + politically difficult thing to do and you should ask for + advice on the debian-legal mailing list first, as + explained below. +

+ +

+ When in doubt about a copyright, send mail to + debian-legal@lists.debian.org. Be prepared + to provide us with the copyright statement. Software + covered by the GPL, public domain software and BSD-like + copyrights are safe; be wary of the phrases `commercial + use prohibited' and `distribution restricted'. +

+ + + Subsections + +

+ The packages in the sections main, + contrib and non-free are grouped further + into subsections to simplify handling. +

+ +

+ The section and subsection for each package should be + specified in the package's Section control + record. However, the maintainer of the Debian archive + may override this selection to ensure the consistency of + the Debian distribution. The Section field + should be of the form: + + +

+ subsection if the package is in the + main section, +

+ + +

+ section/subsection if the package is in + the contrib or non-free section, + and +

+ + +

+ non-US, non-US/contrib or + non-US/non-free if the package is in + non-US/main, non-US/contrib or + non-US/non-free respectively. +

+ + +

+ +

+ The Debian archive maintainers provide the authoritative + list of subsections. At present, they are: + admin, base, comm, + contrib, devel, doc, + editors, electronics, games, + graphics, hamradio, + interpreters, libs, mail, + math, misc, net, news, + non-US, non-free, oldlibs, + otherosfs, science, shells, + sound, tex, text, + utils, web, x11. +

+ + + Priorities + +

+ Each package should have a priority value, which is + included in the package's control record. This + information is used by the Debian package management tools + to separate high-priority packages from less-important + packages.

+ +

+ The following priority levels are recognised by the + Debian package management tools. + + required + +

+ Packages which are necessary for the proper + functioning of the system. You must not remove these + packages or your system may become totally broken and + you may not even be able to use dpkg to + put things back. Systems with only the + required packages are probably unusable, but + they do have enough functionality to allow the + sysadmin to boot and install more software.

+ + important + +

+ Important programs, including those which one would + expect to find on any Unix-like system. If the + expectation is that an experienced Unix person who + found it missing would say `What on earth is going on, + where is foo?', it must be an + important package. + +

+ This is an important criterion because we are + trying to produce, amongst other things, a free + Unix. +

+ + Other packages without which the system will not run + well or be usable must also have priority + important. This does + not include Emacs, the X Window System, TeX + or any other large applications. The + important packages are just a bare minimum of + commonly-expected and necessary tools.

+ + standard + +

+ These packages provide a reasonably small but not too + limited character-mode system. This is what will be + installed by default if the user doesn't select anything + else. It doesn't include many large applications, but + it does include Emacs (this is more of a piece of + infrastructure than an application) and a reasonable + subset of TeX and LaTeX.

+ + optional + +

+ (In a sense everything that isn't required is + optional, but that's not what is meant here.) This is + all the software that you might reasonably want to + install if you didn't know what it was and don't have + specialized requirements. This is a much larger system + and includes the X Window System, a full TeX + distribution, and many applications. Note that + optional packages should not conflict with each other. +

+ + extra + +

+ This contains all packages that conflict with others + with required, important, standard or optional + priorities, or are only likely to be useful if you + already know what they are or have specialised + requirements. +

+ +

+ +

+ Packages must not depend on packages with lower priority + values (excluding build-time dependencies). In order to + ensure this, the priorities of one or more packages may need + to be adjusted. +

+ + + + Binary packages + +

+ The Debian GNU/Linux distribution is based on the Debian + package management system, called dpkg. Thus, + all packages in the Debian distribution must be provided + in the .deb file format.

+ + + + The package name + +

+ Every package must have a name that's unique within the Debian + archive.

+ +

+ Package names must consist of lower case letters (a-z), + digits (0-9), plus (+) and minus (-) signs, and periods + (.). They must be at least two characters long and must + contain at least one letter. +

+ +

+ The package name is part of the file name of the + .deb file and is included in the control field + information. +

+ + + + The maintainer of a package +

+ Every package must have a Debian maintainer (the + maintainer may be one person or a group of people + reachable from a common email address, such as a mailing + list). The maintainer is responsible for ensuring that + the package is placed in the appropriate distributions. +

+ +

+ The maintainer must be specified in the + Maintainer control field with their correct name + and a working email address. If one person maintains + several packages, he/she should try to avoid having + different forms of their name and email address in + the Maintainer fields of those packages. +

+ +

+ If the maintainer of a package quits from the Debian + project, "Debian QA Group" + packages@qa.debian.org takes over the + maintainership of the package until someone else + volunteers for that task. These packages are called + orphaned packages. + +

+ The detailed procedure for doing this gracefully can + be found in the Debian Developer's Reference, either + in the developers-reference package, or on + the Debian FTP server + ftp.debian.org as + /debian/doc/package-developer/developers-reference.txt.gz + or from the webpage. +

+ +

+ + + + + The description of a package + +

+ Every Debian package must have an extended description + stored in the appropriate field of the control record.

+ +

+ The description should be written so that it gives the + system administrator enough information to decide whether + to install the package. This description should not just + be copied verbatim from the program's documentation. + Instructions for configuring or using the package should + not be included -- that is what installation scripts, + manual pages, info files, etc., are for. Copyright + statements and other administrivia should not be included + either -- that is what the copyright file is for.

+ + + + + Dependencies + +

+ Every package must specify the dependency information + about other packages that are required for the first to + work correctly.

+ +

+ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package.

+ +

+ Packages are not required to declare any dependencies they + have on other packages which are marked Essential + (see below), and should not do so unless they depend on a + particular version of that package.

+ +

+ Sometimes, a package requires another package to be installed + and configured before it can be installed. In this + case, you must specify a Pre-Depends entry for + the package.

+ +

+ You should not specify a Pre-Depends entry for a + package before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached.

 + + + + Virtual packages + +

+ Sometimes, there are several packages which offer + more-or-less the same functionality. In this case, it's + useful to define a virtual package whose name + describes that common functionality. (The virtual + packages only exist logically, not physically--that's why + they are called virtual.) The packages with this + particular function will then provide the virtual + package. Thus, any other package requiring that function + can simply depend on the virtual package without having to + specify all possible packages individually.

+ +

+ All packages should use virtual package names where + appropriate, and arrange to create new ones if necessary. + They should not use virtual package names (except privately, + amongst a cooperating group of packages) unless they have + been agreed upon and appear in the list of virtual package + names.

+ +

+ The latest version of the authoritative list of virtual + package names can be found on + ftp.debian.org in + /debian/doc/package-developer/virtual-package-names-list.txt + or your local mirror. In addition, it is included in the + debian-policy package. The procedure for updating + the list is described at the top of the file.

 + + + + Base packages + +

+ The packages included in the base section have a + special function. They form a minimum subset of the Debian + GNU/Linux system that is installed before everything else + on a new system. Thus, only very few packages are allowed + to go into the base section to keep the required + disk usage very small.

+ +

+ Most of these packages will have the priority value + required or at least important, and many + of them will be tagged essential (see below).

+ +

+ You must not place any packages into the base + section before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached.

 + + + + Essential packages + +

+ Some packages are tagged essential. (They have + Essential: yes in their package control record.) + This flag is used for packages that are essential + for a system.

+ +

+ Since these packages cannot be easily removed (one has to + specify an extra force option to + dpkg to do so), this flag must not be used + unless absolutely necessary. A shared library package + must not be tagged essential--dependencies will + prevent its premature removal, and we need to be able to + remove it when it has been superseded. +

+ +

+ Since dpkg will not prevent upgrading of other packages + while an essential package is in an unconfigured + state, all essential packages must supply all of + their core functionality even when unconfigured. If the + package cannot satisfy this requirement it must not be + tagged as essential, and any packages depending on this + package must instead have explicit dependency fields as + appropriate. +

+ +

+ You must not tag any packages essential before + this has been discussed on the debian-devel + mailing list and a consensus about doing that has been + reached. +

+ + + + Maintainer scripts + +

+ The package installation scripts should avoid producing + output which it is unnecessary for the user to see and + should rely on dpkg to stave off boredom on + the part of a user installing many packages. This means, + amongst other things, using the --quiet option on + install-info.

+ +

+ Errors which occur during the execution of an installation + script must be checked and the installation must not + continue after an error. +

+ +

+ Note that in general applies to package + maintainer scripts, too. +

+ +

+ You should not use dpkg-divert on a file + belonging to another package without consulting the + maintainer of that package first. +

+

+ All packages which supply an instance of a common command + name (or, in general, filename) should generally use + update-alternatives, so that they may be + installed together. If update-alternatives + is not used, then each package must use + Conflicts to ensure that other packages are + de-installed. (In this case, it may be appropriate to + specify a conflict against earlier versions of something + that previously did not use + update-alternatives - this is an exception to + the usual rule that versioned conflicts should be + avoided). +

+ + + + Prompting in maintainer scripts +

+ Package maintainer scripts may prompt the user if + necessary. Prompting may be accomplished by hand, or by + communicating with a program, such as + debconf, which conforms to the Debian + Configuration management specification, version 2 or + higher. These are included in the + debconf_specification files in the + debian-policy package. + You may also find this file on the FTP site + ftp.debian.org in + /debian/doc/package-developer/debconf_specification.txt.gz + or on your local mirror. + +

+ 2.5% of Debian packages [see ] + currently use debconf to prompt + the user at install time, and this number is growing + daily. The benefits of using debconf are briefly + explained at ; + they include preconfiguration, (mostly) + noninteractive installation, elimination of + redundant prompting, consistency of user interface, + etc. +

+

+ With this increasing number of packages using + debconf, plus the existance of a + nascent second implementation of the Debian + configuration management system + (cdebconf), and the stabalization + of the protocol these things use, the time has + finally come to reflect the use of these things in + policy. + +

+ +

+

+ Packages which use the Debian Configuration management + specification may contain an additional + config script and a templates + file in their control archive. The config + script might be run before the preinst + script, and before the package is unpacked or any of its + dependancies or pre-dependancies are satisfied. + Therefore it must work using only the tools present in + essential packages. + +

+ Debconf or another tool that + implements the Debian Configuration management + specification will also be installed, and any + versioned dependencies on it will be satisfied + before preconfiguration begins. +

+ +

+ +

+ Packages should try to minimize the amount of prompting + they need to do, and they should ensure that the user + will only ever be asked each question once. This means + that packages should try to use appropriate shared + configuration files (such as /etc/papersize and + /etc/news/server), and shared + debconf variables rather than each + prompting for their own list of required pieces of + information. +

+ +

+ It also means that an upgrade should not ask the same + questions again, unless the user has used dpkg + --purge to remove the package's configuration. The + answers to configuration questions should be stored in an + appropriate place in /etc so that the user can + modify them, and how this has been done should be + documented.

+ +

+ If a package has a vitally important piece of + information to pass to the user (such as "don't run me + as I am, you must edit the following configuration files + first or you risk your system emitting badly-formatted + messages"), it should display this in the + config or postinst script and + prompt the user to hit return to acknowledge the + message. Copyright messages do not count as vitally + important (they belong in + /usr/share/doc/package/copyright); + neither do instructions on how to use a program (these + should be in on-line documentation, where all the users + can see them).

+ +

+ Any necessary prompting should almost always be confined + to the config or postinst + script. If it is done in the postinst, it + should be protected with a conditional so that unnecessary + prompting doesn't happen if a package's installation fails + and the postinst is called with + abort-upgrade, abort-remove or + abort-deconfigure.

+ + + + + Source packages + + + Standards conformance + +

+ In the source package's Standards-Version control + field, you must specify the most recent version number of + this policy document with which your package complies. + The current version number is &version;. +

+ +

+ This information may be used to file bug reports + automatically if your package becomes too much out of + date. +

+ +

+ The version number has four components--major and minor + version number and major and minor patch level. When the + standards change in a way that requires every package to + change the major number will be changed. Significant + changes that will require work in many packages will be + signaled by a change to the minor number. The major patch + level will be changed for any change to the meaning of the + standards, however small; the minor patch level will be + changed when only cosmetic, typographical or other edits + are made which neither change the meaning of the document + nor affect the contents of packages.

+ +

+ Thus only the first three components of the policy version + are significant in the Standards-Version control + field, and so either these three components or the all + four components may be specified. + +

+ In the past, people specified the full version number + in the Standards-Version field, for example `2.3.0.0'. + Since minor patch-level changes don't introduce new + policy, it was thought it would be better to relax + policy and only require the first 3 components to be + specified, in this example `2.3.0'. All four + components may still be used if someone wishes to do + so. +

+ +

+ +

+ You should regularly, and especially if your package has + become out of date, check for the newest Policy Manual + available and update your package, if necessary. When your + package complies with the new standards you should update the + Standards-Version source package field and + release it. + +

+ See the file upgrading-checklist for + information about policy which has changed between + different versions of this document. +

+ +

+ + + + + Package relationships + +

+ Source packages should specify which binary packages they + require to be installed or not to be installed in order to + build correctly. For example, if building a package + requires a certain compiler, then the compiler should be + specified as a build-time dependency. +

+ +

+ It is not necessary to explicitly specify build-time + relationships on a minimal set of packages that are always + needed to compile, link and put in a Debian package a + standard "Hello World!" program written in C or C++. The + required packages are called build-essential, and + an informational list can be found in + /usr/share/doc/build-essential/list (which is + contained in the build-essential + package). + +

Rationale: + + +

This allows maintaining the list separately + from the policy documents (the list does not + need the kind of control that the policy + documents do). +

+ + +

+ Having a separate package allows one to install + the build-essential packages on a machine, as + well as allowing other packages such as task + packages to require installation of the + build-essential packages using the depends + relation. +

+ + +

+ The separate package allows bug reports against + the list to be categorized separately from + the policy management process in the BTS. +

+ + +

+ + +

+ +

+ When specifying the set of build-time dependencies, one + should list only those packages explicitly required by the + build. It is not necessary to list packages which are + required merely because some other package in the list of + build-time dependencies depends on them. + +

+ The reason for this is that dependencies change, and + you should list all those packages, and only + those packages that you need directly. What + others need is their business. For example, if you + only link against libimlib, you will need to + build-depend on libimlib2-dev but + not against any libjpeg* packages, even + though libimlib2-dev currently depends on + them: installation of libimlib2-dev + will automatically ensure that all of its run-time + dependencies are satisfied. +

+ +

+ +

+ If build-time dependencies are specified, it must be + possible to build the package and produce working binaries + on a system with only essential and build-essential + packages installed and also those required to satisfy the + build-time relationships (including any implied + relationships). In particular, this means that version + clauses should be used rigorously in build-time + relationships so that one cannot produce bad or + inconsistently configured packages when the relationships + are properly satisfied. +

+ + + Changes to the upstream sources + +

+ If changes to the source code are made that are not + specific to the needs of the Debian system, they should be + sent to the upstream authors in whatever form they prefer + so as to be included in the upstream version of the + package.

+ +

+ If you need to configure the package differently for + Debian or for Linux, and the upstream source doesn't + provide a way to do so, you should add such configuration + facilities (for example, a new autoconf test + or #define) and send the patch to the upstream + authors, with the default set to the way they originally + had it. You can then easily override the default in your + debian/rules or wherever is appropriate.

+ +

+ You should make sure that the configure utility + detects the correct architecture specification string + (refer to for details).

+ +

+ If you need to edit a Makefile where + GNU-style configure scripts are used, you + should edit the .in files rather than editing the + Makefile directly. This allows the user to + reconfigure the package if necessary. You should + not configure the package and edit the generated + Makefile! This makes it impossible for + someone else to later reconfigure the package.

 + + + + Documenting your changes + +

+ You should document your changes and updates to the source + package properly in the debian/changelog file. (Note + that mistakes in changelogs are usually best rectified by + making a new changelog entry rather than "rewriting history" + by editing old changelog entries.)

+ +

+ In non-experimental packages you must use a format for + debian/changelog which is supported by the most + recent released version of dpkg. + +

+ If you wish to use an alternative format, you may do + so as long as you include a parser for it in your + source package. The parser must have an API + compatible with that expected by + dpkg-genchanges and + dpkg-gencontrol. If there is general + interest in the new format, you should contact the + dpkg maintainer to have the parser + script for it included in the dpkg + package. (You will need to agree that the parser and + its manpage may be distributed under the GNU GPL, just + as the rest of `dpkg' is.) +

+ +

+ + + + + Error trapping in makefiles + +

+ When make invokes a command in a makefile + (including your package's upstream makefiles and + debian/rules), it does so using sh. This + means that sh's usual bad error handling + properties apply: if you include a miniature script as one + of the commands in your makefile you'll find that if you + don't do anything about it then errors are not detected + and make will blithely continue after + problems.

+ +

+ Every time you put more than one shell command (this + includes using a loop) in a makefile command you + must make sure that errors are trapped. For + simple compound commands, such as changing directory and + then running a program, using && rather + than semicolon as a command separator is sufficient. For + more complex commands including most loops and + conditionals you should include a separate set -e + command at the start of every makefile command that's + actually one of these miniature shell scripts.

 + + + + Obsolete constructs and libraries + +

+ The include file <varargs.h> is + provided to support end-users compiling very old software; + the library libtermcap is provided to support the + execution of software which has been linked against it + (either old programs or those such as Netscape which are + only available in binary form).

+ +

+ Debian packages should be patched to use + <stdarg.h> and ncurses + instead. +

+ + + + + Control files and their fields + +

+ Many of the tools in the package management suite manipulate + data represented in a common format, known as control + data. The data is often stored in control + files. Binary and source packages have control files, + and the .changes files which control the installation + of uploaded files are also in control file format. + Dpkg's internal databases are in a similar + format. +

+ + Syntax of control files + +

+ A control file consists of one or more paragraphs of fields. + The paragraphs are separated by blank lines. Some control + files allow only one paragraph; others allow several, in + which case each paragraph usually refers to a different + package. (For example, in source packages, the first + paragraph refers to the source package, and later paragraphs + refer to binary packages generated from the source.) +

+ +

+ Each paragraph consists of a series of data fields; each + field consists of the field name, followed by a colon and + then the data/value associated with that field. It ends at + the end of the line. Horizontal whitespace (spaces and + tabs) may occur immediately before or after the value and is + ignored there; it is conventional to put a single space + after the colon. For example, a field might be: + +Package: libc6 + + the field name is Package and the field value + libc6. +

+ +

+ Some fields' values may span several lines; in this case + each continuation line must start with a space or + tab. Any trailing spaces or tabs at the end of individual + lines of a field value are ignored. +

+ +

+ Except where otherwise stated only a single line of data is + allowed and whitespace is not significant in a field body. + Whitespace must not appear inside names (of packages, + architectures, files or anything else) or version numbers, + or between the characters of multi-character version + relationships. +

+ +

+ Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below. +

+ +

+ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +

+ + + + List of fields +

+ This list here is not supposed to be exhaustive. Most fields + are dealt with elsewhere in this document. +

+ Package + + +

+ The name of the binary package. Package names consist of + the alphanumerics and + - . + (plus, minus and full stop). +

+ +

+ They must be at least two characters long and must start + with an alphanumeric character and not be all digits. The + use of lowercase package names is strongly recommended + unless the package you're building (or referring to, in + other fields) is already using uppercase.

+ + + Version + + +

+ This lists the source or binary package's version number - + see . +

+ + + + Standards-Version + + +

+ The most recent version of the standards (the policy + manual and associated texts) with which the package + complies. This is updated manually when editing the + source package to conform to newer standards; it can + sometimes be used to tell when a package needs attention. + Its format is described above; see + . +

+ + + + Distribution + + +

+ In a .changes file or parsed changelog output + this contains the (space-separated) name(s) of the + distribution(s) where this version of the package should + be installed. Valid distributions are determined by the + archive maintainers. + + Current distribution names are: + + stable + +

+ This is the current `released' version of Debian + GNU/Linux. Once the distribution is + stable only security fixes and other + major bug fixes are allowed. When changes are + made to this distribution, the release number is + increased (for example: 2.2r1 becomes 2.2r2 then + 2.2r3, etc). +

+ + + unstable + +

+ This distribution value refers to the + developmental part of the Debian + distribution tree. New packages, new upstream + versions of packages and bug fixes go into the + unstable directory tree. Download from + this distribution at your own risk. +

+ + + testing + +

+ This distribution value refers to the + testing part of the Debian distribution + tree. It receives its packages from the + unstable distribution after a short time lag to + ensure that there are no major issues with the + unstable packages. It is less prone to breakage + than unstable, but still risky. It is not + possible to upload packages directly to + testing. +

+ + + frozen + +

+ From time to time, the frozen + distribution enters a state of `code-freeze' in + anticipation of release as a stable + version. During this period of testing only + fixes for existing or newly-discovered bugs will + be allowed. The exact details of this stage are + determined by the Release Manager. +

+ + + experimental + +

+ The packages with this distribution value are + deemed by their maintainers to be high + risk. Oftentimes they represent early beta or + developmental packages from various sources that + the maintainers want people to try, but are not + ready to be a part of the other parts of the + Debian distribution tree. Download at your own + risk. +

+ + + + You should list all distributions that the + package should be installed into. + +

+ + + + + + + Version numbering + +

+ Every package has a version number recorded in its + Version control file field. +

+ +

+ The package management system imposes an ordering on version + numbers, so that it can tell whether packages are being up- or + downgraded and so that package system front end applications + can tell whether a package it finds available is newer than + the one installed on the system. The version number format + has the most significant parts (as far as comparison is + concerned) at the beginning. +

+ +

+ The version number format is: + &lsqbepoch:]upstream_version[-debian_revision] +

+ +

+ The three components here are: + + epoch + + +

+ This is a single (generally small) unsigned integer. It + may be omitted, in which case zero is assumed. If it is + omitted then the upstream_version may not + contain any colons. +

+ +

+ It is provided to allow mistakes in the version numbers + of older versions of a package, and also a package's + previous version numbering schemes, to be left behind. +

+ + + + upstream_version + + +

+ This is the main part of the version number. It is + usually the version number of the original (`upstream') + package from which the .deb file has been made, + if this is applicable. Usually this will be in the same + format as that specified by the upstream author(s); + however, it may need to be reformatted to fit into the + package management system's format and comparison + scheme. +

+ +

+ The comparison behavior of the package management system + with respect to the upstream_version is + described below. The upstream_version + portion of the version number is mandatory. +

+ +

+ The upstream_version may contain only + alphanumerics + +

Alphanumerics are A-Za-z0-9 only.

+ + and the characters . + - + : (full stop, plus, hyphen, colon) and should + start with a digit. If there is no + debian_revision then hyphens are not allowed; + if there is no epoch then colons are not + allowed.

+ + + debian_revision + + +

+ This part of the version number specifies the version of + the Debian package based on the upstream version. It + may contain only alphanumerics and the characters + + and . (plus and full stop) and is + compared in the same way as the + upstream_version is. +

+ +

+ It is optional; if it isn't present then the + upstream_version may not contain a hyphen. + This format represents the case where a piece of + software was written specifically to be turned into a + Debian package, and so there is only one `debianization' + of it and therefore no revision indication is required. +

+ +

+ It is conventional to restart the + debian_revision at 1 each time the + upstream_version is increased. +

+ +

+ The package management system will break the version + number apart at the last hyphen in the string (if there + is one) to determine the upstream_version and + debian_revision. The absence of a + debian_revision compares earlier than the + presence of one (but note that the + debian_revision is the least significant part + of the version number). +

+ + + The upstream_version and debian_revision + parts are compared by the package management system using the + same algorithm: +

+ +

+ The strings are compared from left to right. +

+ +

+ First the initial part of each string consisting entirely of + non-digit characters is determined. These two parts (one of + which may be empty) are compared lexically. If a difference + is found it is returned. The lexical comparison is a + comparison of ASCII values modified so that all the letters + sort earlier than all the non-letters. +

+ +

+ Then the initial part of the remainder of each string which + consists entirely of digit characters is determined. The + numerical values of these two parts are compared, and any + difference found is returned as the result of the comparison. + For these purposes an empty string (which can only occur at + the end of one or both version strings being compared) counts + as zero. +

+ +

+ These two steps (comparing and removing initial non-digit + strings and initial digit strings) are repeated until a + difference is found or both strings are exhausted. +

+ +

+ Note that the purpose of epochs is to allow us to leave behind + mistakes in version numbering, and to cope with situations + where the version numbering scheme changes. It is + not intended to cope with version numbers containing + strings of letters which the package management system cannot + interpret (such as ALPHA or pre-), or with + silly orderings (the author of this manual has heard of a + package whose versions went 1.1, 1.2, + 1.3, 1, 2.1, 2.2, + 2 and so forth). +

+ +

+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. +

+ + + Version numbers based on dates +

+ In general, Debian packages should use the same version + numbers as the upstream sources.

+ +

+ However, in some cases where the upstream version number is + based on a date (e.g., a development `snapshot' release) the + package management system cannot handle these version + numbers without epochs. For example, dpkg will consider + `96May01' to be greater than `96Dec24'.

+ +

+ To prevent having to use epochs for every new upstream + version, the version number should be changed to the + following format in such cases: `19960501', `19961224'. It + is up to the maintainer whether he/she wants to bother the + upstream maintainer to change the version numbers upstream, + too.

+ +

+ Note that other version formats based on dates which are + parsed correctly by the package management system should + not be changed.

+ +

+ Native Debian packages (i.e., packages which have been + written especially for Debian) whose version numbers include + dates should always use the `YYYYMMDD' format.

+ + + + Packaging Considerations + + Time Stamps +

+ Maintainers should preserve the modification times of the + upstream source files in a package, as far as is reasonably + possible. + +

+ The rationale is that there is some information conveyed + by knowing the age of the file, for example, you could + recognize that some documentation is very old by looking + at the modification time, so it would be nice if the + modification time of the upstream source would be + preserved. +

+ +

+ + + debian/rules - the + main building script + +

+ This file must be an executable makefile, and contains the + package-specific recipes for compiling the package and + building binary package(s) from the source. +

+ +

+ It must start with the line #!/usr/bin/make -f, + so that it can be invoked by saying its name rather than + invoking make explicitly. +

+ +

+ Since an interactive debian/rules script makes it + impossible to auto-compile that package and also makes it + hard for other people to reproduce the same binary + package, all required targets MUST be + non-interactive. At a minimum, required targets are the + ones called by dpkg-buildpackage, namely, + clean, binary, binary-arch, + binary-indep, and build. It also follows + that any target that these targets depend on must also be + non-interactive. +

+ +

+ The required and optional targets are as follows: + + build + +

+ This should perform all non-interactive configuration + and compilation of the package. If a package has an + interactive pre-build configuration routine, the + Debianized source package must either be built after + this has taken place (so that the binary package can + be built without rerunning the configuration) or the + configuration routine modified to become + non-interactive. (The latter is preferable if there + are architecture-specific features detected by the + configuration routine.) +

+ +

+ For some packages, notably ones where the same + source tree is compiled in different ways to produce + two binary packages, the build target + does not make much sense. For these packages it is + good enough to provide two (or more) targets + (build-a and build-b or whatever) + for each of the ways of building the package, and a + build target that does nothing. The + binary target will have to build the + package in each of the possible ways and make the + binary package out of each. +

+ +

+ The build target must not do anything + that might require root privilege. +

+ +

+ The build target may need to run the + clean target first - see below. +

+ +

+ When a package has a configuration and build routine + which takes a long time, or when the makefiles are + poorly designed, or when build needs to + run clean first, it is a good idea to + touch build when the build process is + complete. This will ensure that if debian/rules + build is run again it will not rebuild the whole + program. + +

+ Another common way to do this is for build + to depend on build-stamp and to do + nothing else, and for the build-stamp + target to do the building and to touch + build-stamp on completion. This is + especially useful if the build routine creates a + file or directory called build; in such a + case, build will need to be listed as + a phony target (i.e., as a dependency of the + .PHONY target). See the documentation of + make for more information on phony + targets. +

+ +

+ + + binary, binary-arch, + binary-indep + + +

+ The binary target must be all that is + necessary for the user to build the binary package(s) + produced from this source package. All of these + targets are required to be non-interactive. It is + split into two parts: binary-arch builds + the binary packages which are specific to a particular + architecture, and binary-indep builds + those which are not. +

+ +

+ binary may be (and commonly is) a target + with no commands which simply depends on + binary-arch and + binary-indep. +

+ +

+ Each binary-* target should depend on + the build target, above, so that the + package is built if it has not been already. It + should then create the relevant binary package(s), + using dpkg-gencontrol to make their + control files and dpkg-deb to build + them and place them in the parent of the top level + directory. +

+ +

+ Both the binary-arch and + binary-indep targets must exist. + If one of them has nothing to do (which will always be + the case if the source generates only a single binary + package, whether architecture-dependent or not), it + must still exist and must always succeed. +

+ +

+ The binary targets must be invoked as + root. + +

+ The fakeroot package often allows one + to build a package correctly even without being + root. +

+ +

+ + + clean + + +

+ This must undo any effects that the build + and binary targets may have had, except + that it should leave alone any output files created in + the parent directory by a run of a binary + target. This target must be non-interactive. +

+ +

+ If a build file is touched at the end of + the build target, as suggested above, it + should be removed as the first action that + clean performs, so that running + build again after an interrupted + clean doesn't think that everything is + already done. +

+ +

+ The clean target may need to be + invoked as root if binary has been + invoked since the last clean, or if + build has been invoked as root (since + build may create directories, for + example). +

+ + + get-orig-source (optional) + + +

+ This target fetches the most recent version of the + original source package from a canonical archive site + (via FTP or WWW, for example), does any necessary + rearrangement to turn it into the original source + tar file format described below, and leaves it in the + current directory. +

+ +

+ This target may be invoked in any directory, and + should take care to clean up any temporary files it + may have left. +

+ +

+ This target is optional, but providing it if + possible is a good idea. +

+ + + +

+ The build, binary and + clean targets must be invoked with the current + directory being the package's top-level directory. +

+ + +

+ Additional targets may exist in debian/rules, + either as published or undocumented interfaces or for the + package's internal use. +

+ +

+ The architectures we build on and build for are determined + by make variables using the utility + dpkg-architecture. You can determine the + Debian architecture and the GNU style architecture + specification string for the build machine (the machine type + we are building on) as well as for the host machine (the + machine type we are building for). Here is a list of + supported make variables: + + +

DEB_*_ARCH (the Debian architecture)

+ + +

DEB_*_GNU_TYPE (the GNU style architecture + specification string)

+ + +

DEB_*_GNU_CPU (the CPU part of + DEB_*_GNU_TYPE)

+ + +

DEB_*_GNU_SYSTEM (the System part of + DEB_*_GNU_TYPE)

+ + where * is either BUILD for specification of + the build machine or HOST for specification of the + host machine. +

+ +

+ Backward compatibility can be provided in the rules file + by setting the needed variables to suitable default + values; please refer to the documentation of + dpkg-architecture for details. +

+ +

+ It is important to understand that the DEB_*_ARCH + string only determines which Debian architecture we are + building on or for. It should not be used to get the CPU + or system information; the GNU style variables should be + used for that. +

+ + + debian/changelog + + +

+ This file records the changes to the Debian-specific parts of the + package + +

+ Though there is nothing stopping an author who is also + the Debian maintainer from using it for all their + changes, it will have to be renamed if the Debian and + upstream maintainers become different people. In such a + case, however, it might be better to maintain the + package as a non-native package. +

+ . +

+ +

+ It has a special format which allows the package building + tools to discover which version of the package is being + built and find out other release-specific information. +

+ +

+ That format is a series of entries like this: + +package (version) distribution(s); urgency=urgency + + * change details + more change details + * even more change details + + -- maintainer name and email address date + +

+ +

+ package and version are the source + package name and version number. +

+ +

+ distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the + .changes file. See . +

+ +

+ urgency is the value for the Urgency + field in the .changes file for the upload. It is + not possible to specify an urgency containing commas; commas + are used to separate + keyword=value settings in the + dpkg changelog format (though there is + currently only one useful keyword, + urgency). + +

+ Usual urgency values are low, medium, + high and critical. They have an + effect on how quickly a package will be considered for + inclusion into the testing distribution, and + give an indication of the importance of any fixes + included in this upload. +

+ +

+ +

+ The change details may in fact be any series of lines + starting with at least two spaces, but conventionally each + change starts with an asterisk and a separating space and + continuation lines are indented so as to bring them in + line with the start of the text above. Blank lines may be + used here to separate groups of changes, if desired. +

+ +

+ If this upload resolves bugs recorded in the Bug Tracking + System (BTS), they may be automatically closed on the + inclusion of this package into the Debian archive by + including the string: closes: Bug#nnnnn + in the change details. + +

+ To be precise, the string should match the following + Perl regular expression: + /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i + Then all of the bug numbers listed will be closed by the + archive maintenance script (katie), or in + the case of an NMU, marked as fixed. +

+ +

+ +

+ The maintainer name and email address used in the changelog + should be the details of the person uploading this + version. They are not necessarily those of the + usual package maintainer. The information here will be + copied to the Changed-By field in the + .changes file, and then later used to send an + acknowledgement when the upload has been installed. +

+ +

+ The date should be in RFC822 format + +

+ This is generated by the 822-date + program. +

+ ; it should include the time zone specified + numerically, with the time zone name or abbreviation + optionally present as a comment in parentheses. +

+ +

+ The first `title' line with the package name should start + at the left hand margin; the `trailer' line with the + maintainer and date details should be preceded by exactly + one space. The maintainer details and the date must be + separated by exactly two spaces. +

+ + Defining alternative changelog formats + +

+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +

+

+ A changelog parser must not interact with the user at + all. +

+ + + + debian/substvars + and variable substitutions + +

+ When dpkg-gencontrol, + dpkg-genchanges and dpkg-source + generate control files they perform variable substitutions + on their output just before writing it. Variable + substitutions have the form + ${variable-name}. The optional file + debian/substvars contains variable substitutions to + be used; variables can also be set directly from + debian/rules using the -V option to the + source packaging commands, and certain predefined variables + are also available. +

+ +

+ The debian/substvars file is usually generated and + modified dynamically by debian/rules targets; in + this case it must be removed by the clean + target. +

+ +

+ See for full + details about source variable substitutions, including the + format of debian/substvars.

+ + + debian/files + + +

+ This file is not a permanent part of the source tree; it + is used while building packages to record which files are + being generated. dpkg-genchanges uses it + when it generates a .changes file. +

+ +

+ It should not exist in a shipped source package, and so it + (and any backup files or temporary files such as + files.new + +

+ files.new is used as a temporary file by + dpkg-gencontrol and + dpkg-distaddfile - they write a new + version of files here before renaming it, + to avoid leaving a corrupted copy if an error + occurs +

+ ) should be removed by the + clean target. It may also be wise to + ensure a fresh start by emptying or removing it at the + start of the binary target. +

+ +

+ When dpkg-gencontrol is run for a binary + package, it adds an entry to debian/files for the + .deb file that will be created when dpkg-deb + --build is run for that binary package. So for most + packages all that needs to be done with this file is to + delete it in the clean target. +

+ +

+ If a package upload includes files besides the source + package and any binary packages whose control files were + made with dpkg-gencontrol then they should be + placed in the parent of the package's top-level directory + and dpkg-distaddfile should be called to add + the file to the list in debian/files.

+ + + Restrictions on objects in source packages + + +

+ The source package may not contain any hard links + +

+ This is not currently detected when building source + packages, but only when extracting + them. +

+

+ Hard links may be permitted at some point in the + future, but would require a fair amount of + work. +

+ , device special files, sockets or setuid or + setgid files. + +

+ Setgid directories are allowed. +

+ +

+ + Descriptions of packages - the + Description field + +

+ The description is intended to describe the program to a user + who has never met it before so that they know whether they + want to install it. It should also give information about the + significant dependencies and conflicts between this package + and others, so that the user knows why these dependencies and + conflicts have been declared. +

+ + Notes about writing descriptions + + +

+ The single line synopsis should be kept brief - certainly + under 80 characters. +

+ +

+ Do not include the package name in the synopsis line. The + display software knows how to display this already, and you + do not need to state it. Remember that in many situations + the user may only see the synopsis line - make it as + informative as you can. +

+ +

+ Do not try to continue the single line synopsis into the + extended description. This will not work correctly when + the full description is displayed, and makes no sense + where only the summary (the single line synopsis) is + available. +

+ +

+ The extended description should describe what the package + does and how it relates to the rest of the system (in terms + of, for example, which subsystem it is which part of). +

+ +

+ The description field needs to make sense to anyone, even + people who have no idea about any of the things the + package deals with. + +

+ The blurb that comes with a program in its + announcements and/or README files is + rarely suitable for use in a description. It is + usually aimed at people who are already in the + community where the package is used. +

+ +

+ +

+ Put important information first, both in the synopsis and + extended description. Sometimes only the first part of the + synopsis or of the description will be displayed. You can + assume that there will usually be a way to see the whole + extended description. +

+ +

+ You may include information about dependencies and so forth + in the extended description, if you wish. +

+ +

+ Do not use tab characters. Their effect is not predictable. +

+ + + + + + + Package maintainer scripts + and installation procedure + + + Introduction to package maintainer scripts + + +

+ It is possible to supply scripts as part of a package which + the package management system will run for you when your + package is installed, upgraded or removed. +

+ +

+ These scripts are the files preinst, + postinst, prerm and postrm in the + control area of the package. They must be proper executable + files; if they are scripts (which is recommended), they must + start with the usual #! convention. They should be + readable and executable by anyone, and not world-writable. +

+ +

+ The package management system looks at the exit status from + these scripts. It is important that they exit with a + non-zero status if there is an error, so that the package + management system can stop its processing. For shell + scripts this means that you almost always need to + use set -e (this is usually true when writing shell + scripts, in fact). It is also important, of course, that + they don't exit with a non-zero status if everything went + well. +

+ +

+ When a package is upgraded a combination of the scripts from + the old and new packages is called during the upgrade + procedure. If your scripts are going to be at all + complicated you need to be aware of this, and may need to + check the arguments to your scripts. +

+ +

+ Broadly speaking the preinst is called before + (a particular version of) a package is installed, and the + postinst afterwards; the prerm + before (a version of) a package is removed and the + postrm afterwards. +

+ +

+ Programs called from maintainer scripts should not normally + have a path prepended to them. Before installation is + started, the package management system checks to see if the + programs ldconfig, + start-stop-daemon, install-info, + and update-rc.d can be found via the + PATH environment variable. Those programs, and any + other program that one would expect to be on the + PATH, should thus be invoked without an absolute + pathname. Maintainer scripts should also not reset the + PATH, though they might choose to modify it by + prepending or appending package-specific directories. These + considerations really apply to all shell scripts.

+ + + + Maintainer scripts Idempotency + +

+ It is necessary for the error recovery procedures that the + scripts be idempotent. This means that if it is run + successfully, and then it is called again, it doesn't bomb + out or cause any harm, but just ensures that everything is + the way it ought to be. If the first call failed, or + aborted half way through for some reason, the second call + should merely do the things that were left undone the first + time, if any, and exit with a success status if everything + is OK. + +

+ This is so that if an error occurs, the user interrupts + dpkg or some other unforeseen circumstance + happens you don't leave the user with a badly-broken + package when dpkg attempts to repeat the + action. +

+ +

+ + + + Controlling terminal for maintainer scripts + +

+ The maintainer scripts are guaranteed to run with a + controlling terminal and can interact with the user. + If they need to prompt for passwords, do full-screen + interaction or something similar you should do these + things to and from /dev/tty, since + dpkg will at some point redirect scripts' + standard input and output so that it can log the + installation process. Likewise, because these scripts + may be executed with standard output redirected into a + pipe for logging purposes, Perl scripts should set + unbuffered output by setting $|=1 so that the + output is printed immediately rather than being + buffered. +

+ +

+ Each script should return a zero exit status for + success, or a nonzero one for failure. +

+ + + Summary of ways maintainer + scripts are called + + +

+ + +

new-preinst install

+ + +

new-preinst install + old-version

+ + +

new-preinst upgrade + old-version

+ + +

old-preinst abort-upgrade + new-version +

+ + + +

+ + +

postinst configure + most-recently-configured-version

+ + +

old-postinst abort-upgrade + new-version

+ + +

conflictor's-postinst abort-remove + in-favour package + new-version

+ + +

+ deconfigured's-postinst + abort-deconfigure in-favour + failed-install-package version + removing conflicting-package + version +

+ + + +

+ + +

prerm remove

+ + +

old-prerm upgrade + new-version

+ + +

new-prerm failed-upgrade + old-version

+ + +

conflictor's-prerm remove + in-favour package + new-version

+ + +

+ deconfigured's-prerm deconfigure + in-favour package-being-installed + version removing + conflicting-package + version +

+ + + +

+ + +

postrm remove

+ + +

postrm purge

+ + +

+ old-postrm upgrade + new-version

+ + +

new-postrm failed-upgrade + old-version

+ + +

new-postrm abort-install

+ + +

new-postrm abort-install + old-version

+ + +

new-postrm abort-upgrade + old-version

+ + +

+ disappearer's-postrm disappear + overwriter + overwriter-version

 + +

+ + + Details of unpack phase of + installation or upgrade + + +

+ The procedure on installation/upgrade/overwrite/disappear + (i.e., when running dpkg --unpack, or the unpack + stage of dpkg --install) is as follows. In each + case, if a major error occurs (unless listed below) the + actions are, in general, run backwards - this means that the + maintainer scripts are run with different arguments in + reverse order. These are the `error unwind' calls listed + below. + + + +

+ + +

If a version of the package is already + installed, call + +old-prerm upgrade new-version +

+ + +

+ If the script runs but exits with a non-zero + exit status, dpkg will attempt: + +new-prerm failed-upgrade old-version + + Error unwind, for both the above cases: + +old-postinst abort-upgrade new-version + +

+ + +

+ + +

If a `conflicting' package is being removed at the same time: + + +

+ If any packages depended on that conflicting + package and --auto-deconfigure is + specified, call, for each such package: + +deconfigured's-prerm deconfigure \ + in-favour package-being-installed version \ + removing conflicting-package version + + Error unwind: + +deconfigured's-postinst abort-deconfigure \ + in-favour package-being-installed-but-failed version \ + removing conflicting-package version + + The deconfigured packages are marked as + requiring configuration, so that if + --install is used they will be + configured again if possible.

+ + +

To prepare for removal of the conflicting package, call: + +conflictor's-prerm remove \ + in-favour package new-version + + Error unwind: + +conflictor's-postinst abort-remove \ + in-favour package new-version + +

+ + +

+ + +

+ + +

If the package is being upgraded, call: + +new-preinst upgrade old-version +

+ + +

+ Otherwise, if the package had some configuration + files from a previous version installed (i.e., it + is in the `configuration files only' state): + +new-preinst install old-version +

+ + +

Otherwise (i.e., the package was completely purged): + +new-preinst install + + Error unwind actions, respectively: + +new-postrm abort-upgrade old-version +new-postrm abort-install old-version +new-postrm abort-install + +

+ + +

+ + + +

+ The new package's files are unpacked, overwriting any + that may be on the system already, for example any + from the old version of the same package or from + another package. Backups of the old files are kept + temporarily, and if anything goes wrong the package + management system will attempt to put them back as + part of the error unwind. +

+ +

+ It is an error for a package to contains files which + are on the system in another package, unless + Replaces is used (see ). + +

+ +

+ It is a more serious error for a package to contain a + plain file or other kind of non-directory where another + package has a directory (again, unless + Replaces is used). This error can be + overridden if desired using + --force-overwrite-dir, but this is not + advisable. +

+ +

+ Packages which overwrite each other's files produce + behavior which, though deterministic, is hard for the + system administrator to understand. It can easily + lead to `missing' programs if, for example, a package + is installed which overwrites a file from another + package, and is then removed again. + +

+ Part of the problem is due to what is arguably a + bug in dpkg. +

+ +

+ +

+ A directory will never be replaced by a symbolic link + to a directory or vice versa; instead, the existing + state (symlink or not) will be left alone and + dpkg will follow the symlink if there is + one.

+ + + + +

+ +

If the package is being upgraded, call + +old-postrm upgrade new-version +

+ + +

If this fails, dpkg will attempt: + +new-postrm failed-upgrade old-version + + Error unwind, for both cases: + +old-preinst abort-upgrade new-version + +

+ + +

+ This is the point of no return - if + dpkg gets this far, it won't back off + past this point if an error occurs. This will + leave the package in a fairly bad state, which + will require a successful re-installation to clear + up, but it's when dpkg starts doing + things that are irreversible. +

+ + +

+ Any files which were in the old version of the package + but not in the new are removed.

+ + +

The new file list replaces the old.

+ + +

The new maintainer scripts replace the old.

+ + + +

Any packages all of whose files have been overwritten during the + installation, and which aren't required for + dependencies, are considered to have been removed. + For each such package + + +

dpkg calls: + +disappearer's-postrm disappear \ + overwriter overwriter-version + +

+ + +

The package's maintainer scripts are removed. +

+ + +

+ It is noted in the status database as being in a + sane state, namely not installed (any conffiles + it may have are ignored, rather than being + removed by dpkg). Note that + disappearing packages do not have their prerm + called, because dpkg doesn't know + in advance that the package is going to + vanish. +

+ + +

+ + +

+ Any files in the package we're unpacking that are also + listed in the file lists of other packages are removed + from those lists. (This will lobotomize the file list + of the `conflicting' package if there is one.) +

+ + +

+ The backup files made during installation, above, are + deleted. +

+ + + +

+ The new package's status is now sane, and recorded as + `unpacked'. +

+ +

+ Here is another point of no return - if the + conflicting package's removal fails we do not unwind + the rest of the installation; the conflicting package + is left in a half-removed limbo. +

+ + + +

+ If there was a conflicting package we go and do the + removal actions (described below), starting with the + removal of the conflicting package's files (any that + are also in the package being installed have already + been removed from the conflicting package's file list, + and so do not get removed now). +

+ + +

+ + + Details of configuration + +

+ When we configure a package (this happens with dpkg + --install, or with --configure), we first + update any conffiles and then call: + +postinst configure most-recently-configured-version + +

+ +

+ No attempt is made to unwind after errors during + configuration. +

+ +

+ If there is no most recently configured version + dpkg will pass a null argument; older versions + of dpkg may pass <unknown> (including the + angle brackets) in this case. Even older ones do not pass a + second argument at all, under any circumstances. +

+ + + Details of removal and/or configuration purging + + +

+ + +

+ +prerm remove + +

+ + +

+ The package's files are removed (except conffiles). +

+ + +

+ +postrm remove + +

+ + +

+ All the maintainer scripts except the postrm + are removed. +

+ +

+ If we aren't purging the package we stop here. Note + that packages which have no postrm and no + conffiles are automatically purged when + removed, as there is no difference except for the + dpkg status.

+ + +

+ The conffiles and any backup files (~-files, + #*# files, %-files, + .dpkg-{old,new,tmp}, etc.) are removed.

+ + +

+ +postrm purge + +

+ + +

The package's file list is removed.

+ + + No attempt is made to unwind after errors during + removal. +

+ + + + + Declaring relationships between + packages + +

+ Packages can declare in their control file that they have + certain relationships to other packages - for example, that + they may not be installed at the same time as certain other + packages, and/or that they depend on the presence of others, + or that they should overwrite files in certain other packages + if present. +

+ +

+ This is done using the Depends, Pre-Depends, + Recommends, Suggests, Enhances, + Conflicts, Provides and Replaces + control file fields. +

+ +

+ Source packages may declare relationships to binary packages, + saying that they require certain binary packages to be + installed or absent at the time of building the package. +

+ +

+ This is done using the Build-Depends, + Build-Depends-Indep, Build-Conflicts and + Build-Conflicts-Indep control file fields. +

+ + Syntax of relationship fields + + +

+ These fields all have a uniform syntax. They are a list of + package names separated by commas. +

+ +

+ In the Depends, Recommends, + Suggests, Pre-Depends, + Build-Depends and Build-Depends-Indep + control file fields of the package, which declare + dependencies on other packages, the package names listed may + also include lists of alternative package names, separated + by vertical bar (pipe) symbols |. In such a case, + if any one of the alternative packages is installed, that + part of the dependency is considered to be satisfied. +

+ +

+ All of the fields except for Provides may restrict + their applicability to particular versions of each named + package. This is done in parentheses after each individual + package name; the parentheses should contain a relation from + the list below followed by a version number, in the format + described in . +

+ +

+ The relations allowed are <<, <=, + =, >= and >> for + strictly earlier, earlier or equal, exactly equal, later or + equal and strictly later, respectively. The deprecated + forms < and > were used to mean + earlier/later or equal, rather than strictly earlier/later, + so they should not appear in new packages (though + dpkg still supports them). +

+ +

+ Whitespace may appear at any point in the version + specification subject to the rules in , and must appear where it's necessary to + disambiguate; it is not otherwise significant. For + consistency and in case of future changes to + dpkg it is recommended that a single space be + used after a version relationship and before a version + number; it is also conventional to put a single space after + each comma, on either side of each vertical bar, and before + each open parenthesis. +

+ +

+ For example, a list of dependencies might appear as: + +Package: mutt +Version: 1.3.17-1 +Depends: libc6 (>= 2.2.1), exim | mail-transport-agent + +

+ +

+ All fields that specify build-time relationships + (Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep) + may be restricted to a certain set of architectures. This + is indicated in brackets after each individual package name and + the optional version specification. The brackets enclose a + list of Debian architecture names separated by whitespace. + Exclamation marks may be prepended to each of the names. + (It is not permitted for some names to be prepended with + exclamation marks and others not.) If the current Debian + host architecture is not in this list and there are no + exclamation marks in the list, or it is in the list with a + prepended exclamation mark, the package name and the + associated version specification are ignored completely for + the purposes of defining the relationships. +

+ +

+ For example: + +Source: glibc +Build-Depends-Indep: texinfo +Build-Depends: kernel-headers-2.2.10 [!hurd-i386], +hurd-dev [hurd-i386], gnumach-dev [hurd-i386] + +

+ + + + Binary Dependencies - Depends, + Recommends, Suggests, Enhances, + Pre-Depends + + +

+ These five fields are used to declare a dependency + relationship by one package on another. They appear in the + depending package's control file. +

+ +

+ A Depends field takes effect only when a + package is to be configured. It does not prevent a package + being on the system in an unconfigured state while its + dependencies are unsatisfied, and it is possible to replace + a package whose dependencies are satisfied and which is + properly installed with a different version whose + dependencies are not and cannot be satisfied; when this is + done the depending package will be left unconfigured (since + attempts to configure it will give errors) and will not + function properly. If it is necessary, a + Pre-Depends field can be used, which has a partial + effect even when a package is being unpacked, as explained + in detail below. (The other three dependency fields, + Recommends, Suggests and + Enhances, are only used by the various front-ends + to dpkg such as dselect.) +

+ +

+ For this reason packages in an installation run are usually + all unpacked first and all configured later; this gives + later versions of packages with dependencies on later + versions of other packages the opportunity to have their + dependencies satisfied. +

+ +

+ The Depends field thus allows package maintainers + to impose an order in which packages should be configured. +

+ +

+ The meaning of the five dependency fields is as follows: + + Depends + + +

+ This declares an absolute dependency. A package will + not be configured unless all of the packages listed in + its Depends field have been correctly + configured. +

+ +

+ The Depends field should be used if the + depended-on package is required for the depending + package to provide a significant amount of + functionality. +

+

+ The Depends field should also be used if the + postinst, prerm or + postrm scripts require the package to be + present in order to run. Note, however, that the + postrm cannot rely on any non-essential + packages to be present during the purge + phase. + + + Recommends + +

This declares a strong, but not absolute, dependency. +

+ +

+ The Recommends field should list packages + that would be found together with this one in all but + unusual installations.

+ + + Suggests + + +

+ This is used to declare that one package may be more + useful with one or more others. Using this field + tells the packaging system and the user that the + listed packages are related to this one and can + perhaps enhance its usefulness, but that installing + this one without them is perfectly reasonable. +

+ + + Enhances + +

+ This field is similar to Suggests but works in the + opposite direction. It is used to declare that a + package can enhance the functionality of another + package. +

+ + + Pre-Depends + + +

+ This field is like Depends, except that it + also forces dpkg to complete installation + of the packages named before even starting the + installation of the package which declares the + pre-dependency, as follows: +

+ +

+ When a package declaring a pre-dependency is about to + be unpacked the pre-dependency can be + satisfied if the depended-on package is either fully + configured, or even if the depended-on + package(s) are only unpacked or half-configured, + provided that they have been configured correctly at + some point in the past (and not removed or partially + removed since). In this case, both the + previously-configured and currently unpacked or + half-configured versions must satisfy any version + clause in the Pre-Depends field. +

+ +

+ When the package declaring a pre-dependency is about + to be configured, the pre-dependency will be + treated as a normal Depends, that is, it will + be considered satisfied only if the depended-on + package has been correctly configured. +

+ +

+ Pre-Depends should be used sparingly, + preferably only by packages whose premature upgrade or + installation would hamper the ability of the system to + continue with any upgrade that might be in progress. +

+ +

+ Pre-Depends are also required if the + preinst script depends on the named + package. It is best to avoid this situation if + possible. + + +

+

+ When selecting which level of dependency to use you should + consider how important the depended-on package is to the + functionality of the one declaring the dependency. Some + packages are composed of components of varying degrees of + importance. Such a package should list using + Depends the package(s) which are required by the + more important components. The other components' + requirements may be mentioned as Suggestions or + Recommendations, as appropriate to the components' relative + importance. +

+ + + Conflicting binary packages - + Conflicts + +

+ When one binary package declares a conflict with another + using a Conflicts field, dpkg will + refuse to allow them to be installed on the system at the + same time. +

+ +

+ If one package is to be installed, the other must be removed + first - if the package being installed is marked as + replacing (see ) the one on the system, + or the one on the system is marked as deselected, or both + packages are marked Essential, then + dpkg will automatically remove the package + which is causing the conflict, otherwise it will halt the + installation of the new package with an error. This + mechanism is specifically designed to produce an error when + the installed package is Essential, but the new + package is not. +

+ +

+ A package will not cause a conflict merely because its + configuration files are still installed; it must be at least + half-installed. +

+ +

+ A special exception is made for packages which declare a + conflict with their own package name, or with a virtual + package which they provide (see below): this does not + prevent their installation, and allows a package to conflict + with others providing a replacement for it. You use this + feature when you want the package in question to be the only + package providing some feature. +

+ +

+ A Conflicts entry should almost never have an + `earlier than' version clause. This would prevent + dpkg from upgrading or installing the package + which declared such a conflict until the upgrade or removal + of the conflicted-with package had been completed. +

+ + + Virtual packages - Provides + + +

+ As well as the names of actual (`concrete') packages, the + package relationship fields Depends, + Recommends, Suggests, Enhances, + Pre-Depends, Conflicts, + Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep + may mention `virtual packages'. +

+ +

+ A virtual package is one which appears in the + Provides control file field of another package. + The effect is as if the package(s) which provide a + particular virtual package name had been listed by name + everywhere the virtual package name appears. +

+ +

+ If there are both a real and a virtual package of the same + name then the dependency may be satisfied (or the conflict + caused) by either the real package or any of the virtual + packages which provide it. This is so that, for example, + supposing we have + +Package: foo +Depends: bar + + and someone else releases an enhanced version of the + bar package (for example, a non-US variant), they + can say: + +Package: bar-plus +Provides: bar + + and the bar-plus package will now also satisfy the + dependency for the foo package. +

+ +

+ If a dependency or a conflict has a version number attached + then only real packages will be considered to see whether + the relationship is satisfied (or the prohibition violated, + for a conflict) - it is assumed that a real package which + provides the virtual package is not of the `right' version. + So, a Provides field may not contain version + numbers, and the version number of the concrete package + which provides a particular virtual package will not be + looked at when considering a dependency on or conflict with + the virtual package name. +

+ +

+ It is likely that the ability will be added in a future + release of dpkg to specify a version number for + each virtual package it provides. This feature is not yet + present, however, and is expected to be used only + infrequently. +

+ +

+ If you want to specify which of a set of real packages + should be the default to satisfy a particular dependency on + a virtual package, you should list the real package as an + alternative before the virtual one. +

+ + + + Overwriting files and replacing + packages - Replaces + +

+ The Replaces control file field has two distinct + purposes, which come into play in different situations. +

+ + Overwriting files in other packages + +

+ Firstly, as mentioned before, it is usually an error for a + package to contain files which are on the system in + another package. +

+ +

+ However, if the overwriting package declares that it + Replaces the one containing the file being + overwritten, then dpkg will replace the file + from the old package with that from the new. The file + will no longer be listed as `owned' by the old package. +

+ +

+ If a package is completely replaced in this way, so that + dpkg does not know of any files it still + contains, it is considered to have `disappeared'. It will + be marked as not wanted on the system (selected for + removal) and not installed. Any conffiles + details noted for the package will be ignored, as they + will have been taken over by the overwriting package. The + package's postrm script will be run with a + special argument to allow the package to do any final + cleanup required. See . +

+ +

+ If an installed package, foo say, declares that + it replaces another, bar, and an attempt is made + to install bar, dpkg will discard + files in the bar package which would overwrite + those already present in foo. This is so that + you can install an older version of a package without + problems. +

+ +

+ For this usage of Replaces, virtual packages (see + ) are not considered when looking at a + Replaces field - the packages declared as being + replaced must be mentioned by their real names. +

+ +

+ Furthermore, this usage of Replaces only takes + effect when both packages are at least partially on the + system at once, so that it can only happen if they do not + conflict or if the conflict has been overridden. +

+ + + + Replacing whole packages, forcing their + removal + +

+ Secondly, Replaces allows the packaging system to + resolve which package should be removed when there is a + conflict - see . This usage only + takes effect when the two packages do conflict, + so that the two usages of this field do not interfere with + each other. +

+ +

+ In this situation, the package declared as being replaced + can be a virtual package, so for example, all mail + transport agents (MTAs) would have the following fields in + their control files: + +Provides: mail-transport-agent +Conflicts: mail-transport-agent +Replaces: mail-transport-agent + + ensuring that only one MTA can be installed at any one + time. + + + + Relationships between source and binary packages - + Build-Depends, Build-Depends-Indep, + Build-Conflicts, Build-Conflicts-Indep + + +

+ A source package may declare a dependency or a conflict on a + binary package, indicating which packages are required to be + present on the system in order to build the binary packages + from the source package. This is done with the control file + fields Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep. + The dependencies and conflicts they define must be satisfied + (as defined earlier for binary packages) in order to invoke + the targets in debian/rules, as follows: + + + Build-Depends, Build-Conflicts + +

+ The Build-Depends and + Build-Conflicts fields must be satisfied when + any of the following targets is invoked: + build, binary, binary-arch + and binary-indep. +

+ + Build-Depends-Indep, Build-Conflicts-Indep + +

+ The Build-Depends-Indep and + Build-Conflicts-Indep fields must be + satisfied when any of the following targets is + invoked: binary and binary-indep. +

+ + + +

+ + + + + + Configuration file handling + + +

+ This chapter has been superseded by . +

+ + + Shared libraries + +

+ Packages containing shared libraries must be constructed with + a little care to make sure that the shared library is always + available. This is especially important for packages whose + shared libraries are vitally important, such as the C library + (currently libc6). +

+ +

+ Firstly, the package should install the shared libraries under + their normal names. For example, the libgdbmg1 + package should install libgdbm.so.1.7.3 as + /usr/lib/libgdbm.so.1.7.3. The files should not be + renamed or re-linked by any prerm or + postrm scripts; dpkg will take care + of renaming things safely without affecting running programs, + and attempts to interfere with this are likely to lead to + problems. +

+ +

+ Secondly, the package should include the symbolic link that + ldconfig would create for the shared libraries. + For example, the libgdbmg1 package should include + a symbolic link from /usr/lib/libgdbm.so.1 to + libgdbm.so.1.7.3. This is needed so that the dynamic + linker (for example ld.so or + ld-linux.so.*) can find the library between the + time that dpkg installs it and the time that + ldconfig is run in the postinst + script. + +

+ The package management system requires the library to be + placed before the symbolic link pointing to it in the + .deb file. This is so that when + dpkg comes to install the symlink + (overwriting the previous symlink pointing at an older + version of the library), the new shared library is already + in place. In the past, this was achieved by creating the + library in the temporary packaging directory before + creating the symlink. Unfortunately, this was not always + effective, since the building of the tar file in the + .deb depended on the behavior of the underlying + file system. Some file systems (such as reiserfs) reorder + the files so that the order of creation is forgotten. + Starting with release 1.7.0, dpkg + will reorder the files itself as necessary when building a + package. Thus it is no longer important to concern + oneself with the order of file creation. +

+ +

+ +

+ Thirdly, the associated development package should contain a + symlink for the shared library without a version number. For + example, the libgdbmg1-dev package should include a + symlink from /usr/lib/libgdbm.so to + libgdbm.so.1.7.3. This symlink is needed by the + linker (ld) when compiling packages, as it will + only look for libgdbm.so when compiling dynamically. +

+ +

+ Any package installing shared libraries in one of the default + library directories of the dynamic linker (which are currently + /usr/lib and /lib) or a directory that is + listed in /etc/ld.so.conf + +

+ These are currently + +

/usr/X11R6/lib/Xaw3d

+

/usr/local/lib

 +

/usr/lib/libc5-compat

 +

/lib/libc5-compat

 +

/usr/X11R6/lib

 + +

+ + must call ldconfig in its postinst + script if and only if the first argument is configure + and should call it in the postrm script if the + first argument is remove. +

+ +

+ However, postrm and preinst scripts + must not call ldconfig in the case where + the package is being upgraded (see for + details), as ldconfig will see the temporary + names that dpkg uses for the files while it is + installing them and will make the shared library links point + to them, just before dpkg continues the + installation and renames the temporary files! +

+ + + Handling shared library dependencies - the + shlibs system + +

+ 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 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 needs to 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. +

+ + + The shlibs files present on the system + + +

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

+ + + /etc/dpkg/shlibs.override + +

+ This lists global overrides. This list is normally + empty. It is maintained by the local system + administrator. +

+ + + DEBIAN/shlibs files in the `build directory' + +

+ When packages are being built, any + debian/shlibs files are copied into the + control file area of the temporary build directory and + given the name shlibs. These files give + details of any shared libraries included in the + package. + +

+ An example may help here. Let us say that the + source package foo generates two binary + packages, libfoo2 and + foo-runtime. When building the binary + packages, the two packages are created in the + directories debian/libfoo2 and + debian/foo-runtime respectively. + (debian/tmp could be used instead of one + of these.) Since libfoo2 provides the + libfoo shared library, it will require a + shlibs file, which will be installed in + debian/libfoo2/DEBIAN/shlibs, eventually + to become + /var/lib/dpkg/info/libfoo2.shlibs. Then + when dpkg-shlibdeps is run on the + executable + debian/foo-runtime/usr/bin/foo-prog, it + will examine the + debian/libfoo2/DEBIAN/shlibs file to + determine whether foo-prog's library + dependencies are satisfied by any of the libraries + provided by libfoo2. For this reason, + dpkg-shlibdeps must only be run once + all of the individual binary packages' + shlibs files have been installed into the + build directory. +

+ +

+ + + /var/lib/dpkg/info/*.shlibs + +

+ These are the shlibs files corresponding to + all of the packages installed on the system, and are + maintained by the relevant package maintainers. +

+ + + /etc/dpkg/shlibs.default + +

+ This file lists any shared libraries whose packages + have failed to provide correct shlibs files. + It was used when the shlibs setup was first + introduced, but it is now normally empty. It is + maintained by the dpkg maintainer. +

+ + +

+ + + + How to use dpkg-shlibdeps and the + shlibs files + +

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

+ + + The shlibs File Format + + +

+ Each shlibs file has the same format. Lines + beginning with # are considered to be commments 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 + +

+ + The version part is the part which comes after + .so., so in our case, it is 1. +

+ +

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

+ + + + Providing a shlibs file + +

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

+ + since the debian/shlibs file itself is ignored by + dpkg-shlibdeps. +

+ +

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

+ + + + Writing the debian/shlibs.local file + +

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

+ + + + The Operating System + + + File system hierarchy + + + + Linux File system Structure + +

+ The location of all installed files and directories must + comply with the Linux File system Hierarchy Standard + (FHS). The latest version of this document can be found + alongside this manual or on + . + Specific questions about following the standard may be + asked on debian-devel, or referred to Daniel + Quinlan, the FHS coordinator, at + quinlan@pathname.com.

 + + + + Site-specific programs + +

+ As mandated by the FHS, packages must not place any + files in /usr/local, either by putting them in + the file system archive to be unpacked by dpkg + or by manipulating them in their maintainer scripts.

+ +

+ However, the package may create empty directories below + /usr/local so that the system administrator knows + where to place site-specific files. These directories + should be removed on package removal if they are + empty.

+ +

+ Note, that this applies only to directories below + /usr/local, not in + /usr/local. Packages must not create sub-directories + in the directory /usr/local itself, except those listed in + FHS, section 4.5. However, you may create directories + below them as you wish. You must not remove any of the + directories listed in 4.5, even if you created them.

+ +

+ Since /usr/local can be mounted read-only from a + remote server, these directories must be created and + removed by the postinst and prerm + maintainer scripts. These scripts must not fail if either + of these operations fail. (In the future, it will be + possible to tell dpkg not to unpack files + matching certain patterns, so that the directories can be + included in the .deb packages and system + administrators who do not wish these directories in + /usr/local do not need to have them.)

+ +

+ For example, the emacs package will contain + +mkdir -p /usr/local/lib/emacs/site-lisp || true + + in the postinst script, and + +rmdir /usr/local/lib/emacs/site-lisp || true +rmdir /usr/local/lib/emacs || true + + in the prerm script.

+ +

+ If you do create a directory in /usr/local for + local additions to a package, you should ensure that + settings in /usr/local take precedence over the + equivalents in /usr.

+ +

+ However, because '/usr/local' and its contents are for + exclusive use of the local administrator, a package must + not rely on the presence or absence of files or + directories in '/usr/local' for normal operation.

+ +

+ The /usr/local directory itself and all the + subdirectories created by the package should (by default) have + permissions 2775 (group-writable and set-group-id) and be + owned by root.staff.

+ + + The system-wide mail directory +

+ The system-wide mail directory is /var/mail. This + directory is part of the base system and should not owned + by any particular mail agents. The use of the old + location /var/spool/mail is deprecated, even + though the spool may still be physically located there. + To maintain partial upgrade compatibility for systems + which have /var/spool/mail as their physical mail + spool, packages using /var/mail must depend on + either libc6 (>= 2.1.3-13), or on + base-files (>= 2.2.0), or on later + versions of either one of these packages. +

+ + + + + + + + Users and groups + +

+ The Debian system can be configured to use either plain or + shadow passwords.

+ +

+ Some user ids (UIDs) and group ids (GIDs) are reserved + globally for use by certain packages. Because some packages + need to include files which are owned by these users or + groups, or need the ids compiled into binaries, these ids + must be used on any Debian system only for the purpose for + which they are allocated. This is a serious restriction, and + we should avoid getting in the way of local administration + policies. In particular, many sites allocate users and/or + local system groups starting at 100.

+ +

+ Apart from this we should have dynamically allocated ids, + which should by default be arranged in some sensible + order--but the behavior should be configurable.

+ +

+ Packages other than base-passwd must not modify + /etc/passwd, /etc/shadow, + /etc/group or /etc/gshadow.

+ +

+ The UID and GID ranges are as follows: + + 0-99: + +

+ Globally allocated by the Debian project, the + same on every Debian system. These ids will appear in + the passwd and group files of all + Debian systems, new ids in this range being added + automatically as the base-passwd package is + updated.

+ +

+ Packages which need a single statically allocated uid + or gid should use one of these; their maintainers + should ask the base-passwd maintainer for + ids.

+ + + 100-999: + +

+ Dynamically allocated system users and groups. + Packages which need a user or group, but can have this + user or group allocated dynamically and differently on + each system, should use `adduser --system' to + create the group and/or user. adduser + will check for the existence of the user or group, and + if necessary choose an unused id based on the ranges + specified in adduser.conf.

 + + + 1000-29999: + +

+ Dynamically allocated user accounts. By default + adduser will choose UIDs and GIDs for + user accounts in this range, though + adduser.conf may be used to modify this + behavior.

+ + + 30000-59999: + +

Reserved.

 + + + 60000-64999: + +

+ Globally allocated by the Debian project, but only + created on demand. The ids are allocated centrally and + statically, but the actual accounts are only created + on users' systems on demand.

+ +

+ These ids are for packages which are obscure or which + require many statically-allocated ids. These packages + should check for and create the accounts in + /etc/passwd or /etc/group (using + adduser if it has this facility) if + necessary. Packages which are likely to require + further allocations should have a `hole' left after + them in the allocation, to give them room to + grow.

 + + + 65000-65533: + +

Reserved.

 + + + 65534: + +

User `nobody.' The corresponding gid refers + to the group `nogroup.'

 + + + 65535: + +

+ (uid_t)(-1) == (gid_t)(-1). NOT TO BE USED, + because it is the error return sentinel value.

+ + +

+ + + System run levels + + + + Introduction + +

+ The /etc/init.d directory contains the scripts + executed by init at boot time and when init + state (or `runlevel') is changed (see ).

+ +

+ There are at least two different, yet functionally + equivalent, ways of handling these scripts. For the sake + of simplicity, this document describes only the symbolic + link method. However, it must not be assumed by maintainer + scripts that this method is being used, and any automated + manipulation of the various runlevel behaviours by + maintainer scripts must be performed using `update-rc.d' + as described below and not by manually installing or + removing symlinks. For information on the + implementation details of the other method, implemented in + the file-rc package, please refer to the + documentation of that package.

+ +

+ These scripts are referenced by symbolic links in + the /etc/rcn.d directories. When + changing runlevels, init looks in the + directory /etc/rcn.d for the scripts + it should execute, where n is the runlevel that + is being changed to, or `S' for the boot-up scripts.

+ +

+ The names of the links all have the form + Smmscript or + Kmmscript where + mm is a two-digit number and script + is the name of the script (this should be the same as the + name of the actual script in /etc/init.d.

+ +

+ When init changes runlevel first the targets + of the links whose names starting with a K are + executed, each with the single argument stop, + followed by the scripts prefixed with an S, each + with the single argument start. The K + links are responsible for killing services and the + S link for starting services upon entering the + runlevel.

+ +

+ For example, if we are changing from runlevel 2 to + runlevel 3, init will first execute all of the K + prefixed scripts it finds in /etc/rc3.d, and then + all of the S prefixed scripts. The links + starting with K will cause the referred-to file + to be executed with an argument of stop, and the + S links with an argument of start.

+ +

+ The two-digit number mm is used to decide which + order to start and stop things in--low-numbered links have + their scripts run first. For example, the K20 + scripts will be executed before the K30 scripts. + This is used when a certain service must be started before + another. For example, the name server bind + might need to be started before the news server + inn so that inn can set up its + access lists. In this case, the script that starts + bind would have a lower number than the + script that starts inn so that it runs first: + +/etc/rc2.d/S17bind +/etc/rc2.d/S70inn + +

+ + + + Writing the scripts + +

+ Packages that include daemons for system services should + place scripts in /etc/init.d to start or stop + services at boot time or during a change of runlevel. + These scripts should be named + /etc/init.d/package, and they should + accept one argument, saying what to do: + + + start +

start the service,

+ + stop +

stop the service,

 + + restart +

stop and restart the service,

 + + reload +

cause the configuration of the service to be + reloaded without actually stopping and restarting + the service,

 + + force-reload

cause the + configuration to be reloaded if the service supports + this, otherwise restart the service.

 + + + The start, stop, restart, and + force-reload options should be supported by all + scripts in /etc/init.d, the reload + option is optional.

+ +

+ The init.d scripts should ensure that they will + behave sensibly if invoked with start when the + service is already running, or with stop when it + isn't, and that they don't kill unfortunately-named user + processes. The best way to achieve this is usually to use + start-stop-daemon.

+ +

+ If a service reloads its configuration automatically (as + in the case of cron, for example), the + reload option of the init.d script + should behave as if the configuration has been reloaded + successfully.

+ +

+ These scripts should not fail obscurely when the + configuration files remain but the package has been + removed, as configuration files remain on the system after + the package has been removed. Only when dpkg + is executed with the --purge option will + configuration files be removed. In particular, the init + script itself is usually a configuration file (see + ), and will remain on the system if + the package is removed but not purged. Therefore, you + should include a test statement at the top of the + script, like this: + +test -f program-executed-later-in-script || exit 0 +

+ +

+ Often there are some values in the `init.d' + scripts that a system administrator will frequently want + to change. While the scripts are frequently conffiles, + modifying them requires that the administrator merge in + their changes each time the package is upgraded and the + conffile changes. To ease the burden on the system + administrator, such configurable values should not be + placed directly in the script. Instead, they should be + placed in a file in `/etc/default', which + typically will have the same base name as the + `init.d' script. This extra file can be sourced + by the script when the script runs. It must contain only + variable settings and comments. +

+ +

+ To ensure that vital configurable values are always + available, the `init.d' script should set default + values for each of the shell variables it uses before + sourcing the /etc/default/ file. Also, since the + `/etc/default/' file is often a conffile, the + `init.d' script must behave sensibly without + failing if it is deleted. +

+ + + + + Managing the links + +

+ The program update-rc.d is provided to make + it easier for package maintainers to arrange for the + proper creation and removal of + /etc/rcn.d symbolic links, or their + functional equivalent if another method is being used. + This may be used by maintainers in their packages' + postinst and postrm scripts.

+ +

+ You must use this script to make changes to + /etc/rcn.d and never either + include any /etc/rcn.d symbolic links + in the actual archive or manually create or remove the + symbolic links in maintainer scripts. (The latter will + fail if an alternative method of maintaining runlevel + information is being used.)

+ +

+ By default update-rc.d will start services in + each of the multi-user state runlevels (2, 3, 4, and 5) + and stop them in the halt runlevel (0), the single-user + runlevel (1) and the reboot runlevel (6). The system + administrator will have the opportunity to customize + runlevels by either running update-rc.d, by + simply adding, moving, or removing the symbolic links in + /etc/rcn.d if symbolic links are being + used, or by modifying /etc/runlevel.conf if the + file-rc method is being used.

+ +

+ To get the default behavior for your package, put in your + postinst script + +update-rc.d package defaults >/dev/null + + and in your postrm + +if [ purge = "$1" ]; then + update-rc.d package remove >/dev/null +fi +

+ +

+ This will use a default sequence number of 20. If it does + not matter when or in which order the script is run, use + this default. If it does, then you should talk to the + maintainer of the sysvinit package or post to + debian-devel, and they will help you choose a + number.

+ +

+ For more information about using update-rc.d, + please consult its manpage .

 + + + + Boot-time initialization + +

+ There used to be another directory, /etc/rc.boot, + which contained scripts which were run once per machine + boot. This has been deprecated in favour of links from + /etc/rcS.d to files in /etc/init.d as + described in . Packages must not + place files in /etc/rc.boot.

+ + + Notes + +

+ Do not include the + /etc/rcn.d/* symbolic links in the + .deb file system archive! This will cause + problems! You must create them with + update-rc.d, as above.

+ +

+ Do not include the + /etc/rcn.d/* symbolic links in + dpkg's conffiles list! This will cause + problems! You should, however, treat the + /etc/init.d scripts as configuration files, + either by marking them as conffiles or managing them + correctly in the maintainer scripts (see + ). (This is important since we want + to give the local system administrator the chance to adapt + the scripts to the local system--e.g., to disable a + service without de-installing the package, or to specify + some special command line options when starting a + service--while making sure her changes aren't lost during + the next package upgrade.)

+ + + + Example + +

+ The bind DNS (nameserver) package wants to + make sure that the nameserver is running in multiuser + runlevels, and is properly shut down with the system. It + puts a script in /etc/init.d, naming the script + appropriately bind. As you can see, the script + interprets the argument reload to send the + nameserver a HUP signal (causing it to reload its + configuration); this way the user can say + /etc/init.d/bind reload to reload the name + server. The script has one configurable value, which can + be used to pass parameters to the named program at + startup. +

+ +

+ #!/bin/sh -BAR=/var/lib/fubar +# +# Original version by Robert Leslie +# <rob@mars.org>, edited by iwj and cs + +test -x /usr/sbin/named || exit 0 + +# Source defaults file. +PARAMS='' +if [ -f /etc/default/bind ]; then + . /etc/default/bind +fi + + +case "$1" in +start) + echo -n "Starting domain name service: named" + start-stop-daemon --start --quiet --exec /usr/sbin/named \ + -- $PARAMS + echo "." + ;; +stop) + echo -n "Stopping domain name service: named" + start-stop-daemon --stop --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + echo "." + ;; +restart) + echo -n "Restarting domain name service: named" + start-stop-daemon --stop --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + start-stop-daemon --start --verbose --exec /usr/sbin/named \ + -- $PARAMS + echo "." + ;; +force-reload|reload) + echo -n "Reloading configuration of domain name service: named" + start-stop-daemon --stop --signal 1 --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + echo "." + ;; +*) + echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2 + exit 1 + ;; +esac + +exit 0 + +

+ +

+ Complementing the above init script is a file + '/etc/default/bind', which contains configurable + parameters used by the script. +

+

+ +# Specified parameters to pass to named. See named(8). +# You may uncomment the following line, and edit to taste. +#PARAMS="-u nobody" + +

+ +

+ Another example on which to base your /etc/init.d + scripts is in /etc/init.d/skeleton.

+ +

+ If this package is happy with the default setup from + update-rc.d, namely an ordering number of 20 + and having named running in all runlevels, it can say in + its postinst: + +update-rc.d bind defaults >/dev/null + + And in its postrm, to remove the links when the + package is purged: + +if [ purge = "$1" ]; then + update-rc.d bind remove >/dev/null +fi +

+ + + + Cron jobs + +

+ 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 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 (shell scripts, Perl scripts, etc.) 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.

+ + + + Console messages + +

+ This section describes different formats 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.

+ +

+ Please look very careful at the details. We want to get the + messages to look exactly the same way concerning 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 isn't covered in the sections + below.

+ +

+ + +

+ Every message should cover one line, start with a + capital letter and end with a period `.'.

+ + + +

+ If you want to express that the computer is working on + something (performing a specific task, not starting or + stopping a program), we use an ``ellipsis'', namely + three dots `...'. Note that we don't insert spaces in + front of or behind the dots. If the task has been + completed we write `done.' and a line feed.

 + + + +

+ Design your messages as if the computer is telling you + what he is doing (let him be polite :-) but don't + mention ``him'' directly. For example, if you think + of saying + +I'm starting network daemons: nfsd mountd. + + just say + +Starting network daemons: nfsd mountd. + +

+ + +

+ +

+ The following formats should be used

+ +

+ + +

when daemons get started.

+ +

+ Use this format 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-2> <...> <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 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. +

+ + + +

when something needs to be configured.

+ +

+ If you have to set up different parameters of the + system upon boot up, you should use this format: + +Setting <parameter> to `<value>'. + +

+ +

+ You can use the following echo statement to get the quotes right: + +echo "Setting DNS domainname to \`"value"'." + +

+ +

+ Note that the left quotation mark (`) is different + from the right ('). +

+ + + +

when a daemon is stopped.

+ +

+ When you stop a daemon you should issue a message + similar to the startup message, except that `Starting' + is replaced with `Stopping'.

+ +

+ So stopping the printer daemon will like like this: + +Stopping printer spooler: lpd. +

+ + +

when something is executed.

+ +

+ There are several examples where you have to run a + program at system startup or shutdown to perform a + specific task. For example, setting the system's clock + via `netdate' or killing all processes when the system + comes down. Your message should like this: + +Doing something very useful...done. + + You should print the `done.' right after the job has been completed, + so that the user gets informed why he has to wait. You can get this + behavior by saying + +echo -n "Doing something very useful..." +do_something +echo "done." + + in your script. +

+ + + +

when the configuration is reloaded.

+ +

+ When a daemon is forced to reload its configuration + files you should use the following format: + +Reloading <daemon's-name> configuration...done. + +

+ + + +

when none of the above rules apply.

+ +

+ If you have to print a message that doesn't fit into + the styles described above, you can use something + appropriate, but please have a look at the overall + rules listed above. +

+ + +

+ + + + Menus + +

+ Menu entries should follow the current menu policy as + defined in the file ftp.debian.org in + /debian/doc/package-developer/menu-policy.txt.gz + or your local mirror. In addition, it is included in the + debian-policy package. +

+ +

+ The Debian menu packages provides a unique + interface between packages providing applications and + documents, and menu programs (either X window + managers or text-based menu programs 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 refer to the Debian Menu System document + that comes with the menu package for information + about how to register your applications and web + documents.

+ + + + + Multimedia handlers + +

+ 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 as defined + in the file found on ftp.debian.org in + /debian/doc/package-developer/mime-policy.txt.gz + or your local mirror. In addition, it is included in the + debian-policy package. +

+ +

+ MIME (Multipurpose Internet Mail Extensions, RFC 1521) 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. +

+ + + + Keyboard configuration + +

+ To achieve a consistent keyboard configuration (i.e., all + applications interpret a keyboard event the same way) all + programs in the Debian distribution must be configured to + comply with the following guidelines.

+ +

+ Here is a list that contains certain keys and their interpretation: + + + <-- +

delete the character to the left of the cursor

+ + Delete +

delete the character to the right of the cursor

 + + Control+H +

emacs: the help prefix

 + + + The interpretation of any keyboard events should be independent + of the terminal that's used, be it a virtual console, an X + terminal emulator, an rlogin/telnet session, etc.

+ +

+ The following list explains how the different programs + should be set up to achieve this:

+ +

+ +

`<--' generates KB_Backspace in + X.

+ +

`Delete' generates KB_Delete in X.

 + + +

+ X translations are set up to make KB_Backspace + generate ASCII DEL, and to make KB_Delete generate + ESC [ 3 ~ (this is the vt220 escape code for + the `delete character' key). This must be done by + loading the resources using xrdb on all local X + displays, not using the application defaults, so that + the translation resources used correspond to the + xmodmap settings.

 + + +

+ The Linux console is configured to make + `<--' generate DEL, and `Delete' generate + ESC [ 3 ~ (this is the case at the + moment).

 + +

+ X applications are configured so that Backspace + deletes left, and Delete deletes right. Motif + applications already work like this.

 + +

stty erase ^? .

 + +

+ The `xterm' terminfo entry should have ESC [ 3 + ~ for kdch1, just like TERM=linux and + TERM=vt220.

 + +

+ Emacs is programmed to map KB_Backspace or the `stty + erase' character to delete-backward-char, and + KB_Delete or kdch1 to delete-forward-char, and + ^H to help as always.

 + +

+ Other applications use the `stty erase' character and + kdch1 for the two delete keys, with ASCII DEL being + `delete previous character' and kdch1 being `delete + character under cursor'.

 +

+ +

+ This will solve the problem except for:

+ +

+ +

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

+ +

+ Some operating systems use ^H for stty erase. + However, modern telnet versions and all rlogin + versions propagate stty settings, and almost all UNIX + versions honour stty erase. Where the stty settings + are not propagated correctly things can be made to + work by using stty manually.

 + +

+ Some systems (including previous Debian versions) use + xmodmap to arrange for both <-- and Delete + to generate KB_Delete. We can change the behavior + of their X clients via the same X resources that we + use to do it for our own, or have our clients be + configured via their resources when things are the + other way around. On displays configured like this + Delete will not work, but <-- + will.

 + +

+ Some operating systems have different kdch1 settings + in their terminfo for xterm and others. On these + systems the Delete key will not work correctly when + you log in from a system conforming to our policy, but + <-- will.

 + +

+ + + + + Environment variables + +

+ 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 - - - - -Customized programs -

- -Architecture specification strings -

- -If a program needs to specify an architecture specification -string in some place, the following format has to be used: - - <arch>-linux - -where `<arch>' is one of the following: i386, alpha, arm, m68k, -powerpc, sparc. -

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

- -Daemons -

- -The configuration files /etc/services, -/etc/protocols, and /etc/rpc are managed by the - - -If a package requires a new entry in one of these files, the -maintainer has to get in contact with the - -The configuration file /etc/inetd.conf may be modified by the -package's scripts only via the - -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 - -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. -

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

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

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

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

- - -

- -Mail transport agents -

- -Debian packages which process electronic mail, whether -mail-user-agents (MUAs) or mail-transport-agents (MTAs), - -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 - -Mailboxes are generally 660 - -The mail spool is 2775 - -/etc/aliases is the source file for the system mail aliases -(e.g., postmaster, usenet, etc.)--it is the one which the sysadmin -and /etc/aliases is edited -the program or human editing it must call - -The convention of writing - -The location for the /usr/sbin/rmail, as per the FSSTND. Likewise, -/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 - -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 -where - -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. -

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

- -Emacs lisp programs -

- -Please refer to the `Debian Emacs Policy' (documented in -debian-emacs-policy.gz of the - -Games -

- -The permissions on /var/lib/games are 755 - -Each game decides on its own security policy. -

- -Games which require protected, privileged access to high-score files, -savegames, etc., must be made set- - -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 - -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. -

- -Documentation -

- -Manual pages -

- -You must install manual pages in /usr/man. You should only use sections 1 to 9 -(see the FSSTND for more details). You must - -If no manual page is available for a particular program, utility or -function and this is reported as a bug on debian-bugs, a symbolic link -from the requested manual page to the manual page should be provided. This symbolic link can be -created from debian/rules like this: - - ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/man/man[1-9]/the_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 - -If one manpage needs to be accessible via several names it is better -to use a symbolic link than the /usr/man). -

- -Info documents -

- -Info documents should be installed in /usr/info. They should -be compressed with - -Your package must call - install-info --quiet --section Development Development \ - /usr/info/foobar.info - -

- -It is a good idea to specify a section for the location of your -program; this is done with the /usr/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 - -You must remove the entries in the pre-removal script: - - install-info --quiet --remove /usr/info/foobar.info - -

- -If for details. -

- -Additional documentation -

- -Any additional documentation that comes with the package can be -installed at the discretion of the package maintainer. Text -documentation should be installed in a directory -/usr/doc/, where - -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 (/usr/doc/ in the binary package. However, you don't -need to install the instructions for building and installing the package, of -course! -

- -Preferred documentation formats -

- -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 the binary package, in the directory -/usr/doc/ or its subdirectories. -

- -Other formats such as PostScript may be provided at your option. -

- -Log files -

- -Log files should usually be named /var/log/. -If you have many log files, or need a separate directory for -permissions reasons (/var/log is writable only by -/var/log/. -

- -Make sure that any log files are rotated occasionally so that they -don't grow indefinitely; the best way to do this is to use -/etc/cron.daily, -/etc/cron.weekly or /etc/cron.monthly script. Here is a good -example: - - [ -d /var/log/apache/. ] || exit 0 - umask 022 - cd /var/log/apache - if [ -fs access.log ] - then - savelog -c 7 access.log > /dev/null - fi - -

- -Make sure that any log files are removed when the package is purged -(but not when it is only removed), by checking the argument to the -Debian Packaging Manual for -details). -

- -Copyright information -

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

- -/usr/doc/<package-name> may be a symbolic link to a directory in -/usr/doc only if two packages both come from the same source and the -first package has a "Depends" relationship 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/doc/copyright/BSD, /usr/doc/copyright/Artistic, -/usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL. -

- -Do not use the copyright file as a general /usr/doc/ or - -Examples -

- -Any examples (configurations, source files, whatever), should be -installed in a directory /usr/doc/. -These files should not be referenced by any program--they're there -for the benefit of the system administrator and users, as -documentation only. -

- -Changelog files -

- -This installed file must contain a copy of the debian/changelog -file from your Debian source tree, and a copy of the upstream -changelog file if there is one. They should usually be installed in -/usr/doc/ as - -Both should be installed compressed using - -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/doc/; if there is a separate -upstream maintainer, but no upstream changelog, then the Debian -changelog should still be called - - +

+ +

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

+ + + + Files + + + + Binaries + +

+ 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.') + If this case happens, one of the programs must be + renamed. The maintainers should report this to the + developers' mailing and try to find a consensus about + which package will have to be renamed. If a consensus can + not 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. The following makefile snippet is only + an example of how one may test for either condition: + +

+ Rationale: Building by default with -g causes more + wasted CPU cycles since the information is stripped away + anyway. The package can by default build without -g if + it also provides a mechanism to easily be rebuilt with + debugging information. This can be done by providing a + "build-debug" make target, or allowing the user to + specify "DEB_BUILD_OPTIONS=debug" in the environment while + compiling that package. +

+

Now this has several added benefits: + + +

+ It is actually easier to build debugging bins and + libraries this way (no more editing debian/rules + or similar) since it provides a documented way of + getting this type of build.

+ + +

+ There will be much less wasted CPU time for the + autobuilders since not having debugging + information (and hence also not having to strip + it) will increase the speed of compiles. This + skips an entire pass of the compiler. +

+ + +

+ + + + +CFLAGS = -O2 -Wall +INSTALL = install +INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 +INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 +INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 +INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 + +ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS))) +CFLAGS += -g +endif +ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) +INSTALL_PROGRAM += -s +endif + + + Please note that the above example is merely informative, + and is not a policy mandate. You may have to massage this + example in order to make it work for your package. + +

+ +

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

 + + + + Libraries + +

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

+ +

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

+ +

+ 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'). 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 (e.g. dependency libraries for + static linking). Also, they're essential for + programs using libltdl. +

+ +

+ Certainly libtool is fully capable of linking against shared + libraries which don't have .la files, but being 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-1.4 (and to a + lesser extent libtool-1.3), the .la files will 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 + packages, with the exception that if the package relies on + libtool's libltdl library, in which case the .la + files must go in the run-time library package. This is a + good idea in general, and especially for static linking + issues. +

+ +

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

+ + + + + Shared libraries + +

+ 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: + librarynamesoname + (soname is the shared object name of the shared + library--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; usually the + soname is the major number of the library) and + librarynamesoname-dev.

+ +

+ If you prefer only to support one development version at a + time you may name the development package + libraryname-dev; otherwise you may + wish to use dpkg's conflicts mechanism to + ensure that the user only installs one development version + at a time (after all, different development versions are + likely to have the same header files in them, causing a + filename clash if both are 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.

+ +

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

+ +

+ You should follow the directions in the Debian Packaging + Manual (or other documentation of the Debian + packaging tools) for putting the shared library in its + package, and you must include a shlibs control area + file with details of the dependencies for packages which use + the library.

+ +

+ Shared libraries should not be installed + executable, since ld.so does not require this + and trying to execute a shared library results in a core + dump.

 + + + + Scripts + +

+ 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 + (including especially debian 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. +

+ + Thus, shell scripts + specifying `/bin/sh' as interpreter should only + use POSIX features. If a script requires non-POSIX + features from the shell interpreter, the appropriate shell + must be specified in the first line of the script (e.g., + `#!/bin/bash') and the package must depend on the + package providing the shell (unless the shell package is + marked `Essential', e.g., in the case of + bash). +

+ +

+ 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. It can be found on + , or + + or even on ftp.cpan.org + /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. + If an upstream package comes with csh scripts + then you must make sure that they start with + #!/bin/csh and make your package depend on the + c-shell virtual package.

+ +

+ 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 distribution provides the + tempfile and mktemp utilities + for use by scripts for this purpose.

 + + + + Symbolic links + +

+ 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, 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.')

 + + + + Device files + +

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

+ + + + Configuration files + + Definitions +

+ + configuration file +

+ A file that affects the operation of program, or + provides site- or host-specific information, or + otherwise customizes the behavior of program. + Typically, configuration files are intended to be + modified by the system administrator (if needed or + desired) to conform to local policy or provide more + useful site-specific behavior.

+ + + conffile +

+ A file listed in a package's conffiles + file, and is treated specially by dpkg + (see the Debian Packaging Manual).

+ + +

+ +

+ The distinction between these two is important; they are + not interchangeable concepts. Almost all + conffiles are configuration files, but many + configuration files are not conffiles.

+ +

+ Note that a script that embeds configuration information + (such as most of the files in /etc/init.d and + /etc/cron.{daily,weekly,monthly}) is de-facto a + configuration file and should be treated as such.

+ + + + Location +

+ Any configuration files created or used by your package + must reside in /etc. If there are several you + should consider creating a subdirectory of /etc + named after your package.

+ +

+ If your package creates or uses configuration files + outside of /etc, and it is not feasible to modify + the package to use the /etc, you should still put + the files in /etc and create symbolic links to + those files from the location that the package + requires.

+ + + + Behavior +

+ Configuration file handling must conform to the following + behavior: + + +

local changes must be preserved during a package + upgrade

+ + +

configuration files must be preserved when the + package is removed, and only deleted when the + package is purged.

+ +

+ +

+ The easy way to achieve this behavior is to make the + configuration file a conffile. This is + appropriate only if it is possible to distribute a default + version that will work for most installations, although + some system administrators may choose to modify it. This + implies that the default version will be part of the + package distribution, and must not be modified by the + maintainer scripts during installation (or at any other + time). +

+ +

+ In order to ensure that local changes are preserved + correctly, no package may contain or make hard links to + conffiles. + +

+ Rationale: There are two problems with hard links. + The first is that some editors break the link while + editing one of the files, so that the two files may + unwittingly become different. The second is that + dpkg might break the hard link while + upgrading conffiles. +

+ +

+ +

+ The other way to do it is via the maintainer scripts. + In this case, the configuration file must not be listed as + a conffile and must not be part of the package + distribution. If the existence of a file is required for + the package to be sensibly configured it is the + responsibility of the package maintainer to write scripts + which correctly create, update, maintain and + remove-on-purge the file. These scripts must be idempotent + (i.e., must work correctly if dpkg needs to + re-run them due to errors during installation or removal), + must cope with all the variety of ways dpkg + can call maintainer scripts, must not overwrite or + otherwise mangle the user's configuration without asking, + must not ask unnecessary questions (particularly during + upgrades), and otherwise be good citizens.

+ +

+ The scripts are not required to configure every possible option for + the package, but only those necessary to get the package + running on a given system. Ideally the sysadmin should not + have to do any configuration other than that done + (semi-)automatically by the postinst script.

+ +

+ A common practice is to create a script called + package-configure and have the + package's postinst call it if and only if the + configuration file does not already exist. In certain + cases it is useful for there to be an example or template + file which the maintainer scripts use. Such files should + be in /usr/share/<package> or + /usr/lib/<package> with a symbolic link + from /usr/share/doc/<package>/examples + if they are examples, and should be + perfectly ordinary dpkg-handled files + (not conffiles). +

+ +

+ These two styles of configuration file handling must + not be mixed, for that way lies madness: + dpkg will ask about overwriting the file + every time the package is upgraded.

+ + + + + Sharing configuration files +

+ Packages which specify the same file as + `conffile' must be tagged as conflicting + with each other. +

+ +

+ The maintainer scripts must not alter the conffile of + any package, including the one the scripts belong + to.

+ +

+ If two or more packages use the same configuration file + and it is reasonable for both to be installed at the same + time, one of these packages must be defined as + owner of the configuration file, i.e., it will be + the package to list that distributes the file and lists it + as a conffile. Other packages that use the + configuration file must depend on the owning package if + they require the configuration file to operate. If the + other package will use the configuration file if present, + but is capable of operating without it, no dependency need + be declared.

+ +

+ If it is desirable for two or more related packages to + share a configuration file and for all of the + related packages to be able to modify that configuration + file, then the following should be done: + + +

+ have one of the related packages (the "core" + package) manage the configuration file with + maintainer scripts as described in the previous + section.

+ +

+ the core package should also provide a program that + the other packages may use to modify the + configuration file.

+ + +

+ the related packages must use the provided program + to make any modifications to the configuration file. + They should either depend on the core package to + guarantee that the configuration modifier program is + available or accept gracefully that they cannot + modify the configuration file if it is not.

+ +

+ +

+ Sometimes it's appropriate to create a new package which + provides the basic infrastructure for the other packages + and which manages the shared configuration files. (Check + out the sgml-base package as an example.)

+ + + + User configuration files ("dotfiles") + +

+ Files in /etc/skel will automatically be copied + into new user accounts by adduser. They + should not be referenced there by any program.

+ +

+ Therefore, if a program needs a dotfile to exist in + advance in $HOME to work sensibly, that dotfile + should be installed in /etc/skel (and listed in + conffiles, if it is not generated and modified dynamically + by the package's installation scripts).

+ +

+ However, programs that require dotfiles in order to + operate sensibly (dotfiles that they do not create + themselves automatically, that is) are a bad thing, and + programs should be configured by the Debian default + installation as close to normal as possible.

+ +

+ Therefore, if a program in a Debian package needs to be + configured in some way in order to operate sensibly that + configuration should be done in a site-wide global + configuration file elsewhere in /etc. Only if the + program doesn't support a site-wide default configuration + and the package maintainer doesn't have time to add it + may a default per-user file be placed in + /etc/skel.

+ +

+ /etc/skel should be as empty as we can make it. + This is particularly true because there is no easy + mechanism for ensuring that the appropriate dotfiles are + copied into the accounts of existing users when a package + is installed.

+ + + + + Log files +

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

+ +

+ A better scheme is to use logrotate, a GPL'd program + developed by Red Hat, which centralizes log management. It + has both a configuration file (/etc/logrotate.conf) + and a directory where packages can drop logrotation info + (/etc/logrotate.d). +

+ +

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

+ +

+ Log files must be rotated occasionally so + that they don't grow indefinitely; the best way to do this + is to drop a script into the directory + /etc/logrotate.d and use the facilities provided by + logrotate. Here is a good example for a logrotate config + file (for more information see ): + +/var/log/foo/* { +rotate 12 +weekly +compress +postrotate +/etc/init.d/foo force-reload +endscript +} + + Which rotates all files under `/var/log/foo', saves 12 + compressed generations, and sends a HUP signal at the end of + rotation. + +

+ +

+ Log files should be removed when the package is + purged (but not when it is only removed), by checking the + argument to the postrm script (see the Debian + Packaging Manual for details).

+ + + + + Permissions and owners + +

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

+ +

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

+ +

+ You must not arrange that the system administrator can only + reconfigure the package to correspond to their local + security policy by changing the permissions on a binary. + Ordinary files installed by dpkg (as opposed + to conffiles and other similar objects) have their + permissions reset to the distributed permissions when the + package is reinstalled. Instead you should consider (for + example) creating a group for people allowed to use the + program(s) and making any setuid executables executable + only by that group.

+ +

+ 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 system + maintainer, and must not release the package until you + have been allocated one. Once you have been allocated one + you must make the package depend on a version of the base + system with the id present in /etc/passwd or + /etc/group, or alternatively arrange for your + package to create the user or group itself with the + correct id (using adduser) in its pre- or + post-installation script (the latter is to be preferred if + it is possible).

+ +

+ On the other hand, the program might be able to determine the + uid or gid from the group name at runtime, so that a + dynamic 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 pre- or post-installation + 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.

+ + + + + Customized programs + + + 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.

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

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

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

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

+ +

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

+ +

+ + +

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

+ + +

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 for + backward compatibility, see + and can be referred to as + +http://localhost/doc/<package>/<filename> + +

+ + +

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.

+ + +

+ + + + 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/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 (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 +

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

+ . Using the functions maillock and + mailunlock provided by the + liblockfile* +

+ liblockfile version >>1.01

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

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

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

+ This implements current practice, and provides an actual + policy for usage of the "xserver" virtual package which + appears in the virtual packages list. In a nutshell, X + servers that interface directly with the display and input + hardware or via another subsystem (e.g., GGI) should provide + xserver. Things like Xvfb, Xnest, and Xprt should not. +

+ +

+ +

+ 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: + + Start with a priority of 20. + If the window manager supports the Debian menu system, + add 20 points if this support is available in the + package's default configuration (i.e., no + configuration files belonging to the system or user + have to be edited to activate the feature); if + configuration files must be modified, add only 10 + points. + If the window manager permits the X session to be + restarted using a different window manager + (without killing the X server) in its default + configuration, add 10 points; otherwise add + none. + +

+ +

+ 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. + + + 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. + + + 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: + + + 100 dpi fonts should be placed in + /usr/X11R6/lib/X11/fonts/100dpi/. + + + 75 dpi fonts should be placed in + /usr/X11R6/lib/X11/fonts/75dpi/. + + + Character-cell fonts, cursor fonts, and other + low-resolution fonts should be placed in + /usr/X11R6/lib/X11/fonts/misc/. + + + + + Speedo fonts should be placed in + /usr/X11R6/lib/X11/fonts/Speedo/. + + + 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. + + + 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.) + + + 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. + + + 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. + + + 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. + + + Font packages must not provide the files + fonts.dir, fonts.alias, or + fonts.scale in a font directory. + + + fonts.dir files must not be provided at + all. + + + fonts.alias and fonts.scale + files, if needed, should be provided in the + directory + /etc/X11/fonts/fontdir/package.extension, + where fontdir is the name of the + subdirectory of + /usr/X11R6/lib/X11/fonts/ where the + package's corresponding fonts are stored (e.g., + 75dpi or misc), + package is the name of the package that + provides these fonts, and extension is + either scale or alias, + whichever corresponds to the file + contents. + + + + + 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. + + + 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. + + + 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. + + + Font packages must not provide alias names for the + fonts they include which collide with alias names already in + use by fonts already packaged. + + + 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 /etc/X11/app-defaults/ (use of a + localized subdirectory of /etc/X11/ as described in + the X Toolkit Intrinsics - C Language Interface + manual is also permitted). They must be registered as + conffiles or handled as configuration files. For + programs that are not linked against the X Toolkit (Xt) + library, customization of programs' X resources may also be + supported with the provision of a file with the same name as + that of the package placed in the + /etc/X11/Xresources/ directory, which must + registered as a conffile or handled as a + configuration file. 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. +

+ +

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

+ + + + Perl programs and modules +

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

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

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

+ + + + Documentation + + + + Manual pages + +

+ 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 on + debian-bugs, 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]/the_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).

 + + + + Info documents + +

+ 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 post-installation script: + +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 pre-removal script: + +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.

+ + + + Additional documentation + +

+ Any additional documentation that comes with the package may + be installed at the discretion of the package maintainer. + Text documentation should be installed in a 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>/ and symlinked in + /usr/share/doc/<package>/. +

+ + + + + Accessing the documentation + +

+ 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: + +if [ "$1" = "configure" ]; then + if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \ + -a -d /usr/share/doc/#PACKAGE# ]; then + ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE# + fi +fi + + And the following in the package's prerm: + +if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ + -a -L /usr/doc/#PACKAGE# ]; then + rm -f /usr/doc/#PACKAGE# +fi + +

+ + + + Preferred documentation formats + +

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

+ +

+ If your package comes with extensive documentation in a + mark up 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, though.

+ +

+ +

+ Other formats such as PostScript may be provided at your + option.

+ + + + Copyright information + +

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

+ + +

+ /usr/share/doc/<package> may be a symbolic link to a + directory in /usr/share/doc only if two packages both come from + the same source and the first package has a "Depends" + relationship 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. + +

+ Why "licenses" and not "copyright"? Because + /usr/doc/copyright used to contain all the + copyright files, plus the four common licenses GPL, + LGPL, Artistic and BSD. Now individual copyright files + for packages are no longer in a common directory. Once + /usr/doc/copyright is almost empty it makes + sense to rename "copyright" to "licenses" +

+

+ Why "common-licenses" and not "licenses"? Because if I + put just "licenses" I'm sure I will receive a bug report + saying "license foo is not included in the licenses + directory. They are not all the licenses, just a few + common ones. I could use /usr/share/doc/common-licenses + but I think this is too long, and, after all, the GPL + does not "document" anything, it is merely a license. +

+ +

+ +

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

+ + + + Examples + +

+ 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, and files in + /usr/share/doc/package/examples symlink + to files in it. Or the latter directory may be a symlink to + the former.

+ + + + Changelog files + +

+ Packages that are not Debian-native must contain a copy of + debian/changelog file from the Debian source tree + in /usr/share/doc/package as + 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 the changelog.gz should be generated using, eg, + 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 adding a + symbolic link, at the maintainer's discretion. + +

+ Rationale: People should not have to look into two + places for upstream changelogs merely because they are + in HTML format. +

+ +

+ + +

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

+ + + +