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"
22 <title>Debian Policy Manual
23 <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
24 <author>Christian Schwarz <email/schwarz@debian.org/
25 <author>revised: David A. Morris <email/bweaver@debian.org/
26 <version>version &version;, &date;
29 This manual describes the policy requirements for the Debian GNU/Linux
30 distribution. This includes the structure and contents of the Debian
31 archive, several design issues of the operating system, as well as
32 technical requirements that each package must satisfy to be included
36 <copyright>Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz.
39 This manual is free software; you may redistribute it and/or modify it
40 under the terms of the GNU General Public License as published by the
41 Free Software Foundation; either version 2, or (at your option) any
45 This is distributed in the hope that it will be useful, but
46 <em>without any warranty</em>; without even the implied warranty of
47 merchantability or fitness for a particular purpose. See the GNU
48 General Public License for more details.
51 A copy of the GNU General Public License is available as
52 <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
53 distribution or on the World Wide Web at
54 <url id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it
55 by writing to the Free Software Foundation, Inc., 59 Temple Place -
56 Suite 330, Boston, MA 02111-1307, USA.
61 <chapt id="scope">About this manual
67 This manual describes the policy requirements for the Debian GNU/Linux
68 distribution. This includes the structure and contents of the Debian
69 archive, several design issues of the operating system, as well as
70 technical requirements that each package must satisfy to be included
74 This manual does <em/not/ describe the technical mechanisms involved
75 in package creation, installation, and removal. This information can
76 be found in the <em>Debian Packaging Manual</em> and the <em>Debian
77 System Administrators' Manual</em>.
80 This document assumes familiarity with these other two manuals.
81 Unfortunately, the <em>System Administrators' Manual</em> does not
85 Much of the information presented in this manual will be useful even
86 when building a package which is to be distributed in some other way
90 <sect>New versions of this document
93 The current version of this document is always accessible from the
95 <url id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz">
96 or from the Debian WWW server at
97 <url id="http://www.debian.org/doc/manuals/debian-policy/">
100 There is also a home page for the <em>Debian Policy Manual</em> that
101 contains links to the current development version of this document as
102 well as an archive of old versions. The URL is
103 <url id="http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/">
106 In addition, this manual is distributed via the Debian package
107 <tt>debian-policy</tt>
113 As the Debian GNU/Linux system is continuously evolving this manual is
114 changed from time to time.
117 While the authors of this document tried hard not to include any typos
118 or other errors these still occur. If you discover an error in this
119 manual or if you want to tell us any comments, suggestions, or critics
120 please send an email to the Debian Policy Manager, Christian
121 Schwarz <email>schwarz@debian.org</email>, the developers' mailing
122 list <email>debian-devel@lists.debian.org</email>, or submit a bug report
123 against the <tt>debian-policy</tt> package.
126 <chapt>The Debian Archive
129 The Debian GNU/Linux system is maintained and distributed as a
130 collection of <em>packages</em>. Since there are so many of them (over
131 1000) they are split into <em>sections</em> and <em>priorities</em> to
132 simplify handling of them.
135 The effort of the Debian project is to build a free operating system,
136 but not every package we want to make accessible is <em>free</em> in
137 our sense (see Debian Free Software Guidelines, below), or may be
138 imported/exported without restrictions. Thus, the archive is split
139 into the sections <em/main/, <em/non-us/, <em/non-free/, and
143 The <em/main/ section forms the <em>Debian GNU/Linux distribution</em>.
146 Packages in the other sections are not considered as part of the
147 Debian distribution, though we support their use, and we provide
148 infrastructure for them (such as our bug-tracking system and mailing
149 lists). This Debian Policy Manual applies to these packages as well.
152 <sect id="pkgcopyright">Package copyright and sections
155 The aims of this policy are:
160 We want to make as much software available as we can.<p>
162 We want to encourage everyone to write free software.<p>
164 We want to make it easy for people to produce CD-ROMs of our system
165 without violating any licenses, import/export restrictions, or any
170 <sect1>The Debian Free Software Guidelines
173 The Debian Free Software Guidelines (DFSG) as is our definition of `free'
178 <item>Free Redistribution
180 The license of a Debian component may not restrict any party from
181 selling or giving away the software as a component of an aggregate
182 software distribution containing programs from several different
183 sources. The license may not require a royalty or other fee for such
190 The program must include source code, and must allow distribution in
191 source code as well as compiled form.
197 The license must allow modifications and derived works, and must allow
198 them to be distributed under the same terms as the license of the original
202 <item>Integrity of The Author's Source Code
205 The license may restrict source-code from being distributed in modified
206 form <em/only/ if the license allows the distribution of ``patch files''
207 with the source code for the purpose of modifying the program at build
208 time. The license must explicitly permit distribution of software built
209 from modified source code. The license may require derived works to
210 carry a different name or version number from the original software.
211 (This is a compromise. The Debian group encourages all authors to not
212 restrict any files, source or binary, from being modified.)
215 <item>No Discrimination Against Persons or Groups
218 The license must not discriminate against any person or group of
222 <item>No Discrimination Against Fields of Endeavor
225 The license must not restrict anyone from making use of the program
226 in a specific field of endeavor. For example, it may not restrict the
227 program from being used in a business, or from being used for genetic
231 <item>Distribution of License
234 The rights attached to the program must apply to all to whom the
235 program is redistributed without the need for execution of an
236 additional license by those parties.
239 <item>License Must Not Be Specific to Debian
242 The rights attached to the program must not depend on the program's
243 being part of a Debian system. If the program is extracted from Debian
244 and used or distributed without Debian but otherwise within the terms
245 of the program's license, all parties to whom the program is redistributed
246 should have the same rights as those that are granted in conjunction with
250 <item>License Must Not Contaminate Other Software
253 The license must not place restrictions on other software that is
254 distributed along with the licensed software. For example, the
255 license must not insist that all other programs distributed on the
256 same medium must be free software.
259 <item>Example Licenses
261 The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses
262 that we consider <em/free/.
267 <sect1>The main section
270 Every package in "main" must comply with the DFSG (Debian Free
271 Software Guidelines).
274 In addition, the packages in "main"
278 <item>must not require a package outside of "main" for compilation or
279 execution (thus, the package may not declare a "Depends" or
280 "Recommends" relationship on a non-main package),
282 <item>must not be so buggy that we refuse to support them,
284 <item>must meet all policy requirements presented in this manual.
288 <sect1>The contrib section
291 Every package in "contrib" must comply with the DFSG.
294 Examples of packages which would be included in "contrib" are
297 <item>free packages which require "contrib", "non-free", or "non-US"
298 packages or packages which are not in our archive at all for
299 compilation or execution,
301 <item>wrapper packages or other sorts of free accessories for
304 <item>packages which we don't want to support because they are too
307 <item>packages which fail to meet some other policy requirements in
312 <sect1>The non-free section
315 `Non-free' contains packages which are not compliant with the DFSG
316 or which are encumbered by patents or other legal issues that make
317 their distribution problematic.
320 All packages in `non-free' must be electronically distributable across
321 international borders.
324 <sect1>The non-us server
327 Some programs with cryptographic program code must be stored on the
328 "non-us" server because of export restrictions of the U.S.
331 This applies only to packages which contain cryptographic code. A package
332 containing a program with an interface to a cryptographic program or a
333 program that's dynamically linked against a cryptographic library can be
334 distributed if it is capable of running without the cryptography library
338 <sect1>Further copyright considerations
341 Every package must be accompanied by a verbatim copy of its copyright
342 and distribution license in the file
343 /usr/doc/<package-name>/copyright (see <ref id="copyrightfile">
347 We reserve the right to restrict files from being included anywhere in
351 <item>their use or distribution would break a law,
353 <item>there is an ethical conflict in their distribution or use,
355 <item>we would have to sign a license for them, or
357 <item>their distribution would conflict with other project policies.
361 Programs whose authors encourage the user to make donations are fine
362 for the main distribution, provided that the authors do not claim that
363 not donating is immoral, unethical, illegal or something similar;
364 otherwise they must go in contrib (or non-free, if even distribution
365 is restricted by such statements).
368 Packages whose copyright permission notices (or patent problems) do
369 not allow redistribution even of only binaries, and where no special
370 permission has been obtained, cannot be placed on the Debian FTP site and
374 Note, that under international copyright law (this applies in
375 the United States, too) <em/no/ distribution or
376 modification of a work is allowed without an explicit notice saying
377 so. Therefore a program without a copyright notice <em/is/
378 copyrighted and you may not do anything to it without risking being
379 sued! Likewise if a program has a copyright notice but no statement
380 saying what is permitted then nothing is permitted.
383 Many authors are unaware of the problems that restrictive copyrights
384 (or lack of copyright notices) can cause for the users of their
385 supposedly-free software. It is often worthwhile contacting such
386 authors diplomatically to ask them to modify their license
387 terms. However, this is a politically difficult thing to do and you
388 should ask for advice on <tt/debian-devel/ first.
391 When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be
392 prepared to provide us with the copyright statement. Software covered
393 by the GPL, public domain software and BSD-like copyrights are safe;
394 be wary of the phrases `commercial use prohibited' and `distribution
401 The packages in the <em/main/, <em/contrib/, and <em/non-free/
402 sections are grouped further into <em>subsections</em> to simplify
406 The section for each package is specified in the package's <em>control
407 record</em>. However, the maintainer of the Debian archive may
408 override this selection to assure the consistency of the Debian
412 Please check the current Debian distribution to see which sections are
419 Each package is given a certain <em>priority</em> value, which is
420 included in the package's <em>control
421 record</em>. This information is used in the Debian package management
422 tool to separate high-priority packages from less-important packages.
425 The following <em>priority levels</em> are supported by the Debian
426 package management system, <prgn/dpkg/.
432 <tt/required/ packages are necessary for the proper functioning of the
433 system. You must not remove these packages or your system may become
434 totally broken and you may not even be able to use
435 <prgn/dpkg/ to put things back. Systems with only the <tt/required/
436 packages are probably unusable, but they do have enough functionality
437 to allow the sysadmin to boot and install more software.
441 Important programs, including those which one would expect to find on
442 any Unix-like system. If the expectation is that an experienced Unix
443 person who found it missing would say `What the F*!@<+ is going on,
444 where is <prgn/foo/', it should be in <tt/important/. This is an
445 important criterion because we are trying to produce, amongst other
446 things, a free Unix. Other packages without which the system will not
447 run well or be usable should also be here. This does <em/not/
448 include Emacs or X11 or TeX or any other large applications. The
449 <tt/important/ packages are just a bare minimum of commonly-expected
454 These packages provide a reasonably small but not too limited
455 character-mode system. This is what will install by default if the
456 user doesn't select anything else. It doesn't include many large
457 applications, but it does include Emacs (this is more of a piece of
458 infrastructure than an application) and a reasonable subset of TeX and
459 LaTeX (if this is possible without X).
463 (In a sense everything is optional that isn't required, but that's not
464 what is meant here.) This is all the software that you might
465 reasonably want to install if you didn't know what it was or don't
466 have specialised requirements. This is a much larger system and includes
467 X11, a full TeX distribution, and lots of applications.
471 This contains packages that conflict with others with higher
472 priorities, or are only likely to be useful if you already know what
473 they are or have specialised requirements.
478 Packages may not depend on packages with lower priority values.
479 If this should happen, one of the priority values will have to
483 <sect>Binary packages
486 The Debian GNU/Linux distribution is based on the Debian package
487 management system, called <prgn/dpkg/. Thus, all packages in the
488 Debian distribution have to be provided in the <tt/.deb/ file format.
491 <sect1>The package name
494 Every package must have a name that's unique within the Debian
498 Package names may only consist of lower case letters, digits (0-9),
499 plus (+) or minus (-) signs, and periods (.).
502 The package name is part of the file name of the <tt/.deb/ file and is
503 included in the control field information.
506 <sect1>The maintainer of a package
509 Every package must have exactly one maintainer at a time. This person
510 is responsible that the license of the package's software complies with
511 the policy of the distribution this package is included in.
514 The maintainer must be specified in the <tt/Maintainer/ control field
515 with the correct name and a working email address for the Debian
516 maintainer of the package. If one person maintains several packages
517 he/she should try to avoid having different forms of their name and
518 email address in different <tt/Maintainer/ fields.
521 If the maintainer of a package quits from the Debian project the
522 Debian QA Group takes over the maintainership of the package until
523 someone else volunteers for that task. These packages are called
524 <em>orphaned packages</em>.
527 <sect1>The description of a package
530 Every Debian package should have an extended description stored in the
531 appropriate field of the control record.
534 The description should be written so that it tells the user what they
535 need to know to decide whether to install the package. This
536 description should not just be copied from the blurb for the program.
537 Instructions for configuring or using the package should not be
538 included--that is what installation scripts, manual pages, Info files,
539 etc. are for. Copyright statements and other
540 administrivia should not be included--that is what the copyright file
547 Every package has to specify the dependency information about other
548 packages, that are required for the first to work correctly.
551 For example, for any shared libraries required by dynamically-linked
552 executable binary in a package a dependency entry has to be provided.
555 It is not necessary for other packages to declare any dependencies
556 they have on other packages which are marked <tt/Essential/ (see below).
559 Sometimes, a package requires another package to be installed
560 <em>and</em> configured before it can be installed. In this case,
561 you'll have to specify a <tt/Pre-Depends/ entry for the package.
564 You must not specify a <tt/Pre-Depends/ entry for a package before
565 this has been discussed on the <tt/debian-devel/ mailing list and a
566 consensus about doing that has been reached.
569 <sect1>Virtual packages
572 Sometimes, there are several packages doing more-or-less the same
573 job. In this case, it's useful to define a <em>virtual package</em>
574 who's name describes the function the packages have. (The virtual
575 packages just exist logically, not physically--that's why they are
576 called <em>virtual</em>.) The packages with this particular function
577 will then <em>provide</em> the virtual package. Thus, any other
578 package requiring that function can simply depend on the virtual
579 package without having to specify all possible packages individually.
582 All packages must use virtual package names where appropriate, and
583 arrange to create new ones if necessary. They must not use virtual
584 package names (except privately, amongst a cooperating group of
585 packages) unless they have been agreed upon and appear in the list of
586 virtual package names.
589 The latest version of the authoritative list of virtual package names
590 can be found on <ftpsite>ftp.debian.org</> in
591 <ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
592 or your local mirror. In addition, it is included in the
593 <tt>debian-policy</tt> package. The procedure for updating the list is
594 described at the top of the file.
600 The packages included in the <tt/base/ section have a special
601 function. They form a minimum subset of the Debian GNU/Linux system
602 that is installed before everything else on a new system. Thus, only
603 very few packages are allowed to go into the <tt/base/ section to keep
604 the required disk usage very small.
607 Most of these packages should have the priority value <tt/required/ or
608 at least <tt/important/, and many of them will be tagged
609 <tt/essential/ (see below).
612 You must not place any packages into the <tt/base/ section before this
613 has been discussed on the <tt/debian-devel/ mailing list and a
614 consensus about doing that has been reached.
617 <sect1>Essential packages
620 Some packages are tagged <tt/essential/. (They have <tt/Essential:
621 yes/ in their package control record.) This flag is used for packages
622 that are <em>essential</em> for a system.
625 Since these packages can not easily be removed (you'll have to specify
626 an extra <em>force option</em> to <prgn/dpkg/) this flag should only
627 be used where absolutely necessary.
629 A shared library package should not be tagged <em>essential</em>--the
630 dependencies will prevent its premature removal, and we need to be
631 able to remove it when it has been superseded.
634 You must not tag any packages <tt/essential/ before this has been
635 discussed on the <tt/debian-devel/ mailing and a consensus about doing
636 that has been reached.
639 <sect1>Maintainer scripts
642 The package installation scripts should avoid producing output which
643 it is unnecessary for the user to see and should rely on <prgn/dpkg/
644 to stave off boredom on the part of a user installing many packages.
645 This means, amongst other things, using the <tt/--quiet/ option on
649 Packages should try to minimise the amount of prompting they need to
650 do, and they should ensure that the user will only ever be asked each
651 question once. This means that packages should try to use appropriate
652 shared configuration files (such as <tt>/etc/papersize</> and
653 <tt>/etc/nntpserver</>), rather than each prompting for their own list
654 of required pieces of information.
657 It also means that an upgrade should not ask the same questions again,
658 unless the user has used <tt/dpkg --purge/ to remove the package's
659 configuration. The answers to configuration questions should be
660 stored in an appropriate place in <tt>/etc</> so that the user can
661 modify them, and how this has been done should be documented.
664 If a package has a vitally important piece of information to pass to
665 the user (such as "don't run me as I am, you must edit the following
666 configuration files first or you risk your system emitting
667 badly-formatted messages"), it should display this in the
668 <prgn/postinst/ script and prompt the user to hit return to
669 acknowledge the message. Copyright messages do not count as vitally
670 important (they belong in <tt>/usr/doc/copyright</>); neither do
671 instructions on how to use a program (these should be in on line
672 documentation, where all the users can see them).
675 Any necessary prompting should almost always be confined to the
676 post-installation script, and should be protected with a conditional
677 so that unnecessary prompting doesn't happen if a package's
678 installation fails and the <prgn/postinst/ is called with
679 <tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
682 Errors which occur during the execution of an installation script
683 <em/must/ be checked and the installation <em/must not/ continue after
687 Note, that <ref id="scripts">, in general applies to package
688 maintainer scripts, too.
691 Do not use <prgn/dpkg-divert/ on a file belonging to another package
692 without consulting the maintainer of that package first.
695 In order for <prgn/update-alternatives/ to work correctly all the
696 packages which supply an instance of the `shared' command name (or, in
697 general, filename) must use it. You can use <tt/Conflicts/ to force
698 the deinstallation of other packages supplying it which do not (yet)
699 use <prgn/update-alternatives/. It may in this case be appropriate to
700 specify a conflict on earlier versions on something--this is an
701 exception to the usual rule that this is not allowed.
704 <sect>Source packages
707 <sect1>Standards conformance
710 You should specify the most recent version of the packaging standards
711 with which your package complies in the source package's
712 <tt/Standards-Version/ field.
715 This value will be used to file bug reports automatically if your
716 package becomes too much out of date.
719 The value corresponds to a version of the Debian manuals, as can be
720 found on the title page or page headers and footers (depending on the
724 The version number has four components--major and minor number and
725 major and minor patch level. When the standards change in a way that
726 requires every package to change the major number will be changed.
727 Significant changes that will require work in many packages will be
728 signaled by a change to the minor number. The major patch level will
729 be changed for any change to the meaning of the standards, however
730 small; the minor patch level will be changed when only cosmetic,
731 typographical or other edits which do not change the meaning are made,
732 or changes which do not affect the contents of packages.
735 You should regularly, and especially if your package has become out of
736 date, check for the newest Policy Manual available and update your
737 package, if necessary. When your package complies with the new
738 standards you may update the <tt/Standards-Version/ source package
739 field and release it.
742 <sect1>Changes to the upstream sources
745 If changes to the source code are made that are generally applicable
746 please try to get them included in the upstream version of the package
747 by supplying the upstream authors with the changes in whatever form
751 If you need to configure the package differently for Debian or for
752 Linux, and the upstream source doesn't provide a way to configure it
753 the way you need to, please add such configuration facilities (for
754 example, a new <prgn/autoconf/ test or <tt/#define/) and send the
755 patch to the upstream authors, with the default set to the way they
756 originally had it. You can then easily override the default in your
757 <tt>debian/rules</tt> or wherever is appropriate.
760 Please make sure that the <prgn/configure/ utility detects the correct
761 architecture specification string (refer to <ref id="arch-spec"> for
765 If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
766 scripts are used, you should edit the <tt/.in/ files rather than
767 editing the <prgn/Makefile/ directly. This allows the user to
768 reconfigure the package if necessary. You should <em/not/ configure
769 the package and edit the generated <prgn/Makefile/! This makes it
770 impossible for someone else to later reconfigure the package.
773 <sect1>Documenting your changes
776 Document your changes and updates to the source package properly in
777 the <tt>debian/changelog</tt> file.
780 A copy of the file which will be installed in
781 <tt>/usr/doc/<var/package//copyright</tt> should be in
782 <tt>debian/copyright</tt>.
785 In non-experimental packages you may only use a format for
786 <tt>debian/changelog</> which is supported by the most recent released
787 version of <prgn/dpkg/. If your format is not supported and there is
788 general support for it you should contact the <prgn/dpkg/ maintainer
789 to have the parser script for your format included in the <prgn/dpkg/
790 package. (You will need to agree that the parser and its
791 manpage may be distributed under the GNU GPL, just as the rest of
795 <sect1>Error trapping in makefiles
798 When <prgn/make/ invokes a command in a makefile (including your
799 package's upstream makefiles and the <tt>debian/rules</>) it does so
800 using <tt/sh/. This means that <tt/sh/'s usual bad error handling
801 properties apply: if you include a miniature script as one of the
802 commands in your makefile you'll find that if you don't do anything
803 about it then errors are not detected and <prgn/make/ will blithely
804 continue after problems.
807 Every time you put more than one shell command (this includes using a
808 loop) in a makefile command you <em/must/ make sure that errors are
809 trapped. For simple compound commands, such as changing directory and
810 then running a program, using <tt/&&/ rather than semicolon as
811 a command separator is sufficient. For more complex commands
812 including most loops and conditionals you must include a separate
813 <tt/set -e/ command at the start of every makefile command that's
814 actually one of these miniature shell scripts.
817 <sect1>Obsolete constructs and libraries
820 The include file <prgn/<varargs.h>/ is provided to support
821 end-users compiling very old software; the library <tt/libtermcap/ is
822 provided to support the execution of software which has been linked
823 against it (either old programs or those such as Netscape which are
824 only available in binary form).
827 Debian packages should be ported to include <prgn/<stdarg.h>/ and
828 <tt/ncurses/ when they are built.
831 <chapt>The Operating System
834 <sect>Filesystem hierarchy
837 <sect1>Linux Filesystem Structure
840 The location of all installed files and directories must comply fully
841 with the Linux Filesystem Structure (FSSTND). The latest version of
842 this document can be found alongside this manual or on
843 <ftpsite/tsx-11.mit.edu/ in
844 <ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific
845 questions about following the standard may be asked on
846 <prgn/debian-devel/, or referred to Daniel Quinlan, the FSSTND
847 coordinator, at <email/quinlan@pathname.com/.
850 <sect1>Site-specific programs
853 As mandated by the FSSTND no package should place any files in
854 <tt>/usr/local</>, either by putting them in the filesystem archive to
855 be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
859 However, the package should create empty directories below
860 <tt>/usr/local</> so that the system administrator knows where to
861 place site-specific files. These directories should be removed on
862 package removal if they are empty.
865 Note, that this applies only to directories <em/below/
866 <tt>/usr/local</>, not <em/in/ <tt>/usr/local</>. The directory
867 <tt>/usr/local</> itself may only contain the sub-directories listed
868 in FSSTND, section 4.8. However, you may create directories below them
869 as you wish. You may not remove any of the directories listed in 4.8,
870 even if you created them.
873 Since <tt>/usr/local</> may be mounted read-only from a remote server,
874 these directories have to be created and removed by the <tt/postinst/
875 and <tt/prerm/ maintainer scripts. These scripts must not fail if
876 either of these operations fail. (In the future, it will be possible to
877 tell <prgn/dpkg/ not to unpack files matching certain patterns, so
878 that the directories can be included in the <tt/.deb/ packages and
879 system administrators who do not wish these directories in /usr/local
880 do not need to have them.)
883 For example, the <prgn/emacs/ package will contain
885 mkdir -p /usr/local/lib/emacs/site-lisp || true
887 in the <tt/postinst/ script, and
889 rmdir /usr/local/lib/emacs/site-lisp && \
890 rmdir /usr/local/lib/emacs || \
893 in the <tt/prerm/ script.
896 If you do create a directory in <tt>/usr/local</> for local additions
897 to a package, you must ensure that settings in <tt>/usr/local</tt>
898 take precedence over the equivalents in <tt>/usr</tt>.
901 The <tt>/usr/local</> directory itself and all the subdirectories
902 created by the package should have permissions 2775 (group-writable
903 and set-group-id) and be owned by <tt/root.staff/.
906 <sect>Users and groups
909 The Debian system can be configured to use either plain or shadow
913 Some user ids (UIDs) and group ids (GIDs) are reserved globally for
914 use by certain packages. Because some packages need to include files
915 which are owned by these users or groups, or need the ids compiled
916 into binaries, these ids must be used on any Debian system only for
917 the purpose for which they are allocated. This is a serious
918 restriction, and we should avoid getting in the way of local
919 administration policies. In particular, many sites allocate users
920 and/or local system groups starting at 100.
923 Apart from this we should have dynamically allocated ids, which should
924 by default be arranged in some sensible order--but the behaviour
925 should be configurable.
928 No package except <tt>base-passwd</> may modify <tt>/etc/passwd</>,
929 <tt>/etc/shadow</>, or <tt>/etc/group</>.
932 The UID and GID ranges are as follows:
936 Globally allocated by the Debian project, must be the same on
937 every Debian system. These ids will appear in the <tt>passwd</> and
939 files of all Debian systems, new ids in this range being added
940 automatically as the <tt>base-passwd</> package is updated.
943 Packages which need a single statically allocated uid or gid should
944 use one of these; their maintainers should ask the <tt>base-passwd</>
950 Dynamically allocated system users and groups. Packages
951 which need a user or group, but can have this user or group allocated
952 dynamically and differently on each system, should use `<tt>adduser
953 --system</>' to create the group and/or user. <prgn>adduser</> will
955 existence of the user or group, and if necessary choose an unused id
956 based on the ranged specified in <tt>adduser.conf</>.
961 Dynamically allocated user accounts. By default <prgn>adduser</>
962 will choose UIDs and GIDs for user accounts in this range, though
963 <tt>adduser.conf</> may be used to modify this behaviour.
973 Globally allocated by the Debian project, but only created on
974 demand. The ids are allocated centrally and statically, but the actual
975 accounts are only created on users' systems on demand.
978 These ids are for packages which are obscure or which require many
979 statically-allocated ids. These packages should check for and create
980 the accounts in <tt>/etc/passwd</> or <tt>/etc/group</> (using
981 <prgn>adduser</> if it has this facility) if necessary. Packages
982 which are likely to require further allocations should have a `hole'
983 left after them in the allocation, to give them room to grow.
993 User `<tt>nobody</>.'
998 <tt>(uid_t)(-1) == (gid_t)(-1)</>. NOT TO BE USED, because it is the
999 error return sentinel value.
1009 It is not allowed that two packages install programs with different
1010 functionality but with the same filenames. (The case of two programs
1011 having the same functionality but different implementations is handled via
1012 `alternatives.') If this case happens, one of the programs has to be
1013 renamed. The maintainers should report this to the developers' mailing
1014 and try to find a consensus about which package will have to be renamed.
1015 If a consensus can not be reached, <em>both</> programs must be renamed.
1018 Generally the following compilation parameters should be used:
1021 CFLAGS = -O2 -g -Wall # sane warning options vary between programs
1023 install -s # (or use strip on the files in debian/tmp)
1027 Note that all installed binaries should be
1028 stripped, either by using the <tt/-s/ flag to <prgn/install/, or by calling
1029 <prgn/strip/ on the binaries after they have been copied into
1030 <tt>debian/tmp</> but before the tree is made into a package.
1033 The <tt/-g/ flag is useful on compilation so that you have available a
1034 full set of debugging symbols in your built source tree, in case
1035 anyone should file a bug report involving (for example) a core dump.
1038 The <tt/-N/ flag should not be used. On a.out systems it may have
1039 been useful for some very small binaries, but for ELF it has no good
1043 It is up to the package maintainer to decide what compilation options
1044 are best for the package. Certain binaries (such as
1045 computationally-intensive programs) may function better with certain
1046 flags (<tt/-O3/, for example); feel free to use them. Please use good
1047 judgment here. Don't use flags for the sake of it; only use them if
1048 there is good reason to do so. Feel free to override the upstream
1049 author's ideas about which compilation options are best--they are
1050 often inappropriate for our environment.
1056 All libraries must have a shared version in the lib package and a static
1057 version in the lib-dev package. The shared version must be compiled with
1058 <tt/-fPIC/, and the static version must not be. In other words, each
1059 <tt/*.c/ file is compiled twice.
1062 You have to specify the gcc option <tt>-D_REENTRANT</tt> when building
1063 a library (either static or shared) to make the library compatible with
1067 Note that all installed shared libraries should be stripped with
1069 strip --strip-unneeded <your-lib>
1071 (The option `--strip-unneeded' makes <tt>strip</tt> remove only the symbols
1072 which aren't needed for relocation processing.)
1073 Shared libraries can function perfectly well when
1074 stripped, since the symbols for dynamic linking are in a separate part
1075 of the ELF object file.
1078 Note that under some circumstances
1079 it may be useful to install a shared library unstripped, for example
1080 when building a separate package to support debugging.
1083 Please make sure that you use only released versions of shared
1084 libraries to build your packages; otherwise other users will not be
1085 able to run your binaries properly. Producing source packages that
1086 depend on unreleased compilers is also usually a bad idea.
1089 <sect1>Shared libraries
1092 Packages involving shared libraries should be split up into several
1096 For a straightforward library which has a development environment and
1097 a runtime kit including just shared libraries you need to create two
1098 packages: <tt/<var/libraryname/<var/soname// (<var/soname/ is
1099 the shared object name of the shared library--it's the thing that has
1100 to match exactly between building an executable and running it for the
1101 dynamic linker to be able run the program; usually the <var/soname/
1102 is the major number of the library) and
1103 <tt/<var/libraryname/<var/soname/-dev/.
1106 If you prefer only to support one development version at a time you
1107 may name the development package <tt/<var/libraryname/-dev/; otherwise
1108 you may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that
1109 the user only installs one development version at a time (after all,
1110 different development versions are likely to have the same header
1111 files in them, causing a filename clash if both are installed).
1112 Typically the development version will also need an exact version
1113 dependency on the runtime library, to make sure that compilation and
1114 linking happens correctly.
1117 Packages which use the shared library should have a dependency on the
1118 name of the shared library package,
1119 <tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you
1120 can have both versions of the library installed while moving from the
1121 old library to the new.
1124 If your package has some run-time support programs which use the
1125 shared library you must <em/not/ put them in the shared library
1126 package. If you do that then you won't be able to install several
1127 versions of the shared library without getting filename clashes.
1128 Instead, either create a third package for the runtime binaries (this
1129 package might typically be named <tt/<var/libraryname/-runtime/--note
1130 the absence of the <var/soname/ in the package name) or if the
1131 development package is small include them in there.
1134 If you have several shared libraries built from the same source tree
1135 you can lump them all together into a single shared library package,
1136 provided that you change all their <var/soname/s at once (so that you
1137 don't get filename clashes if you try to install different versions of
1138 the combined shared libraries package).
1141 Follow the directions in the <em>Debian Packaging Manual</em> for
1142 putting the shared library in its package, and make sure you include a
1143 <tt/shlibs/ control area file with details of the dependencies for
1144 packages which use the library.
1147 Shared libraries should <em/not/ be installed executable, since
1148 <prgn/ld.so/ does not require this and trying to execute a shared
1149 library results in a core dump.
1152 <sect1 id=scripts>Scripts
1155 All command scripts, including the package maintainer scripts inside
1156 the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
1157 the shell to be used to interpret them.
1160 In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
1163 Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
1164 start with <tt>set -e</> so that errors are detected. Every script
1165 <em/must/ use <tt/set -e/ or check the exit status of <em/every/
1169 The standard shell interpreter `<tt>/bin/sh</tt>' may be a symbolic
1170 link to any POSIX compatible shell. Thus, shell scripts specifying
1171 `<tt>/bin/sh</tt>' as interpreter may only use POSIX features. If a
1172 script requires non-POSIX features from the shell interpreter, the
1173 appropriate shell has to be specified in the first line of the script
1174 (e.g., `<tt>#!/bin/bash</tt>') and the package has to depend on the
1175 package providing the shell (unless the shell package is marked
1176 `Essential', e.g., in the case of <prgn/bash/).
1179 Restrict your script to POSIX features when possible so that it may
1180 use <tt>/bin/sh</tt> as its interpreter. If your script works with
1181 <prgn/ash/, it's probably POSIX compliant, but if you are in doubt,
1182 use <tt>/bin/bash</tt>.
1185 Perl scripts should check for errors when making any system calls,
1186 including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
1190 <prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages.
1191 See <em>Csh Programming Considered Harmful</>, one of the
1192 <tt/comp.unix.*/ FAQs. It can be found on <ftpsite>rtfm.mit.edu</> in
1193 <ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</>.
1194 If an upstream package comes with <prgn/csh/ scripts then you must
1195 make sure that they start with <tt>#!/bin/csh</tt> and make your
1196 package depend on the <prgn/c-shell/ virtual package.
1199 Any scripts which create files in world-writable directories (e.g., in
1200 <tt>/tmp</tt>) have to use a mechanism which will fail if a file with
1201 the same name already exists.
1204 The Debian base distribution provides the <prgn/tempfile/ and
1205 <prgn/mktemp/ utilities for use by scripts for this purpose.
1208 <sect1>Symbolic links
1211 In general, symbolic links within a toplevel directory should be
1212 relative, and symbolic links pointing from one toplevel directory into
1213 another should be absolute. (A toplevel directory is a sub-directory
1214 of the root directory `/'.)
1217 In addition, symbolic links should be specified as short as possible,
1218 i.e., link targets like `foo/../bar' are deprecated.
1221 Note that when creating a relative link using <prgn/ln/ it is not
1222 necessary for the target of the link to exist relative to the working
1223 directory you're running <prgn/ln/ from; nor is it necessary to change
1224 directory to the directory where the link is to be made. Simply
1225 include the string that should appear as the target of the link (this
1226 will be a pathname relative to the directory in which the link
1227 resides) as the first argument to <prgn/ln/.
1230 For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
1233 ln -fs gcc $(prefix)/bin/cc
1234 ln -fs gcc debian/tmp/usr/bin/cc
1235 ln -fs ../sbin/sendmail $(prefix)/bin/runq
1236 ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
1240 A symbolic link pointing to a compressed file should always have the
1241 same file extension as the referenced file. (For example, if a file
1242 `<tt>foo.gz</tt>' is referenced by a symbolic link, the filename of
1243 the link has to end with `<tt>.gz</tt>' too, as in `bar.gz.')
1249 No package may include device files in the package file tree.
1252 If a package needs any special device files that are not included in
1253 the base system, it has to call <prgn/makedev/ in the <tt/postinst/
1254 script, after asking the user for permission to do so.
1257 No package should remove any device files in the <tt/postrm/ or any
1258 other script. This is left to the system administrator.
1261 Debian uses the serial devices <tt>/dev/tty*</tt>. Programs using the
1262 old <tt>/dev/cu*</tt> devices should be changed to use
1266 <sect1>Configuration files
1269 Any configuration files created or used by your package should reside
1270 in <tt>/etc</tt>. If there are several you should consider creating a
1271 subdirectory named after your package.
1274 It is almost certain that any file in <tt>/etc</tt> that is in your
1275 package's filesystem archive should be listed in <prgn/dpkg/'s
1276 <tt/conffiles/ control area file. (See the <em>Debian Packaging
1280 Only packages that are tagged <em/conflicting/ with each other may
1281 specify the same file as <tt/conffile/. A package may not modify a
1282 configuration file of another package.
1285 If two or more packages use the same configuration file, one of these
1286 packages has to be defined as <em/owner/ of the configuration file,
1287 i.e., it has to list the file as <tt/conffile/ and has to provide
1288 a program that modifies the configuration file.
1291 The other packages have to depend on the <em/owner/ package and use
1292 that program to update the configuration file.
1295 Sometimes it's appropriate to build a new package, which just provides
1296 the basic <em/infrastructure/ for the other packages and which manages
1297 the shared configuration files. (Check out the <prgn/sgml-base/
1298 package as an example.)
1301 Files in <tt>/etc/skel</> will automatically be copied into new user
1302 accounts by <prgn/adduser/. They should not be referenced there by
1306 Therefore, if a program needs a dotfile to exist in advance in
1307 <tt/$HOME/ to work sensibly that dotfile should be installed in
1308 <tt>/etc/skel</> (and listed in conffiles, if it is not generated and
1309 modified dynamically by the package's installation scripts).
1312 However, programs that require dotfiles in order to operate sensibly
1313 (dotfiles that they do not create themselves automatically, that is)
1314 are a bad thing, and programs should be configured by the Debian
1315 default installation as close to normal as possible.
1318 Therefore, if a program in a Debian package needs to be configured in
1319 some way in order to operate sensibly that configuration should be
1320 done in a site-wide global configuration file elsewhere in
1321 <tt>/etc</>. Only if the program doesn't support a site-wide default
1322 configuration and the package maintainer doesn't have time to add it
1323 should a default per-user file be placed in <tt>/etc/skel</>.
1326 <tt>/etc/skel</> should be as empty as we can make it. This is
1327 particularly true because there is no easy mechanism for ensuring that
1328 the appropriate dotfiles are copied into the accounts of existing
1329 users when a package is installed.
1332 Ideally the sysadmin should not have to do any configuration other
1333 than that done (semi-)automatically by the <tt/postinst/ script.
1336 <sect1>Permissions and owners
1339 The rules in this section are guidelines for general use. If
1340 necessary you may deviate from the details below. However, if you do
1341 so you must make sure that what is done is secure and you must try to
1342 be as consistent as possible with the rest of the system. You should
1343 probably also discuss it on <prgn/debian-devel/ first.
1346 Files should be owned by <tt/root.root/, and made writable only by
1347 the owner and universally readable (and executable, if appropriate).
1350 Directories should be mode 755 or (for group-writability) mode 2775.
1351 The ownership of the directory should be consistent with its mode--if
1352 a directory is mode 2775, it should be owned by the group that needs
1356 Setuid and setgid executables should be mode 4755 or 2755
1357 respectively, and owned by the appropriate user or group. They should
1358 not be made unreadable (modes like 4711 or 2711 or even 4111); doing
1359 so achieves no extra security, because anyone can find the binary in
1360 the freely available Debian package--it is merely inconvenient. For
1361 the same reason you should not restrict read or execute permissions on
1362 non-set-id executables.
1365 Some setuid programs need to be restricted to particular sets of
1366 users, using file permissions. In this case they should be owned by
1367 the uid to which they are set-id, and by the group which should be
1368 allowed to execute them. They should have mode 4754; there is no
1369 point in making them unreadable to those users who must not be allowed
1373 Do not arrange that the system administrator can only reconfigure the
1374 package to correspond to their local security policy by changing the
1375 permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as
1376 opposed to conffiles and other similar objects) have their permissions
1377 reset to the distributed permissions when the package is reinstalled.
1378 Instead you should consider (for example) creating a group for people
1379 allowed to use the program(s) and making any setuid executables
1380 executable only by that group.
1383 If you need to create a new user or group for your package there are
1384 two possibilities. Firstly, you may need to make some files in the
1385 binary package be owned by this user or group, or you may need to
1386 compile the user or group id (rather than just the name) into the
1387 binary (though this latter should be avoided if possible). In this
1388 case you need a statically allocated id.
1391 You must ask for a user or group id from the base system maintainer,
1392 and must not release the package until you have been allocated one.
1393 Once you have been allocated one you must make the package depend on a
1394 version of the base system with the id present in <tt>/etc/passwd</tt>
1395 or <tt>/etc/group</tt>, or alternatively arrange for your package to
1396 create the user or group itself with the correct id (using
1397 <tt/adduser/) in its pre- or post-installation script (the latter is
1398 to be preferred if it is possible).
1401 On the other hand, the program may able to determine the uid or gid
1402 from the group name at runtime, so that a dynamic id can be used. In
1403 this case you must choose an appropriate user or group name,
1404 discussing this on <prgn/debian-devel/ and checking with the base
1405 system maintainer that it is unique and that they do not wish you to
1406 use a statically allocated id instead. When this has been checked you
1407 must arrange for your package to create the user or group if necessary
1408 using <prgn/adduser/ in the pre- or post-installation script (again,
1409 the latter is to be preferred if it is possible).
1412 Note that changing the numeric value of an id associated with a name
1413 is very difficult, and involves searching the filesystem for all
1414 appropriate files. You need to think carefully whether a static or
1415 dynamic id is required, since changing your mind later will cause
1419 <sect id="sysvinit">System run levels
1425 The <tt>/etc/init.d</> directory contains the scripts executed by
1426 <prgn/init/ at boot time and when init state (or `runlevel') is
1427 changed (see <manref name=init section=8>). <p>
1429 These scripts are being referenced by symbolic links in the
1430 <tt>/etc/rc<var/n/.d</> directories. When changing runlevels,
1431 <prgn/init/ looks in the directory <tt>/etc/rc<var/n/.d</> for the
1432 scripts it should execute, where <var/n/ is the runlevel that is being
1433 changed to, or `S' for the boot-up scripts. <p>
1435 The names of the links all have the form <tt/S<var/mm/<var/script// or
1436 <tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and
1437 <var/script/ is the name of the script (this should be the same as the
1438 name of the actual script in <tt>/etc/init.d</>.
1440 When <prgn/init/ changes runlevel first the targets of the links whose
1441 names starting with a <tt/K/ are executed, each with the single
1442 argument <tt/stop/, followed by the scripts prefixed with an <tt/S/,
1443 each with the single argument <tt/start/. The <tt/K/ links are
1444 responsible for killing services and the <tt/S/ link for starting
1445 services upon entering the runlevel.
1448 For example, if we are changing from runlevel 2 to runlevel 3, init
1449 will first execute all of the <tt/K/ prefixed scripts it finds in
1450 <tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The
1451 links starting with <tt/K/ will cause the referred-to file to be
1452 executed with an argument of <tt/stop/, and the <tt/S/ links with an
1453 argument of <tt/start/.
1456 The two-digit number <var/mm/ is used to decide which order to start
1457 and stop things in--low-numbered links have their scripts run first.
1458 For example, the <tt/K20/ scripts will be executed before the <tt/K30/
1459 scripts. This is used when a certain service must be started before
1460 another. For example, the name server <prgn/bind/ might need to be
1461 started before the news server <prgn/inn/ so that <prgn/inn/ can set
1462 up its access lists. In this case, the script that starts <prgn/bind/
1463 should have a lower number than the script that starts <prgn/inn/ so
1470 <sect1>Writing the scripts
1473 Packages can and should place scripts in <tt>/etc/init.d</> to start
1474 or stop services at boot time or during a change of runlevel. These
1475 scripts should be named <tt>/etc/init.d/<var/package/</>, and they
1476 should accept one argument, saying what to do:
1480 <item>start the service,
1483 <item>stop the service,
1486 <item>stop and restart the service,
1489 <item>cause the configuration of the service to be
1490 reloaded without actually stopping and restarting the service,
1492 <tag><tt/force-reload/
1493 <item>cause the configuration to be reloaded if the service supports
1494 this, otherwise restart the service.
1497 The <tt/start/, <tt/stop/, <tt/restart/, and <tt/force-reload/ options
1498 must be supported by all scripts in <tt>/etc/init.d</>, the
1499 <tt/reload/ option is optional.
1502 The <tt/init.d/ scripts should ensure that they will behave sensibly
1503 if invoked with <tt/start/ when the service is already running, or
1504 with <tt/stop/ when it isn't, and that they don't kill
1505 unfortunately-named user processes. The best way to achieve this is
1506 usually to use <prgn/start-stop-daemon/.
1509 If a service reloads its configuration automatically (as in the case
1510 of <prgn/cron/, for example), the <tt/reload/ option of the
1511 <tt/init.d/ script should behave as if the configuration has been
1512 reloaded successfully.
1515 These scripts should not fail obscurely when the configuration files
1516 remain but the package has been removed, as the default in <prgn/dpkg/
1517 is to leave configuration files on the system after the package has
1518 been removed. Only when it is executed with the <tt/--purge/ option
1519 will dpkg remove configuration files. Therefore, you should include a
1520 <tt/test/ statement at the top of the script, like this:
1522 test -f <var/program-executed-later-in-script/ || exit 0
1525 <sect1>Managing the links
1528 A program is provided, <prgn/update-rc.d/, to make it easier for
1529 package maintainers to arrange for the proper creation and removal of
1530 <tt>/etc/rc<var/n/.d</> symbolic links from their <tt/postinst/ and
1531 <tt/postrm/ scripts.
1534 You should use this script to make changes to <tt>/etc/rc<var/n/.d</>
1535 and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in
1539 By default <prgn/update-rc.d/ will start services in each of the
1540 multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
1541 runlevel (0), the single-user runlevel (1) and the reboot runlevel
1542 (6). The system administrator will have the opportunity to customize
1543 runlevels by simply adding, moving, or removing the symbolic links in
1544 <tt>/etc/rc<var/n/.d</>.
1547 To get the default behaviour for your package, put in your
1548 <tt/postinst/ script
1550 update-rc.d <var/package/ default >/dev/null
1552 and in your <tt/postrm/
1554 if [ purge = "$1" ]; then
1555 update-rc.d <var/package/ remove >/dev/null
1560 This will use a default sequence number of 20. If it does not matter
1561 when or in which order the script is run, use this default. If it
1562 does, then you should talk to the maintainer of the <prgn/sysvinit/
1563 package or post to <tt>debian-devel</>, and they will help you choose
1567 For more information about using <tt/update-rc.d/, please consult its
1568 manpage <manref name=update-rc.d section=8>.
1571 <sect1>Boot-time initialisation
1574 There is another directory, <tt>/etc/rc.boot</>, which contains
1575 scripts which are run once per machine boot. This facility is
1576 provided for initialisation of hardware devices, cleaning up of
1577 leftover files, and so forth.
1580 For example, the <prgn/kbd/ package provides a script here for
1581 initialising the keyboard layout and console font and mode.
1584 The files in <tt>/etc/rc.boot</> should <em/not/ be links into
1585 <tt>/etc/init.d</>--they should be the scripts themselves.
1588 <tt/rc.boot/ should <em/not/ be used for starting general-purpose
1589 daemons and similar activities. This should be done using the
1590 <tt/rc<var/n/.d/ scheme, above, so that the services can be started
1591 and stopped cleanly when the runlevel changes or the machine is to be
1592 shut down or rebooted.
1598 <em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
1599 the <tt/.deb/ filesystem archive! <em/This will cause problems!/
1600 You should create them with <prgn/update-rc.d/, as above.
1603 <em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
1604 <prgn/dpkg/'s conffiles list! <em/This will cause problems!/ <em/Do/,
1605 however, include the <tt>/etc/init.d</> scripts in conffiles. (This
1606 is important since we want to give the local system administrator the
1607 chance to adapt the scripts to the local system--e.g., to disable a
1608 service without deinstalling the package, or to specify some special
1609 command line options when starting a service--while making sure her
1610 changes aren't lost during the next package upgrade.) <p>
1615 The <prgn/bind/ DNS (nameserver) package wants to make sure that the
1616 nameserver is running in multiuser runlevels, and is properly shut
1617 down with the system. It puts a script in <tt>/etc/init.d</>, naming
1618 the script appropriately <tt/bind/. As you can see, the script
1619 interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/
1620 signal (causing it to reload its configuration); this way the user can
1621 say <tt>/etc/init.d/bind reload</> to reload the name server.
1627 # Original version by Robert Leslie <rob@mars.org>, edited by iwj and cs
1629 test -x /usr/sbin/named || exit 0
1633 echo -n "Starting domain name service: named"
1634 start-stop-daemon --start --quiet --exec /usr/sbin/named
1638 echo -n "Stopping domain name service: named"
1639 start-stop-daemon --stop --quiet \
1640 --pidfile /var/run/named.pid --exec /usr/sbin/named
1644 echo -n "Restarting domain name service: named"
1645 start-stop-daemon --stop --quiet \
1646 --pidfile /var/run/named.pid --exec /usr/sbin/named
1647 start-stop-daemon --start --verbose --exec /usr/sbin/named
1650 force-reload|reload)
1651 echo -n "Reloading configuration of domain name service: named"
1652 start-stop-daemon --stop --signal 1 --quiet \
1653 --pidfile /var/run/named.pid --exec /usr/sbin/named
1657 echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
1666 Another example on which to base your <tt>/etc/init.d</> scripts is in
1667 <tt>/etc/init.d/skeleton</>.
1670 If this package is happy with the default setup from
1671 <prgn/update-rc.d/, namely an ordering number of 20 and having named
1672 running in all runlevels, it can say in its <tt/postinst/:
1674 update-rc.d bind default >/dev/null
1676 And in its <tt/postrm/, to remove the links when the package is purged:
1678 if [ purge = "$1" ]; then
1679 update-rc.d acct remove >/dev/null
1687 Packages may not touch the configuration file <tt>/etc/crontab</>, nor
1688 may they modify the files in <tt>/var/spool/cron/crontabs</>.
1691 If a package wants to install a job that has to be executed via
1692 cron, it should place a file with the name if the package in one
1693 of the following directories:
1699 As these directory names say, the files within them are executed on
1700 a daily, weekly, or monthly basis, respectively.
1703 If a certain job has to be executed more frequently than `daily,' the
1704 package should install a file
1705 <tt>/etc/cron.d/<package-name></tt> tagged as configuration
1706 file. This file uses the same syntax as <tt>/etc/crontab</tt> and is
1707 processed by <prgn/cron/ automatically. (Note, that scripts in the
1708 <tt>/etc/cron.d</tt> directory are not handled by
1709 <prgn/anacron/. Thus, you should only use this directory for jobs
1710 which may be skipped if the system is not running.)
1713 All files installed in any of these directories have to be scripts
1714 (shell scripts, Perl scripts, etc.) so that they can easily be
1715 modified by the local system administrator. In addition, they have to
1716 be registered as configuration file.
1719 The scripts in these directories have to check, if all necessary
1720 programs are installed before they try to execute them. Otherwise,
1721 problems will arise when a package was removed (but not purged), since
1722 the configuration files are kept on the system in this situation.
1725 <sect>Console messages
1728 This section describes different formats for messages written to
1729 standard output by the <tt>/etc/init.d</> scripts. The intent is to
1730 improve the consistency of Debian's startup and shutdown look and
1734 Please look very careful at the details. We want to get the messages
1735 to look exactly the same way concerning spaces, punctuation, and case
1739 Here is a list of overall rules that you should use when you create output
1740 messages. They can be useful if you have a non-standard message that isn't
1741 covered in the sections below.
1746 Every message should cover one line, start with a capital letter and
1747 end with a period `.'.
1751 If you want to express that the computer is working on something
1752 (performing a specific task, not starting or stopping a program), we
1753 use an ``ellipsis'', namely three dots `...'. Note that we don't insert
1754 spaces in front of or behind the dots.
1755 If the task has been completed we write `done.' and a line feed.
1759 Design your messages as if the computer is telling you what he is
1760 doing (let him be polite :-) but don't mention ``him'' directly.
1761 For example, if you think of saying
1763 I'm starting network daemons: nfsd mountd.
1767 Starting network daemons: nfsd mountd.
1772 The following formats must be used
1777 when daemons get started.
1780 Use this format if your script starts one or more daemons.
1781 The output should look like this (a single line, no leading spaces):
1783 Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
1785 The <description> should describe the subsystem the daemon or set of
1786 daemons are part of, while <daemon-1> up to <daemon-n>
1787 denote each daemon's name (typically the file name of the program).
1790 For example, the output of /etc/init.d/lpd would look like:
1792 Starting printer spooler: lpd.
1796 This can be achieved by saying
1798 echo -n "Starting printer spooler: lpd"
1799 start-stop-daemon --start --quiet lpd
1802 in the script. If you have more than one daemon to start, you should
1805 echo -n "Starting remote filesystem services:"
1806 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
1807 echo -n " mountd"; start-stop-daemon --start --quiet mountd
1808 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
1811 This makes it possible for the user to see what takes so long and when
1812 the final daemon has been started. Please be careful where to put spaces:
1813 In the example above the system administrator can easily comment out
1814 a line if he don't wants to start a specific daemon, while the displayed
1815 message still looks good.
1819 when something needs to be configured.
1822 If you have to set up different parameters of the system upon boot up,
1823 you can use this format:
1825 Setting <parameter> to `<value>'.
1829 You can use the following echo statement to get the quotes right:
1831 echo "Setting DNS domainname to \`"value"'."
1835 Note that the left quotation mark (`) is different from the right (').
1838 when a daemon is stopped.
1841 When you stop a daemon you should issue a message similar to the startup
1842 message, except that `Starting' is replaced with `Stopping'.
1845 So stopping the printer daemon will like like this:
1847 Stopping printer spooler: lpd.
1851 when something is executed.
1854 There a several examples where you have to run a program at system
1855 startup or shutdown to perform a specific task. For example, setting
1856 the system's clock via `netdate' or killing all processes when the
1857 system comes down. Your message should like this:
1859 Doing something very useful...done.
1861 You should print the `done.' right after the job has been completed,
1862 so that the user gets informed why he has to wait. You can get this
1865 echo -n "Doing something very useful..."
1872 when the configuration is reloaded.
1875 When a daemon is forced to reload its configuration files you
1876 should use the following format:
1878 Reloading <daemon's-name> configuration...done.
1882 when none of the above rules apply.
1885 If you have to print a message that doesn't fit into the styles described
1886 above, you can use something appropriate, but please have a look at the
1887 overall rules listed above.
1894 The Debian <tt/menu/ packages provides a unique interface between
1895 packages providing applications and documents, and <em/menu programs/
1896 (either X window managers or text-based menu programs as
1900 All packages that provide applications that need not be passed any
1901 special command line arguments for normal operation should register a
1902 menu entry for those applications, so that users of the <tt/menu/
1903 package will automatically get menu entries in their window managers,
1904 as well in shells like <tt/pdmenu/.
1907 Please refer to the <em>Debian Menu System</em> document that comes
1908 with the <tt/menu/ package for information about how to register your
1909 applications and web documents.
1912 <sect>Keyboard configuration
1915 To achieve a consistent keyboard configuration (i.e., all applications
1916 interpret a keyboard event the same way) all programs in the Debian
1917 distribution have to be configured to comply with the following
1921 Here is a list that contains certain keys and their interpretation:
1925 <item>delete the character to the left of the cursor
1928 <item>delete the character to the right of the cursor
1931 <item>emacs: the help prefix
1934 The interpretation of any keyboard events should be independent of the
1935 terminal that's used (either the console, X windows, rlogin/telnet
1939 The following list explains how the different programs should be set
1944 <item>`<tt><--</tt>' generates KB_Backspace in X.
1946 <item>`<tt/Delete/' generates KB_Delete in X.
1948 <item>X translations are set up to make KB_Backspace generate ASCII DEL,
1949 and to make KB_Delete generate <tt>ESC [ 3 ~</tt> (this is the vt220 escape
1950 code for the `delete character' key). This must be done by loading
1951 the resources using xrdb on all local X displays, not using the
1952 application defaults, so that the translation resources used
1953 correspond to the xmodmap settings.
1955 <item>The Linux console is configured to make `<tt><--</tt>' generate DEL, and
1956 `Delete' generate <tt>ESC [ 3 ~</tt> (this is the case at the moment).
1958 <item>X applications are configured so that Backspace deletes left, and
1959 Delete deletes right. Motif applications already work like this.
1961 <item>stty erase <tt>^?</tt> .
1963 <item>The `xterm' terminfo entry should have <tt>ESC [ 3 ~</tt> for kdch1, just
1964 like TERM=linux and TERM=vt220.
1966 <item>Emacs is programmed to map KB_Backspace or the `stty erase'
1967 character to delete-backward-char, and KB_Delete or kdch1 to
1968 delete-forward-char, and <tt>^H</tt> to help as always.
1970 <item>Other applications use the `stty erase' character and kdch1 for the
1971 two delete keys, with ASCII DEL being `delete previous character'
1972 and kdch1 being `delete character under cursor'.
1976 This will solve the problem except for:
1980 <item>Some terminals have a <tt><--</tt> key that cannot be made to produce
1981 anything except <tt>^H</tt>. On these terminals Emacs help will be
1982 unavailable on <tt>^H</tt> (assuming that the `stty erase' character takes
1983 precedence in Emacs, and has been set correctly). M-x help or F1
1984 (if available) can be used instead.
1986 <item>Some operating systems use <tt>^H</tt> for stty erase. However, modern
1987 telnet versions and all rlogin versions propagate stty settings,
1988 and almost all UNIX versions honour stty erase. Where the stty
1989 settings are not propagated correctly things can be made to work by
1990 using stty manually.
1992 <item>Some systems (including previous Debian versions) use xmodmap to
1993 arrange for both <tt><--</tt> and Delete to generate KB_Delete). We can
1994 change the behaviour of their X clients via the same X resources
1995 that we use to do it for our own, or have our clients be configured
1996 via their resources when things are the other way around. On
1997 displays configured like this Delete will not work, but <tt><--</tt> will.
1999 <item>Some operating systems have different kdch1 settings in their
2000 terminfo for xterm and others. On these systems the Delete key
2001 will not work correctly when you log in from a system conforming to
2002 our policy, but <tt><--</tt> will.
2006 <sect>Environment variables
2009 No program may depend on environment variables to get reasonable
2010 defaults. (That's because these environment variables would have to
2011 be set in a system-wide configuration file like /etc/profile, which is
2012 not supported by all shells.)
2015 If a program should depend on environment variables for its
2016 configuration, the program has to be changed to fall back to a
2017 reasonable default configuration if these environment variables are
2018 not present. If this cannot be done easily (e.g., if the source code
2019 of a non-free program is not available), the program should be
2020 replaced by a small `wrapper' shell script which sets the environment
2021 variables and calls the original program.
2024 Here is an example of a wrapper script for this purpose:
2030 exec /usr/lib/foo/foo "$@"
2034 Furthermore, as <tt>/etc/profile</tt> is a configuration file of the
2035 <prgn/bash/ package, no other package may put any environment
2036 variables or other commands into that file.
2041 <chapt>Customized programs
2044 <sect id="arch-spec">Architecture specification strings
2047 If a program needs to specify an <em>architecture specification
2048 string</> in some place, the following format has to be used:
2052 where `<arch>' is one of the following: i386, alpha, arm, m68k,
2056 Note, that we don't want to use `<arch>-debian-linux' to apply
2057 to the rule `architecture-vendor-os' since this would make our
2058 programs incompatible to other Linux distributions. Also note, that we
2059 don't use `<arch>-unknown-linux', since the `unknown' does not
2066 The configuration files <tt>/etc/services</tt>,
2067 <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed by the
2068 <prgn/netbase/ package and may not be modified by other packages.
2071 If a package requires a new entry in one of these files, the
2072 maintainer has to get in contact with the <prgn/netbase/ maintainer,
2073 who will add the entries and release a new version of the
2074 <prgn/netbase/ package.
2077 The configuration file <tt>/etc/inetd.conf</tt> may be modified by the
2078 package's scripts only via the <prgn/update-inetd/ script or the
2079 <prgn/DebianNet.pm/ Perl module.
2082 If a package wants to install an example entry into
2083 <tt>/etc/inetd.conf</tt>, the entry has to be preceded with exactly
2084 one hash character (#). Such lines are treated as `commented out by
2085 user' by the <prgn/update-inetd/ script and are not changed or
2086 activated during a package updates.
2089 <sect>Editors and pagers
2092 Some programs have the ability to launch an editor or pager
2093 program to edit or display a text document. Since there are
2094 lots of different editors and pagers available in the Debian
2095 distribution, the system administrator and each user should have
2096 the possibility to choose his/her preferred editor and pager.
2099 In addition, every program should choose a good default
2100 editor/pager if none is selected by the user or system
2104 Thus, every program that launches an editor or pager has to use the
2105 EDITOR or PAGER environment variables to determine the editor/pager
2106 the user wants to get started. If these variables are not set, the
2107 programs `/usr/bin/editor' and `/usr/bin/pager' have to be used,
2111 These two files are managed through `alternatives.' That is,
2112 every package providing an editor or pager has to call the
2113 `update-alternatives' script to register these programs.
2116 If it is very hard to adapt a program to make us of the EDITOR
2117 and PAGER variable, that program should be configured to use
2118 `/usr/bin/sensible-editor' and `/usr/bin/sensible-pager' as
2119 editor or pager program, respectively. These are two scripts
2120 provided in the Debian base system that check the EDITOR and
2121 PAGER variables and launches the appropriate program or
2122 falls back to `/usr/bin/editor' and `/usr/bin/pager',
2126 Since the Debian base system already provides an editor and
2127 a pager program, there is no need for a package to depend on
2128 `editor' and `pager', nor is it necessary for a package to
2129 provide such virtual packages.
2132 <sect id="web-appl">Web servers and applications
2135 This section describes the locations and URLs that have to be used by
2136 all web servers and web application in the Debian system.
2140 <item>Cgi-bin executable files are installed in the directory
2142 /usr/lib/cgi-bin/<cgi-bin-name>
2144 and can be referred to as
2146 http://localhost/cgi-bin/<cgi-bin-name>
2150 <item>Access to html documents
2153 Html documents for a package are stored in /usr/doc/<package> and can be
2156 http://localhost/doc/<package>/<filename>
2160 <item>Web Document Root
2163 Web Applications should try to avoid storing files in the Web Document Root.
2164 Instead use the /usr/doc/<package> directory for documents and
2165 register the Web Application via the menu package. If access to the
2166 web-root is unavoidable then use
2170 as the Document Root. This might be just a symbolic link to the location where the
2171 sysadmin has put the real document root.
2177 <sect>Mail transport agents
2180 Debian packages which process electronic mail, whether
2181 mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
2182 make sure that they are compatible with the configuration decisions
2183 below. Failure to do this may result in lost mail, broken <tt/From:/
2184 lines, and other serious brain damage!
2187 The mail spool is <tt>/var/spool/mail</> and the interface to send a
2188 mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND). The
2189 mail spool is part of the base system and not part of the MTA package.
2192 All Debian MUAs and MTAs have to use the <tt>maillock</tt> and
2193 <tt>mailunlock</tt> functions provided by the <tt>liblockfile</tt>
2194 packages to lock and unlock mail boxes. These functions implement
2195 a NFS-safe locking mechanism. (It is ok if MUAs and MTAs don't link
2196 against liblockfile but use a <em/compatible/ mechanism. Please
2197 compare the mechanisms very carefully!)
2200 Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
2201 chosen otherwise. A MUA may remove a mailbox (unless it has
2202 nonstandard permissions) in which case the MTA or another MUA must
2203 recreate it if needed. Mailboxes must be writable by group mail.
2206 The mail spool is 2775 <tt/mail.mail/, and MUAs need to be setgid
2207 mail to do the locking mentioned above (and obviously need to avoid
2208 accessing other users' mailboxes using this privilege).
2211 <tt>/etc/aliases</> is the source file for the system mail aliases
2212 (e.g., postmaster, usenet, etc.)--it is the one which the sysadmin
2213 and <tt/postinst/ scripts may edit. After <tt>/etc/aliases</> is edited
2214 the program or human editing it must call <prgn/newaliases/. All MTA
2215 packages should come with a <prgn/newaliases/ program, even if it does
2216 nothing, but older MTA packages do not do this so programs should not
2217 fail if <prgn/newaliases/ cannot be found.
2220 The convention of writing <tt/forward to <var/address// in the mailbox
2221 itself is not supported. Use a <tt/.forward/ file instead.
2224 The location for the <prgn/rmail/ program used by UUCP for incoming
2225 mail is <tt>/usr/sbin/rmail</>, as per the FSSTND. Likewise,
2226 <prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
2227 <tt>/usr/sbin/rsmtp</> if it is supported.
2230 If you need to know what name to use (for example) on outgoing news
2231 and mail messages which are generated locally, you should use the file
2232 <tt>/etc/mailname</>. It will contain the portion after the username
2233 and <tt/@/ (at) sign for email addresses of users on the machine
2234 (followed by a newline).
2237 A package should check for the existence of this file. If it exists
2238 it should use it without comment. (An MTA's prompting
2239 configuration script may wish to prompt the user even if it finds this
2240 file exists.) If it does not exist it should prompt the user
2241 for the value and store it in <tt>/etc/mailname</> as well as using it
2242 in the package's configuration. The prompt should make it clear that
2243 the name will not just be used by that package. For example, in this
2244 situation the INN package says:
2246 Please enter the `mail name' of your system. This is the hostname
2247 portion of the address to be shown on outgoing news and mail messages.
2248 The default is <var/syshostname/, your system's host name.
2249 Mail name [`<var/syshostname/']:
2251 where <var/syshostname/ is the output of <tt/hostname --fqdn/.
2254 <sect>News system configuration
2257 All the configuration files related to the NNTP (news) servers and
2258 clients should be located under <tt>/etc/news</tt>.
2261 There are some configuration issues that apply to a number of
2262 news clients and server packages on the machine. These are:
2265 <tag>/etc/news/organization
2266 <item>A string which shall appear as the
2267 organization header for all messages posted
2268 by NNTP clients on the machine
2270 <tag>/etc/news/server
2271 <item>Contains the FQDN of the upstream NNTP
2272 server, or localhost if the local machine is
2276 Other global files may be added as required for cross-package news
2280 <sect>Programs for the X Windows system
2283 Some programs can be configured with or without support for X Windows.
2284 Typically these binaries produced when configured for X will need the
2285 X shared libraries to run.
2288 Such programs should be configured <em/with/ X support, and should
2289 declare a dependency on <tt/xlib6g/ (for the X11R6 libraries).
2290 Users who wish to use the program can install just the relatively
2291 small <tt/xlib6g/ package, and do not need to install the whole of X.
2294 Do not create two versions (one with X support and one without) of
2298 <em>Application defaults</em> files have to be installed in the
2299 directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
2300 considered as part of the program code. Thus, they should not be
2301 modified and should not be tagged as <em>conffile</em>. If the local
2302 system administrator wants to customise X applications globally, the
2303 file <tt>/etc/X11/Xresources</tt> should be used.
2306 If you package a program that requires a non-free Motif library, it
2307 would be good if you can provide a "foo-smotif" and a "foo-dmotif"
2308 package, containing a (against Motif libraries) statically and a
2309 dynamically linked version, respectively. This way, users without
2310 Motif can use the package too, while users that have Motif installed
2311 get the advantages of a dynamically linked version.
2314 However, if your package works reliably with lesstif, you should
2315 package it with lesstif, and not with Motif at all.
2318 Note, that packages that require non-free Motif libraries can't go
2319 into the main section. If your package is free otherwise, it should go
2320 into contrib. Otherwise it has to go into non-free.
2323 <sect>Emacs lisp programs
2326 Please refer to the `Debian Emacs Policy' (documented in
2327 <tt>debian-emacs-policy.gz</tt> of the <prgn/emacsen-common/ package)
2328 for details of how to package emacs lisp programs.
2334 The permissions on /var/lib/games are 755 <tt/root.root/.
2337 Each game decides on its own security policy.
2340 Games which require protected, privileged access to high-score files,
2341 savegames, etc., must be made set-<em/group/-id (mode 2755) and
2342 owned by <tt/root.games/, and use files and directories with
2343 appropriate permissions (770 <tt/root.games/, for example). They must
2344 <em/not/ be made set-<em/user/-id, as this causes security
2345 problems. (If an attacker can subvert any set-user-id game
2346 they can overwrite the executable of any other, causing other players
2347 of these games to run a Trojan horse program. With a set-group-id
2348 game the attacker only gets access to less important game data, and if
2349 they can get at the other players' accounts at all it will take
2350 considerably more effort.)
2353 Some packages, for example some fortune cookie programs, are
2354 configured by the upstream authors to install with their data files or
2355 other static information made unreadable so that they can only be
2356 accessed through set-id programs provided. Do not do this in a Debian
2357 package: anyone can download the <tt/.deb/ file and read the data from
2358 it, so there is no point making the files unreadable. Not making the
2359 files unreadable also means that you don't have to make so many
2360 programs set-id, which reduces the risk of a security hole.
2363 As described in the FSSTND, binaries of games should be installed in
2364 the directory <tt>/usr/games</tt>. This also applies to games that use
2365 the X windows system. Manual pages for games (X and non-X games) should
2366 be installed in <tt>/usr/man/man6</tt>.
2369 <chapt>Documentation
2375 You must install manual pages in <prgn/nroff/ source form, in appropriate
2376 places under <tt>/usr/man</tt>. You should only use sections 1 to 9
2377 (see the FSSTND for more details). You must <em/not/ install a
2378 preformatted `cat page'.
2381 If no manual page is available for a particular program, utility or
2382 function and this is reported as a bug on debian-bugs, a symbolic link
2383 from the requested manual page to the <manref name=undocumented
2384 section=7> manual page should be provided. This symbolic link can be
2385 created from <tt>debian/rules</> like this:
2387 ln -s ../man7/undocumented.7.gz \
2388 debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
2390 This manpage claims that the lack of a manpage has been reported as a
2391 bug, so you may only do this if it really has (you can report it
2392 yourself, if you like). Do not close the bug report until a proper
2393 manpage is available.
2396 You may forward a complaint about a missing manpage to the upstream
2397 authors, and mark the bug as forwarded in the Debian bug tracking
2398 system. Even though the GNU Project do not in general consider the
2399 lack of a manpage to be a bug, we do--if they tell you that they
2400 don't consider it a bug you should leave the bug in our bug tracking
2404 Manual pages should be installed compressed using <tt/gzip -9/.
2407 If one manpage needs to be accessible via several names it is better
2408 to use a symbolic link than the <tt/.so/ feature, but there is no need
2409 to fiddle with the relevant parts of the upstream source to change
2410 from <tt/.so/ to symlinks--don't do it unless it's easy. Do not
2411 create hard links in the manual page directories, and do not put
2412 absolute filenames in <tt/.so/ directives. The filename in a <tt/.so/
2413 in a manpage should be relative to the base of the manpage tree
2414 (usually <tt>/usr/man</tt>).
2417 <sect>Info documents
2420 Info documents should be installed in <tt>/usr/info</tt>. They should
2421 be compressed with <tt/gzip -9/.
2424 Your package must call <prgn/install-info/ to update the Info <tt/dir/
2425 file, in its post-installation script:
2427 install-info --quiet --section Development Development \
2428 /usr/info/foobar.info
2432 It is a good idea to specify a section for the location of your
2433 program; this is done with the <tt/--section/ switch. To determine
2434 which section to use, you should look at <tt>/usr/info/dir</> on your
2435 system and choose the most relevant (or create a new section if none
2436 of the current sections are relevant). Note that the <tt/--section/
2437 flag takes two arguments; the first is a regular expression to match
2438 (case-insensitively) against an existing section, the second is used
2439 when creating a new one.
2442 You must remove the entries in the pre-removal script:
2444 install-info --quiet --remove /usr/info/foobar.info
2448 If <prgn/install-info/ cannot find a description entry in the Info
2449 file you will have to supply one. See <manref name=install-info
2450 section=8> for details.
2453 <sect>Additional documentation
2456 Any additional documentation that comes with the package can be
2457 installed at the discretion of the package maintainer. Text
2458 documentation should be installed in a directory
2459 <tt>/usr/doc/<var/package/</tt>, where <var/package/ is the
2460 name of the package, and compressed with <tt/gzip -9/
2464 If a package comes with large amounts of documentation which many
2465 users of the package will not require you should create a separate
2466 binary package to contain it, so that it does not take up disk space
2467 on the machines of users who do not need or want it installed.
2470 It is often a good idea to put text information files (<tt/README/s,
2471 changelogs, and so forth) that come with the source package in
2472 <tt>/usr/doc/<var/package/</> in the binary package. However, you don't
2473 need to install the instructions for building and installing the package, of
2477 <sect>Preferred documentation formats
2480 The unification of Debian documentation is being carried out via HTML.
2483 If your package comes with extensive documentation in a markup format
2484 that can be converted to various other formats you should if possible
2485 ship HTML versions in the binary package, in the directory
2486 <tt>/usr/doc/<var/package/</> or its subdirectories.
2489 Other formats such as PostScript may be provided at your option.
2495 Log files should usually be named <tt>/var/log/<var/package/.log</tt>.
2496 If you have many log files, or need a separate directory for
2497 permissions reasons (<tt>/var/log</tt> is writable only by
2498 <tt/root/), you should usually create a directory named
2499 <tt>/var/log/<var/package/</tt>.
2502 Make sure that any log files are rotated occasionally so that they
2503 don't grow indefinitely; the best way to do this is to use
2504 <prgn/savelog/ program in an <tt>/etc/cron.daily</>,
2505 <tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script. Here is a good
2508 [ -d /var/log/apache/. ] || exit 0
2511 if [ -fs access.log ]
2513 savelog -c 7 access.log > /dev/null
2518 Make sure that any log files are removed when the package is purged
2519 (but not when it is only removed), by checking the argument to the
2520 <tt/postrm/ script (see the <em>Debian Packaging Manual</em> for
2524 <sect id="copyrightfile">Copyright information
2527 Every package must be accompanied by a verbatim copy of its copyright
2528 and distribution license in the file
2529 /usr/doc/<package-name>/copyright. This file must neither be
2530 compressed nor be a symbolic link.
2533 In addition, the copyright file must say where the upstream sources
2534 (if any) were obtained, and explain briefly what modifications were
2535 made in the Debian version of the package compared to the upstream
2536 one. It must name the original authors of the package and the Debian
2537 maintainer(s) who were involved with its creation.
2540 /usr/doc/<package-name> may be a symbolic link to a directory in
2541 /usr/doc only if two packages both come from the same source and the
2542 first package has a "Depends" relationship on the second. These rules
2543 are important because copyrights must be extractable by mechanical
2547 Packages distributed under the UCB BSD license, the Artistic license,
2548 the GNU GPL, and the GNU LGPL should refer to the files
2549 /usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
2550 /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.
2553 Do not use the copyright file as a general <tt/README/ file. If your
2554 package has such a file it should be installed in
2555 <tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
2556 other appropriate place.
2562 Any examples (configurations, source files, whatever), should be
2563 installed in a directory <tt>/usr/doc/<var/package//examples</tt>.
2564 These files should not be referenced by any program--they're there
2565 for the benefit of the system administrator and users, as
2569 <sect id="instchangelog">Changelog files
2572 This installed file must contain a copy of the <tt>debian/changelog</>
2573 file from your Debian source tree, and a copy of the upstream
2574 changelog file if there is one. They should usually be installed in
2575 <tt>/usr/doc/<var/package/</> as <tt/changelog.Debian.gz/ and
2576 <tt/changelog.gz/ respectively.
2579 Both should be installed compressed using <tt/gzip -9/, as they will
2580 become large with time even if they start out small.
2583 If the package has only one changelog which is used both as the Debian
2584 changelog and the upstream one because there is no separate upstream
2585 maintainer then that changelog should usually be installed as
2586 <tt>/usr/doc/<var/package//changelog.gz</>; if there is a separate
2587 upstream maintainer, but no upstream changelog, then the Debian
2588 changelog should still be called <tt/changelog.Debian.gz/.