1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Policy Manual.
9 Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
10 released under the terms of the GNU
11 General Public License, version 2 or (at your option) any later.
12 Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
13 Revised November 27, 1996, David A. Morris, bweaver@debian.org
14 New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
15 Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
16 Maintainer since 1997, Christian Schwarz, schwarz@debian.org
17 Christoph Lameter contributed the "Web Standard"
18 The debian-policy mailing list has taken responsibility for the
19 contents of this document since September 1998, with the package
20 maintainers responsible for packaging administrivia only.
25 <title>Debian Policy Manual</title>
27 <name>Ian Jackson </name>
28 <email>ijackson@gnu.ai.mit.edu</email>
31 <name>Christian Schwarz</name>
32 <email>schwarz@debian.org</email>
35 <name>revised: David A. Morris</name>
36 <email>bweaver@debian.org</email>
39 <name>The Debian Policy mailing List</name>
40 <email>debian-policy@lists.debian.org</email>
42 <version>version &version;, &date;</version>
45 This manual describes the policy requirements for the Debian
46 GNU/Linux distribution. This includes the structure and
47 contents of the Debian archive, several design issues of the
48 operating system, as well as technical requirements that each
49 package must satisfy to be included in the distribution. The
50 policy package itself is maintained by a group of maintainers
51 that have no editorial powers. At the moment, the list of
55 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
58 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
61 <p>Philip Hands <email>phil@hands.com</email></p>
64 <p>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</email></p>
67 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
75 Copyright ©1996,1997,1998 Ian Jackson
76 and Christian Schwarz.
79 This manual is free software; you may redistribute it and/or
80 modify it under the terms of the GNU General Public License
81 as published by the Free Software Foundation; either version
82 2, or (at your option) any later version.
86 This is distributed in the hope that it will be useful, but
87 <em>without any warranty</em>; without even the implied
88 warranty of merchantability or fitness for a particular
89 purpose. See the GNU General Public License for more
94 A copy of the GNU General Public License is available as
95 <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
96 distribution or on the World Wide Web at
97 <url id="http://www.gnu.org/copyleft/gpl.html"
98 name="The GNU Public Licence">. You can also obtain it by writing to the
99 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
100 Boston, MA 02111-1307, USA.
108 <heading>About this manual</heading>
110 <heading>Scope</heading>
112 This manual describes the policy requirements for the Debian
113 GNU/Linux distribution. This includes the structure and
114 contents of the Debian archive, several design issues of the
115 operating system, as well as technical requirements that
116 each package must satisfy to be included in the
120 In this manual, the words <em>must</em>, <em>should</em> and
121 <em>may</em>, and the adjectives <em>required></em>,
122 <em>recommended</em> and <em>optional</em>, are used to
123 distinguish the significance of the various guidelines in
124 this policy document. Packages that do not conform the the
125 guidelines denoted by <em>must</em> (or <em>required</em>)
126 will generally not be considered acceptable for the Debian
127 distribution. Non-conformance with guidelines denoted by
128 <em>should</em> (or <em>recommended</em>) will generally be
129 considered a bug, but will not necessarily render a package
130 unsuitable for distribution. Guidelines denoted by
131 <em>may</em> (or <em>optional</em>) are truly optional and
132 adherence is left to the maintainer's discretion.
135 These classifications are roughly equivalent to the bug
136 severities <em>important</em> (for <em>must</em> or
137 <em>required</em> directive violations), <em>normal</em>
138 (for <em>should</em> or <em>recommended</em> directive
139 violations) and <em>wishlist</em> (for <em>optional</em>
141 <p>Also see RFC 2119.</p>
145 This manual does <em>not</em> describe the technical
146 mechanisms involved in package creation, installation, and
147 removal. This information can be found in the <em>Debian
148 Packaging Manual</em> and the <em>Debian System
149 Administrators' Manual</em>. Please note that the
150 footnotes present in this manual are merely informative,
151 and are not part of Debian policy itself.
154 This document assumes familiarity with these other two
155 manuals. Unfortunately, the <em>System Administrators'
156 Manual</em> does not exist yet.
159 Much of the information presented in this manual will be
160 useful even when building a package which is to be
161 distributed in some other way or is for local use.
165 <heading>New versions of this document</heading>
167 The current version of this document is always accessible from the
168 Debian FTP server <ftpsite>ftp.debian.org</ftpsite> at
169 <ftppath>/debian/doc/package-developer/debian-policy.html.tar.gz</ftppath>
170 or from the Debian WWW server at
171 <url id="http://www.debian.org/doc/debian-policy/"
172 name="The Debian Policy Manual">.</p>
175 In addition, this manual is distributed via the Debian package
176 <tt>debian-policy</tt>.
180 <heading>Feedback</heading>
183 As the Debian GNU/Linux system is continuously evolving this
184 manual is changed from time to time.
187 While the authors of this document tried hard not to include
188 any typos or other errors these still occur. If you discover
189 an error in this manual or if you want to tell us any
190 comments, suggestions, or critics please send an email to
191 the Debian Policy List,
192 <email>debian-policy@lists.debian.org</email>, or submit a
193 bug report against the <tt>debian-policy</tt> package.
198 <heading>The Debian Archive</heading>
200 The Debian GNU/Linux system is maintained and distributed as a
201 collection of <em>packages</em>. Since there are so many of them (over
202 2600) they are split into <em>sections</em> and <em>priorities</em> to
203 simplify handling of them.
206 The effort of the Debian project is to build a free operating
207 system, but not every package we want to make accessible is
208 <em>free</em> in our sense (see Debian Free Software
209 Guidelines, below), or may be imported/exported without
210 restrictions. Thus, the archive is split into the sections
211 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
212 <em>contrib</em>.</p>
214 The <em>main</em> section forms the <em>Debian GNU/Linux
215 distribution</em>. </p>
217 Packages in the other sections are not considered as part of
218 the Debian distribution, though we support their use, and we
219 provide infrastructure for them (such as our bug-tracking
220 system and mailing lists). This Debian Policy Manual applies
221 to these packages as well.</p>
223 <sect id="pkgcopyright">
224 <heading>Package copyright and sections</heading>
226 The aims of this policy are:
228 <list compact="compact">
230 <p>We want to make as much software available as we
234 <p>We want to encourage everyone to write free software.</p>
237 <p> We want to make it easy for people to produce
238 CD-ROMs of our system without violating any licenses,
239 import/export restrictions, or any other laws.</p>
244 <heading>The Debian Free Software Guidelines</heading>
246 The Debian Free Software Guidelines (DFSG) is our
247 definition of `free' software.
249 <tag>Free Redistribution
253 The license of a Debian component may not restrict any
254 party from selling or giving away the software as a
255 component of an aggregate software distribution
256 containing programs from several different
257 sources. The license may not require a royalty or
258 other fee for such sale.
265 The program must include source code, and must allow
266 distribution in source code as well as compiled form.
273 The license must allow modifications and derived
274 works, and must allow them to be distributed under the
275 same terms as the license of the original software.
278 <tag>Integrity of The Author's Source Code
282 The license may restrict source-code from being
283 distributed in modified form <em>only</em> if the
284 license allows the distribution of ``patch files''
285 with the source code for the purpose of modifying the
286 program at build time. The license must explicitly
287 permit distribution of software built from modified
288 source code. The license may require derived works to
289 carry a different name or version number from the
290 original software. (This is a compromise. The Debian
291 group encourages all authors to not restrict any
292 files, source or binary, from being modified.)
295 <tag>No Discrimination Against Persons or Groups
299 The license must not discriminate against any person
303 <tag>No Discrimination Against Fields of Endeavor
307 The license must not restrict anyone from making use
308 of the program in a specific field of endeavor. For
309 example, it may not restrict the program from being
310 used in a business, or from being used for genetic
314 <tag>Distribution of License
318 The rights attached to the program must apply to all
319 to whom the program is redistributed without the need
320 for execution of an additional license by those
324 <tag>License Must Not Be Specific to Debian
328 The rights attached to the program must not depend on
329 the program's being part of a Debian system. If the
330 program is extracted from Debian and used or
331 distributed without Debian but otherwise within the
332 terms of the program's license, all parties to whom
333 the program is redistributed must have the same
334 rights as those that are granted in conjunction with
338 <tag>License Must Not Contaminate Other Software
342 The license must not place restrictions on other
343 software that is distributed along with the licensed
344 software. For example, the license must not insist
345 that all other programs distributed on the same medium
346 must be free software.
349 <tag>Example Licenses
353 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
354 examples of licenses that we consider <em>free</em>.
361 <heading>The main section</heading>
363 Every package in "main" must comply with the DFSG (Debian
364 Free Software Guidelines).</p>
367 In addition, the packages in "main"
368 <list compact="compact">
371 must not require a package outside of "main" for
372 compilation or execution (thus, the package must not
373 declare a "Depends" or "Recommends" relationship on a
379 should not be so buggy that we refuse to support them,
384 should meet all policy requirements presented in this
392 <heading>The contrib section</heading>
394 Every package in "contrib" must comply with the DFSG.
398 Examples of packages which would be included in "contrib" are
399 <list compact="compact">
402 free packages which require "contrib", "non-free", or
403 "non-US" packages or packages which are not in our
404 archive at all for compilation or execution,
409 wrapper packages or other sorts of free accessories for
417 <heading>The non-free section</heading>
419 `Non-free' contains packages which are not compliant with
420 the DFSG or which are encumbered by patents or other legal
421 issues that make their distribution problematic.</p>
423 All packages in `non-free' must be electronically
424 distributable across international borders.
428 <heading>The non-us server</heading>
430 Some programs with cryptographic program code need to be stored
431 on the "non-us" server because of export restrictions of the
434 This applies only to packages which contain cryptographic
435 code. A package containing a program with an interface to a
436 cryptographic program or a program that's dynamically linked
437 against a cryptographic library should not be distributed
438 via the non-us server if it is capable of running without the
439 cryptography library or program.
443 <heading>Further copyright considerations</heading>
445 Every package must be accompanied by a verbatim copy of its
446 copyright and distribution license in the file
447 /usr/share/doc/<package-name>/copyright (see <ref
448 id="copyrightfile"> for details).</p>
450 We reserve the right to restrict files from being included
451 anywhere in our archives if
452 <list compact="compact">
455 their use or distribution would break a law,
460 there is an ethical conflict in their distribution or
466 we would have to sign a license for them, or
471 their distribution would conflict with other project
479 Programs whose authors encourage the user to make donations
480 are fine for the main distribution, provided that the
481 authors do not claim that not donating is immoral,
482 unethical, illegal or something similar; otherwise they must
486 Packages whose copyright permission notices (or patent
487 problems) do not allow redistribution even of only binaries,
488 and where no special permission has been obtained, must not be
489 placed on the Debian FTP site and its mirrors at all.</p>
492 Note, that under international copyright law (this applies
493 in the United States, too) <em>no</em> distribution or
494 modification of a work is allowed without an explicit notice
495 saying so. Therefore a program without a copyright notice
496 <em>is</em> copyrighted and you may not do anything to it
497 without risking being sued! Likewise if a program has a
498 copyright notice but no statement saying what is permitted
499 then nothing is permitted.</p>
502 Many authors are unaware of the problems that restrictive
503 copyrights (or lack of copyright notices) can cause for the
504 users of their supposedly-free software. It is often
505 worthwhile contacting such authors diplomatically to ask
506 them to modify their license terms. However, this is a
507 politically difficult thing to do and you should ask for
508 advice on <tt>debian-devel</tt> first.</p>
511 When in doubt, send mail to
512 <email>debian-devel@lists.debian.org</email>. Be prepared
513 to provide us with the copyright statement. Software
514 covered by the GPL, public domain software and BSD-like
515 copyrights are safe; be wary of the phrases `commercial use
516 prohibited' and `distribution restricted'.</p>
519 <heading>Subsections</heading>
522 The packages in all the sections (<em>main</em>,
523 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
524 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
525 grouped further into <em>subsections</em> to simplify
529 The section for each package should be specified in the
530 package's <em>control record</em>. However, the maintainer of
531 the Debian archive may override this selection to assure the
532 consistency of the Debian distribution. </p>
535 Please check the current Debian distribution to see which
536 sections are available.</p>
539 <heading>Priorities</heading>
542 Each package should have a <em>priority</em> value,
543 which is included in the package's <em>control
544 record</em>. This information is used in the Debian package
545 management tool to separate high-priority packages from
546 less-important packages.</p>
549 The following <em>priority levels</em> are supported by the
550 Debian package management system, <prgn>dpkg</prgn>.
552 <tag><tt>required</tt></tag>
555 <tt>required</tt> packages are necessary for the
556 proper functioning of the system. You must not remove
557 these packages or your system may become totally
558 broken and you may not even be able to use
559 <prgn>dpkg</prgn> to put things back. Systems with
560 only the <tt>required</tt> packages are probably
561 unusable, but they do have enough functionality to
562 allow the sysadmin to boot and install more
565 <tag><tt>important</tt></tag>
568 Important programs, including those which one would
569 expect to find on any Unix-like system. If the
570 expectation is that an experienced Unix person who
571 found it missing would say `What the F*!@<+ is
572 going on, where is <prgn>foo</prgn>', it must be in
573 <tt>important</tt>. This is an important criterion
574 because we are trying to produce, amongst other
575 things, a free Unix. Other packages without which the
576 system will not run well or be usable must also be
577 here. This does <em>not</em> include Emacs, the X
578 Window System, TeX or any other large applications.
579 The <tt>important</tt> packages are just a bare
580 minimum of commonly-expected and necessary tools.</p>
582 <tag><tt>standard</tt></tag>
585 These packages provide a reasonably small but not too
586 limited character-mode system. This is what will
587 install by default if the user doesn't select anything
588 else. It doesn't include many large applications, but
589 it does include Emacs (this is more of a piece of
590 infrastructure than an application) and a reasonable
591 subset of TeX and LaTeX (if this is possible without
594 <tag><tt>optional</tt></tag>
597 (In a sense everything is optional that isn't
598 required, but that's not what is meant here.) This is
599 all the software that you might reasonably want to
600 install if you didn't know what it was or don't have
601 specialized requirements. This is a much larger system
602 and includes the X Window System, a full TeX distribution,
603 and many applications. Note that optional packages should
604 not conflict with each other.
607 <tag><tt>extra</tt></tag>
610 This contains all packages that conflict with others
611 with required, important, standard or optional
612 priorities, or are only likely to be useful if you
613 already know what they are or have specialised
620 Packages must not depend on packages with lower priority
621 values (excluding build-time dependencies). In order to
622 ensure this, the priorities of one or more packages must
628 <heading>Binary packages</heading>
631 The Debian GNU/Linux distribution is based on the Debian
632 package management system, called <prgn>dpkg</prgn>. Thus,
633 all packages in the Debian distribution must be provided
634 in the <tt>.deb</tt> file format.</p>
638 <heading>The package name</heading>
641 Every package must have a name that's unique within the Debian
645 Package names must only consist of lower case letters, digits (0-9),
646 plus (+) or minus (-) signs, and periods (.).</p>
649 The package name is part of the file name of the
650 <tt>.deb</tt> file and is included in the control field
656 <heading>The maintainer of a package</heading>
659 Every package should have exactly one maintainer at a
660 time. This person is responsible that the license of the
661 package's software complies with the policy of the
662 distribution this package is included in.</p>
665 The maintainer must be specified in the
666 <tt>Maintainer</tt> control field with the correct name
667 and a working email address for the Debian maintainer of
668 the package. If one person maintains several packages
669 he/she should try to avoid having different forms of their
670 name and email address in different <tt>Maintainer</tt>
674 If the maintainer of a package quits from the Debian
675 project the Debian QA Group
676 <email>debian-qa@lists.debian.org</email> takes over the
677 maintainership of the package until someone else
678 volunteers for that task. These packages are called
679 <em>orphaned packages</em>.
685 <heading>The description of a package</heading>
688 Every Debian package must have an extended description
689 stored in the appropriate field of the control record.</p>
692 The description should be written so that it tells the user
693 what they need to know to decide whether to install the
694 package. This description should not just be copied from
695 the blurb for the program. Instructions for configuring
696 or using the package should not be included -- that is what
697 installation scripts, manual pages, Info files, etc. are
698 for. Copyright statements and other administrivia should
699 not be included -- that is what the copyright file is
705 <heading>Dependencies</heading>
708 Every package must specify the dependency information
709 about other packages that are required for the first to
713 For example, a dependency entry must be provided for any
714 shared libraries required by a dynamically-linked executable
715 binary in a package.</p>
718 Packages are not required to declare any dependencies they
719 have on other packages which are marked <tt>Essential</tt>
720 (see below), and should not do so unless they depend on a
721 particular version of that package.</p>
724 Sometimes, a package requires another package to be installed
725 <em>and</em> configured before it can be installed. In this
726 case, you must specify a <tt>Pre-Depends</tt> entry for
730 You should not specify a <tt>Pre-Depends</tt> entry for a
731 package before this has been discussed on the
732 <tt>debian-devel</tt> mailing list and a consensus about
733 doing that has been reached.</p></sect1>
737 <heading>Virtual packages</heading>
740 Sometimes, there are several packages doing more-or-less
741 the same job. In this case, it's useful to define a
742 <em>virtual package</em> whose name describes the function
743 the packages have. (The virtual packages just exist
744 logically, not physically--that's why they are called
745 <em>virtual</em>.) The packages with this particular
746 function will then <em>provide</em> the virtual
747 package. Thus, any other package requiring that function
748 can simply depend on the virtual package without having to
749 specify all possible packages individually.</p>
752 All packages should use virtual package names where
753 appropriate, and arrange to create new ones if necessary.
754 They should not use virtual package names (except privately,
755 amongst a cooperating group of packages) unless they have
756 been agreed upon and appear in the list of virtual package
760 The latest version of the authoritative list of virtual
761 package names can be found on
762 <ftpsite>ftp.debian.org</ftpsite> in
763 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
764 or your local mirror. In addition, it is included in the
765 <tt>debian-policy</tt> package. The procedure for updating
766 the list is described at the top of the file.</p></sect1>
770 <heading>Base packages</heading>
773 The packages included in the <tt>base</tt> section have a
774 special function. They form a minimum subset of the Debian
775 GNU/Linux system that is installed before everything else
776 on a new system. Thus, only very few packages are allowed
777 to go into the <tt>base</tt> section to keep the required
778 disk usage very small.</p>
781 Most of these packages will have the priority value
782 <tt>required</tt> or at least <tt>important</tt>, and many
783 of them will be tagged <tt>essential</tt> (see below).</p>
786 You must not place any packages into the <tt>base</tt>
787 section before this has been discussed on the
788 <tt>debian-devel</tt> mailing list and a consensus about
789 doing that has been reached.</p></sect1>
793 <heading>Essential packages</heading>
796 Some packages are tagged <tt>essential</tt>. (They have
797 <tt>Essential: yes</tt> in their package control record.)
798 This flag is used for packages that are <em>essential</em>
802 Since these packages can not easily be removed (you'll
803 have to specify an extra <em>force option</em> to
804 <prgn>dpkg</prgn>) this flag must not be used unless
805 absolutely necessary.
807 A shared library package must not be tagged
808 <em>essential</em>--the dependencies will prevent its
809 premature removal, and we need to be able to remove it
810 when it has been superseded.</p>
813 You must not tag any packages <tt>essential</tt> before
814 this has been discussed on the <tt>debian-devel</tt>
815 mailing and a consensus about doing that has been
820 <heading>Maintainer scripts</heading>
823 The package installation scripts should avoid producing
824 output which it is unnecessary for the user to see and
825 should rely on <prgn>dpkg</prgn> to stave off boredom on
826 the part of a user installing many packages. This means,
827 amongst other things, using the <tt>--quiet</tt> option on
828 <prgn>install-info</prgn>.</p>
831 Packages should try to minimize the amount of prompting
832 they need to do, and they should ensure that the user will
833 only ever be asked each question once. This means that
834 packages should try to use appropriate shared
835 configuration files (such as <tt>/etc/papersize</tt> and
836 <tt>/etc/news/server</tt>), rather than each prompting for
837 their own list of required pieces of information.</p>
840 It also means that an upgrade should not ask the same
841 questions again, unless the user has used <tt>dpkg
842 --purge</tt> to remove the package's configuration. The
843 answers to configuration questions should be stored in an
844 appropriate place in <tt>/etc</tt> so that the user can
845 modify them, and how this has been done should be
849 If a package has a vitally important piece of information
850 to pass to the user (such as "don't run me as I am, you
851 must edit the following configuration files first or you
852 risk your system emitting badly-formatted messages"), it
853 should display this in the <prgn>postinst</prgn> script
854 and prompt the user to hit return to acknowledge the
855 message. Copyright messages do not count as vitally
856 important (they belong in
857 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
858 do instructions on how to use a program (these should be
859 in on line documentation, where all the users can see
863 Any necessary prompting should almost always be confined
864 to the post-installation script, and should be protected
865 with a conditional so that unnecessary prompting doesn't
866 happen if a package's installation fails and the
867 <prgn>postinst</prgn> is called with
868 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
869 <tt>abort-deconfigure</tt>.</p>
872 Errors which occur during the execution of an installation
873 script should be checked and the installation should not
874 continue after an error.</p>
877 Note, that <ref id="scripts">, in general applies to
878 package maintainer scripts, too.</p>
881 You should not use <prgn>dpkg-divert</prgn> on a file
882 belonging to another package without consulting the maintainer
883 of that package first.</p>
886 All packages which supply an instance of a common command
887 name (or, in general, filename) should generally use
888 <prgn>update-alternatives</prgn>, so that they may be
889 installed together. If <prgn>update-alternatives</prgn>
890 is not used, then each package must use <tt>Conflicts</tt>
891 to ensure that other packages are de-installed. (In this
892 case, it may be appropriate to specify a conflict against
893 earlier versions of something that previously did not use
894 <prgn>update-alternatives</prgn> -- this is an exception to
895 the usual rule that this not allowed).
900 <heading>Source packages</heading>
903 <heading>Standards conformance</heading>
906 You should specify the most recent version of the
907 packaging standards with which your package complies in
908 the source package's <tt>Standards-Version</tt> field.</p>
911 This value will be used to file bug reports automatically
912 if your package becomes too much out of date.</p>
915 The value corresponds to a version of the Debian manuals,
916 as can be found on the title page or page headers and
917 footers (depending on the format).</p>
920 The version number has four components--major and minor
921 number and major and minor patch level. When the
922 standards change in a way that requires every package to
923 change the major number will be changed. Significant
924 changes that will require work in many packages will be
925 signaled by a change to the minor number. The major patch
926 level will be changed for any change to the meaning of the
927 standards, however small; the minor patch level will be
928 changed when only cosmetic, typographical or other edits
929 which do not change the meaning are made, or changes which
930 do not affect the contents of packages.</p>
933 For package maintainers, only the first 3 digits of the
934 manual version are significant in representing the
935 <em>Standards-Version</em>, and either these 3 digits or
936 the complete 4 digits may be specified.
939 In the past, people specified 4 digits in the
940 Standards-Version field, like `2.3.0.0'. Since any
941 `patch-level changes' don't introduce new policy, it
942 was thought it would be better to relax policy and
943 only require that the first 3 digits are specified. (4
944 digits may still be used if someone wants to do so.)
950 You should regularly, and especially if your package has
951 become out of date, check for the newest Policy Manual
952 available and update your package, if necessary. When your
953 package complies with the new standards you should update the
954 <tt>Standards-Version</tt> source package field and
955 release it.</p></sect1>
959 <heading>Package relationships</heading>
962 Source packages should specify which binary packages they
963 require to be installed or not to be installed in order to
964 build correctly. For example, if building a package
965 requires a certain compiler, then the compiler should be
966 specified as a build-time dependency.
970 It is not be necessary to explicitly specify build-time
971 relationships on a minimal set of packages that are always
972 needed to compile, link and put in a Debian package a
973 standard "Hello World!" program written in C or C++. The
974 required packages are called <em>build-essential</em>, and
975 an informational list can be found in
976 <tt>/usr/share/doc/build-essential/list</tt> (which is
977 contained in the <tt>build-essential</tt> package).
981 When specifying the set of build-time dependencies, one
982 should list only those packages explicitly required by the
983 build. It is not necessary to list packages which are
984 required merely because some other package in the list of
985 build-time dependencies depends on them. The reason is
986 that dependencies change, and you should list only those
987 <em>you</em> need. What others need is their business.
991 If build-time dependencies are specified, it must be
992 possible to build the package and produce working binaries
993 on a system with the build-essential packages installed
994 and satisfying the build-time relationships (including any
995 implied relationships). This
996 means in particular that version clauses should be used
997 rigorously in build-time relationships so that one cannot
998 produce bad or inconsistently configured packages when the
999 relationships are properly satisfied.
1003 <heading>Changes to the upstream sources</heading>
1006 If changes to the source code are made that are generally
1007 applicable, they should be sent to the upstream authors
1008 in whatever form they prefer so as to be included in the
1009 upstream version of the package.</p>
1012 If you need to configure the package differently for
1013 Debian or for Linux, and the upstream source doesn't
1014 provide a way to configure it the way you need to, you
1015 should add such configuration facilities (for example, a new
1016 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
1017 the patch to the upstream authors, with the default set to
1018 the way they originally had it. You can then easily
1019 override the default in your <tt>debian/rules</tt> or
1020 wherever is appropriate.</p>
1023 You should make sure that the <prgn>configure</prgn> utility
1024 detects the correct architecture specification string
1025 (refer to <ref id="arch-spec"> for details).</p>
1028 If you need to edit a <prgn>Makefile</prgn> where
1029 GNU-style <prgn>configure</prgn> scripts are used, you
1030 should edit the <tt>.in</tt> files rather than editing the
1031 <prgn>Makefile</prgn> directly. This allows the user to
1032 reconfigure the package if necessary. You should
1033 <em>not</em> configure the package and edit the generated
1034 <prgn>Makefile</prgn>! This makes it impossible for
1035 someone else to later reconfigure the package.</p></sect1>
1039 <heading>Documenting your changes</heading>
1042 You should document your changes and updates to the source
1043 package properly in the <tt>debian/changelog</tt> file. (Note
1044 that mistakes in changelogs are usually best rectified by
1045 making a new changelog entry rather than "rewriting history"
1046 by editing old changelog entries)</p>
1049 A copy of the file which will be installed in
1050 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1051 in <tt>debian/copyright</tt>.</p>
1054 In non-experimental packages you must only use a format for
1055 <tt>debian/changelog</tt> which is supported by the most
1056 recent released version of <prgn>dpkg</prgn>. If your
1057 format is not supported and there is general support for
1058 it you should contact the <prgn>dpkg</prgn> maintainer to
1059 have the parser script for your format included in the
1060 <prgn>dpkg</prgn> package. (You will need to agree that
1061 the parser and its manpage may be distributed under the
1062 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1067 <heading>Error trapping in makefiles</heading>
1070 When <prgn>make</prgn> invokes a command in a makefile
1071 (including your package's upstream makefiles and the
1072 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1073 means that <tt>sh</tt>'s usual bad error handling
1074 properties apply: if you include a miniature script as one
1075 of the commands in your makefile you'll find that if you
1076 don't do anything about it then errors are not detected
1077 and <prgn>make</prgn> will blithely continue after
1081 Every time you put more than one shell command (this
1082 includes using a loop) in a makefile command you
1083 must make sure that errors are trapped. For
1084 simple compound commands, such as changing directory and
1085 then running a program, using <tt>&&</tt> rather
1086 than semicolon as a command separator is sufficient. For
1087 more complex commands including most loops and
1088 conditionals you should include a separate <tt>set -e</tt>
1089 command at the start of every makefile command that's
1090 actually one of these miniature shell scripts.</p></sect1>
1094 <heading>Obsolete constructs and libraries</heading>
1097 The include file <prgn><varargs.h></prgn> is
1098 provided to support end-users compiling very old software;
1099 the library <tt>libtermcap</tt> is provided to support the
1100 execution of software which has been linked against it
1101 (either old programs or those such as Netscape which are
1102 only available in binary form).</p>
1105 Debian packages should be ported to include
1106 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1111 <chapt><heading>The Operating System</heading>
1115 <heading>File system hierarchy</heading>
1119 <heading>Linux File system Structure</heading>
1122 The location of all installed files and directories must
1123 comply with the Linux File system Hierarchy Standard
1124 (FHS). The latest version of this document can be found
1125 alongside this manual or on
1126 <url id="http://www.pathname.com/fhs/">.<footnote>
1127 <p>The Debian distribution currently distributes a draft
1128 version of FHS 2.1 because several significant details
1129 have changed between the currently released 2.0
1130 version and the to-be-released 2.1 version.</p>
1132 Specific questions about following the standard may be
1133 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1134 Quinlan, the FHS coordinator, at
1135 <email>quinlan@pathname.com</email>.</p></sect1>
1139 <heading>Site-specific programs</heading>
1142 As mandated by the FHS, packages must not place any
1143 files in <tt>/usr/local</tt>, either by putting them in
1144 the file system archive to be unpacked by <prgn>dpkg</prgn>
1145 or by manipulating them in their maintainer scripts.</p>
1148 However, the package may create empty directories below
1149 <tt>/usr/local</tt> so that the system administrator knows
1150 where to place site-specific files. These directories
1151 should be removed on package removal if they are
1155 Note, that this applies only to directories <em>below</em>
1156 <tt>/usr/local</tt>, not <em>in</em>
1157 <tt>/usr/local</tt>. Packages must not create sub-directories
1158 in the directory <tt>/usr/local</tt> itself, except those listed in
1159 FHS, section 4.6. However, you may create directories
1160 below them as you wish. You must not remove any of the
1161 directories listed in 4.6, even if you created them.</p>
1164 Since <tt>/usr/local</tt> can be mounted read-only from a
1165 remote server, these directories must be created and
1166 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1167 maintainer scripts. These scripts must not fail if either
1168 of these operations fail. (In the future, it will be
1169 possible to tell <prgn>dpkg</prgn> not to unpack files
1170 matching certain patterns, so that the directories can be
1171 included in the <tt>.deb</tt> packages and system
1172 administrators who do not wish these directories in
1173 /usr/local do not need to have them.)</p>
1176 For example, the <prgn>emacs</prgn> package will contain
1178 mkdir -p /usr/local/lib/emacs/site-lisp || true
1180 in the <tt>postinst</tt> script, and
1182 rmdir /usr/local/lib/emacs/site-lisp && \
1183 rmdir /usr/local/lib/emacs || \
1186 in the <tt>prerm</tt> script.</p>
1189 If you do create a directory in <tt>/usr/local</tt> for
1190 local additions to a package, you should ensure that
1191 settings in <tt>/usr/local</tt> take precedence over the
1192 equivalents in <tt>/usr</tt>.</p>
1195 However, because '/usr/local' and its contents are for
1196 exclusive use of the local administrator, a package must
1197 not rely on the presence or absence of files or
1198 directories in '/usr/local' for normal operation.</p>
1201 The <tt>/usr/local</tt> directory itself and all the
1202 subdirectories created by the package should (by default) have
1203 permissions 2775 (group-writable and set-group-id) and be
1204 owned by <tt>root.staff</tt>.</p>
1209 <heading>Users and groups</heading>
1212 The Debian system can be configured to use either plain or
1213 shadow passwords.</p>
1216 Some user ids (UIDs) and group ids (GIDs) are reserved
1217 globally for use by certain packages. Because some packages
1218 need to include files which are owned by these users or
1219 groups, or need the ids compiled into binaries, these ids
1220 must be used on any Debian system only for the purpose for
1221 which they are allocated. This is a serious restriction, and
1222 we should avoid getting in the way of local administration
1223 policies. In particular, many sites allocate users and/or
1224 local system groups starting at 100.</p>
1227 Apart from this we should have dynamically allocated ids,
1228 which should by default be arranged in some sensible
1229 order--but the behavior should be configurable.</p>
1232 Packages other than <tt>base-passwd</tt> must not modify
1233 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
1234 <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
1237 The UID and GID ranges are as follows:
1242 Globally allocated by the Debian project, the
1243 same on every Debian system. These ids will appear in
1244 the <tt>passwd</tt> and <tt>group</tt> files of all
1245 Debian systems, new ids in this range being added
1246 automatically as the <tt>base-passwd</tt> package is
1250 Packages which need a single statically allocated uid
1251 or gid should use one of these; their maintainers
1252 should ask the <tt>base-passwd</tt> maintainer for
1259 Dynamically allocated system users and groups.
1260 Packages which need a user or group, but can have this
1261 user or group allocated dynamically and differently on
1262 each system, should use `<tt>adduser --system</tt>' to
1263 create the group and/or user. <prgn>adduser</prgn>
1264 will check for the existence of the user or group, and
1265 if necessary choose an unused id based on the ranged
1266 specified in <tt>adduser.conf</tt>.</p></item>
1269 <tag>1000-29999:</tag>
1272 Dynamically allocated user accounts. By default
1273 <prgn>adduser</prgn> will choose UIDs and GIDs for
1274 user accounts in this range, though
1275 <tt>adduser.conf</tt> may be used to modify this
1279 <tag>30000-59999:</tag>
1281 <p>Reserved.</p></item>
1284 <tag>60000-64999:</tag>
1287 Globally allocated by the Debian project, but only
1288 created on demand. The ids are allocated centrally and
1289 statically, but the actual accounts are only created
1290 on users' systems on demand.</p>
1293 These ids are for packages which are obscure or which
1294 require many statically-allocated ids. These packages
1295 should check for and create the accounts in
1296 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1297 <prgn>adduser</prgn> if it has this facility) if
1298 necessary. Packages which are likely to require
1299 further allocations should have a `hole' left after
1300 them in the allocation, to give them room to
1304 <tag>65000-65533:</tag>
1306 <p>Reserved.</p></item>
1311 <p>User `<tt>nobody</tt>.'</p></item>
1317 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1318 because it is the error return sentinel value.</p>
1323 <sect id="sysvinit">
1324 <heading>System run levels</heading>
1327 <sect1 id="/etc/init.d">
1328 <heading>Introduction</heading>
1331 The <tt>/etc/init.d</tt> directory contains the scripts
1332 executed by <prgn>init</prgn> at boot time and when init
1333 state (or `runlevel') is changed (see <manref name="init"
1337 There are at least two different, yet functionally
1338 equivalent, ways of handling these scripts. For the sake
1339 of simplicity, this document describes only the symbolic
1340 link method. However, it must not be assumed that this
1341 method is being used, and any manipulation of the various
1342 runlevel behaviours must be performed using
1343 <prgn>update-rc.d</prgn> as described below and not by
1344 manually installing symlinks. For information on the
1345 implementation details of the other method, implemented in
1346 the <tt>file-rc</tt> package, please refer to the
1347 documentation of that package.</p>
1350 These scripts are referenced by symbolic links in
1351 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1352 changing runlevels, <prgn>init</prgn> looks in the
1353 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1354 it should execute, where <var>n</var> is the runlevel that
1355 is being changed to, or `S' for the boot-up scripts.</p>
1358 The names of the links all have the form
1359 <tt>S<var>mm</var><var>script</var></tt> or
1360 <tt>K<var>mm</var><var>script</var></tt> where
1361 <var>mm</var> is a two-digit number and <var>script</var>
1362 is the name of the script (this should be the same as the
1363 name of the actual script in <tt>/etc/init.d</tt>.</p>
1366 When <prgn>init</prgn> changes runlevel first the targets
1367 of the links whose names starting with a <tt>K</tt> are
1368 executed, each with the single argument <tt>stop</tt>,
1369 followed by the scripts prefixed with an <tt>S</tt>, each
1370 with the single argument <tt>start</tt>. The <tt>K</tt>
1371 links are responsible for killing services and the
1372 <tt>S</tt> link for starting services upon entering the
1376 For example, if we are changing from runlevel 2 to
1377 runlevel 3, init will first execute all of the <tt>K</tt>
1378 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1379 all of the <tt>S</tt> prefixed scripts. The links
1380 starting with <tt>K</tt> will cause the referred-to file
1381 to be executed with an argument of <tt>stop</tt>, and the
1382 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1385 The two-digit number <var>mm</var> is used to decide which
1386 order to start and stop things in--low-numbered links have
1387 their scripts run first. For example, the <tt>K20</tt>
1388 scripts will be executed before the <tt>K30</tt> scripts.
1389 This is used when a certain service must be started before
1390 another. For example, the name server <prgn>bind</prgn>
1391 might need to be started before the news server
1392 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1393 access lists. In this case, the script that starts
1394 <prgn>bind</prgn> would have a lower number than the
1395 script that starts <prgn>inn</prgn> so that it runs first:
1404 <heading>Writing the scripts</heading>
1407 Packages that include daemons for system services should
1408 place scripts in <tt>/etc/init.d</tt> to start or stop
1409 services at boot time or during a change of runlevel.
1410 These scripts should be named
1411 <tt>/etc/init.d/<var>package</var></tt>, and they should
1412 accept one argument, saying what to do:
1415 <tag><tt>start</tt></tag>
1416 <item><p>start the service,</p></item>
1418 <tag><tt>stop</tt></tag>
1419 <item><p>stop the service,</p></item>
1421 <tag><tt>restart</tt></tag>
1422 <item><p>stop and restart the service,</p></item>
1424 <tag><tt>reload</tt></tag>
1425 <item><p>cause the configuration of the service to be
1426 reloaded without actually stopping and restarting
1427 the service,</p></item>
1429 <tag><tt>force-reload</tt></tag> <item><p>cause the
1430 configuration to be reloaded if the service supports
1431 this, otherwise restart the service.</p></item>
1434 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1435 <tt>force-reload</tt> options should be supported by all
1436 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1437 option is optional.</p>
1440 The <tt>init.d</tt> scripts should ensure that they will
1441 behave sensibly if invoked with <tt>start</tt> when the
1442 service is already running, or with <tt>stop</tt> when it
1443 isn't, and that they don't kill unfortunately-named user
1444 processes. The best way to achieve this is usually to use
1445 <prgn>start-stop-daemon</prgn>.</p>
1448 If a service reloads its configuration automatically (as
1449 in the case of <prgn>cron</prgn>, for example), the
1450 <tt>reload</tt> option of the <tt>init.d</tt> script
1451 should behave as if the configuration has been reloaded
1455 These scripts should not fail obscurely when the
1456 configuration files remain but the package has been
1457 removed, as configuration files remain on the system after
1458 the package has been removed. Only when <prgn>dpkg</prgn>
1459 is executed with the <tt>--purge</tt> option will
1460 configuration files be removed. In particular, the init
1461 script itself is usually a configuration file (see
1462 <ref id="init.d notes">), and will remain on the system if
1463 the package is removed but not purged. Therefore, you
1464 should include a <tt>test</tt> statement at the top of the
1467 test -f <var>program-executed-later-in-script</var> || exit 0
1472 <heading>Managing the links</heading>
1475 The program <prgn>update-rc.d</prgn> is provided to make
1476 it easier for package maintainers to arrange for the
1477 proper creation and removal of
1478 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1479 functional equivalent if another method is being used.
1480 This may be used by maintainers in their packages'
1481 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1484 You must use this script to make changes to
1485 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1486 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1487 in the actual archive or manually create or remove the
1488 symbolic links in maintainer scripts. (The latter will
1489 fail if an alternative method of maintaining runlevel
1490 information is being used.)</p>
1493 By default <prgn>update-rc.d</prgn> will start services in
1494 each of the multi-user state runlevels (2, 3, 4, and 5)
1495 and stop them in the halt runlevel (0), the single-user
1496 runlevel (1) and the reboot runlevel (6). The system
1497 administrator will have the opportunity to customize
1498 runlevels by either running <prgn>update-rc.d</prgn>, by
1499 simply adding, moving, or removing the symbolic links in
1500 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1501 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1502 <tt>file-rc</tt> method is being used.</p>
1505 To get the default behavior for your package, put in your
1506 <tt>postinst</tt> script
1508 update-rc.d <var>package</var> defaults >/dev/null
1510 and in your <tt>postrm</tt>
1512 if [ purge = "$1" ]; then
1513 update-rc.d <var>package</var> remove >/dev/null
1518 This will use a default sequence number of 20. If it does
1519 not matter when or in which order the script is run, use
1520 this default. If it does, then you should talk to the
1521 maintainer of the <prgn>sysvinit</prgn> package or post to
1522 <tt>debian-devel</tt>, and they will help you choose a
1526 For more information about using <tt>update-rc.d</tt>,
1527 please consult its manpage <manref name="update-rc.d"
1528 section="8">.</p></sect1>
1532 <heading>Boot-time initialization</heading>
1535 There used to be another directory, <tt>/etc/rc.boot</tt>,
1536 which contained scripts which were run once per machine
1537 boot. This has been deprecated in favour of links from
1538 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1539 described in <ref id="/etc/init.d">. Packages must not
1540 place files in <tt>/etc/rc.boot</tt>.</p>
1542 <sect1 id="init.d notes">
1543 <heading>Notes</heading>
1546 <em>Do not</em> include the
1547 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1548 <tt>.deb</tt> file system archive! <em>This will cause
1549 problems!</em> You must create them with
1550 <prgn>update-rc.d</prgn>, as above.</p>
1553 <em>Do not</em> include the
1554 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1555 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1556 problems!</em> You should, however, treat the
1557 <tt>/etc/init.d</tt> scripts as configuration files,
1558 either by marking them as conffiles or managing them
1559 correctly in the maintainer scripts (see
1560 <ref id="config files">). (This is important since we want
1561 to give the local system administrator the chance to adapt
1562 the scripts to the local system--e.g., to disable a
1563 service without de-installing the package, or to specify
1564 some special command line options when starting a
1565 service--while making sure her changes aren't lost during
1566 the next package upgrade.)</p>
1570 <heading>Example</heading>
1573 The <prgn>bind</prgn> DNS (nameserver) package wants to
1574 make sure that the nameserver is running in multiuser
1575 runlevels, and is properly shut down with the system. It
1576 puts a script in <tt>/etc/init.d</tt>, naming the script
1577 appropriately <tt>bind</tt>. As you can see, the script
1578 interprets the argument <tt>reload</tt> to send the
1579 nameserver a <tt>HUP</tt> signal (causing it to reload its
1580 configuration); this way the user can say
1581 <tt>/etc/init.d/bind reload</tt> to reload the name
1588 # Original version by Robert Leslie
1589 # <rob@mars.org>, edited by iwj and cs
1591 test -x /usr/sbin/named || exit 0
1595 echo -n "Starting domain name service: named"
1596 start-stop-daemon --start --quiet --exec /usr/sbin/named
1600 echo -n "Stopping domain name service: named"
1601 start-stop-daemon --stop --quiet \
1602 --pidfile /var/run/named.pid --exec /usr/sbin/named
1606 echo -n "Restarting domain name service: named"
1607 start-stop-daemon --stop --quiet \
1608 --pidfile /var/run/named.pid --exec /usr/sbin/named
1609 start-stop-daemon --start --verbose --exec /usr/sbin/named
1612 force-reload|reload)
1613 echo -n "Reloading configuration of domain name service: named"
1614 start-stop-daemon --stop --signal 1 --quiet \
1615 --pidfile /var/run/named.pid --exec /usr/sbin/named
1619 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1628 Another example on which to base your <tt>/etc/init.d</tt>
1629 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1632 If this package is happy with the default setup from
1633 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1634 and having named running in all runlevels, it can say in
1635 its <tt>postinst</tt>:
1637 update-rc.d bind defaults >/dev/null
1639 And in its <tt>postrm</tt>, to remove the links when the
1642 if [ purge = "$1" ]; then
1643 update-rc.d bind remove >/dev/null
1649 <heading>Cron jobs</heading>
1652 Packages must not modify the configuration file
1653 <tt>/etc/crontab</tt>, and they must not modify the files in
1654 <tt>/var/spool/cron/crontabs</tt>.</p>
1657 If a package wants to install a job that has to be executed
1658 via cron, it should place a file with the name if the
1659 package in one of the following directories:
1665 As these directory names imply, the files within them are
1666 executed on a daily, weekly, or monthly basis,
1667 respectively. The exact times are listed in
1668 <tt>/etc/crontab</tt>.</p>
1671 All files installed in any of these directories must be
1672 scripts (shell scripts, Perl scripts, etc.) so that they can
1673 easily be modified by the local system administrator. In
1674 addition, they should be treated as configuration files.</p>
1677 If a certain job has to be executed more frequently than
1678 daily, the package should install a file
1679 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1680 the same syntax as <tt>/etc/crontab</tt> and is processed by
1681 <prgn>cron</prgn> automatically. The file must also be
1682 treated as a configuration file. (Note, that entries in the
1683 <tt>/etc/cron.d</tt> directory are not handled by
1684 <prgn>anacron</prgn>. Thus, you should only use this
1685 directory for jobs which may be skipped if the system is not
1689 The scripts or crontab entries in these directories should
1690 check if all necessary programs are installed before they
1691 try to execute them. Otherwise, problems will arise when a
1692 package was removed but not purged since configuration files
1693 are kept on the system in this situation.</p>
1697 <heading>Console messages</heading>
1700 This section describes different formats for messages
1701 written to standard output by the <tt>/etc/init.d</tt>
1702 scripts. The intent is to improve the consistency of
1703 Debian's startup and shutdown look and feel.</p>
1706 Please look very careful at the details. We want to get the
1707 messages to look exactly the same way concerning spaces,
1708 punctuation, and case of letters.</p>
1711 Here is a list of overall rules that you should use when you
1712 create output messages. They can be useful if you have a
1713 non-standard message that isn't covered in the sections
1720 Every message should cover one line, start with a
1721 capital letter and end with a period `.'.</p></item>
1726 If you want to express that the computer is working on
1727 something (performing a specific task, not starting or
1728 stopping a program), we use an ``ellipsis'', namely
1729 three dots `...'. Note that we don't insert spaces in
1730 front of or behind the dots. If the task has been
1731 completed we write `done.' and a line feed.</p></item>
1736 Design your messages as if the computer is telling you
1737 what he is doing (let him be polite :-) but don't
1738 mention ``him'' directly. For example, if you think
1741 I'm starting network daemons: nfsd mountd.
1745 Starting network daemons: nfsd mountd.
1746 </example></p></item>
1750 The following formats should be used</p>
1755 <p>when daemons get started.</p>
1758 Use this format if your script starts one or more
1759 daemons. The output should look like this (a single
1760 line, no leading spaces):
1762 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1764 The <description> should describe the subsystem
1765 the daemon or set of daemons are part of, while
1766 <daemon-1> up to <daemon-n> denote each
1767 daemon's name (typically the file name of the
1771 For example, the output of /etc/init.d/lpd would look like:
1773 Starting printer spooler: lpd.
1777 This can be achieved by saying
1779 echo -n "Starting printer spooler: lpd"
1780 start-stop-daemon --start --quiet lpd
1783 in the script. If you have more than one daemon to
1784 start, you should do the following:
1786 echo -n "Starting remote file system services:"
1787 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1788 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1789 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1792 This makes it possible for the user to see what takes
1793 so long and when the final daemon has been
1794 started. You should be careful where to put spaces: In the
1795 example above the system administrator can easily
1796 comment out a line if he don't wants to start a
1797 specific daemon, while the displayed message still
1798 looks good.</p></item>
1802 <p>when something needs to be configured.</p>
1805 If you have to set up different parameters of the
1806 system upon boot up, you should use this format:
1808 Setting <parameter> to `<value>'.
1812 You can use the following echo statement to get the quotes right:
1814 echo "Setting DNS domainname to \`"value"'."
1818 Note that the left quotation mark (`) is different
1819 from the right (').</p></item>
1822 <p>when a daemon is stopped.</p>
1825 When you stop a daemon you should issue a message
1826 similar to the startup message, except that `Starting'
1827 is replaced with `Stopping'.</p>
1830 So stopping the printer daemon will like like this:
1832 Stopping printer spooler: lpd.
1833 </example></p></item>
1836 <p>when something is executed.</p>
1839 There are several examples where you have to run a
1840 program at system startup or shutdown to perform a
1841 specific task. For example, setting the system's clock
1842 via `netdate' or killing all processes when the system
1843 comes down. Your message should like this:
1845 Doing something very useful...done.
1847 You should print the `done.' right after the job has been completed,
1848 so that the user gets informed why he has to wait. You can get this
1851 echo -n "Doing something very useful..."
1855 in your script.</p></item>
1858 <p>when the configuration is reloaded.</p>
1861 When a daemon is forced to reload its configuration
1862 files you should use the following format:
1864 Reloading <daemon's-name> configuration...done.
1865 </example></p></item>
1868 <p>when none of the above rules apply.</p>
1871 If you have to print a message that doesn't fit into
1872 the styles described above, you can use something
1873 appropriate, but please have a look at the overall
1874 rules listed above.</p></item>
1879 <heading>Menus</heading>
1882 Menu entries should follow the current menu policy as
1883 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1884 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1885 or your local mirror. In addition, it is included in the
1886 <tt>debian-policy</tt> package.
1890 The Debian <tt>menu</tt> packages provides a unique
1891 interface between packages providing applications and
1892 documents, and <em>menu programs</em> (either X window
1893 managers or text-based menu programs as
1894 <prgn>pdmenu</prgn>).</p>
1897 All packages that provide applications that need not be
1898 passed any special command line arguments for normal
1899 operation should register a menu entry for those
1900 applications, so that users of the <tt>menu</tt> package
1901 will automatically get menu entries in their window
1902 managers, as well in shells like <tt>pdmenu</tt>.</p>
1905 Please refer to the <em>Debian Menu System</em> document
1906 that comes with the <tt>menu</tt> package for information
1907 about how to register your applications and web
1913 <heading>Multimedia handlers</heading>
1916 Packages which provide the ability to view/show/play,
1917 compose, edit or print MIME types should register themselves
1918 as such following the current MIME support policy as defined
1919 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1920 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1921 or your local mirror. In addition, it is included in the
1922 <tt>debian-policy</tt> package.
1926 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1927 mechanism for encoding files and data streams and providing
1928 meta-information about them, in particular their type (e.g.
1929 audio or video) and format (e.g. PNG, HTML, MP3).
1933 Registration of MIME type handlers allows programs like mail
1934 user agents and web browsers to to invoke these handlers to
1935 view, edit or display MIME types they don't support
1941 <heading>Keyboard configuration</heading>
1944 To achieve a consistent keyboard configuration (i.e., all
1945 applications interpret a keyboard event the same way) all
1946 programs in the Debian distribution must be configured to
1947 comply with the following guidelines.</p>
1950 Here is a list that contains certain keys and their interpretation:
1953 <tag><tt><--</tt></tag>
1954 <item><p>delete the character to the left of the cursor</p></item>
1956 <tag><tt>Delete</tt></tag>
1957 <item><p>delete the character to the right of the cursor</p></item>
1959 <tag><tt>Control+H</tt></tag>
1960 <item><p>emacs: the help prefix</p></item>
1963 The interpretation of any keyboard events should be independent
1964 of the terminal that's used, be it a virtual console, an X
1965 terminal emulator, an rlogin/telnet session, etc.</p>
1968 The following list explains how the different programs
1969 should be set up to achieve this:</p>
1972 <list compact="compact">
1973 <item><p>`<tt><--</tt>' generates KB_Backspace in
1976 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1980 X translations are set up to make KB_Backspace
1981 generate ASCII DEL, and to make KB_Delete generate
1982 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1983 the `delete character' key). This must be done by
1984 loading the resources using xrdb on all local X
1985 displays, not using the application defaults, so that
1986 the translation resources used correspond to the
1987 xmodmap settings.</p></item>
1991 The Linux console is configured to make
1992 `<tt><--</tt>' generate DEL, and `Delete' generate
1993 <tt>ESC [ 3 ~</tt> (this is the case at the
1997 X applications are configured so that Backspace
1998 deletes left, and Delete deletes right. Motif
1999 applications already work like this.</p></item>
2001 <item><p>stty erase <tt>^?</tt> .</p></item>
2004 The `xterm' terminfo entry should have <tt>ESC [ 3
2005 ~</tt> for kdch1, just like TERM=linux and
2006 TERM=vt220.</p></item>
2009 Emacs is programmed to map KB_Backspace or the `stty
2010 erase' character to delete-backward-char, and
2011 KB_Delete or kdch1 to delete-forward-char, and
2012 <tt>^H</tt> to help as always.</p></item>
2015 Other applications use the `stty erase' character and
2016 kdch1 for the two delete keys, with ASCII DEL being
2017 `delete previous character' and kdch1 being `delete
2018 character under cursor'.</p></item>
2022 This will solve the problem except for:</p>
2025 <list compact="compact">
2027 Some terminals have a <tt><--</tt> key that cannot
2028 be made to produce anything except <tt>^H</tt>. On
2029 these terminals Emacs help will be unavailable on
2030 <tt>^H</tt> (assuming that the `stty erase' character
2031 takes precedence in Emacs, and has been set
2032 correctly). M-x help or F1 (if available) can be used
2036 Some operating systems use <tt>^H</tt> for stty erase.
2037 However, modern telnet versions and all rlogin
2038 versions propagate stty settings, and almost all UNIX
2039 versions honour stty erase. Where the stty settings
2040 are not propagated correctly things can be made to
2041 work by using stty manually.</p></item>
2044 Some systems (including previous Debian versions) use
2045 xmodmap to arrange for both <tt><--</tt> and Delete
2046 to generate KB_Delete. We can change the behavior
2047 of their X clients via the same X resources that we
2048 use to do it for our own, or have our clients be
2049 configured via their resources when things are the
2050 other way around. On displays configured like this
2051 Delete will not work, but <tt><--</tt>
2055 Some operating systems have different kdch1 settings
2056 in their terminfo for xterm and others. On these
2057 systems the Delete key will not work correctly when
2058 you log in from a system conforming to our policy, but
2059 <tt><--</tt> will.</p></item>
2066 <heading>Environment variables</heading>
2069 A program must not depend on environment variables to get
2070 reasonable defaults. (That's because these environment
2071 variables would have to be set in a system-wide
2072 configuration file like /etc/profile, which is not supported
2076 If a program usually depends on environment variables for its
2077 configuration, the program should be changed to fall back to
2078 a reasonable default configuration if these environment
2079 variables are not present. If this cannot be done easily
2080 (e.g., if the source code of a non-free program is not
2081 available), the program must be replaced by a small
2082 `wrapper' shell script which sets the environment variables
2083 if they are not already defined, and calls the original program.</p>
2086 Here is an example of a wrapper script for this purpose:
2090 BAR=${BAR:-/var/lib/fubar}
2092 exec /usr/lib/foo/foo "$@"
2096 Furthermore, as <tt>/etc/profile</tt> is a configuration
2097 file of the <prgn>bash</prgn> package, other packages must not
2098 put any environment variables or other commands into that
2103 <heading>Files</heading>
2107 <heading>Binaries</heading>
2110 Two different packages must not install programs with
2111 different functionality but with the same filenames. (The
2112 case of two programs having the same functionality but
2113 different implementations is handled via `alternatives.')
2114 If this case happens, one of the programs must be
2115 renamed. The maintainers should report this to the
2116 developers' mailing and try to find a consensus about
2117 which package will have to be renamed. If a consensus can
2118 not be reached, <em>both</em> programs must be
2122 Generally the following compilation parameters should be used:
2125 CFLAGS = -O2 -Wall # sane warning options vary between programs
2127 install -s # (or use strip on the files in debian/tmp)
2131 Note that by default all installed binaries should be stripped,
2132 either by using the <tt>-s</tt> flag to
2133 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2134 the binaries after they have been copied into
2135 <tt>debian/tmp</tt> but before the tree is made into a
2139 The <tt>-N</tt> flag should not be used. On a.out systems
2140 it may have been useful for some very small binaries, but
2141 for ELF it has no good effect.</p>
2144 Debugging symbols are useful for error diagnosis,
2145 investigation of core dumps (which may be submitted by users
2146 in bug reports), or testing and developing the
2147 software. Therefore it is recommended to support building
2148 the package with debugging information through the following
2149 interface: If the environment variable
2150 <tt>DEB_BUILD_OPTIONS</tt> contains the string
2151 <tt>debug</tt>, compile the software with debugging
2152 information (usually this involves adding the <tt>-g</tt>
2153 flag to <tt>CFLAGS</tt>). This allows the generation of a
2154 build tree with debugging information. If the environment
2155 variable <tt>DEB_BUILD_OPTIONS</tt> contains the string
2156 <tt>nostrip</tt>, do not strip the files at installation
2157 time. This allows to generate a package with debugging
2158 information included. The following makefile snippet is only
2159 an example how to test for either condition:
2162 Rationale: Building by default with -g causes more
2163 wasted CPU cycles since the information is stripped away
2164 anyway. The package can by default build without -g if
2165 it also provides a mechanism to easily be rebuilt with
2166 debugging information. This can be done by providing a
2167 "build-debug" make target, or allowing the user to
2168 specify "BUILD_DEBUG=yes" in the environment while
2169 compiling that package.
2171 <p>Now this has several added benefits:
2175 It is actually easier to build debugging bins and
2176 libraries this way (no more editing debian/rules
2177 or similar) since it provides a documented way of
2178 getting this type of build.</p>
2182 There will be much less wasted cpu time for the
2183 autobuilders since not having debugging
2184 information (and hence also not having to strip
2185 it) will increase the speed of compiles. This
2186 skips an entire pass of the compiler,
2197 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
2199 ifneq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
2206 It is up to the package maintainer to decide what
2207 compilation options are best for the package. Certain
2208 binaries (such as computationally-intensive programs) will
2209 function better with certain flags (<tt>-O3</tt>, for
2210 example); feel free to use them. Please use good judgment
2211 here. Don't use flags for the sake of it; only use them
2212 if there is good reason to do so. Feel free to override
2213 the upstream author's ideas about which compilation
2214 options are best--they are often inappropriate for our
2215 environment.</p></sect>
2219 <heading>Libraries</heading>
2222 All libraries must have a shared version in the lib
2223 package and a static version in the lib-dev package. The
2224 shared version must be compiled with <tt>-fPIC</tt>, and
2225 the static version must not be. In other words, each
2226 <tt>*.c</tt> file will need to be compiled twice.</p>
2229 You must specify the gcc option <tt>-D_REENTRANT</tt>
2230 when building a library (either static or shared) to make
2231 the library compatible with LinuxThreads.</p>
2234 Note that all installed shared libraries should be
2237 strip --strip-unneeded <your-lib>
2239 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2240 only the symbols which aren't needed for relocation
2241 processing.) Shared libraries can function perfectly well
2242 when stripped, since the symbols for dynamic linking are
2243 in a separate part of the ELF object file.</p>
2246 Note that under some circumstances it may be useful to
2247 install a shared library unstripped, for example when
2248 building a separate package to support debugging.
2252 An ever increasing number of packages are using libtool to
2253 do their linking. The latest GNU libtools (>= 1.3a) can take
2254 advantage of the metadata in the installed libtool archive
2255 files (`*.la'). The main advantage of libtool's .la files is
2256 that it allows libtool to store and subsequently access
2257 metadata with respect to the libraries it builds. libtool
2258 will search for those files, which contain a lot of useful
2259 information about a library (e.g. dependency libraries for
2260 static linking). Also, they're <em>essential</em> for
2261 programs using libltdl.
2265 Certainly libtool is fully capable of linking against shared
2266 libraries which don't have .la files, but being a mere shell
2267 script it can add considerably to the build time of a
2268 libtool using package if that shell-script has to derive all
2269 this information from first principles for each library every
2270 time it is linked. With the advent of libtool-1.4 (and to a
2271 lesser extent libtool-1.3), the .la files will also store
2272 information about inter-library dependencies which cannot
2273 necessarily be derived after the .la file is deleted.
2277 Packages that use libtool to create shared libraries should
2278 include the <em>.la</em> files in the <em>-dev</em>
2279 packages, with the exception that if the package relies on
2280 libtool's <em>libltdl</em> library, in which case the .la
2281 files must go in the run-time library package. This is a
2282 good idea in general, and especially for static linking
2287 You must make sure that you use only released versions of
2288 shared libraries to build your packages; otherwise other
2289 users will not be able to run your binaries
2290 properly. Producing source packages that depend on
2291 unreleased compilers is also usually a bad
2298 <heading>Shared libraries</heading>
2301 Packages involving shared libraries should be split up
2302 into several binary packages.</p>
2305 For a straightforward library which has a development
2306 environment and a runtime kit including just shared
2307 libraries you need to create two packages:
2308 <tt><var>libraryname</var><var>soname</var></tt>
2309 (<var>soname</var> is the shared object name of the shared
2310 library--it's the thing that has to match exactly between
2311 building an executable and running it for the dynamic
2312 linker to be able run the program; usually the
2313 <var>soname</var> is the major number of the library) and
2314 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2317 If you prefer only to support one development version at a
2318 time you may name the development package
2319 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2320 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2321 ensure that the user only installs one development version
2322 at a time (after all, different development versions are
2323 likely to have the same header files in them, causing a
2324 filename clash if both are installed). Typically the
2325 development version should also have an exact version
2326 dependency on the runtime library, to make sure that
2327 compilation and linking happens correctly.</p>
2330 Packages which use the shared library should have a
2331 dependency on the name of the shared library package,
2332 <tt><var>libraryname</var><var>soname</var></tt>. When
2333 the <var>soname</var> changes you can have both versions
2334 of the library installed while moving from the old library
2338 If your package has some run-time support programs which
2339 use the shared library you must not put them in
2340 the shared library package. If you do that then you won't
2341 be able to install several versions of the shared library
2342 without getting filename clashes. Instead, either create
2343 a third package for the runtime binaries (this package
2344 might typically be named
2345 <tt><var>libraryname</var>-runtime</tt>--note the absence
2346 of the <var>soname</var> in the package name) or if the
2347 development package is small include them in there.</p>
2350 If you have several shared libraries built from the same
2351 source tree you may lump them all together into a single
2352 shared library package, provided that you change all their
2353 <var>soname</var>s at once (so that you don't get filename
2354 clashes if you try to install different versions of the
2355 combined shared libraries package).</p>
2358 You should follow the directions in the <em>Debian Packaging
2359 Manual</em> for putting the shared library in its package,
2360 and you must include a <tt>shlibs</tt> control area
2361 file with details of the dependencies for packages which
2362 use the library.</p>
2365 Shared libraries should not be installed
2366 executable, since <prgn>ld.so</prgn> does not require this
2367 and trying to execute a shared library results in a core
2372 <heading>Scripts</heading>
2375 All command scripts, including the package maintainer
2376 scripts inside the package and used by <prgn>dpkg</prgn>,
2377 should have a <tt>#!</tt> line naming the shell to be used
2378 to interpret them.</p>
2381 In the case of Perl scripts this should be
2382 <tt>#!/usr/bin/perl</tt>.</p>
2385 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2386 should almost certainly start with <tt>set -e</tt> so that
2387 errors are detected. Every script should use
2388 <tt>set -e</tt> or check the exit status of <em>every</em>
2392 The standard shell interpreter `<tt>/bin/sh</tt>' can be a
2393 symbolic link to any POSIX compatible shell. Thus, shell
2394 scripts specifying `<tt>/bin/sh</tt>' as interpreter should
2395 only use POSIX features. If a script requires non-POSIX
2396 features from the shell interpreter, the appropriate shell
2397 must be specified in the first line of the script (e.g.,
2398 `<tt>#!/bin/bash</tt>') and the package must depend on
2399 the package providing the shell (unless the shell package
2400 is marked `Essential', e.g., in the case of
2401 <prgn>bash</prgn>).</p>
2404 You may wish to restrict your script to POSIX features when possible so
2405 that it may use <tt>/bin/sh</tt> as its interpreter. If
2406 your script works with <prgn>ash</prgn>, it's probably
2407 POSIX compliant, but if you are in doubt, use
2408 <tt>/bin/bash</tt>.</p>
2411 Perl scripts should check for errors when making any
2412 system calls, including <tt>open</tt>, <tt>print</tt>,
2413 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2416 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2417 as scripting languages. See <em>Csh Programming
2418 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2419 FAQs. It can be found on
2420 <url id="http://language.perl.com/versus/csh.whynot">, or
2421 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2422 or even on <ftpsite>ftp.cpan.org</ftpsite>
2423 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2424 If an upstream package comes with <prgn>csh</prgn> scripts
2425 then you must make sure that they start with
2426 <tt>#!/bin/csh</tt> and make your package depend on the
2427 <prgn>c-shell</prgn> virtual package.</p>
2430 Any scripts which create files in world-writeable
2431 directories (e.g., in <tt>/tmp</tt>) must use a
2432 mechanism which will fail if a file with the same name
2436 The Debian base distribution provides the
2437 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2438 for use by scripts for this purpose.</p></sect>
2442 <heading>Symbolic links</heading>
2445 In general, symbolic links within a top-level directory
2446 should be relative, and symbolic links pointing from one
2447 top-level directory into another should be absolute. (A
2448 top-level directory is a sub-directory of the root
2452 In addition, symbolic links should be specified as short
2453 as possible, i.e., link targets like `foo/../bar' are
2457 Note that when creating a relative link using
2458 <prgn>ln</prgn> it is not necessary for the target of the
2459 link to exist relative to the working directory you're
2460 running <prgn>ln</prgn> from; nor is it necessary to
2461 change directory to the directory where the link is to be
2462 made. Simply include the string that should appear as the
2463 target of the link (this will be a pathname relative to
2464 the directory in which the link resides) as the first
2465 argument to <prgn>ln</prgn>.</p>
2468 For example, in your <prgn>Makefile</prgn> or
2469 <tt>debian/rules</tt>, do things like:
2471 ln -fs gcc $(prefix)/bin/cc
2472 ln -fs gcc debian/tmp/usr/bin/cc
2473 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2474 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2478 A symbolic link pointing to a compressed file should
2479 always have the same file extension as the referenced
2480 file. (For example, if a file `<tt>foo.gz</tt>' is
2481 referenced by a symbolic link, the filename of the link
2482 has to end with `<tt>.gz</tt>' too, as in
2483 `bar.gz.')</p></sect>
2487 <heading>Device files</heading>
2490 Packages must not include device files in the package file
2494 If a package needs any special device files that are not
2495 included in the base system, it must call
2496 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2497 after asking the user for permission to do so.</p>
2500 Packages must not remove any device files in the
2501 <tt>postrm</tt> or any other script. This is left to the
2502 system administrator.</p>
2505 Debian uses the serial devices
2506 <tt>/dev/tty*</tt>. Programs using the old
2507 <tt>/dev/cu*</tt> devices should be changed to use
2508 <tt>/dev/tty*</tt>.</p>
2511 <sect id="config files">
2512 <heading>Configuration files</heading>
2514 <heading>Definitions</heading>
2517 <tag>configuration file</tag>
2519 A file that affects the operation of program, or
2520 provides site- or host-specific information, or
2521 otherwise customizes the behavior of program.
2522 Typically, configuration files are intended to be
2523 modified by the system administrator (if needed or
2524 desired) to conform to local policy or provide more
2525 useful site-specific behavior.</p>
2528 <tag><tt>conffile</tt></tag>
2530 A file listed in a package's <tt>conffiles</tt>
2531 file, and is treated specially by <prgn>dpkg</prgn>
2532 (see the <em>Debian Packaging Manual</em>).</p>
2538 The distinction between these two is important; they are
2539 not interchangeable concepts. Almost all
2540 <tt>conffiles</tt> are configuration files, but many
2541 configuration files are not <tt>conffiles</tt>.</p>
2544 Note that a script that embeds configuration information
2545 (such as most of the files in <tt>/etc/init.d</tt> and
2546 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2547 configuration file and should be treated as such.</p>
2551 <heading>Location</heading>
2553 Any configuration files created or used by your package
2554 must reside in <tt>/etc</tt>. If there are several you
2555 should consider creating a subdirectory of <tt>/etc</tt>
2556 named after your package.</p>
2559 If your package creates or uses configuration files
2560 outside of <tt>/etc</tt>, and it is not feasible to modify
2561 the package to use the <tt>/etc</tt>, you should still put
2562 the files in <tt>/etc</tt> and create symbolic links to
2563 those files from the location that the package
2568 <heading>Behavior</heading>
2570 Configuration file handling must conform to the following
2574 <p>local changes must be preserved during a package
2578 <p>configuration files must be preserved when the
2579 package is removed, and only deleted when the
2580 package is purged.</p>
2585 The easy way to achieve this behavior is to make the
2586 configuration file a <tt>conffile</tt>. This is
2587 appropriate if it is possible to distribute a default
2588 version that will work for most installations, although
2589 some system administrators may choose to modify it. This
2590 implies that the default version will be part of the
2591 package distribution, and must not be modified by the
2592 maintainer scripts during installation (or at any other
2596 In order to ensure that local changes are preserved
2597 correctly, no package may contain or make hard links to
2601 Rationale: There are two problems with hard links.
2602 The first is that some editors break the link while
2603 editing one of the files, so that the two files may
2604 unwittingly become different. The second is that
2605 <prgn>dpkg</prgn> might break the hard link while
2606 upgrading <tt>conffile</tt>s.
2611 The other way to do it is to via the maintainer scripts.
2612 In this case, the configuration file must not be listed as
2613 a <tt>conffile</tt> and must not be part of the package
2614 distribution. If the existence of a file is required for
2615 the package to be sensibly configured it is the
2616 responsibility of the package maintainer to write scripts
2617 which correctly create, update, maintain and
2618 remove-on-purge the file. These scripts must be idempotent
2619 (i.e. must work correctly if <prgn>dpkg</prgn> needs to
2620 re-run them due to errors during installation or removal),
2621 must cope with all the variety of ways <prgn>dpkg</prgn>
2622 can call maintainer scripts, must not overwrite or
2623 otherwise mangle the user's configuration without asking,
2624 must not ask unnecessary questions (particularly during
2625 upgrades), and otherwise be good citizens.</p>
2628 The scripts are not required to configure every possible option for
2629 the package, but only those necessary to get the package
2630 running on a given system. Ideally the sysadmin should not
2631 have to do any configuration other than that done
2632 (semi-)automatically by the <tt>postinst</tt> script.</p>
2635 A common practice is to create a script called
2636 <tt><var>package</var>-configure</tt> and have the
2637 package's <tt>postinst</tt> call it if and only if the
2638 configuration file does not already exist. In certain
2639 cases it is useful for there to be an example or template
2640 file which the maintainer scripts use. Such files should
2641 be in <tt>/usr/share/doc</tt> if they are examples or
2642 <tt>/usr/lib</tt> if they are templates, and should be
2643 perfectly ordinary <prgn>dpkg</prgn>-handled files
2644 (<em>not</em> <tt>conffiles</tt>).</p>
2647 These two styles of configuration file handling must
2648 not be mixed, for that way lies madness:
2649 <prgn>dpkg</prgn> will ask about overwriting the file
2650 every time the package is upgraded.</p>
2655 <heading>Sharing configuration files</heading>
2657 Packages that are not tagged as <em>conflicting</em> with
2658 each other must not specify the same file as
2659 <tt>conffile</tt>.</p>
2662 The maintainer scripts must not alter the conffile of
2663 <em>any</em> package, including the one the scripts belong
2667 If two or more packages use the same configuration file
2668 and it is reasonable for both to be installed at the same
2669 time, one of these packages must be defined as
2670 <em>owner</em> of the configuration file, i.e. it will be
2671 the package to list that distributes the file and lists it
2672 as a <tt>conffile</tt>. Other packages that use the
2673 configuration file must depend on the owning package if
2674 they require the configuration file to operate. If the
2675 other package will use the configuration file if present,
2676 but is capable of operating without it, no dependency need
2680 If it is desirable for two or more related packages to
2681 share a configuration file <em>and</em> for all of the
2682 related packages to be able to modify that configuration
2683 file, then the following should be done:
2687 have one of the related packages (the "core"
2688 package) manage the configuration file with
2689 maintainer scripts as described in the previous
2693 the core package should also provide a program that
2694 the other packages may use to modify the
2695 configuration file.</p>
2699 the related packages must use the provided program
2700 to make any modifications to the configuration file.
2701 They should either depend on the core package to
2702 guarantee that the configuration modifier program is
2703 available or accept gracefully that they cannot
2704 modify the configuration file if it is not.</p>
2709 Sometimes it's appropriate to create a new package which
2710 provides the basic infrastructure for the other packages
2711 and which manages the shared configuration files. (Check
2712 out the <tt>sgml-base</tt> package as an example.)</p>
2716 <heading>User configuration files ("dotfiles")</heading>
2719 Files in <tt>/etc/skel</tt> will automatically be copied
2720 into new user accounts by <prgn>adduser</prgn>. They
2721 should not be referenced there by any program.</p>
2724 Therefore, if a program needs a dotfile to exist in
2725 advance in <tt>$HOME</tt> to work sensibly that dotfile
2726 should be installed in <tt>/etc/skel</tt> (and listed in
2727 conffiles, if it is not generated and modified dynamically
2728 by the package's installation scripts).</p>
2731 However, programs that require dotfiles in order to
2732 operate sensibly (dotfiles that they do not create
2733 themselves automatically, that is) are a bad thing, and
2734 programs should be configured by the Debian default
2735 installation as close to normal as possible.</p>
2738 Therefore, if a program in a Debian package needs to be
2739 configured in some way in order to operate sensibly that
2740 configuration should be done in a site-wide global
2741 configuration file elsewhere in <tt>/etc</tt>. Only if the
2742 program doesn't support a site-wide default configuration
2743 and the package maintainer doesn't have time to add it
2744 may a default per-user file be placed in
2745 <tt>/etc/skel</tt>.</p>
2748 <tt>/etc/skel</tt> should be as empty as we can make it.
2749 This is particularly true because there is no easy
2750 mechanism for ensuring that the appropriate dotfiles are
2751 copied into the accounts of existing users when a package
2757 <heading>Log files</heading>
2759 The traditional approach to log files has been to set up ad
2760 hoc log rotation schemes using simple shell scripts and
2761 cron. While this approach is highly customizable, it
2762 requires quite a lot of sysadmin work. Even though the
2763 original Debian system helped a little by automatically
2764 installing a system which can be used as a template, this
2765 was deemed not enough.
2769 A better scheme is to use logrotate, a GPL'd program
2770 developed by Red Hat, which centralizes log management. It
2771 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2772 and a directory where packages can drop logrotation info
2773 (<tt>/etc/logrotate.d</tt>).
2777 Log files should usually be named
2778 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2779 log files, or need a separate directory for permissions
2780 reasons (<tt>/var/log</tt> is writable only by
2781 <tt>root</tt>), you should usually create a directory named
2782 <tt>/var/log/<var>package</var></tt>.</p>
2785 Log files must be rotated occasionally so
2786 that they don't grow indefinitely; the best way to do this
2787 is to drop a script into the directory
2788 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2789 logrotate. Here is a good example for a logrotate config
2790 file (for more information see <manref name="logrotate"
2798 /etc/init.d/foo force-reload
2802 Which rotates all files under `/var/log/foo', saves 12
2803 compressed generations, and sends a HUP signal at the end of
2809 Log files should be removed when the package is
2810 purged (but not when it is only removed), by checking the
2811 argument to the <tt>postrm</tt> script (see the <em>Debian
2812 Packaging Manual</em> for details).</p>
2817 <heading>Permissions and owners</heading>
2820 The rules in this section are guidelines for general use.
2821 If necessary you may deviate from the details below.
2822 However, if you do so you must make sure that what is done
2823 is secure and you should try to be as consistent as possible
2824 with the rest of the system. You should probably also
2825 discuss it on <prgn>debian-devel</prgn> first.</p>
2828 Files should be owned by <tt>root.root</tt>, and made
2829 writable only by the owner and universally readable (and
2830 executable, if appropriate).</p>
2833 Directories should be mode 755 or (for group-writability)
2834 mode 2775. The ownership of the directory should be
2835 consistent with its mode--if a directory is mode 2775, it
2836 should be owned by the group that needs write access to
2840 Setuid and setgid executables should be mode 4755 or 2755
2841 respectively, and owned by the appropriate user or group.
2842 They should not be made unreadable (modes like 4711 or
2843 2711 or even 4111); doing so achieves no extra security,
2844 because anyone can find the binary in the freely available
2845 Debian package--it is merely inconvenient. For the same
2846 reason you should not restrict read or execute permissions
2847 on non-set-id executables.</p>
2850 Some setuid programs need to be restricted to particular
2851 sets of users, using file permissions. In this case they
2852 should be owned by the uid to which they are set-id, and
2853 by the group which should be allowed to execute them.
2854 They should have mode 4754; there is no point in making
2855 them unreadable to those users who must not be allowed to
2859 You must not arrange that the system administrator can only
2860 reconfigure the package to correspond to their local
2861 security policy by changing the permissions on a binary.
2862 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2863 to conffiles and other similar objects) have their
2864 permissions reset to the distributed permissions when the
2865 package is reinstalled. Instead you should consider (for
2866 example) creating a group for people allowed to use the
2867 program(s) and making any setuid executables executable
2868 only by that group.</p>
2871 If you need to create a new user or group for your package
2872 there are two possibilities. Firstly, you may need to
2873 make some files in the binary package be owned by this
2874 user or group, or you may need to compile the user or
2875 group id (rather than just the name) into the binary
2876 (though this latter should be avoided if possible, as in
2877 this case you need a statically allocated id).</p>
2880 If you need a statically allocated id, you must ask for a
2881 user or group id from the base system
2882 maintainer, and must not release the package until you
2883 have been allocated one. Once you have been allocated one
2884 you must make the package depend on a version of the base
2885 system with the id present in <tt>/etc/passwd</tt> or
2886 <tt>/etc/group</tt>, or alternatively arrange for your
2887 package to create the user or group itself with the
2888 correct id (using <tt>adduser</tt>) in its pre- or
2889 post-installation script (the latter is to be preferred if
2890 it is possible).</p>
2893 On the other hand, the program might be able to determine the
2894 uid or gid from the group name at runtime, so that a
2895 dynamic id can be used. In this case you should choose an
2896 appropriate user or group name, discussing this on
2897 <prgn>debian-devel</prgn> and checking with the base
2898 system maintainer that it is unique and that they do not
2899 wish you to use a statically allocated id instead. When
2900 this has been checked you must arrange for your package to
2901 create the user or group if necessary using
2902 <prgn>adduser</prgn> in the pre- or post-installation
2903 script (again, the latter is to be preferred if it is
2907 Note that changing the numeric value of an id associated with a name
2908 is very difficult, and involves searching the file system for all
2909 appropriate files. You need to think carefully whether a static or
2910 dynamic id is required, since changing your mind later will cause
2916 <heading>Customized programs</heading>
2918 <sect id="arch-spec">
2919 <heading>Architecture specification strings</heading>
2922 If a program needs to specify an <em>architecture specification
2923 string</em> in some place, the following format should be used:
2925 <arch>-<os>
2927 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2928 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2929 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2930 operating system.</p>
2932 Note, that we don't want to use `<arch>-debian-linux'
2933 to apply to the rule `architecture-vendor-os' since this
2934 would make our programs incompatible to other Linux
2935 distributions. Also note, that we don't use
2936 `<arch>-unknown-linux', since the `unknown' does not
2937 look very good.</p></sect>
2941 <heading>Daemons</heading>
2944 The configuration files <tt>/etc/services</tt>,
2945 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2946 by the <prgn>netbase</prgn> package and may not be modified
2947 by other packages.</p>
2950 If a package requires a new entry in one of these files, the
2951 maintainer should get in contact with the
2952 <prgn>netbase</prgn> maintainer, who will add the entries
2953 and release a new version of the <prgn>netbase</prgn>
2957 The configuration file <tt>/etc/inetd.conf</tt> must not be
2958 modified by the package's scripts except via the
2959 <prgn>update-inetd</prgn> script or the
2960 <prgn>DebianNet.pm</prgn> Perl module.</p>
2963 If a package wants to install an example entry into
2964 <tt>/etc/inetd.conf</tt>, the entry must be preceded with
2965 exactly one hash character (<tt>#</tt>). Such lines are
2966 treated as `commented out by user' by the
2967 <prgn>update-inetd</prgn> script and are not changed or
2968 activated during a package updates.</p></sect>
2972 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2975 Some programs need to create pseudo-ttys. This should be done
2976 using Unix98 ptys if the C library supports it. The resulting
2977 program must not be installed setuid root, unless that
2978 is required for other functionality.
2982 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2983 <tt>/var/log/lastlog</tt> must be installed writeable by
2984 group utmp. Programs who need to modify those files must
2985 be installed setgid utmp.
2990 <heading>Editors and pagers</heading>
2993 Some programs have the ability to launch an editor or pager
2994 program to edit or display a text document. Since there are
2995 lots of different editors and pagers available in the Debian
2996 distribution, the system administrator and each user should
2997 have the possibility to choose his/her preferred editor and
3001 In addition, every program should choose a good default
3002 editor/pager if none is selected by the user or system
3006 Thus, every program that launches an editor or pager must
3007 use the EDITOR or PAGER environment variables to determine
3008 the editor/pager the user wants to get started. If these
3009 variables are not set, the programs <tt>/usr/bin/editor</tt>
3010 and <tt>/usr/bin/pager</tt> should be used, respectively.</p>
3013 These two files are managed through `alternatives.' That is,
3014 every package providing an editor or pager must call the
3015 <prgn>update-alternatives</prgn> script to register these
3019 If it is very hard to adapt a program to make us of the
3020 EDITOR and PAGER variable, that program may be configured
3021 to use <tt>/usr/bin/sensible-editor</tt> and
3022 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
3023 respectively. These are two scripts provided in the Debian
3024 base system that check the EDITOR and PAGER variables and
3025 launch the appropriate program or fall back to
3026 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
3030 A program may also use the VISUAL environment variable to
3031 determine the user's choice of editor. If it exists, it
3032 should take precedence over EDITOR. This is in fact what
3033 <tt>/usr/bin/sensible-editor</tt> does.</p>
3036 Since the Debian base system already provides an editor and
3037 a pager program, it is not required for a package to depend on
3038 `editor' and `pager', nor is it required for a package to
3039 provide such virtual packages.</p></sect>
3042 <sect id="web-appl">
3043 <heading>Web servers and applications</heading>
3046 This section describes the locations and URLs that should
3047 be used by all web servers and web application in the Debian
3053 <p>Cgi-bin executable files are installed in the
3056 /usr/lib/cgi-bin/<cgi-bin-name>
3058 and should be referred to as
3060 http://localhost/cgi-bin/<cgi-bin-name>
3061 </example></p></item>
3064 <item><p>Access to html documents</p>
3067 Html documents for a package are stored in
3068 <tt>/usr/share/doc/<var>package</var></tt> but should
3069 be accessed via symlinks as
3070 <tt>/usr/doc/<var>package</var></tt><footnote> for
3071 backward compatibility, see <ref id="usrdoc"></footnote>
3072 and can be referred to as
3074 http://localhost/doc/<package>/<filename>
3075 </example></p></item>
3078 <item><p>Web Document Root</p>
3081 Web Applications should try to avoid storing files in
3082 the Web Document Root. Instead they should use the
3083 /usr/share/doc/<package> directory for documents and
3084 register the Web Application via the menu package. If
3085 access to the web-root is unavoidable then use
3089 as the Document Root. This might be just a
3090 symbolic link to the location where the sysadmin has
3091 put the real document root.</p>
3094 </enumlist></p></sect>
3098 <heading>Mail transport agents</heading>
3101 Debian packages which process electronic mail, whether
3102 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
3103 must make sure that they are compatible with the
3104 configuration decisions below. Failure to do this may
3105 result in lost mail, broken <tt>From:</tt> lines, and other
3106 serious brain damage!</p>
3109 The mail spool is <tt>/var/spool/mail</tt> and the interface
3110 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3111 per the FHS). The mail spool is part of the base system
3112 and not part of the MTA package.</p>
3115 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3116 programs (like IMAP daemons) must lock the mailbox in an
3117 NFS-safe way. This means that <tt>fcntl()</tt> locking must
3118 to be combined with dot locking. To avoid dead locks, a
3119 program should use <tt>fcntl()</tt> first and dot locking
3120 after this or alternatively implement the two locking
3121 methods in a non blocking way<footnote>
3123 If it is not possible to establish both locks, the
3124 system shouldn't wait for the second lock to be
3125 established, but remove the first lock, wait a (random)
3126 time, and start over locking again.</p>
3127 </footnote>. Using the functions <tt>maillock</tt> and
3128 <tt>mailunlock</tt> provided by the
3129 <tt>liblockfile*</tt><footnote>
3131 <tt>liblockfile</tt> version >>1.01</p>
3132 </footnote> packages is the recommended way to realize this.
3136 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3137 unless the user has chosen otherwise. A MUA may remove a
3138 mailbox (unless it has nonstandard permissions) in which
3139 case the MTA or another MUA must recreate it if needed.
3140 Mailboxes must be writable by group mail.</p>
3143 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs should
3144 be setgid mail to do the locking mentioned above (and
3145 must obviously avoid accessing other users' mailboxes
3146 using this privilege).</p>
3149 <tt>/etc/aliases</tt> is the source file for the system mail
3150 aliases (e.g., postmaster, usenet, etc.)--it is the one
3151 which the sysadmin and <tt>postinst</tt> scripts may edit.
3152 After <tt>/etc/aliases</tt> is edited the program or human
3153 editing it must call <prgn>newaliases</prgn>. All MTA
3154 packages must come with a <prgn>newaliases</prgn> program,
3155 even if it does nothing, but older MTA packages do not do
3156 this so programs should not fail if <prgn>newaliases</prgn>
3157 cannot be found.</p>
3160 The convention of writing <tt>forward to
3161 <var>address</var></tt> in the mailbox itself is not
3162 supported. Use a <tt>.forward</tt> file instead.</p>
3165 The <prgn>rmail</prgn> program used by UUCP
3166 for incoming mail should be <tt>/usr/sbin/rmail</tt>, as per the
3167 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3168 batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
3172 If you need to know what name to use (for example) on
3173 outgoing news and mail messages which are generated locally,
3174 you should use the file <tt>/etc/mailname</tt>. It will
3175 contain the portion after the username and <tt>@</tt> (at)
3176 sign for email addresses of users on the machine (followed
3180 A package should check for the existence of this file. If
3181 it exists it should use it without comment. (An MTA's
3182 prompting configuration script may wish to prompt the user
3183 even if it finds this file exists.) If it does not exist it
3184 should prompt the user for the value and store it in
3185 <tt>/etc/mailname</tt> as well as using it in the package's
3186 configuration. The prompt should make it clear that the
3187 name will not just be used by that package. For example, in
3188 this situation the INN package says:
3190 Please enter the `mail name' of your system. This is the
3191 hostname portion of the address to be shown on outgoing
3192 news and mail messages. The default is
3193 <var>syshostname</var>, your system's host name. Mail
3194 name [`<var>syshostname</var>']:
3196 where <var>syshostname</var> is the output of <tt>hostname
3197 --fqdn</tt>.</p></sect>
3201 <heading>News system configuration</heading>
3204 All the configuration files related to the NNTP (news)
3205 servers and clients should be located under
3206 <tt>/etc/news</tt>.</p>
3209 There are some configuration issues that apply to a number
3210 of news clients and server packages on the machine. These
3214 <tag>/etc/news/organization</tag>
3215 <item><p>A string which should appear as the
3216 organization header for all messages posted
3217 by NNTP clients on the machine</p></item>
3219 <tag>/etc/news/server</tag>
3220 <item><p>Contains the FQDN of the upstream NNTP
3221 server, or localhost if the local machine is
3222 an NNTP server.</p></item>
3225 Other global files may be added as required for cross-package news
3226 configuration.</p></sect>
3230 <heading>Programs for the X Window System</heading>
3233 Some programs can be configured with or without support for the X
3234 Window System. Typically, binaries produced with support for X
3235 will need the X shared libraries to run.<footnote>
3237 <strong>NOTE</strong> The forthcoming major X Window
3238 System release shall probably change this
3245 Such programs should be configured <em>with</em> X support,
3246 and should declare a dependency on <tt>xlib6g</tt> (which
3247 contains X shared libraries). Users who wish to use the
3248 program can install just the relatively small
3249 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
3250 not need to install the whole of X.
3252 <p>Note: With the release of the new X window System
3253 version (4.X), there probably shall be a sweeping change
3254 in the X Window System Policy in the future.</p>
3259 You should not create two versions (one with X support and one
3260 without) of your package.</p>
3263 <em>Packages which provide an X server</em> that, directly or
3264 indirectly, communicates with real input and display hardware
3265 should declare in their control data that they provide the
3266 virtual package <tt>xserver</tt>.
3269 Rationale: implement current practice, and provide an
3270 actual policy for usage of the "xserver" virtual package
3271 which appears in the virtual packages list.
3272 In a nutshell, X servers that interface directly with
3273 the display and input hardware or via another subsystem
3274 (e.g., GGI) should provide xserver. Things like Xvfb,
3275 Xnest, and Xprt should not. <strong>NOTE</strong> The
3276 forthcoming major X Window System release shall probably
3277 change this drastically.
3283 <em>Packages that provide a terminal emulator</em> for the X
3284 Window System which support a terminal type with a terminfo
3285 description provided in the <tt>ncurses-base</tt> package
3286 should declare in their control data that they provide the
3287 virtual package <tt>x-terminal-emulator</tt>. They should
3288 also register themselves as an alternative for
3289 <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
3294 <em>Packages that provide window managers</em> should declare in
3295 their control data that they provide the virtual package
3296 <tt>x-window-manager</tt>. They should also register themselves as an
3297 alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
3298 calculated as follows:
3300 <item>Start with a priority of 20.</item>
3301 <item>If the window manager supports the Debian menu system,
3302 add 20 points if this support is available in the
3303 package's default configuration (i.e., no
3304 configuration files belonging to the system or user
3305 have to be edited to activate the feature); if
3306 configuration files must be modified, add only 10
3308 <item>If the window manager permits the X session to be
3309 restarted using a <em>different</em> window manager
3310 (without killing the X server) in its default
3311 configuration, add 10 points; otherwise add
3317 <em>Packages that provide fonts for the X Window System</em>
3318 must do a number of things to ensure that they are both
3319 available without modification of the X or font server
3320 configuration, and that they do not corrupt files used by
3321 other font packages to register information about themselves.
3324 Fonts of any type supported by the X Window System
3325 should be be in a separate binary package from any
3326 executables, libraries, or documentation (except that
3327 specific to the fonts shipped); if a program or
3328 library is <em>unusable</em> without one or more
3329 specific fonts, the package containing the program or
3330 library should declare a dependency on the package(s)
3331 containing the font(s) it requires.
3334 BDF fonts should be converted to PCF fonts with the
3335 <tt>bdftopcf</tt> utility (available in the
3336 <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
3337 placed in a directory that corresponds to their
3341 100 dpi fonts should be placed in
3342 <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
3345 75 dpi fonts should be placed in
3346 <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
3349 Character-cell fonts, cursor fonts, and other
3350 low-resolution fonts should be placed in
3351 <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
3356 Speedo fonts should be placed in
3357 <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
3360 Type 1 fonts should be placed in
3361 <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
3362 metric files are available, they may be placed here as
3366 Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
3367 other than those listed above should be neither created nor
3368 used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
3369 excepted for historical reasons, but installation of files into
3370 these directories remains discouraged.)
3373 Font packages may, instead of placing files directly in
3374 the X font directories listed above, provide symbolic links in
3375 the font directory which point to the files' actual location
3376 in the filesystem. Such a location should comply with the
3380 Font packages should not contain both 75dpi and 100dpi
3381 versions of a font. If both are available, they should be
3382 provided in separate binary packages with "-75dpi" or "-100dpi"
3383 appended to the names of the packages containing the
3384 corresponding fonts.
3387 Fonts destined for the <tt>misc</tt> subdirectory should
3388 not be included in the same package as 75dpi or 100dpi fonts;
3389 instead, they should be provided in a separate package with
3390 "-misc" appended to its name.
3393 Font packages <em>must not</em> provide the files
3394 <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
3395 <tt>fonts.scale</tt> in a font directory.
3398 <tt>fonts.dir</tt> files must not be provided at
3402 <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
3403 files, if needed, should be provided in the
3405 <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
3406 where <em>fontdir</em> is the name of the
3408 <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
3409 package's corresponding fonts are stored (e.g.,
3410 <tt>75dpi</tt> or <tt>misc</tt>),
3411 <em>package</em> is the name of the package that
3412 provides these fonts, and <em>extension</em> is
3413 either <tt>scale</tt> or <tt>alias</tt>,
3414 whichever corresponds to the file
3420 Font packages must declare a dependency on
3421 <tt>xbase-clients</tt> and, in the package
3422 post-installation and post-removal scripts, invoke the
3423 <tt>mkfontdir</tt> command on each directory into
3424 which they installed fonts.
3427 Font packages that provide one or more
3428 <tt>fonts.scale</tt> files as described above must declare a
3429 versioned dependency on <tt>xbase-clients (>=
3430 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
3431 directory into which they installed fonts
3432 <em>before</em> invoking <tt>mkfontdir</tt> on that
3433 directory. This invocation must occur in both the
3434 post-installation and post-removal scripts.
3437 Font packages that provide one or more
3438 <tt>fonts.alias</tt> files as described above must
3439 declare a versioned dependency on <tt>xbase-clients
3440 (>= 3.3.3.1-5)</tt> and, in the package
3441 post-installation and post-removal scripts, invoke
3442 <tt>update-fonts-alias</tt> on each directory into
3443 which they installed fonts.
3446 Font packages must not provide alias names for the
3447 fonts they include which collide with alias names already in
3448 use by fonts already packaged.
3451 Font packages must not provide fonts with the same XLFD
3452 registry name as another font already packaged.
3458 <em>Application defaults</em> files must be installed in the
3459 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
3461 <p>Note: This shall change very shortly.</p>
3463 They should not be registered as <em>conffile</em>s or
3464 otherwise treated as configuration files. Customization of
3465 programs' X resources may be supported with the provision of
3466 a file with the same name as that of the package placed in
3467 the <tt>/etc/X11/Xresources/</tt> directory, which must
3468 registered as a <em>conffile</em>. <em>Important:</em>
3469 packages that install files into the
3470 <tt>/etc/X11/Xresources/</tt> directory <em>must</em>
3471 declare a conflict with <tt>xbase (<<
3472 3.3.2.3a-2)</tt>; if this is not done it is possible for the
3473 installing package to destroy a previously-existing
3474 <tt>/etc/X11/Xresources</tt> <em>file</em> which had been
3475 customized by the system administrator.
3477 <p>Rationale: clarifies the language to properly
3478 address the package maintainer, not the system
3479 administrator, as to how to manage
3480 /etc/X11/Xresources.</p>
3486 <em>Packages using the X Window System should abide by the FHS
3487 standard whenever possible</em>; they should install binaries,
3488 libraries, manual pages, and other files in FHS-mandated
3489 locations wherever possible. This means that files must
3490 not be installed into <tt>/usr/X11R6/bin/</tt>,
3491 <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
3492 this is necessary for the package to operate properly.
3493 Configuration files for window managers and display managers
3494 should be placed in a subdirectory of <tt>/etc/X11/</tt>
3495 corresponding to the package name due to these programs'
3496 tight integration with the mechanisms of the X Window
3497 System. Application-level programs should use the
3498 <tt>/etc/</tt> directory unless otherwise mandated by
3499 policy. The installation of files into subdirectories of
3500 <tt>/usr/X11R6/include/X11/</tt> and
3501 <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
3502 package maintainers should determine if subdirectories of
3503 <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
3504 instead (symlinks from the X11R6 directories to
3505 FHS-compliant locations is encouraged if the program is not
3506 easily configured to look elsewhere for its files).
3507 Packages must not provide -- or install files into -- the
3508 directories <tt>/usr/bin/X11/</tt>,
3509 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
3510 Files within a package should, however, make reference to
3511 these directories, rather than their X11R6-named
3512 counterparts <tt>/usr/X11R6/bin/</tt>,
3513 <tt>/usr/X11R6/include/X11/</tt>, and
3514 <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
3515 referred to have not been moved to FHS-compliant locations.
3519 <em>Programs that require the non-DFSG-compliant OSF/Motif
3520 library</em> should be compiled against and tested with
3521 LessTif (a free re-implementation of Motif) instead. If the
3522 maintainer judges that the program or programs do not work
3523 sufficiently well with LessTif to be distributed and
3524 supported, but do so when compiled against Motif, then two
3525 versions of the package should be created; one linked
3526 statically against Motif and with <tt>-smotif</tt> appended
3527 to the package name, and one linked dynamically against
3528 Motif and with <tt>-dmotif</tt> appended to the package
3529 name. Both Motif-linked versions are dependent upon
3530 non-DFSG-compliant software and thus cannot be uploaded to
3531 the main distribution; if the software is itself
3532 DFSG-compliant it may be uploaded to the contrib
3533 distribution. While known existing versions of OSF/Motif
3534 permit unlimited redistribution of binaries linked against
3535 the library (whether statically or dynamically), it is the
3536 package maintainer's responsibility to determine whether
3537 this is permitted by the license of the copy of OSF/Motif in
3538 his or her possession.
3544 <heading>Emacs lisp programs</heading>
3547 Please refer to the `Debian Emacs Policy' (documented in
3548 <tt>debian-emacs-policy.gz</tt> of the
3549 <prgn>emacsen-common</prgn> package) for details of how to
3550 package emacs lisp programs.</p></sect>
3554 <heading>Games</heading>
3557 The permissions on /var/games are 755
3558 <tt>root.root</tt>.</p>
3561 Each game decides on its own security policy.</p>
3564 Games which require protected, privileged access to
3565 high-score files, savegames, etc., may be made
3566 set-<em>group</em>-id (mode 2755) and owned by
3567 <tt>root.games</tt>, and use files and directories with
3568 appropriate permissions (770 <tt>root.games</tt>, for
3569 example). They must not be made
3570 set-<em>user</em>-id, as this causes security problems. (If
3571 an attacker can subvert any set-user-id game they can
3572 overwrite the executable of any other, causing other players
3573 of these games to run a Trojan horse program. With a
3574 set-group-id game the attacker only gets access to less
3575 important game data, and if they can get at the other
3576 players' accounts at all it will take considerably more
3580 Some packages, for example some fortune cookie programs, are
3581 configured by the upstream authors to install with their
3582 data files or other static information made unreadable so
3583 that they can only be accessed through set-id programs
3584 provided. You should not do this in a Debian package: anyone can
3585 download the <tt>.deb</tt> file and read the data from it,
3586 so there is no point making the files unreadable. Not
3587 making the files unreadable also means that you don't have
3588 to make so many programs set-id, which reduces the risk of a
3592 As described in the FHS, binaries of games should be
3593 installed in the directory <tt>/usr/games</tt>. This also
3594 applies to games that use the X Window System. Manual pages
3595 for games (X and non-X games) should be installed in
3596 <tt>/usr/share/man/man6</tt>.</p>
3600 <chapt><heading>Documentation</heading>
3604 <heading>Manual pages</heading>
3607 You should install manual pages in <prgn>nroff</prgn> source
3608 form, in appropriate places under <tt>/usr/share/man</tt>. You
3609 should only use sections 1 to 9 (see the FHS for more
3610 details). You must not install a preformatted `cat
3614 Each program, utiltiy, and function should have an
3615 associated manpage included in the same package. It is
3616 suggested that all configuration files also have a manual
3617 page included as well.
3621 If no manual page is available for a particular program,
3622 utility, function or configuration file and this is reported as a bug on
3623 debian-bugs, a symbolic link from the requested manual page
3624 to the <manref name="undocumented" section="7"> manual page
3625 may be provided. This symbolic link can be created from
3626 <tt>debian/rules</tt> like this:
3628 ln -s ../man7/undocumented.7.gz \
3629 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3631 This manpage claims that the lack of a manpage has been
3632 reported as a bug, so you may only do this if it really has
3633 (you can report it yourself, if you like). Do not close the
3634 bug report until a proper manpage is available.</p>
3637 You may forward a complaint about a missing manpage to the
3638 upstream authors, and mark the bug as forwarded in the
3639 Debian bug tracking system. Even though the GNU Project do
3640 not in general consider the lack of a manpage to be a bug,
3641 we do--if they tell you that they don't consider it a bug
3642 you should leave the bug in our bug tracking system open
3646 Manual pages should be installed compressed using <tt>gzip
3650 If one manpage needs to be accessible via several names it
3651 is better to use a symbolic link than the <tt>.so</tt>
3652 feature, but there is no need to fiddle with the relevant
3653 parts of the upstream source to change from <tt>.so</tt> to
3654 symlinks--don't do it unless it's easy. You should not create hard
3655 links in the manual page directories, nor put
3656 absolute filenames in <tt>.so</tt> directives. The filename
3657 in a <tt>.so</tt> in a manpage should be relative to the
3658 base of the manpage tree (usually
3659 <tt>/usr/share/man</tt>).</p></sect>
3663 <heading>Info documents</heading>
3666 Info documents should be installed in <tt>/usr/share/info</tt>.
3667 They should be compressed with <tt>gzip -9</tt>.</p>
3670 Your package should call <prgn>install-info</prgn> to update the Info
3672 file, in its post-installation script:
3674 install-info --quiet --section Development Development \
3675 /usr/share/info/foobar.info
3679 It is a good idea to specify a section for the location of
3680 your program; this is done with the <tt>--section</tt>
3681 switch. To determine which section to use, you should look
3682 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3683 relevant (or create a new section if none of the current
3684 sections are relevant). Note that the <tt>--section</tt>
3685 flag takes two arguments; the first is a regular expression
3686 to match (case-insensitively) against an existing section,
3687 the second is used when creating a new one.</p>
3690 You should remove the entries in the pre-removal script:
3692 install-info --quiet --remove /usr/share/info/foobar.info
3696 If <prgn>install-info</prgn> cannot find a description entry
3697 in the Info file you must supply one. See <manref
3698 name="install-info" section="8"> for details.</p>
3702 <heading>Additional documentation</heading>
3705 Any additional documentation that comes with the package may
3706 be installed at the discretion of the package maintainer.
3707 Text documentation should be installed in a directory
3708 <tt>/usr/share/doc/<var>package</var></tt>, where
3709 <var>package</var> is the name of the package, and
3710 compressed with <tt>gzip -9</tt> unless it is small.</p>
3713 If a package comes with large amounts of documentation which
3714 many users of the package will not require you should create
3715 a separate binary package to contain it, so that it does not
3716 take up disk space on the machines of users who do not need
3717 or want it installed.</p>
3720 It is often a good idea to put text information files
3721 (<tt>README</tt>s, changelogs, and so forth) that come with
3722 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3723 in the binary package. However, you don't need to install
3724 the instructions for building and installing the package, of
3729 <heading>Accessing the documentation</heading>
3732 Former Debian releases placed all additional documentation
3733 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3735 <tt>/usr/share/doc/<var>package</var></tt>, each package
3736 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3737 that points to the new location of its documentation in
3738 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3739 symlinks will be removed in the future, but they have to be
3740 there for compatibility reasons until all packages have
3741 moved and the policy is changed accordingly.</footnote>.
3742 The symlink must be created when the package is installed;
3743 it cannot be contained in the package itself due to problems
3744 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3745 this is to put the following in the package's
3746 <prgn>postinst</prgn>:
3748 if [ "$1" = "configure" ]; then
3749 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3750 -a -d /usr/share/doc/#PACKAGE# ]; then
3751 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3755 And the following in the package's <prgn>prerm</prgn>:
3757 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3758 -a -L /usr/doc/#PACKAGE# ]; then
3759 rm -f /usr/doc/#PACKAGE#
3766 <heading>Preferred documentation formats</heading>
3769 The unification of Debian documentation is being carried out
3773 If your package comes with extensive documentation in a
3774 mark up format that can be converted to various other formats
3775 you should if possible ship HTML versions in a binary
3776 package, in the directory
3777 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3780 <p>The rationale: The important thing here is that HTML
3781 docs should be available in <em>some</em> package, not
3782 necessarily in the main binary package, though. </p>
3787 Other formats such as PostScript may be provided at your
3791 <sect id="copyrightfile">
3792 <heading>Copyright information</heading>
3795 Every package must be accompanied by a verbatim copy of its
3796 copyright and distribution license in the file
3797 /usr/share/doc/<package-name>/copyright. This file must
3798 neither be compressed nor be a symbolic link.</p>
3801 In addition, the copyright file must say where the upstream
3802 sources (if any) were obtained, and should explain briefly what
3803 modifications were made in the Debian version of the package
3804 compared to the upstream one. It should name the original
3805 authors of the package and the Debian maintainer(s) who were
3806 involved with its creation.</p>
3809 /usr/share/doc/<package-name> may be a symbolic link to a
3810 directory in /usr/share/doc only if two packages both come from
3811 the same source and the first package has a "Depends"
3812 relationship on the second. These rules are important
3813 because copyrights must be extractable by mechanical
3817 Packages distributed under the UCB BSD license, the Artistic
3818 license, the GNU GPL, and the GNU LGPL should refer to the
3819 files /usr/share/common-licenses/BSD,
3820 /usr/share/common-licenses/Artistic,
3821 /usr/share/common-licenses/GPL, and
3822 /usr/share/common-licenses/LGPL.
3825 Why "licenses" and not "copyright"? Because
3826 <tt>/usr/doc/copyright</tt> used to contain all the
3827 copyright files, plus the four common licenses GPL,
3828 LGPL, Artistic and BSD. Now individual copyright files
3829 for packages are no longer in a common directory. Once
3830 <tt>/usr/doc/copyright</tt> is almost empty it makes
3831 sense to rename "copyright" to "licenses"
3834 Why "common-licenses" and not "licenses"? Because if I
3835 put just "licenses" I'm sure I will receive a bug report
3836 saying "license foo is not included in the licenses
3837 directory. They are not all the licenses, just a few
3838 common ones. I could use /usr/share/doc/common-licenses
3839 but I think this is too long, and, after all, the GPL
3840 does not "document" anything, it is merely a license.
3846 You should not use the copyright file as a general <tt>README</tt>
3847 file. If your package has such a file it should be
3848 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3849 <tt>README.Debian</tt> or some other appropriate place.</p>
3853 <heading>Examples</heading>
3856 Any examples (configurations, source files, whatever),
3857 should be installed in a directory
3858 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3859 files should not be referenced by any program--they're there
3860 for the benefit of the system administrator and users, as
3861 documentation only. Architecture-specific example files
3862 should be installed in a directory
3863 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3864 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3865 to files in it. Or the latter directory may be a symlink to
3869 <sect id="instchangelog">
3870 <heading>Changelog files</heading>
3873 Packages that are not Debian-native must contain a copy
3874 of <tt>debian/changelog</tt> file from the Debian source
3875 tree in <tt>/usr/share/doc/<var>package</var></tt>
3876 as <tt>changelog.Debian.gz</tt>. If an upstream
3877 changelog is available, it should be accessible as
3878 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>
3879 in plain text. If the upstream changelog is distributed
3880 in HTML, it should be made available in that form as
3881 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
3882 and the <tt>changelog.gz</tt> should be generated using, eg,
3883 lynx -dump -nolist</tt>. If the upstream changelog files do
3884 not already conform to this naming convention, then this may
3885 be achieved either by renaming the files, or adding a symbolic
3886 link, at the maintainer's discretion.</p>
3889 Rationale: People should not have to look into two
3890 places for upstream changelogs merely because they are
3898 All these files should be installed compressed using <tt>gzip -9</tt>,
3899 as they will become large with time even if they start out
3904 If the package has only one changelog which is used both as
3905 the Debian changelog and the upstream one because there is
3906 no separate upstream maintainer then that changelog should
3907 usually be installed as
3908 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3909 there is a separate upstream maintainer, but no upstream
3910 changelog, then the Debian changelog should still be called
3911 <tt>changelog.Debian.gz</tt>.</p>