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></author>
37 <author><name></name><email></email></author>
38 <version>version &version;, &date;</version>
41 This manual describes the policy requirements for the Debian
42 GNU/Linux distribution. This includes the structure and
43 contents of the Debian archive, several design issues of the
44 operating system, as well as technical requirements that each
45 package must satisfy to be included in the distribution.
50 Copyright ©1996,1997,1998 Ian Jackson
51 and Christian Schwarz.
54 This manual is free software; you may redistribute it and/or
55 modify it under the terms of the GNU General Public License
56 as published by the Free Software Foundation; either version
57 2, or (at your option) any later version.
61 This is distributed in the hope that it will be useful, but
62 <em>without any warranty</em>; without even the implied
63 warranty of merchantability or fitness for a particular
64 purpose. See the GNU General Public License for more
68 A copy of the GNU General Public License is available as
69 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
70 distribution or on the World Wide Web at
71 <url id="http://www.gnu.org/copyleft/gpl.html"
72 name="&urlname">. You can also obtain it by writing to the
73 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
74 Boston, MA 02111-1307, USA.
82 <heading>About this manual</heading>
84 <heading>Scope</heading>
86 This manual describes the policy requirements for the Debian
87 GNU/Linux distribution. This includes the structure and
88 contents of the Debian archive, several design issues of the
89 operating system, as well as technical requirements that
90 each package must satisfy to be included in the
94 This manual does <em>not</em> describe the technical
95 mechanisms involved in package creation, installation, and
96 removal. This information can be found in the <em>Debian
97 Packaging Manual</em> and the <em>Debian System
98 Administrators' Manual</em>.
101 This document assumes familiarity with these other two
102 manuals. Unfortunately, the <em>System Administrators'
103 Manual</em> does not exist yet.
106 Much of the information presented in this manual will be
107 useful even when building a package which is to be
108 distributed in some other way or is for local use.
112 <heading>New versions of this document</heading>
114 The current version of this document is always accessible from the
117 id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz" name="&urlname">
118 or from the Debian WWW server at
119 <url id="http://www.debian.org/doc/manuals/debian-policy/"
123 In addition, this manual is distributed via the Debian package
124 <tt>debian-policy</tt>
128 <heading>Feedback</heading>
131 As the Debian GNU/Linux system is continuously evolving this
132 manual is changed from time to time.
135 While the authors of this document tried hard not to include
136 any typos or other errors these still occur. If you discover
137 an error in this manual or if you want to tell us any
138 comments, suggestions, or critics please send an email to
139 the Debian Policy List,
140 <email>debian-policy@lists.debian.org</email>, or submit a
141 bug report against the <tt>debian-policy</tt> package.
146 <heading>The Debian Archive</heading>
148 The Debian GNU/Linux system is maintained and distributed as a
149 collection of <em>packages</em>. Since there are so many of them (over
150 2600) they are split into <em>sections</em> and <em>priorities</em> to
151 simplify handling of them.
154 The effort of the Debian project is to build a free operating
155 system, but not every package we want to make accessible is
156 <em>free</em> in our sense (see Debian Free Software
157 Guidelines, below), or may be imported/exported without
158 restrictions. Thus, the archive is split into the sections
159 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
160 <em>contrib</em>.</p>
162 The <em>main</em> section forms the <em>Debian GNU/Linux
163 distribution</em>. </p>
165 Packages in the other sections are not considered as part of
166 the Debian distribution, though we support their use, and we
167 provide infrastructure for them (such as our bug-tracking
168 system and mailing lists). This Debian Policy Manual applies
169 to these packages as well.</p>
171 <sect id="pkgcopyright">
172 <heading>Package copyright and sections</heading>
174 The aims of this policy are:
176 <list compact="compact">
178 <p>We want to make as much software available as we
182 <p>We want to encourage everyone to write free software.</p>
185 <p> We want to make it easy for people to produce
186 CD-ROMs of our system without violating any licenses,
187 import/export restrictions, or any other laws.</p>
192 <heading>The Debian Free Software Guidelines</heading>
194 The Debian Free Software Guidelines (DFSG) as is our
195 definition of `free' software.
197 <tag>>Free Redistribution
201 The license of a Debian component may not restrict any
202 party from selling or giving away the software as a
203 component of an aggregate software distribution
204 containing programs from several different
205 sources. The license may not require a royalty or
206 other fee for such sale.
213 The program must include source code, and must allow
214 distribution in source code as well as compiled form.
221 The license must allow modifications and derived
222 works, and must allow them to be distributed under the
223 same terms as the license of the original software.
226 <tag>Integrity of The Author's Source Code
230 The license may restrict source-code from being
231 distributed in modified form <em>only</em> if the
232 license allows the distribution of ``patch files''
233 with the source code for the purpose of modifying the
234 program at build time. The license must explicitly
235 permit distribution of software built from modified
236 source code. The license may require derived works to
237 carry a different name or version number from the
238 original software. (This is a compromise. The Debian
239 group encourages all authors to not restrict any
240 files, source or binary, from being modified.)
243 <tag>No Discrimination Against Persons or Groups
247 The license must not discriminate against any person
251 <tag>No Discrimination Against Fields of Endeavor
255 The license must not restrict anyone from making use
256 of the program in a specific field of endeavor. For
257 example, it may not restrict the program from being
258 used in a business, or from being used for genetic
262 <tag>Distribution of License
266 The rights attached to the program must apply to all
267 to whom the program is redistributed without the need
268 for execution of an additional license by those
272 <tag>License Must Not Be Specific to Debian
276 The rights attached to the program must not depend on
277 the program's being part of a Debian system. If the
278 program is extracted from Debian and used or
279 distributed without Debian but otherwise within the
280 terms of the program's license, all parties to whom
281 the program is redistributed should have the same
282 rights as those that are granted in conjunction with
286 <tag>License Must Not Contaminate Other Software
290 The license must not place restrictions on other
291 software that is distributed along with the licensed
292 software. For example, the license must not insist
293 that all other programs distributed on the same medium
294 must be free software.
297 <tag>Example Licenses
301 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
302 examples of licenses that we consider <em>free</em>.
309 <heading>The main section</heading>
311 Every package in "main" must comply with the DFSG (Debian
312 Free Software Guidelines).</p>
315 In addition, the packages in "main"
316 <list compact="compact">
319 must not require a package outside of "main" for
320 compilation or execution (thus, the package may not
321 declare a "Depends" or "Recommends" relationship on a
327 must not be so buggy that we refuse to support them,
332 must meet all policy requirements presented in this
340 <heading>The contrib section</heading>
342 Every package in "contrib" must comply with the DFSG.
346 Examples of packages which would be included in "contrib" are
347 <list compact="compact">
350 free packages which require "contrib", "non-free", or
351 "non-US" packages or packages which are not in our
352 archive at all for compilation or execution,
357 wrapper packages or other sorts of free accessories for
363 packages which we don't want to support because they are too
369 packages which fail to meet some other policy requirements in
377 <heading>The non-free section</heading>
379 `Non-free' contains packages which are not compliant with
380 the DFSG or which are encumbered by patents or other legal
381 issues that make their distribution problematic.</p>
383 All packages in `non-free' must be electronically
384 distributable across international borders.
388 <heading>The non-us server</heading>
390 Some programs with cryptographic program code must be stored
391 on the "non-us" server because of export restrictions of the
394 This applies only to packages which contain cryptographic
395 code. A package containing a program with an interface to a
396 cryptographic program or a program that's dynamically linked
397 against a cryptographic library can be distributed if it is
398 capable of running without the cryptography library or
403 <heading>Further copyright considerations</heading>
405 Every package must be accompanied by a verbatim copy of its
406 copyright and distribution license in the file
407 /usr/doc/<package-name>/copyright (see <ref
408 id="copyrightfile"> for details).</p>
410 We reserve the right to restrict files from being included
411 anywhere in our archives if
412 <list compact="compact">
415 their use or distribution would break a law,
420 there is an ethical conflict in their distribution or
426 we would have to sign a license for them, or
431 their distribution would conflict with other project
439 Programs whose authors encourage the user to make donations
440 are fine for the main distribution, provided that the
441 authors do not claim that not donating is immoral,
442 unethical, illegal or something similar; otherwise they must
443 go in contrib (or non-free, if even distribution is
444 restricted by such statements).</p>
447 Packages whose copyright permission notices (or patent
448 problems) do not allow redistribution even of only binaries,
449 and where no special permission has been obtained, cannot be
450 placed on the Debian FTP site and its mirrors at all.</p>
453 Note, that under international copyright law (this applies
454 in the United States, too) <em>no</em> distribution or
455 modification of a work is allowed without an explicit notice
456 saying so. Therefore a program without a copyright notice
457 <em>is</em> copyrighted and you may not do anything to it
458 without risking being sued! Likewise if a program has a
459 copyright notice but no statement saying what is permitted
460 then nothing is permitted.</p>
463 Many authors are unaware of the problems that restrictive
464 copyrights (or lack of copyright notices) can cause for the
465 users of their supposedly-free software. It is often
466 worthwhile contacting such authors diplomatically to ask
467 them to modify their license terms. However, this is a
468 politically difficult thing to do and you should ask for
469 advice on <tt>debian-devel</tt> first.</p>
472 When in doubt, send mail to
473 <email>debian-devel@lists.debian.org</email>. Be prepared
474 to provide us with the copyright statement. Software
475 covered by the GPL, public domain software and BSD-like
476 copyrights are safe; be wary of the phrases `commercial use
477 prohibited' and `distribution restricted'.</p>
480 <heading>Subsections</heading>
483 The packages in the <em>main</em>, <em>contrib</em>, and
484 <em>non-free</em> sections are grouped further into
485 <em>subsections</em> to simplify handling of them.</p>
488 The section for each package is specified in the package's
489 <em>control record</em>. However, the maintainer of the
490 Debian archive may override this selection to assure the
491 consistency of the Debian distribution. </p>
494 Please check the current Debian distribution to see which
495 sections are available.</p>
498 <heading>Priorities</heading>
501 Each package is given a certain <em>priority</em> value,
502 which is included in the package's <em>control
503 record</em>. This information is used in the Debian package
504 management tool to separate high-priority packages from
505 less-important packages.</p>
508 The following <em>priority levels</em> are supported by the
509 Debian package management system, <prgn>dpkg</prgn>.
511 <tag><tt>required</tt></tag>
514 <tt>required</tt> packages are necessary for the
515 proper functioning of the system. You must not remove
516 these packages or your system may become totally
517 broken and you may not even be able to use
518 <prgn>dpkg</prgn> to put things back. Systems with
519 only the <tt>required</tt> packages are probably
520 unusable, but they do have enough functionality to
521 allow the sysadmin to boot and install more
524 <tag><tt>important</tt></tag>
527 Important programs, including those which one would
528 expect to find on any Unix-like system. If the
529 expectation is that an experienced Unix person who
530 found it missing would say `What the F*!@<+ is
531 going on, where is <prgn>foo</prgn>', it should be in
532 <tt>important</tt>. This is an important criterion
533 because we are trying to produce, amongst other
534 things, a free Unix. Other packages without which the
535 system will not run well or be usable should also be
536 here. This does <em>not</em> include Emacs or X11 or
537 TeX or any other large applications. The
538 <tt>important</tt> packages are just a bare minimum of
539 commonly-expected and necessary tools.</p>
541 <tag><tt>standard</tt></tag>
544 These packages provide a reasonably small but not too
545 limited character-mode system. This is what will
546 install by default if the user doesn't select anything
547 else. It doesn't include many large applications, but
548 it does include Emacs (this is more of a piece of
549 infrastructure than an application) and a reasonable
550 subset of TeX and LaTeX (if this is possible without
553 <tag><tt>optional</tt></tag>
556 (In a sense everything is optional that isn't
557 required, but that's not what is meant here.) This is
558 all the software that you might reasonably want to
559 install if you didn't know what it was or don't have
560 specialised requirements. This is a much larger system
561 and includes X11, a full TeX distribution, and lots of
564 <tag><tt>extra</tt></tag>
567 This contains packages that conflict with others with
568 higher priorities, or are only likely to be useful if
569 you already know what they are or have specialised
576 Packages may not depend on packages with lower priority
577 values. If this should happen, one of the priority values
578 will have to be adapted.
583 <heading>Binary packages</heading>
586 The Debian GNU/Linux distribution is based on the Debian
587 package management system, called <prgn>dpkg</prgn>. Thus,
588 all packages in the Debian distribution have to be provided
589 in the <tt>.deb</tt> file format.</p>
593 <heading>The package name</heading>
596 Every package must have a name that's unique within the Debian
600 Package names may only consist of lower case letters, digits (0-9),
601 plus (+) or minus (-) signs, and periods (.).</p>
604 The package name is part of the file name of the
605 <tt>.deb</tt> file and is included in the control field
611 <heading>The maintainer of a package</heading>
614 Every package must have exactly one maintainer at a
615 time. This person is responsible that the license of the
616 package's software complies with the policy of the
617 distribution this package is included in.</p>
620 The maintainer must be specified in the
621 <tt>Maintainer</tt> control field with the correct name
622 and a working email address for the Debian maintainer of
623 the package. If one person maintains several packages
624 he/she should try to avoid having different forms of their
625 name and email address in different <tt>Maintainer</tt>
629 If the maintainer of a package quits from the Debian
630 project the Debian QA Group takes over the maintainership
631 of the package until someone else volunteers for that
632 task. These packages are called <em>orphaned
639 <heading>The description of a package</heading>
642 Every Debian package should have an extended description
643 stored in the appropriate field of the control record.</p>
646 The description should be written so that it tells the
647 user what they need to know to decide whether to install
648 the package. This description should not just be copied
649 from the blurb for the program. Instructions for
650 configuring or using the package should not be
651 included--that is what installation scripts, manual pages,
652 Info files, etc. are for. Copyright statements and other
653 administrivia should not be included--that is what the
654 copyright file is for.</p>
659 <heading>Dependencies</heading>
662 Every package has to specify the dependency information
663 about other packages, that are required for the first to
667 For example, for any shared libraries required by
668 dynamically-linked executable binary in a package a
669 dependency entry has to be provided.</p>
672 It is not necessary for other packages to declare any
673 dependencies they have on other packages which are marked
674 <tt>Essential</tt> (see below).</p>
677 Sometimes, a package requires another package to be
678 installed <em>and</em> configured before it can be
679 installed. In this case, you'll have to specify a
680 <tt>Pre-Depends</tt> entry for the package.</p>
683 You must not specify a <tt>Pre-Depends</tt> entry for a
684 package before this has been discussed on the
685 <tt>debian-devel</tt> mailing list and a consensus about
686 doing that has been reached.</p></sect1>
690 <heading>Virtual packages</heading>
693 Sometimes, there are several packages doing more-or-less
694 the same job. In this case, it's useful to define a
695 <em>virtual package</em> who's name describes the function
696 the packages have. (The virtual packages just exist
697 logically, not physically--that's why they are called
698 <em>virtual</em>.) The packages with this particular
699 function will then <em>provide</em> the virtual
700 package. Thus, any other package requiring that function
701 can simply depend on the virtual package without having to
702 specify all possible packages individually.</p>
705 All packages must use virtual package names where
706 appropriate, and arrange to create new ones if necessary.
707 They must not use virtual package names (except privately,
708 amongst a cooperating group of packages) unless they have
709 been agreed upon and appear in the list of virtual package
713 The latest version of the authoritative list of virtual
714 package names can be found on
715 <ftpsite>ftp.debian.org</ftpsite> in
716 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
717 or your local mirror. In addition, it is included in the
718 <tt>debian-policy</tt> package. The procedure for updating
719 the list is described at the top of the file.</p></sect1>
723 <heading>Base packages</heading>
726 The packages included in the <tt>base</tt> section have a
727 special function. They form a minimum subset of the Debian
728 GNU/Linux system that is installed before everything else
729 on a new system. Thus, only very few packages are allowed
730 to go into the <tt>base</tt> section to keep the required
731 disk usage very small.</p>
734 Most of these packages should have the priority value
735 <tt>required</tt> or at least <tt>important</tt>, and many
736 of them will be tagged <tt>essential</tt> (see below).</p>
739 You must not place any packages into the <tt>base</tt>
740 section before this has been discussed on the
741 <tt>debian-devel</tt> mailing list and a consensus about
742 doing that has been reached.</p></sect1>
746 <heading>Essential packages</heading>
749 Some packages are tagged <tt>essential</tt>. (They have
750 <tt>Essential: yes</tt> in their package control record.)
751 This flag is used for packages that are <em>essential</em>
755 Since these packages can not easily be removed (you'll
756 have to specify an extra <em>force option</em> to
757 <prgn>dpkg</prgn>) this flag should only be used where
758 absolutely necessary.
760 A shared library package should not be tagged
761 <em>essential</em>--the dependencies will prevent its
762 premature removal, and we need to be able to remove it
763 when it has been superseded.</p>
766 You must not tag any packages <tt>essential</tt> before
767 this has been discussed on the <tt>debian-devel</tt>
768 mailing and a consensus about doing that has been
773 <heading>Maintainer scripts</heading>
776 The package installation scripts should avoid producing
777 output which it is unnecessary for the user to see and
778 should rely on <prgn>dpkg</prgn> to stave off boredom on
779 the part of a user installing many packages. This means,
780 amongst other things, using the <tt>--quiet</tt> option on
781 <prgn>install-info</prgn>.</p>
784 Packages should try to minimise the amount of prompting
785 they need to do, and they should ensure that the user will
786 only ever be asked each question once. This means that
787 packages should try to use appropriate shared
788 configuration files (such as <tt>/etc/papersize</tt> and
789 <tt>/etc/nntpserver</tt>), rather than each prompting for
790 their own list of required pieces of information.</p>
793 It also means that an upgrade should not ask the same
794 questions again, unless the user has used <tt>dpkg
795 --purge</tt> to remove the package's configuration. The
796 answers to configuration questions should be stored in an
797 appropriate place in <tt>/etc</tt> so that the user can
798 modify them, and how this has been done should be
802 If a package has a vitally important piece of information
803 to pass to the user (such as "don't run me as I am, you
804 must edit the following configuration files first or you
805 risk your system emitting badly-formatted messages"), it
806 should display this in the <prgn>postinst</prgn> script
807 and prompt the user to hit return to acknowledge the
808 message. Copyright messages do not count as vitally
809 important (they belong in
810 <tt>/usr/doc/<var>package</var>/copyright</tt>); neither
811 do instructions on how to use a program (these should be
812 in on line documentation, where all the users can see
816 Any necessary prompting should almost always be confined
817 to the post-installation script, and should be protected
818 with a conditional so that unnecessary prompting doesn't
819 happen if a package's installation fails and the
820 <prgn>postinst</prgn> is called with
821 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
822 <tt>abort-deconfigure</tt>.</p>
825 Errors which occur during the execution of an installation
826 script <em>must</em> be checked and the installation
827 <em>must not</em> continue after an error.</p>
830 Note, that <ref id="scripts">, in general applies to
831 package maintainer scripts, too.</p>
834 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
835 another package without consulting the maintainer of that
839 In order for <prgn>update-alternatives</prgn> to work
840 correctly all the packages which supply an instance of the
841 `shared' command name (or, in general, filename) must use
842 it. You can use <tt>Conflicts</tt> to force the
843 deinstallation of other packages supplying it which do not
844 (yet) use <prgn>update-alternatives</prgn>. It may in
845 this case be appropriate to specify a conflict on earlier
846 versions on something--this is an exception to the usual
847 rule that this is not allowed.</p>
851 <heading>Source packages</heading>
854 <heading>Standards conformance</heading>
857 You should specify the most recent version of the
858 packaging standards with which your package complies in
859 the source package's <tt>Standards-Version</tt> field.</p>
862 This value will be used to file bug reports automatically
863 if your package becomes too much out of date.</p>
866 The value corresponds to a version of the Debian manuals,
867 as can be found on the title page or page headers and
868 footers (depending on the format).</p>
871 The version number has four components--major and minor
872 number and major and minor patch level. When the
873 standards change in a way that requires every package to
874 change the major number will be changed. Significant
875 changes that will require work in many packages will be
876 signaled by a change to the minor number. The major patch
877 level will be changed for any change to the meaning of the
878 standards, however small; the minor patch level will be
879 changed when only cosmetic, typographical or other edits
880 which do not change the meaning are made, or changes which
881 do not affect the contents of packages.</p>
884 You should regularly, and especially if your package has
885 become out of date, check for the newest Policy Manual
886 available and update your package, if necessary. When your
887 package complies with the new standards you may update the
888 <tt>Standards-Version</tt> source package field and
889 release it.</p></sect1>
893 <heading>Changes to the upstream sources</heading>
896 If changes to the source code are made that are generally
897 applicable please try to get them included in the upstream
898 version of the package by supplying the upstream authors
899 with the changes in whatever form they prefer.</p>
902 If you need to configure the package differently for
903 Debian or for Linux, and the upstream source doesn't
904 provide a way to configure it the way you need to, please
905 add such configuration facilities (for example, a new
906 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
907 the patch to the upstream authors, with the default set to
908 the way they originally had it. You can then easily
909 override the default in your <tt>debian/rules</tt> or
910 wherever is appropriate.</p>
913 Please make sure that the <prgn>configure</prgn> utility
914 detects the correct architecture specification string
915 (refer to <ref id="arch-spec"> for details).</p>
918 If you need to edit a <prgn>Makefile</prgn> where
919 GNU-style <prgn>configure</prgn> scripts are used, you
920 should edit the <tt>.in</tt> files rather than editing the
921 <prgn>Makefile</prgn> directly. This allows the user to
922 reconfigure the package if necessary. You should
923 <em>not</em> configure the package and edit the generated
924 <prgn>Makefile</prgn>! This makes it impossible for
925 someone else to later reconfigure the package.</p></sect1>
929 <heading>Documenting your changes</heading>
932 Document your changes and updates to the source package
933 properly in the <tt>debian/changelog</tt> file.</p>
936 A copy of the file which will be installed in
937 <tt>/usr/doc/<var>package</var>/copyright</tt> should be
938 in <tt>debian/copyright</tt>.</p>
941 In non-experimental packages you may only use a format for
942 <tt>debian/changelog</tt> which is supported by the most
943 recent released version of <prgn>dpkg</prgn>. If your
944 format is not supported and there is general support for
945 it you should contact the <prgn>dpkg</prgn> maintainer to
946 have the parser script for your format included in the
947 <prgn>dpkg</prgn> package. (You will need to agree that
948 the parser and its manpage may be distributed under the
949 GNU GPL, just as the rest of <prgn>dpkg</prgn>
954 <heading>Error trapping in makefiles</heading>
957 When <prgn>make</prgn> invokes a command in a makefile
958 (including your package's upstream makefiles and the
959 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
960 means that <tt>sh</tt>'s usual bad error handling
961 properties apply: if you include a miniature script as one
962 of the commands in your makefile you'll find that if you
963 don't do anything about it then errors are not detected
964 and <prgn>make</prgn> will blithely continue after
968 Every time you put more than one shell command (this
969 includes using a loop) in a makefile command you
970 <em>must</em> make sure that errors are trapped. For
971 simple compound commands, such as changing directory and
972 then running a program, using <tt>&&</tt> rather
973 than semicolon as a command separator is sufficient. For
974 more complex commands including most loops and
975 conditionals you must include a separate <tt>set -e</tt>
976 command at the start of every makefile command that's
977 actually one of these miniature shell scripts.</p></sect1>
981 <heading>Obsolete constructs and libraries</heading>
984 The include file <prgn><varargs.h></prgn> is
985 provided to support end-users compiling very old software;
986 the library <tt>libtermcap</tt> is provided to support the
987 execution of software which has been linked against it
988 (either old programs or those such as Netscape which are
989 only available in binary form).</p>
992 Debian packages should be ported to include
993 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
998 <chapt><heading>The Operating System</heading>
1002 <heading>Filesystem hierarchy</heading>
1006 <heading>Linux Filesystem Structure</heading>
1009 The location of all installed files and directories must
1010 comply fully with the Linux Filesystem Structure (FSSTND).
1011 The latest version of this document can be found alongside
1012 this manual or on <ftpsite>tsx-11.mit.edu</ftpsite> in
1013 <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
1014 Specific questions about following the standard may be
1015 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1016 Quinlan, the FSSTND coordinator, at
1017 <email>quinlan@pathname.com</email>.</p></sect1>
1021 <heading>Site-specific programs</heading>
1024 As mandated by the FSSTND no package should place any
1025 files in <tt>/usr/local</tt>, either by putting them in
1026 the filesystem archive to be unpacked by <prgn>dpkg</prgn>
1027 or by manipulating them in their maintainer scripts.</p>
1030 However, the package should create empty directories below
1031 <tt>/usr/local</tt> so that the system administrator knows
1032 where to place site-specific files. These directories
1033 should be removed on package removal if they are
1037 Note, that this applies only to directories <em>below</em>
1038 <tt>/usr/local</tt>, not <em>in</em>
1039 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1040 itself may only contain the sub-directories listed in
1041 FSSTND, section 4.8. However, you may create directories
1042 below them as you wish. You may not remove any of the
1043 directories listed in 4.8, even if you created them.</p>
1046 Since <tt>/usr/local</tt> may be mounted read-only from a
1047 remote server, these directories have to be created and
1048 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1049 maintainer scripts. These scripts must not fail if either
1050 of these operations fail. (In the future, it will be
1051 possible to tell <prgn>dpkg</prgn> not to unpack files
1052 matching certain patterns, so that the directories can be
1053 included in the <tt>.deb</tt> packages and system
1054 administrators who do not wish these directories in
1055 /usr/local do not need to have them.)</p>
1058 For example, the <prgn>emacs</prgn> package will contain
1060 mkdir -p /usr/local/lib/emacs/site-lisp || true
1062 in the <tt>postinst</tt> script, and
1064 rmdir /usr/local/lib/emacs/site-lisp && \
1065 rmdir /usr/local/lib/emacs || \
1068 in the <tt>prerm</tt> script.</p>
1071 If you do create a directory in <tt>/usr/local</tt> for
1072 local additions to a package, you must ensure that
1073 settings in <tt>/usr/local</tt> take precedence over the
1074 equivalents in <tt>/usr</tt>.</p>
1077 The <tt>/usr/local</tt> directory itself and all the subdirectories
1078 created by the package should have permissions 2775 (group-writable
1079 and set-group-id) and be owned by <tt>root.staff</tt>.</p>
1084 <heading>Users and groups</heading>
1087 The Debian system can be configured to use either plain or
1088 shadow passwords.</p>
1091 Some user ids (UIDs) and group ids (GIDs) are reserved
1092 globally for use by certain packages. Because some packages
1093 need to include files which are owned by these users or
1094 groups, or need the ids compiled into binaries, these ids
1095 must be used on any Debian system only for the purpose for
1096 which they are allocated. This is a serious restriction, and
1097 we should avoid getting in the way of local administration
1098 policies. In particular, many sites allocate users and/or
1099 local system groups starting at 100.</p>
1102 Apart from this we should have dynamically allocated ids,
1103 which should by default be arranged in some sensible
1104 order--but the behaviour should be configurable.</p>
1107 No package except <tt>base-passwd</tt> may modify
1108 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1109 <tt>/etc/group</tt>.</p>
1112 The UID and GID ranges are as follows:
1117 Globally allocated by the Debian project, must be the
1118 same on every Debian system. These ids will appear in
1119 the <tt>passwd</tt> and <tt>group</tt> files of all
1120 Debian systems, new ids in this range being added
1121 automatically as the <tt>base-passwd</tt> package is
1125 Packages which need a single statically allocated uid
1126 or gid should use one of these; their maintainers
1127 should ask the <tt>base-passwd</tt> maintainer for
1134 Dynamically allocated system users and groups.
1135 Packages which need a user or group, but can have this
1136 user or group allocated dynamically and differently on
1137 each system, should use `<tt>adduser --system</tt>' to
1138 create the group and/or user. <prgn>adduser</prgn>
1139 will check for the existence of the user or group, and
1140 if necessary choose an unused id based on the ranged
1141 specified in <tt>adduser.conf</tt>.</p></item>
1144 <tag>1000-29999:</tag>
1147 Dynamically allocated user accounts. By default
1148 <prgn>adduser</prgn> will choose UIDs and GIDs for
1149 user accounts in this range, though
1150 <tt>adduser.conf</tt> may be used to modify this
1154 <tag>30000-59999:</tag>
1156 <p>Reserved.</p></item>
1159 <tag>60000-64999:</tag>
1162 Globally allocated by the Debian project, but only
1163 created on demand. The ids are allocated centrally and
1164 statically, but the actual accounts are only created
1165 on users' systems on demand.</p>
1168 These ids are for packages which are obscure or which
1169 require many statically-allocated ids. These packages
1170 should check for and create the accounts in
1171 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1172 <prgn>adduser</prgn> if it has this facility) if
1173 necessary. Packages which are likely to require
1174 further allocations should have a `hole' left after
1175 them in the allocation, to give them room to
1179 <tag>65000-65533:</tag>
1181 <p>Reserved.</p></item>
1186 <p>User `<tt>nobody</tt>.'</p></item>
1192 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1193 because it is the error return sentinel value.</p>
1198 <sect id="sysvinit">
1199 <heading>System run levels</heading>
1203 <heading>Introduction</heading>
1206 The <tt>/etc/init.d</tt> directory contains the scripts
1207 executed by <prgn>init</prgn> at boot time and when init
1208 state (or `runlevel') is changed (see <manref name="init"
1209 section="8">).</p> <p>
1211 These scripts are being referenced by symbolic links in
1212 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1213 changing runlevels, <prgn>init</prgn> looks in the
1214 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1215 it should execute, where <var>n</var> is the runlevel that
1216 is being changed to, or `S' for the boot-up scripts.</p>
1219 The names of the links all have the form
1220 <tt>S<var>mm/<var>script</var></var></tt> or
1221 <tt>K<var>mm/<var>script</var></var></tt> where
1222 <var>mm</var> is a two-digit number and <var>script</var>
1223 is the name of the script (this should be the same as the
1224 name of the actual script in <tt>/etc/init.d</tt>.
1226 When <prgn>init</prgn> changes runlevel first the targets
1227 of the links whose names starting with a <tt>K</tt> are
1228 executed, each with the single argument <tt>stop</tt>,
1229 followed by the scripts prefixed with an <tt>S</tt>, each
1230 with the single argument <tt>start</tt>. The <tt>K</tt>
1231 links are responsible for killing services and the
1232 <tt>S</tt> link for starting services upon entering the
1236 For example, if we are changing from runlevel 2 to
1237 runlevel 3, init will first execute all of the <tt>K</tt>
1238 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1239 all of the <tt>S</tt> prefixed scripts. The links
1240 starting with <tt>K</tt> will cause the referred-to file
1241 to be executed with an argument of <tt>stop</tt>, and the
1242 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1245 The two-digit number <var>mm</var> is used to decide which
1246 order to start and stop things in--low-numbered links have
1247 their scripts run first. For example, the <tt>K20</tt>
1248 scripts will be executed before the <tt>K30</tt> scripts.
1249 This is used when a certain service must be started before
1250 another. For example, the name server <prgn>bind</prgn>
1251 might need to be started before the news server
1252 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1253 access lists. In this case, the script that starts
1254 <prgn>bind</prgn> should have a lower number than the
1255 script that starts <prgn>inn</prgn> so that it runs first:
1264 <heading>Writing the scripts</heading>
1267 Packages can and should place scripts in
1268 <tt>/etc/init.d</tt> to start or stop services at boot
1269 time or during a change of runlevel. These scripts should
1270 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1271 should accept one argument, saying what to do:
1274 <tag><tt>start</tt></tag>
1275 <item><p>start the service,</p></item>
1277 <tag><tt>stop</tt></tag>
1278 <item><p>stop the service,</p></item>
1280 <tag><tt>restart</tt></tag>
1281 <item><p>stop and restart the service,</p></item>
1283 <tag><tt>reload</tt></tag>
1284 <item><p>cause the configuration of the service to be
1285 reloaded without actually stopping and restarting
1286 the service,</p></item>
1288 <tag><tt>force-reload</tt></tag> <item><p>cause the
1289 configuration to be reloaded if the service supports
1290 this, otherwise restart the service.</p></item>
1293 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1294 <tt>force-reload</tt> options must be supported by all
1295 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1296 option is optional.</p>
1299 The <tt>init.d</tt> scripts should ensure that they will
1300 behave sensibly if invoked with <tt>start</tt> when the
1301 service is already running, or with <tt>stop</tt> when it
1302 isn't, and that they don't kill unfortunately-named user
1303 processes. The best way to achieve this is usually to use
1304 <prgn>start-stop-daemon</prgn>.</p>
1307 If a service reloads its configuration automatically (as
1308 in the case of <prgn>cron</prgn>, for example), the
1309 <tt>reload</tt> option of the <tt>init.d</tt> script
1310 should behave as if the configuration has been reloaded
1314 These scripts should not fail obscurely when the
1315 configuration files remain but the package has been
1316 removed, as the default in <prgn>dpkg</prgn> is to leave
1317 configuration files on the system after the package has
1318 been removed. Only when it is executed with the
1319 <tt>--purge</tt> option will dpkg remove configuration
1320 files. Therefore, you should include a <tt>test</tt>
1321 statement at the top of the script, like this:
1323 test -f <var>program-executed-later-in-script</var> || exit 0
1324 </example></p></sect1>
1327 <heading>Managing the links</heading>
1330 A program is provided, <prgn>update-rc.d</prgn>, to make
1331 it easier for package maintainers to arrange for the
1332 proper creation and removal of
1333 <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
1334 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1337 You should use this script to make changes to
1338 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
1339 any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
1343 By default <prgn>update-rc.d</prgn> will start services in
1344 each of the multi-user state runlevels (2, 3, 4, and 5)
1345 and stop them in the halt runlevel (0), the single-user
1346 runlevel (1) and the reboot runlevel (6). The system
1347 administrator will have the opportunity to customize
1348 runlevels by simply adding, moving, or removing the
1349 symbolic links in <tt>/etc/rc<var>n</var>.d</tt>.</p>
1352 To get the default behaviour for your package, put in your
1353 <tt>postinst</tt> script
1355 update-rc.d <var>package</var> default >/dev/null
1357 and in your <tt>postrm</tt>
1359 if [ purge = "$1" ]; then
1360 update-rc.d <var>package</var> remove >/dev/null
1365 This will use a default sequence number of 20. If it does
1366 not matter when or in which order the script is run, use
1367 this default. If it does, then you should talk to the
1368 maintainer of the <prgn>sysvinit</prgn> package or post to
1369 <tt>debian-devel</tt>, and they will help you choose a
1373 For more information about using <tt>update-rc.d</tt>,
1374 please consult its manpage <manref name="update-rc.d"
1375 section="8">.</p></sect1>
1379 <heading>Boot-time initialisation</heading>
1382 There is another directory, <tt>/etc/rc.boot</tt>, which
1383 contains scripts which are run once per machine boot.
1384 This facility is provided for initialisation of hardware
1385 devices, cleaning up of leftover files, and so forth.</p>
1388 For example, the <prgn>kbd</prgn> package provides a
1389 script here for initialising the keyboard layout and
1390 console font and mode.</p>
1393 The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
1394 links into <tt>/etc/init.d</tt>--they should be the
1395 scripts themselves.</p>
1398 <tt>rc.boot</tt> should <em>not</em> be used for starting
1399 general-purpose daemons and similar activities. This
1400 should be done using the <tt>rc<var>n</var>.d</tt> scheme,
1401 above, so that the services can be started and stopped
1402 cleanly when the runlevel changes or the machine is to be
1403 shut down or rebooted.</p></sect1>
1407 <heading>Notes</heading>
1410 <em>Do not</em> include the
1411 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1412 <tt>.deb</tt> filesystem archive! <em>This will cause
1413 problems!</em> You should create them with
1414 <prgn>update-rc.d</prgn>, as above.</p>
1417 <em>Do not</em> include the <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1418 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1419 problems!</em> <em>Do</em>,
1420 however, include the <tt>/etc/init.d</tt> scripts in
1421 conffiles. (This is important since we want to give the
1422 local system administrator the chance to adapt the scripts
1423 to the local system--e.g., to disable a service without
1424 deinstalling the package, or to specify some special
1425 command line options when starting a service--while making
1426 sure her changes aren't lost during the next package
1427 upgrade.)</p></sect1>
1430 <heading>Example</heading>
1433 The <prgn>bind</prgn> DNS (nameserver) package wants to
1434 make sure that the nameserver is running in multiuser
1435 runlevels, and is properly shut down with the system. It
1436 puts a script in <tt>/etc/init.d</tt>, naming the script
1437 appropriately <tt>bind</tt>. As you can see, the script
1438 interprets the argument <tt>reload</tt> to send the
1439 nameserver a <tt>HUP</tt> signal (causing it to reload its
1440 configuration); this way the user can say
1441 <tt>/etc/init.d/bind reload</tt> to reload the name
1448 # Original version by Robert Leslie
1449 # <rob@mars.org>, edited by iwj and cs
1451 test -x /usr/sbin/named || exit 0
1455 echo -n "Starting domain name service: named"
1456 start-stop-daemon --start --quiet --exec /usr/sbin/named
1460 echo -n "Stopping domain name service: named"
1461 start-stop-daemon --stop --quiet \
1462 --pidfile /var/run/named.pid --exec /usr/sbin/named
1466 echo -n "Restarting domain name service: named"
1467 start-stop-daemon --stop --quiet \
1468 --pidfile /var/run/named.pid --exec /usr/sbin/named
1469 start-stop-daemon --start --verbose --exec /usr/sbin/named
1472 force-reload|reload)
1473 echo -n "Reloading configuration of domain name service: named"
1474 start-stop-daemon --stop --signal 1 --quiet \
1475 --pidfile /var/run/named.pid --exec /usr/sbin/named
1479 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1488 Another example on which to base your <tt>/etc/init.d</tt>
1489 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1492 If this package is happy with the default setup from
1493 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1494 and having named running in all runlevels, it can say in
1495 its <tt>postinst</tt>:
1497 update-rc.d bind default >/dev/null
1499 And in its <tt>postrm</tt>, to remove the links when the
1502 if [ purge = "$1" ]; then
1503 update-rc.d acct remove >/dev/null
1509 <heading>Cron jobs</heading>
1512 Packages may not touch the configuration file
1513 <tt>/etc/crontab</tt>, nor may they modify the files in
1514 <tt>/var/spool/cron/crontabs</tt>.</p>
1517 If a package wants to install a job that has to be executed
1518 via cron, it should place a file with the name if the
1519 package in one of the following directories:
1525 As these directory names say, the files within them are executed on
1526 a daily, weekly, or monthly basis, respectively.</p>
1529 If a certain job has to be executed more frequently than
1530 `daily,' the package should install a file
1531 <tt>/etc/cron.d/<package-name></tt> tagged as
1532 configuration file. This file uses the same syntax as
1533 <tt>/etc/crontab</tt> and is processed by <prgn>cron</prgn>
1534 automatically. (Note, that scripts in the
1535 <tt>/etc/cron.d</tt> directory are not handled by
1536 <prgn>anacron</prgn>. Thus, you should only use this
1537 directory for jobs which may be skipped if the system is not
1541 All files installed in any of these directories have to be
1542 scripts (shell scripts, Perl scripts, etc.) so that they can
1543 easily be modified by the local system administrator. In
1544 addition, they have to be registered as configuration
1548 The scripts in these directories have to check, if all
1549 necessary programs are installed before they try to execute
1550 them. Otherwise, problems will arise when a package was
1551 removed (but not purged), since the configuration files are
1552 kept on the system in this situation.</p></sect>
1556 <heading>Console messages</heading>
1559 This section describes different formats for messages
1560 written to standard output by the <tt>/etc/init.d</tt>
1561 scripts. The intent is to improve the consistency of
1562 Debian's startup and shutdown look and feel.</p>
1565 Please look very careful at the details. We want to get the
1566 messages to look exactly the same way concerning spaces,
1567 punctuation, and case of letters.</p>
1570 Here is a list of overall rules that you should use when you
1571 create output messages. They can be useful if you have a
1572 non-standard message that isn't covered in the sections
1579 Every message should cover one line, start with a
1580 capital letter and end with a period `.'.</p></item>
1585 If you want to express that the computer is working on
1586 something (performing a specific task, not starting or
1587 stopping a program), we use an ``ellipsis'', namely
1588 three dots `...'. Note that we don't insert spaces in
1589 front of or behind the dots. If the task has been
1590 completed we write `done.' and a line feed.</p></item>
1595 Design your messages as if the computer is telling you
1596 what he is doing (let him be polite :-) but don't
1597 mention ``him'' directly. For example, if you think
1600 I'm starting network daemons: nfsd mountd.
1604 Starting network daemons: nfsd mountd.
1605 </example></p></item>
1609 The following formats must be used</p>
1614 <p>when daemons get started.</p>
1617 Use this format if your script starts one or more
1618 daemons. The output should look like this (a single
1619 line, no leading spaces):
1621 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1623 The <description> should describe the subsystem
1624 the daemon or set of daemons are part of, while
1625 <daemon-1> up to <daemon-n> denote each
1626 daemon's name (typically the file name of the
1630 For example, the output of /etc/init.d/lpd would look like:
1632 Starting printer spooler: lpd.
1636 This can be achieved by saying
1638 echo -n "Starting printer spooler: lpd"
1639 start-stop-daemon --start --quiet lpd
1642 in the script. If you have more than one daemon to
1643 start, you should do the following:
1645 echo -n "Starting remote filesystem services:"
1646 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1647 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1648 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1651 This makes it possible for the user to see what takes
1652 so long and when the final daemon has been
1653 started. Please be careful where to put spaces: In the
1654 example above the system administrator can easily
1655 comment out a line if he don't wants to start a
1656 specific daemon, while the displayed message still
1657 looks good.</p></item>
1661 <p>when something needs to be configured.</p>
1664 If you have to set up different parameters of the
1665 system upon boot up, you can use this format:
1667 Setting <parameter> to `<value>'.
1671 You can use the following echo statement to get the quotes right:
1673 echo "Setting DNS domainname to \`"value"'."
1677 Note that the left quotation mark (`) is different
1678 from the right (').</p></item>
1681 <p>when a daemon is stopped.</p>
1684 When you stop a daemon you should issue a message
1685 similar to the startup message, except that `Starting'
1686 is replaced with `Stopping'.</p>
1689 So stopping the printer daemon will like like this:
1691 Stopping printer spooler: lpd.
1692 </example></p></item>
1695 <p>when something is executed.</p>
1698 There a several examples where you have to run a
1699 program at system startup or shutdown to perform a
1700 specific task. For example, setting the system's clock
1701 via `netdate' or killing all processes when the system
1702 comes down. Your message should like this:
1704 Doing something very useful...done.
1706 You should print the `done.' right after the job has been completed,
1707 so that the user gets informed why he has to wait. You can get this
1710 echo -n "Doing something very useful..."
1714 in your script.</p></item>
1717 <p>when the configuration is reloaded.</p>
1720 When a daemon is forced to reload its configuration
1721 files you should use the following format:
1723 Reloading <daemon's-name> configuration...done.
1724 </example></p></item>
1727 <p>when none of the above rules apply.</p>
1730 If you have to print a message that doesn't fit into
1731 the styles described above, you can use something
1732 appropriate, but please have a look at the overall
1733 rules listed above.</p></item>
1738 <heading>Menus</heading>
1741 The Debian <tt>menu</tt> packages provides a unique
1742 interface between packages providing applications and
1743 documents, and <em>menu programs</em> (either X window
1744 managers or text-based menu programs as
1745 <prgn>pdmenu</prgn>).</p>
1748 All packages that provide applications that need not be
1749 passed any special command line arguments for normal
1750 operation should register a menu entry for those
1751 applications, so that users of the <tt>menu</tt> package
1752 will automatically get menu entries in their window
1753 managers, as well in shells like <tt>pdmenu</tt>.</p>
1756 Please refer to the <em>Debian Menu System</em> document
1757 that comes with the <tt>menu</tt> package for information
1758 about how to register your applications and web
1759 documents.</p></sect>
1763 <heading>Keyboard configuration</heading>
1766 To achieve a consistent keyboard configuration (i.e., all
1767 applications interpret a keyboard event the same way) all
1768 programs in the Debian distribution have to be configured to
1769 comply with the following guidelines.</p>
1772 Here is a list that contains certain keys and their interpretation:
1775 <tag><tt><--</tt></tag>
1776 <item><p>delete the character to the left of the cursor</p></item>
1778 <tag><tt>Delete</tt></tag>
1779 <item><p>delete the character to the right of the cursor</p></item>
1781 <tag><tt>Control+H</tt></tag>
1782 <item><p>emacs: the help prefix</p></item>
1785 The interpretation of any keyboard events should be
1786 independent of the terminal that's used (either the console,
1787 X windows, rlogin/telnet session, etc.).</p>
1790 The following list explains how the different programs
1791 should be set up to achieve this:</p>
1794 <list compact="compact">
1795 <item><p>`<tt><--</tt>' generates KB_Backspace in
1798 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1802 X translations are set up to make KB_Backspace
1803 generate ASCII DEL, and to make KB_Delete generate
1804 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1805 the `delete character' key). This must be done by
1806 loading the resources using xrdb on all local X
1807 displays, not using the application defaults, so that
1808 the translation resources used correspond to the
1809 xmodmap settings.</p></item>
1813 The Linux console is configured to make
1814 `<tt><--</tt>' generate DEL, and `Delete' generate
1815 <tt>ESC [ 3 ~</tt> (this is the case at the
1819 X applications are configured so that Backspace
1820 deletes left, and Delete deletes right. Motif
1821 applications already work like this.</p></item>
1823 <item><p>stty erase <tt>^?</tt> .</p></item>
1826 The `xterm' terminfo entry should have <tt>ESC [ 3
1827 ~</tt> for kdch1, just like TERM=linux and
1828 TERM=vt220.</p></item>
1831 Emacs is programmed to map KB_Backspace or the `stty
1832 erase' character to delete-backward-char, and
1833 KB_Delete or kdch1 to delete-forward-char, and
1834 <tt>^H</tt> to help as always.</p></item>
1837 Other applications use the `stty erase' character and
1838 kdch1 for the two delete keys, with ASCII DEL being
1839 `delete previous character' and kdch1 being `delete
1840 character under cursor'.</p></item>
1844 This will solve the problem except for:</p>
1847 <list compact="compact">
1849 Some terminals have a <tt><--</tt> key that cannot
1850 be made to produce anything except <tt>^H</tt>. On
1851 these terminals Emacs help will be unavailable on
1852 <tt>^H</tt> (assuming that the `stty erase' character
1853 takes precedence in Emacs, and has been set
1854 correctly). M-x help or F1 (if available) can be used
1858 Some operating systems use <tt>^H</tt> for stty erase.
1859 However, modern telnet versions and all rlogin
1860 versions propagate stty settings, and almost all UNIX
1861 versions honour stty erase. Where the stty settings
1862 are not propagated correctly things can be made to
1863 work by using stty manually.</p></item>
1866 Some systems (including previous Debian versions) use
1867 xmodmap to arrange for both <tt><--</tt> and Delete
1868 to generate KB_Delete). We can change the behaviour
1869 of their X clients via the same X resources that we
1870 use to do it for our own, or have our clients be
1871 configured via their resources when things are the
1872 other way around. On displays configured like this
1873 Delete will not work, but <tt><--</tt>
1877 Some operating systems have different kdch1 settings
1878 in their terminfo for xterm and others. On these
1879 systems the Delete key will not work correctly when
1880 you log in from a system conforming to our policy, but
1881 <tt><--</tt> will.</p></item>
1888 <heading>Environment variables</heading>
1891 No program may depend on environment variables to get
1892 reasonable defaults. (That's because these environment
1893 variables would have to be set in a system-wide
1894 configuration file like /etc/profile, which is not supported
1898 If a program should depend on environment variables for its
1899 configuration, the program has to be changed to fall back to
1900 a reasonable default configuration if these environment
1901 variables are not present. If this cannot be done easily
1902 (e.g., if the source code of a non-free program is not
1903 available), the program should be replaced by a small
1904 `wrapper' shell script which sets the environment variables
1905 and calls the original program.</p>
1908 Here is an example of a wrapper script for this purpose:
1914 exec /usr/lib/foo/foo "$@"
1918 Furthermore, as <tt>/etc/profile</tt> is a configuration
1919 file of the <prgn>bash</prgn> package, no other package may
1920 put any environment variables or other commands into that
1925 <heading>Files</heading>
1929 <heading>Binaries</heading>
1932 It is not allowed that two packages install programs with
1933 different functionality but with the same filenames. (The
1934 case of two programs having the same functionality but
1935 different implementations is handled via `alternatives.')
1936 If this case happens, one of the programs has to be
1937 renamed. The maintainers should report this to the
1938 developers' mailing and try to find a consensus about
1939 which package will have to be renamed. If a consensus can
1940 not be reached, <em>both</em> programs must be
1944 Generally the following compilation parameters should be used:
1947 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
1949 install -s # (or use strip on the files in debian/tmp)
1953 Note that all installed binaries should be stripped,
1954 either by using the <tt>-s</tt> flag to
1955 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
1956 the binaries after they have been copied into
1957 <tt>debian/tmp</tt> but before the tree is made into a
1961 The <tt>-g</tt> flag is useful on compilation so that you
1962 have available a full set of debugging symbols in your
1963 built source tree, in case anyone should file a bug report
1964 involving (for example) a core dump.</p>
1967 The <tt>-N</tt> flag should not be used. On a.out systems
1968 it may have been useful for some very small binaries, but
1969 for ELF it has no good effect.</p>
1972 It is up to the package maintainer to decide what
1973 compilation options are best for the package. Certain
1974 binaries (such as computationally-intensive programs) may
1975 function better with certain flags (<tt>-O3</tt>, for
1976 example); feel free to use them. Please use good judgment
1977 here. Don't use flags for the sake of it; only use them
1978 if there is good reason to do so. Feel free to override
1979 the upstream author's ideas about which compilation
1980 options are best--they are often inappropriate for our
1981 environment.</p></sect>
1985 <heading>Libraries</heading>
1988 All libraries must have a shared version in the lib
1989 package and a static version in the lib-dev package. The
1990 shared version must be compiled with <tt>-fPIC</tt>, and
1991 the static version must not be. In other words, each
1992 <tt>*.c</tt> file is compiled twice.</p>
1995 You have to specify the gcc option <tt>-D_REENTRANT</tt>
1996 when building a library (either static or shared) to make
1997 the library compatible with LinuxThreads.</p>
2000 Note that all installed shared libraries should be
2003 strip --strip-unneeded <your-lib>
2005 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2006 only the symbols which aren't needed for relocation
2007 processing.) Shared libraries can function perfectly well
2008 when stripped, since the symbols for dynamic linking are
2009 in a separate part of the ELF object file.</p>
2012 Note that under some circumstances it may be useful to
2013 install a shared library unstripped, for example when
2014 building a separate package to support debugging.</p>
2017 Please make sure that you use only released versions of
2018 shared libraries to build your packages; otherwise other
2019 users will not be able to run your binaries
2020 properly. Producing source packages that depend on
2021 unreleased compilers is also usually a bad
2026 <heading>Shared libraries</heading>
2029 Packages involving shared libraries should be split up
2030 into several binary packages.</p>
2033 For a straightforward library which has a development
2034 environment and a runtime kit including just shared
2035 libraries you need to create two packages:
2036 <tt><var>libraryname</var><var>soname</var></tt>
2037 (<var>soname</var> is the shared object name of the shared
2038 library--it's the thing that has to match exactly between
2039 building an executable and running it for the dynamic
2040 linker to be able run the program; usually the
2041 <var>soname</var> is the major number of the library) and
2042 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2045 If you prefer only to support one development version at a
2046 time you may name the development package
2047 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2048 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2049 ensure that the user only installs one development version
2050 at a time (after all, different development versions are
2051 likely to have the same header files in them, causing a
2052 filename clash if both are installed). Typically the
2053 development version will also need an exact version
2054 dependency on the runtime library, to make sure that
2055 compilation and linking happens correctly.</p>
2058 Packages which use the shared library should have a
2059 dependency on the name of the shared library package,
2060 <tt><var>libraryname</var><var>soname</var></tt>. When
2061 the <var>soname</var> changes you can have both versions
2062 of the library installed while moving from the old library
2066 If your package has some run-time support programs which
2067 use the shared library you must <em>not</em> put them in
2068 the shared library package. If you do that then you won't
2069 be able to install several versions of the shared library
2070 without getting filename clashes. Instead, either create
2071 a third package for the runtime binaries (this package
2072 might typically be named
2073 <tt><var>libraryname</var>-runtime</tt>--note the absence
2074 of the <var>soname</var> in the package name) or if the
2075 development package is small include them in there.</p>
2078 If you have several shared libraries built from the same
2079 source tree you can lump them all together into a single
2080 shared library package, provided that you change all their
2081 <var>soname</var>s at once (so that you don't get filename
2082 clashes if you try to install different versions of the
2083 combined shared libraries package).</p>
2086 Follow the directions in the <em>Debian Packaging
2087 Manual</em> for putting the shared library in its package,
2088 and make sure you include a <tt>shlibs</tt> control area
2089 file with details of the dependencies for packages which
2090 use the library.</p>
2093 Shared libraries should <em>not</em> be installed
2094 executable, since <prgn>ld.so</prgn> does not require this
2095 and trying to execute a shared library results in a core
2100 <heading>Scripts</heading>
2103 All command scripts, including the package maintainer
2104 scripts inside the package and used by <prgn>dpkg</prgn>,
2105 should have a <tt>#!</tt> line naming the shell to be used
2106 to interpret them.</p>
2109 In the case of Perl scripts this should be
2110 <tt>#!/usr/bin/perl</tt>.</p>
2113 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2114 should almost certainly start with <tt>set -e</tt> so that
2115 errors are detected. Every script <em>must</em> use
2116 <tt>set -e</tt> or check the exit status of <em>every</em>
2120 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2121 symbolic link to any POSIX compatible shell. Thus, shell
2122 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2123 only use POSIX features. If a script requires non-POSIX
2124 features from the shell interpreter, the appropriate shell
2125 has to be specified in the first line of the script (e.g.,
2126 `<tt>#!/bin/bash</tt>') and the package has to depend on
2127 the package providing the shell (unless the shell package
2128 is marked `Essential', e.g., in the case of
2129 <prgn>bash</prgn>).</p>
2132 Restrict your script to POSIX features when possible so
2133 that it may use <tt>/bin/sh</tt> as its interpreter. If
2134 your script works with <prgn>ash</prgn>, it's probably
2135 POSIX compliant, but if you are in doubt, use
2136 <tt>/bin/bash</tt>.</p>
2139 Perl scripts should check for errors when making any
2140 system calls, including <tt>open</tt>, <tt>print</tt>,
2141 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2144 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2145 as scripting languages. See <em>Csh Programming
2146 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2147 FAQs. It can be found on <ftpsite>rtfm.mit.edu</ftpsite>
2149 <ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</ftppath>.
2150 If an upstream package comes with <prgn>csh</prgn> scripts
2151 then you must make sure that they start with
2152 <tt>#!/bin/csh</tt> and make your package depend on the
2153 <prgn>c-shell</prgn> virtual package.</p>
2156 Any scripts which create files in world-writable
2157 directories (e.g., in <tt>/tmp</tt>) have to use a
2158 mechanism which will fail if a file with the same name
2162 The Debian base distribution provides the
2163 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2164 for use by scripts for this purpose.</p></sect>
2168 <heading>Symbolic links</heading>
2171 In general, symbolic links within a toplevel directory
2172 should be relative, and symbolic links pointing from one
2173 toplevel directory into another should be absolute. (A
2174 toplevel directory is a sub-directory of the root
2178 In addition, symbolic links should be specified as short
2179 as possible, i.e., link targets like `foo/../bar' are
2183 Note that when creating a relative link using
2184 <prgn>ln</prgn> it is not necessary for the target of the
2185 link to exist relative to the working directory you're
2186 running <prgn>ln</prgn> from; nor is it necessary to
2187 change directory to the directory where the link is to be
2188 made. Simply include the string that should appear as the
2189 target of the link (this will be a pathname relative to
2190 the directory in which the link resides) as the first
2191 argument to <prgn>ln</prgn>.</p>
2194 For example, in your <prgn>Makefile</prgn> or
2195 <tt>debian/rules</tt>, do things like:
2197 ln -fs gcc $(prefix)/bin/cc
2198 ln -fs gcc debian/tmp/usr/bin/cc
2199 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2200 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2204 A symbolic link pointing to a compressed file should
2205 always have the same file extension as the referenced
2206 file. (For example, if a file `<tt>foo.gz</tt>' is
2207 referenced by a symbolic link, the filename of the link
2208 has to end with `<tt>.gz</tt>' too, as in
2209 `bar.gz.')</p></sect>
2213 <heading>Device files</heading>
2216 No package may include device files in the package file
2220 If a package needs any special device files that are not
2221 included in the base system, it has to call
2222 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2223 after asking the user for permission to do so.</p>
2226 No package should remove any device files in the
2227 <tt>postrm</tt> or any other script. This is left to the
2228 system administrator.</p>
2231 Debian uses the serial devices
2232 <tt>/dev/tty*</tt>. Programs using the old
2233 <tt>/dev/cu*</tt> devices should be changed to use
2234 <tt>/dev/tty*</tt>.</p></sect>
2238 <heading>Configuration files</heading>
2241 Any configuration files created or used by your package
2242 should reside in <tt>/etc</tt>. If there are several you
2243 should consider creating a subdirectory named after your
2247 It is almost certain that any file in <tt>/etc</tt> that
2248 is in your package's filesystem archive should be listed
2249 in <prgn>dpkg</prgn>'s <tt>conffiles</tt> control area
2250 file. (See the <em>Debian Packaging
2254 Only packages that are tagged <em>conflicting</em> with
2255 each other may specify the same file as
2256 <tt>conffile</tt>. A package may not modify a
2257 configuration file of another package.</p>
2260 If two or more packages use the same configuration file,
2261 one of these packages has to be defined as <em>owner</em>
2262 of the configuration file, i.e., it has to list the file
2263 as <tt>conffile</tt> and has to provide a program that
2264 modifies the configuration file.</p>
2267 The other packages have to depend on the <em>owner</em>
2268 package and use that program to update the configuration
2272 Sometimes it's appropriate to build a new package, which
2273 just provides the basic <em>infrastructure</em> for the
2274 other packages and which manages the shared configuration
2275 files. (Check out the <prgn>sgml-base</prgn> package as an
2279 Files in <tt>/etc/skel</tt> will automatically be copied
2280 into new user accounts by <prgn>adduser</prgn>. They
2281 should not be referenced there by any program.</p>
2284 Therefore, if a program needs a dotfile to exist in
2285 advance in <tt>$HOME</tt> to work sensibly that dotfile
2286 should be installed in <tt>/etc/skel</tt> (and listed in
2287 conffiles, if it is not generated and modified dynamically
2288 by the package's installation scripts).</p>
2291 However, programs that require dotfiles in order to
2292 operate sensibly (dotfiles that they do not create
2293 themselves automatically, that is) are a bad thing, and
2294 programs should be configured by the Debian default
2295 installation as close to normal as possible.</p>
2298 Therefore, if a program in a Debian package needs to be
2299 configured in some way in order to operate sensibly that
2300 configuration should be done in a site-wide global
2301 configuration file elsewhere in <tt>/etc</tt>. Only if
2302 the program doesn't support a site-wide default
2303 configuration and the package maintainer doesn't have time
2304 to add it should a default per-user file be placed in
2305 <tt>/etc/skel</tt>.</p>
2308 <tt>/etc/skel</tt> should be as empty as we can make it.
2309 This is particularly true because there is no easy
2310 mechanism for ensuring that the appropriate dotfiles are
2311 copied into the accounts of existing users when a package
2315 Ideally the sysadmin should not have to do any
2316 configuration other than that done (semi-)automatically by
2317 the <tt>postinst</tt> script.</p>
2321 <heading>Log files</heading>
2324 Log files should usually be named
2325 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2326 log files, or need a separate directory for permissions
2327 reasons (<tt>/var/log</tt> is writable only by
2328 <tt>root</tt>), you should usually create a directory named
2329 <tt>/var/log/<var>package</var></tt>.</p>
2332 Make sure that any log files are rotated occasionally so
2333 that they don't grow indefinitely; the best way to do this
2334 is to use <prgn>savelog</prgn> program in an
2335 <tt>/etc/cron.daily</tt>, <tt>/etc/cron.weekly</tt> or
2336 <tt>/etc/cron.monthly</tt> script. Here is a good example:
2338 [ -d /var/log/apache/. ] || exit 0
2341 if [ -fs access.log ]
2343 savelog -c 7 access.log > /dev/null
2348 Make sure that any log files are removed when the package is
2349 purged (but not when it is only removed), by checking the
2350 argument to the <tt>postrm</tt> script (see the <em>Debian
2351 Packaging Manual</em> for details).</p>
2356 <heading>Permissions and owners</heading>
2359 The rules in this section are guidelines for general use.
2360 If necessary you may deviate from the details below.
2361 However, if you do so you must make sure that what is done
2362 is secure and you must try to be as consistent as possible
2363 with the rest of the system. You should probably also
2364 discuss it on <prgn>debian-devel</prgn> first.</p>
2367 Files should be owned by <tt>root.root</tt>, and made
2368 writable only by the owner and universally readable (and
2369 executable, if appropriate).</p>
2372 Directories should be mode 755 or (for group-writability)
2373 mode 2775. The ownership of the directory should be
2374 consistent with its mode--if a directory is mode 2775, it
2375 should be owned by the group that needs write access to
2379 Setuid and setgid executables should be mode 4755 or 2755
2380 respectively, and owned by the appropriate user or group.
2381 They should not be made unreadable (modes like 4711 or
2382 2711 or even 4111); doing so achieves no extra security,
2383 because anyone can find the binary in the freely available
2384 Debian package--it is merely inconvenient. For the same
2385 reason you should not restrict read or execute permissions
2386 on non-set-id executables.</p>
2389 Some setuid programs need to be restricted to particular
2390 sets of users, using file permissions. In this case they
2391 should be owned by the uid to which they are set-id, and
2392 by the group which should be allowed to execute them.
2393 They should have mode 4754; there is no point in making
2394 them unreadable to those users who must not be allowed to
2398 Do not arrange that the system administrator can only
2399 reconfigure the package to correspond to their local
2400 security policy by changing the permissions on a binary.
2401 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2402 to conffiles and other similar objects) have their
2403 permissions reset to the distributed permissions when the
2404 package is reinstalled. Instead you should consider (for
2405 example) creating a group for people allowed to use the
2406 program(s) and making any setuid executables executable
2407 only by that group.</p>
2410 If you need to create a new user or group for your package
2411 there are two possibilities. Firstly, you may need to
2412 make some files in the binary package be owned by this
2413 user or group, or you may need to compile the user or
2414 group id (rather than just the name) into the binary
2415 (though this latter should be avoided if possible). In
2416 this case you need a statically allocated id.</p>
2419 You must ask for a user or group id from the base system
2420 maintainer, and must not release the package until you
2421 have been allocated one. Once you have been allocated one
2422 you must make the package depend on a version of the base
2423 system with the id present in <tt>/etc/passwd</tt> or
2424 <tt>/etc/group</tt>, or alternatively arrange for your
2425 package to create the user or group itself with the
2426 correct id (using <tt>adduser</tt>) in its pre- or
2427 post-installation script (the latter is to be preferred if
2428 it is possible).</p>
2431 On the other hand, the program may able to determine the
2432 uid or gid from the group name at runtime, so that a
2433 dynamic id can be used. In this case you must choose an
2434 appropriate user or group name, discussing this on
2435 <prgn>debian-devel</prgn> and checking with the base
2436 system maintainer that it is unique and that they do not
2437 wish you to use a statically allocated id instead. When
2438 this has been checked you must arrange for your package to
2439 create the user or group if necessary using
2440 <prgn>adduser</prgn> in the pre- or post-installation
2441 script (again, the latter is to be preferred if it is
2445 Note that changing the numeric value of an id associated with a name
2446 is very difficult, and involves searching the filesystem for all
2447 appropriate files. You need to think carefully whether a static or
2448 dynamic id is required, since changing your mind later will cause
2454 <heading>Customized programs</heading>
2456 <sect id="arch-spec">
2457 <heading>Architecture specification strings</heading>
2460 If a program needs to specify an <em>architecture specification
2461 string</em> in some place, the following format has to be used:
2463 <arch>-<os>
2465 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2466 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2467 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2468 operating system. .</p>
2470 Note, that we don't want to use `<arch>-debian-linux'
2471 to apply to the rule `architecture-vendor-os' since this
2472 would make our programs incompatible to other Linux
2473 distributions. Also note, that we don't use
2474 `<arch>-unknown-linux', since the `unknown' does not
2475 look very good.</p></sect>
2479 <heading>Daemons</heading>
2482 The configuration files <tt>/etc/services</tt>,
2483 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2484 by the <prgn>netbase</prgn> package and may not be modified
2485 by other packages.</p>
2488 If a package requires a new entry in one of these files, the
2489 maintainer has to get in contact with the
2490 <prgn>netbase</prgn> maintainer, who will add the entries
2491 and release a new version of the <prgn>netbase</prgn>
2495 The configuration file <tt>/etc/inetd.conf</tt> may be
2496 modified by the package's scripts only via the
2497 <prgn>update-inetd</prgn> script or the
2498 <prgn>DebianNet.pm</prgn> Perl module.</p>
2501 If a package wants to install an example entry into
2502 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2503 exactly one hash character (#). Such lines are treated as
2504 `commented out by user' by the <prgn>update-inetd</prgn>
2505 script and are not changed or activated during a package
2510 <heading>Editors and pagers</heading>
2513 Some programs have the ability to launch an editor or pager
2514 program to edit or display a text document. Since there are
2515 lots of different editors and pagers available in the Debian
2516 distribution, the system administrator and each user should
2517 have the possibility to choose his/her preferred editor and
2521 In addition, every program should choose a good default
2522 editor/pager if none is selected by the user or system
2526 Thus, every program that launches an editor or pager has to
2527 use the EDITOR or PAGER environment variables to determine
2528 the editor/pager the user wants to get started. If these
2529 variables are not set, the programs `/usr/bin/editor' and
2530 `/usr/bin/pager' have to be used, respectively.</p>
2533 These two files are managed through `alternatives.' That is,
2534 every package providing an editor or pager has to call the
2535 `update-alternatives' script to register these programs.</p>
2538 If it is very hard to adapt a program to make us of the
2539 EDITOR and PAGER variable, that program should be configured
2540 to use `/usr/bin/sensible-editor' and
2541 `/usr/bin/sensible-pager' as editor or pager program,
2542 respectively. These are two scripts provided in the Debian
2543 base system that check the EDITOR and PAGER variables and
2544 launches the appropriate program or falls back to
2545 `/usr/bin/editor' and `/usr/bin/pager', automatically.</p>
2548 Since the Debian base system already provides an editor and
2549 a pager program, there is no need for a package to depend on
2550 `editor' and `pager', nor is it necessary for a package to
2551 provide such virtual packages.</p></sect>
2554 <sect id="web-appl">
2555 <heading>Web servers and applications</heading>
2558 This section describes the locations and URLs that have to
2559 be used by all web servers and web application in the Debian
2565 <p>Cgi-bin executable files are installed in the
2568 /usr/lib/cgi-bin/<cgi-bin-name>
2570 and can be referred to as
2572 http://localhost/cgi-bin/<cgi-bin-name>
2573 </example></p></item>
2576 <item><p>Access to html documents</p>
2579 Html documents for a package are stored in
2580 /usr/doc/<var>package</var> and can be referred to as
2582 http://localhost/doc/<package>/<filename>
2583 </example></p></item>
2586 <item><p>Web Document Root</p>
2589 Web Applications should try to avoid storing files in
2590 the Web Document Root. Instead use the
2591 /usr/doc/<package> directory for documents and
2592 register the Web Application via the menu package. If
2593 access to the web-root is unavoidable then use
2597 as the Document Root. This might be just a
2598 symbolic link to the location where the sysadmin has
2599 put the real document root.</p>
2602 </enumlist></p></sect>
2606 <heading>Mail transport agents</heading>
2609 Debian packages which process electronic mail, whether
2610 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
2611 <em>must</em> make sure that they are compatible with the
2612 configuration decisions below. Failure to do this may
2613 result in lost mail, broken <tt>From:</tt> lines, and other
2614 serious brain damage!</p>
2617 The mail spool is <tt>/var/spool/mail</tt> and the interface
2618 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
2619 per the FSSTND). The mail spool is part of the base system
2620 and not part of the MTA package.</p>
2623 All Debian MUAs and MTAs have to use the <tt>maillock</tt>
2624 and <tt>mailunlock</tt> functions provided by the
2625 <tt>liblockfile</tt> packages to lock and unlock mail
2626 boxes. These functions implement a NFS-safe locking
2627 mechanism. (It is ok if MUAs and MTAs don't link against
2628 liblockfile but use a <em>compatible</em> mechanism. Please
2629 compare the mechanisms very carefully!)</p>
2632 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
2633 unless the user has chosen otherwise. A MUA may remove a
2634 mailbox (unless it has nonstandard permissions) in which
2635 case the MTA or another MUA must recreate it if needed.
2636 Mailboxes must be writable by group mail.</p>
2639 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
2640 be setgid mail to do the locking mentioned above (and
2641 obviously need to avoid accessing other users' mailboxes
2642 using this privilege).</p>
2645 <tt>/etc/aliases</tt> is the source file for the system mail
2646 aliases (e.g., postmaster, usenet, etc.)--it is the one
2647 which the sysadmin and <tt>postinst</tt> scripts may edit.
2648 After <tt>/etc/aliases</tt> is edited the program or human
2649 editing it must call <prgn>newaliases</prgn>. All MTA
2650 packages should come with a <prgn>newaliases</prgn> program,
2651 even if it does nothing, but older MTA packages do not do
2652 this so programs should not fail if <prgn>newaliases</prgn>
2653 cannot be found.</p>
2656 The convention of writing <tt>forward to
2657 <var>address</var></tt> in the mailbox itself is not
2658 supported. Use a <tt>.forward</tt> file instead.</p>
2661 The location for the <prgn>rmail</prgn> program used by UUCP
2662 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
2663 FSSTND. Likewise, <prgn>rsmtp</prgn>, for receiving
2664 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
2668 If you need to know what name to use (for example) on
2669 outgoing news and mail messages which are generated locally,
2670 you should use the file <tt>/etc/mailname</tt>. It will
2671 contain the portion after the username and <tt>@</tt> (at)
2672 sign for email addresses of users on the machine (followed
2676 A package should check for the existence of this file. If
2677 it exists it should use it without comment. (An MTA's
2678 prompting configuration script may wish to prompt the user
2679 even if it finds this file exists.) If it does not exist it
2680 should prompt the user for the value and store it in
2681 <tt>/etc/mailname</tt> as well as using it in the package's
2682 configuration. The prompt should make it clear that the
2683 name will not just be used by that package. For example, in
2684 this situation the INN package says:
2686 Please enter the `mail name' of your system. This is the
2687 hostname portion of the address to be shown on outgoing
2688 news and mail messages. The default is
2689 <var>syshostname</var>, your system's host name. Mail
2690 name [`<var>syshostname</var>']:
2692 where <var>syshostname</var> is the output of <tt>hostname
2693 --fqdn</tt>.</p></sect>
2697 <heading>News system configuration</heading>
2700 All the configuration files related to the NNTP (news)
2701 servers and clients should be located under
2702 <tt>/etc/news</tt>.</p>
2705 There are some configuration issues that apply to a number
2706 of news clients and server packages on the machine. These
2710 <tag>/etc/news/organization</tag>
2711 <item><p>A string which shall appear as the
2712 organization header for all messages posted
2713 by NNTP clients on the machine</p></item>
2715 <tag>/etc/news/server</tag>
2716 <item><p>Contains the FQDN of the upstream NNTP
2717 server, or localhost if the local machine is
2718 an NNTP server.</p></item>
2721 Other global files may be added as required for cross-package news
2722 configuration.</p></sect>
2726 <heading>Programs for the X Windows system</heading>
2729 Some programs can be configured with or without support for
2730 X Windows. Typically these binaries produced when
2731 configured for X will need the X shared libraries to
2735 Such programs should be configured <em>with</em> X support,
2736 and should declare a dependency on <tt>xlib6g</tt> (for the
2737 X11R6 libraries). Users who wish to use the program can
2738 install just the relatively small <tt>xlib6g</tt> package,
2739 and do not need to install the whole of X.</p>
2742 Do not create two versions (one with X support and one
2743 without) of your package.</p>
2746 <em>Application defaults</em> files have to be installed in
2748 <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
2749 considered as part of the program code. Thus, they should
2750 not be modified and should not be tagged as
2751 <em>conffile</em>. If the local system administrator wants
2752 to customise X applications globally, the file
2753 <tt>/etc/X11/Xresources</tt> should be used.</p>
2756 If you package a program that requires a non-free Motif
2757 library, it would be good if you can provide a "foo-smotif"
2758 and a "foo-dmotif" package, containing a (against Motif
2759 libraries) statically and a dynamically linked version,
2760 respectively. This way, users without Motif can use the
2761 package too, while users that have Motif installed get the
2762 advantages of a dynamically linked version.</p>
2765 However, if your package works reliably with lesstif, you
2766 should package it with lesstif, and not with Motif at
2770 Note, that packages that require non-free Motif libraries
2771 can't go into the main section. If your package is free
2772 otherwise, it should go into contrib. Otherwise it has to go
2773 into non-free.</p></sect>
2777 <heading>Emacs lisp programs</heading>
2780 Please refer to the `Debian Emacs Policy' (documented in
2781 <tt>debian-emacs-policy.gz</tt> of the
2782 <prgn>emacsen-common</prgn> package) for details of how to
2783 package emacs lisp programs.</p></sect>
2787 <heading>Games</heading>
2790 The permissions on /var/lib/games are 755
2791 <tt>root.root</tt>.</p>
2794 Each game decides on its own security policy.</p>
2797 Games which require protected, privileged access to
2798 high-score files, savegames, etc., must be made
2799 set-<em>group</em>-id (mode 2755) and owned by
2800 <tt>root.games</tt>, and use files and directories with
2801 appropriate permissions (770 <tt>root.games</tt>, for
2802 example). They must <em>not</em> be made
2803 set-<em>user</em>-id, as this causes security problems. (If
2804 an attacker can subvert any set-user-id game they can
2805 overwrite the executable of any other, causing other players
2806 of these games to run a Trojan horse program. With a
2807 set-group-id game the attacker only gets access to less
2808 important game data, and if they can get at the other
2809 players' accounts at all it will take considerably more
2813 Some packages, for example some fortune cookie programs, are
2814 configured by the upstream authors to install with their
2815 data files or other static information made unreadable so
2816 that they can only be accessed through set-id programs
2817 provided. Do not do this in a Debian package: anyone can
2818 download the <tt>.deb</tt> file and read the data from it,
2819 so there is no point making the files unreadable. Not
2820 making the files unreadable also means that you don't have
2821 to make so many programs set-id, which reduces the risk of a
2825 As described in the FSSTND, binaries of games should be
2826 installed in the directory <tt>/usr/games</tt>. This also
2827 applies to games that use the X windows system. Manual pages
2828 for games (X and non-X games) should be installed in
2829 <tt>/usr/man/man6</tt>.</p>
2833 <chapt><heading>Documentation</heading>
2837 <heading>Manual pages</heading>
2840 You must install manual pages in <prgn>nroff</prgn> source
2841 form, in appropriate places under <tt>/usr/man</tt>. You
2842 should only use sections 1 to 9 (see the FSSTND for more
2843 details). You must <em>not</em> install a preformatted `cat
2847 If no manual page is available for a particular program,
2848 utility or function and this is reported as a bug on
2849 debian-bugs, a symbolic link from the requested manual page
2850 to the <manref name="undocumented" section="7"> manual page
2851 should be provided. This symbolic link can be created from
2852 <tt>debian/rules</tt> like this:
2854 ln -s ../man7/undocumented.7.gz \
2855 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
2857 This manpage claims that the lack of a manpage has been
2858 reported as a bug, so you may only do this if it really has
2859 (you can report it yourself, if you like). Do not close the
2860 bug report until a proper manpage is available.</p>
2863 You may forward a complaint about a missing manpage to the
2864 upstream authors, and mark the bug as forwarded in the
2865 Debian bug tracking system. Even though the GNU Project do
2866 not in general consider the lack of a manpage to be a bug,
2867 we do--if they tell you that they don't consider it a bug
2868 you should leave the bug in our bug tracking system open
2872 Manual pages should be installed compressed using <tt>gzip
2876 If one manpage needs to be accessible via several names it
2877 is better to use a symbolic link than the <tt>.so</tt>
2878 feature, but there is no need to fiddle with the relevant
2879 parts of the upstream source to change from <tt>.so</tt> to
2880 symlinks--don't do it unless it's easy. Do not create hard
2881 links in the manual page directories, and do not put
2882 absolute filenames in <tt>.so</tt> directives. The filename
2883 in a <tt>.so</tt> in a manpage should be relative to the
2884 base of the manpage tree (usually
2885 <tt>/usr/man</tt>).</p></sect>
2889 <heading>Info documents</heading>
2892 Info documents should be installed in <tt>/usr/info</tt>.
2893 They should be compressed with <tt>gzip -9</tt>.</p>
2896 Your package must call <prgn>install-info</prgn> to update the Info
2898 file, in its post-installation script:
2900 install-info --quiet --section Development Development \
2901 /usr/info/foobar.info
2905 It is a good idea to specify a section for the location of
2906 your program; this is done with the <tt>--section</tt>
2907 switch. To determine which section to use, you should look
2908 at <tt>/usr/info/dir</tt> on your system and choose the most
2909 relevant (or create a new section if none of the current
2910 sections are relevant). Note that the <tt>--section</tt>
2911 flag takes two arguments; the first is a regular expression
2912 to match (case-insensitively) against an existing section,
2913 the second is used when creating a new one.</p>
2916 You must remove the entries in the pre-removal script:
2918 install-info --quiet --remove /usr/info/foobar.info
2922 If <prgn>install-info</prgn> cannot find a description entry
2923 in the Info file you will have to supply one. See <manref
2924 name="install-info" section="8"> for details.</p>
2928 <heading>Additional documentation</heading>
2931 Any additional documentation that comes with the package can
2932 be installed at the discretion of the package maintainer.
2933 Text documentation should be installed in a directory
2934 <tt>/usr/doc/<var>package</var></tt>, where
2935 <var>package</var> is the name of the package, and
2936 compressed with <tt>gzip -9</tt> unless it is small.</p>
2939 If a package comes with large amounts of documentation which
2940 many users of the package will not require you should create
2941 a separate binary package to contain it, so that it does not
2942 take up disk space on the machines of users who do not need
2943 or want it installed.</p>
2946 It is often a good idea to put text information files
2947 (<tt>README</tt>s, changelogs, and so forth) that come with
2948 the source package in <tt>/usr/doc/<var>package</var></tt>
2949 in the binary package. However, you don't need to install
2950 the instructions for building and installing the package, of
2955 <heading>Preferred documentation formats</heading>
2958 The unification of Debian documentation is being carried out
2962 If your package comes with extensive documentation in a
2963 markup format that can be converted to various other formats
2964 you should if possible ship HTML versions in a binary
2965 package, in the directory
2966 <tt>/usr/doc/<var>appropriate package</var></tt> or its
2969 <p>The rationale: The important thing here is that HTML
2970 docs should be available in <em>some</em> package, not
2971 necessarily in the main binary package, though. </p>
2976 Other formats such as PostScript may be provided at your
2980 <sect id="copyrightfile">
2981 <heading>Copyright information</heading>
2984 Every package must be accompanied by a verbatim copy of its
2985 copyright and distribution license in the file
2986 /usr/doc/<package-name>/copyright. This file must
2987 neither be compressed nor be a symbolic link.</p>
2990 In addition, the copyright file must say where the upstream
2991 sources (if any) were obtained, and explain briefly what
2992 modifications were made in the Debian version of the package
2993 compared to the upstream one. It must name the original
2994 authors of the package and the Debian maintainer(s) who were
2995 involved with its creation.</p>
2998 /usr/doc/<package-name> may be a symbolic link to a
2999 directory in /usr/doc only if two packages both come from
3000 the same source and the first package has a "Depends"
3001 relationship on the second. These rules are important
3002 because copyrights must be extractable by mechanical
3006 Packages distributed under the UCB BSD license, the Artistic
3007 license, the GNU GPL, and the GNU LGPL should refer to the
3008 files /usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
3009 /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.</p>
3012 Do not use the copyright file as a general <tt>README</tt>
3013 file. If your package has such a file it should be
3014 installed in <tt>/usr/doc/<var>package</var>/README</tt> or
3015 <tt>README.Debian</tt> or some other appropriate place.</p>
3019 <heading>Examples</heading>
3022 Any examples (configurations, source files, whatever),
3023 should be installed in a directory
3024 <tt>/usr/doc/<var>package</var>/examples</tt>. These files
3025 should not be referenced by any program--they're there for
3026 the benefit of the system administrator and users, as
3027 documentation only.</p>
3030 <sect id="instchangelog">
3031 <heading>Changelog files</heading>
3034 This installed file must contain a copy of the
3035 <tt>debian/changelog</tt> file from your Debian source tree,
3036 and a copy of the upstream changelog file if there is one.
3037 The debian/changelog file should be installed in
3038 <tt>/usr/doc/<var>package</var></tt> as
3039 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3040 file is text formatted, it must be accessable as
3041 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>. If the
3042 upstream changelog file is HTML formatted, it must be
3043 accessable as <tt>/usr/doc/<var>package</var>/changelog.html.gz</tt>.
3044 If the upstream changelog files do not already conform to
3045 this naming convention, then this may be achieved by either
3046 renaming the files or adding a symbolic link at the
3047 packaging developer's discretion. </p>
3050 Both should be installed compressed using <tt>gzip -9</tt>,
3051 as they will become large with time even if they start out
3055 If the package has only one changelog which is used both as
3056 the Debian changelog and the upstream one because there is
3057 no separate upstream maintainer then that changelog should
3058 usually be installed as
3059 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>; if there
3060 is a separate upstream maintainer, but no upstream
3061 changelog, then the Debian changelog should still be called
3062 <tt>changelog.Debian.gz</tt>.</p>