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>Manoj Srivastava <email>srivasta@debian.org</email></p>
72 Copyright ©1996,1997,1998 Ian Jackson
73 and Christian Schwarz.
76 This manual is free software; you may redistribute it and/or
77 modify it under the terms of the GNU General Public License
78 as published by the Free Software Foundation; either version
79 2, or (at your option) any later version.
83 This is distributed in the hope that it will be useful, but
84 <em>without any warranty</em>; without even the implied
85 warranty of merchantability or fitness for a particular
86 purpose. See the GNU General Public License for more
91 A copy of the GNU General Public License is available as
92 <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
93 distribution or on the World Wide Web at
94 <url id="http://www.gnu.org/copyleft/gpl.html"
95 name="&urlname">. You can also obtain it by writing to the
96 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
97 Boston, MA 02111-1307, USA.
105 <heading>About this manual</heading>
107 <heading>Scope</heading>
109 This manual describes the policy requirements for the Debian
110 GNU/Linux distribution. This includes the structure and
111 contents of the Debian archive, several design issues of the
112 operating system, as well as technical requirements that
113 each package must satisfy to be included in the
117 This manual does <em>not</em> describe the technical
118 mechanisms involved in package creation, installation, and
119 removal. This information can be found in the <em>Debian
120 Packaging Manual</em> and the <em>Debian System
121 Administrators' Manual</em>. Please note that the
122 footnotes present in this manual are merely informative,
123 and are not part of Debian policy itself.
126 This document assumes familiarity with these other two
127 manuals. Unfortunately, the <em>System Administrators'
128 Manual</em> does not exist yet.
131 Much of the information presented in this manual will be
132 useful even when building a package which is to be
133 distributed in some other way or is for local use.
137 <heading>New versions of this document</heading>
139 The current version of this document is always accessible from the
140 Debian FTP server <ftpsite>ftp.debian.org</ftpsite> at
141 <ftppath>/debian/doc/manuals/debian-policy.html.tar.gz</ftppath>
142 or from the Debian WWW server at
143 <url id="http://www.debian.org/doc/debian-policy/"
144 name="&urlname">.</p>
147 In addition, this manual is distributed via the Debian package
148 <tt>debian-policy</tt>.
152 <heading>Feedback</heading>
155 As the Debian GNU/Linux system is continuously evolving this
156 manual is changed from time to time.
159 While the authors of this document tried hard not to include
160 any typos or other errors these still occur. If you discover
161 an error in this manual or if you want to tell us any
162 comments, suggestions, or critics please send an email to
163 the Debian Policy List,
164 <email>debian-policy@lists.debian.org</email>, or submit a
165 bug report against the <tt>debian-policy</tt> package.
170 <heading>The Debian Archive</heading>
172 The Debian GNU/Linux system is maintained and distributed as a
173 collection of <em>packages</em>. Since there are so many of them (over
174 2600) they are split into <em>sections</em> and <em>priorities</em> to
175 simplify handling of them.
178 The effort of the Debian project is to build a free operating
179 system, but not every package we want to make accessible is
180 <em>free</em> in our sense (see Debian Free Software
181 Guidelines, below), or may be imported/exported without
182 restrictions. Thus, the archive is split into the sections
183 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
184 <em>contrib</em>.</p>
186 The <em>main</em> section forms the <em>Debian GNU/Linux
187 distribution</em>. </p>
189 Packages in the other sections are not considered as part of
190 the Debian distribution, though we support their use, and we
191 provide infrastructure for them (such as our bug-tracking
192 system and mailing lists). This Debian Policy Manual applies
193 to these packages as well.</p>
195 <sect id="pkgcopyright">
196 <heading>Package copyright and sections</heading>
198 The aims of this policy are:
200 <list compact="compact">
202 <p>We want to make as much software available as we
206 <p>We want to encourage everyone to write free software.</p>
209 <p> We want to make it easy for people to produce
210 CD-ROMs of our system without violating any licenses,
211 import/export restrictions, or any other laws.</p>
216 <heading>The Debian Free Software Guidelines</heading>
218 The Debian Free Software Guidelines (DFSG) is our
219 definition of `free' software.
221 <tag>Free Redistribution
225 The license of a Debian component may not restrict any
226 party from selling or giving away the software as a
227 component of an aggregate software distribution
228 containing programs from several different
229 sources. The license may not require a royalty or
230 other fee for such sale.
237 The program must include source code, and must allow
238 distribution in source code as well as compiled form.
245 The license must allow modifications and derived
246 works, and must allow them to be distributed under the
247 same terms as the license of the original software.
250 <tag>Integrity of The Author's Source Code
254 The license may restrict source-code from being
255 distributed in modified form <em>only</em> if the
256 license allows the distribution of ``patch files''
257 with the source code for the purpose of modifying the
258 program at build time. The license must explicitly
259 permit distribution of software built from modified
260 source code. The license may require derived works to
261 carry a different name or version number from the
262 original software. (This is a compromise. The Debian
263 group encourages all authors to not restrict any
264 files, source or binary, from being modified.)
267 <tag>No Discrimination Against Persons or Groups
271 The license must not discriminate against any person
275 <tag>No Discrimination Against Fields of Endeavor
279 The license must not restrict anyone from making use
280 of the program in a specific field of endeavor. For
281 example, it may not restrict the program from being
282 used in a business, or from being used for genetic
286 <tag>Distribution of License
290 The rights attached to the program must apply to all
291 to whom the program is redistributed without the need
292 for execution of an additional license by those
296 <tag>License Must Not Be Specific to Debian
300 The rights attached to the program must not depend on
301 the program's being part of a Debian system. If the
302 program is extracted from Debian and used or
303 distributed without Debian but otherwise within the
304 terms of the program's license, all parties to whom
305 the program is redistributed must have the same
306 rights as those that are granted in conjunction with
310 <tag>License Must Not Contaminate Other Software
314 The license must not place restrictions on other
315 software that is distributed along with the licensed
316 software. For example, the license must not insist
317 that all other programs distributed on the same medium
318 must be free software.
321 <tag>Example Licenses
325 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
326 examples of licenses that we consider <em>free</em>.
333 <heading>The main section</heading>
335 Every package in "main" must comply with the DFSG (Debian
336 Free Software Guidelines).</p>
339 In addition, the packages in "main"
340 <list compact="compact">
343 must not require a package outside of "main" for
344 compilation or execution (thus, the package may not
345 declare a "Depends" or "Recommends" relationship on a
351 must not be so buggy that we refuse to support them,
356 must meet all policy requirements presented in this
364 <heading>The contrib section</heading>
366 Every package in "contrib" must comply with the DFSG.
370 Examples of packages which would be included in "contrib" are
371 <list compact="compact">
374 free packages which require "contrib", "non-free", or
375 "non-US" packages or packages which are not in our
376 archive at all for compilation or execution,
381 wrapper packages or other sorts of free accessories for
389 <heading>The non-free section</heading>
391 `Non-free' contains packages which are not compliant with
392 the DFSG or which are encumbered by patents or other legal
393 issues that make their distribution problematic.</p>
395 All packages in `non-free' must be electronically
396 distributable across international borders.
400 <heading>The non-us server</heading>
402 Some programs with cryptographic program code must be stored
403 on the "non-us" server because of export restrictions of the
406 This applies only to packages which contain cryptographic
407 code. A package containing a program with an interface to a
408 cryptographic program or a program that's dynamically linked
409 against a cryptographic library can be distributed if it is
410 capable of running without the cryptography library or
415 <heading>Further copyright considerations</heading>
417 Every package must be accompanied by a verbatim copy of its
418 copyright and distribution license in the file
419 /usr/share/doc/<package-name>/copyright (see <ref
420 id="copyrightfile"> for details).</p>
422 We reserve the right to restrict files from being included
423 anywhere in our archives if
424 <list compact="compact">
427 their use or distribution would break a law,
432 there is an ethical conflict in their distribution or
438 we would have to sign a license for them, or
443 their distribution would conflict with other project
451 Programs whose authors encourage the user to make donations
452 are fine for the main distribution, provided that the
453 authors do not claim that not donating is immoral,
454 unethical, illegal or something similar; otherwise they must
455 go in contrib (or non-free, if even distribution is
456 restricted by such statements).</p>
459 Packages whose copyright permission notices (or patent
460 problems) do not allow redistribution even of only binaries,
461 and where no special permission has been obtained, cannot be
462 placed on the Debian FTP site and its mirrors at all.</p>
465 Note, that under international copyright law (this applies
466 in the United States, too) <em>no</em> distribution or
467 modification of a work is allowed without an explicit notice
468 saying so. Therefore a program without a copyright notice
469 <em>is</em> copyrighted and you may not do anything to it
470 without risking being sued! Likewise if a program has a
471 copyright notice but no statement saying what is permitted
472 then nothing is permitted.</p>
475 Many authors are unaware of the problems that restrictive
476 copyrights (or lack of copyright notices) can cause for the
477 users of their supposedly-free software. It is often
478 worthwhile contacting such authors diplomatically to ask
479 them to modify their license terms. However, this is a
480 politically difficult thing to do and you should ask for
481 advice on <tt>debian-devel</tt> first.</p>
484 When in doubt, send mail to
485 <email>debian-devel@lists.debian.org</email>. Be prepared
486 to provide us with the copyright statement. Software
487 covered by the GPL, public domain software and BSD-like
488 copyrights are safe; be wary of the phrases `commercial use
489 prohibited' and `distribution restricted'.</p>
492 <heading>Subsections</heading>
495 The packages in all the sections (<em>main</em>,
496 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
497 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
498 grouped further into <em>subsections</em> to simplify
502 The section for each package is specified in the package's
503 <em>control record</em>. However, the maintainer of the
504 Debian archive may override this selection to assure the
505 consistency of the Debian distribution. </p>
508 Please check the current Debian distribution to see which
509 sections are available.</p>
512 <heading>Priorities</heading>
515 Each package is given a certain <em>priority</em> value,
516 which is included in the package's <em>control
517 record</em>. This information is used in the Debian package
518 management tool to separate high-priority packages from
519 less-important packages.</p>
522 The following <em>priority levels</em> are supported by the
523 Debian package management system, <prgn>dpkg</prgn>.
525 <tag><tt>required</tt></tag>
528 <tt>required</tt> packages are necessary for the
529 proper functioning of the system. You must not remove
530 these packages or your system may become totally
531 broken and you may not even be able to use
532 <prgn>dpkg</prgn> to put things back. Systems with
533 only the <tt>required</tt> packages are probably
534 unusable, but they do have enough functionality to
535 allow the sysadmin to boot and install more
538 <tag><tt>important</tt></tag>
541 Important programs, including those which one would
542 expect to find on any Unix-like system. If the
543 expectation is that an experienced Unix person who
544 found it missing would say `What the F*!@<+ is
545 going on, where is <prgn>foo</prgn>', it must be in
546 <tt>important</tt>. This is an important criterion
547 because we are trying to produce, amongst other
548 things, a free Unix. Other packages without which the
549 system will not run well or be usable must also be
550 here. This does <em>not</em> include Emacs, the X
551 Window System, TeX or any other large applications.
552 The <tt>important</tt> packages are just a bare
553 minimum of commonly-expected and necessary tools.</p>
555 <tag><tt>standard</tt></tag>
558 These packages provide a reasonably small but not too
559 limited character-mode system. This is what will
560 install by default if the user doesn't select anything
561 else. It doesn't include many large applications, but
562 it does include Emacs (this is more of a piece of
563 infrastructure than an application) and a reasonable
564 subset of TeX and LaTeX (if this is possible without
567 <tag><tt>optional</tt></tag>
570 (In a sense everything is optional that isn't
571 required, but that's not what is meant here.) This is
572 all the software that you might reasonably want to
573 install if you didn't know what it was or don't have
574 specialized requirements. This is a much larger system
575 and includes the X Window System, a full TeX
576 distribution, and many applications.</p>
578 <tag><tt>extra</tt></tag>
581 This contains all packages that conflict with others
582 with required, important, standard or optional
583 priorities, or are only likely to be useful if you
584 already know what they are or have specialised
591 Packages may not depend on packages with lower priority
592 values (excluding build-time dependencies). If this does
593 happen, one of the priority values will have to be adapted.
598 <heading>Binary packages</heading>
601 The Debian GNU/Linux distribution is based on the Debian
602 package management system, called <prgn>dpkg</prgn>. Thus,
603 all packages in the Debian distribution have to be provided
604 in the <tt>.deb</tt> file format.</p>
608 <heading>The package name</heading>
611 Every package must have a name that's unique within the Debian
615 Package names may only consist of lower case letters, digits (0-9),
616 plus (+) or minus (-) signs, and periods (.).</p>
619 The package name is part of the file name of the
620 <tt>.deb</tt> file and is included in the control field
626 <heading>The maintainer of a package</heading>
629 Every package must have exactly one maintainer at a
630 time. This person is responsible that the license of the
631 package's software complies with the policy of the
632 distribution this package is included in.</p>
635 The maintainer must be specified in the
636 <tt>Maintainer</tt> control field with the correct name
637 and a working email address for the Debian maintainer of
638 the package. If one person maintains several packages
639 he/she should try to avoid having different forms of their
640 name and email address in different <tt>Maintainer</tt>
644 If the maintainer of a package quits from the Debian
645 project the Debian QA Group
646 <email>debian-qa@lists.debian.org</email> takes over the
647 maintainership of the package until someone else
648 volunteers for that task. These packages are called
649 <em>orphaned packages</em>.
655 <heading>The description of a package</heading>
658 Every Debian package must have an extended description
659 stored in the appropriate field of the control record.</p>
662 The description must be written so that it tells the user
663 what they need to know to decide whether to install the
664 package. This description should not just be copied from
665 the blurb for the program. Instructions for configuring
666 or using the package must not be included -- that is what
667 installation scripts, manual pages, Info files, etc. are
668 for. Copyright statements and other administrivia must
669 not be included -- that is what the copyright file is
675 <heading>Dependencies</heading>
678 Every package has to specify the dependency information
679 about other packages, that are required for the first to
683 For example, for any shared libraries required by
684 dynamically-linked executable binary in a package a
685 dependency entry has to be provided.</p>
688 It is not necessary for other packages to declare any
689 dependencies they have on other packages which are marked
690 <tt>Essential</tt> (see below).</p>
693 Sometimes, a package requires another package to be
694 installed <em>and</em> configured before it can be
695 installed. In this case, you'll have to specify a
696 <tt>Pre-Depends</tt> entry for the package.</p>
699 You must not specify a <tt>Pre-Depends</tt> entry for a
700 package before this has been discussed on the
701 <tt>debian-devel</tt> mailing list and a consensus about
702 doing that has been reached.</p></sect1>
706 <heading>Virtual packages</heading>
709 Sometimes, there are several packages doing more-or-less
710 the same job. In this case, it's useful to define a
711 <em>virtual package</em> whose name describes the function
712 the packages have. (The virtual packages just exist
713 logically, not physically--that's why they are called
714 <em>virtual</em>.) The packages with this particular
715 function will then <em>provide</em> the virtual
716 package. Thus, any other package requiring that function
717 can simply depend on the virtual package without having to
718 specify all possible packages individually.</p>
721 All packages must use virtual package names where
722 appropriate, and arrange to create new ones if necessary.
723 They must not use virtual package names (except privately,
724 amongst a cooperating group of packages) unless they have
725 been agreed upon and appear in the list of virtual package
729 The latest version of the authoritative list of virtual
730 package names can be found on
731 <ftpsite>ftp.debian.org</ftpsite> in
732 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
733 or your local mirror. In addition, it is included in the
734 <tt>debian-policy</tt> package. The procedure for updating
735 the list is described at the top of the file.</p></sect1>
739 <heading>Base packages</heading>
742 The packages included in the <tt>base</tt> section have a
743 special function. They form a minimum subset of the Debian
744 GNU/Linux system that is installed before everything else
745 on a new system. Thus, only very few packages are allowed
746 to go into the <tt>base</tt> section to keep the required
747 disk usage very small.</p>
750 Most of these packages should have the priority value
751 <tt>required</tt> or at least <tt>important</tt>, and many
752 of them will be tagged <tt>essential</tt> (see below).</p>
755 You must not place any packages into the <tt>base</tt>
756 section before this has been discussed on the
757 <tt>debian-devel</tt> mailing list and a consensus about
758 doing that has been reached.</p></sect1>
762 <heading>Essential packages</heading>
765 Some packages are tagged <tt>essential</tt>. (They have
766 <tt>Essential: yes</tt> in their package control record.)
767 This flag is used for packages that are <em>essential</em>
771 Since these packages can not easily be removed (you'll
772 have to specify an extra <em>force option</em> to
773 <prgn>dpkg</prgn>) this flag must only be used where
774 absolutely necessary.
776 A shared library package must not be tagged
777 <em>essential</em>--the dependencies will prevent its
778 premature removal, and we need to be able to remove it
779 when it has been superseded.</p>
782 You must not tag any packages <tt>essential</tt> before
783 this has been discussed on the <tt>debian-devel</tt>
784 mailing and a consensus about doing that has been
789 <heading>Maintainer scripts</heading>
792 The package installation scripts must avoid producing
793 output which it is unnecessary for the user to see and
794 should rely on <prgn>dpkg</prgn> to stave off boredom on
795 the part of a user installing many packages. This means,
796 amongst other things, using the <tt>--quiet</tt> option on
797 <prgn>install-info</prgn>.</p>
800 Packages should try to minimize the amount of prompting
801 they need to do, and they should ensure that the user will
802 only ever be asked each question once. This means that
803 packages should try to use appropriate shared
804 configuration files (such as <tt>/etc/papersize</tt> and
805 <tt>/etc/news/server</tt>), rather than each prompting for
806 their own list of required pieces of information.</p>
809 It also means that an upgrade should not ask the same
810 questions again, unless the user has used <tt>dpkg
811 --purge</tt> to remove the package's configuration. The
812 answers to configuration questions should be stored in an
813 appropriate place in <tt>/etc</tt> so that the user can
814 modify them, and how this has been done should be
818 If a package has a vitally important piece of information
819 to pass to the user (such as "don't run me as I am, you
820 must edit the following configuration files first or you
821 risk your system emitting badly-formatted messages"), it
822 should display this in the <prgn>postinst</prgn> script
823 and prompt the user to hit return to acknowledge the
824 message. Copyright messages do not count as vitally
825 important (they belong in
826 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
827 do instructions on how to use a program (these should be
828 in on line documentation, where all the users can see
832 Any necessary prompting should almost always be confined
833 to the post-installation script, and should be protected
834 with a conditional so that unnecessary prompting doesn't
835 happen if a package's installation fails and the
836 <prgn>postinst</prgn> is called with
837 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
838 <tt>abort-deconfigure</tt>.</p>
841 Errors which occur during the execution of an installation
842 script <em>must</em> be checked and the installation
843 <em>must not</em> continue after an error.</p>
846 Note, that <ref id="scripts">, in general applies to
847 package maintainer scripts, too.</p>
850 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
851 another package without consulting the maintainer of that
855 In order for <prgn>update-alternatives</prgn> to work
856 correctly all the packages which supply an instance of the
857 `shared' command name (or, in general, filename) must use
858 it. You can use <tt>Conflicts</tt> to force the
859 De-installation of other packages supplying it which do not
860 (yet) use <prgn>update-alternatives</prgn>. It may in
861 this case be appropriate to specify a conflict on earlier
862 versions of something--this is an exception to the usual
863 rule that this is not allowed.</p>
867 <heading>Source packages</heading>
870 <heading>Standards conformance</heading>
873 You should specify the most recent version of the
874 packaging standards with which your package complies in
875 the source package's <tt>Standards-Version</tt> field.</p>
878 This value will be used to file bug reports automatically
879 if your package becomes too much out of date.</p>
882 The value corresponds to a version of the Debian manuals,
883 as can be found on the title page or page headers and
884 footers (depending on the format).</p>
887 The version number has four components--major and minor
888 number and major and minor patch level. When the
889 standards change in a way that requires every package to
890 change the major number will be changed. Significant
891 changes that will require work in many packages will be
892 signaled by a change to the minor number. The major patch
893 level will be changed for any change to the meaning of the
894 standards, however small; the minor patch level will be
895 changed when only cosmetic, typographical or other edits
896 which do not change the meaning are made, or changes which
897 do not affect the contents of packages.</p>
900 For package maintainers, only the first 3 digits of the
901 manual version are significant in representing the
902 <em>Standards-Version</em>, and either these 3 digits or
903 the complete 4 digits can be specified--that's up to the
907 In the past, people specified 4 digits in the
908 Standards-Version field, like `2.3.0.0'. Since any
909 `patch-level changes' don't introduce new policy, it
910 was thought it would be better to relax policy and
911 only require that the first 3 digits are specified. (4
912 digits can still be used if someone wants to do so.)
918 You should regularly, and especially if your package has
919 become out of date, check for the newest Policy Manual
920 available and update your package, if necessary. When your
921 package complies with the new standards you may update the
922 <tt>Standards-Version</tt> source package field and
923 release it.</p></sect1>
927 <heading>Package relationships</heading>
930 Source packages must specify which binary packages they
931 require to be installed or not to be installed in order to
932 build correctly. For example, if building a package
933 requires a certain compiler, then the compiler must be
934 specified as a build-time dependency.
938 It will not be necessary to explicitly specify build-time
939 relationships on a minimal set of packages that are always
940 needed to compile, link and put in a Debian package a
941 standard "Hello World!" program written in C or C++. The
942 required packages are called <em>build-essential</em>, and
943 an informational list can be found in
944 <tt>/usr/share/doc/build-essential/list</tt> (which is
945 contained in the <tt>build-essential</tt> package).
950 When specifying the set of build-time dependencies, one
951 should list only those packages explicitly required by the
952 build. It is not necessary to list packages which are
953 required merely because some other package in the list of
954 build-time dependencies depends on them. The reason is
955 that dependencies change, and you should list only those
956 <em>you</em> need. What others need is their business.
960 It is a bug if, after unpacking a source package on a
961 system with the build-essential packages installed and
962 satisfying the build-time relationships (including the
963 implied relationships), one cannot build the package and
964 produce a working binary package suitable for installation
965 into the binary distribution corresponding to the source
966 distribution which contained the source package. This
967 means in particular that version clauses should be used
968 rigorously in build-time relationships so that one cannot
969 produce bad or inconsistently configured packages when the
970 relationships are properly satisfied.
974 <heading>Changes to the upstream sources</heading>
977 If changes to the source code are made that are generally
978 applicable please try to get them included in the upstream
979 version of the package by supplying the upstream authors
980 with the changes in whatever form they prefer.</p>
983 If you need to configure the package differently for
984 Debian or for Linux, and the upstream source doesn't
985 provide a way to configure it the way you need to, please
986 add such configuration facilities (for example, a new
987 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
988 the patch to the upstream authors, with the default set to
989 the way they originally had it. You can then easily
990 override the default in your <tt>debian/rules</tt> or
991 wherever is appropriate.</p>
994 Please make sure that the <prgn>configure</prgn> utility
995 detects the correct architecture specification string
996 (refer to <ref id="arch-spec"> for details).</p>
999 If you need to edit a <prgn>Makefile</prgn> where
1000 GNU-style <prgn>configure</prgn> scripts are used, you
1001 should edit the <tt>.in</tt> files rather than editing the
1002 <prgn>Makefile</prgn> directly. This allows the user to
1003 reconfigure the package if necessary. You should
1004 <em>not</em> configure the package and edit the generated
1005 <prgn>Makefile</prgn>! This makes it impossible for
1006 someone else to later reconfigure the package.</p></sect1>
1010 <heading>Documenting your changes</heading>
1013 Document your changes and updates to the source package
1014 properly in the <tt>debian/changelog</tt> file.</p>
1017 A copy of the file which will be installed in
1018 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1019 in <tt>debian/copyright</tt>.</p>
1022 In non-experimental packages you may only use a format for
1023 <tt>debian/changelog</tt> which is supported by the most
1024 recent released version of <prgn>dpkg</prgn>. If your
1025 format is not supported and there is general support for
1026 it you should contact the <prgn>dpkg</prgn> maintainer to
1027 have the parser script for your format included in the
1028 <prgn>dpkg</prgn> package. (You will need to agree that
1029 the parser and its manpage may be distributed under the
1030 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1035 <heading>Error trapping in makefiles</heading>
1038 When <prgn>make</prgn> invokes a command in a makefile
1039 (including your package's upstream makefiles and the
1040 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1041 means that <tt>sh</tt>'s usual bad error handling
1042 properties apply: if you include a miniature script as one
1043 of the commands in your makefile you'll find that if you
1044 don't do anything about it then errors are not detected
1045 and <prgn>make</prgn> will blithely continue after
1049 Every time you put more than one shell command (this
1050 includes using a loop) in a makefile command you
1051 <em>must</em> make sure that errors are trapped. For
1052 simple compound commands, such as changing directory and
1053 then running a program, using <tt>&&</tt> rather
1054 than semicolon as a command separator is sufficient. For
1055 more complex commands including most loops and
1056 conditionals you must include a separate <tt>set -e</tt>
1057 command at the start of every makefile command that's
1058 actually one of these miniature shell scripts.</p></sect1>
1062 <heading>Obsolete constructs and libraries</heading>
1065 The include file <prgn><varargs.h></prgn> is
1066 provided to support end-users compiling very old software;
1067 the library <tt>libtermcap</tt> is provided to support the
1068 execution of software which has been linked against it
1069 (either old programs or those such as Netscape which are
1070 only available in binary form).</p>
1073 Debian packages should be ported to include
1074 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1079 <chapt><heading>The Operating System</heading>
1083 <heading>File system hierarchy</heading>
1087 <heading>Linux File system Structure</heading>
1090 The location of all installed files and directories must
1091 comply with the Linux File system Hierarchy Standard
1092 (FHS). The latest version of this document can be found
1093 alongside this manual or on
1094 <url id="http://www.pathname.com/fhs/">.<footnote>
1095 <p>The Debian distribution currently distributes a draft
1096 version of FHS 2.1 because several significant details
1097 have changed between the currently released 2.0
1098 version and the to-be-released 2.1 version.</p>
1100 Specific questions about following the standard may be
1101 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1102 Quinlan, the FHS coordinator, at
1103 <email>quinlan@pathname.com</email>.</p></sect1>
1107 <heading>Site-specific programs</heading>
1110 As mandated by the FHS no package should place any
1111 files in <tt>/usr/local</tt>, either by putting them in
1112 the file system archive to be unpacked by <prgn>dpkg</prgn>
1113 or by manipulating them in their maintainer scripts.</p>
1116 However, the package should create empty directories below
1117 <tt>/usr/local</tt> so that the system administrator knows
1118 where to place site-specific files. These directories
1119 should be removed on package removal if they are
1123 Note, that this applies only to directories <em>below</em>
1124 <tt>/usr/local</tt>, not <em>in</em>
1125 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1126 itself may only contain the sub-directories listed in
1127 FHS, section 4.6. However, you may create directories
1128 below them as you wish. You may not remove any of the
1129 directories listed in 4.6, even if you created them.</p>
1132 Since <tt>/usr/local</tt> may be mounted read-only from a
1133 remote server, these directories have to be created and
1134 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1135 maintainer scripts. These scripts must not fail if either
1136 of these operations fail. (In the future, it will be
1137 possible to tell <prgn>dpkg</prgn> not to unpack files
1138 matching certain patterns, so that the directories can be
1139 included in the <tt>.deb</tt> packages and system
1140 administrators who do not wish these directories in
1141 /usr/local do not need to have them.)</p>
1144 For example, the <prgn>emacs</prgn> package will contain
1146 mkdir -p /usr/local/lib/emacs/site-lisp || true
1148 in the <tt>postinst</tt> script, and
1150 rmdir /usr/local/lib/emacs/site-lisp && \
1151 rmdir /usr/local/lib/emacs || \
1154 in the <tt>prerm</tt> script.</p>
1157 If you do create a directory in <tt>/usr/local</tt> for
1158 local additions to a package, you must ensure that
1159 settings in <tt>/usr/local</tt> take precedence over the
1160 equivalents in <tt>/usr</tt>.</p>
1163 However, because '/usr/local' and its contents are for
1164 exclusive use of the local administrator, a package must
1165 not rely on the presence or absence of files or
1166 directories in '/usr/local' for normal operation.</p>
1169 The <tt>/usr/local</tt> directory itself and all the
1170 subdirectories created by the package should have
1171 permissions 2775 (group-writable and set-group-id) and be
1172 owned by <tt>root.staff</tt>.</p>
1177 <heading>Users and groups</heading>
1180 The Debian system can be configured to use either plain or
1181 shadow passwords.</p>
1184 Some user ids (UIDs) and group ids (GIDs) are reserved
1185 globally for use by certain packages. Because some packages
1186 need to include files which are owned by these users or
1187 groups, or need the ids compiled into binaries, these ids
1188 must be used on any Debian system only for the purpose for
1189 which they are allocated. This is a serious restriction, and
1190 we should avoid getting in the way of local administration
1191 policies. In particular, many sites allocate users and/or
1192 local system groups starting at 100.</p>
1195 Apart from this we should have dynamically allocated ids,
1196 which should by default be arranged in some sensible
1197 order--but the behavior should be configurable.</p>
1200 No package except <tt>base-passwd</tt> may modify
1201 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1202 <tt>/etc/group</tt>.</p>
1205 The UID and GID ranges are as follows:
1210 Globally allocated by the Debian project, must be the
1211 same on every Debian system. These ids will appear in
1212 the <tt>passwd</tt> and <tt>group</tt> files of all
1213 Debian systems, new ids in this range being added
1214 automatically as the <tt>base-passwd</tt> package is
1218 Packages which need a single statically allocated uid
1219 or gid should use one of these; their maintainers
1220 should ask the <tt>base-passwd</tt> maintainer for
1227 Dynamically allocated system users and groups.
1228 Packages which need a user or group, but can have this
1229 user or group allocated dynamically and differently on
1230 each system, should use `<tt>adduser --system</tt>' to
1231 create the group and/or user. <prgn>adduser</prgn>
1232 will check for the existence of the user or group, and
1233 if necessary choose an unused id based on the ranged
1234 specified in <tt>adduser.conf</tt>.</p></item>
1237 <tag>1000-29999:</tag>
1240 Dynamically allocated user accounts. By default
1241 <prgn>adduser</prgn> will choose UIDs and GIDs for
1242 user accounts in this range, though
1243 <tt>adduser.conf</tt> may be used to modify this
1247 <tag>30000-59999:</tag>
1249 <p>Reserved.</p></item>
1252 <tag>60000-64999:</tag>
1255 Globally allocated by the Debian project, but only
1256 created on demand. The ids are allocated centrally and
1257 statically, but the actual accounts are only created
1258 on users' systems on demand.</p>
1261 These ids are for packages which are obscure or which
1262 require many statically-allocated ids. These packages
1263 should check for and create the accounts in
1264 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1265 <prgn>adduser</prgn> if it has this facility) if
1266 necessary. Packages which are likely to require
1267 further allocations should have a `hole' left after
1268 them in the allocation, to give them room to
1272 <tag>65000-65533:</tag>
1274 <p>Reserved.</p></item>
1279 <p>User `<tt>nobody</tt>.'</p></item>
1285 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1286 because it is the error return sentinel value.</p>
1291 <sect id="sysvinit">
1292 <heading>System run levels</heading>
1295 <sect1 id="/etc/init.d">
1296 <heading>Introduction</heading>
1299 The <tt>/etc/init.d</tt> directory contains the scripts
1300 executed by <prgn>init</prgn> at boot time and when init
1301 state (or `runlevel') is changed (see <manref name="init"
1305 There are at least two different, yet functionally
1306 equivalent, ways of handling these scripts. For the sake
1307 of simplicity, this document describes only the symbolic
1308 link method. However, it may not be assumed that this
1309 method is being used, and any manipulation of the various
1310 runlevel behaviours must be performed using
1311 <prgn>update-rc.d</prgn> as described below and not by
1312 manually installing symlinks. For information on the
1313 implementation details of the other method, implemented in
1314 the <tt>file-rc</tt> package, please refer to the
1315 documentation of that package.</p>
1318 These scripts are referenced by symbolic links in
1319 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1320 changing runlevels, <prgn>init</prgn> looks in the
1321 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1322 it should execute, where <var>n</var> is the runlevel that
1323 is being changed to, or `S' for the boot-up scripts.</p>
1326 The names of the links all have the form
1327 <tt>S<var>mm</var><var>script</var></tt> or
1328 <tt>K<var>mm</var><var>script</var></tt> where
1329 <var>mm</var> is a two-digit number and <var>script</var>
1330 is the name of the script (this should be the same as the
1331 name of the actual script in <tt>/etc/init.d</tt>.</p>
1334 When <prgn>init</prgn> changes runlevel first the targets
1335 of the links whose names starting with a <tt>K</tt> are
1336 executed, each with the single argument <tt>stop</tt>,
1337 followed by the scripts prefixed with an <tt>S</tt>, each
1338 with the single argument <tt>start</tt>. The <tt>K</tt>
1339 links are responsible for killing services and the
1340 <tt>S</tt> link for starting services upon entering the
1344 For example, if we are changing from runlevel 2 to
1345 runlevel 3, init will first execute all of the <tt>K</tt>
1346 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1347 all of the <tt>S</tt> prefixed scripts. The links
1348 starting with <tt>K</tt> will cause the referred-to file
1349 to be executed with an argument of <tt>stop</tt>, and the
1350 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1353 The two-digit number <var>mm</var> is used to decide which
1354 order to start and stop things in--low-numbered links have
1355 their scripts run first. For example, the <tt>K20</tt>
1356 scripts will be executed before the <tt>K30</tt> scripts.
1357 This is used when a certain service must be started before
1358 another. For example, the name server <prgn>bind</prgn>
1359 might need to be started before the news server
1360 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1361 access lists. In this case, the script that starts
1362 <prgn>bind</prgn> should have a lower number than the
1363 script that starts <prgn>inn</prgn> so that it runs first:
1372 <heading>Writing the scripts</heading>
1375 Packages can and should place scripts in
1376 <tt>/etc/init.d</tt> to start or stop services at boot
1377 time or during a change of runlevel. These scripts should
1378 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1379 should accept one argument, saying what to do:
1382 <tag><tt>start</tt></tag>
1383 <item><p>start the service,</p></item>
1385 <tag><tt>stop</tt></tag>
1386 <item><p>stop the service,</p></item>
1388 <tag><tt>restart</tt></tag>
1389 <item><p>stop and restart the service,</p></item>
1391 <tag><tt>reload</tt></tag>
1392 <item><p>cause the configuration of the service to be
1393 reloaded without actually stopping and restarting
1394 the service,</p></item>
1396 <tag><tt>force-reload</tt></tag> <item><p>cause the
1397 configuration to be reloaded if the service supports
1398 this, otherwise restart the service.</p></item>
1401 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1402 <tt>force-reload</tt> options must be supported by all
1403 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1404 option is optional.</p>
1407 The <tt>init.d</tt> scripts should ensure that they will
1408 behave sensibly if invoked with <tt>start</tt> when the
1409 service is already running, or with <tt>stop</tt> when it
1410 isn't, and that they don't kill unfortunately-named user
1411 processes. The best way to achieve this is usually to use
1412 <prgn>start-stop-daemon</prgn>.</p>
1415 If a service reloads its configuration automatically (as
1416 in the case of <prgn>cron</prgn>, for example), the
1417 <tt>reload</tt> option of the <tt>init.d</tt> script
1418 should behave as if the configuration has been reloaded
1422 These scripts should not fail obscurely when the
1423 configuration files remain but the package has been
1424 removed, as configuration files remain on the system after
1425 the package has been removed. Only when <prgn>dpkg</prgn>
1426 is executed with the <tt>--purge</tt> option will
1427 configuration files be removed. In particular, the init
1428 script itself is usually a configuration file (see
1429 <ref id="init.d notes">), and will remain on the system if
1430 the package is removed but not purged. Therefore, you
1431 should include a <tt>test</tt> statement at the top of the
1434 test -f <var>program-executed-later-in-script</var> || exit 0
1439 <heading>Managing the links</heading>
1442 A program is provided, <prgn>update-rc.d</prgn>, to handle
1443 the it easier for package maintainers to arrange for the
1444 proper creation and removal of
1445 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1446 functional equivalent if another method is being used.
1447 This may be used by maintainers in their packages'
1448 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1451 You should use this script to make changes to
1452 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1453 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1454 in the actual archive or manually create or remove the
1455 symbolic links in maintainer scripts. (The latter will
1456 fail if an alternative method of maintaining runlevel
1457 information is being used.)</p>
1460 By default <prgn>update-rc.d</prgn> will start services in
1461 each of the multi-user state runlevels (2, 3, 4, and 5)
1462 and stop them in the halt runlevel (0), the single-user
1463 runlevel (1) and the reboot runlevel (6). The system
1464 administrator will have the opportunity to customize
1465 runlevels by either running <prgn>update-rc.d</prgn>, by
1466 simply adding, moving, or removing the symbolic links in
1467 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1468 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1469 <tt>file-rc</tt> method is being used.</p>
1472 To get the default behavior for your package, put in your
1473 <tt>postinst</tt> script
1475 update-rc.d <var>package</var> defaults >/dev/null
1477 and in your <tt>postrm</tt>
1479 if [ purge = "$1" ]; then
1480 update-rc.d <var>package</var> remove >/dev/null
1485 This will use a default sequence number of 20. If it does
1486 not matter when or in which order the script is run, use
1487 this default. If it does, then you should talk to the
1488 maintainer of the <prgn>sysvinit</prgn> package or post to
1489 <tt>debian-devel</tt>, and they will help you choose a
1493 For more information about using <tt>update-rc.d</tt>,
1494 please consult its manpage <manref name="update-rc.d"
1495 section="8">.</p></sect1>
1499 <heading>Boot-time initialization</heading>
1502 There used to be another directory, <tt>/etc/rc.boot</tt>,
1503 which contained scripts which were run once per machine
1504 boot. This has been deprecated in favour of links from
1505 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1506 described in <ref id="/etc/init.d">. No packages may
1507 place files in <tt>/etc/rc.boot</tt>.</p>
1509 <sect1 id="init.d notes">
1510 <heading>Notes</heading>
1513 <em>Do not</em> include the
1514 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1515 <tt>.deb</tt> file system archive! <em>This will cause
1516 problems!</em> You should create them with
1517 <prgn>update-rc.d</prgn>, as above.</p>
1520 <em>Do not</em> include the
1521 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1522 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1523 problems!</em> <em>Do</em>, however, treat the
1524 <tt>/etc/init.d</tt> scripts as configuration files,
1525 either by marking them as conffiles or managing them
1526 correctly in the maintainer scripts (see
1527 <ref id="config files">). (This is important since we want
1528 to give the local system administrator the chance to adapt
1529 the scripts to the local system--e.g., to disable a
1530 service without de-installing the package, or to specify
1531 some special command line options when starting a
1532 service--while making sure her changes aren't lost during
1533 the next package upgrade.)</p>
1537 <heading>Example</heading>
1540 The <prgn>bind</prgn> DNS (nameserver) package wants to
1541 make sure that the nameserver is running in multiuser
1542 runlevels, and is properly shut down with the system. It
1543 puts a script in <tt>/etc/init.d</tt>, naming the script
1544 appropriately <tt>bind</tt>. As you can see, the script
1545 interprets the argument <tt>reload</tt> to send the
1546 nameserver a <tt>HUP</tt> signal (causing it to reload its
1547 configuration); this way the user can say
1548 <tt>/etc/init.d/bind reload</tt> to reload the name
1555 # Original version by Robert Leslie
1556 # <rob@mars.org>, edited by iwj and cs
1558 test -x /usr/sbin/named || exit 0
1562 echo -n "Starting domain name service: named"
1563 start-stop-daemon --start --quiet --exec /usr/sbin/named
1567 echo -n "Stopping domain name service: named"
1568 start-stop-daemon --stop --quiet \
1569 --pidfile /var/run/named.pid --exec /usr/sbin/named
1573 echo -n "Restarting domain name service: named"
1574 start-stop-daemon --stop --quiet \
1575 --pidfile /var/run/named.pid --exec /usr/sbin/named
1576 start-stop-daemon --start --verbose --exec /usr/sbin/named
1579 force-reload|reload)
1580 echo -n "Reloading configuration of domain name service: named"
1581 start-stop-daemon --stop --signal 1 --quiet \
1582 --pidfile /var/run/named.pid --exec /usr/sbin/named
1586 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1595 Another example on which to base your <tt>/etc/init.d</tt>
1596 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1599 If this package is happy with the default setup from
1600 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1601 and having named running in all runlevels, it can say in
1602 its <tt>postinst</tt>:
1604 update-rc.d bind defaults >/dev/null
1606 And in its <tt>postrm</tt>, to remove the links when the
1609 if [ purge = "$1" ]; then
1610 update-rc.d acct remove >/dev/null
1616 <heading>Cron jobs</heading>
1619 Packages may not modify the configuration file
1620 <tt>/etc/crontab</tt>, nor may they modify the files in
1621 <tt>/var/spool/cron/crontabs</tt>.</p>
1624 If a package wants to install a job that has to be executed
1625 via cron, it should place a file with the name if the
1626 package in one of the following directories:
1632 As these directory names imply, the files within them are
1633 executed on a daily, weekly, or monthly basis,
1634 respectively. The exact times are listed in
1635 <tt>/etc/crontab</tt>.</p>
1638 All files installed in any of these directories have to be
1639 scripts (shell scripts, Perl scripts, etc.) so that they can
1640 easily be modified by the local system administrator. In
1641 addition, they must be treated as configuration files.</p>
1644 If a certain job has to be executed more frequently than
1645 daily, the package should install a file
1646 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1647 the same syntax as <tt>/etc/crontab</tt> and is processed by
1648 <prgn>cron</prgn> automatically. The file must also be
1649 treated as a configuration file. (Note, that entries in the
1650 <tt>/etc/cron.d</tt> directory are not handled by
1651 <prgn>anacron</prgn>. Thus, you should only use this
1652 directory for jobs which may be skipped if the system is not
1656 The scripts or crontab entries in these directories should
1657 check if all necessary programs are installed before they
1658 try to execute them. Otherwise, problems will arise when a
1659 package was removed but not purged since configuration files
1660 are kept on the system in this situation.</p>
1664 <heading>Console messages</heading>
1667 This section describes different formats for messages
1668 written to standard output by the <tt>/etc/init.d</tt>
1669 scripts. The intent is to improve the consistency of
1670 Debian's startup and shutdown look and feel.</p>
1673 Please look very careful at the details. We want to get the
1674 messages to look exactly the same way concerning spaces,
1675 punctuation, and case of letters.</p>
1678 Here is a list of overall rules that you should use when you
1679 create output messages. They can be useful if you have a
1680 non-standard message that isn't covered in the sections
1687 Every message should cover one line, start with a
1688 capital letter and end with a period `.'.</p></item>
1693 If you want to express that the computer is working on
1694 something (performing a specific task, not starting or
1695 stopping a program), we use an ``ellipsis'', namely
1696 three dots `...'. Note that we don't insert spaces in
1697 front of or behind the dots. If the task has been
1698 completed we write `done.' and a line feed.</p></item>
1703 Design your messages as if the computer is telling you
1704 what he is doing (let him be polite :-) but don't
1705 mention ``him'' directly. For example, if you think
1708 I'm starting network daemons: nfsd mountd.
1712 Starting network daemons: nfsd mountd.
1713 </example></p></item>
1717 The following formats must be used</p>
1722 <p>when daemons get started.</p>
1725 Use this format if your script starts one or more
1726 daemons. The output should look like this (a single
1727 line, no leading spaces):
1729 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1731 The <description> should describe the subsystem
1732 the daemon or set of daemons are part of, while
1733 <daemon-1> up to <daemon-n> denote each
1734 daemon's name (typically the file name of the
1738 For example, the output of /etc/init.d/lpd would look like:
1740 Starting printer spooler: lpd.
1744 This can be achieved by saying
1746 echo -n "Starting printer spooler: lpd"
1747 start-stop-daemon --start --quiet lpd
1750 in the script. If you have more than one daemon to
1751 start, you should do the following:
1753 echo -n "Starting remote file system services:"
1754 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1755 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1756 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1759 This makes it possible for the user to see what takes
1760 so long and when the final daemon has been
1761 started. Please be careful where to put spaces: In the
1762 example above the system administrator can easily
1763 comment out a line if he don't wants to start a
1764 specific daemon, while the displayed message still
1765 looks good.</p></item>
1769 <p>when something needs to be configured.</p>
1772 If you have to set up different parameters of the
1773 system upon boot up, you can use this format:
1775 Setting <parameter> to `<value>'.
1779 You can use the following echo statement to get the quotes right:
1781 echo "Setting DNS domainname to \`"value"'."
1785 Note that the left quotation mark (`) is different
1786 from the right (').</p></item>
1789 <p>when a daemon is stopped.</p>
1792 When you stop a daemon you should issue a message
1793 similar to the startup message, except that `Starting'
1794 is replaced with `Stopping'.</p>
1797 So stopping the printer daemon will like like this:
1799 Stopping printer spooler: lpd.
1800 </example></p></item>
1803 <p>when something is executed.</p>
1806 There a several examples where you have to run a
1807 program at system startup or shutdown to perform a
1808 specific task. For example, setting the system's clock
1809 via `netdate' or killing all processes when the system
1810 comes down. Your message should like this:
1812 Doing something very useful...done.
1814 You should print the `done.' right after the job has been completed,
1815 so that the user gets informed why he has to wait. You can get this
1818 echo -n "Doing something very useful..."
1822 in your script.</p></item>
1825 <p>when the configuration is reloaded.</p>
1828 When a daemon is forced to reload its configuration
1829 files you should use the following format:
1831 Reloading <daemon's-name> configuration...done.
1832 </example></p></item>
1835 <p>when none of the above rules apply.</p>
1838 If you have to print a message that doesn't fit into
1839 the styles described above, you can use something
1840 appropriate, but please have a look at the overall
1841 rules listed above.</p></item>
1846 <heading>Menus</heading>
1849 Menu entries should follow the current menu policy as
1850 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1851 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1852 or your local mirror. In addition, it is included in the
1853 <tt>debian-policy</tt> package.
1857 The Debian <tt>menu</tt> packages provides a unique
1858 interface between packages providing applications and
1859 documents, and <em>menu programs</em> (either X window
1860 managers or text-based menu programs as
1861 <prgn>pdmenu</prgn>).</p>
1864 All packages that provide applications that need not be
1865 passed any special command line arguments for normal
1866 operation should register a menu entry for those
1867 applications, so that users of the <tt>menu</tt> package
1868 will automatically get menu entries in their window
1869 managers, as well in shells like <tt>pdmenu</tt>.</p>
1872 Please refer to the <em>Debian Menu System</em> document
1873 that comes with the <tt>menu</tt> package for information
1874 about how to register your applications and web
1880 <heading>Multimedia handlers</heading>
1883 Packages which provide the ability to view/show/play,
1884 compose, edit or print MIME types should register themselves
1885 as such following the current MIME support policy as defined
1886 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1887 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1888 or your local mirror. In addition, it is included in the
1889 <tt>debian-policy</tt> package.
1893 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1894 mechanism for encoding files and data streams and providing
1895 meta-information about them, in particular their type (e.g.
1896 audio or video) and format (e.g. PNG, HTML, MP3).
1900 Registration of MIME type handlers allows programs like mail
1901 user agents and web browsers to to invoke these handlers to
1902 view, edit or display MIME types they don't support
1908 <heading>Keyboard configuration</heading>
1911 To achieve a consistent keyboard configuration (i.e., all
1912 applications interpret a keyboard event the same way) all
1913 programs in the Debian distribution have to be configured to
1914 comply with the following guidelines.</p>
1917 Here is a list that contains certain keys and their interpretation:
1920 <tag><tt><--</tt></tag>
1921 <item><p>delete the character to the left of the cursor</p></item>
1923 <tag><tt>Delete</tt></tag>
1924 <item><p>delete the character to the right of the cursor</p></item>
1926 <tag><tt>Control+H</tt></tag>
1927 <item><p>emacs: the help prefix</p></item>
1930 The interpretation of any keyboard events should be independent
1931 of the terminal that's used, be it a virtual console, an X
1932 terminal emulator, an rlogin/telnet session, etc.</p>
1935 The following list explains how the different programs
1936 should be set up to achieve this:</p>
1939 <list compact="compact">
1940 <item><p>`<tt><--</tt>' generates KB_Backspace in
1943 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1947 X translations are set up to make KB_Backspace
1948 generate ASCII DEL, and to make KB_Delete generate
1949 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1950 the `delete character' key). This must be done by
1951 loading the resources using xrdb on all local X
1952 displays, not using the application defaults, so that
1953 the translation resources used correspond to the
1954 xmodmap settings.</p></item>
1958 The Linux console is configured to make
1959 `<tt><--</tt>' generate DEL, and `Delete' generate
1960 <tt>ESC [ 3 ~</tt> (this is the case at the
1964 X applications are configured so that Backspace
1965 deletes left, and Delete deletes right. Motif
1966 applications already work like this.</p></item>
1968 <item><p>stty erase <tt>^?</tt> .</p></item>
1971 The `xterm' terminfo entry should have <tt>ESC [ 3
1972 ~</tt> for kdch1, just like TERM=linux and
1973 TERM=vt220.</p></item>
1976 Emacs is programmed to map KB_Backspace or the `stty
1977 erase' character to delete-backward-char, and
1978 KB_Delete or kdch1 to delete-forward-char, and
1979 <tt>^H</tt> to help as always.</p></item>
1982 Other applications use the `stty erase' character and
1983 kdch1 for the two delete keys, with ASCII DEL being
1984 `delete previous character' and kdch1 being `delete
1985 character under cursor'.</p></item>
1989 This will solve the problem except for:</p>
1992 <list compact="compact">
1994 Some terminals have a <tt><--</tt> key that cannot
1995 be made to produce anything except <tt>^H</tt>. On
1996 these terminals Emacs help will be unavailable on
1997 <tt>^H</tt> (assuming that the `stty erase' character
1998 takes precedence in Emacs, and has been set
1999 correctly). M-x help or F1 (if available) can be used
2003 Some operating systems use <tt>^H</tt> for stty erase.
2004 However, modern telnet versions and all rlogin
2005 versions propagate stty settings, and almost all UNIX
2006 versions honour stty erase. Where the stty settings
2007 are not propagated correctly things can be made to
2008 work by using stty manually.</p></item>
2011 Some systems (including previous Debian versions) use
2012 xmodmap to arrange for both <tt><--</tt> and Delete
2013 to generate KB_Delete. We can change the behavior
2014 of their X clients via the same X resources that we
2015 use to do it for our own, or have our clients be
2016 configured via their resources when things are the
2017 other way around. On displays configured like this
2018 Delete will not work, but <tt><--</tt>
2022 Some operating systems have different kdch1 settings
2023 in their terminfo for xterm and others. On these
2024 systems the Delete key will not work correctly when
2025 you log in from a system conforming to our policy, but
2026 <tt><--</tt> will.</p></item>
2033 <heading>Environment variables</heading>
2036 No program may depend on environment variables to get
2037 reasonable defaults. (That's because these environment
2038 variables would have to be set in a system-wide
2039 configuration file like /etc/profile, which is not supported
2043 If a program should depend on environment variables for its
2044 configuration, the program has to be changed to fall back to
2045 a reasonable default configuration if these environment
2046 variables are not present. If this cannot be done easily
2047 (e.g., if the source code of a non-free program is not
2048 available), the program should be replaced by a small
2049 `wrapper' shell script which sets the environment variables
2050 and calls the original program.</p>
2053 Here is an example of a wrapper script for this purpose:
2059 exec /usr/lib/foo/foo "$@"
2063 Furthermore, as <tt>/etc/profile</tt> is a configuration
2064 file of the <prgn>bash</prgn> package, no other package may
2065 put any environment variables or other commands into that
2070 <heading>Files</heading>
2074 <heading>Binaries</heading>
2077 It is not allowed that two packages install programs with
2078 different functionality but with the same filenames. (The
2079 case of two programs having the same functionality but
2080 different implementations is handled via `alternatives.')
2081 If this case happens, one of the programs has to be
2082 renamed. The maintainers should report this to the
2083 developers' mailing and try to find a consensus about
2084 which package will have to be renamed. If a consensus can
2085 not be reached, <em>both</em> programs must be
2089 Generally the following compilation parameters should be used:
2092 CFLAGS = -O2 -Wall # sane warning options vary between programs
2094 install -s # (or use strip on the files in debian/tmp)
2098 Note that by default all installed binaries should be stripped,
2099 either by using the <tt>-s</tt> flag to
2100 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2101 the binaries after they have been copied into
2102 <tt>debian/tmp</tt> but before the tree is made into a
2106 The <tt>-N</tt> flag should not be used. On a.out systems
2107 it may have been useful for some very small binaries, but
2108 for ELF it has no good effect.</p>
2111 Debugging symbols are useful for error diagnosis, investigation
2112 of core dumps (which may be submitted by users in bug reports),
2113 or testing and developing the software. Therefore it is
2114 recommended to support building the package with
2115 debugging information through the following interface:
2116 If the environment variable <tt>DEB_BUILD_OPTIONS</tt>
2117 contains the string <tt>debug</tt>, compile the software with
2118 debugging information (usually this involves adding the
2119 <tt>-g</tt> flag to <tt>CFLAGS</tt>). This allows to generate
2120 a build tree with debugging information. If the environment
2121 variable <tt>DEB_BUILD_OPTIONS</tt> contains the
2122 string <tt>nostrip</tt>, do not strip the files at installation
2123 time. This allows to generate a package with debugging
2124 information included. The following makefile snippet
2125 is only an example how to test for either
2129 Rationale: Building by default with -g causes more
2130 wasted CPU cycles since the information is stripped away
2131 anyway. The package can by default build without -g if
2132 it also provides a mechanism to easily be rebuilt with
2133 debugging information. This can be done by providing a
2134 "build-debug" make target, or allowing the user to
2135 specify "BUILD_DEBUG=yes" in the environment while
2136 compiling that package.
2138 <p>Now this has several added benefits:
2142 It is actually easier to build debugging bins and
2143 libraries this way (no more editing debian/rules
2144 or similar) since it provides a documented way of
2145 getting this type of build.</p>
2149 There will be much less wasted cpu time for the
2150 autobuilders since not having debugging
2151 information (and hence also not having to strip
2152 it) will increase the speed of compiles. This
2153 skips an entire pass of the compiler,
2164 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
2166 ifneq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
2173 It is up to the package maintainer to decide what
2174 compilation options are best for the package. Certain
2175 binaries (such as computationally-intensive programs) may
2176 function better with certain flags (<tt>-O3</tt>, for
2177 example); feel free to use them. Please use good judgment
2178 here. Don't use flags for the sake of it; only use them
2179 if there is good reason to do so. Feel free to override
2180 the upstream author's ideas about which compilation
2181 options are best--they are often inappropriate for our
2182 environment.</p></sect>
2186 <heading>Libraries</heading>
2189 All libraries must have a shared version in the lib
2190 package and a static version in the lib-dev package. The
2191 shared version must be compiled with <tt>-fPIC</tt>, and
2192 the static version must not be. In other words, each
2193 <tt>*.c</tt> file is compiled twice.</p>
2196 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2197 when building a library (either static or shared) to make
2198 the library compatible with LinuxThreads.</p>
2201 Note that all installed shared libraries should be
2204 strip --strip-unneeded <your-lib>
2206 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2207 only the symbols which aren't needed for relocation
2208 processing.) Shared libraries can function perfectly well
2209 when stripped, since the symbols for dynamic linking are
2210 in a separate part of the ELF object file.</p>
2213 Note that under some circumstances it may be useful to
2214 install a shared library unstripped, for example when
2215 building a separate package to support debugging.
2219 An ever increasing number of packages are using libtool to
2220 do their linking. The latest GNU libtools (>= 1.3a) can take
2221 advantage of the metadata in the installed libtool archive
2222 files (`*.la'). The main advantage of libtool's .la files is
2223 that it allows libtool to store and subsequently access
2224 metadata with respect to the libraries it builds. libtool
2225 will search for those files, which contain a lot of useful
2226 information about a library (e.g. dependency libraries for
2227 static linking). Also, they're <em>essential</em> for
2228 programs using libltdl.
2232 Certainly libtool is fully capable of linking against shared
2233 libraries which don't have .la files, but being a mere shell
2234 script it can add considerably to the build time of a
2235 libtool using package if that shell-script has to derive all
2236 this information from first principles for each library every
2237 time it is linked. With the advent of libtool-1.4 (and to a
2238 lesser extent libtool-1.3), the .la files will also store
2239 information about inter-library dependencies which cannot
2240 necessarily be derived after the .la file is deleted.
2244 Packages that use libtool to create shared libraries must
2245 include the <em>.la</em> files in the <em>-dev</em>
2246 packages, with the exception that if the package relies on
2247 libtool's <em>libltdl</em> library, in which case the .la
2248 files must go in the run-time library package. This is a
2249 good idea in general, and especially for static linking
2254 Please make sure that you use only released versions of
2255 shared libraries to build your packages; otherwise other
2256 users will not be able to run your binaries
2257 properly. Producing source packages that depend on
2258 unreleased compilers is also usually a bad
2265 <heading>Shared libraries</heading>
2268 Packages involving shared libraries should be split up
2269 into several binary packages.</p>
2272 For a straightforward library which has a development
2273 environment and a runtime kit including just shared
2274 libraries you need to create two packages:
2275 <tt><var>libraryname</var><var>soname</var></tt>
2276 (<var>soname</var> is the shared object name of the shared
2277 library--it's the thing that has to match exactly between
2278 building an executable and running it for the dynamic
2279 linker to be able run the program; usually the
2280 <var>soname</var> is the major number of the library) and
2281 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2284 If you prefer only to support one development version at a
2285 time you may name the development package
2286 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2287 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2288 ensure that the user only installs one development version
2289 at a time (after all, different development versions are
2290 likely to have the same header files in them, causing a
2291 filename clash if both are installed). Typically the
2292 development version will also need an exact version
2293 dependency on the runtime library, to make sure that
2294 compilation and linking happens correctly.</p>
2297 Packages which use the shared library should have a
2298 dependency on the name of the shared library package,
2299 <tt><var>libraryname</var><var>soname</var></tt>. When
2300 the <var>soname</var> changes you can have both versions
2301 of the library installed while moving from the old library
2305 If your package has some run-time support programs which
2306 use the shared library you must <em>not</em> put them in
2307 the shared library package. If you do that then you won't
2308 be able to install several versions of the shared library
2309 without getting filename clashes. Instead, either create
2310 a third package for the runtime binaries (this package
2311 might typically be named
2312 <tt><var>libraryname</var>-runtime</tt>--note the absence
2313 of the <var>soname</var> in the package name) or if the
2314 development package is small include them in there.</p>
2317 If you have several shared libraries built from the same
2318 source tree you can lump them all together into a single
2319 shared library package, provided that you change all their
2320 <var>soname</var>s at once (so that you don't get filename
2321 clashes if you try to install different versions of the
2322 combined shared libraries package).</p>
2325 Follow the directions in the <em>Debian Packaging
2326 Manual</em> for putting the shared library in its package,
2327 and make sure you include a <tt>shlibs</tt> control area
2328 file with details of the dependencies for packages which
2329 use the library.</p>
2332 Shared libraries should <em>not</em> be installed
2333 executable, since <prgn>ld.so</prgn> does not require this
2334 and trying to execute a shared library results in a core
2339 <heading>Scripts</heading>
2342 All command scripts, including the package maintainer
2343 scripts inside the package and used by <prgn>dpkg</prgn>,
2344 should have a <tt>#!</tt> line naming the shell to be used
2345 to interpret them.</p>
2348 In the case of Perl scripts this should be
2349 <tt>#!/usr/bin/perl</tt>.</p>
2352 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2353 should almost certainly start with <tt>set -e</tt> so that
2354 errors are detected. Every script <em>must</em> use
2355 <tt>set -e</tt> or check the exit status of <em>every</em>
2359 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2360 symbolic link to any POSIX compatible shell. Thus, shell
2361 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2362 only use POSIX features. If a script requires non-POSIX
2363 features from the shell interpreter, the appropriate shell
2364 has to be specified in the first line of the script (e.g.,
2365 `<tt>#!/bin/bash</tt>') and the package has to depend on
2366 the package providing the shell (unless the shell package
2367 is marked `Essential', e.g., in the case of
2368 <prgn>bash</prgn>).</p>
2371 Restrict your script to POSIX features when possible so
2372 that it may use <tt>/bin/sh</tt> as its interpreter. If
2373 your script works with <prgn>ash</prgn>, it's probably
2374 POSIX compliant, but if you are in doubt, use
2375 <tt>/bin/bash</tt>.</p>
2378 Perl scripts should check for errors when making any
2379 system calls, including <tt>open</tt>, <tt>print</tt>,
2380 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2383 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2384 as scripting languages. See <em>Csh Programming
2385 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2386 FAQs. It can be found on
2387 <url id="http://language.perl.com/versus/csh.whynot">, or
2388 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2389 or even on <ftpsite>ftp.cpan.org</ftpsite>
2390 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2391 If an upstream package comes with <prgn>csh</prgn> scripts
2392 then you must make sure that they start with
2393 <tt>#!/bin/csh</tt> and make your package depend on the
2394 <prgn>c-shell</prgn> virtual package.</p>
2397 Any scripts which create files in world-writable
2398 directories (e.g., in <tt>/tmp</tt>) have to use a
2399 mechanism which will fail if a file with the same name
2403 The Debian base distribution provides the
2404 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2405 for use by scripts for this purpose.</p></sect>
2409 <heading>Symbolic links</heading>
2412 In general, symbolic links within a top-level directory
2413 should be relative, and symbolic links pointing from one
2414 top-level directory into another should be absolute. (A
2415 top-level directory is a sub-directory of the root
2419 In addition, symbolic links should be specified as short
2420 as possible, i.e., link targets like `foo/../bar' are
2424 Note that when creating a relative link using
2425 <prgn>ln</prgn> it is not necessary for the target of the
2426 link to exist relative to the working directory you're
2427 running <prgn>ln</prgn> from; nor is it necessary to
2428 change directory to the directory where the link is to be
2429 made. Simply include the string that should appear as the
2430 target of the link (this will be a pathname relative to
2431 the directory in which the link resides) as the first
2432 argument to <prgn>ln</prgn>.</p>
2435 For example, in your <prgn>Makefile</prgn> or
2436 <tt>debian/rules</tt>, do things like:
2438 ln -fs gcc $(prefix)/bin/cc
2439 ln -fs gcc debian/tmp/usr/bin/cc
2440 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2441 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2445 A symbolic link pointing to a compressed file should
2446 always have the same file extension as the referenced
2447 file. (For example, if a file `<tt>foo.gz</tt>' is
2448 referenced by a symbolic link, the filename of the link
2449 has to end with `<tt>.gz</tt>' too, as in
2450 `bar.gz.')</p></sect>
2454 <heading>Device files</heading>
2457 No package may include device files in the package file
2461 If a package needs any special device files that are not
2462 included in the base system, it has to call
2463 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2464 after asking the user for permission to do so.</p>
2467 No package should remove any device files in the
2468 <tt>postrm</tt> or any other script. This is left to the
2469 system administrator.</p>
2472 Debian uses the serial devices
2473 <tt>/dev/tty*</tt>. Programs using the old
2474 <tt>/dev/cu*</tt> devices should be changed to use
2475 <tt>/dev/tty*</tt>.</p>
2478 <sect id="config files">
2479 <heading>Configuration files</heading>
2481 <heading>Definitions</heading>
2484 <tag>configuration file</tag>
2486 A file that affects the operation of program, or
2487 provides site- or host-specific information, or
2488 otherwise customizes the behavior of program.
2489 Typically, configuration files are intended to be
2490 modified by the system administrator (if needed or
2491 desired) to conform to local policy or provide more
2492 useful site-specific behavior.</p>
2495 <tag><tt>conffile</tt></tag>
2497 A file listed in a package's <tt>conffiles</tt>
2498 file, and is treated specially by <prgn>dpkg</prgn>
2499 (see the <em>Debian Packaging Manual</em>).</p>
2505 The distinction between these two is important; they are
2506 not interchangeable concepts. Almost all
2507 <tt>conffiles</tt> are configuration files, but many
2508 configuration files are not <tt>conffiles</tt>.</p>
2511 Note that a script that embeds configuration information
2512 (such as most of the files in <tt>/etc/init.d</tt> and
2513 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2514 configuration file and should be treated as such.</p>
2518 <heading>Location</heading>
2520 Any configuration files created or used by your package
2521 should reside in <tt>/etc</tt>. If there are several you
2522 should consider creating a subdirectory of <tt>/etc</tt>
2523 named after your package.</p>
2526 If your packages creates or uses configuration files
2527 outside of <tt>/etc</tt>, and it is not feasible to modify
2528 the package to use the <tt>/etc</tt>, you should still put
2529 the files in <tt>/etc</tt> and create symbolic links to
2530 those files from the location that the package
2535 <heading>Behavior</heading>
2537 Configuration file handling must conform to the following
2541 <p>local changes must be preserved during a package
2545 <p>configuration files should be preserved when the
2546 package is removed, and only deleted when the
2547 package is purged.</p>
2552 The easy way to achieve this behavior is to make the
2553 configuration file a <tt>conffile</tt>. This is
2554 appropriate if it is possible to distribute a default
2555 version that will work for most installations, although
2556 some system administrators may choose to modify it. This
2557 implies that the default version will be part of the
2558 package distribution, and must not be modified by the
2559 maintainer scripts during installation (or at any other
2563 The other way to do it is to via the maintainer scripts.
2564 In this case, the configuration file must not be listed as
2565 a <tt>conffile</tt> and must not be part of the package
2566 distribution. If the existence of a file is required for
2567 the package to be sensibly configured it is the
2568 responsibility of the package maintainer to write scripts
2569 which correctly create, update, maintain and
2570 remove-on-purge the file. These scripts must be idempotent
2571 (i.e. must work correctly if <prgn>dpkg</prgn> needs to
2572 re-run them due to errors during installation or removal),
2573 must cope with all the variety of ways <prgn>dpkg</prgn>
2574 can call maintainer scripts, must not overwrite or
2575 otherwise mangle the user's configuration without asking,
2576 must not ask unnecessary questions (particularly during
2577 upgrades), and otherwise be good citizens.</p>
2580 The scripts need not configure every possible option for
2581 the package, but only those necessary to get the package
2582 running on a given system. Ideally the sysadmin should not
2583 have to do any configuration other than that done
2584 (semi-)automatically by the <tt>postinst</tt> script.</p>
2587 A common practice is to create a script called
2588 <tt><var>package</var>-configure</tt> and have the
2589 package's <tt>postinst</tt> call it if and only if the
2590 configuration file does not already exist. In certain
2591 cases it is useful for there to be an example or template
2592 file which the maintainer scripts use. Such files should
2593 be in <tt>/usr/share/doc</tt> if they are examples or
2594 <tt>/usr/lib</tt> if they are templates, and should be
2595 perfectly ordinary <prgn>dpkg</prgn>-handled files
2596 (<em>not</em> <tt>conffiles</tt>).</p>
2599 These two styles of configuration file handling <em>must
2600 not be mixed</em>, for that way lies madness:
2601 <prgn>dpkg</prgn> will ask about overwriting the file
2602 every time the package is upgraded.</p>
2606 <heading>Sharing configuration files</heading>
2608 Only packages that are tagged <em>conflicting</em> with
2609 each other may specify the same file as
2610 <tt>conffile</tt>.</p>
2613 The maintainer scripts should not alter the conffile of
2614 <em>any</em> package, including the one the scripts belong
2618 If two or more packages use the same configuration file
2619 and it is reasonable for both to be installed at the same
2620 time, one of these packages must be defined as
2621 <em>owner</em> of the configuration file, i.e. it will be
2622 the package to list that distributes the file and lists it
2623 as a <tt>conffile</tt>. Other packages that use the
2624 configuration file should depend on the owning package if
2625 they require the configuration file to operate. If the
2626 other package will use the configuration file if present,
2627 but is capable of operating without it, no dependency need
2631 If it is desirable for two or more related packages to
2632 share a configuration file <em>and</em> for all of the
2633 related packages to be able to modify that configuration
2634 file, then the following should done:
2638 have one of the related packages (the "core"
2639 package) manage the configuration file with
2640 maintainer scripts as described in the previous
2644 the core package should also provide a program that
2645 the other packages may use to modify the
2646 configuration file.</p>
2650 the related packages must use the provided program
2651 to make any modifications to the configuration file.
2652 They should either depend on the core package to
2653 guarantee that the configuration modifier program is
2654 available or accept gracefully that they cannot
2655 modify the configuration file if it is not.</p>
2660 Sometimes it's appropriate to create a new package which
2661 provides the basic infrastructure for the other packages
2662 and which manages the shared configuration files. (Check
2663 out the <tt>sgml-base</tt> package as an example.)</p>
2667 <heading>User configuration files ("dotfiles")</heading>
2670 Files in <tt>/etc/skel</tt> will automatically be copied
2671 into new user accounts by <prgn>adduser</prgn>. They
2672 should not be referenced there by any program.</p>
2675 Therefore, if a program needs a dotfile to exist in
2676 advance in <tt>$HOME</tt> to work sensibly that dotfile
2677 should be installed in <tt>/etc/skel</tt> (and listed in
2678 conffiles, if it is not generated and modified dynamically
2679 by the package's installation scripts).</p>
2682 However, programs that require dotfiles in order to
2683 operate sensibly (dotfiles that they do not create
2684 themselves automatically, that is) are a bad thing, and
2685 programs should be configured by the Debian default
2686 installation as close to normal as possible.</p>
2689 Therefore, if a program in a Debian package needs to be
2690 configured in some way in order to operate sensibly that
2691 configuration should be done in a site-wide global
2692 configuration file elsewhere in <tt>/etc</tt>. Only if the
2693 program doesn't support a site-wide default configuration
2694 and the package maintainer doesn't have time to add it
2695 should a default per-user file be placed in
2696 <tt>/etc/skel</tt>.</p>
2699 <tt>/etc/skel</tt> should be as empty as we can make it.
2700 This is particularly true because there is no easy
2701 mechanism for ensuring that the appropriate dotfiles are
2702 copied into the accounts of existing users when a package
2708 <heading>Log files</heading>
2710 The traditional approach to log files has been to set up ad
2711 hoc log rotation schemes using simple shell scripts and
2712 cron. While this approach is highly customizable, it
2713 requires quite a lot of sysadmin work. Even though the
2714 original Debian system helped a little by automatically
2715 installing a system which can be used as a template, this
2716 was deemed not enough.
2720 A better scheme is to use logrotate, a GPL'd program
2721 developed by Red Hat, which centralizes log management. It
2722 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2723 and a directory where packages can drop logrotation info
2724 (<tt>/etc/logrotate.d</tt>).
2728 Log files should usually be named
2729 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2730 log files, or need a separate directory for permissions
2731 reasons (<tt>/var/log</tt> is writable only by
2732 <tt>root</tt>), you should usually create a directory named
2733 <tt>/var/log/<var>package</var></tt>.</p>
2736 Make sure that any log files are rotated occasionally so
2737 that they don't grow indefinitely; the best way to do this
2738 is to drop a script into the directory
2739 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2740 logrotate. Here is a good example for a logrotate config
2741 file (for more information see <manref name="logrotate"
2749 /etc/init.d/foo force-reload
2753 Which rotates all files under `/var/log/foo', saves 12
2754 compressed generations, and sends a HUP signal at the end of
2760 Make sure that any log files are removed when the package is
2761 purged (but not when it is only removed), by checking the
2762 argument to the <tt>postrm</tt> script (see the <em>Debian
2763 Packaging Manual</em> for details).</p>
2768 <heading>Permissions and owners</heading>
2771 The rules in this section are guidelines for general use.
2772 If necessary you may deviate from the details below.
2773 However, if you do so you must make sure that what is done
2774 is secure and you must try to be as consistent as possible
2775 with the rest of the system. You should probably also
2776 discuss it on <prgn>debian-devel</prgn> first.</p>
2779 Files should be owned by <tt>root.root</tt>, and made
2780 writable only by the owner and universally readable (and
2781 executable, if appropriate).</p>
2784 Directories should be mode 755 or (for group-writability)
2785 mode 2775. The ownership of the directory should be
2786 consistent with its mode--if a directory is mode 2775, it
2787 should be owned by the group that needs write access to
2791 Setuid and setgid executables should be mode 4755 or 2755
2792 respectively, and owned by the appropriate user or group.
2793 They should not be made unreadable (modes like 4711 or
2794 2711 or even 4111); doing so achieves no extra security,
2795 because anyone can find the binary in the freely available
2796 Debian package--it is merely inconvenient. For the same
2797 reason you should not restrict read or execute permissions
2798 on non-set-id executables.</p>
2801 Some setuid programs need to be restricted to particular
2802 sets of users, using file permissions. In this case they
2803 should be owned by the uid to which they are set-id, and
2804 by the group which should be allowed to execute them.
2805 They should have mode 4754; there is no point in making
2806 them unreadable to those users who must not be allowed to
2810 Do not arrange that the system administrator can only
2811 reconfigure the package to correspond to their local
2812 security policy by changing the permissions on a binary.
2813 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2814 to conffiles and other similar objects) have their
2815 permissions reset to the distributed permissions when the
2816 package is reinstalled. Instead you should consider (for
2817 example) creating a group for people allowed to use the
2818 program(s) and making any setuid executables executable
2819 only by that group.</p>
2822 If you need to create a new user or group for your package
2823 there are two possibilities. Firstly, you may need to
2824 make some files in the binary package be owned by this
2825 user or group, or you may need to compile the user or
2826 group id (rather than just the name) into the binary
2827 (though this latter should be avoided if possible). In
2828 this case you need a statically allocated id.</p>
2831 You must ask for a user or group id from the base system
2832 maintainer, and must not release the package until you
2833 have been allocated one. Once you have been allocated one
2834 you must make the package depend on a version of the base
2835 system with the id present in <tt>/etc/passwd</tt> or
2836 <tt>/etc/group</tt>, or alternatively arrange for your
2837 package to create the user or group itself with the
2838 correct id (using <tt>adduser</tt>) in its pre- or
2839 post-installation script (the latter is to be preferred if
2840 it is possible).</p>
2843 On the other hand, the program may able to determine the
2844 uid or gid from the group name at runtime, so that a
2845 dynamic id can be used. In this case you must choose an
2846 appropriate user or group name, discussing this on
2847 <prgn>debian-devel</prgn> and checking with the base
2848 system maintainer that it is unique and that they do not
2849 wish you to use a statically allocated id instead. When
2850 this has been checked you must arrange for your package to
2851 create the user or group if necessary using
2852 <prgn>adduser</prgn> in the pre- or post-installation
2853 script (again, the latter is to be preferred if it is
2857 Note that changing the numeric value of an id associated with a name
2858 is very difficult, and involves searching the file system for all
2859 appropriate files. You need to think carefully whether a static or
2860 dynamic id is required, since changing your mind later will cause
2866 <heading>Customized programs</heading>
2868 <sect id="arch-spec">
2869 <heading>Architecture specification strings</heading>
2872 If a program needs to specify an <em>architecture specification
2873 string</em> in some place, the following format has to be used:
2875 <arch>-<os>
2877 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2878 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2879 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2880 operating system. .</p>
2882 Note, that we don't want to use `<arch>-debian-linux'
2883 to apply to the rule `architecture-vendor-os' since this
2884 would make our programs incompatible to other Linux
2885 distributions. Also note, that we don't use
2886 `<arch>-unknown-linux', since the `unknown' does not
2887 look very good.</p></sect>
2891 <heading>Daemons</heading>
2894 The configuration files <tt>/etc/services</tt>,
2895 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2896 by the <prgn>netbase</prgn> package and may not be modified
2897 by other packages.</p>
2900 If a package requires a new entry in one of these files, the
2901 maintainer has to get in contact with the
2902 <prgn>netbase</prgn> maintainer, who will add the entries
2903 and release a new version of the <prgn>netbase</prgn>
2907 The configuration file <tt>/etc/inetd.conf</tt> may be
2908 modified by the package's scripts only via the
2909 <prgn>update-inetd</prgn> script or the
2910 <prgn>DebianNet.pm</prgn> Perl module.</p>
2913 If a package wants to install an example entry into
2914 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2915 exactly one hash character (<tt>#</tt>). Such lines are
2916 treated as `commented out by user' by the
2917 <prgn>update-inetd</prgn> script and are not changed or
2918 activated during a package updates.</p></sect>
2922 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2925 Some programs need to create pseudo-ttys. This should be done
2926 using Unix98 ptys if the C library supports it. The resulting
2927 program must not be installed setuid root, unless that
2928 is required for other functionality.
2932 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2933 <tt>/var/log/lastlog</tt> must be installed writeable by
2934 group utmp. Programs who need to modify those files must
2935 be installed install setgid utmp.
2940 <heading>Editors and pagers</heading>
2943 Some programs have the ability to launch an editor or pager
2944 program to edit or display a text document. Since there are
2945 lots of different editors and pagers available in the Debian
2946 distribution, the system administrator and each user should
2947 have the possibility to choose his/her preferred editor and
2951 In addition, every program should choose a good default
2952 editor/pager if none is selected by the user or system
2956 Thus, every program that launches an editor or pager has to
2957 use the EDITOR or PAGER environment variables to determine
2958 the editor/pager the user wants to get started. If these
2959 variables are not set, the programs <tt>/usr/bin/editor</tt>
2960 and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
2963 These two files are managed through `alternatives.' That is,
2964 every package providing an editor or pager has to call the
2965 <prgn>update-alternatives</prgn> script to register these
2969 If it is very hard to adapt a program to make us of the
2970 EDITOR and PAGER variable, that program should be configured
2971 to use <tt>/usr/bin/sensible-editor</tt> and
2972 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
2973 respectively. These are two scripts provided in the Debian
2974 base system that check the EDITOR and PAGER variables and
2975 launches the appropriate program or falls back to
2976 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
2980 A program may also use the VISUAL environment variable to
2981 determine the user's choice of editor. If it exists, it
2982 should take precedence over EDITOR. This is in fact what
2983 <tt>/usr/bin/sensible-editor</tt> does.</p>
2986 Since the Debian base system already provides an editor and
2987 a pager program, there is no need for a package to depend on
2988 `editor' and `pager', nor is it necessary for a package to
2989 provide such virtual packages.</p></sect>
2992 <sect id="web-appl">
2993 <heading>Web servers and applications</heading>
2996 This section describes the locations and URLs that have to
2997 be used by all web servers and web application in the Debian
3003 <p>Cgi-bin executable files are installed in the
3006 /usr/lib/cgi-bin/<cgi-bin-name>
3008 and can be referred to as
3010 http://localhost/cgi-bin/<cgi-bin-name>
3011 </example></p></item>
3014 <item><p>Access to html documents</p>
3017 Html documents for a package are stored in
3018 <tt>/usr/share/doc/<var>package</var></tt> but should
3019 be accessed via symlinks as
3020 <tt>/usr/doc/<var>package</var></tt><footnote> for
3021 backward compatibility, see <ref id="usrdoc"></footnote>
3022 and can be referred to as
3024 http://localhost/doc/<package>/<filename>
3025 </example></p></item>
3028 <item><p>Web Document Root</p>
3031 Web Applications should try to avoid storing files in
3032 the Web Document Root. Instead use the
3033 /usr/share/doc/<package> directory for documents and
3034 register the Web Application via the menu package. If
3035 access to the web-root is unavoidable then use
3039 as the Document Root. This might be just a
3040 symbolic link to the location where the sysadmin has
3041 put the real document root.</p>
3044 </enumlist></p></sect>
3048 <heading>Mail transport agents</heading>
3051 Debian packages which process electronic mail, whether
3052 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
3053 <em>must</em> make sure that they are compatible with the
3054 configuration decisions below. Failure to do this may
3055 result in lost mail, broken <tt>From:</tt> lines, and other
3056 serious brain damage!</p>
3059 The mail spool is <tt>/var/spool/mail</tt> and the interface
3060 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3061 per the FHS). The mail spool is part of the base system
3062 and not part of the MTA package.</p>
3065 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3066 programs (like IMAP daemons) have to lock the mailbox in a
3067 NFS-safe way. This means that <tt>fcntl()</tt> locking has
3068 to be combined with dot locking. To avoid dead locks, a
3069 program has to use <tt>fcntl()</tt> first and dot locking
3070 after this or alternatively implement the two locking
3071 methods in a non blocking way<footnote>
3073 If it is not possible to establish both locks, the
3074 system shouldn't wait for the second lock to be
3075 established, but remove the first lock, wait a (random)
3076 time, and start over locking again.</p>
3077 </footnote>. Using the functions <tt>maillock</tt> and
3078 <tt>mailunlock</tt> provided by the
3079 <tt>liblockfile*</tt><footnote>
3081 <tt>liblockfile</tt> version >>1.01</p>
3082 </footnote> packages is the recommended way to realize this.
3086 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3087 unless the user has chosen otherwise. A MUA may remove a
3088 mailbox (unless it has nonstandard permissions) in which
3089 case the MTA or another MUA must recreate it if needed.
3090 Mailboxes must be writable by group mail.</p>
3093 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
3094 be setgid mail to do the locking mentioned above (and
3095 obviously need to avoid accessing other users' mailboxes
3096 using this privilege).</p>
3099 <tt>/etc/aliases</tt> is the source file for the system mail
3100 aliases (e.g., postmaster, usenet, etc.)--it is the one
3101 which the sysadmin and <tt>postinst</tt> scripts may edit.
3102 After <tt>/etc/aliases</tt> is edited the program or human
3103 editing it must call <prgn>newaliases</prgn>. All MTA
3104 packages should come with a <prgn>newaliases</prgn> program,
3105 even if it does nothing, but older MTA packages do not do
3106 this so programs should not fail if <prgn>newaliases</prgn>
3107 cannot be found.</p>
3110 The convention of writing <tt>forward to
3111 <var>address</var></tt> in the mailbox itself is not
3112 supported. Use a <tt>.forward</tt> file instead.</p>
3115 The location for the <prgn>rmail</prgn> program used by UUCP
3116 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
3117 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3118 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
3122 If you need to know what name to use (for example) on
3123 outgoing news and mail messages which are generated locally,
3124 you should use the file <tt>/etc/mailname</tt>. It will
3125 contain the portion after the username and <tt>@</tt> (at)
3126 sign for email addresses of users on the machine (followed
3130 A package should check for the existence of this file. If
3131 it exists it should use it without comment. (An MTA's
3132 prompting configuration script may wish to prompt the user
3133 even if it finds this file exists.) If it does not exist it
3134 should prompt the user for the value and store it in
3135 <tt>/etc/mailname</tt> as well as using it in the package's
3136 configuration. The prompt should make it clear that the
3137 name will not just be used by that package. For example, in
3138 this situation the INN package says:
3140 Please enter the `mail name' of your system. This is the
3141 hostname portion of the address to be shown on outgoing
3142 news and mail messages. The default is
3143 <var>syshostname</var>, your system's host name. Mail
3144 name [`<var>syshostname</var>']:
3146 where <var>syshostname</var> is the output of <tt>hostname
3147 --fqdn</tt>.</p></sect>
3151 <heading>News system configuration</heading>
3154 All the configuration files related to the NNTP (news)
3155 servers and clients should be located under
3156 <tt>/etc/news</tt>.</p>
3159 There are some configuration issues that apply to a number
3160 of news clients and server packages on the machine. These
3164 <tag>/etc/news/organization</tag>
3165 <item><p>A string which shall appear as the
3166 organization header for all messages posted
3167 by NNTP clients on the machine</p></item>
3169 <tag>/etc/news/server</tag>
3170 <item><p>Contains the FQDN of the upstream NNTP
3171 server, or localhost if the local machine is
3172 an NNTP server.</p></item>
3175 Other global files may be added as required for cross-package news
3176 configuration.</p></sect>
3180 <heading>Programs for the X Window System</heading>
3183 Some programs can be configured with or without support for the X
3184 Window System. Typically, binaries produced with support for X
3185 will need the X shared libraries to run.
3189 Such programs should be configured <em>with</em> X support,
3190 and should declare a dependency on <tt>xlib6g</tt> (which
3191 contains X shared libraries). Users who wish to use the
3192 program can install just the relatively small
3193 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
3194 not need to install the whole of X.
3196 <p>Note: With the release of the new X window System
3197 version (4.X), there probably shall be a sweeping change
3198 in the X Window System Policy in the future.</p>
3203 Do not create two versions (one with X support and one
3204 without) of your package.</p>
3207 <em>Packages which provide an X server</em> that, directly or
3208 indirectly, communicates with real input and display hardware
3209 should declare in their control data that they provide the
3210 virtual package <tt>xserver</tt>.
3213 Rationale: implement current practice, and provide an
3214 actual policy for usage of the "xserver" virtual package
3215 which appears in the virtual packages list.
3216 In a nutshell, X servers that interface directly with
3217 the display and input hardware or via another subsystem
3218 (e.g., GGI) should provide xserver. Things like Xvfb,
3219 Xnest, and Xprt should not.
3225 <em>Packages that provide a terminal emulator</em> for the X
3226 Window System which support a terminal type with a terminfo
3227 description provided in the <tt>ncurses-base</tt> package
3228 should declare in their control data that they provide the
3229 virtual package <tt>x-terminal-emulator</tt>. They should
3230 also register themselves as an alternative for
3231 <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
3236 <em>Packages that provide window managers</em> should declare in
3237 their control data that they provide the virtual package
3238 <tt>x-window-manager</tt>. They should also register themselves as an
3239 alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
3240 calculated as follows:
3242 <item>Start with a priority of 20.</item>
3243 <item>If the window manager supports the Debian menu system,
3244 add 20 points if this support is available in the
3245 package's default configuration (i.e., no
3246 configuration files belonging to the system or user
3247 have to be edited to activate the feature); if
3248 configuration files must be modified, add only 10
3250 <item>If the window manager permits the X session to be
3251 restarted using a <em>different</em> window manager
3252 (without killing the X server) in its default
3253 configuration, add 10 points; otherwise add
3259 <em>Packages that provide fonts for the X Window System</em>
3260 must do a number of things to ensure that they are both
3261 available without modification of the X or font server
3262 configuration, and that they do not corrupt files used by
3263 other font packages to register information about themselves.
3266 Fonts of any type supported by the X Window System
3267 should be be in a separate binary package from any
3268 executables, libraries, or documentation (except that
3269 specific to the fonts shipped); if a program or
3270 library is <em>unusable</em> without one or more
3271 specific fonts, the package containing the program or
3272 library should declare a dependency on the package(s)
3273 containing the font(s) it requires.
3276 BDF fonts should be converted to PCF fonts with the
3277 <tt>bdftopcf</tt> utility (available in the
3278 <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
3279 placed in a directory that corresponds to their
3283 100 dpi fonts should be placed in
3284 <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
3287 75 dpi fonts should be placed in
3288 <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
3291 Character-cell fonts, cursor fonts, and other
3292 low-resolution fonts should be placed in
3293 <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
3298 Speedo fonts should be placed in
3299 <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
3302 Type 1 fonts should be placed in
3303 /usr/X11R6/lib/X11/fonts/Type1/</tt>. If font metric files are
3304 available, they may be placed here as well.
3307 Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
3308 other than those listed above should be neither created nor
3309 used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
3310 excepted for historical reasons, but installation of files into
3311 these directories remains discouraged.)
3314 Font packages may, instead of placing files directly in
3315 the X font directories listed above, provide symbolic links in
3316 the font directory which point to the files' actual location
3317 in the filesystem. Such a location should comply with the
3321 Font packages should not contain both 75dpi and 100dpi
3322 versions of a font. If both are available, they should be
3323 provided in separate binary packages with "-75dpi" or "-100dpi"
3324 appended to the names of the packages containing the
3325 corresponding fonts.
3328 Fonts destined for the <tt>misc</tt> subdirectory should
3329 not be included in the same package as 75dpi or 100dpi fonts;
3330 instead, they should be provided in a separate package with
3331 "-misc" appended to its name.
3334 Font packages <em>must not</em> provide the files
3335 <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
3336 <tt>fonts.scale</tt> in a font directory.
3339 <tt>fonts.dir</tt> files must not be provided at
3343 <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
3344 files, if needed, should be provided in the
3346 <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
3347 where <em>fontdir</em> is the name of the
3349 <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
3350 package's corresponding fonts are stored (e.g.,
3351 <tt>75dpi</tt> or <tt>misc</tt>),
3352 <em>package</em> is the name of the package that
3353 provides these fonts, and <em>extension</em> is
3354 either <tt>scale</tt> or <tt>alias</tt>,
3355 whichever corresponds to the file
3361 Font packages must declare a dependency on
3362 <tt>xbase-clients</tt> and, in the package
3363 post-installation and post-removal scripts, invoke the
3364 <tt>mkfontdir</tt> command on each directory into
3365 which they installed fonts.
3368 Font packages that provide one or more
3369 <tt>fonts.scale</tt> files as described above must declare a
3370 versioned dependency on <tt>xbase-clients (>=
3371 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
3372 directory into which they installed fonts
3373 <em>before</em> invoking <tt>mkfontdir</tt> on that
3374 directory. This invocation must occur in both the
3375 post-installation and post-removal scripts.
3378 Font packages that provide one or more
3379 <tt>fonts.alias</tt> files as described above must
3380 declare a versioned dependency on <tt>xbase-clients
3381 (>= 3.3.3.1-5)</tt> and, in the package
3382 post-installation and post-removal scripts, invoke
3383 <tt>update-fonts-alias</tt> on each directory into
3384 which they installed fonts.
3387 Font packages must not provide alias names for the
3388 fonts they include which collide with alias names already in
3389 use by fonts already packaged.
3392 Font packages must not provide fonts with the same XLFD
3393 registry name as another font already packaged.
3399 <em>Application defaults</em> files must be installed in the
3400 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They should
3401 not be registered as <em>conffile</em>s or otherwise treated as
3402 configuration files. Customization of programs' X resources may
3403 be supported with the provision of a file with the same name as
3404 that of the package placed in the <tt>/etc/X11/Xresources/</tt>
3405 directory, which should be registered as a <em>conffile</em>.
3406 <em>Important:</em> packages that install files into the
3407 <tt>/etc/X11/Xresources/</tt> directory <em>must</em> declare a
3408 conflict with <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is
3409 not done it is possible for the installing package to destroy a
3410 previously-existing <tt>/etc/X11/Xresources</tt> <em>file</em>
3411 which had been customized by the system administrator.
3413 <p>Rationale: clarifies the language to properly
3414 address the package maintainer, not the system
3415 administrator, as to how to manage
3416 /etc/X11/Xresources.</p>
3422 <em>Packages using the X Window System should abide by the FHS
3423 standard whenever possible</em>; they should install binaries,
3424 libraries, manual pages, and other files in FHS-mandated
3425 locations wherever possible. This means that files should
3426 not be installed into <tt>/usr/X11R6/bin/</tt>,
3427 <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
3428 this is necessary for the package to operate properly.
3429 Configuration files for window managers and display managers
3430 should be placed in a subdirectory of <tt>/etc/X11/</tt>
3431 corresponding to the package name due to these programs'
3432 tight integration with the mechanisms of the X Window
3433 System. Application-level programs should use the
3434 <tt>/etc/</tt> directory unless otherwise mandated by
3435 policy. The installation of files into subdirectories of
3436 <tt>/usr/X11R6/include/X11/</tt> and
3437 <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
3438 package maintainers should determine if subdirectories of
3439 <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
3440 instead (symlinks from the X11R6 directories to
3441 FHS-compliant locations is encouraged if the program is not
3442 easily configured to look elsewhere for its files).
3443 Packages must not provide -- or install files into -- the
3444 directories <tt>/usr/bin/X11/</tt>,
3445 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
3446 Files within a package should, however, make reference to
3447 these directories, rather than their X11R6-named
3448 counterparts <tt>/usr/X11R6/bin/</tt>,
3449 <tt>/usr/X11R6/include/X11/</tt>, and
3450 <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
3451 referred to have not been moved to FHS-compliant locations.
3455 <em>Programs that require the non-DFSG-compliant OSF/Motif
3456 library</em> should be compiled against and tested with
3457 LessTif (a free re-implementation of Motif) instead. If the
3458 maintainer judges that the program or programs do not work
3459 sufficiently well with LessTif to be distributed and
3460 supported, but do so when compiled against Motif, then two
3461 versions of the package should be created; one linked
3462 statically against Motif and with <tt>-smotif</tt> appended
3463 to the package name, and one linked dynamically against
3464 Motif and with <tt>-dmotif</tt> appended to the package
3465 name. Both Motif-linked versions are dependent upon
3466 non-DFSG-compliant software and thus cannot be uploaded to
3467 the main distribution; if the software is itself
3468 DFSG-compliant it may be uploaded to the contrib
3469 distribution. While known existing versions of OSF/Motif
3470 permit unlimited redistribution of binaries linked against
3471 the library (whether statically or dynamically), it is the
3472 package maintainer's responsibility to determine whether
3473 this is permitted by the license of the copy of OSF/Motif in
3474 his or her possession.
3480 <heading>Emacs lisp programs</heading>
3483 Please refer to the `Debian Emacs Policy' (documented in
3484 <tt>debian-emacs-policy.gz</tt> of the
3485 <prgn>emacsen-common</prgn> package) for details of how to
3486 package emacs lisp programs.</p></sect>
3490 <heading>Games</heading>
3493 The permissions on /var/games are 755
3494 <tt>root.root</tt>.</p>
3497 Each game decides on its own security policy.</p>
3500 Games which require protected, privileged access to
3501 high-score files, savegames, etc., must be made
3502 set-<em>group</em>-id (mode 2755) and owned by
3503 <tt>root.games</tt>, and use files and directories with
3504 appropriate permissions (770 <tt>root.games</tt>, for
3505 example). They must <em>not</em> be made
3506 set-<em>user</em>-id, as this causes security problems. (If
3507 an attacker can subvert any set-user-id game they can
3508 overwrite the executable of any other, causing other players
3509 of these games to run a Trojan horse program. With a
3510 set-group-id game the attacker only gets access to less
3511 important game data, and if they can get at the other
3512 players' accounts at all it will take considerably more
3516 Some packages, for example some fortune cookie programs, are
3517 configured by the upstream authors to install with their
3518 data files or other static information made unreadable so
3519 that they can only be accessed through set-id programs
3520 provided. Do not do this in a Debian package: anyone can
3521 download the <tt>.deb</tt> file and read the data from it,
3522 so there is no point making the files unreadable. Not
3523 making the files unreadable also means that you don't have
3524 to make so many programs set-id, which reduces the risk of a
3528 As described in the FHS, binaries of games should be
3529 installed in the directory <tt>/usr/games</tt>. This also
3530 applies to games that use the X Window System. Manual pages
3531 for games (X and non-X games) should be installed in
3532 <tt>/usr/share/man/man6</tt>.</p>
3536 <chapt><heading>Documentation</heading>
3540 <heading>Manual pages</heading>
3543 You must install manual pages in <prgn>nroff</prgn> source
3544 form, in appropriate places under <tt>/usr/share/man</tt>. You
3545 should only use sections 1 to 9 (see the FHS for more
3546 details). You must <em>not</em> install a preformatted `cat
3550 If no manual page is available for a particular program,
3551 utility or function and this is reported as a bug on
3552 debian-bugs, a symbolic link from the requested manual page
3553 to the <manref name="undocumented" section="7"> manual page
3554 should be provided. This symbolic link can be created from
3555 <tt>debian/rules</tt> like this:
3557 ln -s ../man7/undocumented.7.gz \
3558 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3560 This manpage claims that the lack of a manpage has been
3561 reported as a bug, so you may only do this if it really has
3562 (you can report it yourself, if you like). Do not close the
3563 bug report until a proper manpage is available.</p>
3566 You may forward a complaint about a missing manpage to the
3567 upstream authors, and mark the bug as forwarded in the
3568 Debian bug tracking system. Even though the GNU Project do
3569 not in general consider the lack of a manpage to be a bug,
3570 we do--if they tell you that they don't consider it a bug
3571 you should leave the bug in our bug tracking system open
3575 Manual pages should be installed compressed using <tt>gzip
3579 If one manpage needs to be accessible via several names it
3580 is better to use a symbolic link than the <tt>.so</tt>
3581 feature, but there is no need to fiddle with the relevant
3582 parts of the upstream source to change from <tt>.so</tt> to
3583 symlinks--don't do it unless it's easy. Do not create hard
3584 links in the manual page directories, and do not put
3585 absolute filenames in <tt>.so</tt> directives. The filename
3586 in a <tt>.so</tt> in a manpage should be relative to the
3587 base of the manpage tree (usually
3588 <tt>/usr/share/man</tt>).</p></sect>
3592 <heading>Info documents</heading>
3595 Info documents should be installed in <tt>/usr/share/info</tt>.
3596 They should be compressed with <tt>gzip -9</tt>.</p>
3599 Your package must call <prgn>install-info</prgn> to update the Info
3601 file, in its post-installation script:
3603 install-info --quiet --section Development Development \
3604 /usr/share/info/foobar.info
3608 It is a good idea to specify a section for the location of
3609 your program; this is done with the <tt>--section</tt>
3610 switch. To determine which section to use, you should look
3611 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3612 relevant (or create a new section if none of the current
3613 sections are relevant). Note that the <tt>--section</tt>
3614 flag takes two arguments; the first is a regular expression
3615 to match (case-insensitively) against an existing section,
3616 the second is used when creating a new one.</p>
3619 You must remove the entries in the pre-removal script:
3621 install-info --quiet --remove /usr/share/info/foobar.info
3625 If <prgn>install-info</prgn> cannot find a description entry
3626 in the Info file you will have to supply one. See <manref
3627 name="install-info" section="8"> for details.</p>
3631 <heading>Additional documentation</heading>
3634 Any additional documentation that comes with the package can
3635 be installed at the discretion of the package maintainer.
3636 Text documentation should be installed in a directory
3637 <tt>/usr/share/doc/<var>package</var></tt>, where
3638 <var>package</var> is the name of the package, and
3639 compressed with <tt>gzip -9</tt> unless it is small.</p>
3642 If a package comes with large amounts of documentation which
3643 many users of the package will not require you should create
3644 a separate binary package to contain it, so that it does not
3645 take up disk space on the machines of users who do not need
3646 or want it installed.</p>
3649 It is often a good idea to put text information files
3650 (<tt>README</tt>s, changelogs, and so forth) that come with
3651 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3652 in the binary package. However, you don't need to install
3653 the instructions for building and installing the package, of
3658 <heading>Accessing the documentation</heading>
3661 Former Debian releases placed all additional documentation
3662 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3664 <tt>/usr/share/doc/<var>package</var></tt>, each package
3665 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3666 that points to the new location of its documentation in
3667 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3668 symlinks will be removed in the future, but they have to be
3669 there for compatibility reasons until all packages have
3670 moved and the policy is changed accordingly.</footnote>.
3671 The symlink must be created when the package is installed;
3672 it cannot be contained in the package itself due to problems
3673 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3674 this is to put the following in the package's
3675 <prgn>postinst</prgn>:
3677 if [ "$1" = "configure" ]; then
3678 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3679 -a -d /usr/share/doc/#PACKAGE# ]; then
3680 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3684 And the following in the package's <prgn>prerm</prgn>:
3686 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3687 -a -L /usr/doc/#PACKAGE# ]; then
3688 rm -f /usr/doc/#PACKAGE#
3695 <heading>Preferred documentation formats</heading>
3698 The unification of Debian documentation is being carried out
3702 If your package comes with extensive documentation in a
3703 mark up format that can be converted to various other formats
3704 you should if possible ship HTML versions in a binary
3705 package, in the directory
3706 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3709 <p>The rationale: The important thing here is that HTML
3710 docs should be available in <em>some</em> package, not
3711 necessarily in the main binary package, though. </p>
3716 Other formats such as PostScript may be provided at your
3720 <sect id="copyrightfile">
3721 <heading>Copyright information</heading>
3724 Every package must be accompanied by a verbatim copy of its
3725 copyright and distribution license in the file
3726 /usr/share/doc/<package-name>/copyright. This file must
3727 neither be compressed nor be a symbolic link.</p>
3730 In addition, the copyright file must say where the upstream
3731 sources (if any) were obtained, and explain briefly what
3732 modifications were made in the Debian version of the package
3733 compared to the upstream one. It must name the original
3734 authors of the package and the Debian maintainer(s) who were
3735 involved with its creation.</p>
3738 /usr/share/doc/<package-name> may be a symbolic link to a
3739 directory in /usr/share/doc only if two packages both come from
3740 the same source and the first package has a "Depends"
3741 relationship on the second. These rules are important
3742 because copyrights must be extractable by mechanical
3746 Packages distributed under the UCB BSD license, the Artistic
3747 license, the GNU GPL, and the GNU LGPL should refer to the
3748 files /usr/share/common-licenses/BSD,
3749 /usr/share/common-licenses/Artistic,
3750 /usr/share/common-licenses/GPL, and
3751 /usr/share/common-licenses/LGPL.
3754 Why "licenses" and not "copyright"? Because
3755 <tt>/usr/doc/copyright</tt> used to contain all the
3756 copyright files, plus the four common licenses GPL,
3757 LGPL, Artistic and BSD. Now individual copyright files
3758 for packages are no longer in a common directory. Once
3759 <tt>/usr/doc/copyright</tt> is almost empty it makes
3760 sense to rename "copyright" to "licenses"
3763 Why "common-licenses" and not "licenses"? Because if I
3764 put just "licenses" I'm sure I will receive a bug report
3765 saying "license foo is not included in the licenses
3766 directory. They are not all the licenses, just a few
3767 common ones. I could use /usr/share/doc/common-licenses
3768 but I think this is too long, and, after all, the GPL
3769 does not "document" anything, it is merely a license.
3775 Do not use the copyright file as a general <tt>README</tt>
3776 file. If your package has such a file it should be
3777 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3778 <tt>README.Debian</tt> or some other appropriate place.</p>
3782 <heading>Examples</heading>
3785 Any examples (configurations, source files, whatever),
3786 should be installed in a directory
3787 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3788 files should not be referenced by any program--they're there
3789 for the benefit of the system administrator and users, as
3790 documentation only. Architecture-specific example files
3791 should be installed in a directory
3792 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3793 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3794 to files in it. Or the latter directory may be a symlink to
3798 <sect id="instchangelog">
3799 <heading>Changelog files</heading>
3802 This installed file must contain a copy of the
3803 <tt>debian/changelog</tt> file from your Debian source tree,
3804 and a copy of the upstream changelog file if there is one.
3805 The debian/changelog file should be installed in
3806 <tt>/usr/share/doc/<var>package</var></tt> as
3807 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3808 file is text formatted, it must be accessible as
3809 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
3810 the upstream changelog file is HTML formatted, it must be
3812 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
3813 A plain text version of the changelog must be accessible as
3814 <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
3815 be created by <tt>lynx -dump -nolist</tt>). If the upstream
3816 changelog files do not already conform to this naming
3817 convention, then this may be achieved by either renaming the
3818 files or adding a symbolic link at the packaging developer's
3822 Rationale: People should not have to look into two
3823 places ofr upstream changelogs merely because they are
3830 Both should be installed compressed using <tt>gzip -9</tt>,
3831 as they will become large with time even if they start out
3835 If the package has only one changelog which is used both as
3836 the Debian changelog and the upstream one because there is
3837 no separate upstream maintainer then that changelog should
3838 usually be installed as
3839 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3840 there is a separate upstream maintainer, but no upstream
3841 changelog, then the Debian changelog should still be called
3842 <tt>changelog.Debian.gz</tt>.</p>