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-free</em>, <em>contrib</em>,
212 <em>non-US/main</em>, <em>non-US/non-free</em>, and
213 <em>non-US/contrib</em>.</p>
216 The <em>main</em> and the <em>non-US/main</em> sections form
217 the <em>Debian GNU/Linux distribution</em>.
221 Packages in the other sections are not considered as part of
222 the Debian distribution, though we support their use, and we
223 provide infrastructure for them (such as our bug-tracking
224 system and mailing lists). This Debian Policy Manual applies
225 to these packages as well.</p>
227 <sect id="pkgcopyright">
228 <heading>Package copyright and sections</heading>
230 The aims of this policy are:
232 <list compact="compact">
234 <p>We want to make as much software available as we
238 <p>We want to encourage everyone to write free software.</p>
241 <p> We want to make it easy for people to produce
242 CD-ROMs of our system without violating any licenses,
243 import/export restrictions, or any other laws.</p>
248 <heading>The Debian Free Software Guidelines</heading>
250 The Debian Free Software Guidelines (DFSG) is our
251 definition of `free' software.
253 <tag>Free Redistribution
257 The license of a Debian component may not restrict any
258 party from selling or giving away the software as a
259 component of an aggregate software distribution
260 containing programs from several different
261 sources. The license may not require a royalty or
262 other fee for such sale.
269 The program must include source code, and must allow
270 distribution in source code as well as compiled form.
277 The license must allow modifications and derived
278 works, and must allow them to be distributed under the
279 same terms as the license of the original software.
282 <tag>Integrity of The Author's Source Code
286 The license may restrict source-code from being
287 distributed in modified form <em>only</em> if the
288 license allows the distribution of ``patch files''
289 with the source code for the purpose of modifying the
290 program at build time. The license must explicitly
291 permit distribution of software built from modified
292 source code. The license may require derived works to
293 carry a different name or version number from the
294 original software. (This is a compromise. The Debian
295 group encourages all authors to not restrict any
296 files, source or binary, from being modified.)
299 <tag>No Discrimination Against Persons or Groups
303 The license must not discriminate against any person
307 <tag>No Discrimination Against Fields of Endeavor
311 The license must not restrict anyone from making use
312 of the program in a specific field of endeavor. For
313 example, it may not restrict the program from being
314 used in a business, or from being used for genetic
318 <tag>Distribution of License
322 The rights attached to the program must apply to all
323 to whom the program is redistributed without the need
324 for execution of an additional license by those
328 <tag>License Must Not Be Specific to Debian
332 The rights attached to the program must not depend on
333 the program's being part of a Debian system. If the
334 program is extracted from Debian and used or
335 distributed without Debian but otherwise within the
336 terms of the program's license, all parties to whom
337 the program is redistributed must have the same
338 rights as those that are granted in conjunction with
342 <tag>License Must Not Contaminate Other Software
346 The license must not place restrictions on other
347 software that is distributed along with the licensed
348 software. For example, the license must not insist
349 that all other programs distributed on the same medium
350 must be free software.
353 <tag>Example Licenses
357 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
358 examples of licenses that we consider <em>free</em>.
365 <heading>The main section</heading>
367 Every package in "main" must comply with the DFSG (Debian
368 Free Software Guidelines).</p>
371 In addition, the packages in "main"
372 <list compact="compact">
375 must not require a package outside of "main" for
376 compilation or execution (thus, the package must not
377 declare a "Depends" or "Recommends" relationship on a
383 should not be so buggy that we refuse to support them,
388 should meet all policy requirements presented in this
396 <heading>The contrib section</heading>
398 Every package in "contrib" must comply with the DFSG.
402 Examples of packages which would be included in "contrib" are
403 <list compact="compact">
406 free packages which require "contrib", "non-free", or
407 "non-US" packages or packages which are not in our
408 archive at all for compilation or execution,
413 wrapper packages or other sorts of free accessories for
421 <heading>The non-free section</heading>
423 `Non-free' contains packages which are not compliant with
426 All packages in `non-free' must be electronically
427 distributable across international borders.
431 <heading>The non-us server</heading>
433 Some programs with cryptographic program code need to be stored
434 on the "non-us" server because of export restrictions of the
437 This applies only to packages which contain cryptographic
438 code. A package containing a program with an interface to a
439 cryptographic program or a program that's dynamically linked
440 against a cryptographic library should not be distributed
441 via the non-us server if it is capable of running without the
442 cryptography library or program.
446 <heading>Further copyright considerations</heading>
448 Every package must be accompanied by a verbatim copy of its
449 copyright and distribution license in the file
450 /usr/share/doc/<package-name>/copyright (see <ref
451 id="copyrightfile"> for details).</p>
453 We reserve the right to restrict files from being included
454 anywhere in our archives if
455 <list compact="compact">
458 their use or distribution would break a law,
463 there is an ethical conflict in their distribution or
469 we would have to sign a license for them, or
474 their distribution would conflict with other project
482 Programs whose authors encourage the user to make donations
483 are fine for the main distribution, provided that the
484 authors do not claim that not donating is immoral,
485 unethical, illegal or something similar; otherwise they must
489 Packages whose copyright permission notices (or patent
490 problems) do not allow redistribution even of only binaries,
491 and where no special permission has been obtained, must not be
492 placed on the Debian FTP site and its mirrors at all.</p>
495 Note, that under international copyright law (this applies
496 in the United States, too) <em>no</em> distribution or
497 modification of a work is allowed without an explicit notice
498 saying so. Therefore a program without a copyright notice
499 <em>is</em> copyrighted and you may not do anything to it
500 without risking being sued! Likewise if a program has a
501 copyright notice but no statement saying what is permitted
502 then nothing is permitted.</p>
505 Many authors are unaware of the problems that restrictive
506 copyrights (or lack of copyright notices) can cause for the
507 users of their supposedly-free software. It is often
508 worthwhile contacting such authors diplomatically to ask
509 them to modify their license terms. However, this is a
510 politically difficult thing to do and you should ask for
511 advice on <tt>debian-legal</tt> first.</p>
514 When in doubt, send mail to
515 <email>debian-legal@lists.debian.org</email>. Be prepared
516 to provide us with the copyright statement. Software
517 covered by the GPL, public domain software and BSD-like
518 copyrights are safe; be wary of the phrases `commercial use
519 prohibited' and `distribution restricted'.</p>
522 <heading>Subsections</heading>
525 The packages in all the sections (<em>main</em>,
526 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
527 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
528 grouped further into <em>subsections</em> to simplify
532 The section for each package should be specified in the
533 package's <em>control record</em>. However, the maintainer of
534 the Debian archive may override this selection to assure the
535 consistency of the Debian distribution. </p>
538 Please check the current Debian distribution to see which
539 sections are available.</p>
542 <heading>Priorities</heading>
545 Each package should have a <em>priority</em> value,
546 which is included in the package's <em>control
547 record</em>. This information is used in the Debian package
548 management tool to separate high-priority packages from
549 less-important packages.</p>
552 The following <em>priority levels</em> are supported by the
553 Debian package management system, <prgn>dpkg</prgn>.
555 <tag><tt>required</tt></tag>
558 <tt>required</tt> packages are necessary for the
559 proper functioning of the system. You must not remove
560 these packages or your system may become totally
561 broken and you may not even be able to use
562 <prgn>dpkg</prgn> to put things back. Systems with
563 only the <tt>required</tt> packages are probably
564 unusable, but they do have enough functionality to
565 allow the sysadmin to boot and install more
568 <tag><tt>important</tt></tag>
571 Important programs, including those which one would
572 expect to find on any Unix-like system. If the
573 expectation is that an experienced Unix person who
574 found it missing would say `What the F*!@<+ is
575 going on, where is <prgn>foo</prgn>', it must be in
576 <tt>important</tt>. This is an important criterion
577 because we are trying to produce, amongst other
578 things, a free Unix. Other packages without which the
579 system will not run well or be usable must also be
580 here. This does <em>not</em> include Emacs, the X
581 Window System, TeX or any other large applications.
582 The <tt>important</tt> packages are just a bare
583 minimum of commonly-expected and necessary tools.</p>
585 <tag><tt>standard</tt></tag>
588 These packages provide a reasonably small but not too
589 limited character-mode system. This is what will
590 install by default if the user doesn't select anything
591 else. It doesn't include many large applications, but
592 it does include Emacs (this is more of a piece of
593 infrastructure than an application) and a reasonable
594 subset of TeX and LaTeX (if this is possible without
597 <tag><tt>optional</tt></tag>
600 (In a sense everything is optional that isn't
601 required, but that's not what is meant here.) This is
602 all the software that you might reasonably want to
603 install if you didn't know what it was or don't have
604 specialized requirements. This is a much larger system
605 and includes the X Window System, a full TeX distribution,
606 and many applications. Note that optional packages should
607 not conflict with each other.
610 <tag><tt>extra</tt></tag>
613 This contains all packages that conflict with others
614 with required, important, standard or optional
615 priorities, or are only likely to be useful if you
616 already know what they are or have specialised
623 Packages must not depend on packages with lower priority
624 values (excluding build-time dependencies). In order to
625 ensure this, the priorities of one or more packages must
631 <heading>Binary packages</heading>
634 The Debian GNU/Linux distribution is based on the Debian
635 package management system, called <prgn>dpkg</prgn>. Thus,
636 all packages in the Debian distribution must be provided
637 in the <tt>.deb</tt> file format.</p>
641 <heading>The package name</heading>
644 Every package must have a name that's unique within the Debian
648 Package names must only consist of lower case letters, digits (0-9),
649 plus (+) or minus (-) signs, and periods (.).</p>
652 The package name is part of the file name of the
653 <tt>.deb</tt> file and is included in the control field
659 <heading>The maintainer of a package</heading>
662 Every package should have exactly one maintainer at a
663 time. This person is responsible that the license of the
664 package's software complies with the policy of the
665 distribution this package is included in.</p>
668 The maintainer must be specified in the
669 <tt>Maintainer</tt> control field with the correct name
670 and a working email address for the Debian maintainer of
671 the package. If one person maintains several packages
672 he/she should try to avoid having different forms of their
673 name and email address in different <tt>Maintainer</tt>
677 If the maintainer of a package quits from the Debian
678 project the Debian QA Group
679 <email>debian-qa@lists.debian.org</email> takes over the
680 maintainership of the package until someone else
681 volunteers for that task. These packages are called
682 <em>orphaned packages</em>.
688 <heading>The description of a package</heading>
691 Every Debian package must have an extended description
692 stored in the appropriate field of the control record.</p>
695 The description should be written so that it tells the user
696 what they need to know to decide whether to install the
697 package. This description should not just be copied from
698 the blurb for the program. Instructions for configuring
699 or using the package should not be included -- that is what
700 installation scripts, manual pages, Info files, etc. are
701 for. Copyright statements and other administrivia should
702 not be included -- that is what the copyright file is
708 <heading>Dependencies</heading>
711 Every package must specify the dependency information
712 about other packages that are required for the first to
716 For example, a dependency entry must be provided for any
717 shared libraries required by a dynamically-linked executable
718 binary in a package.</p>
721 Packages are not required to declare any dependencies they
722 have on other packages which are marked <tt>Essential</tt>
723 (see below), and should not do so unless they depend on a
724 particular version of that package.</p>
727 Sometimes, a package requires another package to be installed
728 <em>and</em> configured before it can be installed. In this
729 case, you must specify a <tt>Pre-Depends</tt> entry for
733 You should not specify a <tt>Pre-Depends</tt> entry for a
734 package before this has been discussed on the
735 <tt>debian-devel</tt> mailing list and a consensus about
736 doing that has been reached.</p></sect1>
740 <heading>Virtual packages</heading>
743 Sometimes, there are several packages doing more-or-less
744 the same job. In this case, it's useful to define a
745 <em>virtual package</em> whose name describes the function
746 the packages have. (The virtual packages just exist
747 logically, not physically--that's why they are called
748 <em>virtual</em>.) The packages with this particular
749 function will then <em>provide</em> the virtual
750 package. Thus, any other package requiring that function
751 can simply depend on the virtual package without having to
752 specify all possible packages individually.</p>
755 All packages should use virtual package names where
756 appropriate, and arrange to create new ones if necessary.
757 They should not use virtual package names (except privately,
758 amongst a cooperating group of packages) unless they have
759 been agreed upon and appear in the list of virtual package
763 The latest version of the authoritative list of virtual
764 package names can be found on
765 <ftpsite>ftp.debian.org</ftpsite> in
766 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
767 or your local mirror. In addition, it is included in the
768 <tt>debian-policy</tt> package. The procedure for updating
769 the list is described at the top of the file.</p></sect1>
773 <heading>Base packages</heading>
776 The packages included in the <tt>base</tt> section have a
777 special function. They form a minimum subset of the Debian
778 GNU/Linux system that is installed before everything else
779 on a new system. Thus, only very few packages are allowed
780 to go into the <tt>base</tt> section to keep the required
781 disk usage very small.</p>
784 Most of these packages will have the priority value
785 <tt>required</tt> or at least <tt>important</tt>, and many
786 of them will be tagged <tt>essential</tt> (see below).</p>
789 You must not place any packages into the <tt>base</tt>
790 section before this has been discussed on the
791 <tt>debian-devel</tt> mailing list and a consensus about
792 doing that has been reached.</p></sect1>
796 <heading>Essential packages</heading>
799 Some packages are tagged <tt>essential</tt>. (They have
800 <tt>Essential: yes</tt> in their package control record.)
801 This flag is used for packages that are <em>essential</em>
805 Since these packages can not easily be removed (you'll
806 have to specify an extra <em>force option</em> to
807 <prgn>dpkg</prgn>) this flag must not be used unless
808 absolutely necessary. A shared library package must not
809 be tagged <tt>essential</tt>--the dependencies will
810 prevent its premature removal, and we need to be able to
811 remove it when it has been superseded.
815 Since dpkg will not prevent upgrading of other packages
816 while an <tt>essential</tt> package is in an unconfigured
817 state, all <tt>essential</tt> packages must supply all
818 their core functionality even when unconfigured. If the
819 package cannot satisfy this requirement it must not be
820 tagged as essential, and any packages depending on this
821 package must instead have explicit dependency fields as
826 You must not tag any packages <tt>essential</tt> before
827 this has been discussed on the <tt>debian-devel</tt>
828 mailing and a consensus about doing that has been
833 <heading>Maintainer scripts</heading>
836 The package installation scripts should avoid producing
837 output which it is unnecessary for the user to see and
838 should rely on <prgn>dpkg</prgn> to stave off boredom on
839 the part of a user installing many packages. This means,
840 amongst other things, using the <tt>--quiet</tt> option on
841 <prgn>install-info</prgn>.</p>
844 Packages should try to minimize the amount of prompting
845 they need to do, and they should ensure that the user will
846 only ever be asked each question once. This means that
847 packages should try to use appropriate shared
848 configuration files (such as <tt>/etc/papersize</tt> and
849 <tt>/etc/news/server</tt>), rather than each prompting for
850 their own list of required pieces of information.</p>
853 It also means that an upgrade should not ask the same
854 questions again, unless the user has used <tt>dpkg
855 --purge</tt> to remove the package's configuration. The
856 answers to configuration questions should be stored in an
857 appropriate place in <tt>/etc</tt> so that the user can
858 modify them, and how this has been done should be
862 If a package has a vitally important piece of information
863 to pass to the user (such as "don't run me as I am, you
864 must edit the following configuration files first or you
865 risk your system emitting badly-formatted messages"), it
866 should display this in the <prgn>postinst</prgn> script
867 and prompt the user to hit return to acknowledge the
868 message. Copyright messages do not count as vitally
869 important (they belong in
870 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
871 do instructions on how to use a program (these should be
872 in on line documentation, where all the users can see
876 Any necessary prompting should almost always be confined
877 to the post-installation script, and should be protected
878 with a conditional so that unnecessary prompting doesn't
879 happen if a package's installation fails and the
880 <prgn>postinst</prgn> is called with
881 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
882 <tt>abort-deconfigure</tt>.</p>
885 Errors which occur during the execution of an installation
886 script should be checked and the installation should not
887 continue after an error.</p>
890 Note, that <ref id="scripts">, in general applies to
891 package maintainer scripts, too.</p>
894 You should not use <prgn>dpkg-divert</prgn> on a file
895 belonging to another package without consulting the maintainer
896 of that package first.</p>
899 All packages which supply an instance of a common command
900 name (or, in general, filename) should generally use
901 <prgn>update-alternatives</prgn>, so that they may be
902 installed together. If <prgn>update-alternatives</prgn>
903 is not used, then each package must use <tt>Conflicts</tt>
904 to ensure that other packages are de-installed. (In this
905 case, it may be appropriate to specify a conflict against
906 earlier versions of something that previously did not use
907 <prgn>update-alternatives</prgn> -- this is an exception to
908 the usual rule that this not allowed).
913 <heading>Source packages</heading>
916 <heading>Standards conformance</heading>
919 You should specify the most recent version of the
920 packaging standards with which your package complies in
921 the source package's <tt>Standards-Version</tt> field.</p>
924 This value will be used to file bug reports automatically
925 if your package becomes too much out of date.</p>
928 The value corresponds to a version of the Debian manuals,
929 as can be found on the title page or page headers and
930 footers (depending on the format).</p>
933 The version number has four components--major and minor
934 number and major and minor patch level. When the
935 standards change in a way that requires every package to
936 change the major number will be changed. Significant
937 changes that will require work in many packages will be
938 signaled by a change to the minor number. The major patch
939 level will be changed for any change to the meaning of the
940 standards, however small; the minor patch level will be
941 changed when only cosmetic, typographical or other edits
942 which do not change the meaning are made, or changes which
943 do not affect the contents of packages.</p>
946 For package maintainers, only the first 3 digits of the
947 manual version are significant in representing the
948 <em>Standards-Version</em>, and either these 3 digits or
949 the complete 4 digits may be specified.
952 In the past, people specified 4 digits in the
953 Standards-Version field, like `2.3.0.0'. Since any
954 `patch-level changes' don't introduce new policy, it
955 was thought it would be better to relax policy and
956 only require that the first 3 digits are specified. (4
957 digits may still be used if someone wants to do so.)
963 You should regularly, and especially if your package has
964 become out of date, check for the newest Policy Manual
965 available and update your package, if necessary. When your
966 package complies with the new standards you should update the
967 <tt>Standards-Version</tt> source package field and
968 release it.</p></sect1>
972 <heading>Package relationships</heading>
975 Source packages should specify which binary packages they
976 require to be installed or not to be installed in order to
977 build correctly. For example, if building a package
978 requires a certain compiler, then the compiler should be
979 specified as a build-time dependency.
983 It is not be necessary to explicitly specify build-time
984 relationships on a minimal set of packages that are always
985 needed to compile, link and put in a Debian package a
986 standard "Hello World!" program written in C or C++. The
987 required packages are called <em>build-essential</em>, and
988 an informational list can be found in
989 <tt>/usr/share/doc/build-essential/list</tt> (which is
990 contained in the <tt>build-essential</tt> package).
994 When specifying the set of build-time dependencies, one
995 should list only those packages explicitly required by the
996 build. It is not necessary to list packages which are
997 required merely because some other package in the list of
998 build-time dependencies depends on them. The reason is
999 that dependencies change, and you should list only those
1000 <em>you</em> need. What others need is their business.
1004 If build-time dependencies are specified, it must be
1005 possible to build the package and produce working binaries
1006 on a system with the build-essential packages installed
1007 and satisfying the build-time relationships (including any
1008 implied relationships). This
1009 means in particular that version clauses should be used
1010 rigorously in build-time relationships so that one cannot
1011 produce bad or inconsistently configured packages when the
1012 relationships are properly satisfied.
1016 <heading>Changes to the upstream sources</heading>
1019 If changes to the source code are made that are generally
1020 applicable, they should be sent to the upstream authors
1021 in whatever form they prefer so as to be included in the
1022 upstream version of the package.</p>
1025 If you need to configure the package differently for
1026 Debian or for Linux, and the upstream source doesn't
1027 provide a way to configure it the way you need to, you
1028 should add such configuration facilities (for example, a new
1029 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
1030 the patch to the upstream authors, with the default set to
1031 the way they originally had it. You can then easily
1032 override the default in your <tt>debian/rules</tt> or
1033 wherever is appropriate.</p>
1036 You should make sure that the <prgn>configure</prgn> utility
1037 detects the correct architecture specification string
1038 (refer to <ref id="arch-spec"> for details).</p>
1041 If you need to edit a <prgn>Makefile</prgn> where
1042 GNU-style <prgn>configure</prgn> scripts are used, you
1043 should edit the <tt>.in</tt> files rather than editing the
1044 <prgn>Makefile</prgn> directly. This allows the user to
1045 reconfigure the package if necessary. You should
1046 <em>not</em> configure the package and edit the generated
1047 <prgn>Makefile</prgn>! This makes it impossible for
1048 someone else to later reconfigure the package.</p></sect1>
1052 <heading>Documenting your changes</heading>
1055 You should document your changes and updates to the source
1056 package properly in the <tt>debian/changelog</tt> file. (Note
1057 that mistakes in changelogs are usually best rectified by
1058 making a new changelog entry rather than "rewriting history"
1059 by editing old changelog entries)</p>
1062 A copy of the file which will be installed in
1063 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1064 in <tt>debian/copyright</tt>.</p>
1067 In non-experimental packages you must only use a format for
1068 <tt>debian/changelog</tt> which is supported by the most
1069 recent released version of <prgn>dpkg</prgn>. If your
1070 format is not supported and there is general support for
1071 it you should contact the <prgn>dpkg</prgn> maintainer to
1072 have the parser script for your format included in the
1073 <prgn>dpkg</prgn> package. (You will need to agree that
1074 the parser and its manpage may be distributed under the
1075 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1080 <heading>Error trapping in makefiles</heading>
1083 When <prgn>make</prgn> invokes a command in a makefile
1084 (including your package's upstream makefiles and the
1085 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1086 means that <tt>sh</tt>'s usual bad error handling
1087 properties apply: if you include a miniature script as one
1088 of the commands in your makefile you'll find that if you
1089 don't do anything about it then errors are not detected
1090 and <prgn>make</prgn> will blithely continue after
1094 Every time you put more than one shell command (this
1095 includes using a loop) in a makefile command you
1096 must make sure that errors are trapped. For
1097 simple compound commands, such as changing directory and
1098 then running a program, using <tt>&&</tt> rather
1099 than semicolon as a command separator is sufficient. For
1100 more complex commands including most loops and
1101 conditionals you should include a separate <tt>set -e</tt>
1102 command at the start of every makefile command that's
1103 actually one of these miniature shell scripts.</p></sect1>
1107 <heading>Obsolete constructs and libraries</heading>
1110 The include file <prgn><varargs.h></prgn> is
1111 provided to support end-users compiling very old software;
1112 the library <tt>libtermcap</tt> is provided to support the
1113 execution of software which has been linked against it
1114 (either old programs or those such as Netscape which are
1115 only available in binary form).</p>
1118 Debian packages should be ported to include
1119 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1124 <chapt><heading>The Operating System</heading>
1128 <heading>File system hierarchy</heading>
1132 <heading>Linux File system Structure</heading>
1135 The location of all installed files and directories must
1136 comply with the Linux File system Hierarchy Standard
1137 (FHS). The latest version of this document can be found
1138 alongside this manual or on
1139 <url id="http://www.pathname.com/fhs/">.<footnote>
1140 <p>The Debian distribution currently distributes a draft
1141 version of FHS 2.1 because several significant details
1142 have changed between the currently released 2.0
1143 version and the to-be-released 2.1 version.</p>
1145 Specific questions about following the standard may be
1146 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1147 Quinlan, the FHS coordinator, at
1148 <email>quinlan@pathname.com</email>.</p></sect1>
1152 <heading>Site-specific programs</heading>
1155 As mandated by the FHS, packages must not place any
1156 files in <tt>/usr/local</tt>, either by putting them in
1157 the file system archive to be unpacked by <prgn>dpkg</prgn>
1158 or by manipulating them in their maintainer scripts.</p>
1161 However, the package may create empty directories below
1162 <tt>/usr/local</tt> so that the system administrator knows
1163 where to place site-specific files. These directories
1164 should be removed on package removal if they are
1168 Note, that this applies only to directories <em>below</em>
1169 <tt>/usr/local</tt>, not <em>in</em>
1170 <tt>/usr/local</tt>. Packages must not create sub-directories
1171 in the directory <tt>/usr/local</tt> itself, except those listed in
1172 FHS, section 4.6. However, you may create directories
1173 below them as you wish. You must not remove any of the
1174 directories listed in 4.6, even if you created them.</p>
1177 Since <tt>/usr/local</tt> can be mounted read-only from a
1178 remote server, these directories must be created and
1179 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1180 maintainer scripts. These scripts must not fail if either
1181 of these operations fail. (In the future, it will be
1182 possible to tell <prgn>dpkg</prgn> not to unpack files
1183 matching certain patterns, so that the directories can be
1184 included in the <tt>.deb</tt> packages and system
1185 administrators who do not wish these directories in
1186 /usr/local do not need to have them.)</p>
1189 For example, the <prgn>emacs</prgn> package will contain
1191 mkdir -p /usr/local/lib/emacs/site-lisp || true
1193 in the <tt>postinst</tt> script, and
1195 rmdir /usr/local/lib/emacs/site-lisp && \
1196 rmdir /usr/local/lib/emacs || \
1199 in the <tt>prerm</tt> script.</p>
1202 If you do create a directory in <tt>/usr/local</tt> for
1203 local additions to a package, you should ensure that
1204 settings in <tt>/usr/local</tt> take precedence over the
1205 equivalents in <tt>/usr</tt>.</p>
1208 However, because '/usr/local' and its contents are for
1209 exclusive use of the local administrator, a package must
1210 not rely on the presence or absence of files or
1211 directories in '/usr/local' for normal operation.</p>
1214 The <tt>/usr/local</tt> directory itself and all the
1215 subdirectories created by the package should (by default) have
1216 permissions 2775 (group-writable and set-group-id) and be
1217 owned by <tt>root.staff</tt>.</p>
1222 <heading>Users and groups</heading>
1225 The Debian system can be configured to use either plain or
1226 shadow passwords.</p>
1229 Some user ids (UIDs) and group ids (GIDs) are reserved
1230 globally for use by certain packages. Because some packages
1231 need to include files which are owned by these users or
1232 groups, or need the ids compiled into binaries, these ids
1233 must be used on any Debian system only for the purpose for
1234 which they are allocated. This is a serious restriction, and
1235 we should avoid getting in the way of local administration
1236 policies. In particular, many sites allocate users and/or
1237 local system groups starting at 100.</p>
1240 Apart from this we should have dynamically allocated ids,
1241 which should by default be arranged in some sensible
1242 order--but the behavior should be configurable.</p>
1245 Packages other than <tt>base-passwd</tt> must not modify
1246 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
1247 <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
1250 The UID and GID ranges are as follows:
1255 Globally allocated by the Debian project, the
1256 same on every Debian system. These ids will appear in
1257 the <tt>passwd</tt> and <tt>group</tt> files of all
1258 Debian systems, new ids in this range being added
1259 automatically as the <tt>base-passwd</tt> package is
1263 Packages which need a single statically allocated uid
1264 or gid should use one of these; their maintainers
1265 should ask the <tt>base-passwd</tt> maintainer for
1272 Dynamically allocated system users and groups.
1273 Packages which need a user or group, but can have this
1274 user or group allocated dynamically and differently on
1275 each system, should use `<tt>adduser --system</tt>' to
1276 create the group and/or user. <prgn>adduser</prgn>
1277 will check for the existence of the user or group, and
1278 if necessary choose an unused id based on the ranged
1279 specified in <tt>adduser.conf</tt>.</p></item>
1282 <tag>1000-29999:</tag>
1285 Dynamically allocated user accounts. By default
1286 <prgn>adduser</prgn> will choose UIDs and GIDs for
1287 user accounts in this range, though
1288 <tt>adduser.conf</tt> may be used to modify this
1292 <tag>30000-59999:</tag>
1294 <p>Reserved.</p></item>
1297 <tag>60000-64999:</tag>
1300 Globally allocated by the Debian project, but only
1301 created on demand. The ids are allocated centrally and
1302 statically, but the actual accounts are only created
1303 on users' systems on demand.</p>
1306 These ids are for packages which are obscure or which
1307 require many statically-allocated ids. These packages
1308 should check for and create the accounts in
1309 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1310 <prgn>adduser</prgn> if it has this facility) if
1311 necessary. Packages which are likely to require
1312 further allocations should have a `hole' left after
1313 them in the allocation, to give them room to
1317 <tag>65000-65533:</tag>
1319 <p>Reserved.</p></item>
1324 <p>User `<tt>nobody</tt>.'</p></item>
1330 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1331 because it is the error return sentinel value.</p>
1336 <sect id="sysvinit">
1337 <heading>System run levels</heading>
1340 <sect1 id="/etc/init.d">
1341 <heading>Introduction</heading>
1344 The <tt>/etc/init.d</tt> directory contains the scripts
1345 executed by <prgn>init</prgn> at boot time and when init
1346 state (or `runlevel') is changed (see <manref name="init"
1350 There are at least two different, yet functionally
1351 equivalent, ways of handling these scripts. For the sake
1352 of simplicity, this document describes only the symbolic
1353 link method. However, it must not be assumed that this
1354 method is being used, and any manipulation of the various
1355 runlevel behaviours must be performed using
1356 <prgn>update-rc.d</prgn> as described below and not by
1357 manually installing symlinks. For information on the
1358 implementation details of the other method, implemented in
1359 the <tt>file-rc</tt> package, please refer to the
1360 documentation of that package.</p>
1363 These scripts are referenced by symbolic links in
1364 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1365 changing runlevels, <prgn>init</prgn> looks in the
1366 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1367 it should execute, where <var>n</var> is the runlevel that
1368 is being changed to, or `S' for the boot-up scripts.</p>
1371 The names of the links all have the form
1372 <tt>S<var>mm</var><var>script</var></tt> or
1373 <tt>K<var>mm</var><var>script</var></tt> where
1374 <var>mm</var> is a two-digit number and <var>script</var>
1375 is the name of the script (this should be the same as the
1376 name of the actual script in <tt>/etc/init.d</tt>.</p>
1379 When <prgn>init</prgn> changes runlevel first the targets
1380 of the links whose names starting with a <tt>K</tt> are
1381 executed, each with the single argument <tt>stop</tt>,
1382 followed by the scripts prefixed with an <tt>S</tt>, each
1383 with the single argument <tt>start</tt>. The <tt>K</tt>
1384 links are responsible for killing services and the
1385 <tt>S</tt> link for starting services upon entering the
1389 For example, if we are changing from runlevel 2 to
1390 runlevel 3, init will first execute all of the <tt>K</tt>
1391 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1392 all of the <tt>S</tt> prefixed scripts. The links
1393 starting with <tt>K</tt> will cause the referred-to file
1394 to be executed with an argument of <tt>stop</tt>, and the
1395 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1398 The two-digit number <var>mm</var> is used to decide which
1399 order to start and stop things in--low-numbered links have
1400 their scripts run first. For example, the <tt>K20</tt>
1401 scripts will be executed before the <tt>K30</tt> scripts.
1402 This is used when a certain service must be started before
1403 another. For example, the name server <prgn>bind</prgn>
1404 might need to be started before the news server
1405 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1406 access lists. In this case, the script that starts
1407 <prgn>bind</prgn> would have a lower number than the
1408 script that starts <prgn>inn</prgn> so that it runs first:
1417 <heading>Writing the scripts</heading>
1420 Packages that include daemons for system services should
1421 place scripts in <tt>/etc/init.d</tt> to start or stop
1422 services at boot time or during a change of runlevel.
1423 These scripts should be named
1424 <tt>/etc/init.d/<var>package</var></tt>, and they should
1425 accept one argument, saying what to do:
1428 <tag><tt>start</tt></tag>
1429 <item><p>start the service,</p></item>
1431 <tag><tt>stop</tt></tag>
1432 <item><p>stop the service,</p></item>
1434 <tag><tt>restart</tt></tag>
1435 <item><p>stop and restart the service,</p></item>
1437 <tag><tt>reload</tt></tag>
1438 <item><p>cause the configuration of the service to be
1439 reloaded without actually stopping and restarting
1440 the service,</p></item>
1442 <tag><tt>force-reload</tt></tag> <item><p>cause the
1443 configuration to be reloaded if the service supports
1444 this, otherwise restart the service.</p></item>
1447 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1448 <tt>force-reload</tt> options should be supported by all
1449 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1450 option is optional.</p>
1453 The <tt>init.d</tt> scripts should ensure that they will
1454 behave sensibly if invoked with <tt>start</tt> when the
1455 service is already running, or with <tt>stop</tt> when it
1456 isn't, and that they don't kill unfortunately-named user
1457 processes. The best way to achieve this is usually to use
1458 <prgn>start-stop-daemon</prgn>.</p>
1461 If a service reloads its configuration automatically (as
1462 in the case of <prgn>cron</prgn>, for example), the
1463 <tt>reload</tt> option of the <tt>init.d</tt> script
1464 should behave as if the configuration has been reloaded
1468 These scripts should not fail obscurely when the
1469 configuration files remain but the package has been
1470 removed, as configuration files remain on the system after
1471 the package has been removed. Only when <prgn>dpkg</prgn>
1472 is executed with the <tt>--purge</tt> option will
1473 configuration files be removed. In particular, the init
1474 script itself is usually a configuration file (see
1475 <ref id="init.d notes">), and will remain on the system if
1476 the package is removed but not purged. Therefore, you
1477 should include a <tt>test</tt> statement at the top of the
1480 test -f <var>program-executed-later-in-script</var> || exit 0
1485 <heading>Managing the links</heading>
1488 The program <prgn>update-rc.d</prgn> is provided to make
1489 it easier for package maintainers to arrange for the
1490 proper creation and removal of
1491 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1492 functional equivalent if another method is being used.
1493 This may be used by maintainers in their packages'
1494 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1497 You must use this script to make changes to
1498 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1499 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1500 in the actual archive or manually create or remove the
1501 symbolic links in maintainer scripts. (The latter will
1502 fail if an alternative method of maintaining runlevel
1503 information is being used.)</p>
1506 By default <prgn>update-rc.d</prgn> will start services in
1507 each of the multi-user state runlevels (2, 3, 4, and 5)
1508 and stop them in the halt runlevel (0), the single-user
1509 runlevel (1) and the reboot runlevel (6). The system
1510 administrator will have the opportunity to customize
1511 runlevels by either running <prgn>update-rc.d</prgn>, by
1512 simply adding, moving, or removing the symbolic links in
1513 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1514 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1515 <tt>file-rc</tt> method is being used.</p>
1518 To get the default behavior for your package, put in your
1519 <tt>postinst</tt> script
1521 update-rc.d <var>package</var> defaults >/dev/null
1523 and in your <tt>postrm</tt>
1525 if [ purge = "$1" ]; then
1526 update-rc.d <var>package</var> remove >/dev/null
1531 This will use a default sequence number of 20. If it does
1532 not matter when or in which order the script is run, use
1533 this default. If it does, then you should talk to the
1534 maintainer of the <prgn>sysvinit</prgn> package or post to
1535 <tt>debian-devel</tt>, and they will help you choose a
1539 For more information about using <tt>update-rc.d</tt>,
1540 please consult its manpage <manref name="update-rc.d"
1541 section="8">.</p></sect1>
1545 <heading>Boot-time initialization</heading>
1548 There used to be another directory, <tt>/etc/rc.boot</tt>,
1549 which contained scripts which were run once per machine
1550 boot. This has been deprecated in favour of links from
1551 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1552 described in <ref id="/etc/init.d">. Packages must not
1553 place files in <tt>/etc/rc.boot</tt>.</p>
1555 <sect1 id="init.d notes">
1556 <heading>Notes</heading>
1559 <em>Do not</em> include the
1560 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1561 <tt>.deb</tt> file system archive! <em>This will cause
1562 problems!</em> You must create them with
1563 <prgn>update-rc.d</prgn>, as above.</p>
1566 <em>Do not</em> include the
1567 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1568 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1569 problems!</em> You should, however, treat the
1570 <tt>/etc/init.d</tt> scripts as configuration files,
1571 either by marking them as conffiles or managing them
1572 correctly in the maintainer scripts (see
1573 <ref id="config files">). (This is important since we want
1574 to give the local system administrator the chance to adapt
1575 the scripts to the local system--e.g., to disable a
1576 service without de-installing the package, or to specify
1577 some special command line options when starting a
1578 service--while making sure her changes aren't lost during
1579 the next package upgrade.)</p>
1583 <heading>Example</heading>
1586 The <prgn>bind</prgn> DNS (nameserver) package wants to
1587 make sure that the nameserver is running in multiuser
1588 runlevels, and is properly shut down with the system. It
1589 puts a script in <tt>/etc/init.d</tt>, naming the script
1590 appropriately <tt>bind</tt>. As you can see, the script
1591 interprets the argument <tt>reload</tt> to send the
1592 nameserver a <tt>HUP</tt> signal (causing it to reload its
1593 configuration); this way the user can say
1594 <tt>/etc/init.d/bind reload</tt> to reload the name
1601 # Original version by Robert Leslie
1602 # <rob@mars.org>, edited by iwj and cs
1604 test -x /usr/sbin/named || exit 0
1608 echo -n "Starting domain name service: named"
1609 start-stop-daemon --start --quiet --exec /usr/sbin/named
1613 echo -n "Stopping domain name service: named"
1614 start-stop-daemon --stop --quiet \
1615 --pidfile /var/run/named.pid --exec /usr/sbin/named
1619 echo -n "Restarting domain name service: named"
1620 start-stop-daemon --stop --quiet \
1621 --pidfile /var/run/named.pid --exec /usr/sbin/named
1622 start-stop-daemon --start --verbose --exec /usr/sbin/named
1625 force-reload|reload)
1626 echo -n "Reloading configuration of domain name service: named"
1627 start-stop-daemon --stop --signal 1 --quiet \
1628 --pidfile /var/run/named.pid --exec /usr/sbin/named
1632 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1641 Another example on which to base your <tt>/etc/init.d</tt>
1642 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1645 If this package is happy with the default setup from
1646 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1647 and having named running in all runlevels, it can say in
1648 its <tt>postinst</tt>:
1650 update-rc.d bind defaults >/dev/null
1652 And in its <tt>postrm</tt>, to remove the links when the
1655 if [ purge = "$1" ]; then
1656 update-rc.d bind remove >/dev/null
1662 <heading>Cron jobs</heading>
1665 Packages must not modify the configuration file
1666 <tt>/etc/crontab</tt>, and they must not modify the files in
1667 <tt>/var/spool/cron/crontabs</tt>.</p>
1670 If a package wants to install a job that has to be executed
1671 via cron, it should place a file with the name if the
1672 package in one of the following directories:
1678 As these directory names imply, the files within them are
1679 executed on a daily, weekly, or monthly basis,
1680 respectively. The exact times are listed in
1681 <tt>/etc/crontab</tt>.</p>
1684 All files installed in any of these directories must be
1685 scripts (shell scripts, Perl scripts, etc.) so that they can
1686 easily be modified by the local system administrator. In
1687 addition, they should be treated as configuration files.</p>
1690 If a certain job has to be executed more frequently than
1691 daily, the package should install a file
1692 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1693 the same syntax as <tt>/etc/crontab</tt> and is processed by
1694 <prgn>cron</prgn> automatically. The file must also be
1695 treated as a configuration file. (Note, that entries in the
1696 <tt>/etc/cron.d</tt> directory are not handled by
1697 <prgn>anacron</prgn>. Thus, you should only use this
1698 directory for jobs which may be skipped if the system is not
1702 The scripts or crontab entries in these directories should
1703 check if all necessary programs are installed before they
1704 try to execute them. Otherwise, problems will arise when a
1705 package was removed but not purged since configuration files
1706 are kept on the system in this situation.</p>
1710 <heading>Console messages</heading>
1713 This section describes different formats for messages
1714 written to standard output by the <tt>/etc/init.d</tt>
1715 scripts. The intent is to improve the consistency of
1716 Debian's startup and shutdown look and feel.</p>
1719 Please look very careful at the details. We want to get the
1720 messages to look exactly the same way concerning spaces,
1721 punctuation, and case of letters.</p>
1724 Here is a list of overall rules that you should use when you
1725 create output messages. They can be useful if you have a
1726 non-standard message that isn't covered in the sections
1733 Every message should cover one line, start with a
1734 capital letter and end with a period `.'.</p></item>
1739 If you want to express that the computer is working on
1740 something (performing a specific task, not starting or
1741 stopping a program), we use an ``ellipsis'', namely
1742 three dots `...'. Note that we don't insert spaces in
1743 front of or behind the dots. If the task has been
1744 completed we write `done.' and a line feed.</p></item>
1749 Design your messages as if the computer is telling you
1750 what he is doing (let him be polite :-) but don't
1751 mention ``him'' directly. For example, if you think
1754 I'm starting network daemons: nfsd mountd.
1758 Starting network daemons: nfsd mountd.
1759 </example></p></item>
1763 The following formats should be used</p>
1768 <p>when daemons get started.</p>
1771 Use this format if your script starts one or more
1772 daemons. The output should look like this (a single
1773 line, no leading spaces):
1775 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1777 The <description> should describe the subsystem
1778 the daemon or set of daemons are part of, while
1779 <daemon-1> up to <daemon-n> denote each
1780 daemon's name (typically the file name of the
1784 For example, the output of /etc/init.d/lpd would look like:
1786 Starting printer spooler: lpd.
1790 This can be achieved by saying
1792 echo -n "Starting printer spooler: lpd"
1793 start-stop-daemon --start --quiet lpd
1796 in the script. If you have more than one daemon to
1797 start, you should do the following:
1799 echo -n "Starting remote file system services:"
1800 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1801 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1802 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1805 This makes it possible for the user to see what takes
1806 so long and when the final daemon has been
1807 started. You should be careful where to put spaces: In the
1808 example above the system administrator can easily
1809 comment out a line if he don't wants to start a
1810 specific daemon, while the displayed message still
1811 looks good.</p></item>
1815 <p>when something needs to be configured.</p>
1818 If you have to set up different parameters of the
1819 system upon boot up, you should use this format:
1821 Setting <parameter> to `<value>'.
1825 You can use the following echo statement to get the quotes right:
1827 echo "Setting DNS domainname to \`"value"'."
1831 Note that the left quotation mark (`) is different
1832 from the right (').</p></item>
1835 <p>when a daemon is stopped.</p>
1838 When you stop a daemon you should issue a message
1839 similar to the startup message, except that `Starting'
1840 is replaced with `Stopping'.</p>
1843 So stopping the printer daemon will like like this:
1845 Stopping printer spooler: lpd.
1846 </example></p></item>
1849 <p>when something is executed.</p>
1852 There are several examples where you have to run a
1853 program at system startup or shutdown to perform a
1854 specific task. For example, setting the system's clock
1855 via `netdate' or killing all processes when the system
1856 comes down. Your message should like this:
1858 Doing something very useful...done.
1860 You should print the `done.' right after the job has been completed,
1861 so that the user gets informed why he has to wait. You can get this
1864 echo -n "Doing something very useful..."
1868 in your script.</p></item>
1871 <p>when the configuration is reloaded.</p>
1874 When a daemon is forced to reload its configuration
1875 files you should use the following format:
1877 Reloading <daemon's-name> configuration...done.
1878 </example></p></item>
1881 <p>when none of the above rules apply.</p>
1884 If you have to print a message that doesn't fit into
1885 the styles described above, you can use something
1886 appropriate, but please have a look at the overall
1887 rules listed above.</p></item>
1892 <heading>Menus</heading>
1895 Menu entries should follow the current menu policy as
1896 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1897 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1898 or your local mirror. In addition, it is included in the
1899 <tt>debian-policy</tt> package.
1903 The Debian <tt>menu</tt> packages provides a unique
1904 interface between packages providing applications and
1905 documents, and <em>menu programs</em> (either X window
1906 managers or text-based menu programs as
1907 <prgn>pdmenu</prgn>).</p>
1910 All packages that provide applications that need not be
1911 passed any special command line arguments for normal
1912 operation should register a menu entry for those
1913 applications, so that users of the <tt>menu</tt> package
1914 will automatically get menu entries in their window
1915 managers, as well in shells like <tt>pdmenu</tt>.</p>
1918 Please refer to the <em>Debian Menu System</em> document
1919 that comes with the <tt>menu</tt> package for information
1920 about how to register your applications and web
1926 <heading>Multimedia handlers</heading>
1929 Packages which provide the ability to view/show/play,
1930 compose, edit or print MIME types should register themselves
1931 as such following the current MIME support policy as defined
1932 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1933 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1934 or your local mirror. In addition, it is included in the
1935 <tt>debian-policy</tt> package.
1939 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1940 mechanism for encoding files and data streams and providing
1941 meta-information about them, in particular their type (e.g.
1942 audio or video) and format (e.g. PNG, HTML, MP3).
1946 Registration of MIME type handlers allows programs like mail
1947 user agents and web browsers to to invoke these handlers to
1948 view, edit or display MIME types they don't support
1954 <heading>Keyboard configuration</heading>
1957 To achieve a consistent keyboard configuration (i.e., all
1958 applications interpret a keyboard event the same way) all
1959 programs in the Debian distribution must be configured to
1960 comply with the following guidelines.</p>
1963 Here is a list that contains certain keys and their interpretation:
1966 <tag><tt><--</tt></tag>
1967 <item><p>delete the character to the left of the cursor</p></item>
1969 <tag><tt>Delete</tt></tag>
1970 <item><p>delete the character to the right of the cursor</p></item>
1972 <tag><tt>Control+H</tt></tag>
1973 <item><p>emacs: the help prefix</p></item>
1976 The interpretation of any keyboard events should be independent
1977 of the terminal that's used, be it a virtual console, an X
1978 terminal emulator, an rlogin/telnet session, etc.</p>
1981 The following list explains how the different programs
1982 should be set up to achieve this:</p>
1985 <list compact="compact">
1986 <item><p>`<tt><--</tt>' generates KB_Backspace in
1989 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1993 X translations are set up to make KB_Backspace
1994 generate ASCII DEL, and to make KB_Delete generate
1995 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1996 the `delete character' key). This must be done by
1997 loading the resources using xrdb on all local X
1998 displays, not using the application defaults, so that
1999 the translation resources used correspond to the
2000 xmodmap settings.</p></item>
2004 The Linux console is configured to make
2005 `<tt><--</tt>' generate DEL, and `Delete' generate
2006 <tt>ESC [ 3 ~</tt> (this is the case at the
2010 X applications are configured so that Backspace
2011 deletes left, and Delete deletes right. Motif
2012 applications already work like this.</p></item>
2014 <item><p>stty erase <tt>^?</tt> .</p></item>
2017 The `xterm' terminfo entry should have <tt>ESC [ 3
2018 ~</tt> for kdch1, just like TERM=linux and
2019 TERM=vt220.</p></item>
2022 Emacs is programmed to map KB_Backspace or the `stty
2023 erase' character to delete-backward-char, and
2024 KB_Delete or kdch1 to delete-forward-char, and
2025 <tt>^H</tt> to help as always.</p></item>
2028 Other applications use the `stty erase' character and
2029 kdch1 for the two delete keys, with ASCII DEL being
2030 `delete previous character' and kdch1 being `delete
2031 character under cursor'.</p></item>
2035 This will solve the problem except for:</p>
2038 <list compact="compact">
2040 Some terminals have a <tt><--</tt> key that cannot
2041 be made to produce anything except <tt>^H</tt>. On
2042 these terminals Emacs help will be unavailable on
2043 <tt>^H</tt> (assuming that the `stty erase' character
2044 takes precedence in Emacs, and has been set
2045 correctly). M-x help or F1 (if available) can be used
2049 Some operating systems use <tt>^H</tt> for stty erase.
2050 However, modern telnet versions and all rlogin
2051 versions propagate stty settings, and almost all UNIX
2052 versions honour stty erase. Where the stty settings
2053 are not propagated correctly things can be made to
2054 work by using stty manually.</p></item>
2057 Some systems (including previous Debian versions) use
2058 xmodmap to arrange for both <tt><--</tt> and Delete
2059 to generate KB_Delete. We can change the behavior
2060 of their X clients via the same X resources that we
2061 use to do it for our own, or have our clients be
2062 configured via their resources when things are the
2063 other way around. On displays configured like this
2064 Delete will not work, but <tt><--</tt>
2068 Some operating systems have different kdch1 settings
2069 in their terminfo for xterm and others. On these
2070 systems the Delete key will not work correctly when
2071 you log in from a system conforming to our policy, but
2072 <tt><--</tt> will.</p></item>
2079 <heading>Environment variables</heading>
2082 A program must not depend on environment variables to get
2083 reasonable defaults. (That's because these environment
2084 variables would have to be set in a system-wide
2085 configuration file like /etc/profile, which is not supported
2089 If a program usually depends on environment variables for its
2090 configuration, the program should be changed to fall back to
2091 a reasonable default configuration if these environment
2092 variables are not present. If this cannot be done easily
2093 (e.g., if the source code of a non-free program is not
2094 available), the program must be replaced by a small
2095 `wrapper' shell script which sets the environment variables
2096 if they are not already defined, and calls the original program.</p>
2099 Here is an example of a wrapper script for this purpose:
2103 BAR=${BAR:-/var/lib/fubar}
2105 exec /usr/lib/foo/foo "$@"
2109 Furthermore, as <tt>/etc/profile</tt> is a configuration
2110 file of the <prgn>base-files</prgn> package, other packages must not
2111 put any environment variables or other commands into that
2116 <heading>Files</heading>
2120 <heading>Binaries</heading>
2123 Two different packages must not install programs with
2124 different functionality but with the same filenames. (The
2125 case of two programs having the same functionality but
2126 different implementations is handled via `alternatives.')
2127 If this case happens, one of the programs must be
2128 renamed. The maintainers should report this to the
2129 developers' mailing and try to find a consensus about
2130 which package will have to be renamed. If a consensus can
2131 not be reached, <em>both</em> programs must be
2135 Generally the following compilation parameters should be used:
2138 CFLAGS = -O2 -Wall # sane warning options vary between programs
2140 install -s # (or use strip on the files in debian/tmp)
2144 Note that by default all installed binaries should be stripped,
2145 either by using the <tt>-s</tt> flag to
2146 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2147 the binaries after they have been copied into
2148 <tt>debian/tmp</tt> but before the tree is made into a
2152 The <tt>-N</tt> flag should not be used. On a.out systems
2153 it may have been useful for some very small binaries, but
2154 for ELF it has no good effect.</p>
2157 Debugging symbols are useful for error diagnosis,
2158 investigation of core dumps (which may be submitted by users
2159 in bug reports), or testing and developing the
2160 software. Therefore it is recommended to support building
2161 the package with debugging information through the following
2162 interface: If the environment variable
2163 <tt>DEB_BUILD_OPTIONS</tt> contains the string
2164 <tt>debug</tt>, compile the software with debugging
2165 information (usually this involves adding the <tt>-g</tt>
2166 flag to <tt>CFLAGS</tt>). This allows the generation of a
2167 build tree with debugging information. If the environment
2168 variable <tt>DEB_BUILD_OPTIONS</tt> contains the string
2169 <tt>nostrip</tt>, do not strip the files at installation
2170 time. This allows one to generate a package with debugging
2171 information included. The following makefile snippet is only
2172 an example of how one may test for either condition:
2175 Rationale: Building by default with -g causes more
2176 wasted CPU cycles since the information is stripped away
2177 anyway. The package can by default build without -g if
2178 it also provides a mechanism to easily be rebuilt with
2179 debugging information. This can be done by providing a
2180 "build-debug" make target, or allowing the user to
2181 specify "DEB_BUILD_OPTIONS=debug" in the environment while
2182 compiling that package.
2184 <p>Now this has several added benefits:
2188 It is actually easier to build debugging bins and
2189 libraries this way (no more editing debian/rules
2190 or similar) since it provides a documented way of
2191 getting this type of build.</p>
2195 There will be much less wasted cpu time for the
2196 autobuilders since not having debugging
2197 information (and hence also not having to strip
2198 it) will increase the speed of compiles. This
2199 skips an entire pass of the compiler.
2210 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
2213 ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
2219 It is up to the package maintainer to decide what
2220 compilation options are best for the package. Certain
2221 binaries (such as computationally-intensive programs) will
2222 function better with certain flags (<tt>-O3</tt>, for
2223 example); feel free to use them. Please use good judgment
2224 here. Don't use flags for the sake of it; only use them
2225 if there is good reason to do so. Feel free to override
2226 the upstream author's ideas about which compilation
2227 options are best--they are often inappropriate for our
2228 environment.</p></sect>
2232 <heading>Libraries</heading>
2235 All libraries must have a shared version in the lib
2236 package and a static version in the lib-dev package. The
2237 shared version must be compiled with <tt>-fPIC</tt>, and
2238 the static version must not be. In other words, each
2239 <tt>*.c</tt> file will need to be compiled twice.</p>
2242 You must specify the gcc option <tt>-D_REENTRANT</tt>
2243 when building a library (either static or shared) to make
2244 the library compatible with LinuxThreads.</p>
2247 Note that all installed shared libraries should be
2250 strip --strip-unneeded <your-lib>
2252 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2253 only the symbols which aren't needed for relocation
2254 processing.) Shared libraries can function perfectly well
2255 when stripped, since the symbols for dynamic linking are
2256 in a separate part of the ELF object file.</p>
2259 Note that under some circumstances it may be useful to
2260 install a shared library unstripped, for example when
2261 building a separate package to support debugging.
2265 An ever increasing number of packages are using libtool to
2266 do their linking. The latest GNU libtools (>= 1.3a) can take
2267 advantage of the metadata in the installed libtool archive
2268 files (`*.la'). The main advantage of libtool's .la files is
2269 that it allows libtool to store and subsequently access
2270 metadata with respect to the libraries it builds. libtool
2271 will search for those files, which contain a lot of useful
2272 information about a library (e.g. dependency libraries for
2273 static linking). Also, they're <em>essential</em> for
2274 programs using libltdl.
2278 Certainly libtool is fully capable of linking against shared
2279 libraries which don't have .la files, but being a mere shell
2280 script it can add considerably to the build time of a
2281 libtool using package if that shell-script has to derive all
2282 this information from first principles for each library every
2283 time it is linked. With the advent of libtool-1.4 (and to a
2284 lesser extent libtool-1.3), the .la files will also store
2285 information about inter-library dependencies which cannot
2286 necessarily be derived after the .la file is deleted.
2290 Packages that use libtool to create shared libraries should
2291 include the <em>.la</em> files in the <em>-dev</em>
2292 packages, with the exception that if the package relies on
2293 libtool's <em>libltdl</em> library, in which case the .la
2294 files must go in the run-time library package. This is a
2295 good idea in general, and especially for static linking
2300 You must make sure that you use only released versions of
2301 shared libraries to build your packages; otherwise other
2302 users will not be able to run your binaries
2303 properly. Producing source packages that depend on
2304 unreleased compilers is also usually a bad
2311 <heading>Shared libraries</heading>
2314 Packages involving shared libraries should be split up
2315 into several binary packages.</p>
2318 For a straightforward library which has a development
2319 environment and a runtime kit including just shared
2320 libraries you need to create two packages:
2321 <tt><var>libraryname</var><var>soname</var></tt>
2322 (<var>soname</var> is the shared object name of the shared
2323 library--it's the thing that has to match exactly between
2324 building an executable and running it for the dynamic
2325 linker to be able run the program; usually the
2326 <var>soname</var> is the major number of the library) and
2327 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2330 If you prefer only to support one development version at a
2331 time you may name the development package
2332 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2333 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2334 ensure that the user only installs one development version
2335 at a time (after all, different development versions are
2336 likely to have the same header files in them, causing a
2337 filename clash if both are installed). Typically the
2338 development version should also have an exact version
2339 dependency on the runtime library, to make sure that
2340 compilation and linking happens correctly.</p>
2343 Packages which use the shared library should have a
2344 dependency on the name of the shared library package,
2345 <tt><var>libraryname</var><var>soname</var></tt>. When
2346 the <var>soname</var> changes you can have both versions
2347 of the library installed while moving from the old library
2351 If your package has some run-time support programs which
2352 use the shared library you must not put them in
2353 the shared library package. If you do that then you won't
2354 be able to install several versions of the shared library
2355 without getting filename clashes. Instead, either create
2356 a third package for the runtime binaries (this package
2357 might typically be named
2358 <tt><var>libraryname</var>-runtime</tt>--note the absence
2359 of the <var>soname</var> in the package name) or if the
2360 development package is small include them in there.</p>
2363 If you have several shared libraries built from the same
2364 source tree you may lump them all together into a single
2365 shared library package, provided that you change all their
2366 <var>soname</var>s at once (so that you don't get filename
2367 clashes if you try to install different versions of the
2368 combined shared libraries package).</p>
2371 You should follow the directions in the <em>Debian Packaging
2372 Manual</em> for putting the shared library in its package,
2373 and you must include a <tt>shlibs</tt> control area
2374 file with details of the dependencies for packages which
2375 use the library.</p>
2378 Shared libraries should not be installed
2379 executable, since <prgn>ld.so</prgn> does not require this
2380 and trying to execute a shared library results in a core
2385 <heading>Scripts</heading>
2388 All command scripts, including the package maintainer
2389 scripts inside the package and used by <prgn>dpkg</prgn>,
2390 should have a <tt>#!</tt> line naming the shell to be used
2391 to interpret them.</p>
2394 In the case of Perl scripts this should be
2395 <tt>#!/usr/bin/perl</tt>.</p>
2398 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2399 should almost certainly start with <tt>set -e</tt> so that
2400 errors are detected. Every script should use
2401 <tt>set -e</tt> or check the exit status of <em>every</em>
2405 The standard shell interpreter `<tt>/bin/sh</tt>' can be a
2406 symbolic link to any POSIX compatible shell, if <tt>echo
2407 -n</tt> does not generate a newline.
2410 Debian policy specifies POSIX behavior for /bin/sh, but
2411 echo -n has widespread use in the Linux community
2412 (including especially debian policy, the linux kernel
2413 source, many debian scripts, etc.). This echo -n
2414 mechanism is valid but not required under POSIX, hence
2415 this explicit addition. Also, rumour has it that this
2416 shall be mandated under the LSB anyway.
2420 specifying `<tt>/bin/sh</tt>' as interpreter should only
2421 use POSIX features. If a script requires non-POSIX
2422 features from the shell interpreter, the appropriate shell
2423 must be specified in the first line of the script (e.g.,
2424 `<tt>#!/bin/bash</tt>') and the package must depend on the
2425 package providing the shell (unless the shell package is
2426 marked `Essential', e.g., in the case of
2431 You may wish to restrict your script to POSIX features when possible so
2432 that it may use <tt>/bin/sh</tt> as its interpreter. If
2433 your script works with <prgn>ash</prgn>, it's probably
2434 POSIX compliant, but if you are in doubt, use
2435 <tt>/bin/bash</tt>.</p>
2438 Perl scripts should check for errors when making any
2439 system calls, including <tt>open</tt>, <tt>print</tt>,
2440 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2443 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2444 as scripting languages. See <em>Csh Programming
2445 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2446 FAQs. It can be found on
2447 <url id="http://language.perl.com/versus/csh.whynot">, or
2448 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2449 or even on <ftpsite>ftp.cpan.org</ftpsite>
2450 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2451 If an upstream package comes with <prgn>csh</prgn> scripts
2452 then you must make sure that they start with
2453 <tt>#!/bin/csh</tt> and make your package depend on the
2454 <prgn>c-shell</prgn> virtual package.</p>
2457 Any scripts which create files in world-writeable
2458 directories (e.g., in <tt>/tmp</tt>) must use a
2459 mechanism which will fail if a file with the same name
2463 The Debian base distribution provides the
2464 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2465 for use by scripts for this purpose.</p></sect>
2469 <heading>Symbolic links</heading>
2472 In general, symbolic links within a top-level directory
2473 should be relative, and symbolic links pointing from one
2474 top-level directory into another should be absolute. (A
2475 top-level directory is a sub-directory of the root
2479 In addition, symbolic links should be specified as short
2480 as possible, i.e., link targets like `foo/../bar' are
2484 Note that when creating a relative link using
2485 <prgn>ln</prgn> it is not necessary for the target of the
2486 link to exist relative to the working directory you're
2487 running <prgn>ln</prgn> from; nor is it necessary to
2488 change directory to the directory where the link is to be
2489 made. Simply include the string that should appear as the
2490 target of the link (this will be a pathname relative to
2491 the directory in which the link resides) as the first
2492 argument to <prgn>ln</prgn>.</p>
2495 For example, in your <prgn>Makefile</prgn> or
2496 <tt>debian/rules</tt>, do things like:
2498 ln -fs gcc $(prefix)/bin/cc
2499 ln -fs gcc debian/tmp/usr/bin/cc
2500 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2501 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2505 A symbolic link pointing to a compressed file should
2506 always have the same file extension as the referenced
2507 file. (For example, if a file `<tt>foo.gz</tt>' is
2508 referenced by a symbolic link, the filename of the link
2509 has to end with `<tt>.gz</tt>' too, as in
2510 `bar.gz.')</p></sect>
2514 <heading>Device files</heading>
2517 Packages must not include device files in the package file
2521 If a package needs any special device files that are not
2522 included in the base system, it must call
2523 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2524 after asking the user for permission to do so.</p>
2527 Packages must not remove any device files in the
2528 <tt>postrm</tt> or any other script. This is left to the
2529 system administrator.</p>
2532 Debian uses the serial devices
2533 <tt>/dev/ttyS*</tt>. Programs using the old
2534 <tt>/dev/cu*</tt> devices should be changed to use
2535 <tt>/dev/ttyS*</tt>.</p>
2538 <sect id="config files">
2539 <heading>Configuration files</heading>
2541 <heading>Definitions</heading>
2544 <tag>configuration file</tag>
2546 A file that affects the operation of program, or
2547 provides site- or host-specific information, or
2548 otherwise customizes the behavior of program.
2549 Typically, configuration files are intended to be
2550 modified by the system administrator (if needed or
2551 desired) to conform to local policy or provide more
2552 useful site-specific behavior.</p>
2555 <tag><tt>conffile</tt></tag>
2557 A file listed in a package's <tt>conffiles</tt>
2558 file, and is treated specially by <prgn>dpkg</prgn>
2559 (see the <em>Debian Packaging Manual</em>).</p>
2565 The distinction between these two is important; they are
2566 not interchangeable concepts. Almost all
2567 <tt>conffiles</tt> are configuration files, but many
2568 configuration files are not <tt>conffiles</tt>.</p>
2571 Note that a script that embeds configuration information
2572 (such as most of the files in <tt>/etc/init.d</tt> and
2573 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2574 configuration file and should be treated as such.</p>
2578 <heading>Location</heading>
2580 Any configuration files created or used by your package
2581 must reside in <tt>/etc</tt>. If there are several you
2582 should consider creating a subdirectory of <tt>/etc</tt>
2583 named after your package.</p>
2586 If your package creates or uses configuration files
2587 outside of <tt>/etc</tt>, and it is not feasible to modify
2588 the package to use the <tt>/etc</tt>, you should still put
2589 the files in <tt>/etc</tt> and create symbolic links to
2590 those files from the location that the package
2595 <heading>Behavior</heading>
2597 Configuration file handling must conform to the following
2601 <p>local changes must be preserved during a package
2605 <p>configuration files must be preserved when the
2606 package is removed, and only deleted when the
2607 package is purged.</p>
2612 The easy way to achieve this behavior is to make the
2613 configuration file a <tt>conffile</tt>. This is
2614 appropriate only if it is possible to distribute a default
2615 version that will work for most installations, although
2616 some system administrators may choose to modify it. This
2617 implies that the default version will be part of the
2618 package distribution, and must not be modified by the
2619 maintainer scripts during installation (or at any other
2624 In order to ensure that local changes are preserved
2625 correctly, no package may contain or make hard links to
2629 Rationale: There are two problems with hard links.
2630 The first is that some editors break the link while
2631 editing one of the files, so that the two files may
2632 unwittingly become different. The second is that
2633 <prgn>dpkg</prgn> might break the hard link while
2634 upgrading <tt>conffile</tt>s.
2639 The other way to do it is via the maintainer scripts.
2640 In this case, the configuration file must not be listed as
2641 a <tt>conffile</tt> and must not be part of the package
2642 distribution. If the existence of a file is required for
2643 the package to be sensibly configured it is the
2644 responsibility of the package maintainer to write scripts
2645 which correctly create, update, maintain and
2646 remove-on-purge the file. These scripts must be idempotent
2647 (i.e., must work correctly if <prgn>dpkg</prgn> needs to
2648 re-run them due to errors during installation or removal),
2649 must cope with all the variety of ways <prgn>dpkg</prgn>
2650 can call maintainer scripts, must not overwrite or
2651 otherwise mangle the user's configuration without asking,
2652 must not ask unnecessary questions (particularly during
2653 upgrades), and otherwise be good citizens.</p>
2656 The scripts are not required to configure every possible option for
2657 the package, but only those necessary to get the package
2658 running on a given system. Ideally the sysadmin should not
2659 have to do any configuration other than that done
2660 (semi-)automatically by the <tt>postinst</tt> script.</p>
2663 A common practice is to create a script called
2664 <tt><var>package</var>-configure</tt> and have the
2665 package's <tt>postinst</tt> call it if and only if the
2666 configuration file does not already exist. In certain
2667 cases it is useful for there to be an example or template
2668 file which the maintainer scripts use. Such files should
2669 be in <tt>/usr/share/doc</tt> if they are examples or
2670 <tt>/usr/lib</tt> if they are templates, and should be
2671 perfectly ordinary <prgn>dpkg</prgn>-handled files
2672 (<em>not</em> <tt>conffiles</tt>).</p>
2675 These two styles of configuration file handling must
2676 not be mixed, for that way lies madness:
2677 <prgn>dpkg</prgn> will ask about overwriting the file
2678 every time the package is upgraded.</p>
2683 <heading>Sharing configuration files</heading>
2685 Packages that are not tagged as <em>conflicting</em> with
2686 each other must not specify the same file as
2687 <tt>conffile</tt>.</p>
2690 The maintainer scripts must not alter the conffile of
2691 <em>any</em> package, including the one the scripts belong
2695 If two or more packages use the same configuration file
2696 and it is reasonable for both to be installed at the same
2697 time, one of these packages must be defined as
2698 <em>owner</em> of the configuration file, i.e., it will be
2699 the package to list that distributes the file and lists it
2700 as a <tt>conffile</tt>. Other packages that use the
2701 configuration file must depend on the owning package if
2702 they require the configuration file to operate. If the
2703 other package will use the configuration file if present,
2704 but is capable of operating without it, no dependency need
2708 If it is desirable for two or more related packages to
2709 share a configuration file <em>and</em> for all of the
2710 related packages to be able to modify that configuration
2711 file, then the following should be done:
2715 have one of the related packages (the "core"
2716 package) manage the configuration file with
2717 maintainer scripts as described in the previous
2721 the core package should also provide a program that
2722 the other packages may use to modify the
2723 configuration file.</p>
2727 the related packages must use the provided program
2728 to make any modifications to the configuration file.
2729 They should either depend on the core package to
2730 guarantee that the configuration modifier program is
2731 available or accept gracefully that they cannot
2732 modify the configuration file if it is not.</p>
2737 Sometimes it's appropriate to create a new package which
2738 provides the basic infrastructure for the other packages
2739 and which manages the shared configuration files. (Check
2740 out the <tt>sgml-base</tt> package as an example.)</p>
2744 <heading>User configuration files ("dotfiles")</heading>
2747 Files in <tt>/etc/skel</tt> will automatically be copied
2748 into new user accounts by <prgn>adduser</prgn>. They
2749 should not be referenced there by any program.</p>
2752 Therefore, if a program needs a dotfile to exist in
2753 advance in <tt>$HOME</tt> to work sensibly, that dotfile
2754 should be installed in <tt>/etc/skel</tt> (and listed in
2755 conffiles, if it is not generated and modified dynamically
2756 by the package's installation scripts).</p>
2759 However, programs that require dotfiles in order to
2760 operate sensibly (dotfiles that they do not create
2761 themselves automatically, that is) are a bad thing, and
2762 programs should be configured by the Debian default
2763 installation as close to normal as possible.</p>
2766 Therefore, if a program in a Debian package needs to be
2767 configured in some way in order to operate sensibly that
2768 configuration should be done in a site-wide global
2769 configuration file elsewhere in <tt>/etc</tt>. Only if the
2770 program doesn't support a site-wide default configuration
2771 and the package maintainer doesn't have time to add it
2772 may a default per-user file be placed in
2773 <tt>/etc/skel</tt>.</p>
2776 <tt>/etc/skel</tt> should be as empty as we can make it.
2777 This is particularly true because there is no easy
2778 mechanism for ensuring that the appropriate dotfiles are
2779 copied into the accounts of existing users when a package
2785 <heading>Log files</heading>
2787 The traditional approach to log files has been to set up ad
2788 hoc log rotation schemes using simple shell scripts and
2789 cron. While this approach is highly customizable, it
2790 requires quite a lot of sysadmin work. Even though the
2791 original Debian system helped a little by automatically
2792 installing a system which can be used as a template, this
2793 was deemed not enough.
2797 A better scheme is to use logrotate, a GPL'd program
2798 developed by Red Hat, which centralizes log management. It
2799 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2800 and a directory where packages can drop logrotation info
2801 (<tt>/etc/logrotate.d</tt>).
2805 Log files should usually be named
2806 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2807 log files, or need a separate directory for permissions
2808 reasons (<tt>/var/log</tt> is writable only by
2809 <tt>root</tt>), you should usually create a directory named
2810 <tt>/var/log/<var>package</var></tt>.</p>
2813 Log files must be rotated occasionally so
2814 that they don't grow indefinitely; the best way to do this
2815 is to drop a script into the directory
2816 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2817 logrotate. Here is a good example for a logrotate config
2818 file (for more information see <manref name="logrotate"
2826 /etc/init.d/foo force-reload
2830 Which rotates all files under `/var/log/foo', saves 12
2831 compressed generations, and sends a HUP signal at the end of
2837 Log files should be removed when the package is
2838 purged (but not when it is only removed), by checking the
2839 argument to the <tt>postrm</tt> script (see the <em>Debian
2840 Packaging Manual</em> for details).</p>
2845 <heading>Permissions and owners</heading>
2848 The rules in this section are guidelines for general use.
2849 If necessary you may deviate from the details below.
2850 However, if you do so you must make sure that what is done
2851 is secure and you should try to be as consistent as possible
2852 with the rest of the system. You should probably also
2853 discuss it on <prgn>debian-devel</prgn> first.</p>
2856 Files should be owned by <tt>root.root</tt>, and made
2857 writable only by the owner and universally readable (and
2858 executable, if appropriate).</p>
2861 Directories should be mode 755 or (for group-writability)
2862 mode 2775. The ownership of the directory should be
2863 consistent with its mode--if a directory is mode 2775, it
2864 should be owned by the group that needs write access to
2868 Setuid and setgid executables should be mode 4755 or 2755
2869 respectively, and owned by the appropriate user or group.
2870 They should not be made unreadable (modes like 4711 or
2871 2711 or even 4111); doing so achieves no extra security,
2872 because anyone can find the binary in the freely available
2873 Debian package--it is merely inconvenient. For the same
2874 reason you should not restrict read or execute permissions
2875 on non-set-id executables.</p>
2878 Some setuid programs need to be restricted to particular
2879 sets of users, using file permissions. In this case they
2880 should be owned by the uid to which they are set-id, and
2881 by the group which should be allowed to execute them.
2882 They should have mode 4754; there is no point in making
2883 them unreadable to those users who must not be allowed to
2887 You must not arrange that the system administrator can only
2888 reconfigure the package to correspond to their local
2889 security policy by changing the permissions on a binary.
2890 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2891 to conffiles and other similar objects) have their
2892 permissions reset to the distributed permissions when the
2893 package is reinstalled. Instead you should consider (for
2894 example) creating a group for people allowed to use the
2895 program(s) and making any setuid executables executable
2896 only by that group.</p>
2899 If you need to create a new user or group for your package
2900 there are two possibilities. Firstly, you may need to
2901 make some files in the binary package be owned by this
2902 user or group, or you may need to compile the user or
2903 group id (rather than just the name) into the binary
2904 (though this latter should be avoided if possible, as in
2905 this case you need a statically allocated id).</p>
2908 If you need a statically allocated id, you must ask for a
2909 user or group id from the base system
2910 maintainer, and must not release the package until you
2911 have been allocated one. Once you have been allocated one
2912 you must make the package depend on a version of the base
2913 system with the id present in <tt>/etc/passwd</tt> or
2914 <tt>/etc/group</tt>, or alternatively arrange for your
2915 package to create the user or group itself with the
2916 correct id (using <tt>adduser</tt>) in its pre- or
2917 post-installation script (the latter is to be preferred if
2918 it is possible).</p>
2921 On the other hand, the program might be able to determine the
2922 uid or gid from the group name at runtime, so that a
2923 dynamic id can be used. In this case you should choose an
2924 appropriate user or group name, discussing this on
2925 <prgn>debian-devel</prgn> and checking with the base
2926 system maintainer that it is unique and that they do not
2927 wish you to use a statically allocated id instead. When
2928 this has been checked you must arrange for your package to
2929 create the user or group if necessary using
2930 <prgn>adduser</prgn> in the pre- or post-installation
2931 script (again, the latter is to be preferred if it is
2935 Note that changing the numeric value of an id associated with a name
2936 is very difficult, and involves searching the file system for all
2937 appropriate files. You need to think carefully whether a static or
2938 dynamic id is required, since changing your mind later will cause
2944 <heading>Customized programs</heading>
2946 <sect id="arch-spec">
2947 <heading>Architecture specification strings</heading>
2950 If a program needs to specify an <em>architecture specification
2951 string</em> in some place, the following format should be used:
2953 <arch>-<os>
2955 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2956 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2957 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2958 operating system.</p>
2960 Note, that we don't want to use `<arch>-debian-linux'
2961 to apply to the rule `architecture-vendor-os' since this
2962 would make our programs incompatible to other Linux
2963 distributions. Also note, that we don't use
2964 `<arch>-unknown-linux', since the `unknown' does not
2965 look very good.</p></sect>
2969 <heading>Daemons</heading>
2972 The configuration files <tt>/etc/services</tt>,
2973 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2974 by the <prgn>netbase</prgn> package and may not be modified
2975 by other packages.</p>
2978 If a package requires a new entry in one of these files, the
2979 maintainer should get in contact with the
2980 <prgn>netbase</prgn> maintainer, who will add the entries
2981 and release a new version of the <prgn>netbase</prgn>
2985 The configuration file <tt>/etc/inetd.conf</tt> must not be
2986 modified by the package's scripts except via the
2987 <prgn>update-inetd</prgn> script or the
2988 <prgn>DebianNet.pm</prgn> Perl module.</p>
2991 If a package wants to install an example entry into
2992 <tt>/etc/inetd.conf</tt>, the entry must be preceded with
2993 exactly one hash character (<tt>#</tt>). Such lines are
2994 treated as `commented out by user' by the
2995 <prgn>update-inetd</prgn> script and are not changed or
2996 activated during a package updates.</p></sect>
3000 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
3003 Some programs need to create pseudo-ttys. This should be done
3004 using Unix98 ptys if the C library supports it. The resulting
3005 program must not be installed setuid root, unless that
3006 is required for other functionality.
3010 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
3011 <tt>/var/log/lastlog</tt> must be installed writeable by
3012 group utmp. Programs who need to modify those files must
3013 be installed setgid utmp.
3018 <heading>Editors and pagers</heading>
3021 Some programs have the ability to launch an editor or pager
3022 program to edit or display a text document. Since there are
3023 lots of different editors and pagers available in the Debian
3024 distribution, the system administrator and each user should
3025 have the possibility to choose his/her preferred editor and
3029 In addition, every program should choose a good default
3030 editor/pager if none is selected by the user or system
3034 Thus, every program that launches an editor or pager must
3035 use the EDITOR or PAGER environment variables to determine
3036 the editor/pager the user wants to get started. If these
3037 variables are not set, the programs <tt>/usr/bin/editor</tt>
3038 and <tt>/usr/bin/pager</tt> should be used, respectively.</p>
3041 These two files are managed through `alternatives.' That is,
3042 every package providing an editor or pager must call the
3043 <prgn>update-alternatives</prgn> script to register these
3047 If it is very hard to adapt a program to make us of the
3048 EDITOR and PAGER variables, that program may be configured
3049 to use <tt>/usr/bin/sensible-editor</tt> and
3050 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
3051 respectively. These are two scripts provided in the Debian
3052 base system that check the EDITOR and PAGER variables and
3053 launch the appropriate program or fall back to
3054 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
3058 A program may also use the VISUAL environment variable to
3059 determine the user's choice of editor. If it exists, it
3060 should take precedence over EDITOR. This is in fact what
3061 <tt>/usr/bin/sensible-editor</tt> does.</p>
3064 Since the Debian base system already provides an editor and
3065 a pager program, it is not required for a package to depend on
3066 `editor' and `pager', nor is it required for a package to
3067 provide such virtual packages.</p></sect>
3070 <sect id="web-appl">
3071 <heading>Web servers and applications</heading>
3074 This section describes the locations and URLs that should
3075 be used by all web servers and web application in the Debian
3081 <p>Cgi-bin executable files are installed in the
3084 /usr/lib/cgi-bin/<cgi-bin-name>
3086 and should be referred to as
3088 http://localhost/cgi-bin/<cgi-bin-name>
3089 </example></p></item>
3092 <item><p>Access to html documents</p>
3095 Html documents for a package are stored in
3096 <tt>/usr/share/doc/<var>package</var></tt> but should
3097 be accessed via symlinks as
3098 <tt>/usr/doc/<var>package</var></tt><footnote> for
3099 backward compatibility, see <ref id="usrdoc"></footnote>
3100 and can be referred to as
3102 http://localhost/doc/<package>/<filename>
3103 </example></p></item>
3106 <item><p>Web Document Root</p>
3109 Web Applications should try to avoid storing files in
3110 the Web Document Root. Instead they should use the
3111 /usr/share/doc/<package> directory for documents and
3112 register the Web Application via the menu package. If
3113 access to the web-root is unavoidable then use
3117 as the Document Root. This might be just a
3118 symbolic link to the location where the sysadmin has
3119 put the real document root.</p>
3122 </enumlist></p></sect>
3126 <heading>Mail transport agents</heading>
3129 Debian packages which process electronic mail, whether
3130 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
3131 must make sure that they are compatible with the
3132 configuration decisions below. Failure to do this may
3133 result in lost mail, broken <tt>From:</tt> lines, and other
3134 serious brain damage!</p>
3137 The mail spool is <tt>/var/spool/mail</tt> and the interface
3138 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3139 per the FHS). The mail spool is part of the base system
3140 and not part of the MTA package.</p>
3143 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3144 programs (like IMAP daemons) must lock the mailbox in an
3145 NFS-safe way. This means that <tt>fcntl()</tt> locking must
3146 to be combined with dot locking. To avoid dead locks, a
3147 program should use <tt>fcntl()</tt> first and dot locking
3148 after this or alternatively implement the two locking
3149 methods in a non blocking way<footnote>
3151 If it is not possible to establish both locks, the
3152 system shouldn't wait for the second lock to be
3153 established, but remove the first lock, wait a (random)
3154 time, and start over locking again.</p>
3155 </footnote>. Using the functions <tt>maillock</tt> and
3156 <tt>mailunlock</tt> provided by the
3157 <tt>liblockfile*</tt><footnote>
3159 <tt>liblockfile</tt> version >>1.01</p>
3160 </footnote> packages is the recommended way to realize this.
3164 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3165 unless the user has chosen otherwise. A MUA may remove a
3166 mailbox (unless it has nonstandard permissions) in which
3167 case the MTA or another MUA must recreate it if needed.
3168 Mailboxes must be writable by group mail.</p>
3171 The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
3172 be setgid mail to do the locking mentioned above (and
3173 must obviously avoid accessing other users' mailboxes
3174 using this privilege).</p>
3177 <tt>/etc/aliases</tt> is the source file for the system mail
3178 aliases (e.g., postmaster, usenet, etc.)--it is the one
3179 which the sysadmin and <tt>postinst</tt> scripts may edit.
3180 After <tt>/etc/aliases</tt> is edited the program or human
3181 editing it must call <prgn>newaliases</prgn>. All MTA
3182 packages must come with a <prgn>newaliases</prgn> program,
3183 even if it does nothing, but older MTA packages do not do
3184 this so programs should not fail if <prgn>newaliases</prgn>
3185 cannot be found.</p>
3188 The convention of writing <tt>forward to
3189 <var>address</var></tt> in the mailbox itself is not
3190 supported. Use a <tt>.forward</tt> file instead.</p>
3193 The <prgn>rmail</prgn> program used by UUCP
3194 for incoming mail should be <tt>/usr/sbin/rmail</tt>, as per the
3195 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3196 batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
3200 If you need to know what name to use (for example) on
3201 outgoing news and mail messages which are generated locally,
3202 you should use the file <tt>/etc/mailname</tt>. It will
3203 contain the portion after the username and <tt>@</tt> (at)
3204 sign for email addresses of users on the machine (followed
3208 A package should check for the existence of this file. If
3209 it exists it should use it without comment. (An MTA's
3210 prompting configuration script may wish to prompt the user
3211 even if it finds this file exists.) If it does not exist it
3212 should prompt the user for the value and store it in
3213 <tt>/etc/mailname</tt> as well as using it in the package's
3214 configuration. The prompt should make it clear that the
3215 name will not just be used by that package. For example, in
3216 this situation the INN package says:
3218 Please enter the `mail name' of your system. This is the
3219 hostname portion of the address to be shown on outgoing
3220 news and mail messages. The default is
3221 <var>syshostname</var>, your system's host name. Mail
3222 name [`<var>syshostname</var>']:
3224 where <var>syshostname</var> is the output of <tt>hostname
3225 --fqdn</tt>.</p></sect>
3229 <heading>News system configuration</heading>
3232 All the configuration files related to the NNTP (news)
3233 servers and clients should be located under
3234 <tt>/etc/news</tt>.</p>
3237 There are some configuration issues that apply to a number
3238 of news clients and server packages on the machine. These
3242 <tag>/etc/news/organization</tag>
3243 <item><p>A string which should appear as the
3244 organization header for all messages posted
3245 by NNTP clients on the machine</p></item>
3247 <tag>/etc/news/server</tag>
3248 <item><p>Contains the FQDN of the upstream NNTP
3249 server, or localhost if the local machine is
3250 an NNTP server.</p></item>
3253 Other global files may be added as required for cross-package news
3254 configuration.</p></sect>
3258 <heading>Programs for the X Window System</heading>
3261 <em>Programs that may be configured with support for the X Window
3262 System</em> must be configured to do so and must declare any
3263 package dependencies necessary to satisfy their runtime
3264 requirements when using the X Window System, unless the package
3265 in question is of standard or higher priority, in which case
3266 X-specific binaries may be split into a separate package, or
3267 alternative versions of the package with X support may be
3270 <strong>NOTE</strong> The forthcoming major X Window
3271 System release shall probably change this
3275 This seems to be more what people want. It will enable
3276 packages like vim-tty to become legal if they are
3277 promoted to standard priority. Also, that X client in
3278 mtools can be split into its own package and made
3282 This paves the way for xlib6g and xfree86-common to be
3283 moved from standard to optional, <strong>if</strong> all
3284 Xlib dependent packages are moved from standard to
3285 optional priority (or if non-Xlib-linked versions are
3286 retained in standard). That, however is up to the
3287 affected package maintainers and the archive
3288 maintainers, and is not mandated by this policy.
3295 <em>Packages which provide an X server</em> that, directly or
3296 indirectly, communicates with real input and display hardware
3297 should declare in their control data that they provide the
3298 virtual package <tt>xserver</tt>.
3301 Rationale: implement current practice, and provide an
3302 actual policy for usage of the "xserver" virtual package
3303 which appears in the virtual packages list.
3304 In a nutshell, X servers that interface directly with
3305 the display and input hardware or via another subsystem
3306 (e.g., GGI) should provide xserver. Things like Xvfb,
3307 Xnest, and Xprt should not. <strong>NOTE</strong> The
3308 forthcoming major X Window System release shall probably
3309 change this drastically.
3315 <em>Packages that provide a terminal emulator</em> for the X
3316 Window System which support a terminal type with a terminfo
3317 description provided in the <tt>ncurses-base</tt> package
3318 should declare in their control data that they provide the
3319 virtual package <tt>x-terminal-emulator</tt>. They should
3320 also register themselves as an alternative for
3321 <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
3326 <em>Packages that provide window managers</em> should declare in
3327 their control data that they provide the virtual package
3328 <tt>x-window-manager</tt>. They should also register themselves as an
3329 alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
3330 calculated as follows:
3332 <item>Start with a priority of 20.</item>
3333 <item>If the window manager supports the Debian menu system,
3334 add 20 points if this support is available in the
3335 package's default configuration (i.e., no
3336 configuration files belonging to the system or user
3337 have to be edited to activate the feature); if
3338 configuration files must be modified, add only 10
3340 <item>If the window manager permits the X session to be
3341 restarted using a <em>different</em> window manager
3342 (without killing the X server) in its default
3343 configuration, add 10 points; otherwise add
3349 <em>Packages that provide fonts for the X Window System</em>
3350 must do a number of things to ensure that they are both
3351 available without modification of the X or font server
3352 configuration, and that they do not corrupt files used by
3353 other font packages to register information about themselves.
3356 Fonts of any type supported by the X Window System
3357 should be be in a separate binary package from any
3358 executables, libraries, or documentation (except that
3359 specific to the fonts shipped); if a program or
3360 library is <em>unusable</em> without one or more
3361 specific fonts, the package containing the program or
3362 library should declare a dependency on the package(s)
3363 containing the font(s) it requires.
3366 BDF fonts should be converted to PCF fonts with the
3367 <tt>bdftopcf</tt> utility (available in the
3368 <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
3369 placed in a directory that corresponds to their
3373 100 dpi fonts should be placed in
3374 <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
3377 75 dpi fonts should be placed in
3378 <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
3381 Character-cell fonts, cursor fonts, and other
3382 low-resolution fonts should be placed in
3383 <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
3388 Speedo fonts should be placed in
3389 <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
3392 Type 1 fonts should be placed in
3393 <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
3394 metric files are available, they may be placed here as
3398 Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
3399 other than those listed above should be neither created nor
3400 used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
3401 excepted for historical reasons, but installation of files into
3402 these directories remains discouraged.)
3405 Font packages may, instead of placing files directly in
3406 the X font directories listed above, provide symbolic links in
3407 the font directory which point to the files' actual location
3408 in the filesystem. Such a location should comply with the
3412 Font packages should not contain both 75dpi and 100dpi
3413 versions of a font. If both are available, they should be
3414 provided in separate binary packages with "-75dpi" or "-100dpi"
3415 appended to the names of the packages containing the
3416 corresponding fonts.
3419 Fonts destined for the <tt>misc</tt> subdirectory should
3420 not be included in the same package as 75dpi or 100dpi fonts;
3421 instead, they should be provided in a separate package with
3422 "-misc" appended to its name.
3425 Font packages <em>must not</em> provide the files
3426 <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
3427 <tt>fonts.scale</tt> in a font directory.
3430 <tt>fonts.dir</tt> files must not be provided at
3434 <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
3435 files, if needed, should be provided in the
3437 <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
3438 where <em>fontdir</em> is the name of the
3440 <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
3441 package's corresponding fonts are stored (e.g.,
3442 <tt>75dpi</tt> or <tt>misc</tt>),
3443 <em>package</em> is the name of the package that
3444 provides these fonts, and <em>extension</em> is
3445 either <tt>scale</tt> or <tt>alias</tt>,
3446 whichever corresponds to the file
3452 Font packages must declare a dependency on
3453 <tt>xbase-clients</tt> and, in the package
3454 post-installation and post-removal scripts, invoke the
3455 <tt>mkfontdir</tt> command on each directory into
3456 which they installed fonts.
3459 Font packages that provide one or more
3460 <tt>fonts.scale</tt> files as described above must declare a
3461 versioned dependency on <tt>xbase-clients (>=
3462 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
3463 directory into which they installed fonts
3464 <em>before</em> invoking <tt>mkfontdir</tt> on that
3465 directory. This invocation must occur in both the
3466 post-installation and post-removal scripts.
3469 Font packages that provide one or more
3470 <tt>fonts.alias</tt> files as described above must
3471 declare a versioned dependency on <tt>xbase-clients
3472 (>= 3.3.3.1-5)</tt> and, in the package
3473 post-installation and post-removal scripts, invoke
3474 <tt>update-fonts-alias</tt> on each directory into
3475 which they installed fonts.
3478 Font packages must not provide alias names for the
3479 fonts they include which collide with alias names already in
3480 use by fonts already packaged.
3483 Font packages must not provide fonts with the same XLFD
3484 registry name as another font already packaged.
3490 <em>Application defaults</em> files must be installed in the
3491 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
3493 <p>Note: This shall change very shortly.</p>
3495 They should not be registered as <em>conffile</em>s or
3496 otherwise treated as configuration files. Customization of
3497 programs' X resources may be supported with the provision of
3498 a file with the same name as that of the package placed in
3499 the <tt>/etc/X11/Xresources/</tt> directory, which must
3500 registered as a <em>conffile</em>. <em>Important:</em>
3501 packages that install files into the
3502 <tt>/etc/X11/Xresources/</tt> directory <em>must</em>
3503 declare a conflict with <tt>xbase (<<
3504 3.3.2.3a-2)</tt>; if this is not done it is possible for the
3505 installing package to destroy a previously-existing
3506 <tt>/etc/X11/Xresources</tt> <em>file</em> which had been
3507 customized by the system administrator.
3509 <p>Rationale: clarifies the language to properly
3510 address the package maintainer, not the system
3511 administrator, as to how to manage
3512 /etc/X11/Xresources.</p>
3518 <em>Packages using the X Window System should abide by the FHS
3519 standard whenever possible</em>; they should install binaries,
3520 libraries, manual pages, and other files in FHS-mandated
3521 locations wherever possible. This means that files must
3522 not be installed into <tt>/usr/X11R6/bin/</tt>,
3523 <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
3524 this is necessary for the package to operate properly.
3525 Configuration files for window managers and display managers
3526 should be placed in a subdirectory of <tt>/etc/X11/</tt>
3527 corresponding to the package name due to these programs'
3528 tight integration with the mechanisms of the X Window
3529 System. Application-level programs should use the
3530 <tt>/etc/</tt> directory unless otherwise mandated by
3531 policy. The installation of files into subdirectories of
3532 <tt>/usr/X11R6/include/X11/</tt> and
3533 <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
3534 package maintainers should determine if subdirectories of
3535 <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
3536 instead (symlinks from the X11R6 directories to
3537 FHS-compliant locations is encouraged if the program is not
3538 easily configured to look elsewhere for its files).
3539 Packages must not provide -- or install files into -- the
3540 directories <tt>/usr/bin/X11/</tt>,
3541 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
3542 Files within a package should, however, make reference to
3543 these directories, rather than their X11R6-named
3544 counterparts <tt>/usr/X11R6/bin/</tt>,
3545 <tt>/usr/X11R6/include/X11/</tt>, and
3546 <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
3547 referred to have not been moved to FHS-compliant locations.
3551 <em>Programs that require the non-DFSG-compliant OSF/Motif
3552 library</em> should be compiled against and tested with
3553 LessTif (a free re-implementation of Motif) instead. If the
3554 maintainer judges that the program or programs do not work
3555 sufficiently well with LessTif to be distributed and
3556 supported, but do so when compiled against Motif, then two
3557 versions of the package should be created; one linked
3558 statically against Motif and with <tt>-smotif</tt> appended
3559 to the package name, and one linked dynamically against
3560 Motif and with <tt>-dmotif</tt> appended to the package
3561 name. Both Motif-linked versions are dependent upon
3562 non-DFSG-compliant software and thus cannot be uploaded to
3563 the main distribution; if the software is itself
3564 DFSG-compliant it may be uploaded to the contrib
3565 distribution. While known existing versions of OSF/Motif
3566 permit unlimited redistribution of binaries linked against
3567 the library (whether statically or dynamically), it is the
3568 package maintainer's responsibility to determine whether
3569 this is permitted by the license of the copy of OSF/Motif in
3570 his or her possession.
3576 <heading>Emacs lisp programs</heading>
3579 Please refer to the `Debian Emacs Policy' (documented in
3580 <tt>debian-emacs-policy.gz</tt> of the
3581 <prgn>emacsen-common</prgn> package) for details of how to
3582 package emacs lisp programs.</p></sect>
3586 <heading>Games</heading>
3589 The permissions on /var/games are 755
3590 <tt>root.root</tt>.</p>
3593 Each game decides on its own security policy.</p>
3596 Games which require protected, privileged access to
3597 high-score files, savegames, etc., may be made
3598 set-<em>group</em>-id (mode 2755) and owned by
3599 <tt>root.games</tt>, and use files and directories with
3600 appropriate permissions (770 <tt>root.games</tt>, for
3601 example). They must not be made
3602 set-<em>user</em>-id, as this causes security problems. (If
3603 an attacker can subvert any set-user-id game they can
3604 overwrite the executable of any other, causing other players
3605 of these games to run a Trojan horse program. With a
3606 set-group-id game the attacker only gets access to less
3607 important game data, and if they can get at the other
3608 players' accounts at all it will take considerably more
3612 Some packages, for example some fortune cookie programs, are
3613 configured by the upstream authors to install with their
3614 data files or other static information made unreadable so
3615 that they can only be accessed through set-id programs
3616 provided. You should not do this in a Debian package: anyone can
3617 download the <tt>.deb</tt> file and read the data from it,
3618 so there is no point making the files unreadable. Not
3619 making the files unreadable also means that you don't have
3620 to make so many programs set-id, which reduces the risk of a
3624 As described in the FHS, binaries of games should be
3625 installed in the directory <tt>/usr/games</tt>. This also
3626 applies to games that use the X Window System. Manual pages
3627 for games (X and non-X games) should be installed in
3628 <tt>/usr/share/man/man6</tt>.</p>
3632 <chapt><heading>Documentation</heading>
3636 <heading>Manual pages</heading>
3639 You should install manual pages in <prgn>nroff</prgn> source
3640 form, in appropriate places under <tt>/usr/share/man</tt>. You
3641 should only use sections 1 to 9 (see the FHS for more
3642 details). You must not install a preformatted `cat
3646 Each program, utiltiy, and function should have an
3647 associated manpage included in the same package. It is
3648 suggested that all configuration files also have a manual
3649 page included as well.
3653 If no manual page is available for a particular program,
3654 utility, function or configuration file and this is reported as a bug on
3655 debian-bugs, a symbolic link from the requested manual page
3656 to the <manref name="undocumented" section="7"> manual page
3657 may be provided. This symbolic link can be created from
3658 <tt>debian/rules</tt> like this:
3660 ln -s ../man7/undocumented.7.gz \
3661 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3663 This manpage claims that the lack of a manpage has been
3664 reported as a bug, so you may only do this if it really has
3665 (you can report it yourself, if you like). Do not close the
3666 bug report until a proper manpage is available.</p>
3669 You may forward a complaint about a missing manpage to the
3670 upstream authors, and mark the bug as forwarded in the
3671 Debian bug tracking system. Even though the GNU Project do
3672 not in general consider the lack of a manpage to be a bug,
3673 we do--if they tell you that they don't consider it a bug
3674 you should leave the bug in our bug tracking system open
3678 Manual pages should be installed compressed using <tt>gzip
3682 If one manpage needs to be accessible via several names it
3683 is better to use a symbolic link than the <tt>.so</tt>
3684 feature, but there is no need to fiddle with the relevant
3685 parts of the upstream source to change from <tt>.so</tt> to
3686 symlinks--don't do it unless it's easy. You should not create hard
3687 links in the manual page directories, nor put
3688 absolute filenames in <tt>.so</tt> directives. The filename
3689 in a <tt>.so</tt> in a manpage should be relative to the
3690 base of the manpage tree (usually
3691 <tt>/usr/share/man</tt>).</p></sect>
3695 <heading>Info documents</heading>
3698 Info documents should be installed in <tt>/usr/share/info</tt>.
3699 They should be compressed with <tt>gzip -9</tt>.</p>
3702 Your package should call <prgn>install-info</prgn> to update the Info
3704 file, in its post-installation script:
3706 install-info --quiet --section Development Development \
3707 /usr/share/info/foobar.info
3711 It is a good idea to specify a section for the location of
3712 your program; this is done with the <tt>--section</tt>
3713 switch. To determine which section to use, you should look
3714 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3715 relevant (or create a new section if none of the current
3716 sections are relevant). Note that the <tt>--section</tt>
3717 flag takes two arguments; the first is a regular expression
3718 to match (case-insensitively) against an existing section,
3719 the second is used when creating a new one.</p>
3722 You should remove the entries in the pre-removal script:
3724 install-info --quiet --remove /usr/share/info/foobar.info
3728 If <prgn>install-info</prgn> cannot find a description entry
3729 in the Info file you must supply one. See <manref
3730 name="install-info" section="8"> for details.</p>
3734 <heading>Additional documentation</heading>
3737 Any additional documentation that comes with the package may
3738 be installed at the discretion of the package maintainer.
3739 Text documentation should be installed in a directory
3740 <tt>/usr/share/doc/<var>package</var></tt>, where
3741 <var>package</var> is the name of the package, and
3742 compressed with <tt>gzip -9</tt> unless it is small.</p>
3745 If a package comes with large amounts of documentation which
3746 many users of the package will not require you should create
3747 a separate binary package to contain it, so that it does not
3748 take up disk space on the machines of users who do not need
3749 or want it installed.</p>
3752 It is often a good idea to put text information files
3753 (<tt>README</tt>s, changelogs, and so forth) that come with
3754 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3755 in the binary package. However, you don't need to install
3756 the instructions for building and installing the package, of
3761 <heading>Accessing the documentation</heading>
3764 Former Debian releases placed all additional documentation
3765 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3767 <tt>/usr/share/doc/<var>package</var></tt>, each package
3768 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3769 that points to the new location of its documentation in
3770 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3771 symlinks will be removed in the future, but they have to be
3772 there for compatibility reasons until all packages have
3773 moved and the policy is changed accordingly.</footnote>.
3774 The symlink must be created when the package is installed;
3775 it cannot be contained in the package itself due to problems
3776 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3777 this is to put the following in the package's
3778 <prgn>postinst</prgn>:
3780 if [ "$1" = "configure" ]; then
3781 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3782 -a -d /usr/share/doc/#PACKAGE# ]; then
3783 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3787 And the following in the package's <prgn>prerm</prgn>:
3789 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3790 -a -L /usr/doc/#PACKAGE# ]; then
3791 rm -f /usr/doc/#PACKAGE#
3798 <heading>Preferred documentation formats</heading>
3801 The unification of Debian documentation is being carried out
3805 If your package comes with extensive documentation in a
3806 mark up format that can be converted to various other formats
3807 you should if possible ship HTML versions in a binary
3808 package, in the directory
3809 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3812 <p>The rationale: The important thing here is that HTML
3813 docs should be available in <em>some</em> package, not
3814 necessarily in the main binary package, though. </p>
3819 Other formats such as PostScript may be provided at your
3823 <sect id="copyrightfile">
3824 <heading>Copyright information</heading>
3827 Every package must be accompanied by a verbatim copy of its
3828 copyright and distribution license in the file
3829 /usr/share/doc/<package-name>/copyright. This file must
3830 neither be compressed nor be a symbolic link.</p>
3833 In addition, the copyright file must say where the upstream
3834 sources (if any) were obtained, and should explain briefly what
3835 modifications were made in the Debian version of the package
3836 compared to the upstream one. It should name the original
3837 authors of the package and the Debian maintainer(s) who were
3838 involved with its creation.</p>
3841 /usr/share/doc/<package-name> may be a symbolic link to a
3842 directory in /usr/share/doc only if two packages both come from
3843 the same source and the first package has a "Depends"
3844 relationship on the second. These rules are important
3845 because copyrights must be extractable by mechanical
3849 Packages distributed under the UCB BSD license, the Artistic
3850 license, the GNU GPL, and the GNU LGPL should refer to the
3851 files /usr/share/common-licenses/BSD,
3852 /usr/share/common-licenses/Artistic,
3853 /usr/share/common-licenses/GPL, and
3854 /usr/share/common-licenses/LGPL.
3857 Why "licenses" and not "copyright"? Because
3858 <tt>/usr/doc/copyright</tt> used to contain all the
3859 copyright files, plus the four common licenses GPL,
3860 LGPL, Artistic and BSD. Now individual copyright files
3861 for packages are no longer in a common directory. Once
3862 <tt>/usr/doc/copyright</tt> is almost empty it makes
3863 sense to rename "copyright" to "licenses"
3866 Why "common-licenses" and not "licenses"? Because if I
3867 put just "licenses" I'm sure I will receive a bug report
3868 saying "license foo is not included in the licenses
3869 directory. They are not all the licenses, just a few
3870 common ones. I could use /usr/share/doc/common-licenses
3871 but I think this is too long, and, after all, the GPL
3872 does not "document" anything, it is merely a license.
3878 You should not use the copyright file as a general <tt>README</tt>
3879 file. If your package has such a file it should be
3880 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3881 <tt>README.Debian</tt> or some other appropriate place.</p>
3885 <heading>Examples</heading>
3888 Any examples (configurations, source files, whatever),
3889 should be installed in a directory
3890 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3891 files should not be referenced by any program--they're there
3892 for the benefit of the system administrator and users, as
3893 documentation only. Architecture-specific example files
3894 should be installed in a directory
3895 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3896 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3897 to files in it. Or the latter directory may be a symlink to
3901 <sect id="instchangelog">
3902 <heading>Changelog files</heading>
3905 Packages that are not Debian-native must contain a copy of
3906 <tt>debian/changelog</tt> file from the Debian source tree
3907 in <tt>/usr/share/doc/<var>package</var></tt> as
3908 <tt>changelog.Debian.gz</tt>. If an upstream changelog is
3909 available, it should be accessible as
3910 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> in
3911 plain text. If the upstream changelog is distributed in
3912 HTML, it should be made available in that form as
3913 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
3914 and the <tt>changelog.gz</tt> should be generated using, eg,
3915 <tt>lynx -dump -nolist</tt>. If the upstream changelog files
3916 do not already conform to this naming convention, then this
3917 may be achieved either by renaming the files, or adding a
3918 symbolic link, at the maintainer's discretion.
3921 Rationale: People should not have to look into two
3922 places for upstream changelogs merely because they are
3930 All these files should be installed compressed using <tt>gzip -9</tt>,
3931 as they will become large with time even if they start out
3936 If the package has only one changelog which is used both as
3937 the Debian changelog and the upstream one because there is
3938 no separate upstream maintainer then that changelog should
3939 usually be installed as
3940 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3941 there is a separate upstream maintainer, but no upstream
3942 changelog, then the Debian changelog should still be called
3943 <tt>changelog.Debian.gz</tt>.</p>