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 packagingn 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.
54 Copyright ©1996,1997,1998 Ian Jackson
55 and Christian Schwarz.
58 This manual is free software; you may redistribute it and/or
59 modify it under the terms of the GNU General Public License
60 as published by the Free Software Foundation; either version
61 2, or (at your option) any later version.
65 This is distributed in the hope that it will be useful, but
66 <em>without any warranty</em>; without even the implied
67 warranty of merchantability or fitness for a particular
68 purpose. See the GNU General Public License for more
72 A copy of the GNU General Public License is available as
73 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
74 distribution or on the World Wide Web at
75 <url id="http://www.gnu.org/copyleft/gpl.html"
76 name="&urlname">. You can also obtain it by writing to the
77 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
78 Boston, MA 02111-1307, USA.
86 <heading>About this manual</heading>
88 <heading>Scope</heading>
90 This manual describes the policy requirements for the Debian
91 GNU/Linux distribution. This includes the structure and
92 contents of the Debian archive, several design issues of the
93 operating system, as well as technical requirements that
94 each package must satisfy to be included in the
98 This manual does <em>not</em> describe the technical
99 mechanisms involved in package creation, installation, and
100 removal. This information can be found in the <em>Debian
101 Packaging Manual</em> and the <em>Debian System
102 Administrators' Manual</em>.
105 This document assumes familiarity with these other two
106 manuals. Unfortunately, the <em>System Administrators'
107 Manual</em> does not exist yet.
110 Much of the information presented in this manual will be
111 useful even when building a package which is to be
112 distributed in some other way or is for local use.
116 <heading>New versions of this document</heading>
118 The current version of this document is always accessible from the
121 id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz" name="&urlname">
122 or from the Debian WWW server at
123 <url id="http://www.debian.org/doc/manuals/debian-policy/"
127 In addition, this manual is distributed via the Debian package
128 <tt>debian-policy</tt>
132 <heading>Feedback</heading>
135 As the Debian GNU/Linux system is continuously evolving this
136 manual is changed from time to time.
139 While the authors of this document tried hard not to include
140 any typos or other errors these still occur. If you discover
141 an error in this manual or if you want to tell us any
142 comments, suggestions, or critics please send an email to
143 the Debian Policy List,
144 <email>debian-policy@lists.debian.org</email>, or submit a
145 bug report against the <tt>debian-policy</tt> package.
150 <heading>The Debian Archive</heading>
152 The Debian GNU/Linux system is maintained and distributed as a
153 collection of <em>packages</em>. Since there are so many of them (over
154 2600) they are split into <em>sections</em> and <em>priorities</em> to
155 simplify handling of them.
158 The effort of the Debian project is to build a free operating
159 system, but not every package we want to make accessible is
160 <em>free</em> in our sense (see Debian Free Software
161 Guidelines, below), or may be imported/exported without
162 restrictions. Thus, the archive is split into the sections
163 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
164 <em>contrib</em>.</p>
166 The <em>main</em> section forms the <em>Debian GNU/Linux
167 distribution</em>. </p>
169 Packages in the other sections are not considered as part of
170 the Debian distribution, though we support their use, and we
171 provide infrastructure for them (such as our bug-tracking
172 system and mailing lists). This Debian Policy Manual applies
173 to these packages as well.</p>
175 <sect id="pkgcopyright">
176 <heading>Package copyright and sections</heading>
178 The aims of this policy are:
180 <list compact="compact">
182 <p>We want to make as much software available as we
186 <p>We want to encourage everyone to write free software.</p>
189 <p> We want to make it easy for people to produce
190 CD-ROMs of our system without violating any licenses,
191 import/export restrictions, or any other laws.</p>
196 <heading>The Debian Free Software Guidelines</heading>
198 The Debian Free Software Guidelines (DFSG) as is our
199 definition of `free' software.
201 <tag>>Free Redistribution
205 The license of a Debian component may not restrict any
206 party from selling or giving away the software as a
207 component of an aggregate software distribution
208 containing programs from several different
209 sources. The license may not require a royalty or
210 other fee for such sale.
217 The program must include source code, and must allow
218 distribution in source code as well as compiled form.
225 The license must allow modifications and derived
226 works, and must allow them to be distributed under the
227 same terms as the license of the original software.
230 <tag>Integrity of The Author's Source Code
234 The license may restrict source-code from being
235 distributed in modified form <em>only</em> if the
236 license allows the distribution of ``patch files''
237 with the source code for the purpose of modifying the
238 program at build time. The license must explicitly
239 permit distribution of software built from modified
240 source code. The license may require derived works to
241 carry a different name or version number from the
242 original software. (This is a compromise. The Debian
243 group encourages all authors to not restrict any
244 files, source or binary, from being modified.)
247 <tag>No Discrimination Against Persons or Groups
251 The license must not discriminate against any person
255 <tag>No Discrimination Against Fields of Endeavor
259 The license must not restrict anyone from making use
260 of the program in a specific field of endeavor. For
261 example, it may not restrict the program from being
262 used in a business, or from being used for genetic
266 <tag>Distribution of License
270 The rights attached to the program must apply to all
271 to whom the program is redistributed without the need
272 for execution of an additional license by those
276 <tag>License Must Not Be Specific to Debian
280 The rights attached to the program must not depend on
281 the program's being part of a Debian system. If the
282 program is extracted from Debian and used or
283 distributed without Debian but otherwise within the
284 terms of the program's license, all parties to whom
285 the program is redistributed should have the same
286 rights as those that are granted in conjunction with
290 <tag>License Must Not Contaminate Other Software
294 The license must not place restrictions on other
295 software that is distributed along with the licensed
296 software. For example, the license must not insist
297 that all other programs distributed on the same medium
298 must be free software.
301 <tag>Example Licenses
305 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
306 examples of licenses that we consider <em>free</em>.
313 <heading>The main section</heading>
315 Every package in "main" must comply with the DFSG (Debian
316 Free Software Guidelines).</p>
319 In addition, the packages in "main"
320 <list compact="compact">
323 must not require a package outside of "main" for
324 compilation or execution (thus, the package may not
325 declare a "Depends" or "Recommends" relationship on a
331 must not be so buggy that we refuse to support them,
336 must meet all policy requirements presented in this
344 <heading>The contrib section</heading>
346 Every package in "contrib" must comply with the DFSG.
350 Examples of packages which would be included in "contrib" are
351 <list compact="compact">
354 free packages which require "contrib", "non-free", or
355 "non-US" packages or packages which are not in our
356 archive at all for compilation or execution,
361 wrapper packages or other sorts of free accessories for
367 packages which we don't want to support because they are too
373 packages which fail to meet some other policy requirements in
381 <heading>The non-free section</heading>
383 `Non-free' contains packages which are not compliant with
384 the DFSG or which are encumbered by patents or other legal
385 issues that make their distribution problematic.</p>
387 All packages in `non-free' must be electronically
388 distributable across international borders.
392 <heading>The non-us server</heading>
394 Some programs with cryptographic program code must be stored
395 on the "non-us" server because of export restrictions of the
398 This applies only to packages which contain cryptographic
399 code. A package containing a program with an interface to a
400 cryptographic program or a program that's dynamically linked
401 against a cryptographic library can be distributed if it is
402 capable of running without the cryptography library or
407 <heading>Further copyright considerations</heading>
409 Every package must be accompanied by a verbatim copy of its
410 copyright and distribution license in the file
411 /usr/doc/<package-name>/copyright (see <ref
412 id="copyrightfile"> for details).</p>
414 We reserve the right to restrict files from being included
415 anywhere in our archives if
416 <list compact="compact">
419 their use or distribution would break a law,
424 there is an ethical conflict in their distribution or
430 we would have to sign a license for them, or
435 their distribution would conflict with other project
443 Programs whose authors encourage the user to make donations
444 are fine for the main distribution, provided that the
445 authors do not claim that not donating is immoral,
446 unethical, illegal or something similar; otherwise they must
447 go in contrib (or non-free, if even distribution is
448 restricted by such statements).</p>
451 Packages whose copyright permission notices (or patent
452 problems) do not allow redistribution even of only binaries,
453 and where no special permission has been obtained, cannot be
454 placed on the Debian FTP site and its mirrors at all.</p>
457 Note, that under international copyright law (this applies
458 in the United States, too) <em>no</em> distribution or
459 modification of a work is allowed without an explicit notice
460 saying so. Therefore a program without a copyright notice
461 <em>is</em> copyrighted and you may not do anything to it
462 without risking being sued! Likewise if a program has a
463 copyright notice but no statement saying what is permitted
464 then nothing is permitted.</p>
467 Many authors are unaware of the problems that restrictive
468 copyrights (or lack of copyright notices) can cause for the
469 users of their supposedly-free software. It is often
470 worthwhile contacting such authors diplomatically to ask
471 them to modify their license terms. However, this is a
472 politically difficult thing to do and you should ask for
473 advice on <tt>debian-devel</tt> first.</p>
476 When in doubt, send mail to
477 <email>debian-devel@lists.debian.org</email>. Be prepared
478 to provide us with the copyright statement. Software
479 covered by the GPL, public domain software and BSD-like
480 copyrights are safe; be wary of the phrases `commercial use
481 prohibited' and `distribution restricted'.</p>
484 <heading>Subsections</heading>
487 The packages in the <em>main</em>, <em>contrib</em>, and
488 <em>non-free</em> sections are grouped further into
489 <em>subsections</em> to simplify handling of them.</p>
492 The section for each package is specified in the package's
493 <em>control record</em>. However, the maintainer of the
494 Debian archive may override this selection to assure the
495 consistency of the Debian distribution. </p>
498 Please check the current Debian distribution to see which
499 sections are available.</p>
502 <heading>Priorities</heading>
505 Each package is given a certain <em>priority</em> value,
506 which is included in the package's <em>control
507 record</em>. This information is used in the Debian package
508 management tool to separate high-priority packages from
509 less-important packages.</p>
512 The following <em>priority levels</em> are supported by the
513 Debian package management system, <prgn>dpkg</prgn>.
515 <tag><tt>required</tt></tag>
518 <tt>required</tt> packages are necessary for the
519 proper functioning of the system. You must not remove
520 these packages or your system may become totally
521 broken and you may not even be able to use
522 <prgn>dpkg</prgn> to put things back. Systems with
523 only the <tt>required</tt> packages are probably
524 unusable, but they do have enough functionality to
525 allow the sysadmin to boot and install more
528 <tag><tt>important</tt></tag>
531 Important programs, including those which one would
532 expect to find on any Unix-like system. If the
533 expectation is that an experienced Unix person who
534 found it missing would say `What the F*!@<+ is
535 going on, where is <prgn>foo</prgn>', it should be in
536 <tt>important</tt>. This is an important criterion
537 because we are trying to produce, amongst other
538 things, a free Unix. Other packages without which the
539 system will not run well or be usable should also be
540 here. This does <em>not</em> include Emacs or X11 or
541 TeX or any other large applications. The
542 <tt>important</tt> packages are just a bare minimum of
543 commonly-expected and necessary tools.</p>
545 <tag><tt>standard</tt></tag>
548 These packages provide a reasonably small but not too
549 limited character-mode system. This is what will
550 install by default if the user doesn't select anything
551 else. It doesn't include many large applications, but
552 it does include Emacs (this is more of a piece of
553 infrastructure than an application) and a reasonable
554 subset of TeX and LaTeX (if this is possible without
557 <tag><tt>optional</tt></tag>
560 (In a sense everything is optional that isn't
561 required, but that's not what is meant here.) This is
562 all the software that you might reasonably want to
563 install if you didn't know what it was or don't have
564 specialised requirements. This is a much larger system
565 and includes X11, a full TeX distribution, and lots of
568 <tag><tt>extra</tt></tag>
571 This contains packages that conflict with others with
572 higher priorities, or are only likely to be useful if
573 you already know what they are or have specialised
580 Packages may not depend on packages with lower priority
581 values. If this should happen, one of the priority values
582 will have to be adapted.
587 <heading>Binary packages</heading>
590 The Debian GNU/Linux distribution is based on the Debian
591 package management system, called <prgn>dpkg</prgn>. Thus,
592 all packages in the Debian distribution have to be provided
593 in the <tt>.deb</tt> file format.</p>
597 <heading>The package name</heading>
600 Every package must have a name that's unique within the Debian
604 Package names may only consist of lower case letters, digits (0-9),
605 plus (+) or minus (-) signs, and periods (.).</p>
608 The package name is part of the file name of the
609 <tt>.deb</tt> file and is included in the control field
615 <heading>The maintainer of a package</heading>
618 Every package must have exactly one maintainer at a
619 time. This person is responsible that the license of the
620 package's software complies with the policy of the
621 distribution this package is included in.</p>
624 The maintainer must be specified in the
625 <tt>Maintainer</tt> control field with the correct name
626 and a working email address for the Debian maintainer of
627 the package. If one person maintains several packages
628 he/she should try to avoid having different forms of their
629 name and email address in different <tt>Maintainer</tt>
633 If the maintainer of a package quits from the Debian
634 project the Debian QA Group takes over the maintainership
635 of the package until someone else volunteers for that
636 task. These packages are called <em>orphaned
643 <heading>The description of a package</heading>
646 Every Debian package should have an extended description
647 stored in the appropriate field of the control record.</p>
650 The description should be written so that it tells the
651 user what they need to know to decide whether to install
652 the package. This description should not just be copied
653 from the blurb for the program. Instructions for
654 configuring or using the package should not be
655 included--that is what installation scripts, manual pages,
656 Info files, etc. are for. Copyright statements and other
657 administrivia should not be included--that is what the
658 copyright file is for.</p>
663 <heading>Dependencies</heading>
666 Every package has to specify the dependency information
667 about other packages, that are required for the first to
671 For example, for any shared libraries required by
672 dynamically-linked executable binary in a package a
673 dependency entry has to be provided.</p>
676 It is not necessary for other packages to declare any
677 dependencies they have on other packages which are marked
678 <tt>Essential</tt> (see below).</p>
681 Sometimes, a package requires another package to be
682 installed <em>and</em> configured before it can be
683 installed. In this case, you'll have to specify a
684 <tt>Pre-Depends</tt> entry for the package.</p>
687 You must not specify a <tt>Pre-Depends</tt> entry for a
688 package before this has been discussed on the
689 <tt>debian-devel</tt> mailing list and a consensus about
690 doing that has been reached.</p></sect1>
694 <heading>Virtual packages</heading>
697 Sometimes, there are several packages doing more-or-less
698 the same job. In this case, it's useful to define a
699 <em>virtual package</em> who's name describes the function
700 the packages have. (The virtual packages just exist
701 logically, not physically--that's why they are called
702 <em>virtual</em>.) The packages with this particular
703 function will then <em>provide</em> the virtual
704 package. Thus, any other package requiring that function
705 can simply depend on the virtual package without having to
706 specify all possible packages individually.</p>
709 All packages must use virtual package names where
710 appropriate, and arrange to create new ones if necessary.
711 They must not use virtual package names (except privately,
712 amongst a cooperating group of packages) unless they have
713 been agreed upon and appear in the list of virtual package
717 The latest version of the authoritative list of virtual
718 package names can be found on
719 <ftpsite>ftp.debian.org</ftpsite> in
720 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
721 or your local mirror. In addition, it is included in the
722 <tt>debian-policy</tt> package. The procedure for updating
723 the list is described at the top of the file.</p></sect1>
727 <heading>Base packages</heading>
730 The packages included in the <tt>base</tt> section have a
731 special function. They form a minimum subset of the Debian
732 GNU/Linux system that is installed before everything else
733 on a new system. Thus, only very few packages are allowed
734 to go into the <tt>base</tt> section to keep the required
735 disk usage very small.</p>
738 Most of these packages should have the priority value
739 <tt>required</tt> or at least <tt>important</tt>, and many
740 of them will be tagged <tt>essential</tt> (see below).</p>
743 You must not place any packages into the <tt>base</tt>
744 section before this has been discussed on the
745 <tt>debian-devel</tt> mailing list and a consensus about
746 doing that has been reached.</p></sect1>
750 <heading>Essential packages</heading>
753 Some packages are tagged <tt>essential</tt>. (They have
754 <tt>Essential: yes</tt> in their package control record.)
755 This flag is used for packages that are <em>essential</em>
759 Since these packages can not easily be removed (you'll
760 have to specify an extra <em>force option</em> to
761 <prgn>dpkg</prgn>) this flag should only be used where
762 absolutely necessary.
764 A shared library package should not be tagged
765 <em>essential</em>--the dependencies will prevent its
766 premature removal, and we need to be able to remove it
767 when it has been superseded.</p>
770 You must not tag any packages <tt>essential</tt> before
771 this has been discussed on the <tt>debian-devel</tt>
772 mailing and a consensus about doing that has been
777 <heading>Maintainer scripts</heading>
780 The package installation scripts should avoid producing
781 output which it is unnecessary for the user to see and
782 should rely on <prgn>dpkg</prgn> to stave off boredom on
783 the part of a user installing many packages. This means,
784 amongst other things, using the <tt>--quiet</tt> option on
785 <prgn>install-info</prgn>.</p>
788 Packages should try to minimise the amount of prompting
789 they need to do, and they should ensure that the user will
790 only ever be asked each question once. This means that
791 packages should try to use appropriate shared
792 configuration files (such as <tt>/etc/papersize</tt> and
793 <tt>/etc/nntpserver</tt>), rather than each prompting for
794 their own list of required pieces of information.</p>
797 It also means that an upgrade should not ask the same
798 questions again, unless the user has used <tt>dpkg
799 --purge</tt> to remove the package's configuration. The
800 answers to configuration questions should be stored in an
801 appropriate place in <tt>/etc</tt> so that the user can
802 modify them, and how this has been done should be
806 If a package has a vitally important piece of information
807 to pass to the user (such as "don't run me as I am, you
808 must edit the following configuration files first or you
809 risk your system emitting badly-formatted messages"), it
810 should display this in the <prgn>postinst</prgn> script
811 and prompt the user to hit return to acknowledge the
812 message. Copyright messages do not count as vitally
813 important (they belong in
814 <tt>/usr/doc/<var>package</var>/copyright</tt>); neither
815 do instructions on how to use a program (these should be
816 in on line documentation, where all the users can see
820 Any necessary prompting should almost always be confined
821 to the post-installation script, and should be protected
822 with a conditional so that unnecessary prompting doesn't
823 happen if a package's installation fails and the
824 <prgn>postinst</prgn> is called with
825 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
826 <tt>abort-deconfigure</tt>.</p>
829 Errors which occur during the execution of an installation
830 script <em>must</em> be checked and the installation
831 <em>must not</em> continue after an error.</p>
834 Note, that <ref id="scripts">, in general applies to
835 package maintainer scripts, too.</p>
838 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
839 another package without consulting the maintainer of that
843 In order for <prgn>update-alternatives</prgn> to work
844 correctly all the packages which supply an instance of the
845 `shared' command name (or, in general, filename) must use
846 it. You can use <tt>Conflicts</tt> to force the
847 deinstallation of other packages supplying it which do not
848 (yet) use <prgn>update-alternatives</prgn>. It may in
849 this case be appropriate to specify a conflict on earlier
850 versions on something--this is an exception to the usual
851 rule that this is not allowed.</p>
855 <heading>Source packages</heading>
858 <heading>Standards conformance</heading>
861 You should specify the most recent version of the
862 packaging standards with which your package complies in
863 the source package's <tt>Standards-Version</tt> field.</p>
866 This value will be used to file bug reports automatically
867 if your package becomes too much out of date.</p>
870 The value corresponds to a version of the Debian manuals,
871 as can be found on the title page or page headers and
872 footers (depending on the format).</p>
875 The version number has four components--major and minor
876 number and major and minor patch level. When the
877 standards change in a way that requires every package to
878 change the major number will be changed. Significant
879 changes that will require work in many packages will be
880 signaled by a change to the minor number. The major patch
881 level will be changed for any change to the meaning of the
882 standards, however small; the minor patch level will be
883 changed when only cosmetic, typographical or other edits
884 which do not change the meaning are made, or changes which
885 do not affect the contents of packages.</p>
888 You should regularly, and especially if your package has
889 become out of date, check for the newest Policy Manual
890 available and update your package, if necessary. When your
891 package complies with the new standards you may update the
892 <tt>Standards-Version</tt> source package field and
893 release it.</p></sect1>
897 <heading>Changes to the upstream sources</heading>
900 If changes to the source code are made that are generally
901 applicable please try to get them included in the upstream
902 version of the package by supplying the upstream authors
903 with the changes in whatever form they prefer.</p>
906 If you need to configure the package differently for
907 Debian or for Linux, and the upstream source doesn't
908 provide a way to configure it the way you need to, please
909 add such configuration facilities (for example, a new
910 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
911 the patch to the upstream authors, with the default set to
912 the way they originally had it. You can then easily
913 override the default in your <tt>debian/rules</tt> or
914 wherever is appropriate.</p>
917 Please make sure that the <prgn>configure</prgn> utility
918 detects the correct architecture specification string
919 (refer to <ref id="arch-spec"> for details).</p>
922 If you need to edit a <prgn>Makefile</prgn> where
923 GNU-style <prgn>configure</prgn> scripts are used, you
924 should edit the <tt>.in</tt> files rather than editing the
925 <prgn>Makefile</prgn> directly. This allows the user to
926 reconfigure the package if necessary. You should
927 <em>not</em> configure the package and edit the generated
928 <prgn>Makefile</prgn>! This makes it impossible for
929 someone else to later reconfigure the package.</p></sect1>
933 <heading>Documenting your changes</heading>
936 Document your changes and updates to the source package
937 properly in the <tt>debian/changelog</tt> file.</p>
940 A copy of the file which will be installed in
941 <tt>/usr/doc/<var>package</var>/copyright</tt> should be
942 in <tt>debian/copyright</tt>.</p>
945 In non-experimental packages you may only use a format for
946 <tt>debian/changelog</tt> which is supported by the most
947 recent released version of <prgn>dpkg</prgn>. If your
948 format is not supported and there is general support for
949 it you should contact the <prgn>dpkg</prgn> maintainer to
950 have the parser script for your format included in the
951 <prgn>dpkg</prgn> package. (You will need to agree that
952 the parser and its manpage may be distributed under the
953 GNU GPL, just as the rest of <prgn>dpkg</prgn>
958 <heading>Error trapping in makefiles</heading>
961 When <prgn>make</prgn> invokes a command in a makefile
962 (including your package's upstream makefiles and the
963 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
964 means that <tt>sh</tt>'s usual bad error handling
965 properties apply: if you include a miniature script as one
966 of the commands in your makefile you'll find that if you
967 don't do anything about it then errors are not detected
968 and <prgn>make</prgn> will blithely continue after
972 Every time you put more than one shell command (this
973 includes using a loop) in a makefile command you
974 <em>must</em> make sure that errors are trapped. For
975 simple compound commands, such as changing directory and
976 then running a program, using <tt>&&</tt> rather
977 than semicolon as a command separator is sufficient. For
978 more complex commands including most loops and
979 conditionals you must include a separate <tt>set -e</tt>
980 command at the start of every makefile command that's
981 actually one of these miniature shell scripts.</p></sect1>
985 <heading>Obsolete constructs and libraries</heading>
988 The include file <prgn><varargs.h></prgn> is
989 provided to support end-users compiling very old software;
990 the library <tt>libtermcap</tt> is provided to support the
991 execution of software which has been linked against it
992 (either old programs or those such as Netscape which are
993 only available in binary form).</p>
996 Debian packages should be ported to include
997 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1002 <chapt><heading>The Operating System</heading>
1006 <heading>Filesystem hierarchy</heading>
1010 <heading>Linux Filesystem Structure</heading>
1013 The location of all installed files and directories must
1014 comply fully with the Linux Filesystem Structure (FSSTND).
1015 The latest version of this document can be found alongside
1016 this manual or on <ftpsite>tsx-11.mit.edu</ftpsite> in
1017 <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
1018 Specific questions about following the standard may be
1019 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1020 Quinlan, the FSSTND coordinator, at
1021 <email>quinlan@pathname.com</email>.</p></sect1>
1025 <heading>Site-specific programs</heading>
1028 As mandated by the FSSTND no package should place any
1029 files in <tt>/usr/local</tt>, either by putting them in
1030 the filesystem archive to be unpacked by <prgn>dpkg</prgn>
1031 or by manipulating them in their maintainer scripts.</p>
1034 However, the package should create empty directories below
1035 <tt>/usr/local</tt> so that the system administrator knows
1036 where to place site-specific files. These directories
1037 should be removed on package removal if they are
1041 Note, that this applies only to directories <em>below</em>
1042 <tt>/usr/local</tt>, not <em>in</em>
1043 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1044 itself may only contain the sub-directories listed in
1045 FSSTND, section 4.8. However, you may create directories
1046 below them as you wish. You may not remove any of the
1047 directories listed in 4.8, even if you created them.</p>
1050 Since <tt>/usr/local</tt> may be mounted read-only from a
1051 remote server, these directories have to be created and
1052 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1053 maintainer scripts. These scripts must not fail if either
1054 of these operations fail. (In the future, it will be
1055 possible to tell <prgn>dpkg</prgn> not to unpack files
1056 matching certain patterns, so that the directories can be
1057 included in the <tt>.deb</tt> packages and system
1058 administrators who do not wish these directories in
1059 /usr/local do not need to have them.)</p>
1062 For example, the <prgn>emacs</prgn> package will contain
1064 mkdir -p /usr/local/lib/emacs/site-lisp || true
1066 in the <tt>postinst</tt> script, and
1068 rmdir /usr/local/lib/emacs/site-lisp && \
1069 rmdir /usr/local/lib/emacs || \
1072 in the <tt>prerm</tt> script.</p>
1075 If you do create a directory in <tt>/usr/local</tt> for
1076 local additions to a package, you must ensure that
1077 settings in <tt>/usr/local</tt> take precedence over the
1078 equivalents in <tt>/usr</tt>.</p>
1081 The <tt>/usr/local</tt> directory itself and all the subdirectories
1082 created by the package should have permissions 2775 (group-writable
1083 and set-group-id) and be owned by <tt>root.staff</tt>.</p>
1088 <heading>Users and groups</heading>
1091 The Debian system can be configured to use either plain or
1092 shadow passwords.</p>
1095 Some user ids (UIDs) and group ids (GIDs) are reserved
1096 globally for use by certain packages. Because some packages
1097 need to include files which are owned by these users or
1098 groups, or need the ids compiled into binaries, these ids
1099 must be used on any Debian system only for the purpose for
1100 which they are allocated. This is a serious restriction, and
1101 we should avoid getting in the way of local administration
1102 policies. In particular, many sites allocate users and/or
1103 local system groups starting at 100.</p>
1106 Apart from this we should have dynamically allocated ids,
1107 which should by default be arranged in some sensible
1108 order--but the behaviour should be configurable.</p>
1111 No package except <tt>base-passwd</tt> may modify
1112 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1113 <tt>/etc/group</tt>.</p>
1116 The UID and GID ranges are as follows:
1121 Globally allocated by the Debian project, must be the
1122 same on every Debian system. These ids will appear in
1123 the <tt>passwd</tt> and <tt>group</tt> files of all
1124 Debian systems, new ids in this range being added
1125 automatically as the <tt>base-passwd</tt> package is
1129 Packages which need a single statically allocated uid
1130 or gid should use one of these; their maintainers
1131 should ask the <tt>base-passwd</tt> maintainer for
1138 Dynamically allocated system users and groups.
1139 Packages which need a user or group, but can have this
1140 user or group allocated dynamically and differently on
1141 each system, should use `<tt>adduser --system</tt>' to
1142 create the group and/or user. <prgn>adduser</prgn>
1143 will check for the existence of the user or group, and
1144 if necessary choose an unused id based on the ranged
1145 specified in <tt>adduser.conf</tt>.</p></item>
1148 <tag>1000-29999:</tag>
1151 Dynamically allocated user accounts. By default
1152 <prgn>adduser</prgn> will choose UIDs and GIDs for
1153 user accounts in this range, though
1154 <tt>adduser.conf</tt> may be used to modify this
1158 <tag>30000-59999:</tag>
1160 <p>Reserved.</p></item>
1163 <tag>60000-64999:</tag>
1166 Globally allocated by the Debian project, but only
1167 created on demand. The ids are allocated centrally and
1168 statically, but the actual accounts are only created
1169 on users' systems on demand.</p>
1172 These ids are for packages which are obscure or which
1173 require many statically-allocated ids. These packages
1174 should check for and create the accounts in
1175 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1176 <prgn>adduser</prgn> if it has this facility) if
1177 necessary. Packages which are likely to require
1178 further allocations should have a `hole' left after
1179 them in the allocation, to give them room to
1183 <tag>65000-65533:</tag>
1185 <p>Reserved.</p></item>
1190 <p>User `<tt>nobody</tt>.'</p></item>
1196 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1197 because it is the error return sentinel value.</p>
1202 <sect id="sysvinit">
1203 <heading>System run levels</heading>
1207 <heading>Introduction</heading>
1210 The <tt>/etc/init.d</tt> directory contains the scripts
1211 executed by <prgn>init</prgn> at boot time and when init
1212 state (or `runlevel') is changed (see <manref name="init"
1213 section="8">).</p> <p>
1215 These scripts are being referenced by symbolic links in
1216 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1217 changing runlevels, <prgn>init</prgn> looks in the
1218 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1219 it should execute, where <var>n</var> is the runlevel that
1220 is being changed to, or `S' for the boot-up scripts.</p>
1223 The names of the links all have the form
1224 <tt>S<var>mm/<var>script</var></var></tt> or
1225 <tt>K<var>mm/<var>script</var></var></tt> where
1226 <var>mm</var> is a two-digit number and <var>script</var>
1227 is the name of the script (this should be the same as the
1228 name of the actual script in <tt>/etc/init.d</tt>.
1230 When <prgn>init</prgn> changes runlevel first the targets
1231 of the links whose names starting with a <tt>K</tt> are
1232 executed, each with the single argument <tt>stop</tt>,
1233 followed by the scripts prefixed with an <tt>S</tt>, each
1234 with the single argument <tt>start</tt>. The <tt>K</tt>
1235 links are responsible for killing services and the
1236 <tt>S</tt> link for starting services upon entering the
1240 For example, if we are changing from runlevel 2 to
1241 runlevel 3, init will first execute all of the <tt>K</tt>
1242 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1243 all of the <tt>S</tt> prefixed scripts. The links
1244 starting with <tt>K</tt> will cause the referred-to file
1245 to be executed with an argument of <tt>stop</tt>, and the
1246 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1249 The two-digit number <var>mm</var> is used to decide which
1250 order to start and stop things in--low-numbered links have
1251 their scripts run first. For example, the <tt>K20</tt>
1252 scripts will be executed before the <tt>K30</tt> scripts.
1253 This is used when a certain service must be started before
1254 another. For example, the name server <prgn>bind</prgn>
1255 might need to be started before the news server
1256 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1257 access lists. In this case, the script that starts
1258 <prgn>bind</prgn> should have a lower number than the
1259 script that starts <prgn>inn</prgn> so that it runs first:
1268 <heading>Writing the scripts</heading>
1271 Packages can and should place scripts in
1272 <tt>/etc/init.d</tt> to start or stop services at boot
1273 time or during a change of runlevel. These scripts should
1274 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1275 should accept one argument, saying what to do:
1278 <tag><tt>start</tt></tag>
1279 <item><p>start the service,</p></item>
1281 <tag><tt>stop</tt></tag>
1282 <item><p>stop the service,</p></item>
1284 <tag><tt>restart</tt></tag>
1285 <item><p>stop and restart the service,</p></item>
1287 <tag><tt>reload</tt></tag>
1288 <item><p>cause the configuration of the service to be
1289 reloaded without actually stopping and restarting
1290 the service,</p></item>
1292 <tag><tt>force-reload</tt></tag> <item><p>cause the
1293 configuration to be reloaded if the service supports
1294 this, otherwise restart the service.</p></item>
1297 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1298 <tt>force-reload</tt> options must be supported by all
1299 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1300 option is optional.</p>
1303 The <tt>init.d</tt> scripts should ensure that they will
1304 behave sensibly if invoked with <tt>start</tt> when the
1305 service is already running, or with <tt>stop</tt> when it
1306 isn't, and that they don't kill unfortunately-named user
1307 processes. The best way to achieve this is usually to use
1308 <prgn>start-stop-daemon</prgn>.</p>
1311 If a service reloads its configuration automatically (as
1312 in the case of <prgn>cron</prgn>, for example), the
1313 <tt>reload</tt> option of the <tt>init.d</tt> script
1314 should behave as if the configuration has been reloaded
1318 These scripts should not fail obscurely when the
1319 configuration files remain but the package has been
1320 removed, as the default in <prgn>dpkg</prgn> is to leave
1321 configuration files on the system after the package has
1322 been removed. Only when it is executed with the
1323 <tt>--purge</tt> option will dpkg remove configuration
1324 files. Therefore, you should include a <tt>test</tt>
1325 statement at the top of the script, like this:
1327 test -f <var>program-executed-later-in-script</var> || exit 0
1328 </example></p></sect1>
1331 <heading>Managing the links</heading>
1334 A program is provided, <prgn>update-rc.d</prgn>, to make
1335 it easier for package maintainers to arrange for the
1336 proper creation and removal of
1337 <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
1338 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1341 You should use this script to make changes to
1342 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
1343 any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
1347 By default <prgn>update-rc.d</prgn> will start services in
1348 each of the multi-user state runlevels (2, 3, 4, and 5)
1349 and stop them in the halt runlevel (0), the single-user
1350 runlevel (1) and the reboot runlevel (6). The system
1351 administrator will have the opportunity to customize
1352 runlevels by simply adding, moving, or removing the
1353 symbolic links in <tt>/etc/rc<var>n</var>.d</tt>.</p>
1356 To get the default behaviour for your package, put in your
1357 <tt>postinst</tt> script
1359 update-rc.d <var>package</var> default >/dev/null
1361 and in your <tt>postrm</tt>
1363 if [ purge = "$1" ]; then
1364 update-rc.d <var>package</var> remove >/dev/null
1369 This will use a default sequence number of 20. If it does
1370 not matter when or in which order the script is run, use
1371 this default. If it does, then you should talk to the
1372 maintainer of the <prgn>sysvinit</prgn> package or post to
1373 <tt>debian-devel</tt>, and they will help you choose a
1377 For more information about using <tt>update-rc.d</tt>,
1378 please consult its manpage <manref name="update-rc.d"
1379 section="8">.</p></sect1>
1383 <heading>Boot-time initialisation</heading>
1386 There is another directory, <tt>/etc/rc.boot</tt>, which
1387 contains scripts which are run once per machine boot.
1388 This facility is provided for initialisation of hardware
1389 devices, cleaning up of leftover files, and so forth.</p>
1392 For example, the <prgn>kbd</prgn> package provides a
1393 script here for initialising the keyboard layout and
1394 console font and mode.</p>
1397 The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
1398 links into <tt>/etc/init.d</tt>--they should be the
1399 scripts themselves.</p>
1402 <tt>rc.boot</tt> should <em>not</em> be used for starting
1403 general-purpose daemons and similar activities. This
1404 should be done using the <tt>rc<var>n</var>.d</tt> scheme,
1405 above, so that the services can be started and stopped
1406 cleanly when the runlevel changes or the machine is to be
1407 shut down or rebooted.</p></sect1>
1411 <heading>Notes</heading>
1414 <em>Do not</em> include the
1415 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1416 <tt>.deb</tt> filesystem archive! <em>This will cause
1417 problems!</em> You should create them with
1418 <prgn>update-rc.d</prgn>, as above.</p>
1421 <em>Do not</em> include the <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1422 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1423 problems!</em> <em>Do</em>,
1424 however, include the <tt>/etc/init.d</tt> scripts in
1425 conffiles. (This is important since we want to give the
1426 local system administrator the chance to adapt the scripts
1427 to the local system--e.g., to disable a service without
1428 deinstalling the package, or to specify some special
1429 command line options when starting a service--while making
1430 sure her changes aren't lost during the next package
1431 upgrade.)</p></sect1>
1434 <heading>Example</heading>
1437 The <prgn>bind</prgn> DNS (nameserver) package wants to
1438 make sure that the nameserver is running in multiuser
1439 runlevels, and is properly shut down with the system. It
1440 puts a script in <tt>/etc/init.d</tt>, naming the script
1441 appropriately <tt>bind</tt>. As you can see, the script
1442 interprets the argument <tt>reload</tt> to send the
1443 nameserver a <tt>HUP</tt> signal (causing it to reload its
1444 configuration); this way the user can say
1445 <tt>/etc/init.d/bind reload</tt> to reload the name
1452 # Original version by Robert Leslie
1453 # <rob@mars.org>, edited by iwj and cs
1455 test -x /usr/sbin/named || exit 0
1459 echo -n "Starting domain name service: named"
1460 start-stop-daemon --start --quiet --exec /usr/sbin/named
1464 echo -n "Stopping domain name service: named"
1465 start-stop-daemon --stop --quiet \
1466 --pidfile /var/run/named.pid --exec /usr/sbin/named
1470 echo -n "Restarting domain name service: named"
1471 start-stop-daemon --stop --quiet \
1472 --pidfile /var/run/named.pid --exec /usr/sbin/named
1473 start-stop-daemon --start --verbose --exec /usr/sbin/named
1476 force-reload|reload)
1477 echo -n "Reloading configuration of domain name service: named"
1478 start-stop-daemon --stop --signal 1 --quiet \
1479 --pidfile /var/run/named.pid --exec /usr/sbin/named
1483 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1492 Another example on which to base your <tt>/etc/init.d</tt>
1493 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1496 If this package is happy with the default setup from
1497 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1498 and having named running in all runlevels, it can say in
1499 its <tt>postinst</tt>:
1501 update-rc.d bind default >/dev/null
1503 And in its <tt>postrm</tt>, to remove the links when the
1506 if [ purge = "$1" ]; then
1507 update-rc.d acct remove >/dev/null
1513 <heading>Cron jobs</heading>
1516 Packages may not touch the configuration file
1517 <tt>/etc/crontab</tt>, nor may they modify the files in
1518 <tt>/var/spool/cron/crontabs</tt>.</p>
1521 If a package wants to install a job that has to be executed
1522 via cron, it should place a file with the name if the
1523 package in one of the following directories:
1529 As these directory names say, the files within them are executed on
1530 a daily, weekly, or monthly basis, respectively.</p>
1533 If a certain job has to be executed more frequently than
1534 `daily,' the package should install a file
1535 <tt>/etc/cron.d/<package-name></tt> tagged as
1536 configuration file. This file uses the same syntax as
1537 <tt>/etc/crontab</tt> and is processed by <prgn>cron</prgn>
1538 automatically. (Note, that scripts in the
1539 <tt>/etc/cron.d</tt> directory are not handled by
1540 <prgn>anacron</prgn>. Thus, you should only use this
1541 directory for jobs which may be skipped if the system is not
1545 All files installed in any of these directories have to be
1546 scripts (shell scripts, Perl scripts, etc.) so that they can
1547 easily be modified by the local system administrator. In
1548 addition, they have to be registered as configuration
1552 The scripts in these directories have to check, if all
1553 necessary programs are installed before they try to execute
1554 them. Otherwise, problems will arise when a package was
1555 removed (but not purged), since the configuration files are
1556 kept on the system in this situation.</p></sect>
1560 <heading>Console messages</heading>
1563 This section describes different formats for messages
1564 written to standard output by the <tt>/etc/init.d</tt>
1565 scripts. The intent is to improve the consistency of
1566 Debian's startup and shutdown look and feel.</p>
1569 Please look very careful at the details. We want to get the
1570 messages to look exactly the same way concerning spaces,
1571 punctuation, and case of letters.</p>
1574 Here is a list of overall rules that you should use when you
1575 create output messages. They can be useful if you have a
1576 non-standard message that isn't covered in the sections
1583 Every message should cover one line, start with a
1584 capital letter and end with a period `.'.</p></item>
1589 If you want to express that the computer is working on
1590 something (performing a specific task, not starting or
1591 stopping a program), we use an ``ellipsis'', namely
1592 three dots `...'. Note that we don't insert spaces in
1593 front of or behind the dots. If the task has been
1594 completed we write `done.' and a line feed.</p></item>
1599 Design your messages as if the computer is telling you
1600 what he is doing (let him be polite :-) but don't
1601 mention ``him'' directly. For example, if you think
1604 I'm starting network daemons: nfsd mountd.
1608 Starting network daemons: nfsd mountd.
1609 </example></p></item>
1613 The following formats must be used</p>
1618 <p>when daemons get started.</p>
1621 Use this format if your script starts one or more
1622 daemons. The output should look like this (a single
1623 line, no leading spaces):
1625 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1627 The <description> should describe the subsystem
1628 the daemon or set of daemons are part of, while
1629 <daemon-1> up to <daemon-n> denote each
1630 daemon's name (typically the file name of the
1634 For example, the output of /etc/init.d/lpd would look like:
1636 Starting printer spooler: lpd.
1640 This can be achieved by saying
1642 echo -n "Starting printer spooler: lpd"
1643 start-stop-daemon --start --quiet lpd
1646 in the script. If you have more than one daemon to
1647 start, you should do the following:
1649 echo -n "Starting remote filesystem services:"
1650 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1651 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1652 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1655 This makes it possible for the user to see what takes
1656 so long and when the final daemon has been
1657 started. Please be careful where to put spaces: In the
1658 example above the system administrator can easily
1659 comment out a line if he don't wants to start a
1660 specific daemon, while the displayed message still
1661 looks good.</p></item>
1665 <p>when something needs to be configured.</p>
1668 If you have to set up different parameters of the
1669 system upon boot up, you can use this format:
1671 Setting <parameter> to `<value>'.
1675 You can use the following echo statement to get the quotes right:
1677 echo "Setting DNS domainname to \`"value"'."
1681 Note that the left quotation mark (`) is different
1682 from the right (').</p></item>
1685 <p>when a daemon is stopped.</p>
1688 When you stop a daemon you should issue a message
1689 similar to the startup message, except that `Starting'
1690 is replaced with `Stopping'.</p>
1693 So stopping the printer daemon will like like this:
1695 Stopping printer spooler: lpd.
1696 </example></p></item>
1699 <p>when something is executed.</p>
1702 There a several examples where you have to run a
1703 program at system startup or shutdown to perform a
1704 specific task. For example, setting the system's clock
1705 via `netdate' or killing all processes when the system
1706 comes down. Your message should like this:
1708 Doing something very useful...done.
1710 You should print the `done.' right after the job has been completed,
1711 so that the user gets informed why he has to wait. You can get this
1714 echo -n "Doing something very useful..."
1718 in your script.</p></item>
1721 <p>when the configuration is reloaded.</p>
1724 When a daemon is forced to reload its configuration
1725 files you should use the following format:
1727 Reloading <daemon's-name> configuration...done.
1728 </example></p></item>
1731 <p>when none of the above rules apply.</p>
1734 If you have to print a message that doesn't fit into
1735 the styles described above, you can use something
1736 appropriate, but please have a look at the overall
1737 rules listed above.</p></item>
1742 <heading>Menus</heading>
1745 The Debian <tt>menu</tt> packages provides a unique
1746 interface between packages providing applications and
1747 documents, and <em>menu programs</em> (either X window
1748 managers or text-based menu programs as
1749 <prgn>pdmenu</prgn>).</p>
1752 All packages that provide applications that need not be
1753 passed any special command line arguments for normal
1754 operation should register a menu entry for those
1755 applications, so that users of the <tt>menu</tt> package
1756 will automatically get menu entries in their window
1757 managers, as well in shells like <tt>pdmenu</tt>.</p>
1760 Please refer to the <em>Debian Menu System</em> document
1761 that comes with the <tt>menu</tt> package for information
1762 about how to register your applications and web
1763 documents.</p></sect>
1767 <heading>Keyboard configuration</heading>
1770 To achieve a consistent keyboard configuration (i.e., all
1771 applications interpret a keyboard event the same way) all
1772 programs in the Debian distribution have to be configured to
1773 comply with the following guidelines.</p>
1776 Here is a list that contains certain keys and their interpretation:
1779 <tag><tt><--</tt></tag>
1780 <item><p>delete the character to the left of the cursor</p></item>
1782 <tag><tt>Delete</tt></tag>
1783 <item><p>delete the character to the right of the cursor</p></item>
1785 <tag><tt>Control+H</tt></tag>
1786 <item><p>emacs: the help prefix</p></item>
1789 The interpretation of any keyboard events should be
1790 independent of the terminal that's used (either the console,
1791 X windows, rlogin/telnet session, etc.).</p>
1794 The following list explains how the different programs
1795 should be set up to achieve this:</p>
1798 <list compact="compact">
1799 <item><p>`<tt><--</tt>' generates KB_Backspace in
1802 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1806 X translations are set up to make KB_Backspace
1807 generate ASCII DEL, and to make KB_Delete generate
1808 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1809 the `delete character' key). This must be done by
1810 loading the resources using xrdb on all local X
1811 displays, not using the application defaults, so that
1812 the translation resources used correspond to the
1813 xmodmap settings.</p></item>
1817 The Linux console is configured to make
1818 `<tt><--</tt>' generate DEL, and `Delete' generate
1819 <tt>ESC [ 3 ~</tt> (this is the case at the
1823 X applications are configured so that Backspace
1824 deletes left, and Delete deletes right. Motif
1825 applications already work like this.</p></item>
1827 <item><p>stty erase <tt>^?</tt> .</p></item>
1830 The `xterm' terminfo entry should have <tt>ESC [ 3
1831 ~</tt> for kdch1, just like TERM=linux and
1832 TERM=vt220.</p></item>
1835 Emacs is programmed to map KB_Backspace or the `stty
1836 erase' character to delete-backward-char, and
1837 KB_Delete or kdch1 to delete-forward-char, and
1838 <tt>^H</tt> to help as always.</p></item>
1841 Other applications use the `stty erase' character and
1842 kdch1 for the two delete keys, with ASCII DEL being
1843 `delete previous character' and kdch1 being `delete
1844 character under cursor'.</p></item>
1848 This will solve the problem except for:</p>
1851 <list compact="compact">
1853 Some terminals have a <tt><--</tt> key that cannot
1854 be made to produce anything except <tt>^H</tt>. On
1855 these terminals Emacs help will be unavailable on
1856 <tt>^H</tt> (assuming that the `stty erase' character
1857 takes precedence in Emacs, and has been set
1858 correctly). M-x help or F1 (if available) can be used
1862 Some operating systems use <tt>^H</tt> for stty erase.
1863 However, modern telnet versions and all rlogin
1864 versions propagate stty settings, and almost all UNIX
1865 versions honour stty erase. Where the stty settings
1866 are not propagated correctly things can be made to
1867 work by using stty manually.</p></item>
1870 Some systems (including previous Debian versions) use
1871 xmodmap to arrange for both <tt><--</tt> and Delete
1872 to generate KB_Delete). We can change the behaviour
1873 of their X clients via the same X resources that we
1874 use to do it for our own, or have our clients be
1875 configured via their resources when things are the
1876 other way around. On displays configured like this
1877 Delete will not work, but <tt><--</tt>
1881 Some operating systems have different kdch1 settings
1882 in their terminfo for xterm and others. On these
1883 systems the Delete key will not work correctly when
1884 you log in from a system conforming to our policy, but
1885 <tt><--</tt> will.</p></item>
1892 <heading>Environment variables</heading>
1895 No program may depend on environment variables to get
1896 reasonable defaults. (That's because these environment
1897 variables would have to be set in a system-wide
1898 configuration file like /etc/profile, which is not supported
1902 If a program should depend on environment variables for its
1903 configuration, the program has to be changed to fall back to
1904 a reasonable default configuration if these environment
1905 variables are not present. If this cannot be done easily
1906 (e.g., if the source code of a non-free program is not
1907 available), the program should be replaced by a small
1908 `wrapper' shell script which sets the environment variables
1909 and calls the original program.</p>
1912 Here is an example of a wrapper script for this purpose:
1918 exec /usr/lib/foo/foo "$@"
1922 Furthermore, as <tt>/etc/profile</tt> is a configuration
1923 file of the <prgn>bash</prgn> package, no other package may
1924 put any environment variables or other commands into that
1929 <heading>Files</heading>
1933 <heading>Binaries</heading>
1936 It is not allowed that two packages install programs with
1937 different functionality but with the same filenames. (The
1938 case of two programs having the same functionality but
1939 different implementations is handled via `alternatives.')
1940 If this case happens, one of the programs has to be
1941 renamed. The maintainers should report this to the
1942 developers' mailing and try to find a consensus about
1943 which package will have to be renamed. If a consensus can
1944 not be reached, <em>both</em> programs must be
1948 Generally the following compilation parameters should be used:
1951 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
1953 install -s # (or use strip on the files in debian/tmp)
1957 Note that all installed binaries should be stripped,
1958 either by using the <tt>-s</tt> flag to
1959 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
1960 the binaries after they have been copied into
1961 <tt>debian/tmp</tt> but before the tree is made into a
1965 The <tt>-g</tt> flag is useful on compilation so that you
1966 have available a full set of debugging symbols in your
1967 built source tree, in case anyone should file a bug report
1968 involving (for example) a core dump.</p>
1971 The <tt>-N</tt> flag should not be used. On a.out systems
1972 it may have been useful for some very small binaries, but
1973 for ELF it has no good effect.</p>
1976 It is up to the package maintainer to decide what
1977 compilation options are best for the package. Certain
1978 binaries (such as computationally-intensive programs) may
1979 function better with certain flags (<tt>-O3</tt>, for
1980 example); feel free to use them. Please use good judgment
1981 here. Don't use flags for the sake of it; only use them
1982 if there is good reason to do so. Feel free to override
1983 the upstream author's ideas about which compilation
1984 options are best--they are often inappropriate for our
1985 environment.</p></sect>
1989 <heading>Libraries</heading>
1992 All libraries must have a shared version in the lib
1993 package and a static version in the lib-dev package. The
1994 shared version must be compiled with <tt>-fPIC</tt>, and
1995 the static version must not be. In other words, each
1996 <tt>*.c</tt> file is compiled twice.</p>
1999 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2000 when building a library (either static or shared) to make
2001 the library compatible with LinuxThreads.</p>
2004 Note that all installed shared libraries should be
2007 strip --strip-unneeded <your-lib>
2009 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2010 only the symbols which aren't needed for relocation
2011 processing.) Shared libraries can function perfectly well
2012 when stripped, since the symbols for dynamic linking are
2013 in a separate part of the ELF object file.</p>
2016 Note that under some circumstances it may be useful to
2017 install a shared library unstripped, for example when
2018 building a separate package to support debugging.</p>
2021 Please make sure that you use only released versions of
2022 shared libraries to build your packages; otherwise other
2023 users will not be able to run your binaries
2024 properly. Producing source packages that depend on
2025 unreleased compilers is also usually a bad
2030 <heading>Shared libraries</heading>
2033 Packages involving shared libraries should be split up
2034 into several binary packages.</p>
2037 For a straightforward library which has a development
2038 environment and a runtime kit including just shared
2039 libraries you need to create two packages:
2040 <tt><var>libraryname</var><var>soname</var></tt>
2041 (<var>soname</var> is the shared object name of the shared
2042 library--it's the thing that has to match exactly between
2043 building an executable and running it for the dynamic
2044 linker to be able run the program; usually the
2045 <var>soname</var> is the major number of the library) and
2046 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2049 If you prefer only to support one development version at a
2050 time you may name the development package
2051 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2052 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2053 ensure that the user only installs one development version
2054 at a time (after all, different development versions are
2055 likely to have the same header files in them, causing a
2056 filename clash if both are installed). Typically the
2057 development version will also need an exact version
2058 dependency on the runtime library, to make sure that
2059 compilation and linking happens correctly.</p>
2062 Packages which use the shared library should have a
2063 dependency on the name of the shared library package,
2064 <tt><var>libraryname</var><var>soname</var></tt>. When
2065 the <var>soname</var> changes you can have both versions
2066 of the library installed while moving from the old library
2070 If your package has some run-time support programs which
2071 use the shared library you must <em>not</em> put them in
2072 the shared library package. If you do that then you won't
2073 be able to install several versions of the shared library
2074 without getting filename clashes. Instead, either create
2075 a third package for the runtime binaries (this package
2076 might typically be named
2077 <tt><var>libraryname</var>-runtime</tt>--note the absence
2078 of the <var>soname</var> in the package name) or if the
2079 development package is small include them in there.</p>
2082 If you have several shared libraries built from the same
2083 source tree you can lump them all together into a single
2084 shared library package, provided that you change all their
2085 <var>soname</var>s at once (so that you don't get filename
2086 clashes if you try to install different versions of the
2087 combined shared libraries package).</p>
2090 Follow the directions in the <em>Debian Packaging
2091 Manual</em> for putting the shared library in its package,
2092 and make sure you include a <tt>shlibs</tt> control area
2093 file with details of the dependencies for packages which
2094 use the library.</p>
2097 Shared libraries should <em>not</em> be installed
2098 executable, since <prgn>ld.so</prgn> does not require this
2099 and trying to execute a shared library results in a core
2104 <heading>Scripts</heading>
2107 All command scripts, including the package maintainer
2108 scripts inside the package and used by <prgn>dpkg</prgn>,
2109 should have a <tt>#!</tt> line naming the shell to be used
2110 to interpret them.</p>
2113 In the case of Perl scripts this should be
2114 <tt>#!/usr/bin/perl</tt>.</p>
2117 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2118 should almost certainly start with <tt>set -e</tt> so that
2119 errors are detected. Every script <em>must</em> use
2120 <tt>set -e</tt> or check the exit status of <em>every</em>
2124 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2125 symbolic link to any POSIX compatible shell. Thus, shell
2126 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2127 only use POSIX features. If a script requires non-POSIX
2128 features from the shell interpreter, the appropriate shell
2129 has to be specified in the first line of the script (e.g.,
2130 `<tt>#!/bin/bash</tt>') and the package has to depend on
2131 the package providing the shell (unless the shell package
2132 is marked `Essential', e.g., in the case of
2133 <prgn>bash</prgn>).</p>
2136 Restrict your script to POSIX features when possible so
2137 that it may use <tt>/bin/sh</tt> as its interpreter. If
2138 your script works with <prgn>ash</prgn>, it's probably
2139 POSIX compliant, but if you are in doubt, use
2140 <tt>/bin/bash</tt>.</p>
2143 Perl scripts should check for errors when making any
2144 system calls, including <tt>open</tt>, <tt>print</tt>,
2145 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2148 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2149 as scripting languages. See <em>Csh Programming
2150 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2151 FAQs. It can be found on <ftpsite>rtfm.mit.edu</ftpsite>
2153 <ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</ftppath>.
2154 If an upstream package comes with <prgn>csh</prgn> scripts
2155 then you must make sure that they start with
2156 <tt>#!/bin/csh</tt> and make your package depend on the
2157 <prgn>c-shell</prgn> virtual package.</p>
2160 Any scripts which create files in world-writable
2161 directories (e.g., in <tt>/tmp</tt>) have to use a
2162 mechanism which will fail if a file with the same name
2166 The Debian base distribution provides the
2167 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2168 for use by scripts for this purpose.</p></sect>
2172 <heading>Symbolic links</heading>
2175 In general, symbolic links within a toplevel directory
2176 should be relative, and symbolic links pointing from one
2177 toplevel directory into another should be absolute. (A
2178 toplevel directory is a sub-directory of the root
2182 In addition, symbolic links should be specified as short
2183 as possible, i.e., link targets like `foo/../bar' are
2187 Note that when creating a relative link using
2188 <prgn>ln</prgn> it is not necessary for the target of the
2189 link to exist relative to the working directory you're
2190 running <prgn>ln</prgn> from; nor is it necessary to
2191 change directory to the directory where the link is to be
2192 made. Simply include the string that should appear as the
2193 target of the link (this will be a pathname relative to
2194 the directory in which the link resides) as the first
2195 argument to <prgn>ln</prgn>.</p>
2198 For example, in your <prgn>Makefile</prgn> or
2199 <tt>debian/rules</tt>, do things like:
2201 ln -fs gcc $(prefix)/bin/cc
2202 ln -fs gcc debian/tmp/usr/bin/cc
2203 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2204 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2208 A symbolic link pointing to a compressed file should
2209 always have the same file extension as the referenced
2210 file. (For example, if a file `<tt>foo.gz</tt>' is
2211 referenced by a symbolic link, the filename of the link
2212 has to end with `<tt>.gz</tt>' too, as in
2213 `bar.gz.')</p></sect>
2217 <heading>Device files</heading>
2220 No package may include device files in the package file
2224 If a package needs any special device files that are not
2225 included in the base system, it has to call
2226 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2227 after asking the user for permission to do so.</p>
2230 No package should remove any device files in the
2231 <tt>postrm</tt> or any other script. This is left to the
2232 system administrator.</p>
2235 Debian uses the serial devices
2236 <tt>/dev/tty*</tt>. Programs using the old
2237 <tt>/dev/cu*</tt> devices should be changed to use
2238 <tt>/dev/tty*</tt>.</p></sect>
2242 <heading>Configuration files</heading>
2245 Any configuration files created or used by your package
2246 should reside in <tt>/etc</tt>. If there are several you
2247 should consider creating a subdirectory named after your
2251 It is almost certain that any file in <tt>/etc</tt> that
2252 is in your package's filesystem archive should be listed
2253 in <prgn>dpkg</prgn>'s <tt>conffiles</tt> control area
2254 file. (See the <em>Debian Packaging
2258 Only packages that are tagged <em>conflicting</em> with
2259 each other may specify the same file as
2260 <tt>conffile</tt>. A package may not modify a
2261 configuration file of another package.</p>
2264 If two or more packages use the same configuration file,
2265 one of these packages has to be defined as <em>owner</em>
2266 of the configuration file, i.e., it has to list the file
2267 as <tt>conffile</tt> and has to provide a program that
2268 modifies the configuration file.</p>
2271 The other packages have to depend on the <em>owner</em>
2272 package and use that program to update the configuration
2276 Sometimes it's appropriate to build a new package, which
2277 just provides the basic <em>infrastructure</em> for the
2278 other packages and which manages the shared configuration
2279 files. (Check out the <prgn>sgml-base</prgn> package as an
2283 Files in <tt>/etc/skel</tt> will automatically be copied
2284 into new user accounts by <prgn>adduser</prgn>. They
2285 should not be referenced there by any program.</p>
2288 Therefore, if a program needs a dotfile to exist in
2289 advance in <tt>$HOME</tt> to work sensibly that dotfile
2290 should be installed in <tt>/etc/skel</tt> (and listed in
2291 conffiles, if it is not generated and modified dynamically
2292 by the package's installation scripts).</p>
2295 However, programs that require dotfiles in order to
2296 operate sensibly (dotfiles that they do not create
2297 themselves automatically, that is) are a bad thing, and
2298 programs should be configured by the Debian default
2299 installation as close to normal as possible.</p>
2302 Therefore, if a program in a Debian package needs to be
2303 configured in some way in order to operate sensibly that
2304 configuration should be done in a site-wide global
2305 configuration file elsewhere in <tt>/etc</tt>. Only if
2306 the program doesn't support a site-wide default
2307 configuration and the package maintainer doesn't have time
2308 to add it should a default per-user file be placed in
2309 <tt>/etc/skel</tt>.</p>
2312 <tt>/etc/skel</tt> should be as empty as we can make it.
2313 This is particularly true because there is no easy
2314 mechanism for ensuring that the appropriate dotfiles are
2315 copied into the accounts of existing users when a package
2319 Ideally the sysadmin should not have to do any
2320 configuration other than that done (semi-)automatically by
2321 the <tt>postinst</tt> script.</p>
2325 <heading>Log files</heading>
2328 Log files should usually be named
2329 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2330 log files, or need a separate directory for permissions
2331 reasons (<tt>/var/log</tt> is writable only by
2332 <tt>root</tt>), you should usually create a directory named
2333 <tt>/var/log/<var>package</var></tt>.</p>
2336 Make sure that any log files are rotated occasionally so
2337 that they don't grow indefinitely; the best way to do this
2338 is to use <prgn>savelog</prgn> program in an
2339 <tt>/etc/cron.daily</tt>, <tt>/etc/cron.weekly</tt> or
2340 <tt>/etc/cron.monthly</tt> script. Here is a good example:
2342 [ -d /var/log/apache/. ] || exit 0
2345 if [ -fs access.log ]
2347 savelog -c 7 access.log > /dev/null
2352 Make sure that any log files are removed when the package is
2353 purged (but not when it is only removed), by checking the
2354 argument to the <tt>postrm</tt> script (see the <em>Debian
2355 Packaging Manual</em> for details).</p>
2360 <heading>Permissions and owners</heading>
2363 The rules in this section are guidelines for general use.
2364 If necessary you may deviate from the details below.
2365 However, if you do so you must make sure that what is done
2366 is secure and you must try to be as consistent as possible
2367 with the rest of the system. You should probably also
2368 discuss it on <prgn>debian-devel</prgn> first.</p>
2371 Files should be owned by <tt>root.root</tt>, and made
2372 writable only by the owner and universally readable (and
2373 executable, if appropriate).</p>
2376 Directories should be mode 755 or (for group-writability)
2377 mode 2775. The ownership of the directory should be
2378 consistent with its mode--if a directory is mode 2775, it
2379 should be owned by the group that needs write access to
2383 Setuid and setgid executables should be mode 4755 or 2755
2384 respectively, and owned by the appropriate user or group.
2385 They should not be made unreadable (modes like 4711 or
2386 2711 or even 4111); doing so achieves no extra security,
2387 because anyone can find the binary in the freely available
2388 Debian package--it is merely inconvenient. For the same
2389 reason you should not restrict read or execute permissions
2390 on non-set-id executables.</p>
2393 Some setuid programs need to be restricted to particular
2394 sets of users, using file permissions. In this case they
2395 should be owned by the uid to which they are set-id, and
2396 by the group which should be allowed to execute them.
2397 They should have mode 4754; there is no point in making
2398 them unreadable to those users who must not be allowed to
2402 Do not arrange that the system administrator can only
2403 reconfigure the package to correspond to their local
2404 security policy by changing the permissions on a binary.
2405 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2406 to conffiles and other similar objects) have their
2407 permissions reset to the distributed permissions when the
2408 package is reinstalled. Instead you should consider (for
2409 example) creating a group for people allowed to use the
2410 program(s) and making any setuid executables executable
2411 only by that group.</p>
2414 If you need to create a new user or group for your package
2415 there are two possibilities. Firstly, you may need to
2416 make some files in the binary package be owned by this
2417 user or group, or you may need to compile the user or
2418 group id (rather than just the name) into the binary
2419 (though this latter should be avoided if possible). In
2420 this case you need a statically allocated id.</p>
2423 You must ask for a user or group id from the base system
2424 maintainer, and must not release the package until you
2425 have been allocated one. Once you have been allocated one
2426 you must make the package depend on a version of the base
2427 system with the id present in <tt>/etc/passwd</tt> or
2428 <tt>/etc/group</tt>, or alternatively arrange for your
2429 package to create the user or group itself with the
2430 correct id (using <tt>adduser</tt>) in its pre- or
2431 post-installation script (the latter is to be preferred if
2432 it is possible).</p>
2435 On the other hand, the program may able to determine the
2436 uid or gid from the group name at runtime, so that a
2437 dynamic id can be used. In this case you must choose an
2438 appropriate user or group name, discussing this on
2439 <prgn>debian-devel</prgn> and checking with the base
2440 system maintainer that it is unique and that they do not
2441 wish you to use a statically allocated id instead. When
2442 this has been checked you must arrange for your package to
2443 create the user or group if necessary using
2444 <prgn>adduser</prgn> in the pre- or post-installation
2445 script (again, the latter is to be preferred if it is
2449 Note that changing the numeric value of an id associated with a name
2450 is very difficult, and involves searching the filesystem for all
2451 appropriate files. You need to think carefully whether a static or
2452 dynamic id is required, since changing your mind later will cause
2458 <heading>Customized programs</heading>
2460 <sect id="arch-spec">
2461 <heading>Architecture specification strings</heading>
2464 If a program needs to specify an <em>architecture specification
2465 string</em> in some place, the following format has to be used:
2467 <arch>-<os>
2469 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2470 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2471 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2472 operating system. .</p>
2474 Note, that we don't want to use `<arch>-debian-linux'
2475 to apply to the rule `architecture-vendor-os' since this
2476 would make our programs incompatible to other Linux
2477 distributions. Also note, that we don't use
2478 `<arch>-unknown-linux', since the `unknown' does not
2479 look very good.</p></sect>
2483 <heading>Daemons</heading>
2486 The configuration files <tt>/etc/services</tt>,
2487 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2488 by the <prgn>netbase</prgn> package and may not be modified
2489 by other packages.</p>
2492 If a package requires a new entry in one of these files, the
2493 maintainer has to get in contact with the
2494 <prgn>netbase</prgn> maintainer, who will add the entries
2495 and release a new version of the <prgn>netbase</prgn>
2499 The configuration file <tt>/etc/inetd.conf</tt> may be
2500 modified by the package's scripts only via the
2501 <prgn>update-inetd</prgn> script or the
2502 <prgn>DebianNet.pm</prgn> Perl module.</p>
2505 If a package wants to install an example entry into
2506 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2507 exactly one hash character (#). Such lines are treated as
2508 `commented out by user' by the <prgn>update-inetd</prgn>
2509 script and are not changed or activated during a package
2514 <heading>Editors and pagers</heading>
2517 Some programs have the ability to launch an editor or pager
2518 program to edit or display a text document. Since there are
2519 lots of different editors and pagers available in the Debian
2520 distribution, the system administrator and each user should
2521 have the possibility to choose his/her preferred editor and
2525 In addition, every program should choose a good default
2526 editor/pager if none is selected by the user or system
2530 Thus, every program that launches an editor or pager has to
2531 use the EDITOR or PAGER environment variables to determine
2532 the editor/pager the user wants to get started. If these
2533 variables are not set, the programs `/usr/bin/editor' and
2534 `/usr/bin/pager' have to be used, respectively.</p>
2537 These two files are managed through `alternatives.' That is,
2538 every package providing an editor or pager has to call the
2539 `update-alternatives' script to register these programs.</p>
2542 If it is very hard to adapt a program to make us of the
2543 EDITOR and PAGER variable, that program should be configured
2544 to use `/usr/bin/sensible-editor' and
2545 `/usr/bin/sensible-pager' as editor or pager program,
2546 respectively. These are two scripts provided in the Debian
2547 base system that check the EDITOR and PAGER variables and
2548 launches the appropriate program or falls back to
2549 `/usr/bin/editor' and `/usr/bin/pager', automatically.</p>
2552 Since the Debian base system already provides an editor and
2553 a pager program, there is no need for a package to depend on
2554 `editor' and `pager', nor is it necessary for a package to
2555 provide such virtual packages.</p></sect>
2558 <sect id="web-appl">
2559 <heading>Web servers and applications</heading>
2562 This section describes the locations and URLs that have to
2563 be used by all web servers and web application in the Debian
2569 <p>Cgi-bin executable files are installed in the
2572 /usr/lib/cgi-bin/<cgi-bin-name>
2574 and can be referred to as
2576 http://localhost/cgi-bin/<cgi-bin-name>
2577 </example></p></item>
2580 <item><p>Access to html documents</p>
2583 Html documents for a package are stored in
2584 /usr/doc/<var>package</var> and can be referred to as
2586 http://localhost/doc/<package>/<filename>
2587 </example></p></item>
2590 <item><p>Web Document Root</p>
2593 Web Applications should try to avoid storing files in
2594 the Web Document Root. Instead use the
2595 /usr/doc/<package> directory for documents and
2596 register the Web Application via the menu package. If
2597 access to the web-root is unavoidable then use
2601 as the Document Root. This might be just a
2602 symbolic link to the location where the sysadmin has
2603 put the real document root.</p>
2606 </enumlist></p></sect>
2610 <heading>Mail transport agents</heading>
2613 Debian packages which process electronic mail, whether
2614 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
2615 <em>must</em> make sure that they are compatible with the
2616 configuration decisions below. Failure to do this may
2617 result in lost mail, broken <tt>From:</tt> lines, and other
2618 serious brain damage!</p>
2621 The mail spool is <tt>/var/spool/mail</tt> and the interface
2622 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
2623 per the FSSTND). The mail spool is part of the base system
2624 and not part of the MTA package.</p>
2627 All Debian MUAs and MTAs have to use the <tt>maillock</tt>
2628 and <tt>mailunlock</tt> functions provided by the
2629 <tt>liblockfile</tt> packages to lock and unlock mail
2630 boxes. These functions implement a NFS-safe locking
2631 mechanism. (It is ok if MUAs and MTAs don't link against
2632 liblockfile but use a <em>compatible</em> mechanism. Please
2633 compare the mechanisms very carefully!)</p>
2636 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
2637 unless the user has chosen otherwise. A MUA may remove a
2638 mailbox (unless it has nonstandard permissions) in which
2639 case the MTA or another MUA must recreate it if needed.
2640 Mailboxes must be writable by group mail.</p>
2643 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
2644 be setgid mail to do the locking mentioned above (and
2645 obviously need to avoid accessing other users' mailboxes
2646 using this privilege).</p>
2649 <tt>/etc/aliases</tt> is the source file for the system mail
2650 aliases (e.g., postmaster, usenet, etc.)--it is the one
2651 which the sysadmin and <tt>postinst</tt> scripts may edit.
2652 After <tt>/etc/aliases</tt> is edited the program or human
2653 editing it must call <prgn>newaliases</prgn>. All MTA
2654 packages should come with a <prgn>newaliases</prgn> program,
2655 even if it does nothing, but older MTA packages do not do
2656 this so programs should not fail if <prgn>newaliases</prgn>
2657 cannot be found.</p>
2660 The convention of writing <tt>forward to
2661 <var>address</var></tt> in the mailbox itself is not
2662 supported. Use a <tt>.forward</tt> file instead.</p>
2665 The location for the <prgn>rmail</prgn> program used by UUCP
2666 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
2667 FSSTND. Likewise, <prgn>rsmtp</prgn>, for receiving
2668 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
2672 If you need to know what name to use (for example) on
2673 outgoing news and mail messages which are generated locally,
2674 you should use the file <tt>/etc/mailname</tt>. It will
2675 contain the portion after the username and <tt>@</tt> (at)
2676 sign for email addresses of users on the machine (followed
2680 A package should check for the existence of this file. If
2681 it exists it should use it without comment. (An MTA's
2682 prompting configuration script may wish to prompt the user
2683 even if it finds this file exists.) If it does not exist it
2684 should prompt the user for the value and store it in
2685 <tt>/etc/mailname</tt> as well as using it in the package's
2686 configuration. The prompt should make it clear that the
2687 name will not just be used by that package. For example, in
2688 this situation the INN package says:
2690 Please enter the `mail name' of your system. This is the
2691 hostname portion of the address to be shown on outgoing
2692 news and mail messages. The default is
2693 <var>syshostname</var>, your system's host name. Mail
2694 name [`<var>syshostname</var>']:
2696 where <var>syshostname</var> is the output of <tt>hostname
2697 --fqdn</tt>.</p></sect>
2701 <heading>News system configuration</heading>
2704 All the configuration files related to the NNTP (news)
2705 servers and clients should be located under
2706 <tt>/etc/news</tt>.</p>
2709 There are some configuration issues that apply to a number
2710 of news clients and server packages on the machine. These
2714 <tag>/etc/news/organization</tag>
2715 <item><p>A string which shall appear as the
2716 organization header for all messages posted
2717 by NNTP clients on the machine</p></item>
2719 <tag>/etc/news/server</tag>
2720 <item><p>Contains the FQDN of the upstream NNTP
2721 server, or localhost if the local machine is
2722 an NNTP server.</p></item>
2725 Other global files may be added as required for cross-package news
2726 configuration.</p></sect>
2730 <heading>Programs for the X Windows system</heading>
2733 Some programs can be configured with or without support for
2734 X Windows. Typically these binaries produced when
2735 configured for X will need the X shared libraries to
2739 Such programs should be configured <em>with</em> X support,
2740 and should declare a dependency on <tt>xlib6g</tt> (for the
2741 X11R6 libraries). Users who wish to use the program can
2742 install just the relatively small <tt>xlib6g</tt> package,
2743 and do not need to install the whole of X.</p>
2746 Do not create two versions (one with X support and one
2747 without) of your package.</p>
2750 <em>Application defaults</em> files have to be installed in
2752 <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
2753 considered as part of the program code. Thus, they should
2754 not be modified and should not be tagged as
2755 <em>conffile</em>. If the local system administrator wants
2756 to customise X applications globally, the file
2757 <tt>/etc/X11/Xresources</tt> should be used.</p>
2760 If you package a program that requires a non-free Motif
2761 library, it would be good if you can provide a "foo-smotif"
2762 and a "foo-dmotif" package, containing a (against Motif
2763 libraries) statically and a dynamically linked version,
2764 respectively. This way, users without Motif can use the
2765 package too, while users that have Motif installed get the
2766 advantages of a dynamically linked version.</p>
2769 However, if your package works reliably with lesstif, you
2770 should package it with lesstif, and not with Motif at
2774 Note, that packages that require non-free Motif libraries
2775 can't go into the main section. If your package is free
2776 otherwise, it should go into contrib. Otherwise it has to go
2777 into non-free.</p></sect>
2781 <heading>Emacs lisp programs</heading>
2784 Please refer to the `Debian Emacs Policy' (documented in
2785 <tt>debian-emacs-policy.gz</tt> of the
2786 <prgn>emacsen-common</prgn> package) for details of how to
2787 package emacs lisp programs.</p></sect>
2791 <heading>Games</heading>
2794 The permissions on /var/lib/games are 755
2795 <tt>root.root</tt>.</p>
2798 Each game decides on its own security policy.</p>
2801 Games which require protected, privileged access to
2802 high-score files, savegames, etc., must be made
2803 set-<em>group</em>-id (mode 2755) and owned by
2804 <tt>root.games</tt>, and use files and directories with
2805 appropriate permissions (770 <tt>root.games</tt>, for
2806 example). They must <em>not</em> be made
2807 set-<em>user</em>-id, as this causes security problems. (If
2808 an attacker can subvert any set-user-id game they can
2809 overwrite the executable of any other, causing other players
2810 of these games to run a Trojan horse program. With a
2811 set-group-id game the attacker only gets access to less
2812 important game data, and if they can get at the other
2813 players' accounts at all it will take considerably more
2817 Some packages, for example some fortune cookie programs, are
2818 configured by the upstream authors to install with their
2819 data files or other static information made unreadable so
2820 that they can only be accessed through set-id programs
2821 provided. Do not do this in a Debian package: anyone can
2822 download the <tt>.deb</tt> file and read the data from it,
2823 so there is no point making the files unreadable. Not
2824 making the files unreadable also means that you don't have
2825 to make so many programs set-id, which reduces the risk of a
2829 As described in the FSSTND, binaries of games should be
2830 installed in the directory <tt>/usr/games</tt>. This also
2831 applies to games that use the X windows system. Manual pages
2832 for games (X and non-X games) should be installed in
2833 <tt>/usr/man/man6</tt>.</p>
2837 <chapt><heading>Documentation</heading>
2841 <heading>Manual pages</heading>
2844 You must install manual pages in <prgn>nroff</prgn> source
2845 form, in appropriate places under <tt>/usr/man</tt>. You
2846 should only use sections 1 to 9 (see the FSSTND for more
2847 details). You must <em>not</em> install a preformatted `cat
2851 If no manual page is available for a particular program,
2852 utility or function and this is reported as a bug on
2853 debian-bugs, a symbolic link from the requested manual page
2854 to the <manref name="undocumented" section="7"> manual page
2855 should be provided. This symbolic link can be created from
2856 <tt>debian/rules</tt> like this:
2858 ln -s ../man7/undocumented.7.gz \
2859 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
2861 This manpage claims that the lack of a manpage has been
2862 reported as a bug, so you may only do this if it really has
2863 (you can report it yourself, if you like). Do not close the
2864 bug report until a proper manpage is available.</p>
2867 You may forward a complaint about a missing manpage to the
2868 upstream authors, and mark the bug as forwarded in the
2869 Debian bug tracking system. Even though the GNU Project do
2870 not in general consider the lack of a manpage to be a bug,
2871 we do--if they tell you that they don't consider it a bug
2872 you should leave the bug in our bug tracking system open
2876 Manual pages should be installed compressed using <tt>gzip
2880 If one manpage needs to be accessible via several names it
2881 is better to use a symbolic link than the <tt>.so</tt>
2882 feature, but there is no need to fiddle with the relevant
2883 parts of the upstream source to change from <tt>.so</tt> to
2884 symlinks--don't do it unless it's easy. Do not create hard
2885 links in the manual page directories, and do not put
2886 absolute filenames in <tt>.so</tt> directives. The filename
2887 in a <tt>.so</tt> in a manpage should be relative to the
2888 base of the manpage tree (usually
2889 <tt>/usr/man</tt>).</p></sect>
2893 <heading>Info documents</heading>
2896 Info documents should be installed in <tt>/usr/info</tt>.
2897 They should be compressed with <tt>gzip -9</tt>.</p>
2900 Your package must call <prgn>install-info</prgn> to update the Info
2902 file, in its post-installation script:
2904 install-info --quiet --section Development Development \
2905 /usr/info/foobar.info
2909 It is a good idea to specify a section for the location of
2910 your program; this is done with the <tt>--section</tt>
2911 switch. To determine which section to use, you should look
2912 at <tt>/usr/info/dir</tt> on your system and choose the most
2913 relevant (or create a new section if none of the current
2914 sections are relevant). Note that the <tt>--section</tt>
2915 flag takes two arguments; the first is a regular expression
2916 to match (case-insensitively) against an existing section,
2917 the second is used when creating a new one.</p>
2920 You must remove the entries in the pre-removal script:
2922 install-info --quiet --remove /usr/info/foobar.info
2926 If <prgn>install-info</prgn> cannot find a description entry
2927 in the Info file you will have to supply one. See <manref
2928 name="install-info" section="8"> for details.</p>
2932 <heading>Additional documentation</heading>
2935 Any additional documentation that comes with the package can
2936 be installed at the discretion of the package maintainer.
2937 Text documentation should be installed in a directory
2938 <tt>/usr/doc/<var>package</var></tt>, where
2939 <var>package</var> is the name of the package, and
2940 compressed with <tt>gzip -9</tt> unless it is small.</p>
2943 If a package comes with large amounts of documentation which
2944 many users of the package will not require you should create
2945 a separate binary package to contain it, so that it does not
2946 take up disk space on the machines of users who do not need
2947 or want it installed.</p>
2950 It is often a good idea to put text information files
2951 (<tt>README</tt>s, changelogs, and so forth) that come with
2952 the source package in <tt>/usr/doc/<var>package</var></tt>
2953 in the binary package. However, you don't need to install
2954 the instructions for building and installing the package, of
2959 <heading>Preferred documentation formats</heading>
2962 The unification of Debian documentation is being carried out
2966 If your package comes with extensive documentation in a
2967 markup format that can be converted to various other formats
2968 you should if possible ship HTML versions in a binary
2969 package, in the directory
2970 <tt>/usr/doc/<var>appropriate package</var></tt> or its
2973 <p>The rationale: The important thing here is that HTML
2974 docs should be available in <em>some</em> package, not
2975 necessarily in the main binary package, though. </p>
2980 Other formats such as PostScript may be provided at your
2984 <sect id="copyrightfile">
2985 <heading>Copyright information</heading>
2988 Every package must be accompanied by a verbatim copy of its
2989 copyright and distribution license in the file
2990 /usr/doc/<package-name>/copyright. This file must
2991 neither be compressed nor be a symbolic link.</p>
2994 In addition, the copyright file must say where the upstream
2995 sources (if any) were obtained, and explain briefly what
2996 modifications were made in the Debian version of the package
2997 compared to the upstream one. It must name the original
2998 authors of the package and the Debian maintainer(s) who were
2999 involved with its creation.</p>
3002 /usr/doc/<package-name> may be a symbolic link to a
3003 directory in /usr/doc only if two packages both come from
3004 the same source and the first package has a "Depends"
3005 relationship on the second. These rules are important
3006 because copyrights must be extractable by mechanical
3010 Packages distributed under the UCB BSD license, the Artistic
3011 license, the GNU GPL, and the GNU LGPL should refer to the
3012 files /usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
3013 /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.</p>
3016 Do not use the copyright file as a general <tt>README</tt>
3017 file. If your package has such a file it should be
3018 installed in <tt>/usr/doc/<var>package</var>/README</tt> or
3019 <tt>README.Debian</tt> or some other appropriate place.</p>
3023 <heading>Examples</heading>
3026 Any examples (configurations, source files, whatever),
3027 should be installed in a directory
3028 <tt>/usr/doc/<var>package</var>/examples</tt>. These files
3029 should not be referenced by any program--they're there for
3030 the benefit of the system administrator and users, as
3031 documentation only.</p>
3034 <sect id="instchangelog">
3035 <heading>Changelog files</heading>
3038 This installed file must contain a copy of the
3039 <tt>debian/changelog</tt> file from your Debian source tree,
3040 and a copy of the upstream changelog file if there is one.
3041 The debian/changelog file should be installed in
3042 <tt>/usr/doc/<var>package</var></tt> as
3043 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3044 file is text formatted, it must be accessable as
3045 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>. If the
3046 upstream changelog file is HTML formatted, it must be
3047 accessable as <tt>/usr/doc/<var>package</var>/changelog.html.gz</tt>.
3048 If the upstream changelog files do not already conform to
3049 this naming convention, then this may be achieved by either
3050 renaming the files or adding a symbolic link at the
3051 packaging developer's discretion. </p>
3054 Both should be installed compressed using <tt>gzip -9</tt>,
3055 as they will become large with time even if they start out
3059 If the package has only one changelog which is used both as
3060 the Debian changelog and the upstream one because there is
3061 no separate upstream maintainer then that changelog should
3062 usually be installed as
3063 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>; if there
3064 is a separate upstream maintainer, but no upstream
3065 changelog, then the Debian changelog should still be called
3066 <tt>changelog.Debian.gz</tt>.</p>