1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Policy Manual.
9 Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
10 released under the terms of the GNU
11 General Public License, version 2 or (at your option) any later.
12 Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
13 Revised November 27, 1996, David A. Morris, bweaver@debian.org
14 New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
15 Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
16 Maintainer since 1997, Christian Schwarz, schwarz@debian.org
17 Christoph Lameter contributed the "Web Standard"
18 The debian-policy mailing list has taken responsibility for the
19 contents of this document since September 1998, with the package
20 maintainers responsible for packaging adminstrivia only.
25 <title>Debian Policy Manual</title>
27 <name>Ian Jackson </name>
28 <email>ijackson@gnu.ai.mit.edu</email>
31 <name>Christian Schwarz</name>
32 <email>schwarz@debian.org</email>
35 <name>revised: David A. Morris</name>
36 <email>bweaver@debian.org</email>
39 <name>The Debian Policy mailing List</name>
40 <email>debian-policy@lists.debian.org</email>
42 <version>version &version;, &date;</version>
45 This manual describes the policy requirements for the Debian
46 GNU/Linux distribution. This includes the structure and
47 contents of the Debian archive, several design issues of the
48 operating system, as well as technical requirements that each
49 package must satisfy to be included in the distribution. The
50 policy package itself is maintained by a group of maintainers
51 that have no editorial powers. At the moment, the list of
55 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
58 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
61 <p>Philip Hands <email>phil@hands.com</email></p>
64 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
72 Copyright ©1996,1997,1998 Ian Jackson
73 and Christian Schwarz.
76 This manual is free software; you may redistribute it and/or
77 modify it under the terms of the GNU General Public License
78 as published by the Free Software Foundation; either version
79 2, or (at your option) any later version.
83 This is distributed in the hope that it will be useful, but
84 <em>without any warranty</em>; without even the implied
85 warranty of merchantability or fitness for a particular
86 purpose. See the GNU General Public License for more
91 A copy of the GNU General Public License is available as
92 <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
93 distribution or on the World Wide Web at
94 <url id="http://www.gnu.org/copyleft/gpl.html"
95 name="&urlname">. You can also obtain it by writing to the
96 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
97 Boston, MA 02111-1307, USA.
105 <heading>About this manual</heading>
107 <heading>Scope</heading>
109 This manual describes the policy requirements for the Debian
110 GNU/Linux distribution. This includes the structure and
111 contents of the Debian archive, several design issues of the
112 operating system, as well as technical requirements that
113 each package must satisfy to be included in the
117 This manual does <em>not</em> describe the technical
118 mechanisms involved in package creation, installation, and
119 removal. This information can be found in the <em>Debian
120 Packaging Manual</em> and the <em>Debian System
121 Administrators' Manual</em>.
124 This document assumes familiarity with these other two
125 manuals. Unfortunately, the <em>System Administrators'
126 Manual</em> does not exist yet.
129 Much of the information presented in this manual will be
130 useful even when building a package which is to be
131 distributed in some other way or is for local use.
135 <heading>New versions of this document</heading>
137 The current version of this document is always accessible from the
138 Debian FTP server <ftpsite>ftp.debian.org</ftpsite> at
139 <ftppath>/debian/doc/manuals/debian-policy.html.tar.gz</ftppath>
140 or from the Debian WWW server at
141 <url id="http://www.debian.org/doc/debian-policy/"
142 name="&urlname">.</p>
145 In addition, this manual is distributed via the Debian package
146 <tt>debian-policy</tt>.
150 <heading>Feedback</heading>
153 As the Debian GNU/Linux system is continuously evolving this
154 manual is changed from time to time.
157 While the authors of this document tried hard not to include
158 any typos or other errors these still occur. If you discover
159 an error in this manual or if you want to tell us any
160 comments, suggestions, or critics please send an email to
161 the Debian Policy List,
162 <email>debian-policy@lists.debian.org</email>, or submit a
163 bug report against the <tt>debian-policy</tt> package.
168 <heading>The Debian Archive</heading>
170 The Debian GNU/Linux system is maintained and distributed as a
171 collection of <em>packages</em>. Since there are so many of them (over
172 2600) they are split into <em>sections</em> and <em>priorities</em> to
173 simplify handling of them.
176 The effort of the Debian project is to build a free operating
177 system, but not every package we want to make accessible is
178 <em>free</em> in our sense (see Debian Free Software
179 Guidelines, below), or may be imported/exported without
180 restrictions. Thus, the archive is split into the sections
181 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
182 <em>contrib</em>.</p>
184 The <em>main</em> section forms the <em>Debian GNU/Linux
185 distribution</em>. </p>
187 Packages in the other sections are not considered as part of
188 the Debian distribution, though we support their use, and we
189 provide infrastructure for them (such as our bug-tracking
190 system and mailing lists). This Debian Policy Manual applies
191 to these packages as well.</p>
193 <sect id="pkgcopyright">
194 <heading>Package copyright and sections</heading>
196 The aims of this policy are:
198 <list compact="compact">
200 <p>We want to make as much software available as we
204 <p>We want to encourage everyone to write free software.</p>
207 <p> We want to make it easy for people to produce
208 CD-ROMs of our system without violating any licenses,
209 import/export restrictions, or any other laws.</p>
214 <heading>The Debian Free Software Guidelines</heading>
216 The Debian Free Software Guidelines (DFSG) is our
217 definition of `free' software.
219 <tag>Free Redistribution
223 The license of a Debian component may not restrict any
224 party from selling or giving away the software as a
225 component of an aggregate software distribution
226 containing programs from several different
227 sources. The license may not require a royalty or
228 other fee for such sale.
235 The program must include source code, and must allow
236 distribution in source code as well as compiled form.
243 The license must allow modifications and derived
244 works, and must allow them to be distributed under the
245 same terms as the license of the original software.
248 <tag>Integrity of The Author's Source Code
252 The license may restrict source-code from being
253 distributed in modified form <em>only</em> if the
254 license allows the distribution of ``patch files''
255 with the source code for the purpose of modifying the
256 program at build time. The license must explicitly
257 permit distribution of software built from modified
258 source code. The license may require derived works to
259 carry a different name or version number from the
260 original software. (This is a compromise. The Debian
261 group encourages all authors to not restrict any
262 files, source or binary, from being modified.)
265 <tag>No Discrimination Against Persons or Groups
269 The license must not discriminate against any person
273 <tag>No Discrimination Against Fields of Endeavor
277 The license must not restrict anyone from making use
278 of the program in a specific field of endeavor. For
279 example, it may not restrict the program from being
280 used in a business, or from being used for genetic
284 <tag>Distribution of License
288 The rights attached to the program must apply to all
289 to whom the program is redistributed without the need
290 for execution of an additional license by those
294 <tag>License Must Not Be Specific to Debian
298 The rights attached to the program must not depend on
299 the program's being part of a Debian system. If the
300 program is extracted from Debian and used or
301 distributed without Debian but otherwise within the
302 terms of the program's license, all parties to whom
303 the program is redistributed must have the same
304 rights as those that are granted in conjunction with
308 <tag>License Must Not Contaminate Other Software
312 The license must not place restrictions on other
313 software that is distributed along with the licensed
314 software. For example, the license must not insist
315 that all other programs distributed on the same medium
316 must be free software.
319 <tag>Example Licenses
323 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
324 examples of licenses that we consider <em>free</em>.
331 <heading>The main section</heading>
333 Every package in "main" must comply with the DFSG (Debian
334 Free Software Guidelines).</p>
337 In addition, the packages in "main"
338 <list compact="compact">
341 must not require a package outside of "main" for
342 compilation or execution (thus, the package may not
343 declare a "Depends" or "Recommends" relationship on a
349 must not be so buggy that we refuse to support them,
354 must meet all policy requirements presented in this
362 <heading>The contrib section</heading>
364 Every package in "contrib" must comply with the DFSG.
368 Examples of packages which would be included in "contrib" are
369 <list compact="compact">
372 free packages which require "contrib", "non-free", or
373 "non-US" packages or packages which are not in our
374 archive at all for compilation or execution,
379 wrapper packages or other sorts of free accessories for
387 <heading>The non-free section</heading>
389 `Non-free' contains packages which are not compliant with
390 the DFSG or which are encumbered by patents or other legal
391 issues that make their distribution problematic.</p>
393 All packages in `non-free' must be electronically
394 distributable across international borders.
398 <heading>The non-us server</heading>
400 Some programs with cryptographic program code must be stored
401 on the "non-us" server because of export restrictions of the
404 This applies only to packages which contain cryptographic
405 code. A package containing a program with an interface to a
406 cryptographic program or a program that's dynamically linked
407 against a cryptographic library can be distributed if it is
408 capable of running without the cryptography library or
413 <heading>Further copyright considerations</heading>
415 Every package must be accompanied by a verbatim copy of its
416 copyright and distribution license in the file
417 /usr/share/doc/<package-name>/copyright (see <ref
418 id="copyrightfile"> for details).</p>
420 We reserve the right to restrict files from being included
421 anywhere in our archives if
422 <list compact="compact">
425 their use or distribution would break a law,
430 there is an ethical conflict in their distribution or
436 we would have to sign a license for them, or
441 their distribution would conflict with other project
449 Programs whose authors encourage the user to make donations
450 are fine for the main distribution, provided that the
451 authors do not claim that not donating is immoral,
452 unethical, illegal or something similar; otherwise they must
453 go in contrib (or non-free, if even distribution is
454 restricted by such statements).</p>
457 Packages whose copyright permission notices (or patent
458 problems) do not allow redistribution even of only binaries,
459 and where no special permission has been obtained, cannot be
460 placed on the Debian FTP site and its mirrors at all.</p>
463 Note, that under international copyright law (this applies
464 in the United States, too) <em>no</em> distribution or
465 modification of a work is allowed without an explicit notice
466 saying so. Therefore a program without a copyright notice
467 <em>is</em> copyrighted and you may not do anything to it
468 without risking being sued! Likewise if a program has a
469 copyright notice but no statement saying what is permitted
470 then nothing is permitted.</p>
473 Many authors are unaware of the problems that restrictive
474 copyrights (or lack of copyright notices) can cause for the
475 users of their supposedly-free software. It is often
476 worthwhile contacting such authors diplomatically to ask
477 them to modify their license terms. However, this is a
478 politically difficult thing to do and you should ask for
479 advice on <tt>debian-devel</tt> first.</p>
482 When in doubt, send mail to
483 <email>debian-devel@lists.debian.org</email>. Be prepared
484 to provide us with the copyright statement. Software
485 covered by the GPL, public domain software and BSD-like
486 copyrights are safe; be wary of the phrases `commercial use
487 prohibited' and `distribution restricted'.</p>
490 <heading>Subsections</heading>
493 The packages in all the sections (<em>main</em>,
494 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
495 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
496 grouped further into <em>subsections</em> to simplify
500 The section for each package is specified in the package's
501 <em>control record</em>. However, the maintainer of the
502 Debian archive may override this selection to assure the
503 consistency of the Debian distribution. </p>
506 Please check the current Debian distribution to see which
507 sections are available.</p>
510 <heading>Priorities</heading>
513 Each package is given a certain <em>priority</em> value,
514 which is included in the package's <em>control
515 record</em>. This information is used in the Debian package
516 management tool to separate high-priority packages from
517 less-important packages.</p>
520 The following <em>priority levels</em> are supported by the
521 Debian package management system, <prgn>dpkg</prgn>.
523 <tag><tt>required</tt></tag>
526 <tt>required</tt> packages are necessary for the
527 proper functioning of the system. You must not remove
528 these packages or your system may become totally
529 broken and you may not even be able to use
530 <prgn>dpkg</prgn> to put things back. Systems with
531 only the <tt>required</tt> packages are probably
532 unusable, but they do have enough functionality to
533 allow the sysadmin to boot and install more
536 <tag><tt>important</tt></tag>
539 Important programs, including those which one would
540 expect to find on any Unix-like system. If the
541 expectation is that an experienced Unix person who
542 found it missing would say `What the F*!@<+ is
543 going on, where is <prgn>foo</prgn>', it must be in
544 <tt>important</tt>. This is an important criterion
545 because we are trying to produce, amongst other
546 things, a free Unix. Other packages without which the
547 system will not run well or be usable must also be
548 here. This does <em>not</em> include Emacs, the X
549 Window System, TeX or any other large applications.
550 The <tt>important</tt> packages are just a bare
551 minimum of commonly-expected and necessary tools.</p>
553 <tag><tt>standard</tt></tag>
556 These packages provide a reasonably small but not too
557 limited character-mode system. This is what will
558 install by default if the user doesn't select anything
559 else. It doesn't include many large applications, but
560 it does include Emacs (this is more of a piece of
561 infrastructure than an application) and a reasonable
562 subset of TeX and LaTeX (if this is possible without
565 <tag><tt>optional</tt></tag>
568 (In a sense everything is optional that isn't
569 required, but that's not what is meant here.) This is
570 all the software that you might reasonably want to
571 install if you didn't know what it was or don't have
572 specialized requirements. This is a much larger system
573 and includes the X Window System, a full TeX
574 distribution, and many applications.</p>
576 <tag><tt>extra</tt></tag>
579 This contains all packages that conflict with others
580 with required, important, standard or optional
581 priorities, or are only likely to be useful if you
582 already know what they are or have specialised
589 Packages may not depend on packages with lower priority
590 values (excluding build-time dependencies). If this does
591 happen, one of the priority values will have to be adapted.
596 <heading>Binary packages</heading>
599 The Debian GNU/Linux distribution is based on the Debian
600 package management system, called <prgn>dpkg</prgn>. Thus,
601 all packages in the Debian distribution have to be provided
602 in the <tt>.deb</tt> file format.</p>
606 <heading>The package name</heading>
609 Every package must have a name that's unique within the Debian
613 Package names may only consist of lower case letters, digits (0-9),
614 plus (+) or minus (-) signs, and periods (.).</p>
617 The package name is part of the file name of the
618 <tt>.deb</tt> file and is included in the control field
624 <heading>The maintainer of a package</heading>
627 Every package must have exactly one maintainer at a
628 time. This person is responsible that the license of the
629 package's software complies with the policy of the
630 distribution this package is included in.</p>
633 The maintainer must be specified in the
634 <tt>Maintainer</tt> control field with the correct name
635 and a working email address for the Debian maintainer of
636 the package. If one person maintains several packages
637 he/she should try to avoid having different forms of their
638 name and email address in different <tt>Maintainer</tt>
642 If the maintainer of a package quits from the Debian
643 project the Debian QA Group
644 <email>debian-qa@lists.debian.org</email> takes over the
645 maintainership of the package until someone else
646 volunteers for that task. These packages are called
647 <em>orphaned packages</em>.
653 <heading>The description of a package</heading>
656 Every Debian package must have an extended description
657 stored in the appropriate field of the control record.</p>
660 The description must be written so that it tells the user
661 what they need to know to decide whether to install the
662 package. This description should not just be copied from
663 the blurb for the program. Instructions for configuring
664 or using the package must not be included -- that is what
665 installation scripts, manual pages, Info files, etc. are
666 for. Copyright statements and other administrivia must
667 not be included -- that is what the copyright file is
673 <heading>Dependencies</heading>
676 Every package has to specify the dependency information
677 about other packages, that are required for the first to
681 For example, for any shared libraries required by
682 dynamically-linked executable binary in a package a
683 dependency entry has to be provided.</p>
686 It is not necessary for other packages to declare any
687 dependencies they have on other packages which are marked
688 <tt>Essential</tt> (see below).</p>
691 Sometimes, a package requires another package to be
692 installed <em>and</em> configured before it can be
693 installed. In this case, you'll have to specify a
694 <tt>Pre-Depends</tt> entry for the package.</p>
697 You must not specify a <tt>Pre-Depends</tt> entry for a
698 package before this has been discussed on the
699 <tt>debian-devel</tt> mailing list and a consensus about
700 doing that has been reached.</p></sect1>
704 <heading>Virtual packages</heading>
707 Sometimes, there are several packages doing more-or-less
708 the same job. In this case, it's useful to define a
709 <em>virtual package</em> whose name describes the function
710 the packages have. (The virtual packages just exist
711 logically, not physically--that's why they are called
712 <em>virtual</em>.) The packages with this particular
713 function will then <em>provide</em> the virtual
714 package. Thus, any other package requiring that function
715 can simply depend on the virtual package without having to
716 specify all possible packages individually.</p>
719 All packages must use virtual package names where
720 appropriate, and arrange to create new ones if necessary.
721 They must not use virtual package names (except privately,
722 amongst a cooperating group of packages) unless they have
723 been agreed upon and appear in the list of virtual package
727 The latest version of the authoritative list of virtual
728 package names can be found on
729 <ftpsite>ftp.debian.org</ftpsite> in
730 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
731 or your local mirror. In addition, it is included in the
732 <tt>debian-policy</tt> package. The procedure for updating
733 the list is described at the top of the file.</p></sect1>
737 <heading>Base packages</heading>
740 The packages included in the <tt>base</tt> section have a
741 special function. They form a minimum subset of the Debian
742 GNU/Linux system that is installed before everything else
743 on a new system. Thus, only very few packages are allowed
744 to go into the <tt>base</tt> section to keep the required
745 disk usage very small.</p>
748 Most of these packages should have the priority value
749 <tt>required</tt> or at least <tt>important</tt>, and many
750 of them will be tagged <tt>essential</tt> (see below).</p>
753 You must not place any packages into the <tt>base</tt>
754 section before this has been discussed on the
755 <tt>debian-devel</tt> mailing list and a consensus about
756 doing that has been reached.</p></sect1>
760 <heading>Essential packages</heading>
763 Some packages are tagged <tt>essential</tt>. (They have
764 <tt>Essential: yes</tt> in their package control record.)
765 This flag is used for packages that are <em>essential</em>
769 Since these packages can not easily be removed (you'll
770 have to specify an extra <em>force option</em> to
771 <prgn>dpkg</prgn>) this flag must only be used where
772 absolutely necessary.
774 A shared library package must not be tagged
775 <em>essential</em>--the dependencies will prevent its
776 premature removal, and we need to be able to remove it
777 when it has been superseded.</p>
780 You must not tag any packages <tt>essential</tt> before
781 this has been discussed on the <tt>debian-devel</tt>
782 mailing and a consensus about doing that has been
787 <heading>Maintainer scripts</heading>
790 The package installation scripts must avoid producing
791 output which it is unnecessary for the user to see and
792 should rely on <prgn>dpkg</prgn> to stave off boredom on
793 the part of a user installing many packages. This means,
794 amongst other things, using the <tt>--quiet</tt> option on
795 <prgn>install-info</prgn>.</p>
798 Packages should try to minimize the amount of prompting
799 they need to do, and they should ensure that the user will
800 only ever be asked each question once. This means that
801 packages should try to use appropriate shared
802 configuration files (such as <tt>/etc/papersize</tt> and
803 <tt>/etc/news/server</tt>), rather than each prompting for
804 their own list of required pieces of information.</p>
807 It also means that an upgrade should not ask the same
808 questions again, unless the user has used <tt>dpkg
809 --purge</tt> to remove the package's configuration. The
810 answers to configuration questions should be stored in an
811 appropriate place in <tt>/etc</tt> so that the user can
812 modify them, and how this has been done should be
816 If a package has a vitally important piece of information
817 to pass to the user (such as "don't run me as I am, you
818 must edit the following configuration files first or you
819 risk your system emitting badly-formatted messages"), it
820 should display this in the <prgn>postinst</prgn> script
821 and prompt the user to hit return to acknowledge the
822 message. Copyright messages do not count as vitally
823 important (they belong in
824 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
825 do instructions on how to use a program (these should be
826 in on line documentation, where all the users can see
830 Any necessary prompting should almost always be confined
831 to the post-installation script, and should be protected
832 with a conditional so that unnecessary prompting doesn't
833 happen if a package's installation fails and the
834 <prgn>postinst</prgn> is called with
835 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
836 <tt>abort-deconfigure</tt>.</p>
839 Errors which occur during the execution of an installation
840 script <em>must</em> be checked and the installation
841 <em>must not</em> continue after an error.</p>
844 Note, that <ref id="scripts">, in general applies to
845 package maintainer scripts, too.</p>
848 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
849 another package without consulting the maintainer of that
853 In order for <prgn>update-alternatives</prgn> to work
854 correctly all the packages which supply an instance of the
855 `shared' command name (or, in general, filename) must use
856 it. You can use <tt>Conflicts</tt> to force the
857 De-installation of other packages supplying it which do not
858 (yet) use <prgn>update-alternatives</prgn>. It may in
859 this case be appropriate to specify a conflict on earlier
860 versions of something--this is an exception to the usual
861 rule that this is not allowed.</p>
865 <heading>Source packages</heading>
868 <heading>Standards conformance</heading>
871 You should specify the most recent version of the
872 packaging standards with which your package complies in
873 the source package's <tt>Standards-Version</tt> field.</p>
876 This value will be used to file bug reports automatically
877 if your package becomes too much out of date.</p>
880 The value corresponds to a version of the Debian manuals,
881 as can be found on the title page or page headers and
882 footers (depending on the format).</p>
885 The version number has four components--major and minor
886 number and major and minor patch level. When the
887 standards change in a way that requires every package to
888 change the major number will be changed. Significant
889 changes that will require work in many packages will be
890 signaled by a change to the minor number. The major patch
891 level will be changed for any change to the meaning of the
892 standards, however small; the minor patch level will be
893 changed when only cosmetic, typographical or other edits
894 which do not change the meaning are made, or changes which
895 do not affect the contents of packages.</p>
898 For package maintainers, only the first 3 digits of the
899 manual version are significant in representing the
900 <em>Standards-Version</em>, and either these 3 digits or
901 the complete 4 digits can be specified--that's up to the
905 In the past, people specified 4 digits in the
906 Standards-Version field, like `2.3.0.0'. Since any
907 `patch-level changes' don't introduce new policy, it
908 was thought it would be better to relax policy and
909 only require that the first 3 digits are specified. (4
910 digits can still be used if someone wants to do so.)
916 You should regularly, and especially if your package has
917 become out of date, check for the newest Policy Manual
918 available and update your package, if necessary. When your
919 package complies with the new standards you may update the
920 <tt>Standards-Version</tt> source package field and
921 release it.</p></sect1>
925 <heading>Package relationships</heading>
928 Source packages must specify which binary packages they
929 require to be installed or not to be installed in order to
930 build correctly. For example, if building a package
931 requires a certain compiler, then the compiler must be
932 specified as a build-time dependency.
936 It will not be necessary to explicitly specify build-time
937 relationships on a minimal set of packages that are always
938 needed to compile, link and put in a Debian package a
939 standard "Hello World!" program written in C or C++. The
940 required packages are called <em>build-essential</em>, and
941 an informational list can be found in
942 <tt>/usr/share/doc/build-essential/list</tt> (which is
943 contained in the <tt>build-essential</tt> package).
948 When specifying the set of build-time dependencies, one
949 should list only those packages explicitly required by the
950 build. It is not necessary to list packages which are
951 required merely because some other package in the list of
952 build-time dependencies depends on them. The reason is
953 that dependencies change, and you should list only those
954 <em>you</em> need. What others need is their business.
958 It is a bug if, after unpacking a source package on a
959 system with the build-essential packages installed and
960 satisfying the build-time relationships (including the
961 implied relationships), one cannot build the package and
962 produce a working binary package suitable for installation
963 into the binary distribution corresponding to the source
964 distribution which contained the source package. This
965 means in particular that version clauses should be used
966 rigorously in build-time relationships so that one cannot
967 produce bad or inconsistently configured packages when the
968 relationships are properly satisfied.
972 <heading>Changes to the upstream sources</heading>
975 If changes to the source code are made that are generally
976 applicable please try to get them included in the upstream
977 version of the package by supplying the upstream authors
978 with the changes in whatever form they prefer.</p>
981 If you need to configure the package differently for
982 Debian or for Linux, and the upstream source doesn't
983 provide a way to configure it the way you need to, please
984 add such configuration facilities (for example, a new
985 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
986 the patch to the upstream authors, with the default set to
987 the way they originally had it. You can then easily
988 override the default in your <tt>debian/rules</tt> or
989 wherever is appropriate.</p>
992 Please make sure that the <prgn>configure</prgn> utility
993 detects the correct architecture specification string
994 (refer to <ref id="arch-spec"> for details).</p>
997 If you need to edit a <prgn>Makefile</prgn> where
998 GNU-style <prgn>configure</prgn> scripts are used, you
999 should edit the <tt>.in</tt> files rather than editing the
1000 <prgn>Makefile</prgn> directly. This allows the user to
1001 reconfigure the package if necessary. You should
1002 <em>not</em> configure the package and edit the generated
1003 <prgn>Makefile</prgn>! This makes it impossible for
1004 someone else to later reconfigure the package.</p></sect1>
1008 <heading>Documenting your changes</heading>
1011 Document your changes and updates to the source package
1012 properly in the <tt>debian/changelog</tt> file.</p>
1015 A copy of the file which will be installed in
1016 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
1017 in <tt>debian/copyright</tt>.</p>
1020 In non-experimental packages you may only use a format for
1021 <tt>debian/changelog</tt> which is supported by the most
1022 recent released version of <prgn>dpkg</prgn>. If your
1023 format is not supported and there is general support for
1024 it you should contact the <prgn>dpkg</prgn> maintainer to
1025 have the parser script for your format included in the
1026 <prgn>dpkg</prgn> package. (You will need to agree that
1027 the parser and its manpage may be distributed under the
1028 GNU GPL, just as the rest of <prgn>dpkg</prgn>
1033 <heading>Error trapping in makefiles</heading>
1036 When <prgn>make</prgn> invokes a command in a makefile
1037 (including your package's upstream makefiles and the
1038 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1039 means that <tt>sh</tt>'s usual bad error handling
1040 properties apply: if you include a miniature script as one
1041 of the commands in your makefile you'll find that if you
1042 don't do anything about it then errors are not detected
1043 and <prgn>make</prgn> will blithely continue after
1047 Every time you put more than one shell command (this
1048 includes using a loop) in a makefile command you
1049 <em>must</em> make sure that errors are trapped. For
1050 simple compound commands, such as changing directory and
1051 then running a program, using <tt>&&</tt> rather
1052 than semicolon as a command separator is sufficient. For
1053 more complex commands including most loops and
1054 conditionals you must include a separate <tt>set -e</tt>
1055 command at the start of every makefile command that's
1056 actually one of these miniature shell scripts.</p></sect1>
1060 <heading>Obsolete constructs and libraries</heading>
1063 The include file <prgn><varargs.h></prgn> is
1064 provided to support end-users compiling very old software;
1065 the library <tt>libtermcap</tt> is provided to support the
1066 execution of software which has been linked against it
1067 (either old programs or those such as Netscape which are
1068 only available in binary form).</p>
1071 Debian packages should be ported to include
1072 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1077 <chapt><heading>The Operating System</heading>
1081 <heading>File system hierarchy</heading>
1085 <heading>Linux File system Structure</heading>
1088 The location of all installed files and directories must
1089 comply with the Linux File system Hierarchy Standard
1090 (FHS). The latest version of this document can be found
1091 alongside this manual or on
1092 <url id="http://www.pathname.com/fhs/">.<footnote>
1093 <p>The Debian distribution currently distributes a draft
1094 version of FHS 2.1 because several significant details
1095 have changed between the currently released 2.0
1096 version and the to-be-released 2.1 version.</p>
1098 Specific questions about following the standard may be
1099 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1100 Quinlan, the FHS coordinator, at
1101 <email>quinlan@pathname.com</email>.</p></sect1>
1105 <heading>Site-specific programs</heading>
1108 As mandated by the FHS no package should place any
1109 files in <tt>/usr/local</tt>, either by putting them in
1110 the file system archive to be unpacked by <prgn>dpkg</prgn>
1111 or by manipulating them in their maintainer scripts.</p>
1114 However, the package should create empty directories below
1115 <tt>/usr/local</tt> so that the system administrator knows
1116 where to place site-specific files. These directories
1117 should be removed on package removal if they are
1121 Note, that this applies only to directories <em>below</em>
1122 <tt>/usr/local</tt>, not <em>in</em>
1123 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1124 itself may only contain the sub-directories listed in
1125 FHS, section 4.6. However, you may create directories
1126 below them as you wish. You may not remove any of the
1127 directories listed in 4.6, even if you created them.</p>
1130 Since <tt>/usr/local</tt> may be mounted read-only from a
1131 remote server, these directories have to be created and
1132 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1133 maintainer scripts. These scripts must not fail if either
1134 of these operations fail. (In the future, it will be
1135 possible to tell <prgn>dpkg</prgn> not to unpack files
1136 matching certain patterns, so that the directories can be
1137 included in the <tt>.deb</tt> packages and system
1138 administrators who do not wish these directories in
1139 /usr/local do not need to have them.)</p>
1142 For example, the <prgn>emacs</prgn> package will contain
1144 mkdir -p /usr/local/lib/emacs/site-lisp || true
1146 in the <tt>postinst</tt> script, and
1148 rmdir /usr/local/lib/emacs/site-lisp && \
1149 rmdir /usr/local/lib/emacs || \
1152 in the <tt>prerm</tt> script.</p>
1155 If you do create a directory in <tt>/usr/local</tt> for
1156 local additions to a package, you must ensure that
1157 settings in <tt>/usr/local</tt> take precedence over the
1158 equivalents in <tt>/usr</tt>.</p>
1161 However, because '/usr/local' and its contents are for
1162 exclusive use of the local administrator, a package must
1163 not rely on the presence or absence of files or
1164 directories in '/usr/local' for normal operation.</p>
1167 The <tt>/usr/local</tt> directory itself and all the
1168 subdirectories created by the package should have
1169 permissions 2775 (group-writable and set-group-id) and be
1170 owned by <tt>root.staff</tt>.</p>
1175 <heading>Users and groups</heading>
1178 The Debian system can be configured to use either plain or
1179 shadow passwords.</p>
1182 Some user ids (UIDs) and group ids (GIDs) are reserved
1183 globally for use by certain packages. Because some packages
1184 need to include files which are owned by these users or
1185 groups, or need the ids compiled into binaries, these ids
1186 must be used on any Debian system only for the purpose for
1187 which they are allocated. This is a serious restriction, and
1188 we should avoid getting in the way of local administration
1189 policies. In particular, many sites allocate users and/or
1190 local system groups starting at 100.</p>
1193 Apart from this we should have dynamically allocated ids,
1194 which should by default be arranged in some sensible
1195 order--but the behavior should be configurable.</p>
1198 No package except <tt>base-passwd</tt> may modify
1199 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1200 <tt>/etc/group</tt>.</p>
1203 The UID and GID ranges are as follows:
1208 Globally allocated by the Debian project, must be the
1209 same on every Debian system. These ids will appear in
1210 the <tt>passwd</tt> and <tt>group</tt> files of all
1211 Debian systems, new ids in this range being added
1212 automatically as the <tt>base-passwd</tt> package is
1216 Packages which need a single statically allocated uid
1217 or gid should use one of these; their maintainers
1218 should ask the <tt>base-passwd</tt> maintainer for
1225 Dynamically allocated system users and groups.
1226 Packages which need a user or group, but can have this
1227 user or group allocated dynamically and differently on
1228 each system, should use `<tt>adduser --system</tt>' to
1229 create the group and/or user. <prgn>adduser</prgn>
1230 will check for the existence of the user or group, and
1231 if necessary choose an unused id based on the ranged
1232 specified in <tt>adduser.conf</tt>.</p></item>
1235 <tag>1000-29999:</tag>
1238 Dynamically allocated user accounts. By default
1239 <prgn>adduser</prgn> will choose UIDs and GIDs for
1240 user accounts in this range, though
1241 <tt>adduser.conf</tt> may be used to modify this
1245 <tag>30000-59999:</tag>
1247 <p>Reserved.</p></item>
1250 <tag>60000-64999:</tag>
1253 Globally allocated by the Debian project, but only
1254 created on demand. The ids are allocated centrally and
1255 statically, but the actual accounts are only created
1256 on users' systems on demand.</p>
1259 These ids are for packages which are obscure or which
1260 require many statically-allocated ids. These packages
1261 should check for and create the accounts in
1262 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1263 <prgn>adduser</prgn> if it has this facility) if
1264 necessary. Packages which are likely to require
1265 further allocations should have a `hole' left after
1266 them in the allocation, to give them room to
1270 <tag>65000-65533:</tag>
1272 <p>Reserved.</p></item>
1277 <p>User `<tt>nobody</tt>.'</p></item>
1283 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1284 because it is the error return sentinel value.</p>
1289 <sect id="sysvinit">
1290 <heading>System run levels</heading>
1293 <sect1 id="/etc/init.d">
1294 <heading>Introduction</heading>
1297 The <tt>/etc/init.d</tt> directory contains the scripts
1298 executed by <prgn>init</prgn> at boot time and when init
1299 state (or `runlevel') is changed (see <manref name="init"
1303 There are at least two different, yet functionally
1304 equivalent, ways of handling these scripts. For the sake
1305 of simplicity, this document describes only the symbolic
1306 link method. However, it may not be assumed that this
1307 method is being used, and any manipulation of the various
1308 runlevel behaviours must be performed using
1309 <prgn>update-rc.d</prgn> as described below and not by
1310 manually installing symlinks. For information on the
1311 implementation details of the other method, implemented in
1312 the <tt>file-rc</tt> package, please refer to the
1313 documentation of that package.</p>
1316 These scripts are referenced by symbolic links in
1317 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1318 changing runlevels, <prgn>init</prgn> looks in the
1319 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1320 it should execute, where <var>n</var> is the runlevel that
1321 is being changed to, or `S' for the boot-up scripts.</p>
1324 The names of the links all have the form
1325 <tt>S<var>mm</var><var>script</var></tt> or
1326 <tt>K<var>mm</var><var>script</var></tt> where
1327 <var>mm</var> is a two-digit number and <var>script</var>
1328 is the name of the script (this should be the same as the
1329 name of the actual script in <tt>/etc/init.d</tt>.</p>
1332 When <prgn>init</prgn> changes runlevel first the targets
1333 of the links whose names starting with a <tt>K</tt> are
1334 executed, each with the single argument <tt>stop</tt>,
1335 followed by the scripts prefixed with an <tt>S</tt>, each
1336 with the single argument <tt>start</tt>. The <tt>K</tt>
1337 links are responsible for killing services and the
1338 <tt>S</tt> link for starting services upon entering the
1342 For example, if we are changing from runlevel 2 to
1343 runlevel 3, init will first execute all of the <tt>K</tt>
1344 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1345 all of the <tt>S</tt> prefixed scripts. The links
1346 starting with <tt>K</tt> will cause the referred-to file
1347 to be executed with an argument of <tt>stop</tt>, and the
1348 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1351 The two-digit number <var>mm</var> is used to decide which
1352 order to start and stop things in--low-numbered links have
1353 their scripts run first. For example, the <tt>K20</tt>
1354 scripts will be executed before the <tt>K30</tt> scripts.
1355 This is used when a certain service must be started before
1356 another. For example, the name server <prgn>bind</prgn>
1357 might need to be started before the news server
1358 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1359 access lists. In this case, the script that starts
1360 <prgn>bind</prgn> should have a lower number than the
1361 script that starts <prgn>inn</prgn> so that it runs first:
1370 <heading>Writing the scripts</heading>
1373 Packages can and should place scripts in
1374 <tt>/etc/init.d</tt> to start or stop services at boot
1375 time or during a change of runlevel. These scripts should
1376 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1377 should accept one argument, saying what to do:
1380 <tag><tt>start</tt></tag>
1381 <item><p>start the service,</p></item>
1383 <tag><tt>stop</tt></tag>
1384 <item><p>stop the service,</p></item>
1386 <tag><tt>restart</tt></tag>
1387 <item><p>stop and restart the service,</p></item>
1389 <tag><tt>reload</tt></tag>
1390 <item><p>cause the configuration of the service to be
1391 reloaded without actually stopping and restarting
1392 the service,</p></item>
1394 <tag><tt>force-reload</tt></tag> <item><p>cause the
1395 configuration to be reloaded if the service supports
1396 this, otherwise restart the service.</p></item>
1399 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1400 <tt>force-reload</tt> options must be supported by all
1401 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1402 option is optional.</p>
1405 The <tt>init.d</tt> scripts should ensure that they will
1406 behave sensibly if invoked with <tt>start</tt> when the
1407 service is already running, or with <tt>stop</tt> when it
1408 isn't, and that they don't kill unfortunately-named user
1409 processes. The best way to achieve this is usually to use
1410 <prgn>start-stop-daemon</prgn>.</p>
1413 If a service reloads its configuration automatically (as
1414 in the case of <prgn>cron</prgn>, for example), the
1415 <tt>reload</tt> option of the <tt>init.d</tt> script
1416 should behave as if the configuration has been reloaded
1420 These scripts should not fail obscurely when the
1421 configuration files remain but the package has been
1422 removed, as configuration files remain on the system after
1423 the package has been removed. Only when <prgn>dpkg</prgn>
1424 is executed with the <tt>--purge</tt> option will
1425 configuration files be removed. In particular, the init
1426 script itself is usually a configuration file (see
1427 <ref id="init.d notes">), and will remain on the system if
1428 the package is removed but not purged. Therefore, you
1429 should include a <tt>test</tt> statement at the top of the
1432 test -f <var>program-executed-later-in-script</var> || exit 0
1437 <heading>Managing the links</heading>
1440 A program is provided, <prgn>update-rc.d</prgn>, to handle
1441 the it easier for package maintainers to arrange for the
1442 proper creation and removal of
1443 <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
1444 functional equivalent if another method is being used.
1445 This may be used by maintainers in their packages'
1446 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1449 You should use this script to make changes to
1450 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
1451 include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
1452 in the actual archive or manually create or remove the
1453 symbolic links in maintainer scripts. (The latter will
1454 fail if an alternative method of maintaining runlevel
1455 information is being used.)</p>
1458 By default <prgn>update-rc.d</prgn> will start services in
1459 each of the multi-user state runlevels (2, 3, 4, and 5)
1460 and stop them in the halt runlevel (0), the single-user
1461 runlevel (1) and the reboot runlevel (6). The system
1462 administrator will have the opportunity to customize
1463 runlevels by either running <prgn>update-rc.d</prgn>, by
1464 simply adding, moving, or removing the symbolic links in
1465 <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
1466 used, or by modifying <tt>/etc/runlevel.conf</tt> if the
1467 <tt>file-rc</tt> method is being used.</p>
1470 To get the default behavior for your package, put in your
1471 <tt>postinst</tt> script
1473 update-rc.d <var>package</var> defaults >/dev/null
1475 and in your <tt>postrm</tt>
1477 if [ purge = "$1" ]; then
1478 update-rc.d <var>package</var> remove >/dev/null
1483 This will use a default sequence number of 20. If it does
1484 not matter when or in which order the script is run, use
1485 this default. If it does, then you should talk to the
1486 maintainer of the <prgn>sysvinit</prgn> package or post to
1487 <tt>debian-devel</tt>, and they will help you choose a
1491 For more information about using <tt>update-rc.d</tt>,
1492 please consult its manpage <manref name="update-rc.d"
1493 section="8">.</p></sect1>
1497 <heading>Boot-time initialization</heading>
1500 There used to be another directory, <tt>/etc/rc.boot</tt>,
1501 which contained scripts which were run once per machine
1502 boot. This has been deprecated in favour of links from
1503 <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
1504 described in <ref id="/etc/init.d">. No packages may
1505 place files in <tt>/etc/rc.boot</tt>.</p>
1507 <sect1 id="init.d notes">
1508 <heading>Notes</heading>
1511 <em>Do not</em> include the
1512 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1513 <tt>.deb</tt> file system archive! <em>This will cause
1514 problems!</em> You should create them with
1515 <prgn>update-rc.d</prgn>, as above.</p>
1518 <em>Do not</em> include the
1519 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1520 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1521 problems!</em> <em>Do</em>, however, treat the
1522 <tt>/etc/init.d</tt> scripts as configuration files,
1523 either by marking them as conffiles or managing them
1524 correctly in the maintainer scripts (see
1525 <ref id="config files">). (This is important since we want
1526 to give the local system administrator the chance to adapt
1527 the scripts to the local system--e.g., to disable a
1528 service without de-installing the package, or to specify
1529 some special command line options when starting a
1530 service--while making sure her changes aren't lost during
1531 the next package upgrade.)</p>
1535 <heading>Example</heading>
1538 The <prgn>bind</prgn> DNS (nameserver) package wants to
1539 make sure that the nameserver is running in multiuser
1540 runlevels, and is properly shut down with the system. It
1541 puts a script in <tt>/etc/init.d</tt>, naming the script
1542 appropriately <tt>bind</tt>. As you can see, the script
1543 interprets the argument <tt>reload</tt> to send the
1544 nameserver a <tt>HUP</tt> signal (causing it to reload its
1545 configuration); this way the user can say
1546 <tt>/etc/init.d/bind reload</tt> to reload the name
1553 # Original version by Robert Leslie
1554 # <rob@mars.org>, edited by iwj and cs
1556 test -x /usr/sbin/named || exit 0
1560 echo -n "Starting domain name service: named"
1561 start-stop-daemon --start --quiet --exec /usr/sbin/named
1565 echo -n "Stopping domain name service: named"
1566 start-stop-daemon --stop --quiet \
1567 --pidfile /var/run/named.pid --exec /usr/sbin/named
1571 echo -n "Restarting domain name service: named"
1572 start-stop-daemon --stop --quiet \
1573 --pidfile /var/run/named.pid --exec /usr/sbin/named
1574 start-stop-daemon --start --verbose --exec /usr/sbin/named
1577 force-reload|reload)
1578 echo -n "Reloading configuration of domain name service: named"
1579 start-stop-daemon --stop --signal 1 --quiet \
1580 --pidfile /var/run/named.pid --exec /usr/sbin/named
1584 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1593 Another example on which to base your <tt>/etc/init.d</tt>
1594 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1597 If this package is happy with the default setup from
1598 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1599 and having named running in all runlevels, it can say in
1600 its <tt>postinst</tt>:
1602 update-rc.d bind defaults >/dev/null
1604 And in its <tt>postrm</tt>, to remove the links when the
1607 if [ purge = "$1" ]; then
1608 update-rc.d acct remove >/dev/null
1614 <heading>Cron jobs</heading>
1617 Packages may not modify the configuration file
1618 <tt>/etc/crontab</tt>, nor may they modify the files in
1619 <tt>/var/spool/cron/crontabs</tt>.</p>
1622 If a package wants to install a job that has to be executed
1623 via cron, it should place a file with the name if the
1624 package in one of the following directories:
1630 As these directory names imply, the files within them are
1631 executed on a daily, weekly, or monthly basis,
1632 respectively. The exact times are listed in
1633 <tt>/etc/crontab</tt>.</p>
1636 All files installed in any of these directories have to be
1637 scripts (shell scripts, Perl scripts, etc.) so that they can
1638 easily be modified by the local system administrator. In
1639 addition, they must be treated as configuration files.</p>
1642 If a certain job has to be executed more frequently than
1643 daily, the package should install a file
1644 <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
1645 the same syntax as <tt>/etc/crontab</tt> and is processed by
1646 <prgn>cron</prgn> automatically. The file must also be
1647 treated as a configuration file. (Note, that entries in the
1648 <tt>/etc/cron.d</tt> directory are not handled by
1649 <prgn>anacron</prgn>. Thus, you should only use this
1650 directory for jobs which may be skipped if the system is not
1654 The scripts or crontab entries in these directories should
1655 check if all necessary programs are installed before they
1656 try to execute them. Otherwise, problems will arise when a
1657 package was removed but not purged since configuration files
1658 are kept on the system in this situation.</p>
1662 <heading>Console messages</heading>
1665 This section describes different formats for messages
1666 written to standard output by the <tt>/etc/init.d</tt>
1667 scripts. The intent is to improve the consistency of
1668 Debian's startup and shutdown look and feel.</p>
1671 Please look very careful at the details. We want to get the
1672 messages to look exactly the same way concerning spaces,
1673 punctuation, and case of letters.</p>
1676 Here is a list of overall rules that you should use when you
1677 create output messages. They can be useful if you have a
1678 non-standard message that isn't covered in the sections
1685 Every message should cover one line, start with a
1686 capital letter and end with a period `.'.</p></item>
1691 If you want to express that the computer is working on
1692 something (performing a specific task, not starting or
1693 stopping a program), we use an ``ellipsis'', namely
1694 three dots `...'. Note that we don't insert spaces in
1695 front of or behind the dots. If the task has been
1696 completed we write `done.' and a line feed.</p></item>
1701 Design your messages as if the computer is telling you
1702 what he is doing (let him be polite :-) but don't
1703 mention ``him'' directly. For example, if you think
1706 I'm starting network daemons: nfsd mountd.
1710 Starting network daemons: nfsd mountd.
1711 </example></p></item>
1715 The following formats must be used</p>
1720 <p>when daemons get started.</p>
1723 Use this format if your script starts one or more
1724 daemons. The output should look like this (a single
1725 line, no leading spaces):
1727 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1729 The <description> should describe the subsystem
1730 the daemon or set of daemons are part of, while
1731 <daemon-1> up to <daemon-n> denote each
1732 daemon's name (typically the file name of the
1736 For example, the output of /etc/init.d/lpd would look like:
1738 Starting printer spooler: lpd.
1742 This can be achieved by saying
1744 echo -n "Starting printer spooler: lpd"
1745 start-stop-daemon --start --quiet lpd
1748 in the script. If you have more than one daemon to
1749 start, you should do the following:
1751 echo -n "Starting remote file system services:"
1752 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1753 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1754 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1757 This makes it possible for the user to see what takes
1758 so long and when the final daemon has been
1759 started. Please be careful where to put spaces: In the
1760 example above the system administrator can easily
1761 comment out a line if he don't wants to start a
1762 specific daemon, while the displayed message still
1763 looks good.</p></item>
1767 <p>when something needs to be configured.</p>
1770 If you have to set up different parameters of the
1771 system upon boot up, you can use this format:
1773 Setting <parameter> to `<value>'.
1777 You can use the following echo statement to get the quotes right:
1779 echo "Setting DNS domainname to \`"value"'."
1783 Note that the left quotation mark (`) is different
1784 from the right (').</p></item>
1787 <p>when a daemon is stopped.</p>
1790 When you stop a daemon you should issue a message
1791 similar to the startup message, except that `Starting'
1792 is replaced with `Stopping'.</p>
1795 So stopping the printer daemon will like like this:
1797 Stopping printer spooler: lpd.
1798 </example></p></item>
1801 <p>when something is executed.</p>
1804 There a several examples where you have to run a
1805 program at system startup or shutdown to perform a
1806 specific task. For example, setting the system's clock
1807 via `netdate' or killing all processes when the system
1808 comes down. Your message should like this:
1810 Doing something very useful...done.
1812 You should print the `done.' right after the job has been completed,
1813 so that the user gets informed why he has to wait. You can get this
1816 echo -n "Doing something very useful..."
1820 in your script.</p></item>
1823 <p>when the configuration is reloaded.</p>
1826 When a daemon is forced to reload its configuration
1827 files you should use the following format:
1829 Reloading <daemon's-name> configuration...done.
1830 </example></p></item>
1833 <p>when none of the above rules apply.</p>
1836 If you have to print a message that doesn't fit into
1837 the styles described above, you can use something
1838 appropriate, but please have a look at the overall
1839 rules listed above.</p></item>
1844 <heading>Menus</heading>
1847 Menu entries should follow the current menu policy as
1848 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1849 <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
1850 or your local mirror. In addition, it is included in the
1851 <tt>debian-policy</tt> package.
1855 The Debian <tt>menu</tt> packages provides a unique
1856 interface between packages providing applications and
1857 documents, and <em>menu programs</em> (either X window
1858 managers or text-based menu programs as
1859 <prgn>pdmenu</prgn>).</p>
1862 All packages that provide applications that need not be
1863 passed any special command line arguments for normal
1864 operation should register a menu entry for those
1865 applications, so that users of the <tt>menu</tt> package
1866 will automatically get menu entries in their window
1867 managers, as well in shells like <tt>pdmenu</tt>.</p>
1870 Please refer to the <em>Debian Menu System</em> document
1871 that comes with the <tt>menu</tt> package for information
1872 about how to register your applications and web
1878 <heading>Multimedia handlers</heading>
1881 Packages which provide the ability to view/show/play,
1882 compose, edit or print MIME types should register themselves
1883 as such following the current MIME support policy as defined
1884 in the file found on <ftpsite>ftp.debian.org</ftpsite> in
1885 <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
1886 or your local mirror. In addition, it is included in the
1887 <tt>debian-policy</tt> package.
1891 MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
1892 mechanism for encoding files and data streams and providing
1893 meta-information about them, in particular their type (e.g.
1894 audio or video) and format (e.g. PNG, HTML, MP3).
1898 Registration of MIME type handlers allows programs like mail
1899 user agents and web browsers to to invoke these handlers to
1900 view, edit or display MIME types they don't support
1906 <heading>Keyboard configuration</heading>
1909 To achieve a consistent keyboard configuration (i.e., all
1910 applications interpret a keyboard event the same way) all
1911 programs in the Debian distribution have to be configured to
1912 comply with the following guidelines.</p>
1915 Here is a list that contains certain keys and their interpretation:
1918 <tag><tt><--</tt></tag>
1919 <item><p>delete the character to the left of the cursor</p></item>
1921 <tag><tt>Delete</tt></tag>
1922 <item><p>delete the character to the right of the cursor</p></item>
1924 <tag><tt>Control+H</tt></tag>
1925 <item><p>emacs: the help prefix</p></item>
1928 The interpretation of any keyboard events should be independent
1929 of the terminal that's used, be it a virtual console, an X
1930 terminal emulator, an rlogin/telnet session, etc.</p>
1933 The following list explains how the different programs
1934 should be set up to achieve this:</p>
1937 <list compact="compact">
1938 <item><p>`<tt><--</tt>' generates KB_Backspace in
1941 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1945 X translations are set up to make KB_Backspace
1946 generate ASCII DEL, and to make KB_Delete generate
1947 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1948 the `delete character' key). This must be done by
1949 loading the resources using xrdb on all local X
1950 displays, not using the application defaults, so that
1951 the translation resources used correspond to the
1952 xmodmap settings.</p></item>
1956 The Linux console is configured to make
1957 `<tt><--</tt>' generate DEL, and `Delete' generate
1958 <tt>ESC [ 3 ~</tt> (this is the case at the
1962 X applications are configured so that Backspace
1963 deletes left, and Delete deletes right. Motif
1964 applications already work like this.</p></item>
1966 <item><p>stty erase <tt>^?</tt> .</p></item>
1969 The `xterm' terminfo entry should have <tt>ESC [ 3
1970 ~</tt> for kdch1, just like TERM=linux and
1971 TERM=vt220.</p></item>
1974 Emacs is programmed to map KB_Backspace or the `stty
1975 erase' character to delete-backward-char, and
1976 KB_Delete or kdch1 to delete-forward-char, and
1977 <tt>^H</tt> to help as always.</p></item>
1980 Other applications use the `stty erase' character and
1981 kdch1 for the two delete keys, with ASCII DEL being
1982 `delete previous character' and kdch1 being `delete
1983 character under cursor'.</p></item>
1987 This will solve the problem except for:</p>
1990 <list compact="compact">
1992 Some terminals have a <tt><--</tt> key that cannot
1993 be made to produce anything except <tt>^H</tt>. On
1994 these terminals Emacs help will be unavailable on
1995 <tt>^H</tt> (assuming that the `stty erase' character
1996 takes precedence in Emacs, and has been set
1997 correctly). M-x help or F1 (if available) can be used
2001 Some operating systems use <tt>^H</tt> for stty erase.
2002 However, modern telnet versions and all rlogin
2003 versions propagate stty settings, and almost all UNIX
2004 versions honour stty erase. Where the stty settings
2005 are not propagated correctly things can be made to
2006 work by using stty manually.</p></item>
2009 Some systems (including previous Debian versions) use
2010 xmodmap to arrange for both <tt><--</tt> and Delete
2011 to generate KB_Delete. We can change the behavior
2012 of their X clients via the same X resources that we
2013 use to do it for our own, or have our clients be
2014 configured via their resources when things are the
2015 other way around. On displays configured like this
2016 Delete will not work, but <tt><--</tt>
2020 Some operating systems have different kdch1 settings
2021 in their terminfo for xterm and others. On these
2022 systems the Delete key will not work correctly when
2023 you log in from a system conforming to our policy, but
2024 <tt><--</tt> will.</p></item>
2031 <heading>Environment variables</heading>
2034 No program may depend on environment variables to get
2035 reasonable defaults. (That's because these environment
2036 variables would have to be set in a system-wide
2037 configuration file like /etc/profile, which is not supported
2041 If a program should depend on environment variables for its
2042 configuration, the program has to be changed to fall back to
2043 a reasonable default configuration if these environment
2044 variables are not present. If this cannot be done easily
2045 (e.g., if the source code of a non-free program is not
2046 available), the program should be replaced by a small
2047 `wrapper' shell script which sets the environment variables
2048 and calls the original program.</p>
2051 Here is an example of a wrapper script for this purpose:
2057 exec /usr/lib/foo/foo "$@"
2061 Furthermore, as <tt>/etc/profile</tt> is a configuration
2062 file of the <prgn>bash</prgn> package, no other package may
2063 put any environment variables or other commands into that
2068 <heading>Files</heading>
2072 <heading>Binaries</heading>
2075 It is not allowed that two packages install programs with
2076 different functionality but with the same filenames. (The
2077 case of two programs having the same functionality but
2078 different implementations is handled via `alternatives.')
2079 If this case happens, one of the programs has to be
2080 renamed. The maintainers should report this to the
2081 developers' mailing and try to find a consensus about
2082 which package will have to be renamed. If a consensus can
2083 not be reached, <em>both</em> programs must be
2087 Generally the following compilation parameters should be used:
2090 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
2092 install -s # (or use strip on the files in debian/tmp)
2096 Note that all installed binaries should be stripped,
2097 either by using the <tt>-s</tt> flag to
2098 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2099 the binaries after they have been copied into
2100 <tt>debian/tmp</tt> but before the tree is made into a
2104 The <tt>-g</tt> flag is useful on compilation so that you
2105 have available a full set of debugging symbols in your
2106 built source tree, in case anyone should file a bug report
2107 involving (for example) a core dump.</p>
2110 The <tt>-N</tt> flag should not be used. On a.out systems
2111 it may have been useful for some very small binaries, but
2112 for ELF it has no good effect.</p>
2115 It is up to the package maintainer to decide what
2116 compilation options are best for the package. Certain
2117 binaries (such as computationally-intensive programs) may
2118 function better with certain flags (<tt>-O3</tt>, for
2119 example); feel free to use them. Please use good judgment
2120 here. Don't use flags for the sake of it; only use them
2121 if there is good reason to do so. Feel free to override
2122 the upstream author's ideas about which compilation
2123 options are best--they are often inappropriate for our
2124 environment.</p></sect>
2128 <heading>Libraries</heading>
2131 All libraries must have a shared version in the lib
2132 package and a static version in the lib-dev package. The
2133 shared version must be compiled with <tt>-fPIC</tt>, and
2134 the static version must not be. In other words, each
2135 <tt>*.c</tt> file is compiled twice.</p>
2138 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2139 when building a library (either static or shared) to make
2140 the library compatible with LinuxThreads.</p>
2143 Note that all installed shared libraries should be
2146 strip --strip-unneeded <your-lib>
2148 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2149 only the symbols which aren't needed for relocation
2150 processing.) Shared libraries can function perfectly well
2151 when stripped, since the symbols for dynamic linking are
2152 in a separate part of the ELF object file.</p>
2155 Note that under some circumstances it may be useful to
2156 install a shared library unstripped, for example when
2157 building a separate package to support debugging.
2161 An ever increasing number of packages are using libtool to
2162 do their linking. The latest GNU libtools (>= 1.3a) can take
2163 advantage of the metadata in the installed libtool archive
2164 files (`*.la'). The main advantage of libtool's .la files is
2165 that it allows libtool to store and subsequently access
2166 metadata with respect to the libraries it builds. libtool
2167 will search for those files, which contain a lot of useful
2168 information about a library (e.g. dependency libraries for
2169 static linking). Also, they're <em>essential</em> for
2170 programs using libltdl.
2174 Certainly libtool is fully capable of linking against shared
2175 libraries which don't have .la files, but being a mere shell
2176 script it can add considerably to the build time of a
2177 libtool using package if that shell-script has to derive all
2178 this information from first principles for each library every
2179 time it is linked. With the advent of libtool-1.4 (and to a
2180 lesser extent libtool-1.3), the .la files will also store
2181 information about inter-library dependencies which cannot
2182 necessarily be derived after the .la file is deleted.
2186 Packages that use libtool to create shared libraries must
2187 include the <em>.la</em> files in the <em>-dev</em>
2188 packages, with the exception that if the package relies on
2189 libtool's <em>libltdl</em> library, in which case the .la
2190 files must go in the run-time library package. This is a
2191 good idea in general, and especially for static linking
2196 Please make sure that you use only released versions of
2197 shared libraries to build your packages; otherwise other
2198 users will not be able to run your binaries
2199 properly. Producing source packages that depend on
2200 unreleased compilers is also usually a bad
2207 <heading>Shared libraries</heading>
2210 Packages involving shared libraries should be split up
2211 into several binary packages.</p>
2214 For a straightforward library which has a development
2215 environment and a runtime kit including just shared
2216 libraries you need to create two packages:
2217 <tt><var>libraryname</var><var>soname</var></tt>
2218 (<var>soname</var> is the shared object name of the shared
2219 library--it's the thing that has to match exactly between
2220 building an executable and running it for the dynamic
2221 linker to be able run the program; usually the
2222 <var>soname</var> is the major number of the library) and
2223 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2226 If you prefer only to support one development version at a
2227 time you may name the development package
2228 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2229 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2230 ensure that the user only installs one development version
2231 at a time (after all, different development versions are
2232 likely to have the same header files in them, causing a
2233 filename clash if both are installed). Typically the
2234 development version will also need an exact version
2235 dependency on the runtime library, to make sure that
2236 compilation and linking happens correctly.</p>
2239 Packages which use the shared library should have a
2240 dependency on the name of the shared library package,
2241 <tt><var>libraryname</var><var>soname</var></tt>. When
2242 the <var>soname</var> changes you can have both versions
2243 of the library installed while moving from the old library
2247 If your package has some run-time support programs which
2248 use the shared library you must <em>not</em> put them in
2249 the shared library package. If you do that then you won't
2250 be able to install several versions of the shared library
2251 without getting filename clashes. Instead, either create
2252 a third package for the runtime binaries (this package
2253 might typically be named
2254 <tt><var>libraryname</var>-runtime</tt>--note the absence
2255 of the <var>soname</var> in the package name) or if the
2256 development package is small include them in there.</p>
2259 If you have several shared libraries built from the same
2260 source tree you can lump them all together into a single
2261 shared library package, provided that you change all their
2262 <var>soname</var>s at once (so that you don't get filename
2263 clashes if you try to install different versions of the
2264 combined shared libraries package).</p>
2267 Follow the directions in the <em>Debian Packaging
2268 Manual</em> for putting the shared library in its package,
2269 and make sure you include a <tt>shlibs</tt> control area
2270 file with details of the dependencies for packages which
2271 use the library.</p>
2274 Shared libraries should <em>not</em> be installed
2275 executable, since <prgn>ld.so</prgn> does not require this
2276 and trying to execute a shared library results in a core
2281 <heading>Scripts</heading>
2284 All command scripts, including the package maintainer
2285 scripts inside the package and used by <prgn>dpkg</prgn>,
2286 should have a <tt>#!</tt> line naming the shell to be used
2287 to interpret them.</p>
2290 In the case of Perl scripts this should be
2291 <tt>#!/usr/bin/perl</tt>.</p>
2294 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2295 should almost certainly start with <tt>set -e</tt> so that
2296 errors are detected. Every script <em>must</em> use
2297 <tt>set -e</tt> or check the exit status of <em>every</em>
2301 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2302 symbolic link to any POSIX compatible shell. Thus, shell
2303 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2304 only use POSIX features. If a script requires non-POSIX
2305 features from the shell interpreter, the appropriate shell
2306 has to be specified in the first line of the script (e.g.,
2307 `<tt>#!/bin/bash</tt>') and the package has to depend on
2308 the package providing the shell (unless the shell package
2309 is marked `Essential', e.g., in the case of
2310 <prgn>bash</prgn>).</p>
2313 Restrict your script to POSIX features when possible so
2314 that it may use <tt>/bin/sh</tt> as its interpreter. If
2315 your script works with <prgn>ash</prgn>, it's probably
2316 POSIX compliant, but if you are in doubt, use
2317 <tt>/bin/bash</tt>.</p>
2320 Perl scripts should check for errors when making any
2321 system calls, including <tt>open</tt>, <tt>print</tt>,
2322 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2325 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2326 as scripting languages. See <em>Csh Programming
2327 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2328 FAQs. It can be found on
2329 <url id="http://language.perl.com/versus/csh.whynot">, or
2330 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2331 or even on <ftpsite>ftp.cpan.org</ftpsite>
2332 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2333 If an upstream package comes with <prgn>csh</prgn> scripts
2334 then you must make sure that they start with
2335 <tt>#!/bin/csh</tt> and make your package depend on the
2336 <prgn>c-shell</prgn> virtual package.</p>
2339 Any scripts which create files in world-writable
2340 directories (e.g., in <tt>/tmp</tt>) have to use a
2341 mechanism which will fail if a file with the same name
2345 The Debian base distribution provides the
2346 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2347 for use by scripts for this purpose.</p></sect>
2351 <heading>Symbolic links</heading>
2354 In general, symbolic links within a top-level directory
2355 should be relative, and symbolic links pointing from one
2356 top-level directory into another should be absolute. (A
2357 top-level directory is a sub-directory of the root
2361 In addition, symbolic links should be specified as short
2362 as possible, i.e., link targets like `foo/../bar' are
2366 Note that when creating a relative link using
2367 <prgn>ln</prgn> it is not necessary for the target of the
2368 link to exist relative to the working directory you're
2369 running <prgn>ln</prgn> from; nor is it necessary to
2370 change directory to the directory where the link is to be
2371 made. Simply include the string that should appear as the
2372 target of the link (this will be a pathname relative to
2373 the directory in which the link resides) as the first
2374 argument to <prgn>ln</prgn>.</p>
2377 For example, in your <prgn>Makefile</prgn> or
2378 <tt>debian/rules</tt>, do things like:
2380 ln -fs gcc $(prefix)/bin/cc
2381 ln -fs gcc debian/tmp/usr/bin/cc
2382 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2383 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2387 A symbolic link pointing to a compressed file should
2388 always have the same file extension as the referenced
2389 file. (For example, if a file `<tt>foo.gz</tt>' is
2390 referenced by a symbolic link, the filename of the link
2391 has to end with `<tt>.gz</tt>' too, as in
2392 `bar.gz.')</p></sect>
2396 <heading>Device files</heading>
2399 No package may include device files in the package file
2403 If a package needs any special device files that are not
2404 included in the base system, it has to call
2405 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2406 after asking the user for permission to do so.</p>
2409 No package should remove any device files in the
2410 <tt>postrm</tt> or any other script. This is left to the
2411 system administrator.</p>
2414 Debian uses the serial devices
2415 <tt>/dev/tty*</tt>. Programs using the old
2416 <tt>/dev/cu*</tt> devices should be changed to use
2417 <tt>/dev/tty*</tt>.</p>
2420 <sect id="config files">
2421 <heading>Configuration files</heading>
2423 <heading>Definitions</heading>
2426 <tag>configuration file</tag>
2428 A file that affects the operation of program, or
2429 provides site- or host-specific information, or
2430 otherwise customizes the behavior of program.
2431 Typically, configuration files are intended to be
2432 modified by the system administrator (if needed or
2433 desired) to conform to local policy or provide more
2434 useful site-specific behavior.</p>
2437 <tag><tt>conffile</tt></tag>
2439 A file listed in a package's <tt>conffiles</tt>
2440 file, and is treated specially by <prgn>dpkg</prgn>
2441 (see the <em>Debian Packaging Manual</em>).</p>
2447 The distinction between these two is important; they are
2448 not interchangeable concepts. Almost all
2449 <tt>conffiles</tt> are configuration files, but many
2450 configuration files are not <tt>conffiles</tt>.</p>
2453 Note that a script that embeds configuration information
2454 (such as most of the files in <tt>/etc/init.d</tt> and
2455 <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
2456 configuration file and should be treated as such.</p>
2460 <heading>Location</heading>
2462 Any configuration files created or used by your package
2463 should reside in <tt>/etc</tt>. If there are several you
2464 should consider creating a subdirectory of <tt>/etc</tt>
2465 named after your package.</p>
2468 If your packages creates or uses configuration files
2469 outside of <tt>/etc</tt>, and it is not feasible to modify
2470 the package to use the <tt>/etc</tt>, you should still put
2471 the files in <tt>/etc</tt> and create symbolic links to
2472 those files from the location that the package
2477 <heading>Behavior</heading>
2479 Configuration file handling must conform to the following
2483 <p>local changes must be preserved during a package
2487 <p>configuration files should be preserved when the
2488 package is removed, and only deleted when the
2489 package is purged.</p>
2494 The easy way to achieve this behavior is to make the
2495 configuration file a <tt>conffile</tt>. This is
2496 appropriate if it is possible to distribute a default
2497 version that will work for most installations, although
2498 some system administrators may choose to modify it. This
2499 implies that the default version will be part of the
2500 package distribution, and must not be modified by the
2501 maintainer scripts during installation (or at any other
2505 The other way to do it is to via the maintainer scripts.
2506 In this case, the configuration file must not be listed as
2507 a <tt>conffile</tt> and must not be part of the package
2508 distribution. If the existence of a file is required for
2509 the package to be sensibly configured it is the
2510 responsibility of the package maintainer to write scripts
2511 which correctly create, update, maintain and
2512 remove-on-purge the file. These scripts must be idempotent
2513 (i.e. must work correctly if <prgn>dpkg</prgn> needs to
2514 re-run them due to errors during installation or removal),
2515 must cope with all the variety of ways <prgn>dpkg</prgn>
2516 can call maintainer scripts, must not overwrite or
2517 otherwise mangle the user's configuration without asking,
2518 must not ask unnecessary questions (particularly during
2519 upgrades), and otherwise be good citizens.</p>
2522 The scripts need not configure every possible option for
2523 the package, but only those necessary to get the package
2524 running on a given system. Ideally the sysadmin should not
2525 have to do any configuration other than that done
2526 (semi-)automatically by the <tt>postinst</tt> script.</p>
2529 A common practice is to create a script called
2530 <tt><var>package</var>-configure</tt> and have the
2531 package's <tt>postinst</tt> call it if and only if the
2532 configuration file does not already exist. In certain
2533 cases it is useful for there to be an example or template
2534 file which the maintainer scripts use. Such files should
2535 be in <tt>/usr/share/doc</tt> if they are examples or
2536 <tt>/usr/lib</tt> if they are templates, and should be
2537 perfectly ordinary <prgn>dpkg</prgn>-handled files
2538 (<em>not</em> <tt>conffiles</tt>).</p>
2541 These two styles of configuration file handling <em>must
2542 not be mixed</em>, for that way lies madness:
2543 <prgn>dpkg</prgn> will ask about overwriting the file
2544 every time the package is upgraded.</p>
2548 <heading>Sharing configuration files</heading>
2550 Only packages that are tagged <em>conflicting</em> with
2551 each other may specify the same file as
2552 <tt>conffile</tt>.</p>
2555 The maintainer scripts should not alter the conffile of
2556 <em>any</em> package, including the one the scripts belong
2560 If two or more packages use the same configuration file
2561 and it is reasonable for both to be installed at the same
2562 time, one of these packages must be defined as
2563 <em>owner</em> of the configuration file, i.e. it will be
2564 the package to list that distributes the file and lists it
2565 as a <tt>conffile</tt>. Other packages that use the
2566 configuration file should depend on the owning package if
2567 they require the configuration file to operate. If the
2568 other package will use the configuration file if present,
2569 but is capable of operating without it, no dependency need
2573 If it is desirable for two or more related packages to
2574 share a configuration file <em>and</em> for all of the
2575 related packages to be able to modify that configuration
2576 file, then the following should done:
2580 have one of the related packages (the "core"
2581 package) manage the configuration file with
2582 maintainer scripts as described in the previous
2586 the core package should also provide a program that
2587 the other packages may use to modify the
2588 configuration file.</p>
2592 the related packages must use the provided program
2593 to make any modifications to the configuration file.
2594 They should either depend on the core package to
2595 guarantee that the configuration modifier program is
2596 available or accept gracefully that they cannot
2597 modify the configuration file if it is not.</p>
2602 Sometimes it's appropriate to create a new package which
2603 provides the basic infrastructure for the other packages
2604 and which manages the shared configuration files. (Check
2605 out the <tt>sgml-base</tt> package as an example.)</p>
2609 <heading>User configuration files ("dotfiles")</heading>
2612 Files in <tt>/etc/skel</tt> will automatically be copied
2613 into new user accounts by <prgn>adduser</prgn>. They
2614 should not be referenced there by any program.</p>
2617 Therefore, if a program needs a dotfile to exist in
2618 advance in <tt>$HOME</tt> to work sensibly that dotfile
2619 should be installed in <tt>/etc/skel</tt> (and listed in
2620 conffiles, if it is not generated and modified dynamically
2621 by the package's installation scripts).</p>
2624 However, programs that require dotfiles in order to
2625 operate sensibly (dotfiles that they do not create
2626 themselves automatically, that is) are a bad thing, and
2627 programs should be configured by the Debian default
2628 installation as close to normal as possible.</p>
2631 Therefore, if a program in a Debian package needs to be
2632 configured in some way in order to operate sensibly that
2633 configuration should be done in a site-wide global
2634 configuration file elsewhere in <tt>/etc</tt>. Only if the
2635 program doesn't support a site-wide default configuration
2636 and the package maintainer doesn't have time to add it
2637 should a default per-user file be placed in
2638 <tt>/etc/skel</tt>.</p>
2641 <tt>/etc/skel</tt> should be as empty as we can make it.
2642 This is particularly true because there is no easy
2643 mechanism for ensuring that the appropriate dotfiles are
2644 copied into the accounts of existing users when a package
2650 <heading>Log files</heading>
2652 The traditional approach to log files has been to set up ad
2653 hoc log rotation schemes using simple shell scripts and
2654 cron. While this approach is highly customizable, it
2655 requires quite a lot of sysadmin work. Even though the
2656 original Debian system helped a little by automatically
2657 installing a system which can be used as a template, this
2658 was deemed not enough.
2662 A better scheme is to use logrotate, a GPL'd program
2663 developed by Red Hat, which centralizes log management. It
2664 has both a configuration file (<tt>/etc/logrotate.conf</tt>)
2665 and a directory where packages can drop logrotation info
2666 (<tt>/etc/logrotate.d</tt>).
2670 Log files should usually be named
2671 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2672 log files, or need a separate directory for permissions
2673 reasons (<tt>/var/log</tt> is writable only by
2674 <tt>root</tt>), you should usually create a directory named
2675 <tt>/var/log/<var>package</var></tt>.</p>
2678 Make sure that any log files are rotated occasionally so
2679 that they don't grow indefinitely; the best way to do this
2680 is to drop a script into the directory
2681 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2682 logrotate. Here is a good example for a logrotate config
2683 file (for more information see <manref name="logrotate"
2691 /etc/init.d/foo force-reload
2695 Which rotates all files under `/var/log/foo', saves 12
2696 compressed generations, and sends a HUP signal at the end of
2702 Make sure that any log files are removed when the package is
2703 purged (but not when it is only removed), by checking the
2704 argument to the <tt>postrm</tt> script (see the <em>Debian
2705 Packaging Manual</em> for details).</p>
2710 <heading>Permissions and owners</heading>
2713 The rules in this section are guidelines for general use.
2714 If necessary you may deviate from the details below.
2715 However, if you do so you must make sure that what is done
2716 is secure and you must try to be as consistent as possible
2717 with the rest of the system. You should probably also
2718 discuss it on <prgn>debian-devel</prgn> first.</p>
2721 Files should be owned by <tt>root.root</tt>, and made
2722 writable only by the owner and universally readable (and
2723 executable, if appropriate).</p>
2726 Directories should be mode 755 or (for group-writability)
2727 mode 2775. The ownership of the directory should be
2728 consistent with its mode--if a directory is mode 2775, it
2729 should be owned by the group that needs write access to
2733 Setuid and setgid executables should be mode 4755 or 2755
2734 respectively, and owned by the appropriate user or group.
2735 They should not be made unreadable (modes like 4711 or
2736 2711 or even 4111); doing so achieves no extra security,
2737 because anyone can find the binary in the freely available
2738 Debian package--it is merely inconvenient. For the same
2739 reason you should not restrict read or execute permissions
2740 on non-set-id executables.</p>
2743 Some setuid programs need to be restricted to particular
2744 sets of users, using file permissions. In this case they
2745 should be owned by the uid to which they are set-id, and
2746 by the group which should be allowed to execute them.
2747 They should have mode 4754; there is no point in making
2748 them unreadable to those users who must not be allowed to
2752 Do not arrange that the system administrator can only
2753 reconfigure the package to correspond to their local
2754 security policy by changing the permissions on a binary.
2755 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2756 to conffiles and other similar objects) have their
2757 permissions reset to the distributed permissions when the
2758 package is reinstalled. Instead you should consider (for
2759 example) creating a group for people allowed to use the
2760 program(s) and making any setuid executables executable
2761 only by that group.</p>
2764 If you need to create a new user or group for your package
2765 there are two possibilities. Firstly, you may need to
2766 make some files in the binary package be owned by this
2767 user or group, or you may need to compile the user or
2768 group id (rather than just the name) into the binary
2769 (though this latter should be avoided if possible). In
2770 this case you need a statically allocated id.</p>
2773 You must ask for a user or group id from the base system
2774 maintainer, and must not release the package until you
2775 have been allocated one. Once you have been allocated one
2776 you must make the package depend on a version of the base
2777 system with the id present in <tt>/etc/passwd</tt> or
2778 <tt>/etc/group</tt>, or alternatively arrange for your
2779 package to create the user or group itself with the
2780 correct id (using <tt>adduser</tt>) in its pre- or
2781 post-installation script (the latter is to be preferred if
2782 it is possible).</p>
2785 On the other hand, the program may able to determine the
2786 uid or gid from the group name at runtime, so that a
2787 dynamic id can be used. In this case you must choose an
2788 appropriate user or group name, discussing this on
2789 <prgn>debian-devel</prgn> and checking with the base
2790 system maintainer that it is unique and that they do not
2791 wish you to use a statically allocated id instead. When
2792 this has been checked you must arrange for your package to
2793 create the user or group if necessary using
2794 <prgn>adduser</prgn> in the pre- or post-installation
2795 script (again, the latter is to be preferred if it is
2799 Note that changing the numeric value of an id associated with a name
2800 is very difficult, and involves searching the file system for all
2801 appropriate files. You need to think carefully whether a static or
2802 dynamic id is required, since changing your mind later will cause
2808 <heading>Customized programs</heading>
2810 <sect id="arch-spec">
2811 <heading>Architecture specification strings</heading>
2814 If a program needs to specify an <em>architecture specification
2815 string</em> in some place, the following format has to be used:
2817 <arch>-<os>
2819 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2820 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2821 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2822 operating system. .</p>
2824 Note, that we don't want to use `<arch>-debian-linux'
2825 to apply to the rule `architecture-vendor-os' since this
2826 would make our programs incompatible to other Linux
2827 distributions. Also note, that we don't use
2828 `<arch>-unknown-linux', since the `unknown' does not
2829 look very good.</p></sect>
2833 <heading>Daemons</heading>
2836 The configuration files <tt>/etc/services</tt>,
2837 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2838 by the <prgn>netbase</prgn> package and may not be modified
2839 by other packages.</p>
2842 If a package requires a new entry in one of these files, the
2843 maintainer has to get in contact with the
2844 <prgn>netbase</prgn> maintainer, who will add the entries
2845 and release a new version of the <prgn>netbase</prgn>
2849 The configuration file <tt>/etc/inetd.conf</tt> may be
2850 modified by the package's scripts only via the
2851 <prgn>update-inetd</prgn> script or the
2852 <prgn>DebianNet.pm</prgn> Perl module.</p>
2855 If a package wants to install an example entry into
2856 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2857 exactly one hash character (<tt>#</tt>). Such lines are
2858 treated as `commented out by user' by the
2859 <prgn>update-inetd</prgn> script and are not changed or
2860 activated during a package updates.</p></sect>
2864 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2867 Some programs need to create pseudo-ttys. This should be done
2868 using Unix98 ptys if the C library supports it. The resulting
2869 program must not be installed setuid root, unless that
2870 is required for other functionality.
2874 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2875 <tt>/var/log/lastlog</tt> must be installed writeable by
2876 group utmp. Programs who need to modify those files must
2877 be installed install setgid utmp.
2882 <heading>Editors and pagers</heading>
2885 Some programs have the ability to launch an editor or pager
2886 program to edit or display a text document. Since there are
2887 lots of different editors and pagers available in the Debian
2888 distribution, the system administrator and each user should
2889 have the possibility to choose his/her preferred editor and
2893 In addition, every program should choose a good default
2894 editor/pager if none is selected by the user or system
2898 Thus, every program that launches an editor or pager has to
2899 use the EDITOR or PAGER environment variables to determine
2900 the editor/pager the user wants to get started. If these
2901 variables are not set, the programs <tt>/usr/bin/editor</tt>
2902 and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
2905 These two files are managed through `alternatives.' That is,
2906 every package providing an editor or pager has to call the
2907 <prgn>update-alternatives</prgn> script to register these
2911 If it is very hard to adapt a program to make us of the
2912 EDITOR and PAGER variable, that program should be configured
2913 to use <tt>/usr/bin/sensible-editor</tt> and
2914 <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
2915 respectively. These are two scripts provided in the Debian
2916 base system that check the EDITOR and PAGER variables and
2917 launches the appropriate program or falls back to
2918 <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
2922 A program may also use the VISUAL environment variable to
2923 determine the user's choice of editor. If it exists, it
2924 should take precedence over EDITOR. This is in fact what
2925 <tt>/usr/bin/sensible-editor</tt> does.</p>
2928 Since the Debian base system already provides an editor and
2929 a pager program, there is no need for a package to depend on
2930 `editor' and `pager', nor is it necessary for a package to
2931 provide such virtual packages.</p></sect>
2934 <sect id="web-appl">
2935 <heading>Web servers and applications</heading>
2938 This section describes the locations and URLs that have to
2939 be used by all web servers and web application in the Debian
2945 <p>Cgi-bin executable files are installed in the
2948 /usr/lib/cgi-bin/<cgi-bin-name>
2950 and can be referred to as
2952 http://localhost/cgi-bin/<cgi-bin-name>
2953 </example></p></item>
2956 <item><p>Access to html documents</p>
2959 Html documents for a package are stored in
2960 <tt>/usr/share/doc/<var>package</var></tt> but should
2961 be accessed via symlinks as
2962 <tt>/usr/doc/<var>package</var></tt><footnote> for
2963 backward compatibility, see <ref id="usrdoc"></footnote>
2964 and can be referred to as
2966 http://localhost/doc/<package>/<filename>
2967 </example></p></item>
2970 <item><p>Web Document Root</p>
2973 Web Applications should try to avoid storing files in
2974 the Web Document Root. Instead use the
2975 /usr/share/doc/<package> directory for documents and
2976 register the Web Application via the menu package. If
2977 access to the web-root is unavoidable then use
2981 as the Document Root. This might be just a
2982 symbolic link to the location where the sysadmin has
2983 put the real document root.</p>
2986 </enumlist></p></sect>
2990 <heading>Mail transport agents</heading>
2993 Debian packages which process electronic mail, whether
2994 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
2995 <em>must</em> make sure that they are compatible with the
2996 configuration decisions below. Failure to do this may
2997 result in lost mail, broken <tt>From:</tt> lines, and other
2998 serious brain damage!</p>
3001 The mail spool is <tt>/var/spool/mail</tt> and the interface
3002 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
3003 per the FHS). The mail spool is part of the base system
3004 and not part of the MTA package.</p>
3007 All Debian MUAs, MTAs, MDAs and other mailbox accessing
3008 programs (like IMAP daemons) have to lock the mailbox in a
3009 NFS-safe way. This means that <tt>fcntl()</tt> locking has
3010 to be combined with dot locking. To avoid dead locks, a
3011 program has to use <tt>fcntl()</tt> first and dot locking
3012 after this or alternatively implement the two locking
3013 methods in a non blocking way<footnote>
3015 If it is not possible to establish both locks, the
3016 system shouldn't wait for the second lock to be
3017 established, but remove the first lock, wait a (random)
3018 time, and start over locking again.</p>
3019 </footnote>. Using the functions <tt>maillock</tt> and
3020 <tt>mailunlock</tt> provided by the
3021 <tt>liblockfile*</tt><footnote>
3023 <tt>liblockfile</tt> version >>1.01</p>
3024 </footnote> packages is the recommended way to realize this.
3028 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
3029 unless the user has chosen otherwise. A MUA may remove a
3030 mailbox (unless it has nonstandard permissions) in which
3031 case the MTA or another MUA must recreate it if needed.
3032 Mailboxes must be writable by group mail.</p>
3035 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
3036 be setgid mail to do the locking mentioned above (and
3037 obviously need to avoid accessing other users' mailboxes
3038 using this privilege).</p>
3041 <tt>/etc/aliases</tt> is the source file for the system mail
3042 aliases (e.g., postmaster, usenet, etc.)--it is the one
3043 which the sysadmin and <tt>postinst</tt> scripts may edit.
3044 After <tt>/etc/aliases</tt> is edited the program or human
3045 editing it must call <prgn>newaliases</prgn>. All MTA
3046 packages should come with a <prgn>newaliases</prgn> program,
3047 even if it does nothing, but older MTA packages do not do
3048 this so programs should not fail if <prgn>newaliases</prgn>
3049 cannot be found.</p>
3052 The convention of writing <tt>forward to
3053 <var>address</var></tt> in the mailbox itself is not
3054 supported. Use a <tt>.forward</tt> file instead.</p>
3057 The location for the <prgn>rmail</prgn> program used by UUCP
3058 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
3059 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
3060 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
3064 If you need to know what name to use (for example) on
3065 outgoing news and mail messages which are generated locally,
3066 you should use the file <tt>/etc/mailname</tt>. It will
3067 contain the portion after the username and <tt>@</tt> (at)
3068 sign for email addresses of users on the machine (followed
3072 A package should check for the existence of this file. If
3073 it exists it should use it without comment. (An MTA's
3074 prompting configuration script may wish to prompt the user
3075 even if it finds this file exists.) If it does not exist it
3076 should prompt the user for the value and store it in
3077 <tt>/etc/mailname</tt> as well as using it in the package's
3078 configuration. The prompt should make it clear that the
3079 name will not just be used by that package. For example, in
3080 this situation the INN package says:
3082 Please enter the `mail name' of your system. This is the
3083 hostname portion of the address to be shown on outgoing
3084 news and mail messages. The default is
3085 <var>syshostname</var>, your system's host name. Mail
3086 name [`<var>syshostname</var>']:
3088 where <var>syshostname</var> is the output of <tt>hostname
3089 --fqdn</tt>.</p></sect>
3093 <heading>News system configuration</heading>
3096 All the configuration files related to the NNTP (news)
3097 servers and clients should be located under
3098 <tt>/etc/news</tt>.</p>
3101 There are some configuration issues that apply to a number
3102 of news clients and server packages on the machine. These
3106 <tag>/etc/news/organization</tag>
3107 <item><p>A string which shall appear as the
3108 organization header for all messages posted
3109 by NNTP clients on the machine</p></item>
3111 <tag>/etc/news/server</tag>
3112 <item><p>Contains the FQDN of the upstream NNTP
3113 server, or localhost if the local machine is
3114 an NNTP server.</p></item>
3117 Other global files may be added as required for cross-package news
3118 configuration.</p></sect>
3122 <heading>Programs for the X Window System</heading>
3125 Some programs can be configured with or without support for the X
3126 Window System. Typically, binaries produced with support for X
3127 will need the X shared libraries to run.
3131 Such programs should be configured <em>with</em> X support,
3132 and should declare a dependency on <tt>xlib6g</tt> (which
3133 contains X shared libraries). Users who wish to use the
3134 program can install just the relatively small
3135 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
3136 not need to install the whole of X.</p>
3139 Do not create two versions (one with X support and one
3140 without) of your package.</p>
3143 <em>Application defaults</em> files have to be installed in
3144 the directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
3145 They are considered as part of the program code. Thus, they
3146 should not be modified and should not be tagged as
3147 <em>conffile</em>s nor otherwise treated as configuration
3148 files. If the local system administrator wants
3149 to customize X applications globally, a file with the same
3150 name as that of the package should be placed in the
3151 <tt>/etc/X11/Xresources/</tt> directory instead.
3152 <em>Important:</em> packages that install files into the
3153 <tt>/etc/X11/Xresources/</tt> directory <em>must</em>
3154 declare a conflict with <tt>xbase (<<
3155 3.3.2.3a-2)</tt>; if this is not done it is possible for the
3156 package to destroy a previously-existing
3157 <tt>/etc/X11/Xresources</tt> <em>file</em>.</p>
3160 No package should ever install files into the directories
3161 <tt>/usr/bin/X11/</tt>, <tt>/usr/share/doc/X11/</tt>,
3162 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>; these
3163 directories are actually symbolic links, which <tt>dpkg</tt>
3164 does not follow when unpacking a package. Instead, use
3165 <tt>/usr/X11R6/bin/</tt>, <tt>/usr/share/doc/package/</tt>
3166 (i.e., place files with the rest of your package's
3167 documentation), <tt>/usr/X11R6/include/</tt>, and
3168 <tt>/usr/X11R6/lib/</tt>. This restriction governs only the
3169 paths used by the package as it is unpacked onto the system;
3170 it is permissible, and even preferable, for files within a
3171 package (shell scripts, for instance) to refer to the
3172 <tt>/usr/{bin,include,lib}/X11/</tt> directories rather than
3173 their <tt>/usr/X11R6/</tt> counterparts -- this way they do
3174 not have to be modified in the event that the X Window
3175 System packages install their files into a different
3176 directory in the future.</p>
3179 If you package a program that requires the (non-free)
3180 OSF/Motif library, you should try to determine whether the
3181 programs works reasonably well with the free
3182 re-implementation of Motif called LessTif. If so, build the
3183 package using the LessTif libraries; it can then go into the
3184 main section of the package repository and become an
3185 official part of the Debian distribution.</p>
3188 If however, the Motif-based program works insufficiently
3189 well with LessTif, you should instead provide "-smotif" and "-dmotif"
3190 versions (appending these identifiers to the name of the
3191 package), which are statically and dynamically linked
3192 against the Motif libraries, respectively. (All known
3193 versions of OSF/Motif permit redistribution of
3194 statically-linked binaries using the library, but check the
3195 license on your copy of Motif to be sure.) This two-package
3196 approach allows users without Motif to use the package,
3197 whereas users with Motif installed can enjoy the advantages
3198 of the dynamically-linked version (a considerable savings in
3199 disk space usage, download time, etc.). Neither "-smotif"
3200 nor "-dmotif" packages can go into the main section; if the
3201 licensing on the package is compatible with the Debian Free
3202 Software Guidelines, it may go into the contrib section;
3203 otherwise it must go into the non-free section.
3210 <heading>Emacs lisp programs</heading>
3213 Please refer to the `Debian Emacs Policy' (documented in
3214 <tt>debian-emacs-policy.gz</tt> of the
3215 <prgn>emacsen-common</prgn> package) for details of how to
3216 package emacs lisp programs.</p></sect>
3220 <heading>Games</heading>
3223 The permissions on /var/games are 755
3224 <tt>root.root</tt>.</p>
3227 Each game decides on its own security policy.</p>
3230 Games which require protected, privileged access to
3231 high-score files, savegames, etc., must be made
3232 set-<em>group</em>-id (mode 2755) and owned by
3233 <tt>root.games</tt>, and use files and directories with
3234 appropriate permissions (770 <tt>root.games</tt>, for
3235 example). They must <em>not</em> be made
3236 set-<em>user</em>-id, as this causes security problems. (If
3237 an attacker can subvert any set-user-id game they can
3238 overwrite the executable of any other, causing other players
3239 of these games to run a Trojan horse program. With a
3240 set-group-id game the attacker only gets access to less
3241 important game data, and if they can get at the other
3242 players' accounts at all it will take considerably more
3246 Some packages, for example some fortune cookie programs, are
3247 configured by the upstream authors to install with their
3248 data files or other static information made unreadable so
3249 that they can only be accessed through set-id programs
3250 provided. Do not do this in a Debian package: anyone can
3251 download the <tt>.deb</tt> file and read the data from it,
3252 so there is no point making the files unreadable. Not
3253 making the files unreadable also means that you don't have
3254 to make so many programs set-id, which reduces the risk of a
3258 As described in the FHS, binaries of games should be
3259 installed in the directory <tt>/usr/games</tt>. This also
3260 applies to games that use the X Window System. Manual pages
3261 for games (X and non-X games) should be installed in
3262 <tt>/usr/share/man/man6</tt>.</p>
3266 <chapt><heading>Documentation</heading>
3270 <heading>Manual pages</heading>
3273 You must install manual pages in <prgn>nroff</prgn> source
3274 form, in appropriate places under <tt>/usr/share/man</tt>. You
3275 should only use sections 1 to 9 (see the FHS for more
3276 details). You must <em>not</em> install a preformatted `cat
3280 If no manual page is available for a particular program,
3281 utility or function and this is reported as a bug on
3282 debian-bugs, a symbolic link from the requested manual page
3283 to the <manref name="undocumented" section="7"> manual page
3284 should be provided. This symbolic link can be created from
3285 <tt>debian/rules</tt> like this:
3287 ln -s ../man7/undocumented.7.gz \
3288 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3290 This manpage claims that the lack of a manpage has been
3291 reported as a bug, so you may only do this if it really has
3292 (you can report it yourself, if you like). Do not close the
3293 bug report until a proper manpage is available.</p>
3296 You may forward a complaint about a missing manpage to the
3297 upstream authors, and mark the bug as forwarded in the
3298 Debian bug tracking system. Even though the GNU Project do
3299 not in general consider the lack of a manpage to be a bug,
3300 we do--if they tell you that they don't consider it a bug
3301 you should leave the bug in our bug tracking system open
3305 Manual pages should be installed compressed using <tt>gzip
3309 If one manpage needs to be accessible via several names it
3310 is better to use a symbolic link than the <tt>.so</tt>
3311 feature, but there is no need to fiddle with the relevant
3312 parts of the upstream source to change from <tt>.so</tt> to
3313 symlinks--don't do it unless it's easy. Do not create hard
3314 links in the manual page directories, and do not put
3315 absolute filenames in <tt>.so</tt> directives. The filename
3316 in a <tt>.so</tt> in a manpage should be relative to the
3317 base of the manpage tree (usually
3318 <tt>/usr/share/man</tt>).</p></sect>
3322 <heading>Info documents</heading>
3325 Info documents should be installed in <tt>/usr/share/info</tt>.
3326 They should be compressed with <tt>gzip -9</tt>.</p>
3329 Your package must call <prgn>install-info</prgn> to update the Info
3331 file, in its post-installation script:
3333 install-info --quiet --section Development Development \
3334 /usr/share/info/foobar.info
3338 It is a good idea to specify a section for the location of
3339 your program; this is done with the <tt>--section</tt>
3340 switch. To determine which section to use, you should look
3341 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3342 relevant (or create a new section if none of the current
3343 sections are relevant). Note that the <tt>--section</tt>
3344 flag takes two arguments; the first is a regular expression
3345 to match (case-insensitively) against an existing section,
3346 the second is used when creating a new one.</p>
3349 You must remove the entries in the pre-removal script:
3351 install-info --quiet --remove /usr/share/info/foobar.info
3355 If <prgn>install-info</prgn> cannot find a description entry
3356 in the Info file you will have to supply one. See <manref
3357 name="install-info" section="8"> for details.</p>
3361 <heading>Additional documentation</heading>
3364 Any additional documentation that comes with the package can
3365 be installed at the discretion of the package maintainer.
3366 Text documentation should be installed in a directory
3367 <tt>/usr/share/doc/<var>package</var></tt>, where
3368 <var>package</var> is the name of the package, and
3369 compressed with <tt>gzip -9</tt> unless it is small.</p>
3372 If a package comes with large amounts of documentation which
3373 many users of the package will not require you should create
3374 a separate binary package to contain it, so that it does not
3375 take up disk space on the machines of users who do not need
3376 or want it installed.</p>
3379 It is often a good idea to put text information files
3380 (<tt>README</tt>s, changelogs, and so forth) that come with
3381 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3382 in the binary package. However, you don't need to install
3383 the instructions for building and installing the package, of
3388 <heading>Accessing the documentation</heading>
3391 Former Debian releases placed all additional documentation
3392 in <tt>/usr/doc/<var>package</var></tt>. To realize a
3394 <tt>/usr/share/doc/<var>package</var></tt>, each package
3395 must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
3396 that points to the new location of its documentation in
3397 <tt>/usr/share/doc/<var>package</var></tt><footnote>These
3398 symlinks will be removed in the future, but they have to be
3399 there for compatibility reasons until all packages have
3400 moved and the policy is changed accordingly.</footnote>.
3401 The symlink must be created when the package is installed;
3402 it cannot be contained in the package itself due to problems
3403 with <prgn>dpkg</prgn>. One reasonable way to accomplish
3404 this is to put the following in the package's
3405 <prgn>postinst</prgn>:
3407 if [ "$1" = "configure" ]; then
3408 if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
3409 -a -d /usr/share/doc/#PACKAGE# ]; then
3410 ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
3414 And the following in the package's <prgn>prerm</prgn>:
3416 if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
3417 -a -L /usr/doc/#PACKAGE# ]; then
3418 rm -f /usr/doc/#PACKAGE#
3425 <heading>Preferred documentation formats</heading>
3428 The unification of Debian documentation is being carried out
3432 If your package comes with extensive documentation in a
3433 mark up format that can be converted to various other formats
3434 you should if possible ship HTML versions in a binary
3435 package, in the directory
3436 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3439 <p>The rationale: The important thing here is that HTML
3440 docs should be available in <em>some</em> package, not
3441 necessarily in the main binary package, though. </p>
3446 Other formats such as PostScript may be provided at your
3450 <sect id="copyrightfile">
3451 <heading>Copyright information</heading>
3454 Every package must be accompanied by a verbatim copy of its
3455 copyright and distribution license in the file
3456 /usr/share/doc/<package-name>/copyright. This file must
3457 neither be compressed nor be a symbolic link.</p>
3460 In addition, the copyright file must say where the upstream
3461 sources (if any) were obtained, and explain briefly what
3462 modifications were made in the Debian version of the package
3463 compared to the upstream one. It must name the original
3464 authors of the package and the Debian maintainer(s) who were
3465 involved with its creation.</p>
3468 /usr/share/doc/<package-name> may be a symbolic link to a
3469 directory in /usr/share/doc only if two packages both come from
3470 the same source and the first package has a "Depends"
3471 relationship on the second. These rules are important
3472 because copyrights must be extractable by mechanical
3476 Packages distributed under the UCB BSD license, the Artistic
3477 license, the GNU GPL, and the GNU LGPL should refer to the
3478 files /usr/share/common-licenses/BSD,
3479 /usr/share/common-licenses/Artistic,
3480 /usr/share/common-licenses/GPL, and
3481 /usr/share/common-licenses/LGPL.
3484 Why "licenses" and not "copyright"? Because
3485 <tt>/usr/doc/copyright</tt> used to contain all the
3486 copyright files, plus the four common licenses GPL,
3487 LGPL, Artistic and BSD. Now individual copyright files
3488 for packages are no longer in a common directory. Once
3489 <tt>/usr/doc/copyright</tt> is almost empty it makes
3490 sense to rename "copyright" to "licenses"
3493 Why "common-licenses" and not "licenses"? Because if I
3494 put just "licenses" I'm sure I will receive a bug report
3495 saying "license foo is not included in the licenses
3496 directory. They are not all the licenses, just a few
3497 common ones. I could use /usr/share/doc/common-licenses
3498 but I think this is too long, and, after all, the GPL
3499 does not "document" anything, it is merely a license.
3505 Do not use the copyright file as a general <tt>README</tt>
3506 file. If your package has such a file it should be
3507 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3508 <tt>README.Debian</tt> or some other appropriate place.</p>
3512 <heading>Examples</heading>
3515 Any examples (configurations, source files, whatever),
3516 should be installed in a directory
3517 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
3518 files should not be referenced by any program--they're there
3519 for the benefit of the system administrator and users, as
3520 documentation only. Architecture-specific example files
3521 should be installed in a directory
3522 <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
3523 <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
3524 to files in it. Or the latter directory may be a symlink to
3528 <sect id="instchangelog">
3529 <heading>Changelog files</heading>
3532 This installed file must contain a copy of the
3533 <tt>debian/changelog</tt> file from your Debian source tree,
3534 and a copy of the upstream changelog file if there is one.
3535 The debian/changelog file should be installed in
3536 <tt>/usr/share/doc/<var>package</var></tt> as
3537 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3538 file is text formatted, it must be accessible as
3539 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
3540 the upstream changelog file is HTML formatted, it must be
3542 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
3543 A plain text version of the changelog must be accessible as
3544 <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
3545 be created by <tt>lynx -dump -nolist</tt>). If the upstream
3546 changelog files do not already conform to this naming
3547 convention, then this may be achieved by either renaming the
3548 files or adding a symbolic link at the packaging developer's
3552 Both should be installed compressed using <tt>gzip -9</tt>,
3553 as they will become large with time even if they start out
3557 If the package has only one changelog which is used both as
3558 the Debian changelog and the upstream one because there is
3559 no separate upstream maintainer then that changelog should
3560 usually be installed as
3561 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3562 there is a separate upstream maintainer, but no upstream
3563 changelog, then the Debian changelog should still be called
3564 <tt>changelog.Debian.gz</tt>.</p>