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="The GNU Public Licence">. 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/package-developer/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="The Debian Policy Manual">.</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). In order to
593 ensure this, the priorities of one or more packages may have
599 <heading>Binary packages</heading>
602 The Debian GNU/Linux distribution is based on the Debian
603 package management system, called <prgn>dpkg</prgn>. Thus,
604 all packages in the Debian distribution have to be provided
605 in the <tt>.deb</tt> file format.</p>
609 <heading>The package name</heading>
612 Every package must have a name that's unique within the Debian
616 Package names may only consist of lower case letters, digits (0-9),
617 plus (+) or minus (-) signs, and periods (.).</p>
620 The package name is part of the file name of the
621 <tt>.deb</tt> file and is included in the control field
627 <heading>The maintainer of a package</heading>
630 Every package must have exactly one maintainer at a
631 time. This person is responsible that the license of the
632 package's software complies with the policy of the
633 distribution this package is included in.</p>
636 The maintainer must be specified in the
637 <tt>Maintainer</tt> control field with the correct name
638 and a working email address for the Debian maintainer of
639 the package. If one person maintains several packages
640 he/she should try to avoid having different forms of their
641 name and email address in different <tt>Maintainer</tt>
645 If the maintainer of a package quits from the Debian
646 project the Debian QA Group
647 <email>debian-qa@lists.debian.org</email> takes over the
648 maintainership of the package until someone else
649 volunteers for that task. These packages are called
650 <em>orphaned packages</em>.
656 <heading>The description of a package</heading>
659 Every Debian package must have an extended description
660 stored in the appropriate field of the control record.</p>
663 The description must be written so that it tells the user
664 what they need to know to decide whether to install the
665 package. This description should not just be copied from
666 the blurb for the program. Instructions for configuring
667 or using the package must not be included -- that is what
668 installation scripts, manual pages, Info files, etc. are
669 for. Copyright statements and other administrivia must
670 not be included -- that is what the copyright file is
676 <heading>Dependencies</heading>
679 Every package has to specify the dependency information
680 about other packages, that are required for the first to
684 For example, for any shared libraries required by
685 dynamically-linked executable binary in a package a
686 dependency entry has to be provided.</p>
689 It is not necessary for other packages to declare any
690 dependencies they have on other packages which are marked
691 <tt>Essential</tt> (see below).</p>
694 Sometimes, a package requires another package to be
695 installed <em>and</em> configured before it can be
696 installed. In this case, you'll have to specify a
697 <tt>Pre-Depends</tt> entry for the package.</p>
700 You must not specify a <tt>Pre-Depends</tt> entry for a
701 package before this has been discussed on the
702 <tt>debian-devel</tt> mailing list and a consensus about
703 doing that has been reached.</p></sect1>
707 <heading>Virtual packages</heading>
710 Sometimes, there are several packages doing more-or-less
711 the same job. In this case, it's useful to define a
712 <em>virtual package</em> whose name describes the function
713 the packages have. (The virtual packages just exist
714 logically, not physically--that's why they are called
715 <em>virtual</em>.) The packages with this particular
716 function will then <em>provide</em> the virtual
717 package. Thus, any other package requiring that function
718 can simply depend on the virtual package without having to
719 specify all possible packages individually.</p>
722 All packages must use virtual package names where
723 appropriate, and arrange to create new ones if necessary.
724 They must not use virtual package names (except privately,
725 amongst a cooperating group of packages) unless they have
726 been agreed upon and appear in the list of virtual package
730 The latest version of the authoritative list of virtual
731 package names can be found on
732 <ftpsite>ftp.debian.org</ftpsite> in
733 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
734 or your local mirror. In addition, it is included in the
735 <tt>debian-policy</tt> package. The procedure for updating
736 the list is described at the top of the file.</p></sect1>
740 <heading>Base packages</heading>
743 The packages included in the <tt>base</tt> section have a
744 special function. They form a minimum subset of the Debian
745 GNU/Linux system that is installed before everything else
746 on a new system. Thus, only very few packages are allowed
747 to go into the <tt>base</tt> section to keep the required
748 disk usage very small.</p>
751 Most of these packages should have the priority value
752 <tt>required</tt> or at least <tt>important</tt>, and many
753 of them will be tagged <tt>essential</tt> (see below).</p>
756 You must not place any packages into the <tt>base</tt>
757 section before this has been discussed on the
758 <tt>debian-devel</tt> mailing list and a consensus about
759 doing that has been reached.</p></sect1>
763 <heading>Essential packages</heading>
766 Some packages are tagged <tt>essential</tt>. (They have
767 <tt>Essential: yes</tt> in their package control record.)
768 This flag is used for packages that are <em>essential</em>
772 Since these packages can not easily be removed (you'll
773 have to specify an extra <em>force option</em> to
774 <prgn>dpkg</prgn>) this flag must only be used where
775 absolutely necessary.
777 A shared library package must not be tagged
778 <em>essential</em>--the dependencies will prevent its
779 premature removal, and we need to be able to remove it
780 when it has been superseded.</p>
783 You must not tag any packages <tt>essential</tt> before
784 this has been discussed on the <tt>debian-devel</tt>
785 mailing and a consensus about doing that has been
790 <heading>Maintainer scripts</heading>
793 The package installation scripts must avoid producing
794 output which it is unnecessary for the user to see and
795 should rely on <prgn>dpkg</prgn> to stave off boredom on
796 the part of a user installing many packages. This means,
797 amongst other things, using the <tt>--quiet</tt> option on
798 <prgn>install-info</prgn>.</p>
801 Packages should try to minimize the amount of prompting
802 they need to do, and they should ensure that the user will
803 only ever be asked each question once. This means that
804 packages should try to use appropriate shared
805 configuration files (such as <tt>/etc/papersize</tt> and
806 <tt>/etc/news/server</tt>), rather than each prompting for
807 their own list of required pieces of information.</p>
810 It also means that an upgrade should not ask the same
811 questions again, unless the user has used <tt>dpkg
812 --purge</tt> to remove the package's configuration. The
813 answers to configuration questions should be stored in an
814 appropriate place in <tt>/etc</tt> so that the user can
815 modify them, and how this has been done should be
819 If a package has a vitally important piece of information
820 to pass to the user (such as "don't run me as I am, you
821 must edit the following configuration files first or you
822 risk your system emitting badly-formatted messages"), it
823 should display this in the <prgn>postinst</prgn> script
824 and prompt the user to hit return to acknowledge the
825 message. Copyright messages do not count as vitally
826 important (they belong in
827 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
828 do instructions on how to use a program (these should be
829 in on line documentation, where all the users can see
833 Any necessary prompting should almost always be confined
834 to the post-installation script, and should be protected
835 with a conditional so that unnecessary prompting doesn't
836 happen if a package's installation fails and the
837 <prgn>postinst</prgn> is called with
838 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
839 <tt>abort-deconfigure</tt>.</p>
842 Errors which occur during the execution of an installation
843 script <em>must</em> be checked and the installation
844 <em>must not</em> continue after an error.</p>
847 Note, that <ref id="scripts">, in general applies to
848 package maintainer scripts, too.</p>
851 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
852 another package without consulting the maintainer of that
856 In order for <prgn>update-alternatives</prgn> to work
857 correctly all the packages which supply an instance of the
858 `shared' command name (or, in general, filename) must use
859 it. You can use <tt>Conflicts</tt> to force the
860 De-installation of other packages supplying it which do not
861 (yet) use <prgn>update-alternatives</prgn>. It may in
862 this case be appropriate to specify a conflict on earlier
863 versions of something--this is an exception to the usual
864 rule that this is not allowed.</p>
868 <heading>Source packages</heading>
871 <heading>Standards conformance</heading>
874 You should specify the most recent version of the
875 packaging standards with which your package complies in
876 the source package's <tt>Standards-Version</tt> field.</p>
879 This value will be used to file bug reports automatically
880 if your package becomes too much out of date.</p>
883 The value corresponds to a version of the Debian manuals,
884 as can be found on the title page or page headers and
885 footers (depending on the format).</p>
888 The version number has four components--major and minor
889 number and major and minor patch level. When the
890 standards change in a way that requires every package to
891 change the major number will be changed. Significant
892 changes that will require work in many packages will be
893 signaled by a change to the minor number. The major patch
894 level will be changed for any change to the meaning of the
895 standards, however small; the minor patch level will be
896 changed when only cosmetic, typographical or other edits
897 which do not change the meaning are made, or changes which
898 do not affect the contents of packages.</p>
901 For package maintainers, only the first 3 digits of the
902 manual version are significant in representing the
903 <em>Standards-Version</em>, and either these 3 digits or
904 the complete 4 digits can be specified--that's up to the
908 In the past, people specified 4 digits in the
909 Standards-Version field, like `2.3.0.0'. Since any
910 `patch-level changes' don't introduce new policy, it
911 was thought it would be better to relax policy and
912 only require that the first 3 digits are specified. (4
913 digits can still be used if someone wants to do so.)
919 You should regularly, and especially if your package has
920 become out of date, check for the newest Policy Manual
921 available and update your package, if necessary. When your
922 package complies with the new standards you may update the
923 <tt>Standards-Version</tt> source package field and
924 release it.</p></sect1>
928 <heading>Package relationships</heading>
931 Source packages must specify which binary packages they
932 require to be installed or not to be installed in order to
933 build correctly. For example, if building a package
934 requires a certain compiler, then the compiler must be
935 specified as a build-time dependency.
939 It will not be necessary to explicitly specify build-time
940 relationships on a minimal set of packages that are always
941 needed to compile, link and put in a Debian package a
942 standard "Hello World!" program written in C or C++. The
943 required packages are called <em>build-essential</em>, and
944 an informational list can be found in
945 <tt>/usr/share/doc/build-essential/list</tt> (which is
946 contained in the <tt>build-essential</tt> package).
951 When specifying the set of build-time dependencies, one
952 should list only those packages explicitly required by the
953 build. It is not necessary to list packages which are
954 required merely because some other package in the list of
955 build-time dependencies depends on them. The reason is
956 that dependencies change, and you should list only those
957 <em>you</em> need. What others need is their business.
961 It is a bug if, after unpacking a source package on a
962 system with the build-essential packages installed and
963 satisfying the build-time relationships (including the
964 implied relationships), one cannot build the package and
965 produce a working binary package suitable for installation
966 into the binary distribution corresponding to the source
967 distribution which contained the source package. This
968 means in particular that version clauses should be used
969 rigorously in build-time relationships so that one cannot
970 produce bad or inconsistently configured packages when the
971 relationships are properly satisfied.
975 <heading>Changes to the upstream sources</heading>
978 If changes to the source code are made that are generally
979 applicable please try to get them included in the upstream
980 version of the package by supplying the upstream authors
981 with the changes in whatever form they prefer.</p>
984 If you need to configure the package differently for
985 Debian or for Linux, and the upstream source doesn't
986 provide a way to configure it the way you need to, please
987 add such configuration facilities (for example, a new
988 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
989 the patch to the upstream authors, with the default set to
990 the way they originally had it. You can then easily
991 override the default in your <tt>debian/rules</tt> or
992 wherever is appropriate.</p>
995 Please make sure that the <prgn>configure</prgn> utility
996 detects the correct architecture specification string
997 (refer to <ref id="arch-spec"> for details).</p>
1000 If you need to edit a <prgn>Makefile</prgn> where
1001 GNU-style <prgn>configure</prgn> scripts are used, you
1002 should edit the <tt>.in</tt> files rather than editing the
1003 <prgn>Makefile</prgn> directly. This allows the user to
1004 reconfigure the package if necessary. You should
1005 <em>not</em> configure the package and edit the generated
1006 <prgn>Makefile</prgn>! This makes it impossible for
1007 someone else to later reconfigure the package.</p></sect1>
1011 <heading>Documenting your changes</heading>
1014 Document your changes and updates to the source package
1015 properly in the <tt>debian/changelog</tt> file.</p>
1018 A copy of the file which will be installed in
1019 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1020 in <tt>debian/copyright</tt>.</p>
1023 In non-experimental packages you may only use a format for
1024 <tt>debian/changelog</tt> which is supported by the most
1025 recent released version of <prgn>dpkg</prgn>. If your
1026 format is not supported and there is general support for
1027 it you should contact the <prgn>dpkg</prgn> maintainer to
1028 have the parser script for your format included in the
1029 <prgn>dpkg</prgn> package. (You will need to agree that
1030 the parser and its manpage may be distributed under the
1031 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1036 <heading>Error trapping in makefiles</heading>
1039 When <prgn>make</prgn> invokes a command in a makefile
1040 (including your package's upstream makefiles and the
1041 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1042 means that <tt>sh</tt>'s usual bad error handling
1043 properties apply: if you include a miniature script as one
1044 of the commands in your makefile you'll find that if you
1045 don't do anything about it then errors are not detected
1046 and <prgn>make</prgn> will blithely continue after
1050 Every time you put more than one shell command (this
1051 includes using a loop) in a makefile command you
1052 <em>must</em> make sure that errors are trapped. For
1053 simple compound commands, such as changing directory and
1054 then running a program, using <tt>&&</tt> rather
1055 than semicolon as a command separator is sufficient. For
1056 more complex commands including most loops and
1057 conditionals you must include a separate <tt>set -e</tt>
1058 command at the start of every makefile command that's
1059 actually one of these miniature shell scripts.</p></sect1>
1063 <heading>Obsolete constructs and libraries</heading>
1066 The include file <prgn><varargs.h></prgn> is
1067 provided to support end-users compiling very old software;
1068 the library <tt>libtermcap</tt> is provided to support the
1069 execution of software which has been linked against it
1070 (either old programs or those such as Netscape which are
1071 only available in binary form).</p>
1074 Debian packages should be ported to include
1075 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1080 <chapt><heading>The Operating System</heading>
1084 <heading>File system hierarchy</heading>
1088 <heading>Linux File system Structure</heading>
1091 The location of all installed files and directories must
1092 comply with the Linux File system Hierarchy Standard
1093 (FHS). The latest version of this document can be found
1094 alongside this manual or on
1095 <url id="http://www.pathname.com/fhs/">.<footnote>
1096 <p>The Debian distribution currently distributes a draft
1097 version of FHS 2.1 because several significant details
1098 have changed between the currently released 2.0
1099 version and the to-be-released 2.1 version.</p>
1101 Specific questions about following the standard may be
1102 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1103 Quinlan, the FHS coordinator, at
1104 <email>quinlan@pathname.com</email>.</p></sect1>
1108 <heading>Site-specific programs</heading>
1111 As mandated by the FHS no package should place any
1112 files in <tt>/usr/local</tt>, either by putting them in
1113 the file system archive to be unpacked by <prgn>dpkg</prgn>
1114 or by manipulating them in their maintainer scripts.</p>
1117 However, the package should create empty directories below
1118 <tt>/usr/local</tt> so that the system administrator knows
1119 where to place site-specific files. These directories
1120 should be removed on package removal if they are
1124 Note, that this applies only to directories <em>below</em>
1125 <tt>/usr/local</tt>, not <em>in</em>
1126 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1127 itself may only contain the sub-directories listed in
1128 FHS, section 4.6. However, you may create directories
1129 below them as you wish. You may not remove any of the
1130 directories listed in 4.6, even if you created them.</p>
1133 Since <tt>/usr/local</tt> may be mounted read-only from a
1134 remote server, these directories have to be created and
1135 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1136 maintainer scripts. These scripts must not fail if either
1137 of these operations fail. (In the future, it will be
1138 possible to tell <prgn>dpkg</prgn> not to unpack files
1139 matching certain patterns, so that the directories can be
1140 included in the <tt>.deb</tt> packages and system
1141 administrators who do not wish these directories in
1142 /usr/local do not need to have them.)</p>
1145 For example, the <prgn>emacs</prgn> package will contain
1147 mkdir -p /usr/local/lib/emacs/site-lisp || true
1149 in the <tt>postinst</tt> script, and
1151 rmdir /usr/local/lib/emacs/site-lisp && \
1152 rmdir /usr/local/lib/emacs || \
1155 in the <tt>prerm</tt> script.</p>
1158 If you do create a directory in <tt>/usr/local</tt> for
1159 local additions to a package, you must ensure that
1160 settings in <tt>/usr/local</tt> take precedence over the
1161 equivalents in <tt>/usr</tt>.</p>
1164 However, because '/usr/local' and its contents are for
1165 exclusive use of the local administrator, a package must
1166 not rely on the presence or absence of files or
1167 directories in '/usr/local' for normal operation.</p>
1170 The <tt>/usr/local</tt> directory itself and all the
1171 subdirectories created by the package should have
1172 permissions 2775 (group-writable and set-group-id) and be
1173 owned by <tt>root.staff</tt>.</p>
1178 <heading>Users and groups</heading>
1181 The Debian system can be configured to use either plain or
1182 shadow passwords.</p>
1185 Some user ids (UIDs) and group ids (GIDs) are reserved
1186 globally for use by certain packages. Because some packages
1187 need to include files which are owned by these users or
1188 groups, or need the ids compiled into binaries, these ids
1189 must be used on any Debian system only for the purpose for
1190 which they are allocated. This is a serious restriction, and
1191 we should avoid getting in the way of local administration
1192 policies. In particular, many sites allocate users and/or
1193 local system groups starting at 100.</p>
1196 Apart from this we should have dynamically allocated ids,
1197 which should by default be arranged in some sensible
1198 order--but the behavior should be configurable.</p>
1201 No package except <tt>base-passwd</tt> may modify
1202 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1203 <tt>/etc/group</tt>.</p>
1206 The UID and GID ranges are as follows:
1211 Globally allocated by the Debian project, must be the
1212 same on every Debian system. These ids will appear in
1213 the <tt>passwd</tt> and <tt>group</tt> files of all
1214 Debian systems, new ids in this range being added
1215 automatically as the <tt>base-passwd</tt> package is
1219 Packages which need a single statically allocated uid
1220 or gid should use one of these; their maintainers
1221 should ask the <tt>base-passwd</tt> maintainer for
1228 Dynamically allocated system users and groups.
1229 Packages which need a user or group, but can have this
1230 user or group allocated dynamically and differently on
1231 each system, should use `<tt>adduser --system</tt>' to
1232 create the group and/or user. <prgn>adduser</prgn>
1233 will check for the existence of the user or group, and
1234 if necessary choose an unused id based on the ranged
1235 specified in <tt>adduser.conf</tt>.</p></item>
1238 <tag>1000-29999:</tag>
1241 Dynamically allocated user accounts. By default
1242 <prgn>adduser</prgn> will choose UIDs and GIDs for
1243 user accounts in this range, though
1244 <tt>adduser.conf</tt> may be used to modify this
1248 <tag>30000-59999:</tag>
1250 <p>Reserved.</p></item>
1253 <tag>60000-64999:</tag>
1256 Globally allocated by the Debian project, but only
1257 created on demand. The ids are allocated centrally and
1258 statically, but the actual accounts are only created
1259 on users' systems on demand.</p>
1262 These ids are for packages which are obscure or which
1263 require many statically-allocated ids. These packages
1264 should check for and create the accounts in
1265 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1266 <prgn>adduser</prgn> if it has this facility) if
1267 necessary. Packages which are likely to require
1268 further allocations should have a `hole' left after
1269 them in the allocation, to give them room to
1273 <tag>65000-65533:</tag>
1275 <p>Reserved.</p></item>
1280 <p>User `<tt>nobody</tt>.'</p></item>
1286 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1287 because it is the error return sentinel value.</p>
1292 <sect id="sysvinit">
1293 <heading>System run levels</heading>
1296 <sect1 id="/etc/init.d">
1297 <heading>Introduction</heading>
1300 The <tt>/etc/init.d</tt> directory contains the scripts
1301 executed by <prgn>init</prgn> at boot time and when init
1302 state (or `runlevel') is changed (see <manref name="init"
1306 There are at least two different, yet functionally
1307 equivalent, ways of handling these scripts. For the sake
1308 of simplicity, this document describes only the symbolic
1309 link method. However, it may not be assumed that this
1310 method is being used, and any manipulation of the various
1311 runlevel behaviours must be performed using
1312 <prgn>update-rc.d</prgn> as described below and not by
1313 manually installing symlinks. For information on the
1314 implementation details of the other method, implemented in
1315 the <tt>file-rc</tt> package, please refer to the
1316 documentation of that package.</p>
1319 These scripts are referenced by symbolic links in
1320 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1321 changing runlevels, <prgn>init</prgn> looks in the
1322 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1323 it should execute, where <var>n</var> is the runlevel that
1324 is being changed to, or `S' for the boot-up scripts.</p>
1327 The names of the links all have the form
1328 <tt>S<var>mm</var><var>script</var></tt> or
1329 <tt>K<var>mm</var><var>script</var></tt> where
1330 <var>mm</var> is a two-digit number and <var>script</var>
1331 is the name of the script (this should be the same as the
1332 name of the actual script in <tt>/etc/init.d</tt>.</p>
1335 When <prgn>init</prgn> changes runlevel first the targets
1336 of the links whose names starting with a <tt>K</tt> are
1337 executed, each with the single argument <tt>stop</tt>,
1338 followed by the scripts prefixed with an <tt>S</tt>, each
1339 with the single argument <tt>start</tt>. The <tt>K</tt>
1340 links are responsible for killing services and the
1341 <tt>S</tt> link for starting services upon entering the
1345 For example, if we are changing from runlevel 2 to
1346 runlevel 3, init will first execute all of the <tt>K</tt>
1347 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1348 all of the <tt>S</tt> prefixed scripts. The links
1349 starting with <tt>K</tt> will cause the referred-to file
1350 to be executed with an argument of <tt>stop</tt>, and the
1351 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1354 The two-digit number <var>mm</var> is used to decide which
1355 order to start and stop things in--low-numbered links have
1356 their scripts run first. For example, the <tt>K20</tt>
1357 scripts will be executed before the <tt>K30</tt> scripts.
1358 This is used when a certain service must be started before
1359 another. For example, the name server <prgn>bind</prgn>
1360 might need to be started before the news server
1361 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1362 access lists. In this case, the script that starts
1363 <prgn>bind</prgn> should have a lower number than the
1364 script that starts <prgn>inn</prgn> so that it runs first:
1373 <heading>Writing the scripts</heading>
1376 Packages can and should place scripts in
1377 <tt>/etc/init.d</tt> to start or stop services at boot
1378 time or during a change of runlevel. These scripts should
1379 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1380 should accept one argument, saying what to do:
1383 <tag><tt>start</tt></tag>
1384 <item><p>start the service,</p></item>
1386 <tag><tt>stop</tt></tag>
1387 <item><p>stop the service,</p></item>
1389 <tag><tt>restart</tt></tag>
1390 <item><p>stop and restart the service,</p></item>
1392 <tag><tt>reload</tt></tag>
1393 <item><p>cause the configuration of the service to be
1394 reloaded without actually stopping and restarting
1395 the service,</p></item>
1397 <tag><tt>force-reload</tt></tag> <item><p>cause the
1398 configuration to be reloaded if the service supports
1399 this, otherwise restart the service.</p></item>
1402 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1403 <tt>force-reload</tt> options must be supported by all
1404 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1405 option is optional.</p>
1408 The <tt>init.d</tt> scripts should ensure that they will
1409 behave sensibly if invoked with <tt>start</tt> when the
1410 service is already running, or with <tt>stop</tt> when it
1411 isn't, and that they don't kill unfortunately-named user
1412 processes. The best way to achieve this is usually to use
1413 <prgn>start-stop-daemon</prgn>.</p>
1416 If a service reloads its configuration automatically (as
1417 in the case of <prgn>cron</prgn>, for example), the
1418 <tt>reload</tt> option of the <tt>init.d</tt> script
1419 should behave as if the configuration has been reloaded
1423 These scripts should not fail obscurely when the
1424 configuration files remain but the package has been
1425 removed, as configuration files remain on the system after
1426 the package has been removed. Only when <prgn>dpkg</prgn>
1427 is executed with the <tt>--purge</tt> option will
1428 configuration files be removed. In particular, the init
1429 script itself is usually a configuration file (see
1430 <ref id="init.d notes">), and will remain on the system if
1431 the package is removed but not purged. Therefore, you
1432 should include a <tt>test</tt> statement at the top of the
1435 test -f <var>program-executed-later-in-script</var> || exit 0
1440 <heading>Managing the links</heading>
1443 A program is provided, <prgn>update-rc.d</prgn>, to handle
1444 the it easier for package maintainers to arrange for the
1445 proper creation and removal of
1446 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1447 functional equivalent if another method is being used.
1448 This may be used by maintainers in their packages'
1449 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1452 You should use this script to make changes to
1453 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1454 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1455 in the actual archive or manually create or remove the
1456 symbolic links in maintainer scripts. (The latter will
1457 fail if an alternative method of maintaining runlevel
1458 information is being used.)</p>
1461 By default <prgn>update-rc.d</prgn> will start services in
1462 each of the multi-user state runlevels (2, 3, 4, and 5)
1463 and stop them in the halt runlevel (0), the single-user
1464 runlevel (1) and the reboot runlevel (6). The system
1465 administrator will have the opportunity to customize
1466 runlevels by either running <prgn>update-rc.d</prgn>, by
1467 simply adding, moving, or removing the symbolic links in
1468 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1469 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1470 <tt>file-rc</tt> method is being used.</p>
1473 To get the default behavior for your package, put in your
1474 <tt>postinst</tt> script
1476 update-rc.d <var>package</var> defaults >/dev/null
1478 and in your <tt>postrm</tt>
1480 if [ purge = "$1" ]; then
1481 update-rc.d <var>package</var> remove >/dev/null
1486 This will use a default sequence number of 20. If it does
1487 not matter when or in which order the script is run, use
1488 this default. If it does, then you should talk to the
1489 maintainer of the <prgn>sysvinit</prgn> package or post to
1490 <tt>debian-devel</tt>, and they will help you choose a
1494 For more information about using <tt>update-rc.d</tt>,
1495 please consult its manpage <manref name="update-rc.d"
1496 section="8">.</p></sect1>
1500 <heading>Boot-time initialization</heading>
1503 There used to be another directory, <tt>/etc/rc.boot</tt>,
1504 which contained scripts which were run once per machine
1505 boot. This has been deprecated in favour of links from
1506 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1507 described in <ref id="/etc/init.d">. No packages may
1508 place files in <tt>/etc/rc.boot</tt>.</p>
1510 <sect1 id="init.d notes">
1511 <heading>Notes</heading>
1514 <em>Do not</em> include the
1515 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1516 <tt>.deb</tt> file system archive! <em>This will cause
1517 problems!</em> You should create them with
1518 <prgn>update-rc.d</prgn>, as above.</p>
1521 <em>Do not</em> include the
1522 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1523 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1524 problems!</em> <em>Do</em>, however, treat the
1525 <tt>/etc/init.d</tt> scripts as configuration files,
1526 either by marking them as conffiles or managing them
1527 correctly in the maintainer scripts (see
1528 <ref id="config files">). (This is important since we want
1529 to give the local system administrator the chance to adapt
1530 the scripts to the local system--e.g., to disable a
1531 service without de-installing the package, or to specify
1532 some special command line options when starting a
1533 service--while making sure her changes aren't lost during
1534 the next package upgrade.)</p>
1538 <heading>Example</heading>
1541 The <prgn>bind</prgn> DNS (nameserver) package wants to
1542 make sure that the nameserver is running in multiuser
1543 runlevels, and is properly shut down with the system. It
1544 puts a script in <tt>/etc/init.d</tt>, naming the script
1545 appropriately <tt>bind</tt>. As you can see, the script
1546 interprets the argument <tt>reload</tt> to send the
1547 nameserver a <tt>HUP</tt> signal (causing it to reload its
1548 configuration); this way the user can say
1549 <tt>/etc/init.d/bind reload</tt> to reload the name
1556 # Original version by Robert Leslie
1557 # <rob@mars.org>, edited by iwj and cs
1559 test -x /usr/sbin/named || exit 0
1563 echo -n "Starting domain name service: named"
1564 start-stop-daemon --start --quiet --exec /usr/sbin/named
1568 echo -n "Stopping domain name service: named"
1569 start-stop-daemon --stop --quiet \
1570 --pidfile /var/run/named.pid --exec /usr/sbin/named
1574 echo -n "Restarting domain name service: named"
1575 start-stop-daemon --stop --quiet \
1576 --pidfile /var/run/named.pid --exec /usr/sbin/named
1577 start-stop-daemon --start --verbose --exec /usr/sbin/named
1580 force-reload|reload)
1581 echo -n "Reloading configuration of domain name service: named"
1582 start-stop-daemon --stop --signal 1 --quiet \
1583 --pidfile /var/run/named.pid --exec /usr/sbin/named
1587 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1596 Another example on which to base your <tt>/etc/init.d</tt>
1597 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1600 If this package is happy with the default setup from
1601 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1602 and having named running in all runlevels, it can say in
1603 its <tt>postinst</tt>:
1605 update-rc.d bind defaults >/dev/null
1607 And in its <tt>postrm</tt>, to remove the links when the
1610 if [ purge = "$1" ]; then
1611 update-rc.d acct remove >/dev/null
1617 <heading>Cron jobs</heading>
1620 Packages may not modify the configuration file
1621 <tt>/etc/crontab</tt>, nor may they modify the files in
1622 <tt>/var/spool/cron/crontabs</tt>.</p>
1625 If a package wants to install a job that has to be executed
1626 via cron, it should place a file with the name if the
1627 package in one of the following directories:
1633 As these directory names imply, the files within them are
1634 executed on a daily, weekly, or monthly basis,
1635 respectively. The exact times are listed in
1636 <tt>/etc/crontab</tt>.</p>
1639 All files installed in any of these directories have to be
1640 scripts (shell scripts, Perl scripts, etc.) so that they can
1641 easily be modified by the local system administrator. In
1642 addition, they must be treated as configuration files.</p>
1645 If a certain job has to be executed more frequently than
1646 daily, the package should install a file
1647 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1648 the same syntax as <tt>/etc/crontab</tt> and is processed by
1649 <prgn>cron</prgn> automatically. The file must also be
1650 treated as a configuration file. (Note, that entries in the
1651 <tt>/etc/cron.d</tt> directory are not handled by
1652 <prgn>anacron</prgn>. Thus, you should only use this
1653 directory for jobs which may be skipped if the system is not
1657 The scripts or crontab entries in these directories should
1658 check if all necessary programs are installed before they
1659 try to execute them. Otherwise, problems will arise when a
1660 package was removed but not purged since configuration files
1661 are kept on the system in this situation.</p>
1665 <heading>Console messages</heading>
1668 This section describes different formats for messages
1669 written to standard output by the <tt>/etc/init.d</tt>
1670 scripts. The intent is to improve the consistency of
1671 Debian's startup and shutdown look and feel.</p>
1674 Please look very careful at the details. We want to get the
1675 messages to look exactly the same way concerning spaces,
1676 punctuation, and case of letters.</p>
1679 Here is a list of overall rules that you should use when you
1680 create output messages. They can be useful if you have a
1681 non-standard message that isn't covered in the sections
1688 Every message should cover one line, start with a
1689 capital letter and end with a period `.'.</p></item>
1694 If you want to express that the computer is working on
1695 something (performing a specific task, not starting or
1696 stopping a program), we use an ``ellipsis'', namely
1697 three dots `...'. Note that we don't insert spaces in
1698 front of or behind the dots. If the task has been
1699 completed we write `done.' and a line feed.</p></item>
1704 Design your messages as if the computer is telling you
1705 what he is doing (let him be polite :-) but don't
1706 mention ``him'' directly. For example, if you think
1709 I'm starting network daemons: nfsd mountd.
1713 Starting network daemons: nfsd mountd.
1714 </example></p></item>
1718 The following formats must be used</p>
1723 <p>when daemons get started.</p>
1726 Use this format if your script starts one or more
1727 daemons. The output should look like this (a single
1728 line, no leading spaces):
1730 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1732 The <description> should describe the subsystem
1733 the daemon or set of daemons are part of, while
1734 <daemon-1> up to <daemon-n> denote each
1735 daemon's name (typically the file name of the
1739 For example, the output of /etc/init.d/lpd would look like:
1741 Starting printer spooler: lpd.
1745 This can be achieved by saying
1747 echo -n "Starting printer spooler: lpd"
1748 start-stop-daemon --start --quiet lpd
1751 in the script. If you have more than one daemon to
1752 start, you should do the following:
1754 echo -n "Starting remote file system services:"
1755 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1756 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1757 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1760 This makes it possible for the user to see what takes
1761 so long and when the final daemon has been
1762 started. Please be careful where to put spaces: In the
1763 example above the system administrator can easily
1764 comment out a line if he don't wants to start a
1765 specific daemon, while the displayed message still
1766 looks good.</p></item>
1770 <p>when something needs to be configured.</p>
1773 If you have to set up different parameters of the
1774 system upon boot up, you can use this format:
1776 Setting <parameter> to `<value>'.
1780 You can use the following echo statement to get the quotes right:
1782 echo "Setting DNS domainname to \`"value"'."
1786 Note that the left quotation mark (`) is different
1787 from the right (').</p></item>
1790 <p>when a daemon is stopped.</p>
1793 When you stop a daemon you should issue a message
1794 similar to the startup message, except that `Starting'
1795 is replaced with `Stopping'.</p>
1798 So stopping the printer daemon will like like this:
1800 Stopping printer spooler: lpd.
1801 </example></p></item>
1804 <p>when something is executed.</p>
1807 There a several examples where you have to run a
1808 program at system startup or shutdown to perform a
1809 specific task. For example, setting the system's clock
1810 via `netdate' or killing all processes when the system
1811 comes down. Your message should like this:
1813 Doing something very useful...done.
1815 You should print the `done.' right after the job has been completed,
1816 so that the user gets informed why he has to wait. You can get this
1819 echo -n "Doing something very useful..."
1823 in your script.</p></item>
1826 <p>when the configuration is reloaded.</p>
1829 When a daemon is forced to reload its configuration
1830 files you should use the following format:
1832 Reloading <daemon's-name> configuration...done.
1833 </example></p></item>
1836 <p>when none of the above rules apply.</p>
1839 If you have to print a message that doesn't fit into
1840 the styles described above, you can use something
1841 appropriate, but please have a look at the overall
1842 rules listed above.</p></item>
1847 <heading>Menus</heading>
1850 Menu entries should follow the current menu policy as
1851 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1852 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1853 or your local mirror. In addition, it is included in the
1854 <tt>debian-policy</tt> package.
1858 The Debian <tt>menu</tt> packages provides a unique
1859 interface between packages providing applications and
1860 documents, and <em>menu programs</em> (either X window
1861 managers or text-based menu programs as
1862 <prgn>pdmenu</prgn>).</p>
1865 All packages that provide applications that need not be
1866 passed any special command line arguments for normal
1867 operation should register a menu entry for those
1868 applications, so that users of the <tt>menu</tt> package
1869 will automatically get menu entries in their window
1870 managers, as well in shells like <tt>pdmenu</tt>.</p>
1873 Please refer to the <em>Debian Menu System</em> document
1874 that comes with the <tt>menu</tt> package for information
1875 about how to register your applications and web
1881 <heading>Multimedia handlers</heading>
1884 Packages which provide the ability to view/show/play,
1885 compose, edit or print MIME types should register themselves
1886 as such following the current MIME support policy as defined
1887 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1888 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1889 or your local mirror. In addition, it is included in the
1890 <tt>debian-policy</tt> package.
1894 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1895 mechanism for encoding files and data streams and providing
1896 meta-information about them, in particular their type (e.g.
1897 audio or video) and format (e.g. PNG, HTML, MP3).
1901 Registration of MIME type handlers allows programs like mail
1902 user agents and web browsers to to invoke these handlers to
1903 view, edit or display MIME types they don't support
1909 <heading>Keyboard configuration</heading>
1912 To achieve a consistent keyboard configuration (i.e., all
1913 applications interpret a keyboard event the same way) all
1914 programs in the Debian distribution have to be configured to
1915 comply with the following guidelines.</p>
1918 Here is a list that contains certain keys and their interpretation:
1921 <tag><tt><--</tt></tag>
1922 <item><p>delete the character to the left of the cursor</p></item>
1924 <tag><tt>Delete</tt></tag>
1925 <item><p>delete the character to the right of the cursor</p></item>
1927 <tag><tt>Control+H</tt></tag>
1928 <item><p>emacs: the help prefix</p></item>
1931 The interpretation of any keyboard events should be independent
1932 of the terminal that's used, be it a virtual console, an X
1933 terminal emulator, an rlogin/telnet session, etc.</p>
1936 The following list explains how the different programs
1937 should be set up to achieve this:</p>
1940 <list compact="compact">
1941 <item><p>`<tt><--</tt>' generates KB_Backspace in
1944 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1948 X translations are set up to make KB_Backspace
1949 generate ASCII DEL, and to make KB_Delete generate
1950 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1951 the `delete character' key). This must be done by
1952 loading the resources using xrdb on all local X
1953 displays, not using the application defaults, so that
1954 the translation resources used correspond to the
1955 xmodmap settings.</p></item>
1959 The Linux console is configured to make
1960 `<tt><--</tt>' generate DEL, and `Delete' generate
1961 <tt>ESC [ 3 ~</tt> (this is the case at the
1965 X applications are configured so that Backspace
1966 deletes left, and Delete deletes right. Motif
1967 applications already work like this.</p></item>
1969 <item><p>stty erase <tt>^?</tt> .</p></item>
1972 The `xterm' terminfo entry should have <tt>ESC [ 3
1973 ~</tt> for kdch1, just like TERM=linux and
1974 TERM=vt220.</p></item>
1977 Emacs is programmed to map KB_Backspace or the `stty
1978 erase' character to delete-backward-char, and
1979 KB_Delete or kdch1 to delete-forward-char, and
1980 <tt>^H</tt> to help as always.</p></item>
1983 Other applications use the `stty erase' character and
1984 kdch1 for the two delete keys, with ASCII DEL being
1985 `delete previous character' and kdch1 being `delete
1986 character under cursor'.</p></item>
1990 This will solve the problem except for:</p>
1993 <list compact="compact">
1995 Some terminals have a <tt><--</tt> key that cannot
1996 be made to produce anything except <tt>^H</tt>. On
1997 these terminals Emacs help will be unavailable on
1998 <tt>^H</tt> (assuming that the `stty erase' character
1999 takes precedence in Emacs, and has been set
2000 correctly). M-x help or F1 (if available) can be used
2004 Some operating systems use <tt>^H</tt> for stty erase.
2005 However, modern telnet versions and all rlogin
2006 versions propagate stty settings, and almost all UNIX
2007 versions honour stty erase. Where the stty settings
2008 are not propagated correctly things can be made to
2009 work by using stty manually.</p></item>
2012 Some systems (including previous Debian versions) use
2013 xmodmap to arrange for both <tt><--</tt> and Delete
2014 to generate KB_Delete. We can change the behavior
2015 of their X clients via the same X resources that we
2016 use to do it for our own, or have our clients be
2017 configured via their resources when things are the
2018 other way around. On displays configured like this
2019 Delete will not work, but <tt><--</tt>
2023 Some operating systems have different kdch1 settings
2024 in their terminfo for xterm and others. On these
2025 systems the Delete key will not work correctly when
2026 you log in from a system conforming to our policy, but
2027 <tt><--</tt> will.</p></item>
2034 <heading>Environment variables</heading>
2037 No program may depend on environment variables to get
2038 reasonable defaults. (That's because these environment
2039 variables would have to be set in a system-wide
2040 configuration file like /etc/profile, which is not supported
2044 If a program should depend on environment variables for its
2045 configuration, the program has to be changed to fall back to
2046 a reasonable default configuration if these environment
2047 variables are not present. If this cannot be done easily
2048 (e.g., if the source code of a non-free program is not
2049 available), the program should be replaced by a small
2050 `wrapper' shell script which sets the environment variables
2051 and calls the original program.</p>
2054 Here is an example of a wrapper script for this purpose:
2060 exec /usr/lib/foo/foo "$@"
2064 Furthermore, as <tt>/etc/profile</tt> is a configuration
2065 file of the <prgn>bash</prgn> package, no other package may
2066 put any environment variables or other commands into that
2071 <heading>Files</heading>
2075 <heading>Binaries</heading>
2078 It is not allowed that two packages install programs with
2079 different functionality but with the same filenames. (The
2080 case of two programs having the same functionality but
2081 different implementations is handled via `alternatives.')
2082 If this case happens, one of the programs has to be
2083 renamed. The maintainers should report this to the
2084 developers' mailing and try to find a consensus about
2085 which package will have to be renamed. If a consensus can
2086 not be reached, <em>both</em> programs must be
2090 Generally the following compilation parameters should be used:
2093 CFLAGS = -O2 -Wall # sane warning options vary between programs
2095 install -s # (or use strip on the files in debian/tmp)
2099 Note that by default all installed binaries should be stripped,
2100 either by using the <tt>-s</tt> flag to
2101 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2102 the binaries after they have been copied into
2103 <tt>debian/tmp</tt> but before the tree is made into a
2107 The <tt>-N</tt> flag should not be used. On a.out systems
2108 it may have been useful for some very small binaries, but
2109 for ELF it has no good effect.</p>
2112 Debugging symbols are useful for error diagnosis, investigation
2113 of core dumps (which may be submitted by users in bug reports),
2114 or testing and developing the software. Therefore it is
2115 recommended to support building the package with
2116 debugging information through the following interface:
2117 If the environment variable <tt>DEB_BUILD_OPTIONS</tt>
2118 contains the string <tt>debug</tt>, compile the software with
2119 debugging information (usually this involves adding the
2120 <tt>-g</tt> flag to <tt>CFLAGS</tt>). This allows to generate
2121 a build tree with debugging information. If the environment
2122 variable <tt>DEB_BUILD_OPTIONS</tt> contains the
2123 string <tt>nostrip</tt>, do not strip the files at installation
2124 time. This allows to generate a package with debugging
2125 information included. The following makefile snippet
2126 is only an example how to test for either
2130 Rationale: Building by default with -g causes more
2131 wasted CPU cycles since the information is stripped away
2132 anyway. The package can by default build without -g if
2133 it also provides a mechanism to easily be rebuilt with
2134 debugging information. This can be done by providing a
2135 "build-debug" make target, or allowing the user to
2136 specify "BUILD_DEBUG=yes" in the environment while
2137 compiling that package.
2139 <p>Now this has several added benefits:
2143 It is actually easier to build debugging bins and
2144 libraries this way (no more editing debian/rules
2145 or similar) since it provides a documented way of
2146 getting this type of build.</p>
2150 There will be much less wasted cpu time for the
2151 autobuilders since not having debugging
2152 information (and hence also not having to strip
2153 it) will increase the speed of compiles. This
2154 skips an entire pass of the compiler,
2165 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
2167 ifneq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
2174 It is up to the package maintainer to decide what
2175 compilation options are best for the package. Certain
2176 binaries (such as computationally-intensive programs) may
2177 function better with certain flags (<tt>-O3</tt>, for
2178 example); feel free to use them. Please use good judgment
2179 here. Don't use flags for the sake of it; only use them
2180 if there is good reason to do so. Feel free to override
2181 the upstream author's ideas about which compilation
2182 options are best--they are often inappropriate for our
2183 environment.</p></sect>
2187 <heading>Libraries</heading>
2190 All libraries must have a shared version in the lib
2191 package and a static version in the lib-dev package. The
2192 shared version must be compiled with <tt>-fPIC</tt>, and
2193 the static version must not be. In other words, each
2194 <tt>*.c</tt> file is compiled twice.</p>
2197 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2198 when building a library (either static or shared) to make
2199 the library compatible with LinuxThreads.</p>
2202 Note that all installed shared libraries should be
2205 strip --strip-unneeded <your-lib>
2207 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2208 only the symbols which aren't needed for relocation
2209 processing.) Shared libraries can function perfectly well
2210 when stripped, since the symbols for dynamic linking are
2211 in a separate part of the ELF object file.</p>
2214 Note that under some circumstances it may be useful to
2215 install a shared library unstripped, for example when
2216 building a separate package to support debugging.
2220 An ever increasing number of packages are using libtool to
2221 do their linking. The latest GNU libtools (>= 1.3a) can take
2222 advantage of the metadata in the installed libtool archive
2223 files (`*.la'). The main advantage of libtool's .la files is
2224 that it allows libtool to store and subsequently access
2225 metadata with respect to the libraries it builds. libtool
2226 will search for those files, which contain a lot of useful
2227 information about a library (e.g. dependency libraries for
2228 static linking). Also, they're <em>essential</em> for
2229 programs using libltdl.
2233 Certainly libtool is fully capable of linking against shared
2234 libraries which don't have .la files, but being a mere shell
2235 script it can add considerably to the build time of a
2236 libtool using package if that shell-script has to derive all
2237 this information from first principles for each library every
2238 time it is linked. With the advent of libtool-1.4 (and to a
2239 lesser extent libtool-1.3), the .la files will also store
2240 information about inter-library dependencies which cannot
2241 necessarily be derived after the .la file is deleted.
2245 Packages that use libtool to create shared libraries must
2246 include the <em>.la</em> files in the <em>-dev</em>
2247 packages, with the exception that if the package relies on
2248 libtool's <em>libltdl</em> library, in which case the .la
2249 files must go in the run-time library package. This is a
2250 good idea in general, and especially for static linking
2255 Please make sure that you use only released versions of
2256 shared libraries to build your packages; otherwise other
2257 users will not be able to run your binaries
2258 properly. Producing source packages that depend on
2259 unreleased compilers is also usually a bad
2266 <heading>Shared libraries</heading>
2269 Packages involving shared libraries should be split up
2270 into several binary packages.</p>
2273 For a straightforward library which has a development
2274 environment and a runtime kit including just shared
2275 libraries you need to create two packages:
2276 <tt><var>libraryname</var><var>soname</var></tt>
2277 (<var>soname</var> is the shared object name of the shared
2278 library--it's the thing that has to match exactly between
2279 building an executable and running it for the dynamic
2280 linker to be able run the program; usually the
2281 <var>soname</var> is the major number of the library) and
2282 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2285 If you prefer only to support one development version at a
2286 time you may name the development package
2287 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2288 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2289 ensure that the user only installs one development version
2290 at a time (after all, different development versions are
2291 likely to have the same header files in them, causing a
2292 filename clash if both are installed). Typically the
2293 development version will also need an exact version
2294 dependency on the runtime library, to make sure that
2295 compilation and linking happens correctly.</p>
2298 Packages which use the shared library should have a
2299 dependency on the name of the shared library package,
2300 <tt><var>libraryname</var><var>soname</var></tt>. When
2301 the <var>soname</var> changes you can have both versions
2302 of the library installed while moving from the old library
2306 If your package has some run-time support programs which
2307 use the shared library you must <em>not</em> put them in
2308 the shared library package. If you do that then you won't
2309 be able to install several versions of the shared library
2310 without getting filename clashes. Instead, either create
2311 a third package for the runtime binaries (this package
2312 might typically be named
2313 <tt><var>libraryname</var>-runtime</tt>--note the absence
2314 of the <var>soname</var> in the package name) or if the
2315 development package is small include them in there.</p>
2318 If you have several shared libraries built from the same
2319 source tree you can lump them all together into a single
2320 shared library package, provided that you change all their
2321 <var>soname</var>s at once (so that you don't get filename
2322 clashes if you try to install different versions of the
2323 combined shared libraries package).</p>
2326 Follow the directions in the <em>Debian Packaging
2327 Manual</em> for putting the shared library in its package,
2328 and make sure you include a <tt>shlibs</tt> control area
2329 file with details of the dependencies for packages which
2330 use the library.</p>
2333 Shared libraries should <em>not</em> be installed
2334 executable, since <prgn>ld.so</prgn> does not require this
2335 and trying to execute a shared library results in a core
2340 <heading>Scripts</heading>
2343 All command scripts, including the package maintainer
2344 scripts inside the package and used by <prgn>dpkg</prgn>,
2345 should have a <tt>#!</tt> line naming the shell to be used
2346 to interpret them.</p>
2349 In the case of Perl scripts this should be
2350 <tt>#!/usr/bin/perl</tt>.</p>
2353 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2354 should almost certainly start with <tt>set -e</tt> so that
2355 errors are detected. Every script <em>must</em> use
2356 <tt>set -e</tt> or check the exit status of <em>every</em>
2360 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2361 symbolic link to any POSIX compatible shell. Thus, shell
2362 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2363 only use POSIX features. If a script requires non-POSIX
2364 features from the shell interpreter, the appropriate shell
2365 has to be specified in the first line of the script (e.g.,
2366 `<tt>#!/bin/bash</tt>') and the package has to depend on
2367 the package providing the shell (unless the shell package
2368 is marked `Essential', e.g., in the case of
2369 <prgn>bash</prgn>).</p>
2372 Restrict your script to POSIX features when possible so
2373 that it may use <tt>/bin/sh</tt> as its interpreter. If
2374 your script works with <prgn>ash</prgn>, it's probably
2375 POSIX compliant, but if you are in doubt, use
2376 <tt>/bin/bash</tt>.</p>
2379 Perl scripts should check for errors when making any
2380 system calls, including <tt>open</tt>, <tt>print</tt>,
2381 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2384 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2385 as scripting languages. See <em>Csh Programming
2386 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2387 FAQs. It can be found on
2388 <url id="http://language.perl.com/versus/csh.whynot">, or
2389 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2390 or even on <ftpsite>ftp.cpan.org</ftpsite>
2391 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2392 If an upstream package comes with <prgn>csh</prgn> scripts
2393 then you must make sure that they start with
2394 <tt>#!/bin/csh</tt> and make your package depend on the
2395 <prgn>c-shell</prgn> virtual package.</p>
2398 Any scripts which create files in world-writable
2399 directories (e.g., in <tt>/tmp</tt>) have to use a
2400 mechanism which will fail if a file with the same name
2404 The Debian base distribution provides the
2405 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2406 for use by scripts for this purpose.</p></sect>
2410 <heading>Symbolic links</heading>
2413 In general, symbolic links within a top-level directory
2414 should be relative, and symbolic links pointing from one
2415 top-level directory into another should be absolute. (A
2416 top-level directory is a sub-directory of the root
2420 In addition, symbolic links should be specified as short
2421 as possible, i.e., link targets like `foo/../bar' are
2425 Note that when creating a relative link using
2426 <prgn>ln</prgn> it is not necessary for the target of the
2427 link to exist relative to the working directory you're
2428 running <prgn>ln</prgn> from; nor is it necessary to
2429 change directory to the directory where the link is to be
2430 made. Simply include the string that should appear as the
2431 target of the link (this will be a pathname relative to
2432 the directory in which the link resides) as the first
2433 argument to <prgn>ln</prgn>.</p>
2436 For example, in your <prgn>Makefile</prgn> or
2437 <tt>debian/rules</tt>, do things like:
2439 ln -fs gcc $(prefix)/bin/cc
2440 ln -fs gcc debian/tmp/usr/bin/cc
2441 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2442 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2446 A symbolic link pointing to a compressed file should
2447 always have the same file extension as the referenced
2448 file. (For example, if a file `<tt>foo.gz</tt>' is
2449 referenced by a symbolic link, the filename of the link
2450 has to end with `<tt>.gz</tt>' too, as in
2451 `bar.gz.')</p></sect>
2455 <heading>Device files</heading>
2458 No package may include device files in the package file
2462 If a package needs any special device files that are not
2463 included in the base system, it has to call
2464 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2465 after asking the user for permission to do so.</p>
2468 No package should remove any device files in the
2469 <tt>postrm</tt> or any other script. This is left to the
2470 system administrator.</p>
2473 Debian uses the serial devices
2474 <tt>/dev/tty*</tt>. Programs using the old
2475 <tt>/dev/cu*</tt> devices should be changed to use
2476 <tt>/dev/tty*</tt>.</p>
2479 <sect id="config files">
2480 <heading>Configuration files</heading>
2482 <heading>Definitions</heading>
2485 <tag>configuration file</tag>
2487 A file that affects the operation of program, or
2488 provides site- or host-specific information, or
2489 otherwise customizes the behavior of program.
2490 Typically, configuration files are intended to be
2491 modified by the system administrator (if needed or
2492 desired) to conform to local policy or provide more
2493 useful site-specific behavior.</p>
2496 <tag><tt>conffile</tt></tag>
2498 A file listed in a package's <tt>conffiles</tt>
2499 file, and is treated specially by <prgn>dpkg</prgn>
2500 (see the <em>Debian Packaging Manual</em>).</p>
2506 The distinction between these two is important; they are
2507 not interchangeable concepts. Almost all
2508 <tt>conffiles</tt> are configuration files, but many
2509 configuration files are not <tt>conffiles</tt>.</p>
2512 Note that a script that embeds configuration information
2513 (such as most of the files in <tt>/etc/init.d</tt> and
2514 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2515 configuration file and should be treated as such.</p>
2519 <heading>Location</heading>
2521 Any configuration files created or used by your package
2522 should reside in <tt>/etc</tt>. If there are several you
2523 should consider creating a subdirectory of <tt>/etc</tt>
2524 named after your package.</p>
2527 If your packages creates or uses configuration files
2528 outside of <tt>/etc</tt>, and it is not feasible to modify
2529 the package to use the <tt>/etc</tt>, you should still put
2530 the files in <tt>/etc</tt> and create symbolic links to
2531 those files from the location that the package
2536 <heading>Behavior</heading>
2538 Configuration file handling must conform to the following
2542 <p>local changes must be preserved during a package
2546 <p>configuration files should be preserved when the
2547 package is removed, and only deleted when the
2548 package is purged.</p>
2553 The easy way to achieve this behavior is to make the
2554 configuration file a <tt>conffile</tt>. This is
2555 appropriate if it is possible to distribute a default
2556 version that will work for most installations, although
2557 some system administrators may choose to modify it. This
2558 implies that the default version will be part of the
2559 package distribution, and must not be modified by the
2560 maintainer scripts during installation (or at any other
2564 In order to ensure that local changes are preserved
2565 correctly, no package may contain or make hard links to
2569 Rationale: There are two problems with hard links.
2570 The first is that some editors break the link while
2571 editing one of the files, so that the two files may
2572 unwittingly become different. The second is that
2573 <prgn>dpkg</prgn> might break the hard link while
2574 upgrading <tt>conffile</tt>s.
2579 The other way to do it is to via the maintainer scripts.
2580 In this case, the configuration file must not be listed as
2581 a <tt>conffile</tt> and must not be part of the package
2582 distribution. If the existence of a file is required for
2583 the package to be sensibly configured it is the
2584 responsibility of the package maintainer to write scripts
2585 which correctly create, update, maintain and
2586 remove-on-purge the file. These scripts must be idempotent
2587 (i.e. must work correctly if <prgn>dpkg</prgn> needs to
2588 re-run them due to errors during installation or removal),
2589 must cope with all the variety of ways <prgn>dpkg</prgn>
2590 can call maintainer scripts, must not overwrite or
2591 otherwise mangle the user's configuration without asking,
2592 must not ask unnecessary questions (particularly during
2593 upgrades), and otherwise be good citizens.</p>
2596 The scripts need not configure every possible option for
2597 the package, but only those necessary to get the package
2598 running on a given system. Ideally the sysadmin should not
2599 have to do any configuration other than that done
2600 (semi-)automatically by the <tt>postinst</tt> script.</p>
2603 A common practice is to create a script called
2604 <tt><var>package</var>-configure</tt> and have the
2605 package's <tt>postinst</tt> call it if and only if the
2606 configuration file does not already exist. In certain
2607 cases it is useful for there to be an example or template
2608 file which the maintainer scripts use. Such files should
2609 be in <tt>/usr/share/doc</tt> if they are examples or
2610 <tt>/usr/lib</tt> if they are templates, and should be
2611 perfectly ordinary <prgn>dpkg</prgn>-handled files
2612 (<em>not</em> <tt>conffiles</tt>).</p>
2615 These two styles of configuration file handling <em>must
2616 not be mixed</em>, for that way lies madness:
2617 <prgn>dpkg</prgn> will ask about overwriting the file
2618 every time the package is upgraded.</p>
2623 <heading>Sharing configuration files</heading>
2625 Only packages that are tagged <em>conflicting</em> with
2626 each other may specify the same file as
2627 <tt>conffile</tt>.</p>
2630 The maintainer scripts should not alter the conffile of
2631 <em>any</em> package, including the one the scripts belong
2635 If two or more packages use the same configuration file
2636 and it is reasonable for both to be installed at the same
2637 time, one of these packages must be defined as
2638 <em>owner</em> of the configuration file, i.e. it will be
2639 the package to list that distributes the file and lists it
2640 as a <tt>conffile</tt>. Other packages that use the
2641 configuration file should depend on the owning package if
2642 they require the configuration file to operate. If the
2643 other package will use the configuration file if present,
2644 but is capable of operating without it, no dependency need
2648 If it is desirable for two or more related packages to
2649 share a configuration file <em>and</em> for all of the
2650 related packages to be able to modify that configuration
2651 file, then the following should done:
2655 have one of the related packages (the "core"
2656 package) manage the configuration file with
2657 maintainer scripts as described in the previous
2661 the core package should also provide a program that
2662 the other packages may use to modify the
2663 configuration file.</p>
2667 the related packages must use the provided program
2668 to make any modifications to the configuration file.
2669 They should either depend on the core package to
2670 guarantee that the configuration modifier program is
2671 available or accept gracefully that they cannot
2672 modify the configuration file if it is not.</p>
2677 Sometimes it's appropriate to create a new package which
2678 provides the basic infrastructure for the other packages
2679 and which manages the shared configuration files. (Check
2680 out the <tt>sgml-base</tt> package as an example.)</p>
2684 <heading>User configuration files ("dotfiles")</heading>
2687 Files in <tt>/etc/skel</tt> will automatically be copied
2688 into new user accounts by <prgn>adduser</prgn>. They
2689 should not be referenced there by any program.</p>
2692 Therefore, if a program needs a dotfile to exist in
2693 advance in <tt>$HOME</tt> to work sensibly that dotfile
2694 should be installed in <tt>/etc/skel</tt> (and listed in
2695 conffiles, if it is not generated and modified dynamically
2696 by the package's installation scripts).</p>
2699 However, programs that require dotfiles in order to
2700 operate sensibly (dotfiles that they do not create
2701 themselves automatically, that is) are a bad thing, and
2702 programs should be configured by the Debian default
2703 installation as close to normal as possible.</p>
2706 Therefore, if a program in a Debian package needs to be
2707 configured in some way in order to operate sensibly that
2708 configuration should be done in a site-wide global
2709 configuration file elsewhere in <tt>/etc</tt>. Only if the
2710 program doesn't support a site-wide default configuration
2711 and the package maintainer doesn't have time to add it
2712 should a default per-user file be placed in
2713 <tt>/etc/skel</tt>.</p>
2716 <tt>/etc/skel</tt> should be as empty as we can make it.
2717 This is particularly true because there is no easy
2718 mechanism for ensuring that the appropriate dotfiles are
2719 copied into the accounts of existing users when a package
2725 <heading>Log files</heading>
2727 The traditional approach to log files has been to set up ad
2728 hoc log rotation schemes using simple shell scripts and
2729 cron. While this approach is highly customizable, it
2730 requires quite a lot of sysadmin work. Even though the
2731 original Debian system helped a little by automatically
2732 installing a system which can be used as a template, this
2733 was deemed not enough.
2737 A better scheme is to use logrotate, a GPL'd program
2738 developed by Red Hat, which centralizes log management. It
2739 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2740 and a directory where packages can drop logrotation info
2741 (<tt>/etc/logrotate.d</tt>).
2745 Log files should usually be named
2746 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2747 log files, or need a separate directory for permissions
2748 reasons (<tt>/var/log</tt> is writable only by
2749 <tt>root</tt>), you should usually create a directory named
2750 <tt>/var/log/<var>package</var></tt>.</p>
2753 Make sure that any log files are rotated occasionally so
2754 that they don't grow indefinitely; the best way to do this
2755 is to drop a script into the directory
2756 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2757 logrotate. Here is a good example for a logrotate config
2758 file (for more information see <manref name="logrotate"
2766 /etc/init.d/foo force-reload
2770 Which rotates all files under `/var/log/foo', saves 12
2771 compressed generations, and sends a HUP signal at the end of
2777 Make sure that any log files are removed when the package is
2778 purged (but not when it is only removed), by checking the
2779 argument to the <tt>postrm</tt> script (see the <em>Debian
2780 Packaging Manual</em> for details).</p>
2785 <heading>Permissions and owners</heading>
2788 The rules in this section are guidelines for general use.
2789 If necessary you may deviate from the details below.
2790 However, if you do so you must make sure that what is done
2791 is secure and you must try to be as consistent as possible
2792 with the rest of the system. You should probably also
2793 discuss it on <prgn>debian-devel</prgn> first.</p>
2796 Files should be owned by <tt>root.root</tt>, and made
2797 writable only by the owner and universally readable (and
2798 executable, if appropriate).</p>
2801 Directories should be mode 755 or (for group-writability)
2802 mode 2775. The ownership of the directory should be
2803 consistent with its mode--if a directory is mode 2775, it
2804 should be owned by the group that needs write access to
2808 Setuid and setgid executables should be mode 4755 or 2755
2809 respectively, and owned by the appropriate user or group.
2810 They should not be made unreadable (modes like 4711 or
2811 2711 or even 4111); doing so achieves no extra security,
2812 because anyone can find the binary in the freely available
2813 Debian package--it is merely inconvenient. For the same
2814 reason you should not restrict read or execute permissions
2815 on non-set-id executables.</p>
2818 Some setuid programs need to be restricted to particular
2819 sets of users, using file permissions. In this case they
2820 should be owned by the uid to which they are set-id, and
2821 by the group which should be allowed to execute them.
2822 They should have mode 4754; there is no point in making
2823 them unreadable to those users who must not be allowed to
2827 Do not arrange that the system administrator can only
2828 reconfigure the package to correspond to their local
2829 security policy by changing the permissions on a binary.
2830 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2831 to conffiles and other similar objects) have their
2832 permissions reset to the distributed permissions when the
2833 package is reinstalled. Instead you should consider (for
2834 example) creating a group for people allowed to use the
2835 program(s) and making any setuid executables executable
2836 only by that group.</p>
2839 If you need to create a new user or group for your package
2840 there are two possibilities. Firstly, you may need to
2841 make some files in the binary package be owned by this
2842 user or group, or you may need to compile the user or
2843 group id (rather than just the name) into the binary
2844 (though this latter should be avoided if possible). In
2845 this case you need a statically allocated id.</p>
2848 You must ask for a user or group id from the base system
2849 maintainer, and must not release the package until you
2850 have been allocated one. Once you have been allocated one
2851 you must make the package depend on a version of the base
2852 system with the id present in <tt>/etc/passwd</tt> or
2853 <tt>/etc/group</tt>, or alternatively arrange for your
2854 package to create the user or group itself with the
2855 correct id (using <tt>adduser</tt>) in its pre- or
2856 post-installation script (the latter is to be preferred if
2857 it is possible).</p>
2860 On the other hand, the program may able to determine the
2861 uid or gid from the group name at runtime, so that a
2862 dynamic id can be used. In this case you must choose an
2863 appropriate user or group name, discussing this on
2864 <prgn>debian-devel</prgn> and checking with the base
2865 system maintainer that it is unique and that they do not
2866 wish you to use a statically allocated id instead. When
2867 this has been checked you must arrange for your package to
2868 create the user or group if necessary using
2869 <prgn>adduser</prgn> in the pre- or post-installation
2870 script (again, the latter is to be preferred if it is
2874 Note that changing the numeric value of an id associated with a name
2875 is very difficult, and involves searching the file system for all
2876 appropriate files. You need to think carefully whether a static or
2877 dynamic id is required, since changing your mind later will cause
2883 <heading>Customized programs</heading>
2885 <sect id="arch-spec">
2886 <heading>Architecture specification strings</heading>
2889 If a program needs to specify an <em>architecture specification
2890 string</em> in some place, the following format has to be used:
2892 <arch>-<os>
2894 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2895 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2896 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2897 operating system. .</p>
2899 Note, that we don't want to use `<arch>-debian-linux'
2900 to apply to the rule `architecture-vendor-os' since this
2901 would make our programs incompatible to other Linux
2902 distributions. Also note, that we don't use
2903 `<arch>-unknown-linux', since the `unknown' does not
2904 look very good.</p></sect>
2908 <heading>Daemons</heading>
2911 The configuration files <tt>/etc/services</tt>,
2912 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2913 by the <prgn>netbase</prgn> package and may not be modified
2914 by other packages.</p>
2917 If a package requires a new entry in one of these files, the
2918 maintainer has to get in contact with the
2919 <prgn>netbase</prgn> maintainer, who will add the entries
2920 and release a new version of the <prgn>netbase</prgn>
2924 The configuration file <tt>/etc/inetd.conf</tt> may be
2925 modified by the package's scripts only via the
2926 <prgn>update-inetd</prgn> script or the
2927 <prgn>DebianNet.pm</prgn> Perl module.</p>
2930 If a package wants to install an example entry into
2931 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2932 exactly one hash character (<tt>#</tt>). Such lines are
2933 treated as `commented out by user' by the
2934 <prgn>update-inetd</prgn> script and are not changed or
2935 activated during a package updates.</p></sect>
2939 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2942 Some programs need to create pseudo-ttys. This should be done
2943 using Unix98 ptys if the C library supports it. The resulting
2944 program must not be installed setuid root, unless that
2945 is required for other functionality.
2949 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2950 <tt>/var/log/lastlog</tt> must be installed writeable by
2951 group utmp. Programs who need to modify those files must
2952 be installed install setgid utmp.
2957 <heading>Editors and pagers</heading>
2960 Some programs have the ability to launch an editor or pager
2961 program to edit or display a text document. Since there are
2962 lots of different editors and pagers available in the Debian
2963 distribution, the system administrator and each user should
2964 have the possibility to choose his/her preferred editor and
2968 In addition, every program should choose a good default
2969 editor/pager if none is selected by the user or system
2973 Thus, every program that launches an editor or pager has to
2974 use the EDITOR or PAGER environment variables to determine
2975 the editor/pager the user wants to get started. If these
2976 variables are not set, the programs <tt>/usr/bin/editor</tt>
2977 and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
2980 These two files are managed through `alternatives.' That is,
2981 every package providing an editor or pager has to call the
2982 <prgn>update-alternatives</prgn> script to register these
2986 If it is very hard to adapt a program to make us of the
2987 EDITOR and PAGER variable, that program should be configured
2988 to use <tt>/usr/bin/sensible-editor</tt> and
2989 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
2990 respectively. These are two scripts provided in the Debian
2991 base system that check the EDITOR and PAGER variables and
2992 launches the appropriate program or falls back to
2993 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
2997 A program may also use the VISUAL environment variable to
2998 determine the user's choice of editor. If it exists, it
2999 should take precedence over EDITOR. This is in fact what
3000 <tt>/usr/bin/sensible-editor</tt> does.</p>
3003 Since the Debian base system already provides an editor and
3004 a pager program, there is no need for a package to depend on
3005 `editor' and `pager', nor is it necessary for a package to
3006 provide such virtual packages.</p></sect>
3009 <sect id="web-appl">
3010 <heading>Web servers and applications</heading>
3013 This section describes the locations and URLs that have to
3014 be used by all web servers and web application in the Debian
3020 <p>Cgi-bin executable files are installed in the
3023 /usr/lib/cgi-bin/<cgi-bin-name>
3025 and can be referred to as
3027 http://localhost/cgi-bin/<cgi-bin-name>
3028 </example></p></item>
3031 <item><p>Access to html documents</p>
3034 Html documents for a package are stored in
3035 <tt>/usr/share/doc/<var>package</var></tt> but should
3036 be accessed via symlinks as
3037 <tt>/usr/doc/<var>package</var></tt><footnote> for
3038 backward compatibility, see <ref id="usrdoc"></footnote>
3039 and can be referred to as
3041 http://localhost/doc/<package>/<filename>
3042 </example></p></item>
3045 <item><p>Web Document Root</p>
3048 Web Applications should try to avoid storing files in
3049 the Web Document Root. Instead use the
3050 /usr/share/doc/<package> directory for documents and
3051 register the Web Application via the menu package. If
3052 access to the web-root is unavoidable then use
3056 as the Document Root. This might be just a
3057 symbolic link to the location where the sysadmin has
3058 put the real document root.</p>
3061 </enumlist></p></sect>
3065 <heading>Mail transport agents</heading>
3068 Debian packages which process electronic mail, whether
3069 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
3070 <em>must</em> make sure that they are compatible with the
3071 configuration decisions below. Failure to do this may
3072 result in lost mail, broken <tt>From:</tt> lines, and other
3073 serious brain damage!</p>
3076 The mail spool is <tt>/var/spool/mail</tt> and the interface
3077 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3078 per the FHS). The mail spool is part of the base system
3079 and not part of the MTA package.</p>
3082 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3083 programs (like IMAP daemons) have to lock the mailbox in a
3084 NFS-safe way. This means that <tt>fcntl()</tt> locking has
3085 to be combined with dot locking. To avoid dead locks, a
3086 program has to use <tt>fcntl()</tt> first and dot locking
3087 after this or alternatively implement the two locking
3088 methods in a non blocking way<footnote>
3090 If it is not possible to establish both locks, the
3091 system shouldn't wait for the second lock to be
3092 established, but remove the first lock, wait a (random)
3093 time, and start over locking again.</p>
3094 </footnote>. Using the functions <tt>maillock</tt> and
3095 <tt>mailunlock</tt> provided by the
3096 <tt>liblockfile*</tt><footnote>
3098 <tt>liblockfile</tt> version >>1.01</p>
3099 </footnote> packages is the recommended way to realize this.
3103 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3104 unless the user has chosen otherwise. A MUA may remove a
3105 mailbox (unless it has nonstandard permissions) in which
3106 case the MTA or another MUA must recreate it if needed.
3107 Mailboxes must be writable by group mail.</p>
3110 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
3111 be setgid mail to do the locking mentioned above (and
3112 obviously need to avoid accessing other users' mailboxes
3113 using this privilege).</p>
3116 <tt>/etc/aliases</tt> is the source file for the system mail
3117 aliases (e.g., postmaster, usenet, etc.)--it is the one
3118 which the sysadmin and <tt>postinst</tt> scripts may edit.
3119 After <tt>/etc/aliases</tt> is edited the program or human
3120 editing it must call <prgn>newaliases</prgn>. All MTA
3121 packages should come with a <prgn>newaliases</prgn> program,
3122 even if it does nothing, but older MTA packages do not do
3123 this so programs should not fail if <prgn>newaliases</prgn>
3124 cannot be found.</p>
3127 The convention of writing <tt>forward to
3128 <var>address</var></tt> in the mailbox itself is not
3129 supported. Use a <tt>.forward</tt> file instead.</p>
3132 The location for the <prgn>rmail</prgn> program used by UUCP
3133 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
3134 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3135 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
3139 If you need to know what name to use (for example) on
3140 outgoing news and mail messages which are generated locally,
3141 you should use the file <tt>/etc/mailname</tt>. It will
3142 contain the portion after the username and <tt>@</tt> (at)
3143 sign for email addresses of users on the machine (followed
3147 A package should check for the existence of this file. If
3148 it exists it should use it without comment. (An MTA's
3149 prompting configuration script may wish to prompt the user
3150 even if it finds this file exists.) If it does not exist it
3151 should prompt the user for the value and store it in
3152 <tt>/etc/mailname</tt> as well as using it in the package's
3153 configuration. The prompt should make it clear that the
3154 name will not just be used by that package. For example, in
3155 this situation the INN package says:
3157 Please enter the `mail name' of your system. This is the
3158 hostname portion of the address to be shown on outgoing
3159 news and mail messages. The default is
3160 <var>syshostname</var>, your system's host name. Mail
3161 name [`<var>syshostname</var>']:
3163 where <var>syshostname</var> is the output of <tt>hostname
3164 --fqdn</tt>.</p></sect>
3168 <heading>News system configuration</heading>
3171 All the configuration files related to the NNTP (news)
3172 servers and clients should be located under
3173 <tt>/etc/news</tt>.</p>
3176 There are some configuration issues that apply to a number
3177 of news clients and server packages on the machine. These
3181 <tag>/etc/news/organization</tag>
3182 <item><p>A string which shall appear as the
3183 organization header for all messages posted
3184 by NNTP clients on the machine</p></item>
3186 <tag>/etc/news/server</tag>
3187 <item><p>Contains the FQDN of the upstream NNTP
3188 server, or localhost if the local machine is
3189 an NNTP server.</p></item>
3192 Other global files may be added as required for cross-package news
3193 configuration.</p></sect>
3197 <heading>Programs for the X Window System</heading>
3200 Some programs can be configured with or without support for the X
3201 Window System. Typically, binaries produced with support for X
3202 will need the X shared libraries to run.
3206 Such programs should be configured <em>with</em> X support,
3207 and should declare a dependency on <tt>xlib6g</tt> (which
3208 contains X shared libraries). Users who wish to use the
3209 program can install just the relatively small
3210 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
3211 not need to install the whole of X.
3213 <p>Note: With the release of the new X window System
3214 version (4.X), there probably shall be a sweeping change
3215 in the X Window System Policy in the future.</p>
3220 Do not create two versions (one with X support and one
3221 without) of your package.</p>
3224 <em>Packages which provide an X server</em> that, directly or
3225 indirectly, communicates with real input and display hardware
3226 should declare in their control data that they provide the
3227 virtual package <tt>xserver</tt>.
3230 Rationale: implement current practice, and provide an
3231 actual policy for usage of the "xserver" virtual package
3232 which appears in the virtual packages list.
3233 In a nutshell, X servers that interface directly with
3234 the display and input hardware or via another subsystem
3235 (e.g., GGI) should provide xserver. Things like Xvfb,
3236 Xnest, and Xprt should not.
3242 <em>Packages that provide a terminal emulator</em> for the X
3243 Window System which support a terminal type with a terminfo
3244 description provided in the <tt>ncurses-base</tt> package
3245 should declare in their control data that they provide the
3246 virtual package <tt>x-terminal-emulator</tt>. They should
3247 also register themselves as an alternative for
3248 <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
3253 <em>Packages that provide window managers</em> should declare in
3254 their control data that they provide the virtual package
3255 <tt>x-window-manager</tt>. They should also register themselves as an
3256 alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
3257 calculated as follows:
3259 <item>Start with a priority of 20.</item>
3260 <item>If the window manager supports the Debian menu system,
3261 add 20 points if this support is available in the
3262 package's default configuration (i.e., no
3263 configuration files belonging to the system or user
3264 have to be edited to activate the feature); if
3265 configuration files must be modified, add only 10
3267 <item>If the window manager permits the X session to be
3268 restarted using a <em>different</em> window manager
3269 (without killing the X server) in its default
3270 configuration, add 10 points; otherwise add
3276 <em>Packages that provide fonts for the X Window System</em>
3277 must do a number of things to ensure that they are both
3278 available without modification of the X or font server
3279 configuration, and that they do not corrupt files used by
3280 other font packages to register information about themselves.
3283 Fonts of any type supported by the X Window System
3284 should be be in a separate binary package from any
3285 executables, libraries, or documentation (except that
3286 specific to the fonts shipped); if a program or
3287 library is <em>unusable</em> without one or more
3288 specific fonts, the package containing the program or
3289 library should declare a dependency on the package(s)
3290 containing the font(s) it requires.
3293 BDF fonts should be converted to PCF fonts with the
3294 <tt>bdftopcf</tt> utility (available in the
3295 <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
3296 placed in a directory that corresponds to their
3300 100 dpi fonts should be placed in
3301 <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
3304 75 dpi fonts should be placed in
3305 <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
3308 Character-cell fonts, cursor fonts, and other
3309 low-resolution fonts should be placed in
3310 <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
3315 Speedo fonts should be placed in
3316 <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
3319 Type 1 fonts should be placed in
3320 /usr/X11R6/lib/X11/fonts/Type1/</tt>. If font metric files are
3321 available, they may be placed here as well.
3324 Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
3325 other than those listed above should be neither created nor
3326 used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
3327 excepted for historical reasons, but installation of files into
3328 these directories remains discouraged.)
3331 Font packages may, instead of placing files directly in
3332 the X font directories listed above, provide symbolic links in
3333 the font directory which point to the files' actual location
3334 in the filesystem. Such a location should comply with the
3338 Font packages should not contain both 75dpi and 100dpi
3339 versions of a font. If both are available, they should be
3340 provided in separate binary packages with "-75dpi" or "-100dpi"
3341 appended to the names of the packages containing the
3342 corresponding fonts.
3345 Fonts destined for the <tt>misc</tt> subdirectory should
3346 not be included in the same package as 75dpi or 100dpi fonts;
3347 instead, they should be provided in a separate package with
3348 "-misc" appended to its name.
3351 Font packages <em>must not</em> provide the files
3352 <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
3353 <tt>fonts.scale</tt> in a font directory.
3356 <tt>fonts.dir</tt> files must not be provided at
3360 <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
3361 files, if needed, should be provided in the
3363 <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
3364 where <em>fontdir</em> is the name of the
3366 <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
3367 package's corresponding fonts are stored (e.g.,
3368 <tt>75dpi</tt> or <tt>misc</tt>),
3369 <em>package</em> is the name of the package that
3370 provides these fonts, and <em>extension</em> is
3371 either <tt>scale</tt> or <tt>alias</tt>,
3372 whichever corresponds to the file
3378 Font packages must declare a dependency on
3379 <tt>xbase-clients</tt> and, in the package
3380 post-installation and post-removal scripts, invoke the
3381 <tt>mkfontdir</tt> command on each directory into
3382 which they installed fonts.
3385 Font packages that provide one or more
3386 <tt>fonts.scale</tt> files as described above must declare a
3387 versioned dependency on <tt>xbase-clients (>=
3388 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
3389 directory into which they installed fonts
3390 <em>before</em> invoking <tt>mkfontdir</tt> on that
3391 directory. This invocation must occur in both the
3392 post-installation and post-removal scripts.
3395 Font packages that provide one or more
3396 <tt>fonts.alias</tt> files as described above must
3397 declare a versioned dependency on <tt>xbase-clients
3398 (>= 3.3.3.1-5)</tt> and, in the package
3399 post-installation and post-removal scripts, invoke
3400 <tt>update-fonts-alias</tt> on each directory into
3401 which they installed fonts.
3404 Font packages must not provide alias names for the
3405 fonts they include which collide with alias names already in
3406 use by fonts already packaged.
3409 Font packages must not provide fonts with the same XLFD
3410 registry name as another font already packaged.
3416 <em>Application defaults</em> files must be installed in the
3417 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They should
3418 not be registered as <em>conffile</em>s or otherwise treated as
3419 configuration files. Customization of programs' X resources may
3420 be supported with the provision of a file with the same name as
3421 that of the package placed in the <tt>/etc/X11/Xresources/</tt>
3422 directory, which should be registered as a <em>conffile</em>.
3423 <em>Important:</em> packages that install files into the
3424 <tt>/etc/X11/Xresources/</tt> directory <em>must</em> declare a
3425 conflict with <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is
3426 not done it is possible for the installing package to destroy a
3427 previously-existing <tt>/etc/X11/Xresources</tt> <em>file</em>
3428 which had been customized by the system administrator.
3430 <p>Rationale: clarifies the language to properly
3431 address the package maintainer, not the system
3432 administrator, as to how to manage
3433 /etc/X11/Xresources.</p>
3439 <em>Packages using the X Window System should abide by the FHS
3440 standard whenever possible</em>; they should install binaries,
3441 libraries, manual pages, and other files in FHS-mandated
3442 locations wherever possible. This means that files should
3443 not be installed into <tt>/usr/X11R6/bin/</tt>,
3444 <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
3445 this is necessary for the package to operate properly.
3446 Configuration files for window managers and display managers
3447 should be placed in a subdirectory of <tt>/etc/X11/</tt>
3448 corresponding to the package name due to these programs'
3449 tight integration with the mechanisms of the X Window
3450 System. Application-level programs should use the
3451 <tt>/etc/</tt> directory unless otherwise mandated by
3452 policy. The installation of files into subdirectories of
3453 <tt>/usr/X11R6/include/X11/</tt> and
3454 <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
3455 package maintainers should determine if subdirectories of
3456 <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
3457 instead (symlinks from the X11R6 directories to
3458 FHS-compliant locations is encouraged if the program is not
3459 easily configured to look elsewhere for its files).
3460 Packages must not provide -- or install files into -- the
3461 directories <tt>/usr/bin/X11/</tt>,
3462 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
3463 Files within a package should, however, make reference to
3464 these directories, rather than their X11R6-named
3465 counterparts <tt>/usr/X11R6/bin/</tt>,
3466 <tt>/usr/X11R6/include/X11/</tt>, and
3467 <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
3468 referred to have not been moved to FHS-compliant locations.
3472 <em>Programs that require the non-DFSG-compliant OSF/Motif
3473 library</em> should be compiled against and tested with
3474 LessTif (a free re-implementation of Motif) instead. If the
3475 maintainer judges that the program or programs do not work
3476 sufficiently well with LessTif to be distributed and
3477 supported, but do so when compiled against Motif, then two
3478 versions of the package should be created; one linked
3479 statically against Motif and with <tt>-smotif</tt> appended
3480 to the package name, and one linked dynamically against
3481 Motif and with <tt>-dmotif</tt> appended to the package
3482 name. Both Motif-linked versions are dependent upon
3483 non-DFSG-compliant software and thus cannot be uploaded to
3484 the main distribution; if the software is itself
3485 DFSG-compliant it may be uploaded to the contrib
3486 distribution. While known existing versions of OSF/Motif
3487 permit unlimited redistribution of binaries linked against
3488 the library (whether statically or dynamically), it is the
3489 package maintainer's responsibility to determine whether
3490 this is permitted by the license of the copy of OSF/Motif in
3491 his or her possession.
3497 <heading>Emacs lisp programs</heading>
3500 Please refer to the `Debian Emacs Policy' (documented in
3501 <tt>debian-emacs-policy.gz</tt> of the
3502 <prgn>emacsen-common</prgn> package) for details of how to
3503 package emacs lisp programs.</p></sect>
3507 <heading>Games</heading>
3510 The permissions on /var/games are 755
3511 <tt>root.root</tt>.</p>
3514 Each game decides on its own security policy.</p>
3517 Games which require protected, privileged access to
3518 high-score files, savegames, etc., must be made
3519 set-<em>group</em>-id (mode 2755) and owned by
3520 <tt>root.games</tt>, and use files and directories with
3521 appropriate permissions (770 <tt>root.games</tt>, for
3522 example). They must <em>not</em> be made
3523 set-<em>user</em>-id, as this causes security problems. (If
3524 an attacker can subvert any set-user-id game they can
3525 overwrite the executable of any other, causing other players
3526 of these games to run a Trojan horse program. With a
3527 set-group-id game the attacker only gets access to less
3528 important game data, and if they can get at the other
3529 players' accounts at all it will take considerably more
3533 Some packages, for example some fortune cookie programs, are
3534 configured by the upstream authors to install with their
3535 data files or other static information made unreadable so
3536 that they can only be accessed through set-id programs
3537 provided. Do not do this in a Debian package: anyone can
3538 download the <tt>.deb</tt> file and read the data from it,
3539 so there is no point making the files unreadable. Not
3540 making the files unreadable also means that you don't have
3541 to make so many programs set-id, which reduces the risk of a
3545 As described in the FHS, binaries of games should be
3546 installed in the directory <tt>/usr/games</tt>. This also
3547 applies to games that use the X Window System. Manual pages
3548 for games (X and non-X games) should be installed in
3549 <tt>/usr/share/man/man6</tt>.</p>
3553 <chapt><heading>Documentation</heading>
3557 <heading>Manual pages</heading>
3560 You must install manual pages in <prgn>nroff</prgn> source
3561 form, in appropriate places under <tt>/usr/share/man</tt>. You
3562 should only use sections 1 to 9 (see the FHS for more
3563 details). You must <em>not</em> install a preformatted `cat
3567 If no manual page is available for a particular program,
3568 utility or function and this is reported as a bug on
3569 debian-bugs, a symbolic link from the requested manual page
3570 to the <manref name="undocumented" section="7"> manual page
3571 should be provided. This symbolic link can be created from
3572 <tt>debian/rules</tt> like this:
3574 ln -s ../man7/undocumented.7.gz \
3575 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3577 This manpage claims that the lack of a manpage has been
3578 reported as a bug, so you may only do this if it really has
3579 (you can report it yourself, if you like). Do not close the
3580 bug report until a proper manpage is available.</p>
3583 You may forward a complaint about a missing manpage to the
3584 upstream authors, and mark the bug as forwarded in the
3585 Debian bug tracking system. Even though the GNU Project do
3586 not in general consider the lack of a manpage to be a bug,
3587 we do--if they tell you that they don't consider it a bug
3588 you should leave the bug in our bug tracking system open
3592 Manual pages should be installed compressed using <tt>gzip
3596 If one manpage needs to be accessible via several names it
3597 is better to use a symbolic link than the <tt>.so</tt>
3598 feature, but there is no need to fiddle with the relevant
3599 parts of the upstream source to change from <tt>.so</tt> to
3600 symlinks--don't do it unless it's easy. Do not create hard
3601 links in the manual page directories, and do not put
3602 absolute filenames in <tt>.so</tt> directives. The filename
3603 in a <tt>.so</tt> in a manpage should be relative to the
3604 base of the manpage tree (usually
3605 <tt>/usr/share/man</tt>).</p></sect>
3609 <heading>Info documents</heading>
3612 Info documents should be installed in <tt>/usr/share/info</tt>.
3613 They should be compressed with <tt>gzip -9</tt>.</p>
3616 Your package must call <prgn>install-info</prgn> to update the Info
3618 file, in its post-installation script:
3620 install-info --quiet --section Development Development \
3621 /usr/share/info/foobar.info
3625 It is a good idea to specify a section for the location of
3626 your program; this is done with the <tt>--section</tt>
3627 switch. To determine which section to use, you should look
3628 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3629 relevant (or create a new section if none of the current
3630 sections are relevant). Note that the <tt>--section</tt>
3631 flag takes two arguments; the first is a regular expression
3632 to match (case-insensitively) against an existing section,
3633 the second is used when creating a new one.</p>
3636 You must remove the entries in the pre-removal script:
3638 install-info --quiet --remove /usr/share/info/foobar.info
3642 If <prgn>install-info</prgn> cannot find a description entry
3643 in the Info file you will have to supply one. See <manref
3644 name="install-info" section="8"> for details.</p>
3648 <heading>Additional documentation</heading>
3651 Any additional documentation that comes with the package can
3652 be installed at the discretion of the package maintainer.
3653 Text documentation should be installed in a directory
3654 <tt>/usr/share/doc/<var>package</var></tt>, where
3655 <var>package</var> is the name of the package, and
3656 compressed with <tt>gzip -9</tt> unless it is small.</p>
3659 If a package comes with large amounts of documentation which
3660 many users of the package will not require you should create
3661 a separate binary package to contain it, so that it does not
3662 take up disk space on the machines of users who do not need
3663 or want it installed.</p>
3666 It is often a good idea to put text information files
3667 (<tt>README</tt>s, changelogs, and so forth) that come with
3668 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3669 in the binary package. However, you don't need to install
3670 the instructions for building and installing the package, of
3675 <heading>Accessing the documentation</heading>
3678 Former Debian releases placed all additional documentation
3679 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3681 <tt>/usr/share/doc/<var>package</var></tt>, each package
3682 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3683 that points to the new location of its documentation in
3684 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3685 symlinks will be removed in the future, but they have to be
3686 there for compatibility reasons until all packages have
3687 moved and the policy is changed accordingly.</footnote>.
3688 The symlink must be created when the package is installed;
3689 it cannot be contained in the package itself due to problems
3690 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3691 this is to put the following in the package's
3692 <prgn>postinst</prgn>:
3694 if [ "$1" = "configure" ]; then
3695 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3696 -a -d /usr/share/doc/#PACKAGE# ]; then
3697 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3701 And the following in the package's <prgn>prerm</prgn>:
3703 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3704 -a -L /usr/doc/#PACKAGE# ]; then
3705 rm -f /usr/doc/#PACKAGE#
3712 <heading>Preferred documentation formats</heading>
3715 The unification of Debian documentation is being carried out
3719 If your package comes with extensive documentation in a
3720 mark up format that can be converted to various other formats
3721 you should if possible ship HTML versions in a binary
3722 package, in the directory
3723 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3726 <p>The rationale: The important thing here is that HTML
3727 docs should be available in <em>some</em> package, not
3728 necessarily in the main binary package, though. </p>
3733 Other formats such as PostScript may be provided at your
3737 <sect id="copyrightfile">
3738 <heading>Copyright information</heading>
3741 Every package must be accompanied by a verbatim copy of its
3742 copyright and distribution license in the file
3743 /usr/share/doc/<package-name>/copyright. This file must
3744 neither be compressed nor be a symbolic link.</p>
3747 In addition, the copyright file must say where the upstream
3748 sources (if any) were obtained, and explain briefly what
3749 modifications were made in the Debian version of the package
3750 compared to the upstream one. It must name the original
3751 authors of the package and the Debian maintainer(s) who were
3752 involved with its creation.</p>
3755 /usr/share/doc/<package-name> may be a symbolic link to a
3756 directory in /usr/share/doc only if two packages both come from
3757 the same source and the first package has a "Depends"
3758 relationship on the second. These rules are important
3759 because copyrights must be extractable by mechanical
3763 Packages distributed under the UCB BSD license, the Artistic
3764 license, the GNU GPL, and the GNU LGPL should refer to the
3765 files /usr/share/common-licenses/BSD,
3766 /usr/share/common-licenses/Artistic,
3767 /usr/share/common-licenses/GPL, and
3768 /usr/share/common-licenses/LGPL.
3771 Why "licenses" and not "copyright"? Because
3772 <tt>/usr/doc/copyright</tt> used to contain all the
3773 copyright files, plus the four common licenses GPL,
3774 LGPL, Artistic and BSD. Now individual copyright files
3775 for packages are no longer in a common directory. Once
3776 <tt>/usr/doc/copyright</tt> is almost empty it makes
3777 sense to rename "copyright" to "licenses"
3780 Why "common-licenses" and not "licenses"? Because if I
3781 put just "licenses" I'm sure I will receive a bug report
3782 saying "license foo is not included in the licenses
3783 directory. They are not all the licenses, just a few
3784 common ones. I could use /usr/share/doc/common-licenses
3785 but I think this is too long, and, after all, the GPL
3786 does not "document" anything, it is merely a license.
3792 Do not use the copyright file as a general <tt>README</tt>
3793 file. If your package has such a file it should be
3794 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3795 <tt>README.Debian</tt> or some other appropriate place.</p>
3799 <heading>Examples</heading>
3802 Any examples (configurations, source files, whatever),
3803 should be installed in a directory
3804 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3805 files should not be referenced by any program--they're there
3806 for the benefit of the system administrator and users, as
3807 documentation only. Architecture-specific example files
3808 should be installed in a directory
3809 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3810 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3811 to files in it. Or the latter directory may be a symlink to
3815 <sect id="instchangelog">
3816 <heading>Changelog files</heading>
3819 This installed file must contain a copy of the
3820 <tt>debian/changelog</tt> file from your Debian source tree,
3821 and a copy of the upstream changelog file if there is one.
3822 The debian/changelog file should be installed in
3823 <tt>/usr/share/doc/<var>package</var></tt> as
3824 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3825 file is text formatted, it must be accessible as
3826 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
3827 the upstream changelog file is HTML formatted, it must be
3829 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
3830 A plain text version of the changelog must be accessible as
3831 <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
3832 be created by <tt>lynx -dump -nolist</tt>). If the upstream
3833 changelog files do not already conform to this naming
3834 convention, then this may be achieved by either renaming the
3835 files or adding a symbolic link at the packaging developer's
3839 Rationale: People should not have to look into two
3840 places ofr upstream changelogs merely because they are
3847 Both should be installed compressed using <tt>gzip -9</tt>,
3848 as they will become large with time even if they start out
3852 If the package has only one changelog which is used both as
3853 the Debian changelog and the upstream one because there is
3854 no separate upstream maintainer then that changelog should
3855 usually be installed as
3856 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3857 there is a separate upstream maintainer, but no upstream
3858 changelog, then the Debian changelog should still be called
3859 <tt>changelog.Debian.gz</tt>.</p>