+ <!--
+ 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 packagingn adminstrivia only.
+ -->
+
+ <book>
+ <titlepag>
+ <title>Debian Policy Manual</title>
+ <author>
+ <name>Ian Jackson </name>
+ <email>ijackson@gnu.ai.mit.edu</email>
+ </author>
+ <author>
+ <name>Christian Schwarz</name>
+ <email>schwarz@debian.org</email>
+ </author>
+ <author>
+ <name>revised: David A. Morris</name>
+ <email>bweaver@debian.org</email></author>
+ <author><name></name><email></email></author>
+ <version>version &version;, &date;</version>
+
+ <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>
+ <copyrightsummary>
+ Copyright ©1996,1997,1998 Ian Jackson
+ and Christian Schwarz.
+ </copyrightsummary>
+ <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>
+
+ <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>
+ <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"
+ name="&urlname">. You can also obtain it by writing to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect">
+
+ <chapt id="scope">
+ <heading>About this manual</heading>
+ <sect>
+ <heading>Scope</heading>
+ <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>
+ <p>
+ This manual does <em>not</em> 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>
+ <p>
+ This document assumes familiarity with these other two
+ manuals. Unfortunately, the <em>System Administrators'
+ Manual</em> does not exist yet.
+ </p>
+ <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>
+ <sect>
+ <heading>New versions of this document</heading>
+ <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" name="&urlname">
+ or from the Debian WWW server at
+ <url id="http://www.debian.org/doc/manuals/debian-policy/"
+ name="&urlname"></p>
+
+ <p>
+ In addition, this manual is distributed via the Debian package
+ <tt>debian-policy</tt>
+ </p>
+ </sect>
+ <sect>
+ <heading>Feedback</heading>
+
+ <p>
+ As the Debian GNU/Linux system is continuously evolving this
+ manual is changed from time to time.
+ </p>
+ <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 List,
+ <email>debian-policy@lists.debian.org</email>, or submit a
+ bug report against the <tt>debian-policy</tt> package.
+ </p>
+ </sect>
+ </chapt>
+ <chapt>
+ <heading>The Debian Archive</heading>
+ <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
+ 2600) they are split into <em>sections</em> and <em>priorities</em> to
+ simplify handling of them.
+ </p>
+ <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>, <em>non-us</em>, <em>non-free</em>, and
+ <em>contrib</em>.</p>
+ <p>
+ The <em>main</em> section forms the <em>Debian GNU/Linux
+ distribution</em>. </p>
+ <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">
+ <heading>Package copyright and sections</heading>
+ <p>
+ The aims of this policy are:
+
+ <list compact="compact">
+ <item>
+ <p>We want to make as much software available as we
+ can.</p>
+ </item>
+ <item>
+ <p>We want to encourage everyone to write free software.</p>
+ </item>
+ <item>
+ <p> 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>
+ </item>
+ </list>
+ </p>
+ <sect1>
+ <heading>The Debian Free Software Guidelines</heading>
+ <p>
+ The Debian Free Software Guidelines (DFSG) as is our
+ definition of `free' software.
+ <taglist>
+ <tag>>Free Redistribution
+ </tag>
+ <item>
+ <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>
+ <tag>Source Code
+ </tag>
+ <item>
+ <p>
+ The program must include source code, and must allow
+ distribution in source code as well as compiled form.
+ </p>
+ </item>
+ <tag>Derived Works
+ </tag>
+ <item>
+ <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>
+ <tag>Integrity of The Author's Source Code
+ </tag>
+ <item>
+ <p>
+ The license may restrict source-code from being
+ distributed in modified form <em>only</em> 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>
+ <tag>No Discrimination Against Persons or Groups
+ </tag>
+ <item>
+ <p>
+ The license must not discriminate against any person
+ or group of persons.
+ </p>
+ </item>
+ <tag>No Discrimination Against Fields of Endeavor
+ </tag>
+ <item>
+ <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>
+ <tag>Distribution of License
+ </tag>
+ <item>
+ <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>
+ <tag>License Must Not Be Specific to Debian
+ </tag>
+ <item>
+ <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>
+ <tag>License Must Not Contaminate Other Software
+ </tag>
+ <item>
+ <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>
+ <tag>Example Licenses
+ </tag>
+ <item>
+ <p>
+ The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
+ examples of licenses that we consider <em>free</em>.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The main section</heading>
+ <p>
+ Every package in "main" must comply with the DFSG (Debian
+ Free Software Guidelines).</p>
+
+ <p>
+ In addition, the packages in "main"
+ <list compact="compact">
+ <item>
+ <p>
+ 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>
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The contrib section</heading>
+ <p>
+ Every package in "contrib" must comply with the DFSG.
+ </p>
+
+ <p>
+ Examples of packages which would be included in "contrib" are
+ <list compact="compact">
+ <item>
+ <p>
+ 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>
+ <item>
+ <p>
+ wrapper packages or other sorts of free accessories for
+ non-free programs,
+ </p>
+ </item>
+ <item>
+ <p>
+ packages which we don't want to support because they are too
+ buggy, and
+ </p>
+ </item>
+ <item>
+ <p>
+ packages which fail to meet some other policy requirements in
+ a serious way.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The non-free section</heading>
+ <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>
+ <p>
+ All packages in `non-free' must be electronically
+ distributable across international borders.
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The non-us server</heading>
+ <p>
+ Some programs with cryptographic program code must be stored
+ on the "non-us" server because of export restrictions of the
+ U.S.</p>
+ <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>
+ <sect1>
+ <heading>Further copyright considerations</heading>
+ <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>
+ <p>
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
+ <list compact="compact">
+ <item>
+ <p>
+ their use or distribution would break a law,
+ </p>
+ </item>
+ <item>
+ <p>
+ there is an ethical conflict in their distribution or
+ use,
+ </p>
+ </item>
+ <item>
+ <p>
+ we would have to sign a license for them, or
+ </p>
+ </item>
+ <item>
+ <p>
+ their distribution would conflict with other project
+ policies.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <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>
+
+ <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>
+
+ <p>
+ Note, that under international copyright law (this applies
+ in the United States, too) <em>no</em> distribution or
+ modification of a work is allowed without an explicit notice
+ saying so. Therefore a program without a copyright notice
+ <em>is</em> 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>
+
+ <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</tt> first.</p>
+
+ <p>
+ When in doubt, send mail to
+ <email>debian-devel@lists.debian.org</email>. 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>
+ <sect1>
+ <heading>Subsections</heading>
+
+ <p>
+ The packages in the <em>main</em>, <em>contrib</em>, and
+ <em>non-free</em> sections are grouped further into
+ <em>subsections</em> to simplify handling of them.</p>
+
+ <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>
+
+ <p>
+ Please check the current Debian distribution to see which
+ sections are available.</p>
+ </sect1>
+ <sect>
+ <heading>Priorities</heading>
+
+ <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>
+
+ <p>
+ The following <em>priority levels</em> are supported by the
+ Debian package management system, <prgn>dpkg</prgn>.
+ <taglist>
+ <tag><tt>required</tt></tag>
+ <item>
+ <p>
+ <tt>required</tt> 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</prgn> to put things back. Systems with
+ only the <tt>required</tt> packages are probably
+ unusable, but they do have enough functionality to
+ allow the sysadmin to boot and install more
+ software.</p>
+ </item>
+ <tag><tt>important</tt></tag>
+ <item>
+ <p>
+ 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</prgn>', it should be in
+ <tt>important</tt>. 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</em> include Emacs or X11 or
+ TeX or any other large applications. The
+ <tt>important</tt> packages are just a bare minimum of
+ commonly-expected and necessary tools.</p>
+ </item>
+ <tag><tt>standard</tt></tag>
+ <item>
+ <p>
+ 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).</p>
+ </item>
+ <tag><tt>optional</tt></tag>
+ <item>
+ <p>
+ (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.</p>
+ </item>
+ <tag><tt>extra</tt></tag>
+ <item>
+ <p>
+ 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.
+ </p>
+ </item>
+ </taglist></p>
+
+ <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>
+
+ <sect>
+ <heading>Binary packages</heading>
+
+ <p>
+ The Debian GNU/Linux distribution is based on the Debian
+ package management system, called <prgn>dpkg</prgn>. Thus,
+ all packages in the Debian distribution have to be provided
+ in the <tt>.deb</tt> file format.</p>
+
+
+ <sect1>
+ <heading>The package name</heading>
+
+ <p>
+ Every package must have a name that's unique within the Debian
+ archive.</p>
+
+ <p>
+ Package names may only consist of lower case letters, digits (0-9),
+ plus (+) or minus (-) signs, and periods (.).</p>
+
+ <p>
+ The package name is part of the file name of the
+ <tt>.deb</tt> file and is included in the control field
+ information.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The maintainer of a package</heading>
+
+ <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>
+
+ <p>
+ The maintainer must be specified in the
+ <tt>Maintainer</tt> 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</tt>
+ fields.</p>
+
+ <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>
+
+
+ <sect1>
+ <heading>The description of a package</heading>
+
+ <p>
+ Every Debian package should have an extended description
+ stored in the appropriate field of the control record.</p>
+
+ <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>
+
+
+ <sect1>
+ <heading>Dependencies</heading>
+
+ <p>
+ Every package has to specify the dependency information
+ about other packages, that are required for the first to
+ work correctly.</p>
+
+ <p>
+ For example, for any shared libraries required by
+ dynamically-linked executable binary in a package a
+ dependency entry has to be provided.</p>
+
+ <p>
+ It is not necessary for other packages to declare any
+ dependencies they have on other packages which are marked
+ <tt>Essential</tt> (see below).</p>
+
+ <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</tt> entry for the package.</p>
+
+ <p>
+ You must not specify a <tt>Pre-Depends</tt> entry for a
+ package before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.</p></sect1>
+
+
+ <sect1>
+ <heading>Virtual packages</heading>
+
+ <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>
+
+ <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>
+
+ <p>
+ The latest version of the authoritative list of virtual
+ package names can be found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
+ 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>
+
+
+ <sect1>
+ <heading>Base packages</heading>
+
+ <p>
+ The packages included in the <tt>base</tt> 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</tt> section to keep the required
+ disk usage very small.</p>
+
+ <p>
+ Most of these packages should have the priority value
+ <tt>required</tt> or at least <tt>important</tt>, and many
+ of them will be tagged <tt>essential</tt> (see below).</p>
+
+ <p>
+ You must not place any packages into the <tt>base</tt>
+ section before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.</p></sect1>
+
+
+ <sect1>
+ <heading>Essential packages</heading>
+
+ <p>
+ Some packages are tagged <tt>essential</tt>. (They have
+ <tt>Essential: yes</tt> in their package control record.)
+ This flag is used for packages that are <em>essential</em>
+ for a system.</p>
+
+ <p>
+ Since these packages can not easily be removed (you'll
+ have to specify an extra <em>force option</em> to
+ <prgn>dpkg</prgn>) 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>
+
+ <p>
+ You must not tag any packages <tt>essential</tt> before
+ this has been discussed on the <tt>debian-devel</tt>
+ mailing and a consensus about doing that has been
+ reached.</p></sect1>
+
+
+ <sect1>
+ <heading>Maintainer scripts</heading>
+
+ <p>
+ The package installation scripts should avoid producing
+ output which it is unnecessary for the user to see and
+ should rely on <prgn>dpkg</prgn> to stave off boredom on
+ the part of a user installing many packages. This means,
+ amongst other things, using the <tt>--quiet</tt> option on
+ <prgn>install-info</prgn>.</p>
+
+ <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</tt> and
+ <tt>/etc/nntpserver</tt>), rather than each prompting for
+ their own list of required pieces of information.</p>
+
+ <p>
+ It also means that an upgrade should not ask the same
+ questions again, unless the user has used <tt>dpkg
+ --purge</tt> to remove the package's configuration. The
+ answers to configuration questions should be stored in an
+ appropriate place in <tt>/etc</tt> so that the user can
+ modify them, and how this has been done should be
+ documented.</p>
+
+ <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</prgn> 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/<var>package</var>/copyright</tt>); neither
+ do instructions on how to use a program (these should be
+ in on line documentation, where all the users can see
+ them).</p>
+
+ <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</prgn> is called with
+ <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
+ <tt>abort-deconfigure</tt>.</p>
+
+ <p>
+ Errors which occur during the execution of an installation
+ script <em>must</em> be checked and the installation
+ <em>must not</em> continue after an error.</p>
+
+ <p>
+ Note, that <ref id="scripts">, in general applies to
+ package maintainer scripts, too.</p>
+
+ <p>
+ Do not use <prgn>dpkg-divert</prgn> on a file belonging to
+ another package without consulting the maintainer of that
+ package first.</p>
+
+ <p>
+ In order for <prgn>update-alternatives</prgn> 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</tt> to force the
+ deinstallation of other packages supplying it which do not
+ (yet) use <prgn>update-alternatives</prgn>. 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>
+ </sect1>
+ </sect>
+ <sect>
+ <heading>Source packages</heading>
+
+ <sect1>
+ <heading>Standards conformance</heading>
+
+ <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</tt> field.</p>
+
+ <p>
+ This value will be used to file bug reports automatically
+ if your package becomes too much out of date.</p>
+
+ <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>
+
+ <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>
+
+ <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</tt> source package field and
+ release it.</p></sect1>
+
+
+ <sect1>
+ <heading>Changes to the upstream sources</heading>
+
+ <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>
+
+ <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</prgn> test or <tt>#define</tt>) 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>
+
+ <p>
+ Please make sure that the <prgn>configure</prgn> utility
+ detects the correct architecture specification string
+ (refer to <ref id="arch-spec"> for details).</p>
+
+ <p>
+ If you need to edit a <prgn>Makefile</prgn> where
+ GNU-style <prgn>configure</prgn> scripts are used, you
+ should edit the <tt>.in</tt> files rather than editing the
+ <prgn>Makefile</prgn> directly. This allows the user to
+ reconfigure the package if necessary. You should
+ <em>not</em> configure the package and edit the generated
+ <prgn>Makefile</prgn>! This makes it impossible for
+ someone else to later reconfigure the package.</p></sect1>
+
+
+ <sect1>
+ <heading>Documenting your changes</heading>
+
+ <p>
+ Document your changes and updates to the source package
+ properly in the <tt>debian/changelog</tt> file.</p>
+
+ <p>
+ A copy of the file which will be installed in
+ <tt>/usr/doc/<var>package</var>/copyright</tt> should be
+ in <tt>debian/copyright</tt>.</p>
+
+ <p>
+ In non-experimental packages you may only use a format for
+ <tt>debian/changelog</tt> which is supported by the most
+ recent released version of <prgn>dpkg</prgn>. If your
+ format is not supported and there is general support for
+ it you should contact the <prgn>dpkg</prgn> maintainer to
+ have the parser script for your format included in the
+ <prgn>dpkg</prgn> 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</prgn>
+ is.)</p></sect1>
+
+
+ <sect1>
+ <heading>Error trapping in makefiles</heading>
+
+ <p>
+ When <prgn>make</prgn> invokes a command in a makefile
+ (including your package's upstream makefiles and the
+ <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
+ means that <tt>sh</tt>'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</prgn> will blithely continue after
+ problems.</p>
+
+ <p>
+ Every time you put more than one shell command (this
+ includes using a loop) in a makefile command you
+ <em>must</em> make sure that errors are trapped. For
+ simple compound commands, such as changing directory and
+ then running a program, using <tt>&&</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</tt>
+ command at the start of every makefile command that's
+ actually one of these miniature shell scripts.</p></sect1>
+
+
+ <sect1>
+ <heading>Obsolete constructs and libraries</heading>
+
+ <p>
+ The include file <prgn><varargs.h></prgn> is
+ provided to support end-users compiling very old software;
+ the library <tt>libtermcap</tt> 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>
+
+ <p>
+ Debian packages should be ported to include
+ <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
+ they are built.</p>
+ </sect1>
+ </sect></chapt>
+
+ <chapt><heading>The Operating System</heading>
+
+
+ <sect>
+ <heading>Filesystem hierarchy</heading>
+
+
+ <sect1>
+ <heading>Linux Filesystem Structure</heading>
+
+ <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</ftpsite> in
+ <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
+ Specific questions about following the standard may be
+ asked on <prgn>debian-devel</prgn>, or referred to Daniel
+ Quinlan, the FSSTND coordinator, at
+ <email>quinlan@pathname.com</email>.</p></sect1>
+
+
+ <sect1>
+ <heading>Site-specific programs</heading>
+
+ <p>
+ As mandated by the FSSTND no package should place any
+ files in <tt>/usr/local</tt>, either by putting them in
+ the filesystem archive to be unpacked by <prgn>dpkg</prgn>
+ or by manipulating them in their maintainer scripts.</p>
+
+ <p>
+ However, the package should create empty directories below
+ <tt>/usr/local</tt> 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>
+
+ <p>
+ Note, that this applies only to directories <em>below</em>
+ <tt>/usr/local</tt>, not <em>in</em>
+ <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
+ 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>
+
+ <p>
+ Since <tt>/usr/local</tt> may be mounted read-only from a
+ remote server, these directories have to be created and
+ removed by the <tt>postinst</tt> and <tt>prerm</tt>
+ maintainer scripts. These scripts must not fail if either
+ of these operations fail. (In the future, it will be
+ possible to tell <prgn>dpkg</prgn> not to unpack files
+ matching certain patterns, so that the directories can be
+ included in the <tt>.deb</tt> packages and system
+ administrators who do not wish these directories in
+ /usr/local do not need to have them.)</p>
+
+ <p>
+ For example, the <prgn>emacs</prgn> package will contain
+ <example>
+ mkdir -p /usr/local/lib/emacs/site-lisp || true
+ </example>
+ in the <tt>postinst</tt> script, and
+ <example>
+ rmdir /usr/local/lib/emacs/site-lisp && \
+ rmdir /usr/local/lib/emacs || \
+ true
+ </example>
+ in the <tt>prerm</tt> script.</p>
+
+ <p>
+ If you do create a directory in <tt>/usr/local</tt> 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>
+
+ <p>
+ The <tt>/usr/local</tt> 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</tt>.</p>
+ </sect1>
+ </sect>
+
+ <sect>
+ <heading>Users and groups</heading>
+
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.</p>
+
+ <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>
+
+ <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>
+
+ <p>
+ No package except <tt>base-passwd</tt> may modify
+ <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
+ <tt>/etc/group</tt>.</p>
+
+ <p>
+ The UID and GID ranges are as follows:
+ <taglist>
+ <tag>0-99:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, must be the
+ same on every Debian system. These ids will appear in
+ the <tt>passwd</tt> and <tt>group</tt> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.</p>
+
+ <p>
+ Packages which need a single statically allocated uid
+ or gid should use one of these; their maintainers
+ should ask the <tt>base-passwd</tt> maintainer for
+ ids.</p>
+ </item>
+
+ <tag>100-999:</tag>
+ <item>
+ <p>
+ 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</tt>' to
+ create the group and/or user. <prgn>adduser</prgn>
+ 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</tt>.</p></item>
+
+
+ <tag>1000-29999:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By default
+ <prgn>adduser</prgn> will choose UIDs and GIDs for
+ user accounts in this range, though
+ <tt>adduser.conf</tt> may be used to modify this
+ behaviour.</p>
+ </item>
+
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p></item>
+
+
+ <tag>60000-64999:</tag>
+ <item>
+ <p>
+ 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>
+
+ <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</tt> or <tt>/etc/group</tt> (using
+ <prgn>adduser</prgn> 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></item>
+
+
+ <tag>65000-65533:</tag>
+ <item>
+ <p>Reserved.</p></item>
+
+
+ <tag>65534:</tag>
+ <item>
+ <p>User `<tt>nobody</tt>.'</p></item>
+
+
+ <tag>65535:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
+ because it is the error return sentinel value.</p>
+ </item>
+ </taglist>
+ </p>
+ </sect>
+ <sect id="sysvinit">
+ <heading>System run levels</heading>
+
+
+ <sect1>
+ <heading>Introduction</heading>
+
+ <p>
+ The <tt>/etc/init.d</tt> directory contains the scripts
+ executed by <prgn>init</prgn> at boot time and when init
+ state (or `runlevel') is changed (see <manref name="init"
+ section="8">).</p> <p>
+
+ These scripts are being referenced by symbolic links in
+ the <tt>/etc/rc<var>n</var>.d</tt> directories. When
+ changing runlevels, <prgn>init</prgn> looks in the
+ directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
+ it should execute, where <var>n</var> is the runlevel that
+ is being changed to, or `S' for the boot-up scripts.</p>
+ <p>
+
+ The names of the links all have the form
+ <tt>S<var>mm/<var>script</var></var></tt> or
+ <tt>K<var>mm/<var>script</var></var></tt> where
+ <var>mm</var> is a two-digit number and <var>script</var>
+ is the name of the script (this should be the same as the
+ name of the actual script in <tt>/etc/init.d</tt>.
+
+ When <prgn>init</prgn> changes runlevel first the targets
+ of the links whose names starting with a <tt>K</tt> are
+ executed, each with the single argument <tt>stop</tt>,
+ followed by the scripts prefixed with an <tt>S</tt>, each
+ with the single argument <tt>start</tt>. The <tt>K</tt>
+ links are responsible for killing services and the
+ <tt>S</tt> link for starting services upon entering the
+ runlevel.</p>
+
+ <p>
+ For example, if we are changing from runlevel 2 to
+ runlevel 3, init will first execute all of the <tt>K</tt>
+ prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
+ all of the <tt>S</tt> prefixed scripts. The links
+ starting with <tt>K</tt> will cause the referred-to file
+ to be executed with an argument of <tt>stop</tt>, and the
+ <tt>S</tt> links with an argument of <tt>start</tt>.</p>
+
+ <p>
+ The two-digit number <var>mm</var> 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</tt>
+ scripts will be executed before the <tt>K30</tt> scripts.
+ This is used when a certain service must be started before
+ another. For example, the name server <prgn>bind</prgn>
+ might need to be started before the news server
+ <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
+ access lists. In this case, the script that starts
+ <prgn>bind</prgn> should have a lower number than the
+ script that starts <prgn>inn</prgn> so that it runs first:
+ <example>
+ /etc/rc2.d/S17bind
+ /etc/rc2.d/S70inn
+ </example>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Writing the scripts</heading>
+
+ <p>
+ Packages can and should place scripts in
+ <tt>/etc/init.d</tt> 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</var></tt>, and they
+ should accept one argument, saying what to do:
+
+ <taglist>
+ <tag><tt>start</tt></tag>
+ <item><p>start the service,</p></item>
+
+ <tag><tt>stop</tt></tag>
+ <item><p>stop the service,</p></item>
+
+ <tag><tt>restart</tt></tag>
+ <item><p>stop and restart the service,</p></item>
+
+ <tag><tt>reload</tt></tag>
+ <item><p>cause the configuration of the service to be
+ reloaded without actually stopping and restarting
+ the service,</p></item>
+
+ <tag><tt>force-reload</tt></tag> <item><p>cause the
+ configuration to be reloaded if the service supports
+ this, otherwise restart the service.</p></item>
+ </taglist>
+
+ The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
+ <tt>force-reload</tt> options must be supported by all
+ scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
+ option is optional.</p>
+
+ <p>
+ The <tt>init.d</tt> scripts should ensure that they will
+ behave sensibly if invoked with <tt>start</tt> when the
+ service is already running, or with <tt>stop</tt> 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</prgn>.</p>
+
+ <p>
+ If a service reloads its configuration automatically (as
+ in the case of <prgn>cron</prgn>, for example), the
+ <tt>reload</tt> option of the <tt>init.d</tt> script
+ should behave as if the configuration has been reloaded
+ successfully.</p>
+
+ <p>
+ These scripts should not fail obscurely when the
+ configuration files remain but the package has been
+ removed, as the default in <prgn>dpkg</prgn> is to leave
+ configuration files on the system after the package has
+ been removed. Only when it is executed with the
+ <tt>--purge</tt> option will dpkg remove configuration
+ files. Therefore, you should include a <tt>test</tt>
+ statement at the top of the script, like this:
+ <example>
+ test -f <var>program-executed-later-in-script</var> || exit 0
+ </example></p></sect1>
+
+ <sect1>
+ <heading>Managing the links</heading>
+
+ <p>
+ A program is provided, <prgn>update-rc.d</prgn>, to make
+ it easier for package maintainers to arrange for the
+ proper creation and removal of
+ <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
+ <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
+
+ <p>
+ You should use this script to make changes to
+ <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
+ any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
+ actual archive.</p>
+
+ <p>
+ By default <prgn>update-rc.d</prgn> 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</var>.d</tt>.</p>
+
+ <p>
+ To get the default behaviour for your package, put in your
+ <tt>postinst</tt> script
+ <example>
+ update-rc.d <var>package</var> default >/dev/null
+ </example>
+ and in your <tt>postrm</tt>
+ <example>
+ if [ purge = "$1" ]; then
+ update-rc.d <var>package</var> remove >/dev/null
+ fi
+ </example></p>
+
+ <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</prgn> package or post to
+ <tt>debian-devel</tt>, and they will help you choose a
+ number.</p>
+
+ <p>
+ For more information about using <tt>update-rc.d</tt>,
+ please consult its manpage <manref name="update-rc.d"
+ section="8">.</p></sect1>
+
+
+ <sect1>
+ <heading>Boot-time initialisation</heading>
+
+ <p>
+ There is another directory, <tt>/etc/rc.boot</tt>, 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>
+
+ <p>
+ For example, the <prgn>kbd</prgn> package provides a
+ script here for initialising the keyboard layout and
+ console font and mode.</p>
+
+ <p>
+ The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
+ links into <tt>/etc/init.d</tt>--they should be the
+ scripts themselves.</p>
+
+ <p>
+ <tt>rc.boot</tt> should <em>not</em> be used for starting
+ general-purpose daemons and similar activities. This
+ should be done using the <tt>rc<var>n</var>.d</tt> 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>
+
+
+ <sect1>
+ <heading>Notes</heading>
+
+ <p>
+ <em>Do not</em> include the
+ <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
+ <tt>.deb</tt> filesystem archive! <em>This will cause
+ problems!</em> You should create them with
+ <prgn>update-rc.d</prgn>, as above.</p>
+
+ <p>
+ <em>Do not</em> include the <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
+ <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
+ problems!</em> <em>Do</em>,
+ however, include the <tt>/etc/init.d</tt> 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>
+
+ <sect1>
+ <heading>Example</heading>
+
+ <p>
+ The <prgn>bind</prgn> 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</tt>, naming the script
+ appropriately <tt>bind</tt>. As you can see, the script
+ interprets the argument <tt>reload</tt> to send the
+ nameserver a <tt>HUP</tt> signal (causing it to reload its
+ configuration); this way the user can say
+ <tt>/etc/init.d/bind reload</tt> to reload the name
+ server.</p>
+
+ <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>
+
+ <p>
+ Another example on which to base your <tt>/etc/init.d</tt>
+ scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
+
+ <p>
+ If this package is happy with the default setup from
+ <prgn>update-rc.d</prgn>, namely an ordering number of 20
+ and having named running in all runlevels, it can say in
+ its <tt>postinst</tt>:
+ <example>
+ update-rc.d bind default >/dev/null
+ </example>
+ And in its <tt>postrm</tt>, to remove the links when the
+ package is purged:
+ <example>
+ if [ purge = "$1" ]; then
+ update-rc.d acct remove >/dev/null
+ fi
+ </example></p>
+ </sect1></sect>
+
+ <sect>
+ <heading>Cron jobs</heading>
+
+ <p>
+ Packages may not touch the configuration file
+ <tt>/etc/crontab</tt>, nor may they modify the files in
+ <tt>/var/spool/cron/crontabs</tt>.</p>
+
+ <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>
+
+ <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</prgn>
+ automatically. (Note, that scripts in the
+ <tt>/etc/cron.d</tt> directory are not handled by
+ <prgn>anacron</prgn>. Thus, you should only use this
+ directory for jobs which may be skipped if the system is not
+ running.)</p>
+
+ <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>
+
+ <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>
+
+
+ <sect>
+ <heading>Console messages</heading>
+
+ <p>
+ This section describes different formats for messages
+ written to standard output by the <tt>/etc/init.d</tt>
+ scripts. The intent is to improve the consistency of
+ Debian's startup and shutdown look and feel.</p>
+
+ <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>
+
+ <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>
+
+ <p>
+ <list>
+ <item>
+ <p>
+ Every message should cover one line, start with a
+ capital letter and end with a period `.'.</p></item>
+
+
+ <item>
+ <p>
+ 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>
+
+
+ <item>
+ <p>
+ 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></p></item>
+ </list></p>
+
+ <p>
+ The following formats must be used</p>
+
+ <p>
+ <list>
+ <item>
+ <p>when daemons get started.</p>
+
+ <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>
+
+ <p>
+ For example, the output of /etc/init.d/lpd would look like:
+ <example>
+ Starting printer spooler: lpd.
+ </example></p>
+
+ <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>
+
+
+ <item>
+ <p>when something needs to be configured.</p>
+
+ <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>
+
+ <p>
+ You can use the following echo statement to get the quotes right:
+ <example>
+ echo "Setting DNS domainname to \`"value"'."
+ </example></p>
+
+ <p>
+ Note that the left quotation mark (`) is different
+ from the right (').</p></item>
+
+ <item>
+ <p>when a daemon is stopped.</p>
+
+ <p>
+ When you stop a daemon you should issue a message
+ similar to the startup message, except that `Starting'
+ is replaced with `Stopping'.</p>
+
+ <p>
+ So stopping the printer daemon will like like this:
+ <example>
+ Stopping printer spooler: lpd.
+ </example></p></item>
+
+ <item>
+ <p>when something is executed.</p>
+
+ <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.</p></item>
+
+ <item>
+ <p>when the configuration is reloaded.</p>
+
+ <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></p></item>
+
+ <item>
+ <p>when none of the above rules apply.</p>
+
+ <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.</p></item>
+ </list></p></sect>
+
+
+ <sect>
+ <heading>Menus</heading>
+
+ <p>
+ The Debian <tt>menu</tt> packages provides a unique
+ interface between packages providing applications and
+ documents, and <em>menu programs</em> (either X window
+ managers or text-based menu programs as
+ <prgn>pdmenu</prgn>).</p>
+
+ <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</tt> package
+ will automatically get menu entries in their window
+ managers, as well in shells like <tt>pdmenu</tt>.</p>
+
+ <p>
+ Please refer to the <em>Debian Menu System</em> document
+ that comes with the <tt>menu</tt> package for information
+ about how to register your applications and web
+ documents.</p></sect>
+
+
+ <sect>
+ <heading>Keyboard configuration</heading>
+
+ <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>
+
+ <p>
+ Here is a list that contains certain keys and their interpretation:
+
+ <taglist>
+ <tag><tt><--</tt></tag>
+ <item><p>delete the character to the left of the cursor</p></item>
+
+ <tag><tt>Delete</tt></tag>
+ <item><p>delete the character to the right of the cursor</p></item>
+
+ <tag><tt>Control+H</tt></tag>
+ <item><p>emacs: the help prefix</p></item>
+ </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>
+
+ <p>
+ The following list explains how the different programs
+ should be set up to achieve this:</p>
+
+ <p>
+ <list compact="compact">
+ <item><p>`<tt><--</tt>' generates KB_Backspace in
+ X.</p></item>
+
+ <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
+
+ <item>
+ <p>
+ 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>
+
+ <item>
+ <p>
+ 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>
+
+ <item><p>
+ X applications are configured so that Backspace
+ deletes left, and Delete deletes right. Motif
+ applications already work like this.</p></item>
+
+ <item><p>stty erase <tt>^?</tt> .</p></item>
+
+ <item><p>
+ The `xterm' terminfo entry should have <tt>ESC [ 3
+ ~</tt> for kdch1, just like TERM=linux and
+ TERM=vt220.</p></item>
+
+ <item><p>
+ 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>
+
+ <item><p>
+ 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'.</p></item>
+ </list></p>
+
+ <p>
+ This will solve the problem except for:</p>
+
+ <p>
+ <list compact="compact">
+ <item><p>
+ 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>
+
+ <item><p>
+ 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>
+
+ <item><p>
+ 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>
+
+ <item><p>
+ 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.</p></item>
+ </list>
+ </p>
+ </sect>
+
+
+ <sect>
+ <heading>Environment variables</heading>
+
+ <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>
+
+ <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>
+
+ <p>
+ Here is an example of a wrapper script for this purpose:
+
+ <example>
+ #!/bin/sh
+ BAR=/var/lib/fubar
+ export BAR
+ exec /usr/lib/foo/foo "$@"
+ </example></p>
+
+ <p>
+ Furthermore, as <tt>/etc/profile</tt> is a configuration
+ file of the <prgn>bash</prgn> package, no other package may
+ put any environment variables or other commands into that
+ file.</p>
+ </sect>
+ </chapt>
+ <chapt>
+ <heading>Files</heading>
+
+
+ <sect>
+ <heading>Binaries</heading>
+
+ <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</em> programs must be
+ renamed.</p>
+
+ <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>
+
+ <p>
+ Note that all installed binaries should be stripped,
+ either by using the <tt>-s</tt> flag to
+ <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
+ the binaries after they have been copied into
+ <tt>debian/tmp</tt> but before the tree is made into a
+ package.</p>
+
+ <p>
+ The <tt>-g</tt> 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>
+
+ <p>
+ The <tt>-N</tt> 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>
+
+ <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</tt>, 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></sect>
+
+
+ <sect>
+ <heading>Libraries</heading>
+
+ <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</tt>, and
+ the static version must not be. In other words, each
+ <tt>*.c</tt> file is compiled twice.</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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></sect>
+
+
+ <sect>
+ <heading>Shared libraries</heading>
+
+ <p>
+ Packages involving shared libraries should be split up
+ into several binary packages.</p>
+
+ <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><var>soname</var></tt>
+ (<var>soname</var> 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</var> is the major number of the library) and
+ <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
+
+ <p>
+ If you prefer only to support one development version at a
+ time you may name the development package
+ <tt><var>libraryname</var>-dev</tt>; otherwise you may
+ wish to use <prgn>dpkg</prgn>'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>
+
+ <p>
+ Packages which use the shared library should have a
+ dependency on the name of the shared library package,
+ <tt><var>libraryname</var><var>soname</var></tt>. When
+ the <var>soname</var> changes you can have both versions
+ of the library installed while moving from the old library
+ to the new.</p>
+
+ <p>
+ If your package has some run-time support programs which
+ use the shared library you must <em>not</em> 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</var>-runtime</tt>--note the absence
+ of the <var>soname</var> in the package name) or if the
+ development package is small include them in there.</p>
+
+ <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</var>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>
+
+ <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</tt> control area
+ file with details of the dependencies for packages which
+ use the library.</p>
+
+ <p>
+ Shared libraries should <em>not</em> be installed
+ executable, since <prgn>ld.so</prgn> does not require this
+ and trying to execute a shared library results in a core
+ dump.</p></sect>
+
+
+ <sect id="scripts">
+ <heading>Scripts</heading>
+
+ <p>
+ All command scripts, including the package maintainer
+ scripts inside the package and used by <prgn>dpkg</prgn>,
+ should have a <tt>#!</tt> line naming the shell to be used
+ to interpret them.</p>
+
+ <p>
+ In the case of Perl scripts this should be
+ <tt>#!/usr/bin/perl</tt>.</p>
+
+ <p>
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
+ should almost certainly start with <tt>set -e</tt> so that
+ errors are detected. Every script <em>must</em> use
+ <tt>set -e</tt> or check the exit status of <em>every</em>
+ command.</p>
+
+ <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</prgn>).</p>
+
+ <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</prgn>, it's probably
+ POSIX compliant, but if you are in doubt, use
+ <tt>/bin/bash</tt>.</p>
+
+ <p>
+ Perl scripts should check for errors when making any
+ system calls, including <tt>open</tt>, <tt>print</tt>,
+ <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
+
+ <p>
+ <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
+ as scripting languages. See <em>Csh Programming
+ Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
+ FAQs. It can be found on <ftpsite>rtfm.mit.edu</ftpsite>
+ in
+ <ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</ftppath>.
+ If an upstream package comes with <prgn>csh</prgn> scripts
+ then you must make sure that they start with
+ <tt>#!/bin/csh</tt> and make your package depend on the
+ <prgn>c-shell</prgn> virtual package.</p>
+
+ <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>
+
+ <p>
+ The Debian base distribution provides the
+ <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
+ for use by scripts for this purpose.</p></sect>
+
+
+ <sect>
+ <heading>Symbolic links</heading>
+
+ <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>
+
+ <p>
+ In addition, symbolic links should be specified as short
+ as possible, i.e., link targets like `foo/../bar' are
+ deprecated.</p>
+
+ <p>
+ Note that when creating a relative link using
+ <prgn>ln</prgn> it is not necessary for the target of the
+ link to exist relative to the working directory you're
+ running <prgn>ln</prgn> 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</prgn>.</p>
+
+ <p>
+ For example, in your <prgn>Makefile</prgn> or
+ <tt>debian/rules</tt>, 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>
+
+ <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></sect>
+
+
+ <sect>
+ <heading>Device files</heading>
+
+ <p>
+ No package may include device files in the package file
+ tree.</p>
+
+ <p>
+ If a package needs any special device files that are not
+ included in the base system, it has to call
+ <prgn>makedev</prgn> in the <tt>postinst</tt> script,
+ after asking the user for permission to do so.</p>
+
+ <p>
+ No package should remove any device files in the
+ <tt>postrm</tt> or any other script. This is left to the
+ system administrator.</p>
+
+ <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></sect>
+
+
+ <sect>
+ <heading>Configuration files</heading>
+
+ <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>
+
+ <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</prgn>'s <tt>conffiles</tt> control area
+ file. (See the <em>Debian Packaging
+ Manual</em>).</p>
+
+ <p>
+ Only packages that are tagged <em>conflicting</em> with
+ each other may specify the same file as
+ <tt>conffile</tt>. A package may not modify a
+ configuration file of another package.</p>
+
+ <p>
+ If two or more packages use the same configuration file,
+ one of these packages has to be defined as <em>owner</em>
+ of the configuration file, i.e., it has to list the file
+ as <tt>conffile</tt> and has to provide a program that
+ modifies the configuration file.</p>
+
+ <p>
+ The other packages have to depend on the <em>owner</em>
+ package and use that program to update the configuration
+ file.</p>
+
+ <p>
+ Sometimes it's appropriate to build a new package, which
+ just provides the basic <em>infrastructure</em> for the
+ other packages and which manages the shared configuration
+ files. (Check out the <prgn>sgml-base</prgn> package as an
+ example.)</p>
+
+ <p>
+ Files in <tt>/etc/skel</tt> will automatically be copied
+ into new user accounts by <prgn>adduser</prgn>. They
+ should not be referenced there by any program.</p>
+
+ <p>
+ Therefore, if a program needs a dotfile to exist in
+ advance in <tt>$HOME</tt> to work sensibly that dotfile
+ should be installed in <tt>/etc/skel</tt> (and listed in
+ conffiles, if it is not generated and modified dynamically
+ by the package's installation scripts).</p>
+
+ <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>
+
+ <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</tt>. 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</tt>.</p>
+
+ <p>
+ <tt>/etc/skel</tt> 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>
+
+ <p>
+ Ideally the sysadmin should not have to do any
+ configuration other than that done (semi-)automatically by
+ the <tt>postinst</tt> script.</p>
+ </sect>
+
+ <sect>
+ <heading>Log files</heading>
+
+ <p>
+ Log files should usually be named
+ <tt>/var/log/<var>package</var>.log</tt>. If you have many
+ log files, or need a separate directory for permissions
+ reasons (<tt>/var/log</tt> is writable only by
+ <tt>root</tt>), you should usually create a directory named
+ <tt>/var/log/<var>package</var></tt>.</p>
+
+ <p>
+ 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 <prgn>savelog</prgn> program in an
+ <tt>/etc/cron.daily</tt>, <tt>/etc/cron.weekly</tt> or
+ <tt>/etc/cron.monthly</tt> script. Here is a good example:
+ <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
+ </example></p>
+
+ <p>
+ 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 <tt>postrm</tt> script (see the <em>Debian
+ Packaging Manual</em> for details).</p>
+ </sect>
+
+
+ <sect>
+ <heading>Permissions and owners</heading>
+
+ <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</prgn> first.</p>
+
+ <p>
+ Files should be owned by <tt>root.root</tt>, and made
+ writable only by the owner and universally readable (and
+ executable, if appropriate).</p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <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</prgn> (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>
+
+ <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>
+
+ <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</tt>) in its pre- or
+ post-installation script (the latter is to be preferred if
+ it is possible).</p>
+
+ <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</prgn> 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</prgn> in the pre- or post-installation
+ script (again, the latter is to be preferred if it is
+ possible).</p>
+
+ <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>
+ </chapt>
+
+ <chapt>
+ <heading>Customized programs</heading>
+
+ <sect id="arch-spec">
+ <heading>Architecture specification strings</heading>
+
+ <p>
+ If a program needs to specify an <em>architecture specification
+ string</em> in some place, the following format has to be used:
+ <example>
+ <arch>-<os>
+ </example>
+ where `<arch>' is one of the following: i386, alpha, arm, m68k,
+ powerpc, sparc and `<os>' is one of: linux, gnu. Use
+ of <em>gnu</em> in this string is reserved for the GNU/Hurd
+ operating system. .</p>
+ <p>
+ 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.</p></sect>
+
+
+ <sect>
+ <heading>Daemons</heading>
+
+ <p>
+ The configuration files <tt>/etc/services</tt>,
+ <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
+ by the <prgn>netbase</prgn> package and may not be modified
+ by other packages.</p>
+
+ <p>
+ If a package requires a new entry in one of these files, the
+ maintainer has to get in contact with the
+ <prgn>netbase</prgn> maintainer, who will add the entries
+ and release a new version of the <prgn>netbase</prgn>
+ package.</p>
+
+ <p>
+ The configuration file <tt>/etc/inetd.conf</tt> may be
+ modified by the package's scripts only via the
+ <prgn>update-inetd</prgn> script or the
+ <prgn>DebianNet.pm</prgn> Perl module.</p>
+
+ <p>
+ If a package wants to install an example entry into
+ <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
+ exactly one hash character (#). Such lines are treated as
+ `commented out by user' by the <prgn>update-inetd</prgn>
+ script and are not changed or activated during a package
+ updates.</p></sect>
+
+
+ <sect>
+ <heading>Editors and pagers</heading>
+
+ <p>
+ 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.</p>
+
+ <p>
+ In addition, every program should choose a good default
+ editor/pager if none is selected by the user or system
+ administrator.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ 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.</p></sect>
+
+
+ <sect id="web-appl">
+ <heading>Web servers and applications</heading>
+
+ <p>
+ This section describes the locations and URLs that have to
+ be used by all web servers and web application in the Debian
+ system.</p>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>Cgi-bin executable files are installed in the
+ directory
+ <example>
+ /usr/lib/cgi-bin/<cgi-bin-name>
+ </example>
+ and can be referred to as
+ <example>
+ http://localhost/cgi-bin/<cgi-bin-name>
+ </example></p></item>
+
+
+ <item><p>Access to html documents</p>
+
+ <p>
+ Html documents for a package are stored in
+ /usr/doc/<var>package</var> and can be referred to as
+ <example>
+ http://localhost/doc/<package>/<filename>
+ </example></p></item>
+
+
+ <item><p>Web Document Root</p>
+
+ <p>
+ 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
+ <example>
+ /var/www
+ </example>
+ as the Document Root. This might be just a
+ symbolic link to the location where the sysadmin has
+ put the real document root.</p>
+ </item>
+
+ </enumlist></p></sect>
+
+
+ <sect>
+ <heading>Mail transport agents</heading>
+
+ <p>
+ Debian packages which process electronic mail, whether
+ mail-user-agents (MUAs) or mail-transport-agents (MTAs),
+ <em>must</em> make sure that they are compatible with the
+ configuration decisions below. Failure to do this may
+ result in lost mail, broken <tt>From:</tt> lines, and other
+ serious brain damage!</p>
+
+ <p>
+ The mail spool is <tt>/var/spool/mail</tt> and the interface
+ to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
+ per the FSSTND). The mail spool is part of the base system
+ and not part of the MTA package.</p>
+
+ <p>
+ All Debian MUAs and MTAs have to use the <tt>maillock</tt>
+ and <tt>mailunlock</tt> functions provided by the
+ <tt>liblockfile</tt> 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 <em>compatible</em> mechanism. Please
+ compare the mechanisms very carefully!)</p>
+
+ <p>
+ Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
+ 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.</p>
+
+ <p>
+ The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
+ be setgid mail to do the locking mentioned above (and
+ obviously need to avoid accessing other users' mailboxes
+ using this privilege).</p>
+
+ <p>
+ <tt>/etc/aliases</tt> is the source file for the system mail
+ aliases (e.g., postmaster, usenet, etc.)--it is the one
+ which the sysadmin and <tt>postinst</tt> scripts may edit.
+ After <tt>/etc/aliases</tt> is edited the program or human
+ editing it must call <prgn>newaliases</prgn>. All MTA
+ packages should come with a <prgn>newaliases</prgn> program,
+ even if it does nothing, but older MTA packages do not do
+ this so programs should not fail if <prgn>newaliases</prgn>
+ cannot be found.</p>
+
+ <p>
+ The convention of writing <tt>forward to
+ <var>address</var></tt> in the mailbox itself is not
+ supported. Use a <tt>.forward</tt> file instead.</p>
+
+ <p>
+ The location for the <prgn>rmail</prgn> program used by UUCP
+ for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
+ FSSTND. Likewise, <prgn>rsmtp</prgn>, for receiving
+ batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
+ is supported.</p>
+
+ <p>
+ 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 <tt>/etc/mailname</tt>. It will
+ contain the portion after the username and <tt>@</tt> (at)
+ sign for email addresses of users on the machine (followed
+ by a newline).</p>
+
+ <p>
+ 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
+ <tt>/etc/mailname</tt> 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:
+ <example>
+ 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
+ <var>syshostname</var>, your system's host name. Mail
+ name [`<var>syshostname</var>']:
+ </example>
+ where <var>syshostname</var> is the output of <tt>hostname
+ --fqdn</tt>.</p></sect>
+
+
+ <sect>
+ <heading>News system configuration</heading>
+
+ <p>
+ All the configuration files related to the NNTP (news)
+ servers and clients should be located under
+ <tt>/etc/news</tt>.</p>
+
+ <p>
+ There are some configuration issues that apply to a number
+ of news clients and server packages on the machine. These
+ are:
+
+ <taglist>
+ <tag>/etc/news/organization</tag>
+ <item><p>A string which shall appear as the
+ organization header for all messages posted
+ by NNTP clients on the machine</p></item>
+
+ <tag>/etc/news/server</tag>
+ <item><p>Contains the FQDN of the upstream NNTP
+ server, or localhost if the local machine is
+ an NNTP server.</p></item>
+ </taglist>
+
+ Other global files may be added as required for cross-package news
+ configuration.</p></sect>
+
+
+ <sect>
+ <heading>Programs for the X Windows system</heading>
+
+ <p>
+ 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.</p>
+
+ <p>
+ Such programs should be configured <em>with</em> X support,
+ and should declare a dependency on <tt>xlib6g</tt> (for the
+ X11R6 libraries). Users who wish to use the program can
+ install just the relatively small <tt>xlib6g</tt> package,
+ and do not need to install the whole of X.</p>
+
+ <p>
+ Do not create two versions (one with X support and one
+ without) of your package.</p>
+
+ <p>
+ <em>Application defaults</em> files have to be installed in
+ the directory
+ <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
+ considered as part of the program code. Thus, they should
+ not be modified and should not be tagged as
+ <em>conffile</em>. If the local system administrator wants
+ to customise X applications globally, the file
+ <tt>/etc/X11/Xresources</tt> should be used.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ However, if your package works reliably with lesstif, you
+ should package it with lesstif, and not with Motif at
+ all.</p>
+
+ <p>
+ 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.</p></sect>
+
+
+ <sect>
+ <heading>Emacs lisp programs</heading>
+
+ <p>
+ Please refer to the `Debian Emacs Policy' (documented in
+ <tt>debian-emacs-policy.gz</tt> of the
+ <prgn>emacsen-common</prgn> package) for details of how to
+ package emacs lisp programs.</p></sect>
+
+
+ <sect>
+ <heading>Games</heading>
+
+ <p>
+ The permissions on /var/lib/games are 755
+ <tt>root.root</tt>.</p>
+
+ <p>
+ Each game decides on its own security policy.</p>
+
+ <p>
+ Games which require protected, privileged access to
+ high-score files, savegames, etc., must be made
+ set-<em>group</em>-id (mode 2755) and owned by
+ <tt>root.games</tt>, and use files and directories with
+ appropriate permissions (770 <tt>root.games</tt>, for
+ example). They must <em>not</em> be made
+ set-<em>user</em>-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.)</p>
+
+ <p>
+ 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 <tt>.deb</tt> 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.</p>
+
+ <p>
+ As described in the FSSTND, binaries of games should be
+ installed in the directory <tt>/usr/games</tt>. This also
+ applies to games that use the X windows system. Manual pages
+ for games (X and non-X games) should be installed in
+ <tt>/usr/man/man6</tt>.</p>
+ </sect>
+ </chapt>
+
+ <chapt><heading>Documentation</heading>
+
+
+ <sect>
+ <heading>Manual pages</heading>
+
+ <p>
+ You must install manual pages in <prgn>nroff</prgn> source
+ form, in appropriate places under <tt>/usr/man</tt>. You
+ should only use sections 1 to 9 (see the FSSTND for more
+ details). You must <em>not</em> install a preformatted `cat
+ page'.</p>
+
+ <p>
+ 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 <manref name="undocumented" section="7"> manual page
+ should be provided. This symbolic link can be created from
+ <tt>debian/rules</tt> like this:
+ <example>
+ ln -s ../man7/undocumented.7.gz \
+ debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
+ </example>
+ 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.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ Manual pages should be installed compressed using <tt>gzip
+ -9</tt>.</p>
+
+ <p>
+ If one manpage needs to be accessible via several names it
+ is better to use a symbolic link than the <tt>.so</tt>
+ feature, but there is no need to fiddle with the relevant
+ parts of the upstream source to change from <tt>.so</tt> to
+ symlinks--don't do it unless it's easy. Do not create hard
+ links in the manual page directories, and do not put
+ absolute filenames in <tt>.so</tt> directives. The filename
+ in a <tt>.so</tt> in a manpage should be relative to the
+ base of the manpage tree (usually
+ <tt>/usr/man</tt>).</p></sect>
+
+
+ <sect>
+ <heading>Info documents</heading>
+
+ <p>
+ Info documents should be installed in <tt>/usr/info</tt>.
+ They should be compressed with <tt>gzip -9</tt>.</p>
+
+ <p>
+ Your package must call <prgn>install-info</prgn> to update the Info
+ <tt>dir</tt>
+ file, in its post-installation script:
+ <example>
+ install-info --quiet --section Development Development \
+ /usr/info/foobar.info
+ </example></p>
+
+ <p>
+ It is a good idea to specify a section for the location of
+ your program; this is done with the <tt>--section</tt>
+ switch. To determine which section to use, you should look
+ at <tt>/usr/info/dir</tt> on your system and choose the most
+ relevant (or create a new section if none of the current
+ sections are relevant). Note that the <tt>--section</tt>
+ 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.</p>
+
+ <p>
+ You must remove the entries in the pre-removal script:
+ <example>
+ install-info --quiet --remove /usr/info/foobar.info
+ </example></p>
+
+ <p>
+ If <prgn>install-info</prgn> cannot find a description entry
+ in the Info file you will have to supply one. See <manref
+ name="install-info" section="8"> for details.</p>
+ </sect>
+
+ <sect>
+ <heading>Additional documentation</heading>
+
+ <p>
+ 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
+ <tt>/usr/doc/<var>package</var></tt>, where
+ <var>package</var> is the name of the package, and
+ compressed with <tt>gzip -9</tt> unless it is small.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ It is often a good idea to put text information files
+ (<tt>README</tt>s, changelogs, and so forth) that come with
+ the source package in <tt>/usr/doc/<var>package</var></tt>
+ in the binary package. However, you don't need to install
+ the instructions for building and installing the package, of
+ course!</p>
+ </sect>
+
+ <sect>
+ <heading>Preferred documentation formats</heading>
+
+ <p>
+ The unification of Debian documentation is being carried out
+ via HTML.</p>
+
+ <p>
+ If your package comes with extensive documentation in a
+ markup format that can be converted to various other formats
+ you should if possible ship HTML versions in a binary
+ package, in the directory
+ <tt>/usr/doc/<var>appropriate package</var></tt> or its
+ subdirectories.
+ <footnote>
+ <p>The rationale: The important thing here is that HTML
+ docs should be available in <em>some</em> package, not
+ necessarily in the main binary package, though. </p>
+ </footnote>
+ </p>
+
+ <p>
+ Other formats such as PostScript may be provided at your
+ option.</p>
+ </sect>
+
+ <sect id="copyrightfile">
+ <heading>Copyright information</heading>
+
+ <p>
+ 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.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ /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.</p>
+
+ <p>
+ 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.</p>
+
+ <p>
+ Do not use the copyright file as a general <tt>README</tt>
+ file. If your package has such a file it should be
+ installed in <tt>/usr/doc/<var>package</var>/README</tt> or
+ <tt>README.Debian</tt> or some other appropriate place.</p>
+ </sect>
+
+ <sect>
+ <heading>Examples</heading>
+
+ <p>
+ Any examples (configurations, source files, whatever),
+ should be installed in a directory
+ <tt>/usr/doc/<var>package</var>/examples</tt>. These files
+ should not be referenced by any program--they're there for
+ the benefit of the system administrator and users, as
+ documentation only.</p>
+ </sect>
+
+ <sect id="instchangelog">
+ <heading>Changelog files</heading>
+
+ <p>
+ This installed file must contain a copy of the
+ <tt>debian/changelog</tt> file from your Debian source tree,
+ and a copy of the upstream changelog file if there is one.
+ The debian/changelog file should be installed in
+ <tt>/usr/doc/<var>package</var></tt> as
+ <tt>changelog.Debian.gz</tt>. If the upstream changelog
+ file is text formatted, it must be accessable as
+ <tt>/usr/doc/<var>package</var>/changelog.gz</tt>. If the
+ upstream changelog file is HTML formatted, it must be
+ accessable as <tt>/usr/doc/<var>package</var>/changelog.html.gz</tt>.
+ If the upstream changelog files do not already conform to
+ this naming convention, then this may be achieved by either
+ renaming the files or adding a symbolic link at the
+ packaging developer's discretion. </p>
+
+ <p>
+ Both should be installed compressed using <tt>gzip -9</tt>,
+ as they will become large with time even if they start out
+ small.</p>
+
+ <p>
+ 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
+ <tt>/usr/doc/<var>package</var>/changelog.gz</tt>; if there
+ is a separate upstream maintainer, but no upstream
+ changelog, then the Debian changelog should still be called
+ <tt>changelog.Debian.gz</tt>.</p>
+ </sect>
+ </chapt>
+ </book>
+</debiandoc>