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 adminstrivia 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 This manual does <em>not</em> describe the technical
121 mechanisms involved in package creation, installation, and
122 removal. This information can be found in the <em>Debian
123 Packaging Manual</em> and the <em>Debian System
124 Administrators' Manual</em>. Please note that the
125 footnotes present in this manual are merely informative,
126 and are not part of Debian policy itself.
129 This document assumes familiarity with these other two
130 manuals. Unfortunately, the <em>System Administrators'
131 Manual</em> does not exist yet.
134 Much of the information presented in this manual will be
135 useful even when building a package which is to be
136 distributed in some other way or is for local use.
140 <heading>New versions of this document</heading>
142 The current version of this document is always accessible from the
143 Debian FTP server <ftpsite>ftp.debian.org</ftpsite> at
144 <ftppath>/debian/doc/package-developer/debian-policy.html.tar.gz</ftppath>
145 or from the Debian WWW server at
146 <url id="http://www.debian.org/doc/debian-policy/"
147 name="The Debian Policy Manual">.</p>
150 In addition, this manual is distributed via the Debian package
151 <tt>debian-policy</tt>.
155 <heading>Feedback</heading>
158 As the Debian GNU/Linux system is continuously evolving this
159 manual is changed from time to time.
162 While the authors of this document tried hard not to include
163 any typos or other errors these still occur. If you discover
164 an error in this manual or if you want to tell us any
165 comments, suggestions, or critics please send an email to
166 the Debian Policy List,
167 <email>debian-policy@lists.debian.org</email>, or submit a
168 bug report against the <tt>debian-policy</tt> package.
173 <heading>The Debian Archive</heading>
175 The Debian GNU/Linux system is maintained and distributed as a
176 collection of <em>packages</em>. Since there are so many of them (over
177 2600) they are split into <em>sections</em> and <em>priorities</em> to
178 simplify handling of them.
181 The effort of the Debian project is to build a free operating
182 system, but not every package we want to make accessible is
183 <em>free</em> in our sense (see Debian Free Software
184 Guidelines, below), or may be imported/exported without
185 restrictions. Thus, the archive is split into the sections
186 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
187 <em>contrib</em>.</p>
189 The <em>main</em> section forms the <em>Debian GNU/Linux
190 distribution</em>. </p>
192 Packages in the other sections are not considered as part of
193 the Debian distribution, though we support their use, and we
194 provide infrastructure for them (such as our bug-tracking
195 system and mailing lists). This Debian Policy Manual applies
196 to these packages as well.</p>
198 <sect id="pkgcopyright">
199 <heading>Package copyright and sections</heading>
201 The aims of this policy are:
203 <list compact="compact">
205 <p>We want to make as much software available as we
209 <p>We want to encourage everyone to write free software.</p>
212 <p> We want to make it easy for people to produce
213 CD-ROMs of our system without violating any licenses,
214 import/export restrictions, or any other laws.</p>
219 <heading>The Debian Free Software Guidelines</heading>
221 The Debian Free Software Guidelines (DFSG) is our
222 definition of `free' software.
224 <tag>Free Redistribution
228 The license of a Debian component may not restrict any
229 party from selling or giving away the software as a
230 component of an aggregate software distribution
231 containing programs from several different
232 sources. The license may not require a royalty or
233 other fee for such sale.
240 The program must include source code, and must allow
241 distribution in source code as well as compiled form.
248 The license must allow modifications and derived
249 works, and must allow them to be distributed under the
250 same terms as the license of the original software.
253 <tag>Integrity of The Author's Source Code
257 The license may restrict source-code from being
258 distributed in modified form <em>only</em> if the
259 license allows the distribution of ``patch files''
260 with the source code for the purpose of modifying the
261 program at build time. The license must explicitly
262 permit distribution of software built from modified
263 source code. The license may require derived works to
264 carry a different name or version number from the
265 original software. (This is a compromise. The Debian
266 group encourages all authors to not restrict any
267 files, source or binary, from being modified.)
270 <tag>No Discrimination Against Persons or Groups
274 The license must not discriminate against any person
278 <tag>No Discrimination Against Fields of Endeavor
282 The license must not restrict anyone from making use
283 of the program in a specific field of endeavor. For
284 example, it may not restrict the program from being
285 used in a business, or from being used for genetic
289 <tag>Distribution of License
293 The rights attached to the program must apply to all
294 to whom the program is redistributed without the need
295 for execution of an additional license by those
299 <tag>License Must Not Be Specific to Debian
303 The rights attached to the program must not depend on
304 the program's being part of a Debian system. If the
305 program is extracted from Debian and used or
306 distributed without Debian but otherwise within the
307 terms of the program's license, all parties to whom
308 the program is redistributed must have the same
309 rights as those that are granted in conjunction with
313 <tag>License Must Not Contaminate Other Software
317 The license must not place restrictions on other
318 software that is distributed along with the licensed
319 software. For example, the license must not insist
320 that all other programs distributed on the same medium
321 must be free software.
324 <tag>Example Licenses
328 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
329 examples of licenses that we consider <em>free</em>.
336 <heading>The main section</heading>
338 Every package in "main" must comply with the DFSG (Debian
339 Free Software Guidelines).</p>
342 In addition, the packages in "main"
343 <list compact="compact">
346 must not require a package outside of "main" for
347 compilation or execution (thus, the package may not
348 declare a "Depends" or "Recommends" relationship on a
354 must not be so buggy that we refuse to support them,
359 must meet all policy requirements presented in this
367 <heading>The contrib section</heading>
369 Every package in "contrib" must comply with the DFSG.
373 Examples of packages which would be included in "contrib" are
374 <list compact="compact">
377 free packages which require "contrib", "non-free", or
378 "non-US" packages or packages which are not in our
379 archive at all for compilation or execution,
384 wrapper packages or other sorts of free accessories for
392 <heading>The non-free section</heading>
394 `Non-free' contains packages which are not compliant with
395 the DFSG or which are encumbered by patents or other legal
396 issues that make their distribution problematic.</p>
398 All packages in `non-free' must be electronically
399 distributable across international borders.
403 <heading>The non-us server</heading>
405 Some programs with cryptographic program code must be stored
406 on the "non-us" server because of export restrictions of the
409 This applies only to packages which contain cryptographic
410 code. A package containing a program with an interface to a
411 cryptographic program or a program that's dynamically linked
412 against a cryptographic library can be distributed if it is
413 capable of running without the cryptography library or
418 <heading>Further copyright considerations</heading>
420 Every package must be accompanied by a verbatim copy of its
421 copyright and distribution license in the file
422 /usr/share/doc/<package-name>/copyright (see <ref
423 id="copyrightfile"> for details).</p>
425 We reserve the right to restrict files from being included
426 anywhere in our archives if
427 <list compact="compact">
430 their use or distribution would break a law,
435 there is an ethical conflict in their distribution or
441 we would have to sign a license for them, or
446 their distribution would conflict with other project
454 Programs whose authors encourage the user to make donations
455 are fine for the main distribution, provided that the
456 authors do not claim that not donating is immoral,
457 unethical, illegal or something similar; otherwise they must
458 go in contrib (or non-free, if even distribution is
459 restricted by such statements).</p>
462 Packages whose copyright permission notices (or patent
463 problems) do not allow redistribution even of only binaries,
464 and where no special permission has been obtained, cannot be
465 placed on the Debian FTP site and its mirrors at all.</p>
468 Note, that under international copyright law (this applies
469 in the United States, too) <em>no</em> distribution or
470 modification of a work is allowed without an explicit notice
471 saying so. Therefore a program without a copyright notice
472 <em>is</em> copyrighted and you may not do anything to it
473 without risking being sued! Likewise if a program has a
474 copyright notice but no statement saying what is permitted
475 then nothing is permitted.</p>
478 Many authors are unaware of the problems that restrictive
479 copyrights (or lack of copyright notices) can cause for the
480 users of their supposedly-free software. It is often
481 worthwhile contacting such authors diplomatically to ask
482 them to modify their license terms. However, this is a
483 politically difficult thing to do and you should ask for
484 advice on <tt>debian-devel</tt> first.</p>
487 When in doubt, send mail to
488 <email>debian-devel@lists.debian.org</email>. Be prepared
489 to provide us with the copyright statement. Software
490 covered by the GPL, public domain software and BSD-like
491 copyrights are safe; be wary of the phrases `commercial use
492 prohibited' and `distribution restricted'.</p>
495 <heading>Subsections</heading>
498 The packages in all the sections (<em>main</em>,
499 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
500 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
501 grouped further into <em>subsections</em> to simplify
505 The section for each package is specified in the package's
506 <em>control record</em>. However, the maintainer of the
507 Debian archive may override this selection to assure the
508 consistency of the Debian distribution. </p>
511 Please check the current Debian distribution to see which
512 sections are available.</p>
515 <heading>Priorities</heading>
518 Each package is given a certain <em>priority</em> value,
519 which is included in the package's <em>control
520 record</em>. This information is used in the Debian package
521 management tool to separate high-priority packages from
522 less-important packages.</p>
525 The following <em>priority levels</em> are supported by the
526 Debian package management system, <prgn>dpkg</prgn>.
528 <tag><tt>required</tt></tag>
531 <tt>required</tt> packages are necessary for the
532 proper functioning of the system. You must not remove
533 these packages or your system may become totally
534 broken and you may not even be able to use
535 <prgn>dpkg</prgn> to put things back. Systems with
536 only the <tt>required</tt> packages are probably
537 unusable, but they do have enough functionality to
538 allow the sysadmin to boot and install more
541 <tag><tt>important</tt></tag>
544 Important programs, including those which one would
545 expect to find on any Unix-like system. If the
546 expectation is that an experienced Unix person who
547 found it missing would say `What the F*!@<+ is
548 going on, where is <prgn>foo</prgn>', it must be in
549 <tt>important</tt>. This is an important criterion
550 because we are trying to produce, amongst other
551 things, a free Unix. Other packages without which the
552 system will not run well or be usable must also be
553 here. This does <em>not</em> include Emacs, the X
554 Window System, TeX or any other large applications.
555 The <tt>important</tt> packages are just a bare
556 minimum of commonly-expected and necessary tools.</p>
558 <tag><tt>standard</tt></tag>
561 These packages provide a reasonably small but not too
562 limited character-mode system. This is what will
563 install by default if the user doesn't select anything
564 else. It doesn't include many large applications, but
565 it does include Emacs (this is more of a piece of
566 infrastructure than an application) and a reasonable
567 subset of TeX and LaTeX (if this is possible without
570 <tag><tt>optional</tt></tag>
573 (In a sense everything is optional that isn't
574 required, but that's not what is meant here.) This is
575 all the software that you might reasonably want to
576 install if you didn't know what it was or don't have
577 specialized requirements. This is a much larger system
578 and includes the X Window System, a full TeX
579 distribution, and many applications.</p>
581 <tag><tt>extra</tt></tag>
584 This contains all packages that conflict with others
585 with required, important, standard or optional
586 priorities, or are only likely to be useful if you
587 already know what they are or have specialised
594 Packages may not depend on packages with lower priority
595 values (excluding build-time dependencies). In order to
596 ensure this, the priorities of one or more packages may have
602 <heading>Binary packages</heading>
605 The Debian GNU/Linux distribution is based on the Debian
606 package management system, called <prgn>dpkg</prgn>. Thus,
607 all packages in the Debian distribution have to be provided
608 in the <tt>.deb</tt> file format.</p>
612 <heading>The package name</heading>
615 Every package must have a name that's unique within the Debian
619 Package names may only consist of lower case letters, digits (0-9),
620 plus (+) or minus (-) signs, and periods (.).</p>
623 The package name is part of the file name of the
624 <tt>.deb</tt> file and is included in the control field
630 <heading>The maintainer of a package</heading>
633 Every package must have exactly one maintainer at a
634 time. This person is responsible that the license of the
635 package's software complies with the policy of the
636 distribution this package is included in.</p>
639 The maintainer must be specified in the
640 <tt>Maintainer</tt> control field with the correct name
641 and a working email address for the Debian maintainer of
642 the package. If one person maintains several packages
643 he/she should try to avoid having different forms of their
644 name and email address in different <tt>Maintainer</tt>
648 If the maintainer of a package quits from the Debian
649 project the Debian QA Group
650 <email>debian-qa@lists.debian.org</email> takes over the
651 maintainership of the package until someone else
652 volunteers for that task. These packages are called
653 <em>orphaned packages</em>.
659 <heading>The description of a package</heading>
662 Every Debian package must have an extended description
663 stored in the appropriate field of the control record.</p>
666 The description must be written so that it tells the user
667 what they need to know to decide whether to install the
668 package. This description should not just be copied from
669 the blurb for the program. Instructions for configuring
670 or using the package must not be included -- that is what
671 installation scripts, manual pages, Info files, etc. are
672 for. Copyright statements and other administrivia must
673 not be included -- that is what the copyright file is
679 <heading>Dependencies</heading>
682 Every package has to specify the dependency information
683 about other packages, that are required for the first to
687 For example, for any shared libraries required by
688 dynamically-linked executable binary in a package a
689 dependency entry has to be provided.</p>
692 It is not necessary for other packages to declare any
693 dependencies they have on other packages which are marked
694 <tt>Essential</tt> (see below).</p>
697 Sometimes, a package requires another package to be
698 installed <em>and</em> configured before it can be
699 installed. In this case, you'll have to specify a
700 <tt>Pre-Depends</tt> entry for the package.</p>
703 You must not specify a <tt>Pre-Depends</tt> entry for a
704 package before this has been discussed on the
705 <tt>debian-devel</tt> mailing list and a consensus about
706 doing that has been reached.</p></sect1>
710 <heading>Virtual packages</heading>
713 Sometimes, there are several packages doing more-or-less
714 the same job. In this case, it's useful to define a
715 <em>virtual package</em> whose name describes the function
716 the packages have. (The virtual packages just exist
717 logically, not physically--that's why they are called
718 <em>virtual</em>.) The packages with this particular
719 function will then <em>provide</em> the virtual
720 package. Thus, any other package requiring that function
721 can simply depend on the virtual package without having to
722 specify all possible packages individually.</p>
725 All packages must use virtual package names where
726 appropriate, and arrange to create new ones if necessary.
727 They must not use virtual package names (except privately,
728 amongst a cooperating group of packages) unless they have
729 been agreed upon and appear in the list of virtual package
733 The latest version of the authoritative list of virtual
734 package names can be found on
735 <ftpsite>ftp.debian.org</ftpsite> in
736 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
737 or your local mirror. In addition, it is included in the
738 <tt>debian-policy</tt> package. The procedure for updating
739 the list is described at the top of the file.</p></sect1>
743 <heading>Base packages</heading>
746 The packages included in the <tt>base</tt> section have a
747 special function. They form a minimum subset of the Debian
748 GNU/Linux system that is installed before everything else
749 on a new system. Thus, only very few packages are allowed
750 to go into the <tt>base</tt> section to keep the required
751 disk usage very small.</p>
754 Most of these packages should have the priority value
755 <tt>required</tt> or at least <tt>important</tt>, and many
756 of them will be tagged <tt>essential</tt> (see below).</p>
759 You must not place any packages into the <tt>base</tt>
760 section before this has been discussed on the
761 <tt>debian-devel</tt> mailing list and a consensus about
762 doing that has been reached.</p></sect1>
766 <heading>Essential packages</heading>
769 Some packages are tagged <tt>essential</tt>. (They have
770 <tt>Essential: yes</tt> in their package control record.)
771 This flag is used for packages that are <em>essential</em>
775 Since these packages can not easily be removed (you'll
776 have to specify an extra <em>force option</em> to
777 <prgn>dpkg</prgn>) this flag must only be used where
778 absolutely necessary.
780 A shared library package must not be tagged
781 <em>essential</em>--the dependencies will prevent its
782 premature removal, and we need to be able to remove it
783 when it has been superseded.</p>
786 You must not tag any packages <tt>essential</tt> before
787 this has been discussed on the <tt>debian-devel</tt>
788 mailing and a consensus about doing that has been
793 <heading>Maintainer scripts</heading>
796 The package installation scripts must avoid producing
797 output which it is unnecessary for the user to see and
798 should rely on <prgn>dpkg</prgn> to stave off boredom on
799 the part of a user installing many packages. This means,
800 amongst other things, using the <tt>--quiet</tt> option on
801 <prgn>install-info</prgn>.</p>
804 Packages should try to minimize the amount of prompting
805 they need to do, and they should ensure that the user will
806 only ever be asked each question once. This means that
807 packages should try to use appropriate shared
808 configuration files (such as <tt>/etc/papersize</tt> and
809 <tt>/etc/news/server</tt>), rather than each prompting for
810 their own list of required pieces of information.</p>
813 It also means that an upgrade should not ask the same
814 questions again, unless the user has used <tt>dpkg
815 --purge</tt> to remove the package's configuration. The
816 answers to configuration questions should be stored in an
817 appropriate place in <tt>/etc</tt> so that the user can
818 modify them, and how this has been done should be
822 If a package has a vitally important piece of information
823 to pass to the user (such as "don't run me as I am, you
824 must edit the following configuration files first or you
825 risk your system emitting badly-formatted messages"), it
826 should display this in the <prgn>postinst</prgn> script
827 and prompt the user to hit return to acknowledge the
828 message. Copyright messages do not count as vitally
829 important (they belong in
830 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
831 do instructions on how to use a program (these should be
832 in on line documentation, where all the users can see
836 Any necessary prompting should almost always be confined
837 to the post-installation script, and should be protected
838 with a conditional so that unnecessary prompting doesn't
839 happen if a package's installation fails and the
840 <prgn>postinst</prgn> is called with
841 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
842 <tt>abort-deconfigure</tt>.</p>
845 Errors which occur during the execution of an installation
846 script <em>must</em> be checked and the installation
847 <em>must not</em> continue after an error.</p>
850 Note, that <ref id="scripts">, in general applies to
851 package maintainer scripts, too.</p>
854 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
855 another package without consulting the maintainer of that
859 In order for <prgn>update-alternatives</prgn> to work
860 correctly all the packages which supply an instance of the
861 `shared' command name (or, in general, filename) must use
862 it. You can use <tt>Conflicts</tt> to force the
863 De-installation of other packages supplying it which do not
864 (yet) use <prgn>update-alternatives</prgn>. It may in
865 this case be appropriate to specify a conflict on earlier
866 versions of something--this is an exception to the usual
867 rule that this is not allowed.</p>
871 <heading>Source packages</heading>
874 <heading>Standards conformance</heading>
877 You should specify the most recent version of the
878 packaging standards with which your package complies in
879 the source package's <tt>Standards-Version</tt> field.</p>
882 This value will be used to file bug reports automatically
883 if your package becomes too much out of date.</p>
886 The value corresponds to a version of the Debian manuals,
887 as can be found on the title page or page headers and
888 footers (depending on the format).</p>
891 The version number has four components--major and minor
892 number and major and minor patch level. When the
893 standards change in a way that requires every package to
894 change the major number will be changed. Significant
895 changes that will require work in many packages will be
896 signaled by a change to the minor number. The major patch
897 level will be changed for any change to the meaning of the
898 standards, however small; the minor patch level will be
899 changed when only cosmetic, typographical or other edits
900 which do not change the meaning are made, or changes which
901 do not affect the contents of packages.</p>
904 For package maintainers, only the first 3 digits of the
905 manual version are significant in representing the
906 <em>Standards-Version</em>, and either these 3 digits or
907 the complete 4 digits can be specified--that's up to the
911 In the past, people specified 4 digits in the
912 Standards-Version field, like `2.3.0.0'. Since any
913 `patch-level changes' don't introduce new policy, it
914 was thought it would be better to relax policy and
915 only require that the first 3 digits are specified. (4
916 digits can still be used if someone wants to do so.)
922 You should regularly, and especially if your package has
923 become out of date, check for the newest Policy Manual
924 available and update your package, if necessary. When your
925 package complies with the new standards you may update the
926 <tt>Standards-Version</tt> source package field and
927 release it.</p></sect1>
931 <heading>Package relationships</heading>
934 Source packages must specify which binary packages they
935 require to be installed or not to be installed in order to
936 build correctly. For example, if building a package
937 requires a certain compiler, then the compiler must be
938 specified as a build-time dependency.
942 It will not be necessary to explicitly specify build-time
943 relationships on a minimal set of packages that are always
944 needed to compile, link and put in a Debian package a
945 standard "Hello World!" program written in C or C++. The
946 required packages are called <em>build-essential</em>, and
947 an informational list can be found in
948 <tt>/usr/share/doc/build-essential/list</tt> (which is
949 contained in the <tt>build-essential</tt> package).
954 When specifying the set of build-time dependencies, one
955 should list only those packages explicitly required by the
956 build. It is not necessary to list packages which are
957 required merely because some other package in the list of
958 build-time dependencies depends on them. The reason is
959 that dependencies change, and you should list only those
960 <em>you</em> need. What others need is their business.
964 It is a bug if, after unpacking a source package on a
965 system with the build-essential packages installed and
966 satisfying the build-time relationships (including the
967 implied relationships), one cannot build the package and
968 produce a working binary package suitable for installation
969 into the binary distribution corresponding to the source
970 distribution which contained the source package. This
971 means in particular that version clauses should be used
972 rigorously in build-time relationships so that one cannot
973 produce bad or inconsistently configured packages when the
974 relationships are properly satisfied.
978 <heading>Changes to the upstream sources</heading>
981 If changes to the source code are made that are generally
982 applicable please try to get them included in the upstream
983 version of the package by supplying the upstream authors
984 with the changes in whatever form they prefer.</p>
987 If you need to configure the package differently for
988 Debian or for Linux, and the upstream source doesn't
989 provide a way to configure it the way you need to, please
990 add such configuration facilities (for example, a new
991 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
992 the patch to the upstream authors, with the default set to
993 the way they originally had it. You can then easily
994 override the default in your <tt>debian/rules</tt> or
995 wherever is appropriate.</p>
998 Please make sure that the <prgn>configure</prgn> utility
999 detects the correct architecture specification string
1000 (refer to <ref id="arch-spec"> for details).</p>
1003 If you need to edit a <prgn>Makefile</prgn> where
1004 GNU-style <prgn>configure</prgn> scripts are used, you
1005 should edit the <tt>.in</tt> files rather than editing the
1006 <prgn>Makefile</prgn> directly. This allows the user to
1007 reconfigure the package if necessary. You should
1008 <em>not</em> configure the package and edit the generated
1009 <prgn>Makefile</prgn>! This makes it impossible for
1010 someone else to later reconfigure the package.</p></sect1>
1014 <heading>Documenting your changes</heading>
1017 Document your changes and updates to the source package
1018 properly in the <tt>debian/changelog</tt> file.</p>
1021 A copy of the file which will be installed in
1022 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1023 in <tt>debian/copyright</tt>.</p>
1026 In non-experimental packages you may only use a format for
1027 <tt>debian/changelog</tt> which is supported by the most
1028 recent released version of <prgn>dpkg</prgn>. If your
1029 format is not supported and there is general support for
1030 it you should contact the <prgn>dpkg</prgn> maintainer to
1031 have the parser script for your format included in the
1032 <prgn>dpkg</prgn> package. (You will need to agree that
1033 the parser and its manpage may be distributed under the
1034 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1039 <heading>Error trapping in makefiles</heading>
1042 When <prgn>make</prgn> invokes a command in a makefile
1043 (including your package's upstream makefiles and the
1044 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1045 means that <tt>sh</tt>'s usual bad error handling
1046 properties apply: if you include a miniature script as one
1047 of the commands in your makefile you'll find that if you
1048 don't do anything about it then errors are not detected
1049 and <prgn>make</prgn> will blithely continue after
1053 Every time you put more than one shell command (this
1054 includes using a loop) in a makefile command you
1055 <em>must</em> make sure that errors are trapped. For
1056 simple compound commands, such as changing directory and
1057 then running a program, using <tt>&&</tt> rather
1058 than semicolon as a command separator is sufficient. For
1059 more complex commands including most loops and
1060 conditionals you must include a separate <tt>set -e</tt>
1061 command at the start of every makefile command that's
1062 actually one of these miniature shell scripts.</p></sect1>
1066 <heading>Obsolete constructs and libraries</heading>
1069 The include file <prgn><varargs.h></prgn> is
1070 provided to support end-users compiling very old software;
1071 the library <tt>libtermcap</tt> is provided to support the
1072 execution of software which has been linked against it
1073 (either old programs or those such as Netscape which are
1074 only available in binary form).</p>
1077 Debian packages should be ported to include
1078 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1083 <chapt><heading>The Operating System</heading>
1087 <heading>File system hierarchy</heading>
1091 <heading>Linux File system Structure</heading>
1094 The location of all installed files and directories must
1095 comply with the Linux File system Hierarchy Standard
1096 (FHS). The latest version of this document can be found
1097 alongside this manual or on
1098 <url id="http://www.pathname.com/fhs/">.<footnote>
1099 <p>The Debian distribution currently distributes a draft
1100 version of FHS 2.1 because several significant details
1101 have changed between the currently released 2.0
1102 version and the to-be-released 2.1 version.</p>
1104 Specific questions about following the standard may be
1105 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1106 Quinlan, the FHS coordinator, at
1107 <email>quinlan@pathname.com</email>.</p></sect1>
1111 <heading>Site-specific programs</heading>
1114 As mandated by the FHS no package should place any
1115 files in <tt>/usr/local</tt>, either by putting them in
1116 the file system archive to be unpacked by <prgn>dpkg</prgn>
1117 or by manipulating them in their maintainer scripts.</p>
1120 However, the package should create empty directories below
1121 <tt>/usr/local</tt> so that the system administrator knows
1122 where to place site-specific files. These directories
1123 should be removed on package removal if they are
1127 Note, that this applies only to directories <em>below</em>
1128 <tt>/usr/local</tt>, not <em>in</em>
1129 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1130 itself may only contain the sub-directories listed in
1131 FHS, section 4.6. However, you may create directories
1132 below them as you wish. You may not remove any of the
1133 directories listed in 4.6, even if you created them.</p>
1136 Since <tt>/usr/local</tt> may be mounted read-only from a
1137 remote server, these directories have to be created and
1138 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1139 maintainer scripts. These scripts must not fail if either
1140 of these operations fail. (In the future, it will be
1141 possible to tell <prgn>dpkg</prgn> not to unpack files
1142 matching certain patterns, so that the directories can be
1143 included in the <tt>.deb</tt> packages and system
1144 administrators who do not wish these directories in
1145 /usr/local do not need to have them.)</p>
1148 For example, the <prgn>emacs</prgn> package will contain
1150 mkdir -p /usr/local/lib/emacs/site-lisp || true
1152 in the <tt>postinst</tt> script, and
1154 rmdir /usr/local/lib/emacs/site-lisp && \
1155 rmdir /usr/local/lib/emacs || \
1158 in the <tt>prerm</tt> script.</p>
1161 If you do create a directory in <tt>/usr/local</tt> for
1162 local additions to a package, you must ensure that
1163 settings in <tt>/usr/local</tt> take precedence over the
1164 equivalents in <tt>/usr</tt>.</p>
1167 However, because '/usr/local' and its contents are for
1168 exclusive use of the local administrator, a package must
1169 not rely on the presence or absence of files or
1170 directories in '/usr/local' for normal operation.</p>
1173 The <tt>/usr/local</tt> directory itself and all the
1174 subdirectories created by the package should have
1175 permissions 2775 (group-writable and set-group-id) and be
1176 owned by <tt>root.staff</tt>.</p>
1181 <heading>Users and groups</heading>
1184 The Debian system can be configured to use either plain or
1185 shadow passwords.</p>
1188 Some user ids (UIDs) and group ids (GIDs) are reserved
1189 globally for use by certain packages. Because some packages
1190 need to include files which are owned by these users or
1191 groups, or need the ids compiled into binaries, these ids
1192 must be used on any Debian system only for the purpose for
1193 which they are allocated. This is a serious restriction, and
1194 we should avoid getting in the way of local administration
1195 policies. In particular, many sites allocate users and/or
1196 local system groups starting at 100.</p>
1199 Apart from this we should have dynamically allocated ids,
1200 which should by default be arranged in some sensible
1201 order--but the behavior should be configurable.</p>
1204 No package except <tt>base-passwd</tt> may modify
1205 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1206 <tt>/etc/group</tt>.</p>
1209 The UID and GID ranges are as follows:
1214 Globally allocated by the Debian project, must be the
1215 same on every Debian system. These ids will appear in
1216 the <tt>passwd</tt> and <tt>group</tt> files of all
1217 Debian systems, new ids in this range being added
1218 automatically as the <tt>base-passwd</tt> package is
1222 Packages which need a single statically allocated uid
1223 or gid should use one of these; their maintainers
1224 should ask the <tt>base-passwd</tt> maintainer for
1231 Dynamically allocated system users and groups.
1232 Packages which need a user or group, but can have this
1233 user or group allocated dynamically and differently on
1234 each system, should use `<tt>adduser --system</tt>' to
1235 create the group and/or user. <prgn>adduser</prgn>
1236 will check for the existence of the user or group, and
1237 if necessary choose an unused id based on the ranged
1238 specified in <tt>adduser.conf</tt>.</p></item>
1241 <tag>1000-29999:</tag>
1244 Dynamically allocated user accounts. By default
1245 <prgn>adduser</prgn> will choose UIDs and GIDs for
1246 user accounts in this range, though
1247 <tt>adduser.conf</tt> may be used to modify this
1251 <tag>30000-59999:</tag>
1253 <p>Reserved.</p></item>
1256 <tag>60000-64999:</tag>
1259 Globally allocated by the Debian project, but only
1260 created on demand. The ids are allocated centrally and
1261 statically, but the actual accounts are only created
1262 on users' systems on demand.</p>
1265 These ids are for packages which are obscure or which
1266 require many statically-allocated ids. These packages
1267 should check for and create the accounts in
1268 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1269 <prgn>adduser</prgn> if it has this facility) if
1270 necessary. Packages which are likely to require
1271 further allocations should have a `hole' left after
1272 them in the allocation, to give them room to
1276 <tag>65000-65533:</tag>
1278 <p>Reserved.</p></item>
1283 <p>User `<tt>nobody</tt>.'</p></item>
1289 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1290 because it is the error return sentinel value.</p>
1295 <sect id="sysvinit">
1296 <heading>System run levels</heading>
1299 <sect1 id="/etc/init.d">
1300 <heading>Introduction</heading>
1303 The <tt>/etc/init.d</tt> directory contains the scripts
1304 executed by <prgn>init</prgn> at boot time and when init
1305 state (or `runlevel') is changed (see <manref name="init"
1309 There are at least two different, yet functionally
1310 equivalent, ways of handling these scripts. For the sake
1311 of simplicity, this document describes only the symbolic
1312 link method. However, it may not be assumed that this
1313 method is being used, and any manipulation of the various
1314 runlevel behaviours must be performed using
1315 <prgn>update-rc.d</prgn> as described below and not by
1316 manually installing symlinks. For information on the
1317 implementation details of the other method, implemented in
1318 the <tt>file-rc</tt> package, please refer to the
1319 documentation of that package.</p>
1322 These scripts are referenced by symbolic links in
1323 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1324 changing runlevels, <prgn>init</prgn> looks in the
1325 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1326 it should execute, where <var>n</var> is the runlevel that
1327 is being changed to, or `S' for the boot-up scripts.</p>
1330 The names of the links all have the form
1331 <tt>S<var>mm</var><var>script</var></tt> or
1332 <tt>K<var>mm</var><var>script</var></tt> where
1333 <var>mm</var> is a two-digit number and <var>script</var>
1334 is the name of the script (this should be the same as the
1335 name of the actual script in <tt>/etc/init.d</tt>.</p>
1338 When <prgn>init</prgn> changes runlevel first the targets
1339 of the links whose names starting with a <tt>K</tt> are
1340 executed, each with the single argument <tt>stop</tt>,
1341 followed by the scripts prefixed with an <tt>S</tt>, each
1342 with the single argument <tt>start</tt>. The <tt>K</tt>
1343 links are responsible for killing services and the
1344 <tt>S</tt> link for starting services upon entering the
1348 For example, if we are changing from runlevel 2 to
1349 runlevel 3, init will first execute all of the <tt>K</tt>
1350 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1351 all of the <tt>S</tt> prefixed scripts. The links
1352 starting with <tt>K</tt> will cause the referred-to file
1353 to be executed with an argument of <tt>stop</tt>, and the
1354 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1357 The two-digit number <var>mm</var> is used to decide which
1358 order to start and stop things in--low-numbered links have
1359 their scripts run first. For example, the <tt>K20</tt>
1360 scripts will be executed before the <tt>K30</tt> scripts.
1361 This is used when a certain service must be started before
1362 another. For example, the name server <prgn>bind</prgn>
1363 might need to be started before the news server
1364 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1365 access lists. In this case, the script that starts
1366 <prgn>bind</prgn> should have a lower number than the
1367 script that starts <prgn>inn</prgn> so that it runs first:
1376 <heading>Writing the scripts</heading>
1379 Packages can and should place scripts in
1380 <tt>/etc/init.d</tt> to start or stop services at boot
1381 time or during a change of runlevel. These scripts should
1382 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1383 should accept one argument, saying what to do:
1386 <tag><tt>start</tt></tag>
1387 <item><p>start the service,</p></item>
1389 <tag><tt>stop</tt></tag>
1390 <item><p>stop the service,</p></item>
1392 <tag><tt>restart</tt></tag>
1393 <item><p>stop and restart the service,</p></item>
1395 <tag><tt>reload</tt></tag>
1396 <item><p>cause the configuration of the service to be
1397 reloaded without actually stopping and restarting
1398 the service,</p></item>
1400 <tag><tt>force-reload</tt></tag> <item><p>cause the
1401 configuration to be reloaded if the service supports
1402 this, otherwise restart the service.</p></item>
1405 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1406 <tt>force-reload</tt> options must be supported by all
1407 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1408 option is optional.</p>
1411 The <tt>init.d</tt> scripts should ensure that they will
1412 behave sensibly if invoked with <tt>start</tt> when the
1413 service is already running, or with <tt>stop</tt> when it
1414 isn't, and that they don't kill unfortunately-named user
1415 processes. The best way to achieve this is usually to use
1416 <prgn>start-stop-daemon</prgn>.</p>
1419 If a service reloads its configuration automatically (as
1420 in the case of <prgn>cron</prgn>, for example), the
1421 <tt>reload</tt> option of the <tt>init.d</tt> script
1422 should behave as if the configuration has been reloaded
1426 These scripts should not fail obscurely when the
1427 configuration files remain but the package has been
1428 removed, as configuration files remain on the system after
1429 the package has been removed. Only when <prgn>dpkg</prgn>
1430 is executed with the <tt>--purge</tt> option will
1431 configuration files be removed. In particular, the init
1432 script itself is usually a configuration file (see
1433 <ref id="init.d notes">), and will remain on the system if
1434 the package is removed but not purged. Therefore, you
1435 should include a <tt>test</tt> statement at the top of the
1438 test -f <var>program-executed-later-in-script</var> || exit 0
1443 <heading>Managing the links</heading>
1446 A program is provided, <prgn>update-rc.d</prgn>, to handle
1447 the it easier for package maintainers to arrange for the
1448 proper creation and removal of
1449 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1450 functional equivalent if another method is being used.
1451 This may be used by maintainers in their packages'
1452 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1455 You should use this script to make changes to
1456 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1457 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1458 in the actual archive or manually create or remove the
1459 symbolic links in maintainer scripts. (The latter will
1460 fail if an alternative method of maintaining runlevel
1461 information is being used.)</p>
1464 By default <prgn>update-rc.d</prgn> will start services in
1465 each of the multi-user state runlevels (2, 3, 4, and 5)
1466 and stop them in the halt runlevel (0), the single-user
1467 runlevel (1) and the reboot runlevel (6). The system
1468 administrator will have the opportunity to customize
1469 runlevels by either running <prgn>update-rc.d</prgn>, by
1470 simply adding, moving, or removing the symbolic links in
1471 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1472 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1473 <tt>file-rc</tt> method is being used.</p>
1476 To get the default behavior for your package, put in your
1477 <tt>postinst</tt> script
1479 update-rc.d <var>package</var> defaults >/dev/null
1481 and in your <tt>postrm</tt>
1483 if [ purge = "$1" ]; then
1484 update-rc.d <var>package</var> remove >/dev/null
1489 This will use a default sequence number of 20. If it does
1490 not matter when or in which order the script is run, use
1491 this default. If it does, then you should talk to the
1492 maintainer of the <prgn>sysvinit</prgn> package or post to
1493 <tt>debian-devel</tt>, and they will help you choose a
1497 For more information about using <tt>update-rc.d</tt>,
1498 please consult its manpage <manref name="update-rc.d"
1499 section="8">.</p></sect1>
1503 <heading>Boot-time initialization</heading>
1506 There used to be another directory, <tt>/etc/rc.boot</tt>,
1507 which contained scripts which were run once per machine
1508 boot. This has been deprecated in favour of links from
1509 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1510 described in <ref id="/etc/init.d">. No packages may
1511 place files in <tt>/etc/rc.boot</tt>.</p>
1513 <sect1 id="init.d notes">
1514 <heading>Notes</heading>
1517 <em>Do not</em> include the
1518 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1519 <tt>.deb</tt> file system archive! <em>This will cause
1520 problems!</em> You should create them with
1521 <prgn>update-rc.d</prgn>, as above.</p>
1524 <em>Do not</em> include the
1525 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1526 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1527 problems!</em> <em>Do</em>, however, treat the
1528 <tt>/etc/init.d</tt> scripts as configuration files,
1529 either by marking them as conffiles or managing them
1530 correctly in the maintainer scripts (see
1531 <ref id="config files">). (This is important since we want
1532 to give the local system administrator the chance to adapt
1533 the scripts to the local system--e.g., to disable a
1534 service without de-installing the package, or to specify
1535 some special command line options when starting a
1536 service--while making sure her changes aren't lost during
1537 the next package upgrade.)</p>
1541 <heading>Example</heading>
1544 The <prgn>bind</prgn> DNS (nameserver) package wants to
1545 make sure that the nameserver is running in multiuser
1546 runlevels, and is properly shut down with the system. It
1547 puts a script in <tt>/etc/init.d</tt>, naming the script
1548 appropriately <tt>bind</tt>. As you can see, the script
1549 interprets the argument <tt>reload</tt> to send the
1550 nameserver a <tt>HUP</tt> signal (causing it to reload its
1551 configuration); this way the user can say
1552 <tt>/etc/init.d/bind reload</tt> to reload the name
1559 # Original version by Robert Leslie
1560 # <rob@mars.org>, edited by iwj and cs
1562 test -x /usr/sbin/named || exit 0
1566 echo -n "Starting domain name service: named"
1567 start-stop-daemon --start --quiet --exec /usr/sbin/named
1571 echo -n "Stopping domain name service: named"
1572 start-stop-daemon --stop --quiet \
1573 --pidfile /var/run/named.pid --exec /usr/sbin/named
1577 echo -n "Restarting domain name service: named"
1578 start-stop-daemon --stop --quiet \
1579 --pidfile /var/run/named.pid --exec /usr/sbin/named
1580 start-stop-daemon --start --verbose --exec /usr/sbin/named
1583 force-reload|reload)
1584 echo -n "Reloading configuration of domain name service: named"
1585 start-stop-daemon --stop --signal 1 --quiet \
1586 --pidfile /var/run/named.pid --exec /usr/sbin/named
1590 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1599 Another example on which to base your <tt>/etc/init.d</tt>
1600 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1603 If this package is happy with the default setup from
1604 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1605 and having named running in all runlevels, it can say in
1606 its <tt>postinst</tt>:
1608 update-rc.d bind defaults >/dev/null
1610 And in its <tt>postrm</tt>, to remove the links when the
1613 if [ purge = "$1" ]; then
1614 update-rc.d acct remove >/dev/null
1620 <heading>Cron jobs</heading>
1623 Packages may not modify the configuration file
1624 <tt>/etc/crontab</tt>, nor may they modify the files in
1625 <tt>/var/spool/cron/crontabs</tt>.</p>
1628 If a package wants to install a job that has to be executed
1629 via cron, it should place a file with the name if the
1630 package in one of the following directories:
1636 As these directory names imply, the files within them are
1637 executed on a daily, weekly, or monthly basis,
1638 respectively. The exact times are listed in
1639 <tt>/etc/crontab</tt>.</p>
1642 All files installed in any of these directories have to be
1643 scripts (shell scripts, Perl scripts, etc.) so that they can
1644 easily be modified by the local system administrator. In
1645 addition, they must be treated as configuration files.</p>
1648 If a certain job has to be executed more frequently than
1649 daily, the package should install a file
1650 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1651 the same syntax as <tt>/etc/crontab</tt> and is processed by
1652 <prgn>cron</prgn> automatically. The file must also be
1653 treated as a configuration file. (Note, that entries in the
1654 <tt>/etc/cron.d</tt> directory are not handled by
1655 <prgn>anacron</prgn>. Thus, you should only use this
1656 directory for jobs which may be skipped if the system is not
1660 The scripts or crontab entries in these directories should
1661 check if all necessary programs are installed before they
1662 try to execute them. Otherwise, problems will arise when a
1663 package was removed but not purged since configuration files
1664 are kept on the system in this situation.</p>
1668 <heading>Console messages</heading>
1671 This section describes different formats for messages
1672 written to standard output by the <tt>/etc/init.d</tt>
1673 scripts. The intent is to improve the consistency of
1674 Debian's startup and shutdown look and feel.</p>
1677 Please look very careful at the details. We want to get the
1678 messages to look exactly the same way concerning spaces,
1679 punctuation, and case of letters.</p>
1682 Here is a list of overall rules that you should use when you
1683 create output messages. They can be useful if you have a
1684 non-standard message that isn't covered in the sections
1691 Every message should cover one line, start with a
1692 capital letter and end with a period `.'.</p></item>
1697 If you want to express that the computer is working on
1698 something (performing a specific task, not starting or
1699 stopping a program), we use an ``ellipsis'', namely
1700 three dots `...'. Note that we don't insert spaces in
1701 front of or behind the dots. If the task has been
1702 completed we write `done.' and a line feed.</p></item>
1707 Design your messages as if the computer is telling you
1708 what he is doing (let him be polite :-) but don't
1709 mention ``him'' directly. For example, if you think
1712 I'm starting network daemons: nfsd mountd.
1716 Starting network daemons: nfsd mountd.
1717 </example></p></item>
1721 The following formats must be used</p>
1726 <p>when daemons get started.</p>
1729 Use this format if your script starts one or more
1730 daemons. The output should look like this (a single
1731 line, no leading spaces):
1733 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1735 The <description> should describe the subsystem
1736 the daemon or set of daemons are part of, while
1737 <daemon-1> up to <daemon-n> denote each
1738 daemon's name (typically the file name of the
1742 For example, the output of /etc/init.d/lpd would look like:
1744 Starting printer spooler: lpd.
1748 This can be achieved by saying
1750 echo -n "Starting printer spooler: lpd"
1751 start-stop-daemon --start --quiet lpd
1754 in the script. If you have more than one daemon to
1755 start, you should do the following:
1757 echo -n "Starting remote file system services:"
1758 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1759 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1760 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1763 This makes it possible for the user to see what takes
1764 so long and when the final daemon has been
1765 started. Please be careful where to put spaces: In the
1766 example above the system administrator can easily
1767 comment out a line if he don't wants to start a
1768 specific daemon, while the displayed message still
1769 looks good.</p></item>
1773 <p>when something needs to be configured.</p>
1776 If you have to set up different parameters of the
1777 system upon boot up, you can use this format:
1779 Setting <parameter> to `<value>'.
1783 You can use the following echo statement to get the quotes right:
1785 echo "Setting DNS domainname to \`"value"'."
1789 Note that the left quotation mark (`) is different
1790 from the right (').</p></item>
1793 <p>when a daemon is stopped.</p>
1796 When you stop a daemon you should issue a message
1797 similar to the startup message, except that `Starting'
1798 is replaced with `Stopping'.</p>
1801 So stopping the printer daemon will like like this:
1803 Stopping printer spooler: lpd.
1804 </example></p></item>
1807 <p>when something is executed.</p>
1810 There a several examples where you have to run a
1811 program at system startup or shutdown to perform a
1812 specific task. For example, setting the system's clock
1813 via `netdate' or killing all processes when the system
1814 comes down. Your message should like this:
1816 Doing something very useful...done.
1818 You should print the `done.' right after the job has been completed,
1819 so that the user gets informed why he has to wait. You can get this
1822 echo -n "Doing something very useful..."
1826 in your script.</p></item>
1829 <p>when the configuration is reloaded.</p>
1832 When a daemon is forced to reload its configuration
1833 files you should use the following format:
1835 Reloading <daemon's-name> configuration...done.
1836 </example></p></item>
1839 <p>when none of the above rules apply.</p>
1842 If you have to print a message that doesn't fit into
1843 the styles described above, you can use something
1844 appropriate, but please have a look at the overall
1845 rules listed above.</p></item>
1850 <heading>Menus</heading>
1853 Menu entries should follow the current menu policy as
1854 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1855 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1856 or your local mirror. In addition, it is included in the
1857 <tt>debian-policy</tt> package.
1861 The Debian <tt>menu</tt> packages provides a unique
1862 interface between packages providing applications and
1863 documents, and <em>menu programs</em> (either X window
1864 managers or text-based menu programs as
1865 <prgn>pdmenu</prgn>).</p>
1868 All packages that provide applications that need not be
1869 passed any special command line arguments for normal
1870 operation should register a menu entry for those
1871 applications, so that users of the <tt>menu</tt> package
1872 will automatically get menu entries in their window
1873 managers, as well in shells like <tt>pdmenu</tt>.</p>
1876 Please refer to the <em>Debian Menu System</em> document
1877 that comes with the <tt>menu</tt> package for information
1878 about how to register your applications and web
1884 <heading>Multimedia handlers</heading>
1887 Packages which provide the ability to view/show/play,
1888 compose, edit or print MIME types should register themselves
1889 as such following the current MIME support policy as defined
1890 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1891 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1892 or your local mirror. In addition, it is included in the
1893 <tt>debian-policy</tt> package.
1897 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1898 mechanism for encoding files and data streams and providing
1899 meta-information about them, in particular their type (e.g.
1900 audio or video) and format (e.g. PNG, HTML, MP3).
1904 Registration of MIME type handlers allows programs like mail
1905 user agents and web browsers to to invoke these handlers to
1906 view, edit or display MIME types they don't support
1912 <heading>Keyboard configuration</heading>
1915 To achieve a consistent keyboard configuration (i.e., all
1916 applications interpret a keyboard event the same way) all
1917 programs in the Debian distribution have to be configured to
1918 comply with the following guidelines.</p>
1921 Here is a list that contains certain keys and their interpretation:
1924 <tag><tt><--</tt></tag>
1925 <item><p>delete the character to the left of the cursor</p></item>
1927 <tag><tt>Delete</tt></tag>
1928 <item><p>delete the character to the right of the cursor</p></item>
1930 <tag><tt>Control+H</tt></tag>
1931 <item><p>emacs: the help prefix</p></item>
1934 The interpretation of any keyboard events should be independent
1935 of the terminal that's used, be it a virtual console, an X
1936 terminal emulator, an rlogin/telnet session, etc.</p>
1939 The following list explains how the different programs
1940 should be set up to achieve this:</p>
1943 <list compact="compact">
1944 <item><p>`<tt><--</tt>' generates KB_Backspace in
1947 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1951 X translations are set up to make KB_Backspace
1952 generate ASCII DEL, and to make KB_Delete generate
1953 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1954 the `delete character' key). This must be done by
1955 loading the resources using xrdb on all local X
1956 displays, not using the application defaults, so that
1957 the translation resources used correspond to the
1958 xmodmap settings.</p></item>
1962 The Linux console is configured to make
1963 `<tt><--</tt>' generate DEL, and `Delete' generate
1964 <tt>ESC [ 3 ~</tt> (this is the case at the
1968 X applications are configured so that Backspace
1969 deletes left, and Delete deletes right. Motif
1970 applications already work like this.</p></item>
1972 <item><p>stty erase <tt>^?</tt> .</p></item>
1975 The `xterm' terminfo entry should have <tt>ESC [ 3
1976 ~</tt> for kdch1, just like TERM=linux and
1977 TERM=vt220.</p></item>
1980 Emacs is programmed to map KB_Backspace or the `stty
1981 erase' character to delete-backward-char, and
1982 KB_Delete or kdch1 to delete-forward-char, and
1983 <tt>^H</tt> to help as always.</p></item>
1986 Other applications use the `stty erase' character and
1987 kdch1 for the two delete keys, with ASCII DEL being
1988 `delete previous character' and kdch1 being `delete
1989 character under cursor'.</p></item>
1993 This will solve the problem except for:</p>
1996 <list compact="compact">
1998 Some terminals have a <tt><--</tt> key that cannot
1999 be made to produce anything except <tt>^H</tt>. On
2000 these terminals Emacs help will be unavailable on
2001 <tt>^H</tt> (assuming that the `stty erase' character
2002 takes precedence in Emacs, and has been set
2003 correctly). M-x help or F1 (if available) can be used
2007 Some operating systems use <tt>^H</tt> for stty erase.
2008 However, modern telnet versions and all rlogin
2009 versions propagate stty settings, and almost all UNIX
2010 versions honour stty erase. Where the stty settings
2011 are not propagated correctly things can be made to
2012 work by using stty manually.</p></item>
2015 Some systems (including previous Debian versions) use
2016 xmodmap to arrange for both <tt><--</tt> and Delete
2017 to generate KB_Delete. We can change the behavior
2018 of their X clients via the same X resources that we
2019 use to do it for our own, or have our clients be
2020 configured via their resources when things are the
2021 other way around. On displays configured like this
2022 Delete will not work, but <tt><--</tt>
2026 Some operating systems have different kdch1 settings
2027 in their terminfo for xterm and others. On these
2028 systems the Delete key will not work correctly when
2029 you log in from a system conforming to our policy, but
2030 <tt><--</tt> will.</p></item>
2037 <heading>Environment variables</heading>
2040 No program may depend on environment variables to get
2041 reasonable defaults. (That's because these environment
2042 variables would have to be set in a system-wide
2043 configuration file like /etc/profile, which is not supported
2047 If a program should depend on environment variables for its
2048 configuration, the program has to be changed to fall back to
2049 a reasonable default configuration if these environment
2050 variables are not present. If this cannot be done easily
2051 (e.g., if the source code of a non-free program is not
2052 available), the program should be replaced by a small
2053 `wrapper' shell script which sets the environment variables
2054 and calls the original program.</p>
2057 Here is an example of a wrapper script for this purpose:
2063 exec /usr/lib/foo/foo "$@"
2067 Furthermore, as <tt>/etc/profile</tt> is a configuration
2068 file of the <prgn>bash</prgn> package, no other package may
2069 put any environment variables or other commands into that
2074 <heading>Files</heading>
2078 <heading>Binaries</heading>
2081 It is not allowed that two packages install programs with
2082 different functionality but with the same filenames. (The
2083 case of two programs having the same functionality but
2084 different implementations is handled via `alternatives.')
2085 If this case happens, one of the programs has to be
2086 renamed. The maintainers should report this to the
2087 developers' mailing and try to find a consensus about
2088 which package will have to be renamed. If a consensus can
2089 not be reached, <em>both</em> programs must be
2093 Generally the following compilation parameters should be used:
2096 CFLAGS = -O2 -Wall # sane warning options vary between programs
2098 install -s # (or use strip on the files in debian/tmp)
2102 Note that by default all installed binaries should be stripped,
2103 either by using the <tt>-s</tt> flag to
2104 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2105 the binaries after they have been copied into
2106 <tt>debian/tmp</tt> but before the tree is made into a
2110 The <tt>-N</tt> flag should not be used. On a.out systems
2111 it may have been useful for some very small binaries, but
2112 for ELF it has no good effect.</p>
2115 Debugging symbols are useful for error diagnosis, investigation
2116 of core dumps (which may be submitted by users in bug reports),
2117 or testing and developing the software. Therefore it is
2118 recommended to support building the package with
2119 debugging information through the following interface:
2120 If the environment variable <tt>DEB_BUILD_OPTIONS</tt>
2121 contains the string <tt>debug</tt>, compile the software with
2122 debugging information (usually this involves adding the
2123 <tt>-g</tt> flag to <tt>CFLAGS</tt>). This allows to generate
2124 a build tree with debugging information. If the environment
2125 variable <tt>DEB_BUILD_OPTIONS</tt> contains the
2126 string <tt>nostrip</tt>, do not strip the files at installation
2127 time. This allows to generate a package with debugging
2128 information included. The following makefile snippet
2129 is only an example how to test for either
2133 Rationale: Building by default with -g causes more
2134 wasted CPU cycles since the information is stripped away
2135 anyway. The package can by default build without -g if
2136 it also provides a mechanism to easily be rebuilt with
2137 debugging information. This can be done by providing a
2138 "build-debug" make target, or allowing the user to
2139 specify "BUILD_DEBUG=yes" in the environment while
2140 compiling that package.
2142 <p>Now this has several added benefits:
2146 It is actually easier to build debugging bins and
2147 libraries this way (no more editing debian/rules
2148 or similar) since it provides a documented way of
2149 getting this type of build.</p>
2153 There will be much less wasted cpu time for the
2154 autobuilders since not having debugging
2155 information (and hence also not having to strip
2156 it) will increase the speed of compiles. This
2157 skips an entire pass of the compiler,
2168 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
2170 ifneq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
2177 It is up to the package maintainer to decide what
2178 compilation options are best for the package. Certain
2179 binaries (such as computationally-intensive programs) may
2180 function better with certain flags (<tt>-O3</tt>, for
2181 example); feel free to use them. Please use good judgment
2182 here. Don't use flags for the sake of it; only use them
2183 if there is good reason to do so. Feel free to override
2184 the upstream author's ideas about which compilation
2185 options are best--they are often inappropriate for our
2186 environment.</p></sect>
2190 <heading>Libraries</heading>
2193 All libraries must have a shared version in the lib
2194 package and a static version in the lib-dev package. The
2195 shared version must be compiled with <tt>-fPIC</tt>, and
2196 the static version must not be. In other words, each
2197 <tt>*.c</tt> file is compiled twice.</p>
2200 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2201 when building a library (either static or shared) to make
2202 the library compatible with LinuxThreads.</p>
2205 Note that all installed shared libraries should be
2208 strip --strip-unneeded <your-lib>
2210 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2211 only the symbols which aren't needed for relocation
2212 processing.) Shared libraries can function perfectly well
2213 when stripped, since the symbols for dynamic linking are
2214 in a separate part of the ELF object file.</p>
2217 Note that under some circumstances it may be useful to
2218 install a shared library unstripped, for example when
2219 building a separate package to support debugging.
2223 An ever increasing number of packages are using libtool to
2224 do their linking. The latest GNU libtools (>= 1.3a) can take
2225 advantage of the metadata in the installed libtool archive
2226 files (`*.la'). The main advantage of libtool's .la files is
2227 that it allows libtool to store and subsequently access
2228 metadata with respect to the libraries it builds. libtool
2229 will search for those files, which contain a lot of useful
2230 information about a library (e.g. dependency libraries for
2231 static linking). Also, they're <em>essential</em> for
2232 programs using libltdl.
2236 Certainly libtool is fully capable of linking against shared
2237 libraries which don't have .la files, but being a mere shell
2238 script it can add considerably to the build time of a
2239 libtool using package if that shell-script has to derive all
2240 this information from first principles for each library every
2241 time it is linked. With the advent of libtool-1.4 (and to a
2242 lesser extent libtool-1.3), the .la files will also store
2243 information about inter-library dependencies which cannot
2244 necessarily be derived after the .la file is deleted.
2248 Packages that use libtool to create shared libraries must
2249 include the <em>.la</em> files in the <em>-dev</em>
2250 packages, with the exception that if the package relies on
2251 libtool's <em>libltdl</em> library, in which case the .la
2252 files must go in the run-time library package. This is a
2253 good idea in general, and especially for static linking
2258 Please make sure that you use only released versions of
2259 shared libraries to build your packages; otherwise other
2260 users will not be able to run your binaries
2261 properly. Producing source packages that depend on
2262 unreleased compilers is also usually a bad
2269 <heading>Shared libraries</heading>
2272 Packages involving shared libraries should be split up
2273 into several binary packages.</p>
2276 For a straightforward library which has a development
2277 environment and a runtime kit including just shared
2278 libraries you need to create two packages:
2279 <tt><var>libraryname</var><var>soname</var></tt>
2280 (<var>soname</var> is the shared object name of the shared
2281 library--it's the thing that has to match exactly between
2282 building an executable and running it for the dynamic
2283 linker to be able run the program; usually the
2284 <var>soname</var> is the major number of the library) and
2285 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2288 If you prefer only to support one development version at a
2289 time you may name the development package
2290 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2291 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2292 ensure that the user only installs one development version
2293 at a time (after all, different development versions are
2294 likely to have the same header files in them, causing a
2295 filename clash if both are installed). Typically the
2296 development version will also need an exact version
2297 dependency on the runtime library, to make sure that
2298 compilation and linking happens correctly.</p>
2301 Packages which use the shared library should have a
2302 dependency on the name of the shared library package,
2303 <tt><var>libraryname</var><var>soname</var></tt>. When
2304 the <var>soname</var> changes you can have both versions
2305 of the library installed while moving from the old library
2309 If your package has some run-time support programs which
2310 use the shared library you must <em>not</em> put them in
2311 the shared library package. If you do that then you won't
2312 be able to install several versions of the shared library
2313 without getting filename clashes. Instead, either create
2314 a third package for the runtime binaries (this package
2315 might typically be named
2316 <tt><var>libraryname</var>-runtime</tt>--note the absence
2317 of the <var>soname</var> in the package name) or if the
2318 development package is small include them in there.</p>
2321 If you have several shared libraries built from the same
2322 source tree you can lump them all together into a single
2323 shared library package, provided that you change all their
2324 <var>soname</var>s at once (so that you don't get filename
2325 clashes if you try to install different versions of the
2326 combined shared libraries package).</p>
2329 Follow the directions in the <em>Debian Packaging
2330 Manual</em> for putting the shared library in its package,
2331 and make sure you include a <tt>shlibs</tt> control area
2332 file with details of the dependencies for packages which
2333 use the library.</p>
2336 Shared libraries should <em>not</em> be installed
2337 executable, since <prgn>ld.so</prgn> does not require this
2338 and trying to execute a shared library results in a core
2343 <heading>Scripts</heading>
2346 All command scripts, including the package maintainer
2347 scripts inside the package and used by <prgn>dpkg</prgn>,
2348 should have a <tt>#!</tt> line naming the shell to be used
2349 to interpret them.</p>
2352 In the case of Perl scripts this should be
2353 <tt>#!/usr/bin/perl</tt>.</p>
2356 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2357 should almost certainly start with <tt>set -e</tt> so that
2358 errors are detected. Every script <em>must</em> use
2359 <tt>set -e</tt> or check the exit status of <em>every</em>
2363 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2364 symbolic link to any POSIX compatible shell. Thus, shell
2365 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2366 only use POSIX features. If a script requires non-POSIX
2367 features from the shell interpreter, the appropriate shell
2368 has to be specified in the first line of the script (e.g.,
2369 `<tt>#!/bin/bash</tt>') and the package has to depend on
2370 the package providing the shell (unless the shell package
2371 is marked `Essential', e.g., in the case of
2372 <prgn>bash</prgn>).</p>
2375 Restrict your script to POSIX features when possible so
2376 that it may use <tt>/bin/sh</tt> as its interpreter. If
2377 your script works with <prgn>ash</prgn>, it's probably
2378 POSIX compliant, but if you are in doubt, use
2379 <tt>/bin/bash</tt>.</p>
2382 Perl scripts should check for errors when making any
2383 system calls, including <tt>open</tt>, <tt>print</tt>,
2384 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2387 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2388 as scripting languages. See <em>Csh Programming
2389 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2390 FAQs. It can be found on
2391 <url id="http://language.perl.com/versus/csh.whynot">, or
2392 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2393 or even on <ftpsite>ftp.cpan.org</ftpsite>
2394 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2395 If an upstream package comes with <prgn>csh</prgn> scripts
2396 then you must make sure that they start with
2397 <tt>#!/bin/csh</tt> and make your package depend on the
2398 <prgn>c-shell</prgn> virtual package.</p>
2401 Any scripts which create files in world-writable
2402 directories (e.g., in <tt>/tmp</tt>) have to use a
2403 mechanism which will fail if a file with the same name
2407 The Debian base distribution provides the
2408 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2409 for use by scripts for this purpose.</p></sect>
2413 <heading>Symbolic links</heading>
2416 In general, symbolic links within a top-level directory
2417 should be relative, and symbolic links pointing from one
2418 top-level directory into another should be absolute. (A
2419 top-level directory is a sub-directory of the root
2423 In addition, symbolic links should be specified as short
2424 as possible, i.e., link targets like `foo/../bar' are
2428 Note that when creating a relative link using
2429 <prgn>ln</prgn> it is not necessary for the target of the
2430 link to exist relative to the working directory you're
2431 running <prgn>ln</prgn> from; nor is it necessary to
2432 change directory to the directory where the link is to be
2433 made. Simply include the string that should appear as the
2434 target of the link (this will be a pathname relative to
2435 the directory in which the link resides) as the first
2436 argument to <prgn>ln</prgn>.</p>
2439 For example, in your <prgn>Makefile</prgn> or
2440 <tt>debian/rules</tt>, do things like:
2442 ln -fs gcc $(prefix)/bin/cc
2443 ln -fs gcc debian/tmp/usr/bin/cc
2444 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2445 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2449 A symbolic link pointing to a compressed file should
2450 always have the same file extension as the referenced
2451 file. (For example, if a file `<tt>foo.gz</tt>' is
2452 referenced by a symbolic link, the filename of the link
2453 has to end with `<tt>.gz</tt>' too, as in
2454 `bar.gz.')</p></sect>
2458 <heading>Device files</heading>
2461 No package may include device files in the package file
2465 If a package needs any special device files that are not
2466 included in the base system, it has to call
2467 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2468 after asking the user for permission to do so.</p>
2471 No package should remove any device files in the
2472 <tt>postrm</tt> or any other script. This is left to the
2473 system administrator.</p>
2476 Debian uses the serial devices
2477 <tt>/dev/tty*</tt>. Programs using the old
2478 <tt>/dev/cu*</tt> devices should be changed to use
2479 <tt>/dev/tty*</tt>.</p>
2482 <sect id="config files">
2483 <heading>Configuration files</heading>
2485 <heading>Definitions</heading>
2488 <tag>configuration file</tag>
2490 A file that affects the operation of program, or
2491 provides site- or host-specific information, or
2492 otherwise customizes the behavior of program.
2493 Typically, configuration files are intended to be
2494 modified by the system administrator (if needed or
2495 desired) to conform to local policy or provide more
2496 useful site-specific behavior.</p>
2499 <tag><tt>conffile</tt></tag>
2501 A file listed in a package's <tt>conffiles</tt>
2502 file, and is treated specially by <prgn>dpkg</prgn>
2503 (see the <em>Debian Packaging Manual</em>).</p>
2509 The distinction between these two is important; they are
2510 not interchangeable concepts. Almost all
2511 <tt>conffiles</tt> are configuration files, but many
2512 configuration files are not <tt>conffiles</tt>.</p>
2515 Note that a script that embeds configuration information
2516 (such as most of the files in <tt>/etc/init.d</tt> and
2517 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2518 configuration file and should be treated as such.</p>
2522 <heading>Location</heading>
2524 Any configuration files created or used by your package
2525 should reside in <tt>/etc</tt>. If there are several you
2526 should consider creating a subdirectory of <tt>/etc</tt>
2527 named after your package.</p>
2530 If your packages creates or uses configuration files
2531 outside of <tt>/etc</tt>, and it is not feasible to modify
2532 the package to use the <tt>/etc</tt>, you should still put
2533 the files in <tt>/etc</tt> and create symbolic links to
2534 those files from the location that the package
2539 <heading>Behavior</heading>
2541 Configuration file handling must conform to the following
2545 <p>local changes must be preserved during a package
2549 <p>configuration files should be preserved when the
2550 package is removed, and only deleted when the
2551 package is purged.</p>
2556 The easy way to achieve this behavior is to make the
2557 configuration file a <tt>conffile</tt>. This is
2558 appropriate if it is possible to distribute a default
2559 version that will work for most installations, although
2560 some system administrators may choose to modify it. This
2561 implies that the default version will be part of the
2562 package distribution, and must not be modified by the
2563 maintainer scripts during installation (or at any other
2567 In order to ensure that local changes are preserved
2568 correctly, no package may contain or make hard links to
2572 Rationale: There are two problems with hard links.
2573 The first is that some editors break the link while
2574 editing one of the files, so that the two files may
2575 unwittingly become different. The second is that
2576 <prgn>dpkg</prgn> might break the hard link while
2577 upgrading <tt>conffile</tt>s.
2582 The other way to do it is to via the maintainer scripts.
2583 In this case, the configuration file must not be listed as
2584 a <tt>conffile</tt> and must not be part of the package
2585 distribution. If the existence of a file is required for
2586 the package to be sensibly configured it is the
2587 responsibility of the package maintainer to write scripts
2588 which correctly create, update, maintain and
2589 remove-on-purge the file. These scripts must be idempotent
2590 (i.e. must work correctly if <prgn>dpkg</prgn> needs to
2591 re-run them due to errors during installation or removal),
2592 must cope with all the variety of ways <prgn>dpkg</prgn>
2593 can call maintainer scripts, must not overwrite or
2594 otherwise mangle the user's configuration without asking,
2595 must not ask unnecessary questions (particularly during
2596 upgrades), and otherwise be good citizens.</p>
2599 The scripts need not configure every possible option for
2600 the package, but only those necessary to get the package
2601 running on a given system. Ideally the sysadmin should not
2602 have to do any configuration other than that done
2603 (semi-)automatically by the <tt>postinst</tt> script.</p>
2606 A common practice is to create a script called
2607 <tt><var>package</var>-configure</tt> and have the
2608 package's <tt>postinst</tt> call it if and only if the
2609 configuration file does not already exist. In certain
2610 cases it is useful for there to be an example or template
2611 file which the maintainer scripts use. Such files should
2612 be in <tt>/usr/share/doc</tt> if they are examples or
2613 <tt>/usr/lib</tt> if they are templates, and should be
2614 perfectly ordinary <prgn>dpkg</prgn>-handled files
2615 (<em>not</em> <tt>conffiles</tt>).</p>
2618 These two styles of configuration file handling <em>must
2619 not be mixed</em>, for that way lies madness:
2620 <prgn>dpkg</prgn> will ask about overwriting the file
2621 every time the package is upgraded.</p>
2626 <heading>Sharing configuration files</heading>
2628 Only packages that are tagged <em>conflicting</em> with
2629 each other may specify the same file as
2630 <tt>conffile</tt>.</p>
2633 The maintainer scripts should not alter the conffile of
2634 <em>any</em> package, including the one the scripts belong
2638 If two or more packages use the same configuration file
2639 and it is reasonable for both to be installed at the same
2640 time, one of these packages must be defined as
2641 <em>owner</em> of the configuration file, i.e. it will be
2642 the package to list that distributes the file and lists it
2643 as a <tt>conffile</tt>. Other packages that use the
2644 configuration file should depend on the owning package if
2645 they require the configuration file to operate. If the
2646 other package will use the configuration file if present,
2647 but is capable of operating without it, no dependency need
2651 If it is desirable for two or more related packages to
2652 share a configuration file <em>and</em> for all of the
2653 related packages to be able to modify that configuration
2654 file, then the following should done:
2658 have one of the related packages (the "core"
2659 package) manage the configuration file with
2660 maintainer scripts as described in the previous
2664 the core package should also provide a program that
2665 the other packages may use to modify the
2666 configuration file.</p>
2670 the related packages must use the provided program
2671 to make any modifications to the configuration file.
2672 They should either depend on the core package to
2673 guarantee that the configuration modifier program is
2674 available or accept gracefully that they cannot
2675 modify the configuration file if it is not.</p>
2680 Sometimes it's appropriate to create a new package which
2681 provides the basic infrastructure for the other packages
2682 and which manages the shared configuration files. (Check
2683 out the <tt>sgml-base</tt> package as an example.)</p>
2687 <heading>User configuration files ("dotfiles")</heading>
2690 Files in <tt>/etc/skel</tt> will automatically be copied
2691 into new user accounts by <prgn>adduser</prgn>. They
2692 should not be referenced there by any program.</p>
2695 Therefore, if a program needs a dotfile to exist in
2696 advance in <tt>$HOME</tt> to work sensibly that dotfile
2697 should be installed in <tt>/etc/skel</tt> (and listed in
2698 conffiles, if it is not generated and modified dynamically
2699 by the package's installation scripts).</p>
2702 However, programs that require dotfiles in order to
2703 operate sensibly (dotfiles that they do not create
2704 themselves automatically, that is) are a bad thing, and
2705 programs should be configured by the Debian default
2706 installation as close to normal as possible.</p>
2709 Therefore, if a program in a Debian package needs to be
2710 configured in some way in order to operate sensibly that
2711 configuration should be done in a site-wide global
2712 configuration file elsewhere in <tt>/etc</tt>. Only if the
2713 program doesn't support a site-wide default configuration
2714 and the package maintainer doesn't have time to add it
2715 should a default per-user file be placed in
2716 <tt>/etc/skel</tt>.</p>
2719 <tt>/etc/skel</tt> should be as empty as we can make it.
2720 This is particularly true because there is no easy
2721 mechanism for ensuring that the appropriate dotfiles are
2722 copied into the accounts of existing users when a package
2728 <heading>Log files</heading>
2730 The traditional approach to log files has been to set up ad
2731 hoc log rotation schemes using simple shell scripts and
2732 cron. While this approach is highly customizable, it
2733 requires quite a lot of sysadmin work. Even though the
2734 original Debian system helped a little by automatically
2735 installing a system which can be used as a template, this
2736 was deemed not enough.
2740 A better scheme is to use logrotate, a GPL'd program
2741 developed by Red Hat, which centralizes log management. It
2742 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2743 and a directory where packages can drop logrotation info
2744 (<tt>/etc/logrotate.d</tt>).
2748 Log files should usually be named
2749 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2750 log files, or need a separate directory for permissions
2751 reasons (<tt>/var/log</tt> is writable only by
2752 <tt>root</tt>), you should usually create a directory named
2753 <tt>/var/log/<var>package</var></tt>.</p>
2756 Make sure that any log files are rotated occasionally so
2757 that they don't grow indefinitely; the best way to do this
2758 is to drop a script into the directory
2759 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2760 logrotate. Here is a good example for a logrotate config
2761 file (for more information see <manref name="logrotate"
2769 /etc/init.d/foo force-reload
2773 Which rotates all files under `/var/log/foo', saves 12
2774 compressed generations, and sends a HUP signal at the end of
2780 Make sure that any log files are removed when the package is
2781 purged (but not when it is only removed), by checking the
2782 argument to the <tt>postrm</tt> script (see the <em>Debian
2783 Packaging Manual</em> for details).</p>
2788 <heading>Permissions and owners</heading>
2791 The rules in this section are guidelines for general use.
2792 If necessary you may deviate from the details below.
2793 However, if you do so you must make sure that what is done
2794 is secure and you must try to be as consistent as possible
2795 with the rest of the system. You should probably also
2796 discuss it on <prgn>debian-devel</prgn> first.</p>
2799 Files should be owned by <tt>root.root</tt>, and made
2800 writable only by the owner and universally readable (and
2801 executable, if appropriate).</p>
2804 Directories should be mode 755 or (for group-writability)
2805 mode 2775. The ownership of the directory should be
2806 consistent with its mode--if a directory is mode 2775, it
2807 should be owned by the group that needs write access to
2811 Setuid and setgid executables should be mode 4755 or 2755
2812 respectively, and owned by the appropriate user or group.
2813 They should not be made unreadable (modes like 4711 or
2814 2711 or even 4111); doing so achieves no extra security,
2815 because anyone can find the binary in the freely available
2816 Debian package--it is merely inconvenient. For the same
2817 reason you should not restrict read or execute permissions
2818 on non-set-id executables.</p>
2821 Some setuid programs need to be restricted to particular
2822 sets of users, using file permissions. In this case they
2823 should be owned by the uid to which they are set-id, and
2824 by the group which should be allowed to execute them.
2825 They should have mode 4754; there is no point in making
2826 them unreadable to those users who must not be allowed to
2830 Do not arrange that the system administrator can only
2831 reconfigure the package to correspond to their local
2832 security policy by changing the permissions on a binary.
2833 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2834 to conffiles and other similar objects) have their
2835 permissions reset to the distributed permissions when the
2836 package is reinstalled. Instead you should consider (for
2837 example) creating a group for people allowed to use the
2838 program(s) and making any setuid executables executable
2839 only by that group.</p>
2842 If you need to create a new user or group for your package
2843 there are two possibilities. Firstly, you may need to
2844 make some files in the binary package be owned by this
2845 user or group, or you may need to compile the user or
2846 group id (rather than just the name) into the binary
2847 (though this latter should be avoided if possible). In
2848 this case you need a statically allocated id.</p>
2851 You must ask for a user or group id from the base system
2852 maintainer, and must not release the package until you
2853 have been allocated one. Once you have been allocated one
2854 you must make the package depend on a version of the base
2855 system with the id present in <tt>/etc/passwd</tt> or
2856 <tt>/etc/group</tt>, or alternatively arrange for your
2857 package to create the user or group itself with the
2858 correct id (using <tt>adduser</tt>) in its pre- or
2859 post-installation script (the latter is to be preferred if
2860 it is possible).</p>
2863 On the other hand, the program may able to determine the
2864 uid or gid from the group name at runtime, so that a
2865 dynamic id can be used. In this case you must choose an
2866 appropriate user or group name, discussing this on
2867 <prgn>debian-devel</prgn> and checking with the base
2868 system maintainer that it is unique and that they do not
2869 wish you to use a statically allocated id instead. When
2870 this has been checked you must arrange for your package to
2871 create the user or group if necessary using
2872 <prgn>adduser</prgn> in the pre- or post-installation
2873 script (again, the latter is to be preferred if it is
2877 Note that changing the numeric value of an id associated with a name
2878 is very difficult, and involves searching the file system for all
2879 appropriate files. You need to think carefully whether a static or
2880 dynamic id is required, since changing your mind later will cause
2886 <heading>Customized programs</heading>
2888 <sect id="arch-spec">
2889 <heading>Architecture specification strings</heading>
2892 If a program needs to specify an <em>architecture specification
2893 string</em> in some place, the following format has to be used:
2895 <arch>-<os>
2897 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2898 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2899 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2900 operating system. .</p>
2902 Note, that we don't want to use `<arch>-debian-linux'
2903 to apply to the rule `architecture-vendor-os' since this
2904 would make our programs incompatible to other Linux
2905 distributions. Also note, that we don't use
2906 `<arch>-unknown-linux', since the `unknown' does not
2907 look very good.</p></sect>
2911 <heading>Daemons</heading>
2914 The configuration files <tt>/etc/services</tt>,
2915 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2916 by the <prgn>netbase</prgn> package and may not be modified
2917 by other packages.</p>
2920 If a package requires a new entry in one of these files, the
2921 maintainer has to get in contact with the
2922 <prgn>netbase</prgn> maintainer, who will add the entries
2923 and release a new version of the <prgn>netbase</prgn>
2927 The configuration file <tt>/etc/inetd.conf</tt> may be
2928 modified by the package's scripts only via the
2929 <prgn>update-inetd</prgn> script or the
2930 <prgn>DebianNet.pm</prgn> Perl module.</p>
2933 If a package wants to install an example entry into
2934 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2935 exactly one hash character (<tt>#</tt>). Such lines are
2936 treated as `commented out by user' by the
2937 <prgn>update-inetd</prgn> script and are not changed or
2938 activated during a package updates.</p></sect>
2942 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2945 Some programs need to create pseudo-ttys. This should be done
2946 using Unix98 ptys if the C library supports it. The resulting
2947 program must not be installed setuid root, unless that
2948 is required for other functionality.
2952 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2953 <tt>/var/log/lastlog</tt> must be installed writeable by
2954 group utmp. Programs who need to modify those files must
2955 be installed install setgid utmp.
2960 <heading>Editors and pagers</heading>
2963 Some programs have the ability to launch an editor or pager
2964 program to edit or display a text document. Since there are
2965 lots of different editors and pagers available in the Debian
2966 distribution, the system administrator and each user should
2967 have the possibility to choose his/her preferred editor and
2971 In addition, every program should choose a good default
2972 editor/pager if none is selected by the user or system
2976 Thus, every program that launches an editor or pager has to
2977 use the EDITOR or PAGER environment variables to determine
2978 the editor/pager the user wants to get started. If these
2979 variables are not set, the programs <tt>/usr/bin/editor</tt>
2980 and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
2983 These two files are managed through `alternatives.' That is,
2984 every package providing an editor or pager has to call the
2985 <prgn>update-alternatives</prgn> script to register these
2989 If it is very hard to adapt a program to make us of the
2990 EDITOR and PAGER variable, that program should be configured
2991 to use <tt>/usr/bin/sensible-editor</tt> and
2992 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
2993 respectively. These are two scripts provided in the Debian
2994 base system that check the EDITOR and PAGER variables and
2995 launches the appropriate program or falls back to
2996 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
3000 A program may also use the VISUAL environment variable to
3001 determine the user's choice of editor. If it exists, it
3002 should take precedence over EDITOR. This is in fact what
3003 <tt>/usr/bin/sensible-editor</tt> does.</p>
3006 Since the Debian base system already provides an editor and
3007 a pager program, there is no need for a package to depend on
3008 `editor' and `pager', nor is it necessary for a package to
3009 provide such virtual packages.</p></sect>
3012 <sect id="web-appl">
3013 <heading>Web servers and applications</heading>
3016 This section describes the locations and URLs that have to
3017 be used by all web servers and web application in the Debian
3023 <p>Cgi-bin executable files are installed in the
3026 /usr/lib/cgi-bin/<cgi-bin-name>
3028 and can be referred to as
3030 http://localhost/cgi-bin/<cgi-bin-name>
3031 </example></p></item>
3034 <item><p>Access to html documents</p>
3037 Html documents for a package are stored in
3038 <tt>/usr/share/doc/<var>package</var></tt> but should
3039 be accessed via symlinks as
3040 <tt>/usr/doc/<var>package</var></tt><footnote> for
3041 backward compatibility, see <ref id="usrdoc"></footnote>
3042 and can be referred to as
3044 http://localhost/doc/<package>/<filename>
3045 </example></p></item>
3048 <item><p>Web Document Root</p>
3051 Web Applications should try to avoid storing files in
3052 the Web Document Root. Instead use the
3053 /usr/share/doc/<package> directory for documents and
3054 register the Web Application via the menu package. If
3055 access to the web-root is unavoidable then use
3059 as the Document Root. This might be just a
3060 symbolic link to the location where the sysadmin has
3061 put the real document root.</p>
3064 </enumlist></p></sect>
3068 <heading>Mail transport agents</heading>
3071 Debian packages which process electronic mail, whether
3072 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
3073 <em>must</em> make sure that they are compatible with the
3074 configuration decisions below. Failure to do this may
3075 result in lost mail, broken <tt>From:</tt> lines, and other
3076 serious brain damage!</p>
3079 The mail spool is <tt>/var/spool/mail</tt> and the interface
3080 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3081 per the FHS). The mail spool is part of the base system
3082 and not part of the MTA package.</p>
3085 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3086 programs (like IMAP daemons) have to lock the mailbox in a
3087 NFS-safe way. This means that <tt>fcntl()</tt> locking has
3088 to be combined with dot locking. To avoid dead locks, a
3089 program has to use <tt>fcntl()</tt> first and dot locking
3090 after this or alternatively implement the two locking
3091 methods in a non blocking way<footnote>
3093 If it is not possible to establish both locks, the
3094 system shouldn't wait for the second lock to be
3095 established, but remove the first lock, wait a (random)
3096 time, and start over locking again.</p>
3097 </footnote>. Using the functions <tt>maillock</tt> and
3098 <tt>mailunlock</tt> provided by the
3099 <tt>liblockfile*</tt><footnote>
3101 <tt>liblockfile</tt> version >>1.01</p>
3102 </footnote> packages is the recommended way to realize this.
3106 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3107 unless the user has chosen otherwise. A MUA may remove a
3108 mailbox (unless it has nonstandard permissions) in which
3109 case the MTA or another MUA must recreate it if needed.
3110 Mailboxes must be writable by group mail.</p>
3113 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
3114 be setgid mail to do the locking mentioned above (and
3115 obviously need to avoid accessing other users' mailboxes
3116 using this privilege).</p>
3119 <tt>/etc/aliases</tt> is the source file for the system mail
3120 aliases (e.g., postmaster, usenet, etc.)--it is the one
3121 which the sysadmin and <tt>postinst</tt> scripts may edit.
3122 After <tt>/etc/aliases</tt> is edited the program or human
3123 editing it must call <prgn>newaliases</prgn>. All MTA
3124 packages should come with a <prgn>newaliases</prgn> program,
3125 even if it does nothing, but older MTA packages do not do
3126 this so programs should not fail if <prgn>newaliases</prgn>
3127 cannot be found.</p>
3130 The convention of writing <tt>forward to
3131 <var>address</var></tt> in the mailbox itself is not
3132 supported. Use a <tt>.forward</tt> file instead.</p>
3135 The location for the <prgn>rmail</prgn> program used by UUCP
3136 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
3137 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3138 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
3142 If you need to know what name to use (for example) on
3143 outgoing news and mail messages which are generated locally,
3144 you should use the file <tt>/etc/mailname</tt>. It will
3145 contain the portion after the username and <tt>@</tt> (at)
3146 sign for email addresses of users on the machine (followed
3150 A package should check for the existence of this file. If
3151 it exists it should use it without comment. (An MTA's
3152 prompting configuration script may wish to prompt the user
3153 even if it finds this file exists.) If it does not exist it
3154 should prompt the user for the value and store it in
3155 <tt>/etc/mailname</tt> as well as using it in the package's
3156 configuration. The prompt should make it clear that the
3157 name will not just be used by that package. For example, in
3158 this situation the INN package says:
3160 Please enter the `mail name' of your system. This is the
3161 hostname portion of the address to be shown on outgoing
3162 news and mail messages. The default is
3163 <var>syshostname</var>, your system's host name. Mail
3164 name [`<var>syshostname</var>']:
3166 where <var>syshostname</var> is the output of <tt>hostname
3167 --fqdn</tt>.</p></sect>
3171 <heading>News system configuration</heading>
3174 All the configuration files related to the NNTP (news)
3175 servers and clients should be located under
3176 <tt>/etc/news</tt>.</p>
3179 There are some configuration issues that apply to a number
3180 of news clients and server packages on the machine. These
3184 <tag>/etc/news/organization</tag>
3185 <item><p>A string which shall appear as the
3186 organization header for all messages posted
3187 by NNTP clients on the machine</p></item>
3189 <tag>/etc/news/server</tag>
3190 <item><p>Contains the FQDN of the upstream NNTP
3191 server, or localhost if the local machine is
3192 an NNTP server.</p></item>
3195 Other global files may be added as required for cross-package news
3196 configuration.</p></sect>
3200 <heading>Programs for the X Window System</heading>
3203 Some programs can be configured with or without support for the X
3204 Window System. Typically, binaries produced with support for X
3205 will need the X shared libraries to run.
3209 Such programs should be configured <em>with</em> X support,
3210 and should declare a dependency on <tt>xlib6g</tt> (which
3211 contains X shared libraries). Users who wish to use the
3212 program can install just the relatively small
3213 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
3214 not need to install the whole of X.
3216 <p>Note: With the release of the new X window System
3217 version (4.X), there probably shall be a sweeping change
3218 in the X Window System Policy in the future.</p>
3223 Do not create two versions (one with X support and one
3224 without) of your package.</p>
3227 <em>Packages which provide an X server</em> that, directly or
3228 indirectly, communicates with real input and display hardware
3229 should declare in their control data that they provide the
3230 virtual package <tt>xserver</tt>.
3233 Rationale: implement current practice, and provide an
3234 actual policy for usage of the "xserver" virtual package
3235 which appears in the virtual packages list.
3236 In a nutshell, X servers that interface directly with
3237 the display and input hardware or via another subsystem
3238 (e.g., GGI) should provide xserver. Things like Xvfb,
3239 Xnest, and Xprt should not.
3245 <em>Packages that provide a terminal emulator</em> for the X
3246 Window System which support a terminal type with a terminfo
3247 description provided in the <tt>ncurses-base</tt> package
3248 should declare in their control data that they provide the
3249 virtual package <tt>x-terminal-emulator</tt>. They should
3250 also register themselves as an alternative for
3251 <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
3256 <em>Packages that provide window managers</em> should declare in
3257 their control data that they provide the virtual package
3258 <tt>x-window-manager</tt>. They should also register themselves as an
3259 alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
3260 calculated as follows:
3262 <item>Start with a priority of 20.</item>
3263 <item>If the window manager supports the Debian menu system,
3264 add 20 points if this support is available in the
3265 package's default configuration (i.e., no
3266 configuration files belonging to the system or user
3267 have to be edited to activate the feature); if
3268 configuration files must be modified, add only 10
3270 <item>If the window manager permits the X session to be
3271 restarted using a <em>different</em> window manager
3272 (without killing the X server) in its default
3273 configuration, add 10 points; otherwise add
3279 <em>Packages that provide fonts for the X Window System</em>
3280 must do a number of things to ensure that they are both
3281 available without modification of the X or font server
3282 configuration, and that they do not corrupt files used by
3283 other font packages to register information about themselves.
3286 Fonts of any type supported by the X Window System
3287 should be be in a separate binary package from any
3288 executables, libraries, or documentation (except that
3289 specific to the fonts shipped); if a program or
3290 library is <em>unusable</em> without one or more
3291 specific fonts, the package containing the program or
3292 library should declare a dependency on the package(s)
3293 containing the font(s) it requires.
3296 BDF fonts should be converted to PCF fonts with the
3297 <tt>bdftopcf</tt> utility (available in the
3298 <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
3299 placed in a directory that corresponds to their
3303 100 dpi fonts should be placed in
3304 <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
3307 75 dpi fonts should be placed in
3308 <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
3311 Character-cell fonts, cursor fonts, and other
3312 low-resolution fonts should be placed in
3313 <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
3318 Speedo fonts should be placed in
3319 <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
3322 Type 1 fonts should be placed in
3323 <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
3324 metric files are available, they may be placed here as
3328 Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
3329 other than those listed above should be neither created nor
3330 used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
3331 excepted for historical reasons, but installation of files into
3332 these directories remains discouraged.)
3335 Font packages may, instead of placing files directly in
3336 the X font directories listed above, provide symbolic links in
3337 the font directory which point to the files' actual location
3338 in the filesystem. Such a location should comply with the
3342 Font packages should not contain both 75dpi and 100dpi
3343 versions of a font. If both are available, they should be
3344 provided in separate binary packages with "-75dpi" or "-100dpi"
3345 appended to the names of the packages containing the
3346 corresponding fonts.
3349 Fonts destined for the <tt>misc</tt> subdirectory should
3350 not be included in the same package as 75dpi or 100dpi fonts;
3351 instead, they should be provided in a separate package with
3352 "-misc" appended to its name.
3355 Font packages <em>must not</em> provide the files
3356 <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
3357 <tt>fonts.scale</tt> in a font directory.
3360 <tt>fonts.dir</tt> files must not be provided at
3364 <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
3365 files, if needed, should be provided in the
3367 <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
3368 where <em>fontdir</em> is the name of the
3370 <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
3371 package's corresponding fonts are stored (e.g.,
3372 <tt>75dpi</tt> or <tt>misc</tt>),
3373 <em>package</em> is the name of the package that
3374 provides these fonts, and <em>extension</em> is
3375 either <tt>scale</tt> or <tt>alias</tt>,
3376 whichever corresponds to the file
3382 Font packages must declare a dependency on
3383 <tt>xbase-clients</tt> and, in the package
3384 post-installation and post-removal scripts, invoke the
3385 <tt>mkfontdir</tt> command on each directory into
3386 which they installed fonts.
3389 Font packages that provide one or more
3390 <tt>fonts.scale</tt> files as described above must declare a
3391 versioned dependency on <tt>xbase-clients (>=
3392 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
3393 directory into which they installed fonts
3394 <em>before</em> invoking <tt>mkfontdir</tt> on that
3395 directory. This invocation must occur in both the
3396 post-installation and post-removal scripts.
3399 Font packages that provide one or more
3400 <tt>fonts.alias</tt> files as described above must
3401 declare a versioned dependency on <tt>xbase-clients
3402 (>= 3.3.3.1-5)</tt> and, in the package
3403 post-installation and post-removal scripts, invoke
3404 <tt>update-fonts-alias</tt> on each directory into
3405 which they installed fonts.
3408 Font packages must not provide alias names for the
3409 fonts they include which collide with alias names already in
3410 use by fonts already packaged.
3413 Font packages must not provide fonts with the same XLFD
3414 registry name as another font already packaged.
3420 <em>Application defaults</em> files must be installed in the
3421 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They should
3422 not be registered as <em>conffile</em>s or otherwise treated as
3423 configuration files. Customization of programs' X resources may
3424 be supported with the provision of a file with the same name as
3425 that of the package placed in the <tt>/etc/X11/Xresources/</tt>
3426 directory, which should be registered as a <em>conffile</em>.
3427 <em>Important:</em> packages that install files into the
3428 <tt>/etc/X11/Xresources/</tt> directory <em>must</em> declare a
3429 conflict with <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is
3430 not done it is possible for the installing package to destroy a
3431 previously-existing <tt>/etc/X11/Xresources</tt> <em>file</em>
3432 which had been customized by the system administrator.
3434 <p>Rationale: clarifies the language to properly
3435 address the package maintainer, not the system
3436 administrator, as to how to manage
3437 /etc/X11/Xresources.</p>
3443 <em>Packages using the X Window System should abide by the FHS
3444 standard whenever possible</em>; they should install binaries,
3445 libraries, manual pages, and other files in FHS-mandated
3446 locations wherever possible. This means that files should
3447 not be installed into <tt>/usr/X11R6/bin/</tt>,
3448 <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
3449 this is necessary for the package to operate properly.
3450 Configuration files for window managers and display managers
3451 should be placed in a subdirectory of <tt>/etc/X11/</tt>
3452 corresponding to the package name due to these programs'
3453 tight integration with the mechanisms of the X Window
3454 System. Application-level programs should use the
3455 <tt>/etc/</tt> directory unless otherwise mandated by
3456 policy. The installation of files into subdirectories of
3457 <tt>/usr/X11R6/include/X11/</tt> and
3458 <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
3459 package maintainers should determine if subdirectories of
3460 <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
3461 instead (symlinks from the X11R6 directories to
3462 FHS-compliant locations is encouraged if the program is not
3463 easily configured to look elsewhere for its files).
3464 Packages must not provide -- or install files into -- the
3465 directories <tt>/usr/bin/X11/</tt>,
3466 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
3467 Files within a package should, however, make reference to
3468 these directories, rather than their X11R6-named
3469 counterparts <tt>/usr/X11R6/bin/</tt>,
3470 <tt>/usr/X11R6/include/X11/</tt>, and
3471 <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
3472 referred to have not been moved to FHS-compliant locations.
3476 <em>Programs that require the non-DFSG-compliant OSF/Motif
3477 library</em> should be compiled against and tested with
3478 LessTif (a free re-implementation of Motif) instead. If the
3479 maintainer judges that the program or programs do not work
3480 sufficiently well with LessTif to be distributed and
3481 supported, but do so when compiled against Motif, then two
3482 versions of the package should be created; one linked
3483 statically against Motif and with <tt>-smotif</tt> appended
3484 to the package name, and one linked dynamically against
3485 Motif and with <tt>-dmotif</tt> appended to the package
3486 name. Both Motif-linked versions are dependent upon
3487 non-DFSG-compliant software and thus cannot be uploaded to
3488 the main distribution; if the software is itself
3489 DFSG-compliant it may be uploaded to the contrib
3490 distribution. While known existing versions of OSF/Motif
3491 permit unlimited redistribution of binaries linked against
3492 the library (whether statically or dynamically), it is the
3493 package maintainer's responsibility to determine whether
3494 this is permitted by the license of the copy of OSF/Motif in
3495 his or her possession.
3501 <heading>Emacs lisp programs</heading>
3504 Please refer to the `Debian Emacs Policy' (documented in
3505 <tt>debian-emacs-policy.gz</tt> of the
3506 <prgn>emacsen-common</prgn> package) for details of how to
3507 package emacs lisp programs.</p></sect>
3511 <heading>Games</heading>
3514 The permissions on /var/games are 755
3515 <tt>root.root</tt>.</p>
3518 Each game decides on its own security policy.</p>
3521 Games which require protected, privileged access to
3522 high-score files, savegames, etc., must be made
3523 set-<em>group</em>-id (mode 2755) and owned by
3524 <tt>root.games</tt>, and use files and directories with
3525 appropriate permissions (770 <tt>root.games</tt>, for
3526 example). They must <em>not</em> be made
3527 set-<em>user</em>-id, as this causes security problems. (If
3528 an attacker can subvert any set-user-id game they can
3529 overwrite the executable of any other, causing other players
3530 of these games to run a Trojan horse program. With a
3531 set-group-id game the attacker only gets access to less
3532 important game data, and if they can get at the other
3533 players' accounts at all it will take considerably more
3537 Some packages, for example some fortune cookie programs, are
3538 configured by the upstream authors to install with their
3539 data files or other static information made unreadable so
3540 that they can only be accessed through set-id programs
3541 provided. Do not do this in a Debian package: anyone can
3542 download the <tt>.deb</tt> file and read the data from it,
3543 so there is no point making the files unreadable. Not
3544 making the files unreadable also means that you don't have
3545 to make so many programs set-id, which reduces the risk of a
3549 As described in the FHS, binaries of games should be
3550 installed in the directory <tt>/usr/games</tt>. This also
3551 applies to games that use the X Window System. Manual pages
3552 for games (X and non-X games) should be installed in
3553 <tt>/usr/share/man/man6</tt>.</p>
3557 <chapt><heading>Documentation</heading>
3561 <heading>Manual pages</heading>
3564 You must install manual pages in <prgn>nroff</prgn> source
3565 form, in appropriate places under <tt>/usr/share/man</tt>. You
3566 should only use sections 1 to 9 (see the FHS for more
3567 details). You must <em>not</em> install a preformatted `cat
3571 If no manual page is available for a particular program,
3572 utility or function and this is reported as a bug on
3573 debian-bugs, a symbolic link from the requested manual page
3574 to the <manref name="undocumented" section="7"> manual page
3575 should be provided. This symbolic link can be created from
3576 <tt>debian/rules</tt> like this:
3578 ln -s ../man7/undocumented.7.gz \
3579 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3581 This manpage claims that the lack of a manpage has been
3582 reported as a bug, so you may only do this if it really has
3583 (you can report it yourself, if you like). Do not close the
3584 bug report until a proper manpage is available.</p>
3587 You may forward a complaint about a missing manpage to the
3588 upstream authors, and mark the bug as forwarded in the
3589 Debian bug tracking system. Even though the GNU Project do
3590 not in general consider the lack of a manpage to be a bug,
3591 we do--if they tell you that they don't consider it a bug
3592 you should leave the bug in our bug tracking system open
3596 Manual pages should be installed compressed using <tt>gzip
3600 If one manpage needs to be accessible via several names it
3601 is better to use a symbolic link than the <tt>.so</tt>
3602 feature, but there is no need to fiddle with the relevant
3603 parts of the upstream source to change from <tt>.so</tt> to
3604 symlinks--don't do it unless it's easy. Do not create hard
3605 links in the manual page directories, and do not put
3606 absolute filenames in <tt>.so</tt> directives. The filename
3607 in a <tt>.so</tt> in a manpage should be relative to the
3608 base of the manpage tree (usually
3609 <tt>/usr/share/man</tt>).</p></sect>
3613 <heading>Info documents</heading>
3616 Info documents should be installed in <tt>/usr/share/info</tt>.
3617 They should be compressed with <tt>gzip -9</tt>.</p>
3620 Your package must call <prgn>install-info</prgn> to update the Info
3622 file, in its post-installation script:
3624 install-info --quiet --section Development Development \
3625 /usr/share/info/foobar.info
3629 It is a good idea to specify a section for the location of
3630 your program; this is done with the <tt>--section</tt>
3631 switch. To determine which section to use, you should look
3632 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3633 relevant (or create a new section if none of the current
3634 sections are relevant). Note that the <tt>--section</tt>
3635 flag takes two arguments; the first is a regular expression
3636 to match (case-insensitively) against an existing section,
3637 the second is used when creating a new one.</p>
3640 You must remove the entries in the pre-removal script:
3642 install-info --quiet --remove /usr/share/info/foobar.info
3646 If <prgn>install-info</prgn> cannot find a description entry
3647 in the Info file you will have to supply one. See <manref
3648 name="install-info" section="8"> for details.</p>
3652 <heading>Additional documentation</heading>
3655 Any additional documentation that comes with the package can
3656 be installed at the discretion of the package maintainer.
3657 Text documentation should be installed in a directory
3658 <tt>/usr/share/doc/<var>package</var></tt>, where
3659 <var>package</var> is the name of the package, and
3660 compressed with <tt>gzip -9</tt> unless it is small.</p>
3663 If a package comes with large amounts of documentation which
3664 many users of the package will not require you should create
3665 a separate binary package to contain it, so that it does not
3666 take up disk space on the machines of users who do not need
3667 or want it installed.</p>
3670 It is often a good idea to put text information files
3671 (<tt>README</tt>s, changelogs, and so forth) that come with
3672 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3673 in the binary package. However, you don't need to install
3674 the instructions for building and installing the package, of
3679 <heading>Accessing the documentation</heading>
3682 Former Debian releases placed all additional documentation
3683 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3685 <tt>/usr/share/doc/<var>package</var></tt>, each package
3686 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3687 that points to the new location of its documentation in
3688 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3689 symlinks will be removed in the future, but they have to be
3690 there for compatibility reasons until all packages have
3691 moved and the policy is changed accordingly.</footnote>.
3692 The symlink must be created when the package is installed;
3693 it cannot be contained in the package itself due to problems
3694 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3695 this is to put the following in the package's
3696 <prgn>postinst</prgn>:
3698 if [ "$1" = "configure" ]; then
3699 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3700 -a -d /usr/share/doc/#PACKAGE# ]; then
3701 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3705 And the following in the package's <prgn>prerm</prgn>:
3707 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3708 -a -L /usr/doc/#PACKAGE# ]; then
3709 rm -f /usr/doc/#PACKAGE#
3716 <heading>Preferred documentation formats</heading>
3719 The unification of Debian documentation is being carried out
3723 If your package comes with extensive documentation in a
3724 mark up format that can be converted to various other formats
3725 you should if possible ship HTML versions in a binary
3726 package, in the directory
3727 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3730 <p>The rationale: The important thing here is that HTML
3731 docs should be available in <em>some</em> package, not
3732 necessarily in the main binary package, though. </p>
3737 Other formats such as PostScript may be provided at your
3741 <sect id="copyrightfile">
3742 <heading>Copyright information</heading>
3745 Every package must be accompanied by a verbatim copy of its
3746 copyright and distribution license in the file
3747 /usr/share/doc/<package-name>/copyright. This file must
3748 neither be compressed nor be a symbolic link.</p>
3751 In addition, the copyright file must say where the upstream
3752 sources (if any) were obtained, and explain briefly what
3753 modifications were made in the Debian version of the package
3754 compared to the upstream one. It must name the original
3755 authors of the package and the Debian maintainer(s) who were
3756 involved with its creation.</p>
3759 /usr/share/doc/<package-name> may be a symbolic link to a
3760 directory in /usr/share/doc only if two packages both come from
3761 the same source and the first package has a "Depends"
3762 relationship on the second. These rules are important
3763 because copyrights must be extractable by mechanical
3767 Packages distributed under the UCB BSD license, the Artistic
3768 license, the GNU GPL, and the GNU LGPL should refer to the
3769 files /usr/share/common-licenses/BSD,
3770 /usr/share/common-licenses/Artistic,
3771 /usr/share/common-licenses/GPL, and
3772 /usr/share/common-licenses/LGPL.
3775 Why "licenses" and not "copyright"? Because
3776 <tt>/usr/doc/copyright</tt> used to contain all the
3777 copyright files, plus the four common licenses GPL,
3778 LGPL, Artistic and BSD. Now individual copyright files
3779 for packages are no longer in a common directory. Once
3780 <tt>/usr/doc/copyright</tt> is almost empty it makes
3781 sense to rename "copyright" to "licenses"
3784 Why "common-licenses" and not "licenses"? Because if I
3785 put just "licenses" I'm sure I will receive a bug report
3786 saying "license foo is not included in the licenses
3787 directory. They are not all the licenses, just a few
3788 common ones. I could use /usr/share/doc/common-licenses
3789 but I think this is too long, and, after all, the GPL
3790 does not "document" anything, it is merely a license.
3796 Do not use the copyright file as a general <tt>README</tt>
3797 file. If your package has such a file it should be
3798 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3799 <tt>README.Debian</tt> or some other appropriate place.</p>
3803 <heading>Examples</heading>
3806 Any examples (configurations, source files, whatever),
3807 should be installed in a directory
3808 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3809 files should not be referenced by any program--they're there
3810 for the benefit of the system administrator and users, as
3811 documentation only. Architecture-specific example files
3812 should be installed in a directory
3813 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3814 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3815 to files in it. Or the latter directory may be a symlink to
3819 <sect id="instchangelog">
3820 <heading>Changelog files</heading>
3823 This installed file must contain a copy of the
3824 <tt>debian/changelog</tt> file from your Debian source tree,
3825 and a copy of the upstream changelog file if there is one.
3826 The debian/changelog file should be installed in
3827 <tt>/usr/share/doc/<var>package</var></tt> as
3828 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3829 file is text formatted, it must be accessible as
3830 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
3831 the upstream changelog file is HTML formatted, it must be
3833 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
3834 A plain text version of the changelog must be accessible as
3835 <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
3836 be created by <tt>lynx -dump -nolist</tt>). If the upstream
3837 changelog files do not already conform to this naming
3838 convention, then this may be achieved by either renaming the
3839 files or adding a symbolic link at the packaging developer's
3843 Rationale: People should not have to look into two
3844 places ofr upstream changelogs merely because they are
3851 Both should be installed compressed using <tt>gzip -9</tt>,
3852 as they will become large with time even if they start out
3856 If the package has only one changelog which is used both as
3857 the Debian changelog and the upstream one because there is
3858 no separate upstream maintainer then that changelog should
3859 usually be installed as
3860 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3861 there is a separate upstream maintainer, but no upstream
3862 changelog, then the Debian changelog should still be called
3863 <tt>changelog.Debian.gz</tt>.</p>