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
90 A copy of the GNU General Public License is available as
91 <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
92 distribution or on the World Wide Web at
93 <url id="http://www.gnu.org/copyleft/gpl.html"
94 name="&urlname">. You can also obtain it by writing to the
95 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
96 Boston, MA 02111-1307, USA.
104 <heading>About this manual</heading>
106 <heading>Scope</heading>
108 This manual describes the policy requirements for the Debian
109 GNU/Linux distribution. This includes the structure and
110 contents of the Debian archive, several design issues of the
111 operating system, as well as technical requirements that
112 each package must satisfy to be included in the
116 This manual does <em>not</em> describe the technical
117 mechanisms involved in package creation, installation, and
118 removal. This information can be found in the <em>Debian
119 Packaging Manual</em> and the <em>Debian System
120 Administrators' Manual</em>.
123 This document assumes familiarity with these other two
124 manuals. Unfortunately, the <em>System Administrators'
125 Manual</em> does not exist yet.
128 Much of the information presented in this manual will be
129 useful even when building a package which is to be
130 distributed in some other way or is for local use.
134 <heading>New versions of this document</heading>
136 The current version of this document is always accessible from the
139 id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz" name="&urlname">
140 or from the Debian WWW server at
141 <url id="http://www.debian.org/doc/debian-policy/"
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
385 packages which we don't want to support because they are too
391 packages which fail to meet some other policy requirements in
399 <heading>The non-free section</heading>
401 `Non-free' contains packages which are not compliant with
402 the DFSG or which are encumbered by patents or other legal
403 issues that make their distribution problematic.</p>
405 All packages in `non-free' must be electronically
406 distributable across international borders.
410 <heading>The non-us server</heading>
412 Some programs with cryptographic program code must be stored
413 on the "non-us" server because of export restrictions of the
416 This applies only to packages which contain cryptographic
417 code. A package containing a program with an interface to a
418 cryptographic program or a program that's dynamically linked
419 against a cryptographic library can be distributed if it is
420 capable of running without the cryptography library or
425 <heading>Further copyright considerations</heading>
427 Every package must be accompanied by a verbatim copy of its
428 copyright and distribution license in the file
429 /usr/share/doc/<package-name>/copyright (see <ref
430 id="copyrightfile"> for details).</p>
432 We reserve the right to restrict files from being included
433 anywhere in our archives if
434 <list compact="compact">
437 their use or distribution would break a law,
442 there is an ethical conflict in their distribution or
448 we would have to sign a license for them, or
453 their distribution would conflict with other project
461 Programs whose authors encourage the user to make donations
462 are fine for the main distribution, provided that the
463 authors do not claim that not donating is immoral,
464 unethical, illegal or something similar; otherwise they must
465 go in contrib (or non-free, if even distribution is
466 restricted by such statements).</p>
469 Packages whose copyright permission notices (or patent
470 problems) do not allow redistribution even of only binaries,
471 and where no special permission has been obtained, cannot be
472 placed on the Debian FTP site and its mirrors at all.</p>
475 Note, that under international copyright law (this applies
476 in the United States, too) <em>no</em> distribution or
477 modification of a work is allowed without an explicit notice
478 saying so. Therefore a program without a copyright notice
479 <em>is</em> copyrighted and you may not do anything to it
480 without risking being sued! Likewise if a program has a
481 copyright notice but no statement saying what is permitted
482 then nothing is permitted.</p>
485 Many authors are unaware of the problems that restrictive
486 copyrights (or lack of copyright notices) can cause for the
487 users of their supposedly-free software. It is often
488 worthwhile contacting such authors diplomatically to ask
489 them to modify their license terms. However, this is a
490 politically difficult thing to do and you should ask for
491 advice on <tt>debian-devel</tt> first.</p>
494 When in doubt, send mail to
495 <email>debian-devel@lists.debian.org</email>. Be prepared
496 to provide us with the copyright statement. Software
497 covered by the GPL, public domain software and BSD-like
498 copyrights are safe; be wary of the phrases `commercial use
499 prohibited' and `distribution restricted'.</p>
502 <heading>Subsections</heading>
505 The packages in all the sections (<em>main</em>,
506 <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
507 <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
508 grouped further into <em>subsections</em> to simplify
512 The section for each package is specified in the package's
513 <em>control record</em>. However, the maintainer of the
514 Debian archive may override this selection to assure the
515 consistency of the Debian distribution. </p>
518 Please check the current Debian distribution to see which
519 sections are available.</p>
522 <heading>Priorities</heading>
525 Each package is given a certain <em>priority</em> value,
526 which is included in the package's <em>control
527 record</em>. This information is used in the Debian package
528 management tool to separate high-priority packages from
529 less-important packages.</p>
532 The following <em>priority levels</em> are supported by the
533 Debian package management system, <prgn>dpkg</prgn>.
535 <tag><tt>required</tt></tag>
538 <tt>required</tt> packages are necessary for the
539 proper functioning of the system. You must not remove
540 these packages or your system may become totally
541 broken and you may not even be able to use
542 <prgn>dpkg</prgn> to put things back. Systems with
543 only the <tt>required</tt> packages are probably
544 unusable, but they do have enough functionality to
545 allow the sysadmin to boot and install more
548 <tag><tt>important</tt></tag>
551 Important programs, including those which one would
552 expect to find on any Unix-like system. If the
553 expectation is that an experienced Unix person who
554 found it missing would say `What the F*!@<+ is
555 going on, where is <prgn>foo</prgn>', it must be in
556 <tt>important</tt>. This is an important criterion
557 because we are trying to produce, amongst other
558 things, a free Unix. Other packages without which the
559 system will not run well or be usable must also be
560 here. This does <em>not</em> include Emacs, the X
561 Window System, TeX or any other large applications.
562 The <tt>important</tt> packages are just a bare
563 minimum of commonly-expected and necessary tools.</p>
565 <tag><tt>standard</tt></tag>
568 These packages provide a reasonably small but not too
569 limited character-mode system. This is what will
570 install by default if the user doesn't select anything
571 else. It doesn't include many large applications, but
572 it does include Emacs (this is more of a piece of
573 infrastructure than an application) and a reasonable
574 subset of TeX and LaTeX (if this is possible without
577 <tag><tt>optional</tt></tag>
580 (In a sense everything is optional that isn't
581 required, but that's not what is meant here.) This is
582 all the software that you might reasonably want to
583 install if you didn't know what it was or don't have
584 specialized requirements. This is a much larger system
585 and includes the X Window System, a full TeX
586 distribution, and many applications.</p>
588 <tag><tt>extra</tt></tag>
591 This contains packages that conflict with others with
592 higher priorities, or are only likely to be useful if
593 you already know what they are or have specialized
600 Packages may not depend on packages with lower priority
601 values. If this does happen, one of the priority values
602 will have to be adapted.
607 <heading>Binary packages</heading>
610 The Debian GNU/Linux distribution is based on the Debian
611 package management system, called <prgn>dpkg</prgn>. Thus,
612 all packages in the Debian distribution have to be provided
613 in the <tt>.deb</tt> file format.</p>
617 <heading>The package name</heading>
620 Every package must have a name that's unique within the Debian
624 Package names may only consist of lower case letters, digits (0-9),
625 plus (+) or minus (-) signs, and periods (.).</p>
628 The package name is part of the file name of the
629 <tt>.deb</tt> file and is included in the control field
635 <heading>The maintainer of a package</heading>
638 Every package must have exactly one maintainer at a
639 time. This person is responsible that the license of the
640 package's software complies with the policy of the
641 distribution this package is included in.</p>
644 The maintainer must be specified in the
645 <tt>Maintainer</tt> control field with the correct name
646 and a working email address for the Debian maintainer of
647 the package. If one person maintains several packages
648 he/she should try to avoid having different forms of their
649 name and email address in different <tt>Maintainer</tt>
653 If the maintainer of a package quits from the Debian
654 project the Debian QA Group
655 <email>debian-qa@lists.debian.org</email> takes over the
656 maintainership of the package until someone else
657 volunteers for that task. These packages are called
658 <em>orphaned packages</em>.
664 <heading>The description of a package</heading>
667 Every Debian package must have an extended description
668 stored in the appropriate field of the control record.</p>
671 The description must be written so that it tells the user
672 what they need to know to decide whether to install the
673 package. This description should not just be copied from
674 the blurb for the program. Instructions for configuring
675 or using the package must not be included -- that is what
676 installation scripts, manual pages, Info files, etc. are
677 for. Copyright statements and other administrivia must
678 not be included -- that is what the copyright file is
684 <heading>Dependencies</heading>
687 Every package has to specify the dependency information
688 about other packages, that are required for the first to
692 For example, for any shared libraries required by
693 dynamically-linked executable binary in a package a
694 dependency entry has to be provided.</p>
697 It is not necessary for other packages to declare any
698 dependencies they have on other packages which are marked
699 <tt>Essential</tt> (see below).</p>
702 Sometimes, a package requires another package to be
703 installed <em>and</em> configured before it can be
704 installed. In this case, you'll have to specify a
705 <tt>Pre-Depends</tt> entry for the package.</p>
708 You must not specify a <tt>Pre-Depends</tt> entry for a
709 package before this has been discussed on the
710 <tt>debian-devel</tt> mailing list and a consensus about
711 doing that has been reached.</p></sect1>
715 <heading>Virtual packages</heading>
718 Sometimes, there are several packages doing more-or-less
719 the same job. In this case, it's useful to define a
720 <em>virtual package</em> who's name describes the function
721 the packages have. (The virtual packages just exist
722 logically, not physically--that's why they are called
723 <em>virtual</em>.) The packages with this particular
724 function will then <em>provide</em> the virtual
725 package. Thus, any other package requiring that function
726 can simply depend on the virtual package without having to
727 specify all possible packages individually.</p>
730 All packages must use virtual package names where
731 appropriate, and arrange to create new ones if necessary.
732 They must not use virtual package names (except privately,
733 amongst a cooperating group of packages) unless they have
734 been agreed upon and appear in the list of virtual package
738 The latest version of the authoritative list of virtual
739 package names can be found on
740 <ftpsite>ftp.debian.org</ftpsite> in
741 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
742 or your local mirror. In addition, it is included in the
743 <tt>debian-policy</tt> package. The procedure for updating
744 the list is described at the top of the file.</p></sect1>
748 <heading>Base packages</heading>
751 The packages included in the <tt>base</tt> section have a
752 special function. They form a minimum subset of the Debian
753 GNU/Linux system that is installed before everything else
754 on a new system. Thus, only very few packages are allowed
755 to go into the <tt>base</tt> section to keep the required
756 disk usage very small.</p>
759 Most of these packages should have the priority value
760 <tt>required</tt> or at least <tt>important</tt>, and many
761 of them will be tagged <tt>essential</tt> (see below).</p>
764 You must not place any packages into the <tt>base</tt>
765 section before this has been discussed on the
766 <tt>debian-devel</tt> mailing list and a consensus about
767 doing that has been reached.</p></sect1>
771 <heading>Essential packages</heading>
774 Some packages are tagged <tt>essential</tt>. (They have
775 <tt>Essential: yes</tt> in their package control record.)
776 This flag is used for packages that are <em>essential</em>
780 Since these packages can not easily be removed (you'll
781 have to specify an extra <em>force option</em> to
782 <prgn>dpkg</prgn>) this flag must only be used where
783 absolutely necessary.
785 A shared library package must not be tagged
786 <em>essential</em>--the dependencies will prevent its
787 premature removal, and we need to be able to remove it
788 when it has been superseded.</p>
791 You must not tag any packages <tt>essential</tt> before
792 this has been discussed on the <tt>debian-devel</tt>
793 mailing and a consensus about doing that has been
798 <heading>Maintainer scripts</heading>
801 The package installation scripts must avoid producing
802 output which it is unnecessary for the user to see and
803 should rely on <prgn>dpkg</prgn> to stave off boredom on
804 the part of a user installing many packages. This means,
805 amongst other things, using the <tt>--quiet</tt> option on
806 <prgn>install-info</prgn>.</p>
809 Packages should try to minimize the amount of prompting
810 they need to do, and they should ensure that the user will
811 only ever be asked each question once. This means that
812 packages should try to use appropriate shared
813 configuration files (such as <tt>/etc/papersize</tt> and
814 <tt>/etc/news/server</tt>), rather than each prompting for
815 their own list of required pieces of information.</p>
818 It also means that an upgrade should not ask the same
819 questions again, unless the user has used <tt>dpkg
820 --purge</tt> to remove the package's configuration. The
821 answers to configuration questions should be stored in an
822 appropriate place in <tt>/etc</tt> so that the user can
823 modify them, and how this has been done should be
827 If a package has a vitally important piece of information
828 to pass to the user (such as "don't run me as I am, you
829 must edit the following configuration files first or you
830 risk your system emitting badly-formatted messages"), it
831 should display this in the <prgn>postinst</prgn> script
832 and prompt the user to hit return to acknowledge the
833 message. Copyright messages do not count as vitally
834 important (they belong in
835 <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
836 do instructions on how to use a program (these should be
837 in on line documentation, where all the users can see
841 Any necessary prompting should almost always be confined
842 to the post-installation script, and should be protected
843 with a conditional so that unnecessary prompting doesn't
844 happen if a package's installation fails and the
845 <prgn>postinst</prgn> is called with
846 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
847 <tt>abort-deconfigure</tt>.</p>
850 Errors which occur during the execution of an installation
851 script <em>must</em> be checked and the installation
852 <em>must not</em> continue after an error.</p>
855 Note, that <ref id="scripts">, in general applies to
856 package maintainer scripts, too.</p>
859 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
860 another package without consulting the maintainer of that
864 In order for <prgn>update-alternatives</prgn> to work
865 correctly all the packages which supply an instance of the
866 `shared' command name (or, in general, filename) must use
867 it. You can use <tt>Conflicts</tt> to force the
868 De-installation of other packages supplying it which do not
869 (yet) use <prgn>update-alternatives</prgn>. It may in
870 this case be appropriate to specify a conflict on earlier
871 versions on something--this is an exception to the usual
872 rule that this is not allowed.</p>
876 <heading>Source packages</heading>
879 <heading>Standards conformance</heading>
882 You should specify the most recent version of the
883 packaging standards with which your package complies in
884 the source package's <tt>Standards-Version</tt> field.</p>
887 This value will be used to file bug reports automatically
888 if your package becomes too much out of date.</p>
891 The value corresponds to a version of the Debian manuals,
892 as can be found on the title page or page headers and
893 footers (depending on the format).</p>
896 The version number has four components--major and minor
897 number and major and minor patch level. When the
898 standards change in a way that requires every package to
899 change the major number will be changed. Significant
900 changes that will require work in many packages will be
901 signaled by a change to the minor number. The major patch
902 level will be changed for any change to the meaning of the
903 standards, however small; the minor patch level will be
904 changed when only cosmetic, typographical or other edits
905 which do not change the meaning are made, or changes which
906 do not affect the contents of packages.</p>
909 For package maintainers, only the first 3 digits of the
910 manual version are significant in representing the
911 <em>Standards-Version</em>, and either these 3 digits or
912 the complete 4 digits can be specified--that's up to the
916 In the past, people specified 4 digits in the
917 Standards-Version field, like `2.3.0.0'. Since any
918 `patch-level changes' don't introduce new policy, it
919 was thought it would be better to relax policy and
920 only require that the first 3 digits are specified. (4
921 digits can still be used if someone wants to do so.)
927 You should regularly, and especially if your package has
928 become out of date, check for the newest Policy Manual
929 available and update your package, if necessary. When your
930 package complies with the new standards you may update the
931 <tt>Standards-Version</tt> source package field and
932 release it.</p></sect1>
936 <heading>Changes to the upstream sources</heading>
939 If changes to the source code are made that are generally
940 applicable please try to get them included in the upstream
941 version of the package by supplying the upstream authors
942 with the changes in whatever form they prefer.</p>
945 If you need to configure the package differently for
946 Debian or for Linux, and the upstream source doesn't
947 provide a way to configure it the way you need to, please
948 add such configuration facilities (for example, a new
949 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
950 the patch to the upstream authors, with the default set to
951 the way they originally had it. You can then easily
952 override the default in your <tt>debian/rules</tt> or
953 wherever is appropriate.</p>
956 Please make sure that the <prgn>configure</prgn> utility
957 detects the correct architecture specification string
958 (refer to <ref id="arch-spec"> for details).</p>
961 If you need to edit a <prgn>Makefile</prgn> where
962 GNU-style <prgn>configure</prgn> scripts are used, you
963 should edit the <tt>.in</tt> files rather than editing the
964 <prgn>Makefile</prgn> directly. This allows the user to
965 reconfigure the package if necessary. You should
966 <em>not</em> configure the package and edit the generated
967 <prgn>Makefile</prgn>! This makes it impossible for
968 someone else to later reconfigure the package.</p></sect1>
972 <heading>Documenting your changes</heading>
975 Document your changes and updates to the source package
976 properly in the <tt>debian/changelog</tt> file.</p>
979 A copy of the file which will be installed in
980 <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
981 in <tt>debian/copyright</tt>.</p>
984 In non-experimental packages you may only use a format for
985 <tt>debian/changelog</tt> which is supported by the most
986 recent released version of <prgn>dpkg</prgn>. If your
987 format is not supported and there is general support for
988 it you should contact the <prgn>dpkg</prgn> maintainer to
989 have the parser script for your format included in the
990 <prgn>dpkg</prgn> package. (You will need to agree that
991 the parser and its manpage may be distributed under the
992 GNU GPL, just as the rest of <prgn>dpkg</prgn>
997 <heading>Error trapping in makefiles</heading>
1000 When <prgn>make</prgn> invokes a command in a makefile
1001 (including your package's upstream makefiles and the
1002 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
1003 means that <tt>sh</tt>'s usual bad error handling
1004 properties apply: if you include a miniature script as one
1005 of the commands in your makefile you'll find that if you
1006 don't do anything about it then errors are not detected
1007 and <prgn>make</prgn> will blithely continue after
1011 Every time you put more than one shell command (this
1012 includes using a loop) in a makefile command you
1013 <em>must</em> make sure that errors are trapped. For
1014 simple compound commands, such as changing directory and
1015 then running a program, using <tt>&&</tt> rather
1016 than semicolon as a command separator is sufficient. For
1017 more complex commands including most loops and
1018 conditionals you must include a separate <tt>set -e</tt>
1019 command at the start of every makefile command that's
1020 actually one of these miniature shell scripts.</p></sect1>
1024 <heading>Obsolete constructs and libraries</heading>
1027 The include file <prgn><varargs.h></prgn> is
1028 provided to support end-users compiling very old software;
1029 the library <tt>libtermcap</tt> is provided to support the
1030 execution of software which has been linked against it
1031 (either old programs or those such as Netscape which are
1032 only available in binary form).</p>
1035 Debian packages should be ported to include
1036 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1041 <chapt><heading>The Operating System</heading>
1045 <heading>File system hierarchy</heading>
1049 <heading>Linux File system Structure</heading>
1052 The location of all installed files and directories must
1053 comply (with some exceptions
1055 <p>In an as yet unreleased version of the standard, the
1056 location of the mail spool and state information
1057 directories has changed; and we propose to follow the
1058 latter, since that would mean that we do not have to
1059 move things around again when the new version of the
1060 FHS comes around). The changes are, amongst others,
1061 s%/var/mail%/var/spool/mail% and
1062 s%/var/state%/var/lib%</p>
1064 ) with the Linux File system Hierarchy Standard
1065 (FHS). The latest version of this document can be found
1066 alongside this manual or on
1067 <ftpsite>tsx-11.mit.edu</ftpsite> in
1068 <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
1069 Specific questions about following the standard may be
1070 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1071 Quinlan, the FHS coordinator, at
1072 <email>quinlan@pathname.com</email>.</p></sect1>
1076 <heading>Site-specific programs</heading>
1079 As mandated by the FHS no package should place any
1080 files in <tt>/usr/local</tt>, either by putting them in
1081 the file system archive to be unpacked by <prgn>dpkg</prgn>
1082 or by manipulating them in their maintainer scripts.</p>
1085 However, the package should create empty directories below
1086 <tt>/usr/local</tt> so that the system administrator knows
1087 where to place site-specific files. These directories
1088 should be removed on package removal if they are
1092 Note, that this applies only to directories <em>below</em>
1093 <tt>/usr/local</tt>, not <em>in</em>
1094 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1095 itself may only contain the sub-directories listed in
1096 FHS, section 4.6. However, you may create directories
1097 below them as you wish. You may not remove any of the
1098 directories listed in 4.6, even if you created them.</p>
1101 Since <tt>/usr/local</tt> may be mounted read-only from a
1102 remote server, these directories have to be created and
1103 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1104 maintainer scripts. These scripts must not fail if either
1105 of these operations fail. (In the future, it will be
1106 possible to tell <prgn>dpkg</prgn> not to unpack files
1107 matching certain patterns, so that the directories can be
1108 included in the <tt>.deb</tt> packages and system
1109 administrators who do not wish these directories in
1110 /usr/local do not need to have them.)</p>
1113 For example, the <prgn>emacs</prgn> package will contain
1115 mkdir -p /usr/local/lib/emacs/site-lisp || true
1117 in the <tt>postinst</tt> script, and
1119 rmdir /usr/local/lib/emacs/site-lisp && \
1120 rmdir /usr/local/lib/emacs || \
1123 in the <tt>prerm</tt> script.</p>
1126 If you do create a directory in <tt>/usr/local</tt> for
1127 local additions to a package, you must ensure that
1128 settings in <tt>/usr/local</tt> take precedence over the
1129 equivalents in <tt>/usr</tt>.</p>
1132 The <tt>/usr/local</tt> directory itself and all the subdirectories
1133 created by the package should have permissions 2775 (group-writable
1134 and set-group-id) and be owned by <tt>root.staff</tt>.</p>
1139 <heading>Users and groups</heading>
1142 The Debian system can be configured to use either plain or
1143 shadow passwords.</p>
1146 Some user ids (UIDs) and group ids (GIDs) are reserved
1147 globally for use by certain packages. Because some packages
1148 need to include files which are owned by these users or
1149 groups, or need the ids compiled into binaries, these ids
1150 must be used on any Debian system only for the purpose for
1151 which they are allocated. This is a serious restriction, and
1152 we should avoid getting in the way of local administration
1153 policies. In particular, many sites allocate users and/or
1154 local system groups starting at 100.</p>
1157 Apart from this we should have dynamically allocated ids,
1158 which should by default be arranged in some sensible
1159 order--but the behavior should be configurable.</p>
1162 No package except <tt>base-passwd</tt> may modify
1163 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1164 <tt>/etc/group</tt>.</p>
1167 The UID and GID ranges are as follows:
1172 Globally allocated by the Debian project, must be the
1173 same on every Debian system. These ids will appear in
1174 the <tt>passwd</tt> and <tt>group</tt> files of all
1175 Debian systems, new ids in this range being added
1176 automatically as the <tt>base-passwd</tt> package is
1180 Packages which need a single statically allocated uid
1181 or gid should use one of these; their maintainers
1182 should ask the <tt>base-passwd</tt> maintainer for
1189 Dynamically allocated system users and groups.
1190 Packages which need a user or group, but can have this
1191 user or group allocated dynamically and differently on
1192 each system, should use `<tt>adduser --system</tt>' to
1193 create the group and/or user. <prgn>adduser</prgn>
1194 will check for the existence of the user or group, and
1195 if necessary choose an unused id based on the ranged
1196 specified in <tt>adduser.conf</tt>.</p></item>
1199 <tag>1000-29999:</tag>
1202 Dynamically allocated user accounts. By default
1203 <prgn>adduser</prgn> will choose UIDs and GIDs for
1204 user accounts in this range, though
1205 <tt>adduser.conf</tt> may be used to modify this
1209 <tag>30000-59999:</tag>
1211 <p>Reserved.</p></item>
1214 <tag>60000-64999:</tag>
1217 Globally allocated by the Debian project, but only
1218 created on demand. The ids are allocated centrally and
1219 statically, but the actual accounts are only created
1220 on users' systems on demand.</p>
1223 These ids are for packages which are obscure or which
1224 require many statically-allocated ids. These packages
1225 should check for and create the accounts in
1226 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1227 <prgn>adduser</prgn> if it has this facility) if
1228 necessary. Packages which are likely to require
1229 further allocations should have a `hole' left after
1230 them in the allocation, to give them room to
1234 <tag>65000-65533:</tag>
1236 <p>Reserved.</p></item>
1241 <p>User `<tt>nobody</tt>.'</p></item>
1247 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1248 because it is the error return sentinel value.</p>
1253 <sect id="sysvinit">
1254 <heading>System run levels</heading>
1258 <heading>Introduction</heading>
1261 The <tt>/etc/init.d</tt> directory contains the scripts
1262 executed by <prgn>init</prgn> at boot time and when init
1263 state (or `runlevel') is changed (see <manref name="init"
1264 section="8">).</p> <p>
1266 These scripts are being referenced by symbolic links in
1267 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1268 changing runlevels, <prgn>init</prgn> looks in the
1269 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1270 it should execute, where <var>n</var> is the runlevel that
1271 is being changed to, or `S' for the boot-up scripts.</p>
1274 The names of the links all have the form
1275 <tt>S<var>mm</var><var>script</var></tt> or
1276 <tt>K<var>mm</var><var>script</var></tt> where
1277 <var>mm</var> is a two-digit number and <var>script</var>
1278 is the name of the script (this should be the same as the
1279 name of the actual script in <tt>/etc/init.d</tt>.
1281 When <prgn>init</prgn> changes runlevel first the targets
1282 of the links whose names starting with a <tt>K</tt> are
1283 executed, each with the single argument <tt>stop</tt>,
1284 followed by the scripts prefixed with an <tt>S</tt>, each
1285 with the single argument <tt>start</tt>. The <tt>K</tt>
1286 links are responsible for killing services and the
1287 <tt>S</tt> link for starting services upon entering the
1291 For example, if we are changing from runlevel 2 to
1292 runlevel 3, init will first execute all of the <tt>K</tt>
1293 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1294 all of the <tt>S</tt> prefixed scripts. The links
1295 starting with <tt>K</tt> will cause the referred-to file
1296 to be executed with an argument of <tt>stop</tt>, and the
1297 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1300 The two-digit number <var>mm</var> is used to decide which
1301 order to start and stop things in--low-numbered links have
1302 their scripts run first. For example, the <tt>K20</tt>
1303 scripts will be executed before the <tt>K30</tt> scripts.
1304 This is used when a certain service must be started before
1305 another. For example, the name server <prgn>bind</prgn>
1306 might need to be started before the news server
1307 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1308 access lists. In this case, the script that starts
1309 <prgn>bind</prgn> should have a lower number than the
1310 script that starts <prgn>inn</prgn> so that it runs first:
1319 <heading>Writing the scripts</heading>
1322 Packages can and should place scripts in
1323 <tt>/etc/init.d</tt> to start or stop services at boot
1324 time or during a change of runlevel. These scripts should
1325 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1326 should accept one argument, saying what to do:
1329 <tag><tt>start</tt></tag>
1330 <item><p>start the service,</p></item>
1332 <tag><tt>stop</tt></tag>
1333 <item><p>stop the service,</p></item>
1335 <tag><tt>restart</tt></tag>
1336 <item><p>stop and restart the service,</p></item>
1338 <tag><tt>reload</tt></tag>
1339 <item><p>cause the configuration of the service to be
1340 reloaded without actually stopping and restarting
1341 the service,</p></item>
1343 <tag><tt>force-reload</tt></tag> <item><p>cause the
1344 configuration to be reloaded if the service supports
1345 this, otherwise restart the service.</p></item>
1348 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1349 <tt>force-reload</tt> options must be supported by all
1350 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1351 option is optional.</p>
1354 The <tt>init.d</tt> scripts should ensure that they will
1355 behave sensibly if invoked with <tt>start</tt> when the
1356 service is already running, or with <tt>stop</tt> when it
1357 isn't, and that they don't kill unfortunately-named user
1358 processes. The best way to achieve this is usually to use
1359 <prgn>start-stop-daemon</prgn>.</p>
1362 If a service reloads its configuration automatically (as
1363 in the case of <prgn>cron</prgn>, for example), the
1364 <tt>reload</tt> option of the <tt>init.d</tt> script
1365 should behave as if the configuration has been reloaded
1369 These scripts should not fail obscurely when the
1370 configuration files remain but the package has been
1371 removed, as the default in <prgn>dpkg</prgn> is to leave
1372 configuration files on the system after the package has
1373 been removed. Only when it is executed with the
1374 <tt>--purge</tt> option will dpkg remove configuration
1375 files. Therefore, you should include a <tt>test</tt>
1376 statement at the top of the script, like this:
1378 test -f <var>program-executed-later-in-script</var> || exit 0
1379 </example></p></sect1>
1382 <heading>Managing the links</heading>
1385 A program is provided, <prgn>update-rc.d</prgn>, to make
1386 it easier for package maintainers to arrange for the
1387 proper creation and removal of
1388 <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
1389 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1392 You should use this script to make changes to
1393 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
1394 any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
1398 By default <prgn>update-rc.d</prgn> will start services in
1399 each of the multi-user state runlevels (2, 3, 4, and 5)
1400 and stop them in the halt runlevel (0), the single-user
1401 runlevel (1) and the reboot runlevel (6). The system
1402 administrator will have the opportunity to customize
1403 runlevels by simply adding, moving, or removing the
1404 symbolic links in <tt>/etc/rc<var>n</var>.d</tt>.</p>
1407 To get the default behavior for your package, put in your
1408 <tt>postinst</tt> script
1410 update-rc.d <var>package</var> defaults >/dev/null
1412 and in your <tt>postrm</tt>
1414 if [ purge = "$1" ]; then
1415 update-rc.d <var>package</var> remove >/dev/null
1420 This will use a default sequence number of 20. If it does
1421 not matter when or in which order the script is run, use
1422 this default. If it does, then you should talk to the
1423 maintainer of the <prgn>sysvinit</prgn> package or post to
1424 <tt>debian-devel</tt>, and they will help you choose a
1428 For more information about using <tt>update-rc.d</tt>,
1429 please consult its manpage <manref name="update-rc.d"
1430 section="8">.</p></sect1>
1434 <heading>Boot-time initialization</heading>
1437 There is another directory, <tt>/etc/rc.boot</tt>, which
1438 contains scripts which are run once per machine boot.
1439 This facility is provided for initialization of hardware
1440 devices, cleaning up of leftover files, and so forth.</p>
1443 For example, the <prgn>kbd</prgn> package provides a
1444 script here for initializing the keyboard layout and
1445 console font and mode.</p>
1448 The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
1449 links into <tt>/etc/init.d</tt>--they should be the
1450 scripts themselves.</p>
1453 <tt>rc.boot</tt> should <em>not</em> be used for starting
1454 general-purpose daemons and similar activities. This
1455 should be done using the <tt>rc<var>n</var>.d</tt> scheme,
1456 above, so that the services can be started and stopped
1457 cleanly when the runlevel changes or the machine is to be
1458 shut down or rebooted.</p></sect1>
1462 <heading>Notes</heading>
1465 <em>Do not</em> include the
1466 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1467 <tt>.deb</tt> file system archive! <em>This will cause
1468 problems!</em> You should create them with
1469 <prgn>update-rc.d</prgn>, as above.</p>
1472 <em>Do not</em> include the <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1473 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1474 problems!</em> <em>Do</em>,
1475 however, include the <tt>/etc/init.d</tt> scripts in
1476 conffiles. (This is important since we want to give the
1477 local system administrator the chance to adapt the scripts
1478 to the local system--e.g., to disable a service without
1479 De-installing the package, or to specify some special
1480 command line options when starting a service--while making
1481 sure her changes aren't lost during the next package
1482 upgrade.)</p></sect1>
1485 <heading>Example</heading>
1488 The <prgn>bind</prgn> DNS (nameserver) package wants to
1489 make sure that the nameserver is running in multiuser
1490 runlevels, and is properly shut down with the system. It
1491 puts a script in <tt>/etc/init.d</tt>, naming the script
1492 appropriately <tt>bind</tt>. As you can see, the script
1493 interprets the argument <tt>reload</tt> to send the
1494 nameserver a <tt>HUP</tt> signal (causing it to reload its
1495 configuration); this way the user can say
1496 <tt>/etc/init.d/bind reload</tt> to reload the name
1503 # Original version by Robert Leslie
1504 # <rob@mars.org>, edited by iwj and cs
1506 test -x /usr/sbin/named || exit 0
1510 echo -n "Starting domain name service: named"
1511 start-stop-daemon --start --quiet --exec /usr/sbin/named
1515 echo -n "Stopping domain name service: named"
1516 start-stop-daemon --stop --quiet \
1517 --pidfile /var/run/named.pid --exec /usr/sbin/named
1521 echo -n "Restarting domain name service: named"
1522 start-stop-daemon --stop --quiet \
1523 --pidfile /var/run/named.pid --exec /usr/sbin/named
1524 start-stop-daemon --start --verbose --exec /usr/sbin/named
1527 force-reload|reload)
1528 echo -n "Reloading configuration of domain name service: named"
1529 start-stop-daemon --stop --signal 1 --quiet \
1530 --pidfile /var/run/named.pid --exec /usr/sbin/named
1534 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1543 Another example on which to base your <tt>/etc/init.d</tt>
1544 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1547 If this package is happy with the default setup from
1548 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1549 and having named running in all runlevels, it can say in
1550 its <tt>postinst</tt>:
1552 update-rc.d bind defaults >/dev/null
1554 And in its <tt>postrm</tt>, to remove the links when the
1557 if [ purge = "$1" ]; then
1558 update-rc.d acct remove >/dev/null
1564 <heading>Cron jobs</heading>
1567 Packages may not touch the configuration file
1568 <tt>/etc/crontab</tt>, nor may they modify the files in
1569 <tt>/var/spool/cron/crontabs</tt>.</p>
1572 If a package wants to install a job that has to be executed
1573 via cron, it should place a file with the name if the
1574 package in one of the following directories:
1580 As these directory names say, the files within them are executed on
1581 a daily, weekly, or monthly basis, respectively.</p>
1584 If a certain job has to be executed more frequently than
1585 `daily,' the package should install a file
1586 <tt>/etc/cron.d/<package-name></tt> tagged as
1587 configuration file. This file uses the same syntax as
1588 <tt>/etc/crontab</tt> and is processed by <prgn>cron</prgn>
1589 automatically. (Note, that scripts in the
1590 <tt>/etc/cron.d</tt> directory are not handled by
1591 <prgn>anacron</prgn>. Thus, you should only use this
1592 directory for jobs which may be skipped if the system is not
1596 All files installed in any of these directories have to be
1597 scripts (shell scripts, Perl scripts, etc.) so that they can
1598 easily be modified by the local system administrator. In
1599 addition, they have to be registered as configuration
1603 The scripts in these directories have to check, if all
1604 necessary programs are installed before they try to execute
1605 them. Otherwise, problems will arise when a package was
1606 removed (but not purged), since the configuration files are
1607 kept on the system in this situation.</p></sect>
1611 <heading>Console messages</heading>
1614 This section describes different formats for messages
1615 written to standard output by the <tt>/etc/init.d</tt>
1616 scripts. The intent is to improve the consistency of
1617 Debian's startup and shutdown look and feel.</p>
1620 Please look very careful at the details. We want to get the
1621 messages to look exactly the same way concerning spaces,
1622 punctuation, and case of letters.</p>
1625 Here is a list of overall rules that you should use when you
1626 create output messages. They can be useful if you have a
1627 non-standard message that isn't covered in the sections
1634 Every message should cover one line, start with a
1635 capital letter and end with a period `.'.</p></item>
1640 If you want to express that the computer is working on
1641 something (performing a specific task, not starting or
1642 stopping a program), we use an ``ellipsis'', namely
1643 three dots `...'. Note that we don't insert spaces in
1644 front of or behind the dots. If the task has been
1645 completed we write `done.' and a line feed.</p></item>
1650 Design your messages as if the computer is telling you
1651 what he is doing (let him be polite :-) but don't
1652 mention ``him'' directly. For example, if you think
1655 I'm starting network daemons: nfsd mountd.
1659 Starting network daemons: nfsd mountd.
1660 </example></p></item>
1664 The following formats must be used</p>
1669 <p>when daemons get started.</p>
1672 Use this format if your script starts one or more
1673 daemons. The output should look like this (a single
1674 line, no leading spaces):
1676 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1678 The <description> should describe the subsystem
1679 the daemon or set of daemons are part of, while
1680 <daemon-1> up to <daemon-n> denote each
1681 daemon's name (typically the file name of the
1685 For example, the output of /etc/init.d/lpd would look like:
1687 Starting printer spooler: lpd.
1691 This can be achieved by saying
1693 echo -n "Starting printer spooler: lpd"
1694 start-stop-daemon --start --quiet lpd
1697 in the script. If you have more than one daemon to
1698 start, you should do the following:
1700 echo -n "Starting remote file system services:"
1701 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1702 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1703 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1706 This makes it possible for the user to see what takes
1707 so long and when the final daemon has been
1708 started. Please be careful where to put spaces: In the
1709 example above the system administrator can easily
1710 comment out a line if he don't wants to start a
1711 specific daemon, while the displayed message still
1712 looks good.</p></item>
1716 <p>when something needs to be configured.</p>
1719 If you have to set up different parameters of the
1720 system upon boot up, you can use this format:
1722 Setting <parameter> to `<value>'.
1726 You can use the following echo statement to get the quotes right:
1728 echo "Setting DNS domainname to \`"value"'."
1732 Note that the left quotation mark (`) is different
1733 from the right (').</p></item>
1736 <p>when a daemon is stopped.</p>
1739 When you stop a daemon you should issue a message
1740 similar to the startup message, except that `Starting'
1741 is replaced with `Stopping'.</p>
1744 So stopping the printer daemon will like like this:
1746 Stopping printer spooler: lpd.
1747 </example></p></item>
1750 <p>when something is executed.</p>
1753 There a several examples where you have to run a
1754 program at system startup or shutdown to perform a
1755 specific task. For example, setting the system's clock
1756 via `netdate' or killing all processes when the system
1757 comes down. Your message should like this:
1759 Doing something very useful...done.
1761 You should print the `done.' right after the job has been completed,
1762 so that the user gets informed why he has to wait. You can get this
1765 echo -n "Doing something very useful..."
1769 in your script.</p></item>
1772 <p>when the configuration is reloaded.</p>
1775 When a daemon is forced to reload its configuration
1776 files you should use the following format:
1778 Reloading <daemon's-name> configuration...done.
1779 </example></p></item>
1782 <p>when none of the above rules apply.</p>
1785 If you have to print a message that doesn't fit into
1786 the styles described above, you can use something
1787 appropriate, but please have a look at the overall
1788 rules listed above.</p></item>
1793 <heading>Menus</heading>
1796 Menu entries should follow the current menu policy as
1797 defined in the file <ftpsite>ftp.debian.org</ftpsite> in
1798 <ftppath>/debian/doc/package-developer/menu_policy.txt</ftppath>
1799 or your local mirror.
1803 The Debian <tt>menu</tt> packages provides a unique
1804 interface between packages providing applications and
1805 documents, and <em>menu programs</em> (either X window
1806 managers or text-based menu programs as
1807 <prgn>pdmenu</prgn>).</p>
1810 All packages that provide applications that need not be
1811 passed any special command line arguments for normal
1812 operation should register a menu entry for those
1813 applications, so that users of the <tt>menu</tt> package
1814 will automatically get menu entries in their window
1815 managers, as well in shells like <tt>pdmenu</tt>.</p>
1818 Please refer to the <em>Debian Menu System</em> document
1819 that comes with the <tt>menu</tt> package for information
1820 about how to register your applications and web
1821 documents.</p></sect>
1825 <heading>Keyboard configuration</heading>
1828 To achieve a consistent keyboard configuration (i.e., all
1829 applications interpret a keyboard event the same way) all
1830 programs in the Debian distribution have to be configured to
1831 comply with the following guidelines.</p>
1834 Here is a list that contains certain keys and their interpretation:
1837 <tag><tt><--</tt></tag>
1838 <item><p>delete the character to the left of the cursor</p></item>
1840 <tag><tt>Delete</tt></tag>
1841 <item><p>delete the character to the right of the cursor</p></item>
1843 <tag><tt>Control+H</tt></tag>
1844 <item><p>emacs: the help prefix</p></item>
1847 The interpretation of any keyboard events should be independent
1848 of the terminal that's used, be it a virtual console, an X
1849 terminal emulator, an rlogin/telnet session, etc.</p>
1852 The following list explains how the different programs
1853 should be set up to achieve this:</p>
1856 <list compact="compact">
1857 <item><p>`<tt><--</tt>' generates KB_Backspace in
1860 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1864 X translations are set up to make KB_Backspace
1865 generate ASCII DEL, and to make KB_Delete generate
1866 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1867 the `delete character' key). This must be done by
1868 loading the resources using xrdb on all local X
1869 displays, not using the application defaults, so that
1870 the translation resources used correspond to the
1871 xmodmap settings.</p></item>
1875 The Linux console is configured to make
1876 `<tt><--</tt>' generate DEL, and `Delete' generate
1877 <tt>ESC [ 3 ~</tt> (this is the case at the
1881 X applications are configured so that Backspace
1882 deletes left, and Delete deletes right. Motif
1883 applications already work like this.</p></item>
1885 <item><p>stty erase <tt>^?</tt> .</p></item>
1888 The `xterm' terminfo entry should have <tt>ESC [ 3
1889 ~</tt> for kdch1, just like TERM=linux and
1890 TERM=vt220.</p></item>
1893 Emacs is programmed to map KB_Backspace or the `stty
1894 erase' character to delete-backward-char, and
1895 KB_Delete or kdch1 to delete-forward-char, and
1896 <tt>^H</tt> to help as always.</p></item>
1899 Other applications use the `stty erase' character and
1900 kdch1 for the two delete keys, with ASCII DEL being
1901 `delete previous character' and kdch1 being `delete
1902 character under cursor'.</p></item>
1906 This will solve the problem except for:</p>
1909 <list compact="compact">
1911 Some terminals have a <tt><--</tt> key that cannot
1912 be made to produce anything except <tt>^H</tt>. On
1913 these terminals Emacs help will be unavailable on
1914 <tt>^H</tt> (assuming that the `stty erase' character
1915 takes precedence in Emacs, and has been set
1916 correctly). M-x help or F1 (if available) can be used
1920 Some operating systems use <tt>^H</tt> for stty erase.
1921 However, modern telnet versions and all rlogin
1922 versions propagate stty settings, and almost all UNIX
1923 versions honour stty erase. Where the stty settings
1924 are not propagated correctly things can be made to
1925 work by using stty manually.</p></item>
1928 Some systems (including previous Debian versions) use
1929 xmodmap to arrange for both <tt><--</tt> and Delete
1930 to generate KB_Delete). We can change the behavior
1931 of their X clients via the same X resources that we
1932 use to do it for our own, or have our clients be
1933 configured via their resources when things are the
1934 other way around. On displays configured like this
1935 Delete will not work, but <tt><--</tt>
1939 Some operating systems have different kdch1 settings
1940 in their terminfo for xterm and others. On these
1941 systems the Delete key will not work correctly when
1942 you log in from a system conforming to our policy, but
1943 <tt><--</tt> will.</p></item>
1950 <heading>Environment variables</heading>
1953 No program may depend on environment variables to get
1954 reasonable defaults. (That's because these environment
1955 variables would have to be set in a system-wide
1956 configuration file like /etc/profile, which is not supported
1960 If a program should depend on environment variables for its
1961 configuration, the program has to be changed to fall back to
1962 a reasonable default configuration if these environment
1963 variables are not present. If this cannot be done easily
1964 (e.g., if the source code of a non-free program is not
1965 available), the program should be replaced by a small
1966 `wrapper' shell script which sets the environment variables
1967 and calls the original program.</p>
1970 Here is an example of a wrapper script for this purpose:
1976 exec /usr/lib/foo/foo "$@"
1980 Furthermore, as <tt>/etc/profile</tt> is a configuration
1981 file of the <prgn>bash</prgn> package, no other package may
1982 put any environment variables or other commands into that
1987 <heading>Files</heading>
1991 <heading>Binaries</heading>
1994 It is not allowed that two packages install programs with
1995 different functionality but with the same filenames. (The
1996 case of two programs having the same functionality but
1997 different implementations is handled via `alternatives.')
1998 If this case happens, one of the programs has to be
1999 renamed. The maintainers should report this to the
2000 developers' mailing and try to find a consensus about
2001 which package will have to be renamed. If a consensus can
2002 not be reached, <em>both</em> programs must be
2006 Generally the following compilation parameters should be used:
2009 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
2011 install -s # (or use strip on the files in debian/tmp)
2015 Note that all installed binaries should be stripped,
2016 either by using the <tt>-s</tt> flag to
2017 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
2018 the binaries after they have been copied into
2019 <tt>debian/tmp</tt> but before the tree is made into a
2023 The <tt>-g</tt> flag is useful on compilation so that you
2024 have available a full set of debugging symbols in your
2025 built source tree, in case anyone should file a bug report
2026 involving (for example) a core dump.</p>
2029 The <tt>-N</tt> flag should not be used. On a.out systems
2030 it may have been useful for some very small binaries, but
2031 for ELF it has no good effect.</p>
2034 It is up to the package maintainer to decide what
2035 compilation options are best for the package. Certain
2036 binaries (such as computationally-intensive programs) may
2037 function better with certain flags (<tt>-O3</tt>, for
2038 example); feel free to use them. Please use good judgment
2039 here. Don't use flags for the sake of it; only use them
2040 if there is good reason to do so. Feel free to override
2041 the upstream author's ideas about which compilation
2042 options are best--they are often inappropriate for our
2043 environment.</p></sect>
2047 <heading>Libraries</heading>
2050 All libraries must have a shared version in the lib
2051 package and a static version in the lib-dev package. The
2052 shared version must be compiled with <tt>-fPIC</tt>, and
2053 the static version must not be. In other words, each
2054 <tt>*.c</tt> file is compiled twice.</p>
2057 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2058 when building a library (either static or shared) to make
2059 the library compatible with LinuxThreads.</p>
2062 Note that all installed shared libraries should be
2065 strip --strip-unneeded <your-lib>
2067 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2068 only the symbols which aren't needed for relocation
2069 processing.) Shared libraries can function perfectly well
2070 when stripped, since the symbols for dynamic linking are
2071 in a separate part of the ELF object file.</p>
2074 Note that under some circumstances it may be useful to
2075 install a shared library unstripped, for example when
2076 building a separate package to support debugging.
2080 An ever increasing number of packages are using libtool to
2081 do their linking. The latest GNU libtools (>= 1.3a) can take
2082 advantage of the nmetadata in the installed libtool archive
2083 files (`*.la'). The main advantage of libtool's .la files is
2084 that it allows libtool to store and subsequently access
2085 metadata with respect to the libraries it builds. libtool
2086 will search for those files, which contain a lot of useful
2087 information about a library (e.g. dependency libraries for
2088 static linking). Also, they're <em>essential</em> for
2089 programs using libltdl.
2093 Certainly libtool is fully capable of linking against shared
2094 libraries which don't have .la files, but being a mere shell
2095 script it can add considerably to the build time of a
2096 libtool using package if that shell-script has to derive all
2097 this information from first principles for each library every
2098 time it is linked. With the advent of libtool-1.4 (and to a
2099 lesser extent libtool-1.3), the .la files will also store
2100 information about inter-library dependencies which cannot
2101 necessarily be derived after the .la file is deleted.
2105 Packages that use libtool to create shared libraries must
2106 include the <em>.la</em> files in the <em>-dev</em>
2107 packages, with the exception that if the package relies on
2108 libtool's <em>libltdl</em> library, in which case the .la
2109 files must go in the run-time library package. This is a
2110 good idea in general, and especially for static linking
2115 Please make sure that you use only released versions of
2116 shared libraries to build your packages; otherwise other
2117 users will not be able to run your binaries
2118 properly. Producing source packages that depend on
2119 unreleased compilers is also usually a bad
2126 <heading>Shared libraries</heading>
2129 Packages involving shared libraries should be split up
2130 into several binary packages.</p>
2133 For a straightforward library which has a development
2134 environment and a runtime kit including just shared
2135 libraries you need to create two packages:
2136 <tt><var>libraryname</var><var>soname</var></tt>
2137 (<var>soname</var> is the shared object name of the shared
2138 library--it's the thing that has to match exactly between
2139 building an executable and running it for the dynamic
2140 linker to be able run the program; usually the
2141 <var>soname</var> is the major number of the library) and
2142 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2145 If you prefer only to support one development version at a
2146 time you may name the development package
2147 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2148 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2149 ensure that the user only installs one development version
2150 at a time (after all, different development versions are
2151 likely to have the same header files in them, causing a
2152 filename clash if both are installed). Typically the
2153 development version will also need an exact version
2154 dependency on the runtime library, to make sure that
2155 compilation and linking happens correctly.</p>
2158 Packages which use the shared library should have a
2159 dependency on the name of the shared library package,
2160 <tt><var>libraryname</var><var>soname</var></tt>. When
2161 the <var>soname</var> changes you can have both versions
2162 of the library installed while moving from the old library
2166 If your package has some run-time support programs which
2167 use the shared library you must <em>not</em> put them in
2168 the shared library package. If you do that then you won't
2169 be able to install several versions of the shared library
2170 without getting filename clashes. Instead, either create
2171 a third package for the runtime binaries (this package
2172 might typically be named
2173 <tt><var>libraryname</var>-runtime</tt>--note the absence
2174 of the <var>soname</var> in the package name) or if the
2175 development package is small include them in there.</p>
2178 If you have several shared libraries built from the same
2179 source tree you can lump them all together into a single
2180 shared library package, provided that you change all their
2181 <var>soname</var>s at once (so that you don't get filename
2182 clashes if you try to install different versions of the
2183 combined shared libraries package).</p>
2186 Follow the directions in the <em>Debian Packaging
2187 Manual</em> for putting the shared library in its package,
2188 and make sure you include a <tt>shlibs</tt> control area
2189 file with details of the dependencies for packages which
2190 use the library.</p>
2193 Shared libraries should <em>not</em> be installed
2194 executable, since <prgn>ld.so</prgn> does not require this
2195 and trying to execute a shared library results in a core
2200 <heading>Scripts</heading>
2203 All command scripts, including the package maintainer
2204 scripts inside the package and used by <prgn>dpkg</prgn>,
2205 should have a <tt>#!</tt> line naming the shell to be used
2206 to interpret them.</p>
2209 In the case of Perl scripts this should be
2210 <tt>#!/usr/bin/perl</tt>.</p>
2213 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2214 should almost certainly start with <tt>set -e</tt> so that
2215 errors are detected. Every script <em>must</em> use
2216 <tt>set -e</tt> or check the exit status of <em>every</em>
2220 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2221 symbolic link to any POSIX compatible shell. Thus, shell
2222 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2223 only use POSIX features. If a script requires non-POSIX
2224 features from the shell interpreter, the appropriate shell
2225 has to be specified in the first line of the script (e.g.,
2226 `<tt>#!/bin/bash</tt>') and the package has to depend on
2227 the package providing the shell (unless the shell package
2228 is marked `Essential', e.g., in the case of
2229 <prgn>bash</prgn>).</p>
2232 Restrict your script to POSIX features when possible so
2233 that it may use <tt>/bin/sh</tt> as its interpreter. If
2234 your script works with <prgn>ash</prgn>, it's probably
2235 POSIX compliant, but if you are in doubt, use
2236 <tt>/bin/bash</tt>.</p>
2239 Perl scripts should check for errors when making any
2240 system calls, including <tt>open</tt>, <tt>print</tt>,
2241 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2244 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2245 as scripting languages. See <em>Csh Programming
2246 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2247 FAQs. It can be found on
2248 <url id="http://language.perl.com/versus/csh.whynot">, or
2249 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2250 or even on <ftpsite>ftp.cpan.org</ftpsite>
2251 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2252 If an upstream package comes with <prgn>csh</prgn> scripts
2253 then you must make sure that they start with
2254 <tt>#!/bin/csh</tt> and make your package depend on the
2255 <prgn>c-shell</prgn> virtual package.</p>
2258 Any scripts which create files in world-writable
2259 directories (e.g., in <tt>/tmp</tt>) have to use a
2260 mechanism which will fail if a file with the same name
2264 The Debian base distribution provides the
2265 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2266 for use by scripts for this purpose.</p></sect>
2270 <heading>Symbolic links</heading>
2273 In general, symbolic links within a top-level directory
2274 should be relative, and symbolic links pointing from one
2275 top-level directory into another should be absolute. (A
2276 top-level directory is a sub-directory of the root
2280 In addition, symbolic links should be specified as short
2281 as possible, i.e., link targets like `foo/../bar' are
2285 Note that when creating a relative link using
2286 <prgn>ln</prgn> it is not necessary for the target of the
2287 link to exist relative to the working directory you're
2288 running <prgn>ln</prgn> from; nor is it necessary to
2289 change directory to the directory where the link is to be
2290 made. Simply include the string that should appear as the
2291 target of the link (this will be a pathname relative to
2292 the directory in which the link resides) as the first
2293 argument to <prgn>ln</prgn>.</p>
2296 For example, in your <prgn>Makefile</prgn> or
2297 <tt>debian/rules</tt>, do things like:
2299 ln -fs gcc $(prefix)/bin/cc
2300 ln -fs gcc debian/tmp/usr/bin/cc
2301 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2302 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2306 A symbolic link pointing to a compressed file should
2307 always have the same file extension as the referenced
2308 file. (For example, if a file `<tt>foo.gz</tt>' is
2309 referenced by a symbolic link, the filename of the link
2310 has to end with `<tt>.gz</tt>' too, as in
2311 `bar.gz.')</p></sect>
2315 <heading>Device files</heading>
2318 No package may include device files in the package file
2322 If a package needs any special device files that are not
2323 included in the base system, it has to call
2324 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2325 after asking the user for permission to do so.</p>
2328 No package should remove any device files in the
2329 <tt>postrm</tt> or any other script. This is left to the
2330 system administrator.</p>
2333 Debian uses the serial devices
2334 <tt>/dev/tty*</tt>. Programs using the old
2335 <tt>/dev/cu*</tt> devices should be changed to use
2336 <tt>/dev/tty*</tt>.</p></sect>
2340 <heading>Configuration files</heading>
2343 Any configuration files created or used by your package
2344 should reside in <tt>/etc</tt>. If there are several you
2345 should consider creating a subdirectory named after your
2349 It is almost certain that any file in <tt>/etc</tt> that
2350 is in your package's file system archive should be listed
2351 in <prgn>dpkg</prgn>'s <tt>conffiles</tt> control area
2352 file. (See the <em>Debian Packaging
2356 Only packages that are tagged <em>conflicting</em> with
2357 each other may specify the same file as
2358 <tt>conffile</tt>. A package may not modify a
2359 configuration file of another package.</p>
2362 If two or more packages use the same configuration file,
2363 one of these packages has to be defined as <em>owner</em>
2364 of the configuration file, i.e., it has to list the file
2365 as <tt>conffile</tt> and has to provide a program that
2366 modifies the configuration file.</p>
2369 The other packages have to depend on the <em>owner</em>
2370 package and use that program to update the configuration
2374 Sometimes it's appropriate to build a new package, which
2375 just provides the basic <em>infrastructure</em> for the
2376 other packages and which manages the shared configuration
2377 files. (Check out the <prgn>sgml-base</prgn> package as an
2381 Files in <tt>/etc/skel</tt> will automatically be copied
2382 into new user accounts by <prgn>adduser</prgn>. They
2383 should not be referenced there by any program.</p>
2386 Therefore, if a program needs a dotfile to exist in
2387 advance in <tt>$HOME</tt> to work sensibly that dotfile
2388 should be installed in <tt>/etc/skel</tt> (and listed in
2389 conffiles, if it is not generated and modified dynamically
2390 by the package's installation scripts).</p>
2393 However, programs that require dotfiles in order to
2394 operate sensibly (dotfiles that they do not create
2395 themselves automatically, that is) are a bad thing, and
2396 programs should be configured by the Debian default
2397 installation as close to normal as possible.</p>
2400 Therefore, if a program in a Debian package needs to be
2401 configured in some way in order to operate sensibly that
2402 configuration should be done in a site-wide global
2403 configuration file elsewhere in <tt>/etc</tt>. Only if
2404 the program doesn't support a site-wide default
2405 configuration and the package maintainer doesn't have time
2406 to add it should a default per-user file be placed in
2407 <tt>/etc/skel</tt>.</p>
2410 <tt>/etc/skel</tt> should be as empty as we can make it.
2411 This is particularly true because there is no easy
2412 mechanism for ensuring that the appropriate dotfiles are
2413 copied into the accounts of existing users when a package
2417 Ideally the sysadmin should not have to do any
2418 configuration other than that done (semi-)automatically by
2419 the <tt>postinst</tt> script.</p>
2423 <heading>Log files</heading>
2425 The traditional approach to log files has been to set up ad
2426 hoc log rotation schemes using simple shell scripts and
2427 cron. While this approach is highly customizable, it
2428 requires quite a lot of sysadmin work. Even though the
2429 original Debian system helped a little by automatically
2430 installing a system which can be used as a template, this
2431 was deemed not enough.
2435 A better scheme is to use logrotate, a GPL'd program
2436 developed by Red Hat, which centralizes log management. It
2437 has both a config file (<tt>/etc/logrotate.conf</tt>) and a
2438 directory where packages can drop logrotation info
2439 (<tt>/etc/logrotate.d</tt>).
2443 Log files should usually be named
2444 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2445 log files, or need a separate directory for permissions
2446 reasons (<tt>/var/log</tt> is writable only by
2447 <tt>root</tt>), you should usually create a directory named
2448 <tt>/var/log/<var>package</var></tt>.</p>
2451 Make sure that any log files are rotated occasionally so
2452 that they don't grow indefinitely; the best way to do this
2453 is to drop a script into the directory
2454 <tt>/etc/logrotate.d</tt> and use the facilities provided by
2455 logrotate. Here is a good example for a logrotate config
2456 file (for more information see <manref name="logrotate"
2464 /etc/init.d/foo force-reload
2468 Which rotates all files under `/var/log/foo', saves 12
2469 compressed generations, and sends a HUP signal at the end of
2475 Make sure that any log files are removed when the package is
2476 purged (but not when it is only removed), by checking the
2477 argument to the <tt>postrm</tt> script (see the <em>Debian
2478 Packaging Manual</em> for details).</p>
2483 <heading>Permissions and owners</heading>
2486 The rules in this section are guidelines for general use.
2487 If necessary you may deviate from the details below.
2488 However, if you do so you must make sure that what is done
2489 is secure and you must try to be as consistent as possible
2490 with the rest of the system. You should probably also
2491 discuss it on <prgn>debian-devel</prgn> first.</p>
2494 Files should be owned by <tt>root.root</tt>, and made
2495 writable only by the owner and universally readable (and
2496 executable, if appropriate).</p>
2499 Directories should be mode 755 or (for group-writability)
2500 mode 2775. The ownership of the directory should be
2501 consistent with its mode--if a directory is mode 2775, it
2502 should be owned by the group that needs write access to
2506 Setuid and setgid executables should be mode 4755 or 2755
2507 respectively, and owned by the appropriate user or group.
2508 They should not be made unreadable (modes like 4711 or
2509 2711 or even 4111); doing so achieves no extra security,
2510 because anyone can find the binary in the freely available
2511 Debian package--it is merely inconvenient. For the same
2512 reason you should not restrict read or execute permissions
2513 on non-set-id executables.</p>
2516 Some setuid programs need to be restricted to particular
2517 sets of users, using file permissions. In this case they
2518 should be owned by the uid to which they are set-id, and
2519 by the group which should be allowed to execute them.
2520 They should have mode 4754; there is no point in making
2521 them unreadable to those users who must not be allowed to
2525 Do not arrange that the system administrator can only
2526 reconfigure the package to correspond to their local
2527 security policy by changing the permissions on a binary.
2528 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2529 to conffiles and other similar objects) have their
2530 permissions reset to the distributed permissions when the
2531 package is reinstalled. Instead you should consider (for
2532 example) creating a group for people allowed to use the
2533 program(s) and making any setuid executables executable
2534 only by that group.</p>
2537 If you need to create a new user or group for your package
2538 there are two possibilities. Firstly, you may need to
2539 make some files in the binary package be owned by this
2540 user or group, or you may need to compile the user or
2541 group id (rather than just the name) into the binary
2542 (though this latter should be avoided if possible). In
2543 this case you need a statically allocated id.</p>
2546 You must ask for a user or group id from the base system
2547 maintainer, and must not release the package until you
2548 have been allocated one. Once you have been allocated one
2549 you must make the package depend on a version of the base
2550 system with the id present in <tt>/etc/passwd</tt> or
2551 <tt>/etc/group</tt>, or alternatively arrange for your
2552 package to create the user or group itself with the
2553 correct id (using <tt>adduser</tt>) in its pre- or
2554 post-installation script (the latter is to be preferred if
2555 it is possible).</p>
2558 On the other hand, the program may able to determine the
2559 uid or gid from the group name at runtime, so that a
2560 dynamic id can be used. In this case you must choose an
2561 appropriate user or group name, discussing this on
2562 <prgn>debian-devel</prgn> and checking with the base
2563 system maintainer that it is unique and that they do not
2564 wish you to use a statically allocated id instead. When
2565 this has been checked you must arrange for your package to
2566 create the user or group if necessary using
2567 <prgn>adduser</prgn> in the pre- or post-installation
2568 script (again, the latter is to be preferred if it is
2572 Note that changing the numeric value of an id associated with a name
2573 is very difficult, and involves searching the file system for all
2574 appropriate files. You need to think carefully whether a static or
2575 dynamic id is required, since changing your mind later will cause
2581 <heading>Customized programs</heading>
2583 <sect id="arch-spec">
2584 <heading>Architecture specification strings</heading>
2587 If a program needs to specify an <em>architecture specification
2588 string</em> in some place, the following format has to be used:
2590 <arch>-<os>
2592 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2593 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2594 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2595 operating system. .</p>
2597 Note, that we don't want to use `<arch>-debian-linux'
2598 to apply to the rule `architecture-vendor-os' since this
2599 would make our programs incompatible to other Linux
2600 distributions. Also note, that we don't use
2601 `<arch>-unknown-linux', since the `unknown' does not
2602 look very good.</p></sect>
2606 <heading>Daemons</heading>
2609 The configuration files <tt>/etc/services</tt>,
2610 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2611 by the <prgn>netbase</prgn> package and may not be modified
2612 by other packages.</p>
2615 If a package requires a new entry in one of these files, the
2616 maintainer has to get in contact with the
2617 <prgn>netbase</prgn> maintainer, who will add the entries
2618 and release a new version of the <prgn>netbase</prgn>
2622 The configuration file <tt>/etc/inetd.conf</tt> may be
2623 modified by the package's scripts only via the
2624 <prgn>update-inetd</prgn> script or the
2625 <prgn>DebianNet.pm</prgn> Perl module.</p>
2628 If a package wants to install an example entry into
2629 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2630 exactly one hash character (#). Such lines are treated as
2631 `commented out by user' by the <prgn>update-inetd</prgn>
2632 script and are not changed or activated during a package
2637 <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
2640 Some programs need to create pseudo-ttys. This should be done
2641 using Unix98 ptys if the C library supports it. The resulting
2642 program must not be installed setuid root, unless that
2643 is required for other functionality.
2647 The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
2648 <tt>/var/log/lastlog</tt> must be installed writeable by
2649 group utmp. Programs who need to modify those files must
2650 be installed install setgid utmp.
2655 <heading>Editors and pagers</heading>
2658 Some programs have the ability to launch an editor or pager
2659 program to edit or display a text document. Since there are
2660 lots of different editors and pagers available in the Debian
2661 distribution, the system administrator and each user should
2662 have the possibility to choose his/her preferred editor and
2666 In addition, every program should choose a good default
2667 editor/pager if none is selected by the user or system
2671 Thus, every program that launches an editor or pager has to
2672 use the EDITOR or PAGER environment variables to determine
2673 the editor/pager the user wants to get started. If these
2674 variables are not set, the programs `/usr/bin/editor' and
2675 `/usr/bin/pager' have to be used, respectively.</p>
2678 These two files are managed through `alternatives.' That is,
2679 every package providing an editor or pager has to call the
2680 `update-alternatives' script to register these programs.</p>
2683 If it is very hard to adapt a program to make us of the
2684 EDITOR and PAGER variable, that program should be configured
2685 to use `/usr/bin/sensible-editor' and
2686 `/usr/bin/sensible-pager' as editor or pager program,
2687 respectively. These are two scripts provided in the Debian
2688 base system that check the EDITOR and PAGER variables and
2689 launches the appropriate program or falls back to
2690 `/usr/bin/editor' and `/usr/bin/pager', automatically.</p>
2693 Since the Debian base system already provides an editor and
2694 a pager program, there is no need for a package to depend on
2695 `editor' and `pager', nor is it necessary for a package to
2696 provide such virtual packages.</p></sect>
2699 <sect id="web-appl">
2700 <heading>Web servers and applications</heading>
2703 This section describes the locations and URLs that have to
2704 be used by all web servers and web application in the Debian
2710 <p>Cgi-bin executable files are installed in the
2713 /usr/lib/cgi-bin/<cgi-bin-name>
2715 and can be referred to as
2717 http://localhost/cgi-bin/<cgi-bin-name>
2718 </example></p></item>
2721 <item><p>Access to html documents</p>
2724 Html documents for a package are stored in
2725 /usr/share/doc/<var>package</var> and can be referred to as
2727 http://localhost/doc/<package>/<filename>
2728 </example></p></item>
2731 <item><p>Web Document Root</p>
2734 Web Applications should try to avoid storing files in
2735 the Web Document Root. Instead use the
2736 /usr/share/doc/<package> directory for documents and
2737 register the Web Application via the menu package. If
2738 access to the web-root is unavoidable then use
2742 as the Document Root. This might be just a
2743 symbolic link to the location where the sysadmin has
2744 put the real document root.</p>
2747 </enumlist></p></sect>
2751 <heading>Mail transport agents</heading>
2754 Debian packages which process electronic mail, whether
2755 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
2756 <em>must</em> make sure that they are compatible with the
2757 configuration decisions below. Failure to do this may
2758 result in lost mail, broken <tt>From:</tt> lines, and other
2759 serious brain damage!</p>
2762 The mail spool is <tt>/var/spool/mail</tt> and the interface
2763 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
2764 per the FHS). The mail spool is part of the base system
2765 and not part of the MTA package.</p>
2768 All Debian MUAs and MTAs have to use the <tt>maillock</tt>
2769 and <tt>mailunlock</tt> functions provided by the
2770 <tt>liblockfile</tt> packages to lock and unlock mail
2771 boxes. These functions implement a NFS-safe locking
2772 mechanism. (It is ok if MUAs and MTAs don't link against
2773 liblockfile but use a <em>compatible</em> mechanism. Please
2774 compare the mechanisms very carefully!)</p>
2777 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
2778 unless the user has chosen otherwise. A MUA may remove a
2779 mailbox (unless it has nonstandard permissions) in which
2780 case the MTA or another MUA must recreate it if needed.
2781 Mailboxes must be writable by group mail.</p>
2784 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
2785 be setgid mail to do the locking mentioned above (and
2786 obviously need to avoid accessing other users' mailboxes
2787 using this privilege).</p>
2790 <tt>/etc/aliases</tt> is the source file for the system mail
2791 aliases (e.g., postmaster, usenet, etc.)--it is the one
2792 which the sysadmin and <tt>postinst</tt> scripts may edit.
2793 After <tt>/etc/aliases</tt> is edited the program or human
2794 editing it must call <prgn>newaliases</prgn>. All MTA
2795 packages should come with a <prgn>newaliases</prgn> program,
2796 even if it does nothing, but older MTA packages do not do
2797 this so programs should not fail if <prgn>newaliases</prgn>
2798 cannot be found.</p>
2801 The convention of writing <tt>forward to
2802 <var>address</var></tt> in the mailbox itself is not
2803 supported. Use a <tt>.forward</tt> file instead.</p>
2806 The location for the <prgn>rmail</prgn> program used by UUCP
2807 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
2808 FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
2809 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
2813 If you need to know what name to use (for example) on
2814 outgoing news and mail messages which are generated locally,
2815 you should use the file <tt>/etc/mailname</tt>. It will
2816 contain the portion after the username and <tt>@</tt> (at)
2817 sign for email addresses of users on the machine (followed
2821 A package should check for the existence of this file. If
2822 it exists it should use it without comment. (An MTA's
2823 prompting configuration script may wish to prompt the user
2824 even if it finds this file exists.) If it does not exist it
2825 should prompt the user for the value and store it in
2826 <tt>/etc/mailname</tt> as well as using it in the package's
2827 configuration. The prompt should make it clear that the
2828 name will not just be used by that package. For example, in
2829 this situation the INN package says:
2831 Please enter the `mail name' of your system. This is the
2832 hostname portion of the address to be shown on outgoing
2833 news and mail messages. The default is
2834 <var>syshostname</var>, your system's host name. Mail
2835 name [`<var>syshostname</var>']:
2837 where <var>syshostname</var> is the output of <tt>hostname
2838 --fqdn</tt>.</p></sect>
2842 <heading>News system configuration</heading>
2845 All the configuration files related to the NNTP (news)
2846 servers and clients should be located under
2847 <tt>/etc/news</tt>.</p>
2850 There are some configuration issues that apply to a number
2851 of news clients and server packages on the machine. These
2855 <tag>/etc/news/organization</tag>
2856 <item><p>A string which shall appear as the
2857 organization header for all messages posted
2858 by NNTP clients on the machine</p></item>
2860 <tag>/etc/news/server</tag>
2861 <item><p>Contains the FQDN of the upstream NNTP
2862 server, or localhost if the local machine is
2863 an NNTP server.</p></item>
2866 Other global files may be added as required for cross-package news
2867 configuration.</p></sect>
2871 <heading>Programs for the X Window System</heading>
2874 Some programs can be configured with or without support for the X
2875 Window System. Typically, binaries produced with support for X
2876 will need the X shared libraries to run.
2880 Such programs should be configured <em>with</em> X support,
2881 and should declare a dependency on <tt>xlib6g</tt> (which
2882 contains X shared libraries). Users who wish to use the
2883 program can install just the relatively small
2884 <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
2885 not need to install the whole of X.</p>
2888 Do not create two versions (one with X support and one
2889 without) of your package.</p>
2892 <em>Application defaults</em> files have to be installed in
2893 the directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
2894 They are considered as part of the program code. Thus, they
2895 should not be modified and should not be tagged as
2896 <em>conffile</em>s. If the local system administrator wants
2897 to customize X applications globally, a file with the same
2898 name as that of the package should be placed in the
2899 <tt>/etc/X11/Xresources/</tt> directory instead.
2900 <em>Important:</em> packages that install files into the
2901 <tt>/etc/X11/Xresources/</tt> directory <em>must</em>
2902 declare a conflict with <tt>xbase (<<
2903 3.3.2.3a-2)</tt>; if this is not done it is possible for the
2904 package to destroy a previously-existing
2905 <tt>/etc/X11/Xresources</tt> <em>file</em>.</p>
2908 No package should ever install files into the directories
2909 <tt>/usr/bin/X11/</tt>, <tt>/usr/doc/X11/</tt>,
2910 <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>; these
2911 directories are actually symbolic links, which <tt>dpkg</tt>
2912 does not follow when unpacking a package. Instead, use
2913 <tt>/usr/X11R6/bin/</tt>, <tt>/usr/share/doc/package/</tt>
2914 (i.e., place files with the rest of your package's
2915 documentation), <tt>/usr/X11R6/include/</tt>, and
2916 <tt>/usr/X11R6/lib/</tt>. This restriction governs only the
2917 paths used by the package as it is unpacked onto the system;
2918 it is permissible, and even preferable, for files within a
2919 package (shell scripts, for instance) to refer to the
2920 <tt>/usr/{bin,include,lib}/X11/</tt> directories rather than
2921 their <tt>/usr/X11R6/</tt> counterparts -- this way they do
2922 not have to be modified in the event that the X Window
2923 System packages install their files into a different
2924 directory in the future.</p>
2927 If you package a program that requires the (non-free)
2928 OSF/Motif library, you should try to determine whether the
2929 programs works reasonably well with the free
2930 re-implementation of Motif called LessTif. If so, build the
2931 package using the LessTif libraries; it can then go into the
2932 main section of the package repository and become an
2933 official part of the Debian distribution.</p>
2936 If however, the Motif-based program works insufficiently
2937 well with LessTif, you should instead provide "-smotif" and "-dmotif"
2938 versions (appending these identifiers to the name of the
2939 package), which are statically and dynamically linked
2940 against the Motif libraries, respectively. (All known
2941 versions of OSF/Motif permit redistribution of
2942 statically-linked binaries using the library, but check the
2943 license on your copy of Motif to be sure.) This two-package
2944 approach allows users without Motif to use the package,
2945 whereas users with Motif installed can enjoy the advantages
2946 of the dynamically-linked version (a considerable savings in
2947 disk space usage, download time, etc.). Neither "-smotif"
2948 nor "-dmotif" packages can go into the main section; if the
2949 licensing on the package is compatible with the Debian Free
2950 Software Guidelines, it may go into the contrib section;
2951 otherwise it must go into the non-free section.
2958 <heading>Emacs lisp programs</heading>
2961 Please refer to the `Debian Emacs Policy' (documented in
2962 <tt>debian-emacs-policy.gz</tt> of the
2963 <prgn>emacsen-common</prgn> package) for details of how to
2964 package emacs lisp programs.</p></sect>
2968 <heading>Games</heading>
2971 The permissions on /var/lib/games are 755
2972 <tt>root.root</tt>.</p>
2975 Each game decides on its own security policy.</p>
2978 Games which require protected, privileged access to
2979 high-score files, savegames, etc., must be made
2980 set-<em>group</em>-id (mode 2755) and owned by
2981 <tt>root.games</tt>, and use files and directories with
2982 appropriate permissions (770 <tt>root.games</tt>, for
2983 example). They must <em>not</em> be made
2984 set-<em>user</em>-id, as this causes security problems. (If
2985 an attacker can subvert any set-user-id game they can
2986 overwrite the executable of any other, causing other players
2987 of these games to run a Trojan horse program. With a
2988 set-group-id game the attacker only gets access to less
2989 important game data, and if they can get at the other
2990 players' accounts at all it will take considerably more
2994 Some packages, for example some fortune cookie programs, are
2995 configured by the upstream authors to install with their
2996 data files or other static information made unreadable so
2997 that they can only be accessed through set-id programs
2998 provided. Do not do this in a Debian package: anyone can
2999 download the <tt>.deb</tt> file and read the data from it,
3000 so there is no point making the files unreadable. Not
3001 making the files unreadable also means that you don't have
3002 to make so many programs set-id, which reduces the risk of a
3006 As described in the FHS, binaries of games should be
3007 installed in the directory <tt>/usr/games</tt>. This also
3008 applies to games that use the X Window System. Manual pages
3009 for games (X and non-X games) should be installed in
3010 <tt>/usr/share/man/man6</tt>.</p>
3014 <chapt><heading>Documentation</heading>
3018 <heading>Manual pages</heading>
3021 You must install manual pages in <prgn>nroff</prgn> source
3022 form, in appropriate places under <tt>/usr/share/man</tt>. You
3023 should only use sections 1 to 9 (see the FHS for more
3024 details). You must <em>not</em> install a preformatted `cat
3028 If no manual page is available for a particular program,
3029 utility or function and this is reported as a bug on
3030 debian-bugs, a symbolic link from the requested manual page
3031 to the <manref name="undocumented" section="7"> manual page
3032 should be provided. This symbolic link can be created from
3033 <tt>debian/rules</tt> like this:
3035 ln -s ../man7/undocumented.7.gz \
3036 debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
3038 This manpage claims that the lack of a manpage has been
3039 reported as a bug, so you may only do this if it really has
3040 (you can report it yourself, if you like). Do not close the
3041 bug report until a proper manpage is available.</p>
3044 You may forward a complaint about a missing manpage to the
3045 upstream authors, and mark the bug as forwarded in the
3046 Debian bug tracking system. Even though the GNU Project do
3047 not in general consider the lack of a manpage to be a bug,
3048 we do--if they tell you that they don't consider it a bug
3049 you should leave the bug in our bug tracking system open
3053 Manual pages should be installed compressed using <tt>gzip
3057 If one manpage needs to be accessible via several names it
3058 is better to use a symbolic link than the <tt>.so</tt>
3059 feature, but there is no need to fiddle with the relevant
3060 parts of the upstream source to change from <tt>.so</tt> to
3061 symlinks--don't do it unless it's easy. Do not create hard
3062 links in the manual page directories, and do not put
3063 absolute filenames in <tt>.so</tt> directives. The filename
3064 in a <tt>.so</tt> in a manpage should be relative to the
3065 base of the manpage tree (usually
3066 <tt>/usr/share/man</tt>).</p></sect>
3070 <heading>Info documents</heading>
3073 Info documents should be installed in <tt>/usr/share/info</tt>.
3074 They should be compressed with <tt>gzip -9</tt>.</p>
3077 Your package must call <prgn>install-info</prgn> to update the Info
3079 file, in its post-installation script:
3081 install-info --quiet --section Development Development \
3082 /usr/share/info/foobar.info
3086 It is a good idea to specify a section for the location of
3087 your program; this is done with the <tt>--section</tt>
3088 switch. To determine which section to use, you should look
3089 at <tt>/usr/share/info/dir</tt> on your system and choose the most
3090 relevant (or create a new section if none of the current
3091 sections are relevant). Note that the <tt>--section</tt>
3092 flag takes two arguments; the first is a regular expression
3093 to match (case-insensitively) against an existing section,
3094 the second is used when creating a new one.</p>
3097 You must remove the entries in the pre-removal script:
3099 install-info --quiet --remove /usr/share/info/foobar.info
3103 If <prgn>install-info</prgn> cannot find a description entry
3104 in the Info file you will have to supply one. See <manref
3105 name="install-info" section="8"> for details.</p>
3109 <heading>Additional documentation</heading>
3112 Any additional documentation that comes with the package can
3113 be installed at the discretion of the package maintainer.
3114 Text documentation should be installed in a directory
3115 <tt>/usr/share/doc/<var>package</var></tt>, where
3116 <var>package</var> is the name of the package, and
3117 compressed with <tt>gzip -9</tt> unless it is small.</p>
3120 If a package comes with large amounts of documentation which
3121 many users of the package will not require you should create
3122 a separate binary package to contain it, so that it does not
3123 take up disk space on the machines of users who do not need
3124 or want it installed.</p>
3127 It is often a good idea to put text information files
3128 (<tt>README</tt>s, changelogs, and so forth) that come with
3129 the source package in <tt>/usr/share/doc/<var>package</var></tt>
3130 in the binary package. However, you don't need to install
3131 the instructions for building and installing the package, of
3136 <heading>Preferred documentation formats</heading>
3139 The unification of Debian documentation is being carried out
3143 If your package comes with extensive documentation in a
3144 mark up format that can be converted to various other formats
3145 you should if possible ship HTML versions in a binary
3146 package, in the directory
3147 <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
3150 <p>The rationale: The important thing here is that HTML
3151 docs should be available in <em>some</em> package, not
3152 necessarily in the main binary package, though. </p>
3157 Other formats such as PostScript may be provided at your
3161 <sect id="copyrightfile">
3162 <heading>Copyright information</heading>
3165 Every package must be accompanied by a verbatim copy of its
3166 copyright and distribution license in the file
3167 /usr/share/doc/<package-name>/copyright. This file must
3168 neither be compressed nor be a symbolic link.</p>
3171 In addition, the copyright file must say where the upstream
3172 sources (if any) were obtained, and explain briefly what
3173 modifications were made in the Debian version of the package
3174 compared to the upstream one. It must name the original
3175 authors of the package and the Debian maintainer(s) who were
3176 involved with its creation.</p>
3179 /usr/share/doc/<package-name> may be a symbolic link to a
3180 directory in /usr/share/doc only if two packages both come from
3181 the same source and the first package has a "Depends"
3182 relationship on the second. These rules are important
3183 because copyrights must be extractable by mechanical
3187 Packages distributed under the UCB BSD license, the Artistic
3188 license, the GNU GPL, and the GNU LGPL should refer to the
3189 files /usr/share/common-licenses/BSD,
3190 /usr/share/common-licenses/Artistic,
3191 /usr/share/common-licenses/GPL, and
3192 /usr/share/common-licenses/LGPL.
3195 Why "licenses" and not "copyright"? Because
3196 <tt>/usr/doc/copyright</tt> used to contain all the
3197 copyright files, plus the four common licenses GPL,
3198 LGPL, Artistic and BSD. Now individual copyright files
3199 for packages are no longer in a common directory. Once
3200 <tt>/usr/doc/copyright</tt> is almost empty it makes
3201 sense to rename "copyright" to "licenses"
3204 Why "common-licenses" and not "licenses"? Because if I
3205 put just "licenses" I'm sure I will receive a bug report
3206 saying "license foo is not included in the licenses
3207 directory. They are not all the licenses, just a few
3208 common ones. I could use /usr/share/doc/common-licenses
3209 but I think this is too long, and, after all, the GPL
3210 does not "document" anything, it is merely a license.
3216 Do not use the copyright file as a general <tt>README</tt>
3217 file. If your package has such a file it should be
3218 installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
3219 <tt>README.Debian</tt> or some other appropriate place.</p>
3223 <heading>Examples</heading>
3226 Any examples (configurations, source files, whatever),
3227 should be installed in a directory
3228 <tt>/usr/share/doc/<var>package</var>/examples</tt>. These files
3229 should not be referenced by any program--they're there for
3230 the benefit of the system administrator and users, as
3231 documentation only.</p>
3234 <sect id="instchangelog">
3235 <heading>Changelog files</heading>
3238 This installed file must contain a copy of the
3239 <tt>debian/changelog</tt> file from your Debian source tree,
3240 and a copy of the upstream changelog file if there is one.
3241 The debian/changelog file should be installed in
3242 <tt>/usr/share/doc/<var>package</var></tt> as
3243 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3244 file is text formatted, it must be accessible as
3245 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
3246 the upstream changelog file is HTML formatted, it must be
3248 <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
3249 If the upstream changelog files do not already conform to
3250 this naming convention, then this may be achieved by either
3251 renaming the files or adding a symbolic link at the
3252 packaging developer's discretion. </p>
3255 Both should be installed compressed using <tt>gzip -9</tt>,
3256 as they will become large with time even if they start out
3260 If the package has only one changelog which is used both as
3261 the Debian changelog and the upstream one because there is
3262 no separate upstream maintainer then that changelog should
3263 usually be installed as
3264 <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
3265 there is a separate upstream maintainer, but no upstream
3266 changelog, then the Debian changelog should still be called
3267 <tt>changelog.Debian.gz</tt>.</p>