1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
8 Debian GNU/Linux Policy Manual.
9 Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
10 released under the terms of the GNU
11 General Public License, version 2 or (at your option) any later.
12 Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
13 Revised November 27, 1996, David A. Morris, bweaver@debian.org
14 New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
15 Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
16 Maintainer since 1997, Christian Schwarz, schwarz@debian.org
17 Christoph Lameter contributed the "Web Standard"
18 The debian-policy mailing list has taken responsibility for the
19 contents of this document since September 1998, with the package
20 maintainers responsible for packagingn adminstrivia only.
25 <title>Debian Policy Manual</title>
27 <name>Ian Jackson </name>
28 <email>ijackson@gnu.ai.mit.edu</email>
31 <name>Christian Schwarz</name>
32 <email>schwarz@debian.org</email>
35 <name>revised: David A. Morris</name>
36 <email>bweaver@debian.org</email>
39 <name>The Debian Policy mailing List</name>
40 <email>debian-policy@lists.debian.org</email>
42 <version>version &version;, &date;</version>
45 This manual describes the policy requirements for the Debian
46 GNU/Linux distribution. This includes the structure and
47 contents of the Debian archive, several design issues of the
48 operating system, as well as technical requirements that each
49 package must satisfy to be included in the distribution. The
50 policy package itself is maintained by a group of maintainers
51 that have no editorial powers. At the moment, the list of
55 <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
58 <p>Richard Braakman <email>dark@xs4all.nl</email></p>
61 <p>Philip Hands <email>phil@hands.com</email></p>
64 <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
72 Copyright ©1996,1997,1998 Ian Jackson
73 and Christian Schwarz.
76 This manual is free software; you may redistribute it and/or
77 modify it under the terms of the GNU General Public License
78 as published by the Free Software Foundation; either version
79 2, or (at your option) any later version.
83 This is distributed in the hope that it will be useful, but
84 <em>without any warranty</em>; without even the implied
85 warranty of merchantability or fitness for a particular
86 purpose. See the GNU General Public License for more
90 A copy of the GNU General Public License is available as
91 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
92 distribution or on the World Wide Web at
93 <url id="http://www.gnu.org/copyleft/gpl.html"
94 name="&urlname">. You can also obtain it by writing to the
95 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
96 Boston, MA 02111-1307, USA.
104 <heading>About this manual</heading>
106 <heading>Scope</heading>
108 This manual describes the policy requirements for the Debian
109 GNU/Linux distribution. This includes the structure and
110 contents of the Debian archive, several design issues of the
111 operating system, as well as technical requirements that
112 each package must satisfy to be included in the
116 This manual does <em>not</em> describe the technical
117 mechanisms involved in package creation, installation, and
118 removal. This information can be found in the <em>Debian
119 Packaging Manual</em> and the <em>Debian System
120 Administrators' Manual</em>.
123 This document assumes familiarity with these other two
124 manuals. Unfortunately, the <em>System Administrators'
125 Manual</em> does not exist yet.
128 Much of the information presented in this manual will be
129 useful even when building a package which is to be
130 distributed in some other way or is for local use.
134 <heading>New versions of this document</heading>
136 The current version of this document is always accessible from the
139 id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz" name="&urlname">
140 or from the Debian WWW server at
141 <url id="http://www.debian.org/doc/manuals/debian-policy/"
145 In addition, this manual is distributed via the Debian package
146 <tt>debian-policy</tt>
150 <heading>Feedback</heading>
153 As the Debian GNU/Linux system is continuously evolving this
154 manual is changed from time to time.
157 While the authors of this document tried hard not to include
158 any typos or other errors these still occur. If you discover
159 an error in this manual or if you want to tell us any
160 comments, suggestions, or critics please send an email to
161 the Debian Policy List,
162 <email>debian-policy@lists.debian.org</email>, or submit a
163 bug report against the <tt>debian-policy</tt> package.
168 <heading>The Debian Archive</heading>
170 The Debian GNU/Linux system is maintained and distributed as a
171 collection of <em>packages</em>. Since there are so many of them (over
172 2600) they are split into <em>sections</em> and <em>priorities</em> to
173 simplify handling of them.
176 The effort of the Debian project is to build a free operating
177 system, but not every package we want to make accessible is
178 <em>free</em> in our sense (see Debian Free Software
179 Guidelines, below), or may be imported/exported without
180 restrictions. Thus, the archive is split into the sections
181 <em>main</em>, <em>non-us</em>, <em>non-free</em>, and
182 <em>contrib</em>.</p>
184 The <em>main</em> section forms the <em>Debian GNU/Linux
185 distribution</em>. </p>
187 Packages in the other sections are not considered as part of
188 the Debian distribution, though we support their use, and we
189 provide infrastructure for them (such as our bug-tracking
190 system and mailing lists). This Debian Policy Manual applies
191 to these packages as well.</p>
193 <sect id="pkgcopyright">
194 <heading>Package copyright and sections</heading>
196 The aims of this policy are:
198 <list compact="compact">
200 <p>We want to make as much software available as we
204 <p>We want to encourage everyone to write free software.</p>
207 <p> We want to make it easy for people to produce
208 CD-ROMs of our system without violating any licenses,
209 import/export restrictions, or any other laws.</p>
214 <heading>The Debian Free Software Guidelines</heading>
216 The Debian Free Software Guidelines (DFSG) is our
217 definition of `free' software.
219 <tag>Free Redistribution
223 The license of a Debian component may not restrict any
224 party from selling or giving away the software as a
225 component of an aggregate software distribution
226 containing programs from several different
227 sources. The license may not require a royalty or
228 other fee for such sale.
235 The program must include source code, and must allow
236 distribution in source code as well as compiled form.
243 The license must allow modifications and derived
244 works, and must allow them to be distributed under the
245 same terms as the license of the original software.
248 <tag>Integrity of The Author's Source Code
252 The license may restrict source-code from being
253 distributed in modified form <em>only</em> if the
254 license allows the distribution of ``patch files''
255 with the source code for the purpose of modifying the
256 program at build time. The license must explicitly
257 permit distribution of software built from modified
258 source code. The license may require derived works to
259 carry a different name or version number from the
260 original software. (This is a compromise. The Debian
261 group encourages all authors to not restrict any
262 files, source or binary, from being modified.)
265 <tag>No Discrimination Against Persons or Groups
269 The license must not discriminate against any person
273 <tag>No Discrimination Against Fields of Endeavor
277 The license must not restrict anyone from making use
278 of the program in a specific field of endeavor. For
279 example, it may not restrict the program from being
280 used in a business, or from being used for genetic
284 <tag>Distribution of License
288 The rights attached to the program must apply to all
289 to whom the program is redistributed without the need
290 for execution of an additional license by those
294 <tag>License Must Not Be Specific to Debian
298 The rights attached to the program must not depend on
299 the program's being part of a Debian system. If the
300 program is extracted from Debian and used or
301 distributed without Debian but otherwise within the
302 terms of the program's license, all parties to whom
303 the program is redistributed should have the same
304 rights as those that are granted in conjunction with
308 <tag>License Must Not Contaminate Other Software
312 The license must not place restrictions on other
313 software that is distributed along with the licensed
314 software. For example, the license must not insist
315 that all other programs distributed on the same medium
316 must be free software.
319 <tag>Example Licenses
323 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
324 examples of licenses that we consider <em>free</em>.
331 <heading>The main section</heading>
333 Every package in "main" must comply with the DFSG (Debian
334 Free Software Guidelines).</p>
337 In addition, the packages in "main"
338 <list compact="compact">
341 must not require a package outside of "main" for
342 compilation or execution (thus, the package may not
343 declare a "Depends" or "Recommends" relationship on a
349 must not be so buggy that we refuse to support them,
354 must meet all policy requirements presented in this
362 <heading>The contrib section</heading>
364 Every package in "contrib" must comply with the DFSG.
368 Examples of packages which would be included in "contrib" are
369 <list compact="compact">
372 free packages which require "contrib", "non-free", or
373 "non-US" packages or packages which are not in our
374 archive at all for compilation or execution,
379 wrapper packages or other sorts of free accessories for
385 packages which we don't want to support because they are too
391 packages which fail to meet some other policy requirements in
399 <heading>The non-free section</heading>
401 `Non-free' contains packages which are not compliant with
402 the DFSG or which are encumbered by patents or other legal
403 issues that make their distribution problematic.</p>
405 All packages in `non-free' must be electronically
406 distributable across international borders.
410 <heading>The non-us server</heading>
412 Some programs with cryptographic program code must be stored
413 on the "non-us" server because of export restrictions of the
416 This applies only to packages which contain cryptographic
417 code. A package containing a program with an interface to a
418 cryptographic program or a program that's dynamically linked
419 against a cryptographic library can be distributed if it is
420 capable of running without the cryptography library or
425 <heading>Further copyright considerations</heading>
427 Every package must be accompanied by a verbatim copy of its
428 copyright and distribution license in the file
429 /usr/doc/<package-name>/copyright (see <ref
430 id="copyrightfile"> for details).</p>
432 We reserve the right to restrict files from being included
433 anywhere in our archives if
434 <list compact="compact">
437 their use or distribution would break a law,
442 there is an ethical conflict in their distribution or
448 we would have to sign a license for them, or
453 their distribution would conflict with other project
461 Programs whose authors encourage the user to make donations
462 are fine for the main distribution, provided that the
463 authors do not claim that not donating is immoral,
464 unethical, illegal or something similar; otherwise they must
465 go in contrib (or non-free, if even distribution is
466 restricted by such statements).</p>
469 Packages whose copyright permission notices (or patent
470 problems) do not allow redistribution even of only binaries,
471 and where no special permission has been obtained, cannot be
472 placed on the Debian FTP site and its mirrors at all.</p>
475 Note, that under international copyright law (this applies
476 in the United States, too) <em>no</em> distribution or
477 modification of a work is allowed without an explicit notice
478 saying so. Therefore a program without a copyright notice
479 <em>is</em> copyrighted and you may not do anything to it
480 without risking being sued! Likewise if a program has a
481 copyright notice but no statement saying what is permitted
482 then nothing is permitted.</p>
485 Many authors are unaware of the problems that restrictive
486 copyrights (or lack of copyright notices) can cause for the
487 users of their supposedly-free software. It is often
488 worthwhile contacting such authors diplomatically to ask
489 them to modify their license terms. However, this is a
490 politically difficult thing to do and you should ask for
491 advice on <tt>debian-devel</tt> first.</p>
494 When in doubt, send mail to
495 <email>debian-devel@lists.debian.org</email>. Be prepared
496 to provide us with the copyright statement. Software
497 covered by the GPL, public domain software and BSD-like
498 copyrights are safe; be wary of the phrases `commercial use
499 prohibited' and `distribution restricted'.</p>
502 <heading>Subsections</heading>
505 The packages in the <em>main</em>, <em>contrib</em>, and
506 <em>non-free</em> sections are grouped further into
507 <em>subsections</em> to simplify handling of them.</p>
510 The section for each package is specified in the package's
511 <em>control record</em>. However, the maintainer of the
512 Debian archive may override this selection to assure the
513 consistency of the Debian distribution. </p>
516 Please check the current Debian distribution to see which
517 sections are available.</p>
520 <heading>Priorities</heading>
523 Each package is given a certain <em>priority</em> value,
524 which is included in the package's <em>control
525 record</em>. This information is used in the Debian package
526 management tool to separate high-priority packages from
527 less-important packages.</p>
530 The following <em>priority levels</em> are supported by the
531 Debian package management system, <prgn>dpkg</prgn>.
533 <tag><tt>required</tt></tag>
536 <tt>required</tt> packages are necessary for the
537 proper functioning of the system. You must not remove
538 these packages or your system may become totally
539 broken and you may not even be able to use
540 <prgn>dpkg</prgn> to put things back. Systems with
541 only the <tt>required</tt> packages are probably
542 unusable, but they do have enough functionality to
543 allow the sysadmin to boot and install more
546 <tag><tt>important</tt></tag>
549 Important programs, including those which one would
550 expect to find on any Unix-like system. If the
551 expectation is that an experienced Unix person who
552 found it missing would say `What the F*!@<+ is
553 going on, where is <prgn>foo</prgn>', it should be in
554 <tt>important</tt>. This is an important criterion
555 because we are trying to produce, amongst other
556 things, a free Unix. Other packages without which the
557 system will not run well or be usable should also be
558 here. This does <em>not</em> include Emacs or X11 or
559 TeX or any other large applications. The
560 <tt>important</tt> packages are just a bare minimum of
561 commonly-expected and necessary tools.</p>
563 <tag><tt>standard</tt></tag>
566 These packages provide a reasonably small but not too
567 limited character-mode system. This is what will
568 install by default if the user doesn't select anything
569 else. It doesn't include many large applications, but
570 it does include Emacs (this is more of a piece of
571 infrastructure than an application) and a reasonable
572 subset of TeX and LaTeX (if this is possible without
575 <tag><tt>optional</tt></tag>
578 (In a sense everything is optional that isn't
579 required, but that's not what is meant here.) This is
580 all the software that you might reasonably want to
581 install if you didn't know what it was or don't have
582 specialised requirements. This is a much larger system
583 and includes X11, a full TeX distribution, and lots of
586 <tag><tt>extra</tt></tag>
589 This contains packages that conflict with others with
590 higher priorities, or are only likely to be useful if
591 you already know what they are or have specialised
598 Packages may not depend on packages with lower priority
599 values. If this should happen, one of the priority values
600 will have to be adapted.
605 <heading>Binary packages</heading>
608 The Debian GNU/Linux distribution is based on the Debian
609 package management system, called <prgn>dpkg</prgn>. Thus,
610 all packages in the Debian distribution have to be provided
611 in the <tt>.deb</tt> file format.</p>
615 <heading>The package name</heading>
618 Every package must have a name that's unique within the Debian
622 Package names may only consist of lower case letters, digits (0-9),
623 plus (+) or minus (-) signs, and periods (.).</p>
626 The package name is part of the file name of the
627 <tt>.deb</tt> file and is included in the control field
633 <heading>The maintainer of a package</heading>
636 Every package must have exactly one maintainer at a
637 time. This person is responsible that the license of the
638 package's software complies with the policy of the
639 distribution this package is included in.</p>
642 The maintainer must be specified in the
643 <tt>Maintainer</tt> control field with the correct name
644 and a working email address for the Debian maintainer of
645 the package. If one person maintains several packages
646 he/she should try to avoid having different forms of their
647 name and email address in different <tt>Maintainer</tt>
651 If the maintainer of a package quits from the Debian
652 project the Debian QA Group takes over the maintainership
653 of the package until someone else volunteers for that
654 task. These packages are called <em>orphaned
661 <heading>The description of a package</heading>
664 Every Debian package should have an extended description
665 stored in the appropriate field of the control record.</p>
668 The description should be written so that it tells the
669 user what they need to know to decide whether to install
670 the package. This description should not just be copied
671 from the blurb for the program. Instructions for
672 configuring or using the package should not be
673 included--that is what installation scripts, manual pages,
674 Info files, etc. are for. Copyright statements and other
675 administrivia should not be included--that is what the
676 copyright file is for.</p>
681 <heading>Dependencies</heading>
684 Every package has to specify the dependency information
685 about other packages, that are required for the first to
689 For example, for any shared libraries required by
690 dynamically-linked executable binary in a package a
691 dependency entry has to be provided.</p>
694 It is not necessary for other packages to declare any
695 dependencies they have on other packages which are marked
696 <tt>Essential</tt> (see below).</p>
699 Sometimes, a package requires another package to be
700 installed <em>and</em> configured before it can be
701 installed. In this case, you'll have to specify a
702 <tt>Pre-Depends</tt> entry for the package.</p>
705 You must not specify a <tt>Pre-Depends</tt> entry for a
706 package before this has been discussed on the
707 <tt>debian-devel</tt> mailing list and a consensus about
708 doing that has been reached.</p></sect1>
712 <heading>Virtual packages</heading>
715 Sometimes, there are several packages doing more-or-less
716 the same job. In this case, it's useful to define a
717 <em>virtual package</em> who's name describes the function
718 the packages have. (The virtual packages just exist
719 logically, not physically--that's why they are called
720 <em>virtual</em>.) The packages with this particular
721 function will then <em>provide</em> the virtual
722 package. Thus, any other package requiring that function
723 can simply depend on the virtual package without having to
724 specify all possible packages individually.</p>
727 All packages must use virtual package names where
728 appropriate, and arrange to create new ones if necessary.
729 They must not use virtual package names (except privately,
730 amongst a cooperating group of packages) unless they have
731 been agreed upon and appear in the list of virtual package
735 The latest version of the authoritative list of virtual
736 package names can be found on
737 <ftpsite>ftp.debian.org</ftpsite> in
738 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</ftppath>
739 or your local mirror. In addition, it is included in the
740 <tt>debian-policy</tt> package. The procedure for updating
741 the list is described at the top of the file.</p></sect1>
745 <heading>Base packages</heading>
748 The packages included in the <tt>base</tt> section have a
749 special function. They form a minimum subset of the Debian
750 GNU/Linux system that is installed before everything else
751 on a new system. Thus, only very few packages are allowed
752 to go into the <tt>base</tt> section to keep the required
753 disk usage very small.</p>
756 Most of these packages should have the priority value
757 <tt>required</tt> or at least <tt>important</tt>, and many
758 of them will be tagged <tt>essential</tt> (see below).</p>
761 You must not place any packages into the <tt>base</tt>
762 section before this has been discussed on the
763 <tt>debian-devel</tt> mailing list and a consensus about
764 doing that has been reached.</p></sect1>
768 <heading>Essential packages</heading>
771 Some packages are tagged <tt>essential</tt>. (They have
772 <tt>Essential: yes</tt> in their package control record.)
773 This flag is used for packages that are <em>essential</em>
777 Since these packages can not easily be removed (you'll
778 have to specify an extra <em>force option</em> to
779 <prgn>dpkg</prgn>) this flag should only be used where
780 absolutely necessary.
782 A shared library package should not be tagged
783 <em>essential</em>--the dependencies will prevent its
784 premature removal, and we need to be able to remove it
785 when it has been superseded.</p>
788 You must not tag any packages <tt>essential</tt> before
789 this has been discussed on the <tt>debian-devel</tt>
790 mailing and a consensus about doing that has been
795 <heading>Maintainer scripts</heading>
798 The package installation scripts should avoid producing
799 output which it is unnecessary for the user to see and
800 should rely on <prgn>dpkg</prgn> to stave off boredom on
801 the part of a user installing many packages. This means,
802 amongst other things, using the <tt>--quiet</tt> option on
803 <prgn>install-info</prgn>.</p>
806 Packages should try to minimise the amount of prompting
807 they need to do, and they should ensure that the user will
808 only ever be asked each question once. This means that
809 packages should try to use appropriate shared
810 configuration files (such as <tt>/etc/papersize</tt> and
811 <tt>/etc/news/server</tt>), rather than each prompting for
812 their own list of required pieces of information.</p>
815 It also means that an upgrade should not ask the same
816 questions again, unless the user has used <tt>dpkg
817 --purge</tt> to remove the package's configuration. The
818 answers to configuration questions should be stored in an
819 appropriate place in <tt>/etc</tt> so that the user can
820 modify them, and how this has been done should be
824 If a package has a vitally important piece of information
825 to pass to the user (such as "don't run me as I am, you
826 must edit the following configuration files first or you
827 risk your system emitting badly-formatted messages"), it
828 should display this in the <prgn>postinst</prgn> script
829 and prompt the user to hit return to acknowledge the
830 message. Copyright messages do not count as vitally
831 important (they belong in
832 <tt>/usr/doc/<var>package</var>/copyright</tt>); neither
833 do instructions on how to use a program (these should be
834 in on line documentation, where all the users can see
838 Any necessary prompting should almost always be confined
839 to the post-installation script, and should be protected
840 with a conditional so that unnecessary prompting doesn't
841 happen if a package's installation fails and the
842 <prgn>postinst</prgn> is called with
843 <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
844 <tt>abort-deconfigure</tt>.</p>
847 Errors which occur during the execution of an installation
848 script <em>must</em> be checked and the installation
849 <em>must not</em> continue after an error.</p>
852 Note, that <ref id="scripts">, in general applies to
853 package maintainer scripts, too.</p>
856 Do not use <prgn>dpkg-divert</prgn> on a file belonging to
857 another package without consulting the maintainer of that
861 In order for <prgn>update-alternatives</prgn> to work
862 correctly all the packages which supply an instance of the
863 `shared' command name (or, in general, filename) must use
864 it. You can use <tt>Conflicts</tt> to force the
865 De-installation of other packages supplying it which do not
866 (yet) use <prgn>update-alternatives</prgn>. It may in
867 this case be appropriate to specify a conflict on earlier
868 versions on something--this is an exception to the usual
869 rule that this is not allowed.</p>
873 <heading>Source packages</heading>
876 <heading>Standards conformance</heading>
879 You should specify the most recent version of the
880 packaging standards with which your package complies in
881 the source package's <tt>Standards-Version</tt> field.</p>
884 This value will be used to file bug reports automatically
885 if your package becomes too much out of date.</p>
888 The value corresponds to a version of the Debian manuals,
889 as can be found on the title page or page headers and
890 footers (depending on the format).</p>
893 The version number has four components--major and minor
894 number and major and minor patch level. When the
895 standards change in a way that requires every package to
896 change the major number will be changed. Significant
897 changes that will require work in many packages will be
898 signaled by a change to the minor number. The major patch
899 level will be changed for any change to the meaning of the
900 standards, however small; the minor patch level will be
901 changed when only cosmetic, typographical or other edits
902 which do not change the meaning are made, or changes which
903 do not affect the contents of packages.</p>
906 You should regularly, and especially if your package has
907 become out of date, check for the newest Policy Manual
908 available and update your package, if necessary. When your
909 package complies with the new standards you may update the
910 <tt>Standards-Version</tt> source package field and
911 release it.</p></sect1>
915 <heading>Changes to the upstream sources</heading>
918 If changes to the source code are made that are generally
919 applicable please try to get them included in the upstream
920 version of the package by supplying the upstream authors
921 with the changes in whatever form they prefer.</p>
924 If you need to configure the package differently for
925 Debian or for Linux, and the upstream source doesn't
926 provide a way to configure it the way you need to, please
927 add such configuration facilities (for example, a new
928 <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
929 the patch to the upstream authors, with the default set to
930 the way they originally had it. You can then easily
931 override the default in your <tt>debian/rules</tt> or
932 wherever is appropriate.</p>
935 Please make sure that the <prgn>configure</prgn> utility
936 detects the correct architecture specification string
937 (refer to <ref id="arch-spec"> for details).</p>
940 If you need to edit a <prgn>Makefile</prgn> where
941 GNU-style <prgn>configure</prgn> scripts are used, you
942 should edit the <tt>.in</tt> files rather than editing the
943 <prgn>Makefile</prgn> directly. This allows the user to
944 reconfigure the package if necessary. You should
945 <em>not</em> configure the package and edit the generated
946 <prgn>Makefile</prgn>! This makes it impossible for
947 someone else to later reconfigure the package.</p></sect1>
951 <heading>Documenting your changes</heading>
954 Document your changes and updates to the source package
955 properly in the <tt>debian/changelog</tt> file.</p>
958 A copy of the file which will be installed in
959 <tt>/usr/doc/<var>package</var>/copyright</tt> should be
960 in <tt>debian/copyright</tt>.</p>
963 In non-experimental packages you may only use a format for
964 <tt>debian/changelog</tt> which is supported by the most
965 recent released version of <prgn>dpkg</prgn>. If your
966 format is not supported and there is general support for
967 it you should contact the <prgn>dpkg</prgn> maintainer to
968 have the parser script for your format included in the
969 <prgn>dpkg</prgn> package. (You will need to agree that
970 the parser and its manpage may be distributed under the
971 GNU GPL, just as the rest of <prgn>dpkg</prgn>
976 <heading>Error trapping in makefiles</heading>
979 When <prgn>make</prgn> invokes a command in a makefile
980 (including your package's upstream makefiles and the
981 <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
982 means that <tt>sh</tt>'s usual bad error handling
983 properties apply: if you include a miniature script as one
984 of the commands in your makefile you'll find that if you
985 don't do anything about it then errors are not detected
986 and <prgn>make</prgn> will blithely continue after
990 Every time you put more than one shell command (this
991 includes using a loop) in a makefile command you
992 <em>must</em> make sure that errors are trapped. For
993 simple compound commands, such as changing directory and
994 then running a program, using <tt>&&</tt> rather
995 than semicolon as a command separator is sufficient. For
996 more complex commands including most loops and
997 conditionals you must include a separate <tt>set -e</tt>
998 command at the start of every makefile command that's
999 actually one of these miniature shell scripts.</p></sect1>
1003 <heading>Obsolete constructs and libraries</heading>
1006 The include file <prgn><varargs.h></prgn> is
1007 provided to support end-users compiling very old software;
1008 the library <tt>libtermcap</tt> is provided to support the
1009 execution of software which has been linked against it
1010 (either old programs or those such as Netscape which are
1011 only available in binary form).</p>
1014 Debian packages should be ported to include
1015 <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
1020 <chapt><heading>The Operating System</heading>
1024 <heading>File system hierarchy</heading>
1028 <heading>Linux File system Structure</heading>
1031 The location of all installed files and directories must
1032 comply fully with the Linux File system Structure (FSSTND).
1033 The latest version of this document can be found alongside
1034 this manual or on <ftpsite>tsx-11.mit.edu</ftpsite> in
1035 <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
1036 Specific questions about following the standard may be
1037 asked on <prgn>debian-devel</prgn>, or referred to Daniel
1038 Quinlan, the FSSTND coordinator, at
1039 <email>quinlan@pathname.com</email>.</p></sect1>
1043 <heading>Site-specific programs</heading>
1046 As mandated by the FSSTND no package should place any
1047 files in <tt>/usr/local</tt>, either by putting them in
1048 the file system archive to be unpacked by <prgn>dpkg</prgn>
1049 or by manipulating them in their maintainer scripts.</p>
1052 However, the package should create empty directories below
1053 <tt>/usr/local</tt> so that the system administrator knows
1054 where to place site-specific files. These directories
1055 should be removed on package removal if they are
1059 Note, that this applies only to directories <em>below</em>
1060 <tt>/usr/local</tt>, not <em>in</em>
1061 <tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
1062 itself may only contain the sub-directories listed in
1063 FSSTND, section 4.8. However, you may create directories
1064 below them as you wish. You may not remove any of the
1065 directories listed in 4.8, even if you created them.</p>
1068 Since <tt>/usr/local</tt> may be mounted read-only from a
1069 remote server, these directories have to be created and
1070 removed by the <tt>postinst</tt> and <tt>prerm</tt>
1071 maintainer scripts. These scripts must not fail if either
1072 of these operations fail. (In the future, it will be
1073 possible to tell <prgn>dpkg</prgn> not to unpack files
1074 matching certain patterns, so that the directories can be
1075 included in the <tt>.deb</tt> packages and system
1076 administrators who do not wish these directories in
1077 /usr/local do not need to have them.)</p>
1080 For example, the <prgn>emacs</prgn> package will contain
1082 mkdir -p /usr/local/lib/emacs/site-lisp || true
1084 in the <tt>postinst</tt> script, and
1086 rmdir /usr/local/lib/emacs/site-lisp && \
1087 rmdir /usr/local/lib/emacs || \
1090 in the <tt>prerm</tt> script.</p>
1093 If you do create a directory in <tt>/usr/local</tt> for
1094 local additions to a package, you must ensure that
1095 settings in <tt>/usr/local</tt> take precedence over the
1096 equivalents in <tt>/usr</tt>.</p>
1099 The <tt>/usr/local</tt> directory itself and all the subdirectories
1100 created by the package should have permissions 2775 (group-writable
1101 and set-group-id) and be owned by <tt>root.staff</tt>.</p>
1106 <heading>Users and groups</heading>
1109 The Debian system can be configured to use either plain or
1110 shadow passwords.</p>
1113 Some user ids (UIDs) and group ids (GIDs) are reserved
1114 globally for use by certain packages. Because some packages
1115 need to include files which are owned by these users or
1116 groups, or need the ids compiled into binaries, these ids
1117 must be used on any Debian system only for the purpose for
1118 which they are allocated. This is a serious restriction, and
1119 we should avoid getting in the way of local administration
1120 policies. In particular, many sites allocate users and/or
1121 local system groups starting at 100.</p>
1124 Apart from this we should have dynamically allocated ids,
1125 which should by default be arranged in some sensible
1126 order--but the behaviour should be configurable.</p>
1129 No package except <tt>base-passwd</tt> may modify
1130 <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>, or
1131 <tt>/etc/group</tt>.</p>
1134 The UID and GID ranges are as follows:
1139 Globally allocated by the Debian project, must be the
1140 same on every Debian system. These ids will appear in
1141 the <tt>passwd</tt> and <tt>group</tt> files of all
1142 Debian systems, new ids in this range being added
1143 automatically as the <tt>base-passwd</tt> package is
1147 Packages which need a single statically allocated uid
1148 or gid should use one of these; their maintainers
1149 should ask the <tt>base-passwd</tt> maintainer for
1156 Dynamically allocated system users and groups.
1157 Packages which need a user or group, but can have this
1158 user or group allocated dynamically and differently on
1159 each system, should use `<tt>adduser --system</tt>' to
1160 create the group and/or user. <prgn>adduser</prgn>
1161 will check for the existence of the user or group, and
1162 if necessary choose an unused id based on the ranged
1163 specified in <tt>adduser.conf</tt>.</p></item>
1166 <tag>1000-29999:</tag>
1169 Dynamically allocated user accounts. By default
1170 <prgn>adduser</prgn> will choose UIDs and GIDs for
1171 user accounts in this range, though
1172 <tt>adduser.conf</tt> may be used to modify this
1176 <tag>30000-59999:</tag>
1178 <p>Reserved.</p></item>
1181 <tag>60000-64999:</tag>
1184 Globally allocated by the Debian project, but only
1185 created on demand. The ids are allocated centrally and
1186 statically, but the actual accounts are only created
1187 on users' systems on demand.</p>
1190 These ids are for packages which are obscure or which
1191 require many statically-allocated ids. These packages
1192 should check for and create the accounts in
1193 <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
1194 <prgn>adduser</prgn> if it has this facility) if
1195 necessary. Packages which are likely to require
1196 further allocations should have a `hole' left after
1197 them in the allocation, to give them room to
1201 <tag>65000-65533:</tag>
1203 <p>Reserved.</p></item>
1208 <p>User `<tt>nobody</tt>.'</p></item>
1214 <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
1215 because it is the error return sentinel value.</p>
1220 <sect id="sysvinit">
1221 <heading>System run levels</heading>
1225 <heading>Introduction</heading>
1228 The <tt>/etc/init.d</tt> directory contains the scripts
1229 executed by <prgn>init</prgn> at boot time and when init
1230 state (or `runlevel') is changed (see <manref name="init"
1231 section="8">).</p> <p>
1233 These scripts are being referenced by symbolic links in
1234 the <tt>/etc/rc<var>n</var>.d</tt> directories. When
1235 changing runlevels, <prgn>init</prgn> looks in the
1236 directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
1237 it should execute, where <var>n</var> is the runlevel that
1238 is being changed to, or `S' for the boot-up scripts.</p>
1241 The names of the links all have the form
1242 <tt>S<var>mm/<var>script</var></var></tt> or
1243 <tt>K<var>mm/<var>script</var></var></tt> where
1244 <var>mm</var> is a two-digit number and <var>script</var>
1245 is the name of the script (this should be the same as the
1246 name of the actual script in <tt>/etc/init.d</tt>.
1248 When <prgn>init</prgn> changes runlevel first the targets
1249 of the links whose names starting with a <tt>K</tt> are
1250 executed, each with the single argument <tt>stop</tt>,
1251 followed by the scripts prefixed with an <tt>S</tt>, each
1252 with the single argument <tt>start</tt>. The <tt>K</tt>
1253 links are responsible for killing services and the
1254 <tt>S</tt> link for starting services upon entering the
1258 For example, if we are changing from runlevel 2 to
1259 runlevel 3, init will first execute all of the <tt>K</tt>
1260 prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
1261 all of the <tt>S</tt> prefixed scripts. The links
1262 starting with <tt>K</tt> will cause the referred-to file
1263 to be executed with an argument of <tt>stop</tt>, and the
1264 <tt>S</tt> links with an argument of <tt>start</tt>.</p>
1267 The two-digit number <var>mm</var> is used to decide which
1268 order to start and stop things in--low-numbered links have
1269 their scripts run first. For example, the <tt>K20</tt>
1270 scripts will be executed before the <tt>K30</tt> scripts.
1271 This is used when a certain service must be started before
1272 another. For example, the name server <prgn>bind</prgn>
1273 might need to be started before the news server
1274 <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
1275 access lists. In this case, the script that starts
1276 <prgn>bind</prgn> should have a lower number than the
1277 script that starts <prgn>inn</prgn> so that it runs first:
1286 <heading>Writing the scripts</heading>
1289 Packages can and should place scripts in
1290 <tt>/etc/init.d</tt> to start or stop services at boot
1291 time or during a change of runlevel. These scripts should
1292 be named <tt>/etc/init.d/<var>package</var></tt>, and they
1293 should accept one argument, saying what to do:
1296 <tag><tt>start</tt></tag>
1297 <item><p>start the service,</p></item>
1299 <tag><tt>stop</tt></tag>
1300 <item><p>stop the service,</p></item>
1302 <tag><tt>restart</tt></tag>
1303 <item><p>stop and restart the service,</p></item>
1305 <tag><tt>reload</tt></tag>
1306 <item><p>cause the configuration of the service to be
1307 reloaded without actually stopping and restarting
1308 the service,</p></item>
1310 <tag><tt>force-reload</tt></tag> <item><p>cause the
1311 configuration to be reloaded if the service supports
1312 this, otherwise restart the service.</p></item>
1315 The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
1316 <tt>force-reload</tt> options must be supported by all
1317 scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
1318 option is optional.</p>
1321 The <tt>init.d</tt> scripts should ensure that they will
1322 behave sensibly if invoked with <tt>start</tt> when the
1323 service is already running, or with <tt>stop</tt> when it
1324 isn't, and that they don't kill unfortunately-named user
1325 processes. The best way to achieve this is usually to use
1326 <prgn>start-stop-daemon</prgn>.</p>
1329 If a service reloads its configuration automatically (as
1330 in the case of <prgn>cron</prgn>, for example), the
1331 <tt>reload</tt> option of the <tt>init.d</tt> script
1332 should behave as if the configuration has been reloaded
1336 These scripts should not fail obscurely when the
1337 configuration files remain but the package has been
1338 removed, as the default in <prgn>dpkg</prgn> is to leave
1339 configuration files on the system after the package has
1340 been removed. Only when it is executed with the
1341 <tt>--purge</tt> option will dpkg remove configuration
1342 files. Therefore, you should include a <tt>test</tt>
1343 statement at the top of the script, like this:
1345 test -f <var>program-executed-later-in-script</var> || exit 0
1346 </example></p></sect1>
1349 <heading>Managing the links</heading>
1352 A program is provided, <prgn>update-rc.d</prgn>, to make
1353 it easier for package maintainers to arrange for the
1354 proper creation and removal of
1355 <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
1356 <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
1359 You should use this script to make changes to
1360 <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
1361 any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
1365 By default <prgn>update-rc.d</prgn> will start services in
1366 each of the multi-user state runlevels (2, 3, 4, and 5)
1367 and stop them in the halt runlevel (0), the single-user
1368 runlevel (1) and the reboot runlevel (6). The system
1369 administrator will have the opportunity to customize
1370 runlevels by simply adding, moving, or removing the
1371 symbolic links in <tt>/etc/rc<var>n</var>.d</tt>.</p>
1374 To get the default behaviour for your package, put in your
1375 <tt>postinst</tt> script
1377 update-rc.d <var>package</var> defaults >/dev/null
1379 and in your <tt>postrm</tt>
1381 if [ purge = "$1" ]; then
1382 update-rc.d <var>package</var> remove >/dev/null
1387 This will use a default sequence number of 20. If it does
1388 not matter when or in which order the script is run, use
1389 this default. If it does, then you should talk to the
1390 maintainer of the <prgn>sysvinit</prgn> package or post to
1391 <tt>debian-devel</tt>, and they will help you choose a
1395 For more information about using <tt>update-rc.d</tt>,
1396 please consult its manpage <manref name="update-rc.d"
1397 section="8">.</p></sect1>
1401 <heading>Boot-time initialization</heading>
1404 There is another directory, <tt>/etc/rc.boot</tt>, which
1405 contains scripts which are run once per machine boot.
1406 This facility is provided for initialization of hardware
1407 devices, cleaning up of leftover files, and so forth.</p>
1410 For example, the <prgn>kbd</prgn> package provides a
1411 script here for initialising the keyboard layout and
1412 console font and mode.</p>
1415 The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
1416 links into <tt>/etc/init.d</tt>--they should be the
1417 scripts themselves.</p>
1420 <tt>rc.boot</tt> should <em>not</em> be used for starting
1421 general-purpose daemons and similar activities. This
1422 should be done using the <tt>rc<var>n</var>.d</tt> scheme,
1423 above, so that the services can be started and stopped
1424 cleanly when the runlevel changes or the machine is to be
1425 shut down or rebooted.</p></sect1>
1429 <heading>Notes</heading>
1432 <em>Do not</em> include the
1433 <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
1434 <tt>.deb</tt> file system archive! <em>This will cause
1435 problems!</em> You should create them with
1436 <prgn>update-rc.d</prgn>, as above.</p>
1439 <em>Do not</em> include the <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
1440 <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
1441 problems!</em> <em>Do</em>,
1442 however, include the <tt>/etc/init.d</tt> scripts in
1443 conffiles. (This is important since we want to give the
1444 local system administrator the chance to adapt the scripts
1445 to the local system--e.g., to disable a service without
1446 De-installing the package, or to specify some special
1447 command line options when starting a service--while making
1448 sure her changes aren't lost during the next package
1449 upgrade.)</p></sect1>
1452 <heading>Example</heading>
1455 The <prgn>bind</prgn> DNS (nameserver) package wants to
1456 make sure that the nameserver is running in multiuser
1457 runlevels, and is properly shut down with the system. It
1458 puts a script in <tt>/etc/init.d</tt>, naming the script
1459 appropriately <tt>bind</tt>. As you can see, the script
1460 interprets the argument <tt>reload</tt> to send the
1461 nameserver a <tt>HUP</tt> signal (causing it to reload its
1462 configuration); this way the user can say
1463 <tt>/etc/init.d/bind reload</tt> to reload the name
1470 # Original version by Robert Leslie
1471 # <rob@mars.org>, edited by iwj and cs
1473 test -x /usr/sbin/named || exit 0
1477 echo -n "Starting domain name service: named"
1478 start-stop-daemon --start --quiet --exec /usr/sbin/named
1482 echo -n "Stopping domain name service: named"
1483 start-stop-daemon --stop --quiet \
1484 --pidfile /var/run/named.pid --exec /usr/sbin/named
1488 echo -n "Restarting domain name service: named"
1489 start-stop-daemon --stop --quiet \
1490 --pidfile /var/run/named.pid --exec /usr/sbin/named
1491 start-stop-daemon --start --verbose --exec /usr/sbin/named
1494 force-reload|reload)
1495 echo -n "Reloading configuration of domain name service: named"
1496 start-stop-daemon --stop --signal 1 --quiet \
1497 --pidfile /var/run/named.pid --exec /usr/sbin/named
1501 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1510 Another example on which to base your <tt>/etc/init.d</tt>
1511 scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
1514 If this package is happy with the default setup from
1515 <prgn>update-rc.d</prgn>, namely an ordering number of 20
1516 and having named running in all runlevels, it can say in
1517 its <tt>postinst</tt>:
1519 update-rc.d bind defaults >/dev/null
1521 And in its <tt>postrm</tt>, to remove the links when the
1524 if [ purge = "$1" ]; then
1525 update-rc.d acct remove >/dev/null
1531 <heading>Cron jobs</heading>
1534 Packages may not touch the configuration file
1535 <tt>/etc/crontab</tt>, nor may they modify the files in
1536 <tt>/var/spool/cron/crontabs</tt>.</p>
1539 If a package wants to install a job that has to be executed
1540 via cron, it should place a file with the name if the
1541 package in one of the following directories:
1547 As these directory names say, the files within them are executed on
1548 a daily, weekly, or monthly basis, respectively.</p>
1551 If a certain job has to be executed more frequently than
1552 `daily,' the package should install a file
1553 <tt>/etc/cron.d/<package-name></tt> tagged as
1554 configuration file. This file uses the same syntax as
1555 <tt>/etc/crontab</tt> and is processed by <prgn>cron</prgn>
1556 automatically. (Note, that scripts in the
1557 <tt>/etc/cron.d</tt> directory are not handled by
1558 <prgn>anacron</prgn>. Thus, you should only use this
1559 directory for jobs which may be skipped if the system is not
1563 All files installed in any of these directories have to be
1564 scripts (shell scripts, Perl scripts, etc.) so that they can
1565 easily be modified by the local system administrator. In
1566 addition, they have to be registered as configuration
1570 The scripts in these directories have to check, if all
1571 necessary programs are installed before they try to execute
1572 them. Otherwise, problems will arise when a package was
1573 removed (but not purged), since the configuration files are
1574 kept on the system in this situation.</p></sect>
1578 <heading>Console messages</heading>
1581 This section describes different formats for messages
1582 written to standard output by the <tt>/etc/init.d</tt>
1583 scripts. The intent is to improve the consistency of
1584 Debian's startup and shutdown look and feel.</p>
1587 Please look very careful at the details. We want to get the
1588 messages to look exactly the same way concerning spaces,
1589 punctuation, and case of letters.</p>
1592 Here is a list of overall rules that you should use when you
1593 create output messages. They can be useful if you have a
1594 non-standard message that isn't covered in the sections
1601 Every message should cover one line, start with a
1602 capital letter and end with a period `.'.</p></item>
1607 If you want to express that the computer is working on
1608 something (performing a specific task, not starting or
1609 stopping a program), we use an ``ellipsis'', namely
1610 three dots `...'. Note that we don't insert spaces in
1611 front of or behind the dots. If the task has been
1612 completed we write `done.' and a line feed.</p></item>
1617 Design your messages as if the computer is telling you
1618 what he is doing (let him be polite :-) but don't
1619 mention ``him'' directly. For example, if you think
1622 I'm starting network daemons: nfsd mountd.
1626 Starting network daemons: nfsd mountd.
1627 </example></p></item>
1631 The following formats must be used</p>
1636 <p>when daemons get started.</p>
1639 Use this format if your script starts one or more
1640 daemons. The output should look like this (a single
1641 line, no leading spaces):
1643 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1645 The <description> should describe the subsystem
1646 the daemon or set of daemons are part of, while
1647 <daemon-1> up to <daemon-n> denote each
1648 daemon's name (typically the file name of the
1652 For example, the output of /etc/init.d/lpd would look like:
1654 Starting printer spooler: lpd.
1658 This can be achieved by saying
1660 echo -n "Starting printer spooler: lpd"
1661 start-stop-daemon --start --quiet lpd
1664 in the script. If you have more than one daemon to
1665 start, you should do the following:
1667 echo -n "Starting remote file system services:"
1668 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1669 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1670 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1673 This makes it possible for the user to see what takes
1674 so long and when the final daemon has been
1675 started. Please be careful where to put spaces: In the
1676 example above the system administrator can easily
1677 comment out a line if he don't wants to start a
1678 specific daemon, while the displayed message still
1679 looks good.</p></item>
1683 <p>when something needs to be configured.</p>
1686 If you have to set up different parameters of the
1687 system upon boot up, you can use this format:
1689 Setting <parameter> to `<value>'.
1693 You can use the following echo statement to get the quotes right:
1695 echo "Setting DNS domainname to \`"value"'."
1699 Note that the left quotation mark (`) is different
1700 from the right (').</p></item>
1703 <p>when a daemon is stopped.</p>
1706 When you stop a daemon you should issue a message
1707 similar to the startup message, except that `Starting'
1708 is replaced with `Stopping'.</p>
1711 So stopping the printer daemon will like like this:
1713 Stopping printer spooler: lpd.
1714 </example></p></item>
1717 <p>when something is executed.</p>
1720 There a several examples where you have to run a
1721 program at system startup or shutdown to perform a
1722 specific task. For example, setting the system's clock
1723 via `netdate' or killing all processes when the system
1724 comes down. Your message should like this:
1726 Doing something very useful...done.
1728 You should print the `done.' right after the job has been completed,
1729 so that the user gets informed why he has to wait. You can get this
1732 echo -n "Doing something very useful..."
1736 in your script.</p></item>
1739 <p>when the configuration is reloaded.</p>
1742 When a daemon is forced to reload its configuration
1743 files you should use the following format:
1745 Reloading <daemon's-name> configuration...done.
1746 </example></p></item>
1749 <p>when none of the above rules apply.</p>
1752 If you have to print a message that doesn't fit into
1753 the styles described above, you can use something
1754 appropriate, but please have a look at the overall
1755 rules listed above.</p></item>
1760 <heading>Menus</heading>
1763 The Debian <tt>menu</tt> packages provides a unique
1764 interface between packages providing applications and
1765 documents, and <em>menu programs</em> (either X window
1766 managers or text-based menu programs as
1767 <prgn>pdmenu</prgn>).</p>
1770 All packages that provide applications that need not be
1771 passed any special command line arguments for normal
1772 operation should register a menu entry for those
1773 applications, so that users of the <tt>menu</tt> package
1774 will automatically get menu entries in their window
1775 managers, as well in shells like <tt>pdmenu</tt>.</p>
1778 Please refer to the <em>Debian Menu System</em> document
1779 that comes with the <tt>menu</tt> package for information
1780 about how to register your applications and web
1781 documents.</p></sect>
1785 <heading>Keyboard configuration</heading>
1788 To achieve a consistent keyboard configuration (i.e., all
1789 applications interpret a keyboard event the same way) all
1790 programs in the Debian distribution have to be configured to
1791 comply with the following guidelines.</p>
1794 Here is a list that contains certain keys and their interpretation:
1797 <tag><tt><--</tt></tag>
1798 <item><p>delete the character to the left of the cursor</p></item>
1800 <tag><tt>Delete</tt></tag>
1801 <item><p>delete the character to the right of the cursor</p></item>
1803 <tag><tt>Control+H</tt></tag>
1804 <item><p>emacs: the help prefix</p></item>
1807 The interpretation of any keyboard events should be
1808 independent of the terminal that's used (either the console,
1809 X windows, rlogin/telnet session, etc.).</p>
1812 The following list explains how the different programs
1813 should be set up to achieve this:</p>
1816 <list compact="compact">
1817 <item><p>`<tt><--</tt>' generates KB_Backspace in
1820 <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
1824 X translations are set up to make KB_Backspace
1825 generate ASCII DEL, and to make KB_Delete generate
1826 <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
1827 the `delete character' key). This must be done by
1828 loading the resources using xrdb on all local X
1829 displays, not using the application defaults, so that
1830 the translation resources used correspond to the
1831 xmodmap settings.</p></item>
1835 The Linux console is configured to make
1836 `<tt><--</tt>' generate DEL, and `Delete' generate
1837 <tt>ESC [ 3 ~</tt> (this is the case at the
1841 X applications are configured so that Backspace
1842 deletes left, and Delete deletes right. Motif
1843 applications already work like this.</p></item>
1845 <item><p>stty erase <tt>^?</tt> .</p></item>
1848 The `xterm' terminfo entry should have <tt>ESC [ 3
1849 ~</tt> for kdch1, just like TERM=linux and
1850 TERM=vt220.</p></item>
1853 Emacs is programmed to map KB_Backspace or the `stty
1854 erase' character to delete-backward-char, and
1855 KB_Delete or kdch1 to delete-forward-char, and
1856 <tt>^H</tt> to help as always.</p></item>
1859 Other applications use the `stty erase' character and
1860 kdch1 for the two delete keys, with ASCII DEL being
1861 `delete previous character' and kdch1 being `delete
1862 character under cursor'.</p></item>
1866 This will solve the problem except for:</p>
1869 <list compact="compact">
1871 Some terminals have a <tt><--</tt> key that cannot
1872 be made to produce anything except <tt>^H</tt>. On
1873 these terminals Emacs help will be unavailable on
1874 <tt>^H</tt> (assuming that the `stty erase' character
1875 takes precedence in Emacs, and has been set
1876 correctly). M-x help or F1 (if available) can be used
1880 Some operating systems use <tt>^H</tt> for stty erase.
1881 However, modern telnet versions and all rlogin
1882 versions propagate stty settings, and almost all UNIX
1883 versions honour stty erase. Where the stty settings
1884 are not propagated correctly things can be made to
1885 work by using stty manually.</p></item>
1888 Some systems (including previous Debian versions) use
1889 xmodmap to arrange for both <tt><--</tt> and Delete
1890 to generate KB_Delete). We can change the behaviour
1891 of their X clients via the same X resources that we
1892 use to do it for our own, or have our clients be
1893 configured via their resources when things are the
1894 other way around. On displays configured like this
1895 Delete will not work, but <tt><--</tt>
1899 Some operating systems have different kdch1 settings
1900 in their terminfo for xterm and others. On these
1901 systems the Delete key will not work correctly when
1902 you log in from a system conforming to our policy, but
1903 <tt><--</tt> will.</p></item>
1910 <heading>Environment variables</heading>
1913 No program may depend on environment variables to get
1914 reasonable defaults. (That's because these environment
1915 variables would have to be set in a system-wide
1916 configuration file like /etc/profile, which is not supported
1920 If a program should depend on environment variables for its
1921 configuration, the program has to be changed to fall back to
1922 a reasonable default configuration if these environment
1923 variables are not present. If this cannot be done easily
1924 (e.g., if the source code of a non-free program is not
1925 available), the program should be replaced by a small
1926 `wrapper' shell script which sets the environment variables
1927 and calls the original program.</p>
1930 Here is an example of a wrapper script for this purpose:
1936 exec /usr/lib/foo/foo "$@"
1940 Furthermore, as <tt>/etc/profile</tt> is a configuration
1941 file of the <prgn>bash</prgn> package, no other package may
1942 put any environment variables or other commands into that
1947 <heading>Files</heading>
1951 <heading>Binaries</heading>
1954 It is not allowed that two packages install programs with
1955 different functionality but with the same filenames. (The
1956 case of two programs having the same functionality but
1957 different implementations is handled via `alternatives.')
1958 If this case happens, one of the programs has to be
1959 renamed. The maintainers should report this to the
1960 developers' mailing and try to find a consensus about
1961 which package will have to be renamed. If a consensus can
1962 not be reached, <em>both</em> programs must be
1966 Generally the following compilation parameters should be used:
1969 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
1971 install -s # (or use strip on the files in debian/tmp)
1975 Note that all installed binaries should be stripped,
1976 either by using the <tt>-s</tt> flag to
1977 <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
1978 the binaries after they have been copied into
1979 <tt>debian/tmp</tt> but before the tree is made into a
1983 The <tt>-g</tt> flag is useful on compilation so that you
1984 have available a full set of debugging symbols in your
1985 built source tree, in case anyone should file a bug report
1986 involving (for example) a core dump.</p>
1989 The <tt>-N</tt> flag should not be used. On a.out systems
1990 it may have been useful for some very small binaries, but
1991 for ELF it has no good effect.</p>
1994 It is up to the package maintainer to decide what
1995 compilation options are best for the package. Certain
1996 binaries (such as computationally-intensive programs) may
1997 function better with certain flags (<tt>-O3</tt>, for
1998 example); feel free to use them. Please use good judgment
1999 here. Don't use flags for the sake of it; only use them
2000 if there is good reason to do so. Feel free to override
2001 the upstream author's ideas about which compilation
2002 options are best--they are often inappropriate for our
2003 environment.</p></sect>
2007 <heading>Libraries</heading>
2010 All libraries must have a shared version in the lib
2011 package and a static version in the lib-dev package. The
2012 shared version must be compiled with <tt>-fPIC</tt>, and
2013 the static version must not be. In other words, each
2014 <tt>*.c</tt> file is compiled twice.</p>
2017 You have to specify the gcc option <tt>-D_REENTRANT</tt>
2018 when building a library (either static or shared) to make
2019 the library compatible with LinuxThreads.</p>
2022 Note that all installed shared libraries should be
2025 strip --strip-unneeded <your-lib>
2027 (The option `--strip-unneeded' makes <tt>strip</tt> remove
2028 only the symbols which aren't needed for relocation
2029 processing.) Shared libraries can function perfectly well
2030 when stripped, since the symbols for dynamic linking are
2031 in a separate part of the ELF object file.</p>
2034 Note that under some circumstances it may be useful to
2035 install a shared library unstripped, for example when
2036 building a separate package to support debugging.</p>
2039 Please make sure that you use only released versions of
2040 shared libraries to build your packages; otherwise other
2041 users will not be able to run your binaries
2042 properly. Producing source packages that depend on
2043 unreleased compilers is also usually a bad
2048 <heading>Shared libraries</heading>
2051 Packages involving shared libraries should be split up
2052 into several binary packages.</p>
2055 For a straightforward library which has a development
2056 environment and a runtime kit including just shared
2057 libraries you need to create two packages:
2058 <tt><var>libraryname</var><var>soname</var></tt>
2059 (<var>soname</var> is the shared object name of the shared
2060 library--it's the thing that has to match exactly between
2061 building an executable and running it for the dynamic
2062 linker to be able run the program; usually the
2063 <var>soname</var> is the major number of the library) and
2064 <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
2067 If you prefer only to support one development version at a
2068 time you may name the development package
2069 <tt><var>libraryname</var>-dev</tt>; otherwise you may
2070 wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
2071 ensure that the user only installs one development version
2072 at a time (after all, different development versions are
2073 likely to have the same header files in them, causing a
2074 filename clash if both are installed). Typically the
2075 development version will also need an exact version
2076 dependency on the runtime library, to make sure that
2077 compilation and linking happens correctly.</p>
2080 Packages which use the shared library should have a
2081 dependency on the name of the shared library package,
2082 <tt><var>libraryname</var><var>soname</var></tt>. When
2083 the <var>soname</var> changes you can have both versions
2084 of the library installed while moving from the old library
2088 If your package has some run-time support programs which
2089 use the shared library you must <em>not</em> put them in
2090 the shared library package. If you do that then you won't
2091 be able to install several versions of the shared library
2092 without getting filename clashes. Instead, either create
2093 a third package for the runtime binaries (this package
2094 might typically be named
2095 <tt><var>libraryname</var>-runtime</tt>--note the absence
2096 of the <var>soname</var> in the package name) or if the
2097 development package is small include them in there.</p>
2100 If you have several shared libraries built from the same
2101 source tree you can lump them all together into a single
2102 shared library package, provided that you change all their
2103 <var>soname</var>s at once (so that you don't get filename
2104 clashes if you try to install different versions of the
2105 combined shared libraries package).</p>
2108 Follow the directions in the <em>Debian Packaging
2109 Manual</em> for putting the shared library in its package,
2110 and make sure you include a <tt>shlibs</tt> control area
2111 file with details of the dependencies for packages which
2112 use the library.</p>
2115 Shared libraries should <em>not</em> be installed
2116 executable, since <prgn>ld.so</prgn> does not require this
2117 and trying to execute a shared library results in a core
2122 <heading>Scripts</heading>
2125 All command scripts, including the package maintainer
2126 scripts inside the package and used by <prgn>dpkg</prgn>,
2127 should have a <tt>#!</tt> line naming the shell to be used
2128 to interpret them.</p>
2131 In the case of Perl scripts this should be
2132 <tt>#!/usr/bin/perl</tt>.</p>
2135 Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
2136 should almost certainly start with <tt>set -e</tt> so that
2137 errors are detected. Every script <em>must</em> use
2138 <tt>set -e</tt> or check the exit status of <em>every</em>
2142 The standard shell interpreter `<tt>/bin/sh</tt>' may be a
2143 symbolic link to any POSIX compatible shell. Thus, shell
2144 scripts specifying `<tt>/bin/sh</tt>' as interpreter may
2145 only use POSIX features. If a script requires non-POSIX
2146 features from the shell interpreter, the appropriate shell
2147 has to be specified in the first line of the script (e.g.,
2148 `<tt>#!/bin/bash</tt>') and the package has to depend on
2149 the package providing the shell (unless the shell package
2150 is marked `Essential', e.g., in the case of
2151 <prgn>bash</prgn>).</p>
2154 Restrict your script to POSIX features when possible so
2155 that it may use <tt>/bin/sh</tt> as its interpreter. If
2156 your script works with <prgn>ash</prgn>, it's probably
2157 POSIX compliant, but if you are in doubt, use
2158 <tt>/bin/bash</tt>.</p>
2161 Perl scripts should check for errors when making any
2162 system calls, including <tt>open</tt>, <tt>print</tt>,
2163 <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
2166 <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
2167 as scripting languages. See <em>Csh Programming
2168 Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
2169 FAQs. It can be found on
2170 <url id="http://language.perl.com/versus/csh.whynot">, or
2171 <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
2172 or even on <ftpsite>ftp.cpan.org</ftpsite>
2173 <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
2174 If an upstream package comes with <prgn>csh</prgn> scripts
2175 then you must make sure that they start with
2176 <tt>#!/bin/csh</tt> and make your package depend on the
2177 <prgn>c-shell</prgn> virtual package.</p>
2180 Any scripts which create files in world-writable
2181 directories (e.g., in <tt>/tmp</tt>) have to use a
2182 mechanism which will fail if a file with the same name
2186 The Debian base distribution provides the
2187 <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
2188 for use by scripts for this purpose.</p></sect>
2192 <heading>Symbolic links</heading>
2195 In general, symbolic links within a toplevel directory
2196 should be relative, and symbolic links pointing from one
2197 toplevel directory into another should be absolute. (A
2198 toplevel directory is a sub-directory of the root
2202 In addition, symbolic links should be specified as short
2203 as possible, i.e., link targets like `foo/../bar' are
2207 Note that when creating a relative link using
2208 <prgn>ln</prgn> it is not necessary for the target of the
2209 link to exist relative to the working directory you're
2210 running <prgn>ln</prgn> from; nor is it necessary to
2211 change directory to the directory where the link is to be
2212 made. Simply include the string that should appear as the
2213 target of the link (this will be a pathname relative to
2214 the directory in which the link resides) as the first
2215 argument to <prgn>ln</prgn>.</p>
2218 For example, in your <prgn>Makefile</prgn> or
2219 <tt>debian/rules</tt>, do things like:
2221 ln -fs gcc $(prefix)/bin/cc
2222 ln -fs gcc debian/tmp/usr/bin/cc
2223 ln -fs ../sbin/sendmail $(prefix)/bin/runq
2224 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
2228 A symbolic link pointing to a compressed file should
2229 always have the same file extension as the referenced
2230 file. (For example, if a file `<tt>foo.gz</tt>' is
2231 referenced by a symbolic link, the filename of the link
2232 has to end with `<tt>.gz</tt>' too, as in
2233 `bar.gz.')</p></sect>
2237 <heading>Device files</heading>
2240 No package may include device files in the package file
2244 If a package needs any special device files that are not
2245 included in the base system, it has to call
2246 <prgn>makedev</prgn> in the <tt>postinst</tt> script,
2247 after asking the user for permission to do so.</p>
2250 No package should remove any device files in the
2251 <tt>postrm</tt> or any other script. This is left to the
2252 system administrator.</p>
2255 Debian uses the serial devices
2256 <tt>/dev/tty*</tt>. Programs using the old
2257 <tt>/dev/cu*</tt> devices should be changed to use
2258 <tt>/dev/tty*</tt>.</p></sect>
2262 <heading>Configuration files</heading>
2265 Any configuration files created or used by your package
2266 should reside in <tt>/etc</tt>. If there are several you
2267 should consider creating a subdirectory named after your
2271 It is almost certain that any file in <tt>/etc</tt> that
2272 is in your package's file system archive should be listed
2273 in <prgn>dpkg</prgn>'s <tt>conffiles</tt> control area
2274 file. (See the <em>Debian Packaging
2278 Only packages that are tagged <em>conflicting</em> with
2279 each other may specify the same file as
2280 <tt>conffile</tt>. A package may not modify a
2281 configuration file of another package.</p>
2284 If two or more packages use the same configuration file,
2285 one of these packages has to be defined as <em>owner</em>
2286 of the configuration file, i.e., it has to list the file
2287 as <tt>conffile</tt> and has to provide a program that
2288 modifies the configuration file.</p>
2291 The other packages have to depend on the <em>owner</em>
2292 package and use that program to update the configuration
2296 Sometimes it's appropriate to build a new package, which
2297 just provides the basic <em>infrastructure</em> for the
2298 other packages and which manages the shared configuration
2299 files. (Check out the <prgn>sgml-base</prgn> package as an
2303 Files in <tt>/etc/skel</tt> will automatically be copied
2304 into new user accounts by <prgn>adduser</prgn>. They
2305 should not be referenced there by any program.</p>
2308 Therefore, if a program needs a dotfile to exist in
2309 advance in <tt>$HOME</tt> to work sensibly that dotfile
2310 should be installed in <tt>/etc/skel</tt> (and listed in
2311 conffiles, if it is not generated and modified dynamically
2312 by the package's installation scripts).</p>
2315 However, programs that require dotfiles in order to
2316 operate sensibly (dotfiles that they do not create
2317 themselves automatically, that is) are a bad thing, and
2318 programs should be configured by the Debian default
2319 installation as close to normal as possible.</p>
2322 Therefore, if a program in a Debian package needs to be
2323 configured in some way in order to operate sensibly that
2324 configuration should be done in a site-wide global
2325 configuration file elsewhere in <tt>/etc</tt>. Only if
2326 the program doesn't support a site-wide default
2327 configuration and the package maintainer doesn't have time
2328 to add it should a default per-user file be placed in
2329 <tt>/etc/skel</tt>.</p>
2332 <tt>/etc/skel</tt> should be as empty as we can make it.
2333 This is particularly true because there is no easy
2334 mechanism for ensuring that the appropriate dotfiles are
2335 copied into the accounts of existing users when a package
2339 Ideally the sysadmin should not have to do any
2340 configuration other than that done (semi-)automatically by
2341 the <tt>postinst</tt> script.</p>
2345 <heading>Log files</heading>
2348 Log files should usually be named
2349 <tt>/var/log/<var>package</var>.log</tt>. If you have many
2350 log files, or need a separate directory for permissions
2351 reasons (<tt>/var/log</tt> is writable only by
2352 <tt>root</tt>), you should usually create a directory named
2353 <tt>/var/log/<var>package</var></tt>.</p>
2356 Make sure that any log files are rotated occasionally so
2357 that they don't grow indefinitely; the best way to do this
2358 is to use <prgn>savelog</prgn> program in an
2359 <tt>/etc/cron.daily</tt>, <tt>/etc/cron.weekly</tt> or
2360 <tt>/etc/cron.monthly</tt> script. Here is a good example:
2362 [ -d /var/log/apache/. ] || exit 0
2365 if [ -fs access.log ]
2367 savelog -c 7 access.log > /dev/null
2372 Make sure that any log files are removed when the package is
2373 purged (but not when it is only removed), by checking the
2374 argument to the <tt>postrm</tt> script (see the <em>Debian
2375 Packaging Manual</em> for details).</p>
2380 <heading>Permissions and owners</heading>
2383 The rules in this section are guidelines for general use.
2384 If necessary you may deviate from the details below.
2385 However, if you do so you must make sure that what is done
2386 is secure and you must try to be as consistent as possible
2387 with the rest of the system. You should probably also
2388 discuss it on <prgn>debian-devel</prgn> first.</p>
2391 Files should be owned by <tt>root.root</tt>, and made
2392 writable only by the owner and universally readable (and
2393 executable, if appropriate).</p>
2396 Directories should be mode 755 or (for group-writability)
2397 mode 2775. The ownership of the directory should be
2398 consistent with its mode--if a directory is mode 2775, it
2399 should be owned by the group that needs write access to
2403 Setuid and setgid executables should be mode 4755 or 2755
2404 respectively, and owned by the appropriate user or group.
2405 They should not be made unreadable (modes like 4711 or
2406 2711 or even 4111); doing so achieves no extra security,
2407 because anyone can find the binary in the freely available
2408 Debian package--it is merely inconvenient. For the same
2409 reason you should not restrict read or execute permissions
2410 on non-set-id executables.</p>
2413 Some setuid programs need to be restricted to particular
2414 sets of users, using file permissions. In this case they
2415 should be owned by the uid to which they are set-id, and
2416 by the group which should be allowed to execute them.
2417 They should have mode 4754; there is no point in making
2418 them unreadable to those users who must not be allowed to
2422 Do not arrange that the system administrator can only
2423 reconfigure the package to correspond to their local
2424 security policy by changing the permissions on a binary.
2425 Ordinary files installed by <prgn>dpkg</prgn> (as opposed
2426 to conffiles and other similar objects) have their
2427 permissions reset to the distributed permissions when the
2428 package is reinstalled. Instead you should consider (for
2429 example) creating a group for people allowed to use the
2430 program(s) and making any setuid executables executable
2431 only by that group.</p>
2434 If you need to create a new user or group for your package
2435 there are two possibilities. Firstly, you may need to
2436 make some files in the binary package be owned by this
2437 user or group, or you may need to compile the user or
2438 group id (rather than just the name) into the binary
2439 (though this latter should be avoided if possible). In
2440 this case you need a statically allocated id.</p>
2443 You must ask for a user or group id from the base system
2444 maintainer, and must not release the package until you
2445 have been allocated one. Once you have been allocated one
2446 you must make the package depend on a version of the base
2447 system with the id present in <tt>/etc/passwd</tt> or
2448 <tt>/etc/group</tt>, or alternatively arrange for your
2449 package to create the user or group itself with the
2450 correct id (using <tt>adduser</tt>) in its pre- or
2451 post-installation script (the latter is to be preferred if
2452 it is possible).</p>
2455 On the other hand, the program may able to determine the
2456 uid or gid from the group name at runtime, so that a
2457 dynamic id can be used. In this case you must choose an
2458 appropriate user or group name, discussing this on
2459 <prgn>debian-devel</prgn> and checking with the base
2460 system maintainer that it is unique and that they do not
2461 wish you to use a statically allocated id instead. When
2462 this has been checked you must arrange for your package to
2463 create the user or group if necessary using
2464 <prgn>adduser</prgn> in the pre- or post-installation
2465 script (again, the latter is to be preferred if it is
2469 Note that changing the numeric value of an id associated with a name
2470 is very difficult, and involves searching the file system for all
2471 appropriate files. You need to think carefully whether a static or
2472 dynamic id is required, since changing your mind later will cause
2478 <heading>Customized programs</heading>
2480 <sect id="arch-spec">
2481 <heading>Architecture specification strings</heading>
2484 If a program needs to specify an <em>architecture specification
2485 string</em> in some place, the following format has to be used:
2487 <arch>-<os>
2489 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2490 powerpc, sparc and `<os>' is one of: linux, gnu. Use
2491 of <em>gnu</em> in this string is reserved for the GNU/Hurd
2492 operating system. .</p>
2494 Note, that we don't want to use `<arch>-debian-linux'
2495 to apply to the rule `architecture-vendor-os' since this
2496 would make our programs incompatible to other Linux
2497 distributions. Also note, that we don't use
2498 `<arch>-unknown-linux', since the `unknown' does not
2499 look very good.</p></sect>
2503 <heading>Daemons</heading>
2506 The configuration files <tt>/etc/services</tt>,
2507 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
2508 by the <prgn>netbase</prgn> package and may not be modified
2509 by other packages.</p>
2512 If a package requires a new entry in one of these files, the
2513 maintainer has to get in contact with the
2514 <prgn>netbase</prgn> maintainer, who will add the entries
2515 and release a new version of the <prgn>netbase</prgn>
2519 The configuration file <tt>/etc/inetd.conf</tt> may be
2520 modified by the package's scripts only via the
2521 <prgn>update-inetd</prgn> script or the
2522 <prgn>DebianNet.pm</prgn> Perl module.</p>
2525 If a package wants to install an example entry into
2526 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with
2527 exactly one hash character (#). Such lines are treated as
2528 `commented out by user' by the <prgn>update-inetd</prgn>
2529 script and are not changed or activated during a package
2534 <heading>Editors and pagers</heading>
2537 Some programs have the ability to launch an editor or pager
2538 program to edit or display a text document. Since there are
2539 lots of different editors and pagers available in the Debian
2540 distribution, the system administrator and each user should
2541 have the possibility to choose his/her preferred editor and
2545 In addition, every program should choose a good default
2546 editor/pager if none is selected by the user or system
2550 Thus, every program that launches an editor or pager has to
2551 use the EDITOR or PAGER environment variables to determine
2552 the editor/pager the user wants to get started. If these
2553 variables are not set, the programs `/usr/bin/editor' and
2554 `/usr/bin/pager' have to be used, respectively.</p>
2557 These two files are managed through `alternatives.' That is,
2558 every package providing an editor or pager has to call the
2559 `update-alternatives' script to register these programs.</p>
2562 If it is very hard to adapt a program to make us of the
2563 EDITOR and PAGER variable, that program should be configured
2564 to use `/usr/bin/sensible-editor' and
2565 `/usr/bin/sensible-pager' as editor or pager program,
2566 respectively. These are two scripts provided in the Debian
2567 base system that check the EDITOR and PAGER variables and
2568 launches the appropriate program or falls back to
2569 `/usr/bin/editor' and `/usr/bin/pager', automatically.</p>
2572 Since the Debian base system already provides an editor and
2573 a pager program, there is no need for a package to depend on
2574 `editor' and `pager', nor is it necessary for a package to
2575 provide such virtual packages.</p></sect>
2578 <sect id="web-appl">
2579 <heading>Web servers and applications</heading>
2582 This section describes the locations and URLs that have to
2583 be used by all web servers and web application in the Debian
2589 <p>Cgi-bin executable files are installed in the
2592 /usr/lib/cgi-bin/<cgi-bin-name>
2594 and can be referred to as
2596 http://localhost/cgi-bin/<cgi-bin-name>
2597 </example></p></item>
2600 <item><p>Access to html documents</p>
2603 Html documents for a package are stored in
2604 /usr/doc/<var>package</var> and can be referred to as
2606 http://localhost/doc/<package>/<filename>
2607 </example></p></item>
2610 <item><p>Web Document Root</p>
2613 Web Applications should try to avoid storing files in
2614 the Web Document Root. Instead use the
2615 /usr/doc/<package> directory for documents and
2616 register the Web Application via the menu package. If
2617 access to the web-root is unavoidable then use
2621 as the Document Root. This might be just a
2622 symbolic link to the location where the sysadmin has
2623 put the real document root.</p>
2626 </enumlist></p></sect>
2630 <heading>Mail transport agents</heading>
2633 Debian packages which process electronic mail, whether
2634 mail-user-agents (MUAs) or mail-transport-agents (MTAs),
2635 <em>must</em> make sure that they are compatible with the
2636 configuration decisions below. Failure to do this may
2637 result in lost mail, broken <tt>From:</tt> lines, and other
2638 serious brain damage!</p>
2641 The mail spool is <tt>/var/spool/mail</tt> and the interface
2642 to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
2643 per the FSSTND). The mail spool is part of the base system
2644 and not part of the MTA package.</p>
2647 All Debian MUAs and MTAs have to use the <tt>maillock</tt>
2648 and <tt>mailunlock</tt> functions provided by the
2649 <tt>liblockfile</tt> packages to lock and unlock mail
2650 boxes. These functions implement a NFS-safe locking
2651 mechanism. (It is ok if MUAs and MTAs don't link against
2652 liblockfile but use a <em>compatible</em> mechanism. Please
2653 compare the mechanisms very carefully!)</p>
2656 Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
2657 unless the user has chosen otherwise. A MUA may remove a
2658 mailbox (unless it has nonstandard permissions) in which
2659 case the MTA or another MUA must recreate it if needed.
2660 Mailboxes must be writable by group mail.</p>
2663 The mail spool is 2775 <tt>mail.mail</tt>, and MUAs need to
2664 be setgid mail to do the locking mentioned above (and
2665 obviously need to avoid accessing other users' mailboxes
2666 using this privilege).</p>
2669 <tt>/etc/aliases</tt> is the source file for the system mail
2670 aliases (e.g., postmaster, usenet, etc.)--it is the one
2671 which the sysadmin and <tt>postinst</tt> scripts may edit.
2672 After <tt>/etc/aliases</tt> is edited the program or human
2673 editing it must call <prgn>newaliases</prgn>. All MTA
2674 packages should come with a <prgn>newaliases</prgn> program,
2675 even if it does nothing, but older MTA packages do not do
2676 this so programs should not fail if <prgn>newaliases</prgn>
2677 cannot be found.</p>
2680 The convention of writing <tt>forward to
2681 <var>address</var></tt> in the mailbox itself is not
2682 supported. Use a <tt>.forward</tt> file instead.</p>
2685 The location for the <prgn>rmail</prgn> program used by UUCP
2686 for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
2687 FSSTND. Likewise, <prgn>rsmtp</prgn>, for receiving
2688 batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
2692 If you need to know what name to use (for example) on
2693 outgoing news and mail messages which are generated locally,
2694 you should use the file <tt>/etc/mailname</tt>. It will
2695 contain the portion after the username and <tt>@</tt> (at)
2696 sign for email addresses of users on the machine (followed
2700 A package should check for the existence of this file. If
2701 it exists it should use it without comment. (An MTA's
2702 prompting configuration script may wish to prompt the user
2703 even if it finds this file exists.) If it does not exist it
2704 should prompt the user for the value and store it in
2705 <tt>/etc/mailname</tt> as well as using it in the package's
2706 configuration. The prompt should make it clear that the
2707 name will not just be used by that package. For example, in
2708 this situation the INN package says:
2710 Please enter the `mail name' of your system. This is the
2711 hostname portion of the address to be shown on outgoing
2712 news and mail messages. The default is
2713 <var>syshostname</var>, your system's host name. Mail
2714 name [`<var>syshostname</var>']:
2716 where <var>syshostname</var> is the output of <tt>hostname
2717 --fqdn</tt>.</p></sect>
2721 <heading>News system configuration</heading>
2724 All the configuration files related to the NNTP (news)
2725 servers and clients should be located under
2726 <tt>/etc/news</tt>.</p>
2729 There are some configuration issues that apply to a number
2730 of news clients and server packages on the machine. These
2734 <tag>/etc/news/organization</tag>
2735 <item><p>A string which shall appear as the
2736 organization header for all messages posted
2737 by NNTP clients on the machine</p></item>
2739 <tag>/etc/news/server</tag>
2740 <item><p>Contains the FQDN of the upstream NNTP
2741 server, or localhost if the local machine is
2742 an NNTP server.</p></item>
2745 Other global files may be added as required for cross-package news
2746 configuration.</p></sect>
2750 <heading>Programs for the X Windows system</heading>
2753 Some programs can be configured with or without support for
2754 X Windows. Typically these binaries produced when
2755 configured for X will need the X shared libraries to
2759 Such programs should be configured <em>with</em> X support,
2760 and should declare a dependency on <tt>xlib6g</tt> (for the
2761 X11R6 libraries). Users who wish to use the program can
2762 install just the relatively small <tt>xlib6g</tt> package,
2763 and do not need to install the whole of X.</p>
2766 Do not create two versions (one with X support and one
2767 without) of your package.</p>
2770 <em>Application defaults</em> files have to be installed in
2772 <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
2773 considered as part of the program code. Thus, they should
2774 not be modified and should not be tagged as
2775 <em>conffile</em>. If the local system administrator wants
2776 to customise X applications globally, the file
2777 <tt>/etc/X11/Xresources</tt> should be used.</p>
2780 If you package a program that requires a non-free Motif
2781 library, it would be good if you can provide a "foo-smotif"
2782 and a "foo-dmotif" package, containing a (against Motif
2783 libraries) statically and a dynamically linked version,
2784 respectively. This way, users without Motif can use the
2785 package too, while users that have Motif installed get the
2786 advantages of a dynamically linked version.</p>
2789 However, if your package works reliably with lesstif, you
2790 should package it with lesstif, and not with Motif at
2794 Note, that packages that require non-free Motif libraries
2795 can't go into the main section. If your package is free
2796 otherwise, it should go into contrib. Otherwise it has to go
2797 into non-free.</p></sect>
2801 <heading>Emacs lisp programs</heading>
2804 Please refer to the `Debian Emacs Policy' (documented in
2805 <tt>debian-emacs-policy.gz</tt> of the
2806 <prgn>emacsen-common</prgn> package) for details of how to
2807 package emacs lisp programs.</p></sect>
2811 <heading>Games</heading>
2814 The permissions on /var/lib/games are 755
2815 <tt>root.root</tt>.</p>
2818 Each game decides on its own security policy.</p>
2821 Games which require protected, privileged access to
2822 high-score files, savegames, etc., must be made
2823 set-<em>group</em>-id (mode 2755) and owned by
2824 <tt>root.games</tt>, and use files and directories with
2825 appropriate permissions (770 <tt>root.games</tt>, for
2826 example). They must <em>not</em> be made
2827 set-<em>user</em>-id, as this causes security problems. (If
2828 an attacker can subvert any set-user-id game they can
2829 overwrite the executable of any other, causing other players
2830 of these games to run a Trojan horse program. With a
2831 set-group-id game the attacker only gets access to less
2832 important game data, and if they can get at the other
2833 players' accounts at all it will take considerably more
2837 Some packages, for example some fortune cookie programs, are
2838 configured by the upstream authors to install with their
2839 data files or other static information made unreadable so
2840 that they can only be accessed through set-id programs
2841 provided. Do not do this in a Debian package: anyone can
2842 download the <tt>.deb</tt> file and read the data from it,
2843 so there is no point making the files unreadable. Not
2844 making the files unreadable also means that you don't have
2845 to make so many programs set-id, which reduces the risk of a
2849 As described in the FSSTND, binaries of games should be
2850 installed in the directory <tt>/usr/games</tt>. This also
2851 applies to games that use the X windows system. Manual pages
2852 for games (X and non-X games) should be installed in
2853 <tt>/usr/man/man6</tt>.</p>
2857 <chapt><heading>Documentation</heading>
2861 <heading>Manual pages</heading>
2864 You must install manual pages in <prgn>nroff</prgn> source
2865 form, in appropriate places under <tt>/usr/man</tt>. You
2866 should only use sections 1 to 9 (see the FSSTND for more
2867 details). You must <em>not</em> install a preformatted `cat
2871 If no manual page is available for a particular program,
2872 utility or function and this is reported as a bug on
2873 debian-bugs, a symbolic link from the requested manual page
2874 to the <manref name="undocumented" section="7"> manual page
2875 should be provided. This symbolic link can be created from
2876 <tt>debian/rules</tt> like this:
2878 ln -s ../man7/undocumented.7.gz \
2879 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
2881 This manpage claims that the lack of a manpage has been
2882 reported as a bug, so you may only do this if it really has
2883 (you can report it yourself, if you like). Do not close the
2884 bug report until a proper manpage is available.</p>
2887 You may forward a complaint about a missing manpage to the
2888 upstream authors, and mark the bug as forwarded in the
2889 Debian bug tracking system. Even though the GNU Project do
2890 not in general consider the lack of a manpage to be a bug,
2891 we do--if they tell you that they don't consider it a bug
2892 you should leave the bug in our bug tracking system open
2896 Manual pages should be installed compressed using <tt>gzip
2900 If one manpage needs to be accessible via several names it
2901 is better to use a symbolic link than the <tt>.so</tt>
2902 feature, but there is no need to fiddle with the relevant
2903 parts of the upstream source to change from <tt>.so</tt> to
2904 symlinks--don't do it unless it's easy. Do not create hard
2905 links in the manual page directories, and do not put
2906 absolute filenames in <tt>.so</tt> directives. The filename
2907 in a <tt>.so</tt> in a manpage should be relative to the
2908 base of the manpage tree (usually
2909 <tt>/usr/man</tt>).</p></sect>
2913 <heading>Info documents</heading>
2916 Info documents should be installed in <tt>/usr/info</tt>.
2917 They should be compressed with <tt>gzip -9</tt>.</p>
2920 Your package must call <prgn>install-info</prgn> to update the Info
2922 file, in its post-installation script:
2924 install-info --quiet --section Development Development \
2925 /usr/info/foobar.info
2929 It is a good idea to specify a section for the location of
2930 your program; this is done with the <tt>--section</tt>
2931 switch. To determine which section to use, you should look
2932 at <tt>/usr/info/dir</tt> on your system and choose the most
2933 relevant (or create a new section if none of the current
2934 sections are relevant). Note that the <tt>--section</tt>
2935 flag takes two arguments; the first is a regular expression
2936 to match (case-insensitively) against an existing section,
2937 the second is used when creating a new one.</p>
2940 You must remove the entries in the pre-removal script:
2942 install-info --quiet --remove /usr/info/foobar.info
2946 If <prgn>install-info</prgn> cannot find a description entry
2947 in the Info file you will have to supply one. See <manref
2948 name="install-info" section="8"> for details.</p>
2952 <heading>Additional documentation</heading>
2955 Any additional documentation that comes with the package can
2956 be installed at the discretion of the package maintainer.
2957 Text documentation should be installed in a directory
2958 <tt>/usr/doc/<var>package</var></tt>, where
2959 <var>package</var> is the name of the package, and
2960 compressed with <tt>gzip -9</tt> unless it is small.</p>
2963 If a package comes with large amounts of documentation which
2964 many users of the package will not require you should create
2965 a separate binary package to contain it, so that it does not
2966 take up disk space on the machines of users who do not need
2967 or want it installed.</p>
2970 It is often a good idea to put text information files
2971 (<tt>README</tt>s, changelogs, and so forth) that come with
2972 the source package in <tt>/usr/doc/<var>package</var></tt>
2973 in the binary package. However, you don't need to install
2974 the instructions for building and installing the package, of
2979 <heading>Preferred documentation formats</heading>
2982 The unification of Debian documentation is being carried out
2986 If your package comes with extensive documentation in a
2987 mark up format that can be converted to various other formats
2988 you should if possible ship HTML versions in a binary
2989 package, in the directory
2990 <tt>/usr/doc/<var>appropriate package</var></tt> or its
2993 <p>The rationale: The important thing here is that HTML
2994 docs should be available in <em>some</em> package, not
2995 necessarily in the main binary package, though. </p>
3000 Other formats such as PostScript may be provided at your
3004 <sect id="copyrightfile">
3005 <heading>Copyright information</heading>
3008 Every package must be accompanied by a verbatim copy of its
3009 copyright and distribution license in the file
3010 /usr/doc/<package-name>/copyright. This file must
3011 neither be compressed nor be a symbolic link.</p>
3014 In addition, the copyright file must say where the upstream
3015 sources (if any) were obtained, and explain briefly what
3016 modifications were made in the Debian version of the package
3017 compared to the upstream one. It must name the original
3018 authors of the package and the Debian maintainer(s) who were
3019 involved with its creation.</p>
3022 /usr/doc/<package-name> may be a symbolic link to a
3023 directory in /usr/doc only if two packages both come from
3024 the same source and the first package has a "Depends"
3025 relationship on the second. These rules are important
3026 because copyrights must be extractable by mechanical
3030 Packages distributed under the UCB BSD license, the Artistic
3031 license, the GNU GPL, and the GNU LGPL should refer to the
3032 files /usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
3033 /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.</p>
3036 Do not use the copyright file as a general <tt>README</tt>
3037 file. If your package has such a file it should be
3038 installed in <tt>/usr/doc/<var>package</var>/README</tt> or
3039 <tt>README.Debian</tt> or some other appropriate place.</p>
3043 <heading>Examples</heading>
3046 Any examples (configurations, source files, whatever),
3047 should be installed in a directory
3048 <tt>/usr/doc/<var>package</var>/examples</tt>. These files
3049 should not be referenced by any program--they're there for
3050 the benefit of the system administrator and users, as
3051 documentation only.</p>
3054 <sect id="instchangelog">
3055 <heading>Changelog files</heading>
3058 This installed file must contain a copy of the
3059 <tt>debian/changelog</tt> file from your Debian source tree,
3060 and a copy of the upstream changelog file if there is one.
3061 The debian/changelog file should be installed in
3062 <tt>/usr/doc/<var>package</var></tt> as
3063 <tt>changelog.Debian.gz</tt>. If the upstream changelog
3064 file is text formatted, it must be accessible as
3065 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>. If the
3066 upstream changelog file is HTML formatted, it must be
3067 accessible as <tt>/usr/doc/<var>package</var>/changelog.html.gz</tt>.
3068 If the upstream changelog files do not already conform to
3069 this naming convention, then this may be achieved by either
3070 renaming the files or adding a symbolic link at the
3071 packaging developer's discretion. </p>
3074 Both should be installed compressed using <tt>gzip -9</tt>,
3075 as they will become large with time even if they start out
3079 If the package has only one changelog which is used both as
3080 the Debian changelog and the upstream one because there is
3081 no separate upstream maintainer then that changelog should
3082 usually be installed as
3083 <tt>/usr/doc/<var>package</var>/changelog.gz</tt>; if there
3084 is a separate upstream maintainer, but no upstream
3085 changelog, then the Debian changelog should still be called
3086 <tt>changelog.Debian.gz</tt>.</p>