dpkg/doc/guidelines.texi

\input texinfo @c -*-texinfo-*-
@setfilename guidelines.info

@set DATE 26th January 1996

@setchapternewpage off

@iftex
@center @titlefont{Debian Linux Packaging Guidelines}
@tex
\vskip2pt \hrule height 2pt width \hsize \vskip2pt
@end tex
@sp 0.5
@center @value{DATE}
@end iftex

@ifinfo
@format
START-INFO-DIR-ENTRY
* Guidelines: (guidelines).       How to make Debian packages.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@node Top, Additional Information, (dir), (dir)

@ifinfo
@top Debian Linux Packaging Guidelines
@end ifinfo

   This file documents the steps that must be taken in the preparation
of a Debian Linux package.  All submissions to be included in the
distribution proper and all packages to be considered for @file{contrib}
or @file{non-free} availability @emph{must} conform to the guidelines
and standards described in this document or they cannot be included or
made available at the archive with the distribution.

   Please read the Guidelines carefully.  If you have comments or
questions, please contact @code{debian-devel@@pixar.com}.  If you are
planning on going further than just contributing a package (i.e., if
you plan to maintain it for an extended period of time or if you are
generally interested in becoming more involved in the Project), you
should join the @code{debian-devel} mailing list.  For more details,
read @file{info/mailing-lists.txt}, available at any Debian Linux
archive.

   (This file was last updated on @value{DATE}.  Please check the most
recent @file{dpkg} package at any Debian Linux archive for a
potentially more up to date copy.)

@menu
* Additional Information::      Where other info is to be found.
* Package Copyright::           A few words about the importance of
                                understanding the package copyright.
* Package Content::             Requirements for the package content.
* Source Package::              Creating the source package.
* Binary Package::              Creating the binary package.
* Control Files::               The binary package control files.
* Appendix::                    More specific details about some aspects.
@end menu



@node Additional Information, Package Copyright, Top, Top
@unnumbered Additional Information

   These Guidelines are intended to be fairly general.  More specific
information is available about certain aspects of building packages,
such as how to use the features of Init under Debian Linux and how
to interact with some more technical details of dpkg's operation.  This
information can be found in the directory @file{doc/package-developer}
at any Debian Linux archive.  At the time of this writing, the
following documents are available:

@table @file
@item virtual-package-names-list.text
The list of virtual package names currently in use, together with the
procedure for getting new virtual package names allocated.
@item auto-deconfiguration.txt
How dpkg can sometimes automatically deconfigure packages in order to
do bulk installations smoothly.
@item dpkg-essential-flag.txt
How to tell dpkg a package is essential and should not be removed.
(This is for the use of base system packages only.)
@item dpkg-disappear-replace.txt
What happens when a package appears to have been completely replaced.
@end table

   In the future, we hope also to make available:

@table @file
@item copyright.txt
How to choose a good copyright notice to attach to new programs.
@item version-ordering.txt
The algorithm with which packages' version numbers are compared.
@end table

   Also, you should download the sample files and the sample package
(GNU Hello) available in @file{standards/samples}.  You may use any
of this material as a starting point for new packages.  The following
sample files, incidentally, are available:

@itemize @bullet
@item debian.README
@item debian.control
@item debian.postinst
@item debian.postrm
@item debian.rules
@end itemize

Some more detailed information about certain topics is available in the
appendix to this document (@pxref{Appendix}).


@node Package Copyright, Package Content, Additional Information, Top
@unnumbered Package Copyright

   Please study the copyright of your submission @emph{carefully}
and @emph{understand it} before proceeding!  If you have doubts or
questions, please ask!

   In order to understand how we classify and distribute certain
packages, it is important to understand the distinction between being
freely available and being freely redistributable.

   Being @dfn{freely available}, quite simply, means that the software
can be made available freely, at least for non-commercial purposes and
in its original, unmodified form.  This includes packages made available
freely that have restrictions on non-commercial use, redistribution of
modifications, etc.  Being freely available, therefore, has nothing to
do with being able to modify and redistribute the software.  It only
means that you can get a copy of the software without having to pay
(and it does not necessarily mean that you can @emph{use} the software
without having to pay---shareware is an example of freely available
software).

   @dfn{freely redistributable}, while generally being freely available,
goes beyond just being freely available.  Freely redistributable means
that that the software, in addition to being able to be made available
freely, must be able to be freely modified and redistributed without
restriction.

   All submissions to be included in the distribution proper @emph{must}
be freely redistributable.

   In addition to the distribution, the Project maintains two separate
archives of software packages with the distribution: the @file{contrib}
archive and the @file{non-free} archive.

   @file{contrib} is an archive of user-contributed packages that are
not maintained by the Project, packages that were once maintained by the
Project but that are no longer actively maintained, and packages that
are maintained by the Project but that are not yet considered ready for
inclusion in the distribution proper (i.e., ALPHA and BETA packages).
As above, all submissions for inclusion in the @file{contrib} archive
@emph{must} be freely redistributable.

   @file{non-free} is an archive of packages with either restrictive or
unclear terms of copying or modification.  If a package has @emph{any}
restrictions on modification or redistribution, it can not be included
in the distribution or @file{contrib} archive.  It can only be included
in the @file{non-free} archive, and then only if it is freely available.

   In summary, in order to be included in the distribution proper or the
@file{contrib} archive, a package must be @emph{freely redistributable}.
Anyone must be able to make copies of it, modify it, redistribute it with
their modifications in place, include it on a CD-ROM, or generally sell
it.  To be included in the @file{non-free} archive, a package may have
restrictions, as long as the package remains @emph{freely available}.  We
must be available to make it available freely at the archive, and anyone
must be able to make copies of it and use it for at least non-commercial,
personal purposes.  Software that will typically be included in
@file{non-free} are software that does not allow commercial distribution,
software that does not allow modification or redistribution of
modifications, commercial ``demos'', and ``shareware''.

   When in doubt, send mail to @file{debian-devel@@lists.debian.org}.
Be prepared to provide us with the copyright statement.  Software
covered by the GPL, public domain software and BSD-like copyrights are
safe; be wary of the phrases ``commercial use prohibited'' and
``distribution restricted''.

   Every package submission @emph{must} be accompanied by verbatim copy
of its copyright (with the exceptions of public domain packages and
those covered by the UCB BSD licence or the GNU GPL or LGPL; in these
cases simply indicate which is appropriate).  This information must be
included in a file installed to the directory @file{/usr/doc/copyright}.
See below for details.



@node Package Content, Source Package, Package Copyright, Top
@unnumbered Package Content

   The following requirements apply equally to both the binary and
source packages.  In either case, when files have been installed,
they must conform to the requirements described in this section.

   The primary rule in Debian Linux is to follow the Linux @dfn{File
System Standard} (@dfn{FSSTND}).  The location of installed files
@emph{must} comply @emph{fully} with the FSSTND.  The latest version of
this document can be found alongside the Guidelines or at
@file{tsx-11.mit.edu} in @file{/pub/linux/docs/linux-standards/fsstnd}.
Specific questions about following the standard should be addressed to
Daniel Quinlan, the FSSTND coordinator, at @code{quinlan@@yggdrasil.com}.

   In addition to the FSSTND, all Debian Linux packages must follow
the guidelines below.

@itemize @bullet
@item
Directories should be mode 755 or (for group-writability) mode 2775,
with the exception of special ``system'' directories that need to be
another mode.  The ownership of the directory should be consistent with
its mode---if a directory is mode 2775, it should be owned by the group
that needs write access to it, of course.  Use common sense in assigning
permissions and ownerships to directories, and make sure that what is
done is secure if it is ``non-standard''.

@item
Normal binaries should be mode 755 and owned by @code{root.root}.  If
there is a good reason to use a different mode or ownership, you may do
so, but you must try to be as consistent as possible with the rest of
the system.  If you need to use a different mode or ownership, please
discuss it with @code{imurdock@@debian.org}.

@item
Setuid binaries should normally be mode 4755 (not 4711!) and, of course,
owned by the appropriate user.

@item
Setgid binaries should normally be mode 2755 (not 2711!) and, of course,
owned by the appropriate group.

@item
Library files should generally be mode 644 and owned by
@code{root.root}; shared libraries should be mode 755.  If the package
requires different permissions or ownerships to function correctly, they
should be used instead.

@item
Manual pages should be mode 644 and owned by @code{root.root}.  The
@file{nroff} source must be installed.  You should @emph{not} install a
preformatted ``cat page'', and you should only use sections 1 to 9---see
the FSSTND for more details.  If no manual page is available for a
particular program, utility or function and this is reported as a bug on
debian-bugs, a symbolic link from the requested manual page to the
@file{undocumented}(7) manual page should be provided. This symbolic
link can be created from @file{debian.rules} like this:

@smallexample
ln -s ../man7/undocumented.7 debian-tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
@end smallexample

Do not close the bug report until a proper manpage is available.  You
may forward the complaint to the upstream maintainers, and mark the bug
as forwarded in the Debian bug tracking system.  The GNU Project do not
in general consider the lack of a manpage to be a bug, but we do - if
they tell you to go away leave the bug open anyway.

@item
Info documents should be mode 644, owned by @code{root.root}, and
compressed with @file{gzip -9} when installed.  The package must call
@file{install-info} to update the Info @file{dir} file.  This should
be done in the post-installation script (@file{postinst}), like this:

@smallexample
install-info --quiet /usr/info/foobar.info
@end smallexample

The entries should be removed by the pre-removal script (@file{prerm}),
like this:

@smallexample
install-info --quiet --remove /usr/info/foobar.info
@end smallexample

It is also a good idea to specify a section for the Info @file{dir}
entry.  This is done with the @file{--section} switch.  To determine
which section to use, you should use look at @file{/usr/info/dir} on
your system and choose the most relevant (or create a new section if
none of the current sections are relevant).

If @file{install-info} cannot find a description entry in the Info file
you will have to supply one.  See @file{install-info}(8) for details.

@item
If a package contains any shared libraries you will have to invoke
@file{ldconfig} in both the @file{postinst} and @file{prerm} scripts
to correctly update the library links.  See @file{ldconfig}(8) for
details.

@item
Any additional documentation that comes with the package can be
installed at the discretion of the package maintainer.  Text
documentation should be mode 644, owned by @code{root.root}, installed
to @file{/usr/doc}, and compressed with @file{gzip -9} unless it is small.

If a subdirectory of @file{/usr/doc} is warranted, please do create one.
Please do not install DVI, PostScript, or large textual documentation in
the same package; upload such documentation as a separate package
(installing its files in @file{/usr/doc}) so that it can be made
available with the distribution.  If a user has the need for the
documentation, they can easily get it from the archive, CD-ROM, etc.,
but it should not take up disk space on the machines of the user who do
not need or want it installed.

@item
Create a file named @file{/usr/doc/copyright/<@i{package}>} which gives
details of the authorship and copyright of the package.  If the package
is distributed under the GNU General Public Licence, the GNU Library
General Public Licence or the Regents of the University of California at
Berkeley (BSD) licence, please say so instead of including a copy of the
licence.  The files @file{BSD}, @file{GPL}, and @file{LGPL} will be
available in the @file{/usr/doc/copyright} directory for you to refer
to.  @file{/usr/doc/copyright/<@i{package}>} should not be compressed.

@emph{All} authorship and copyright information from the original source
package must be included in the @file{/usr/doc/copyright/<@i{package}>}
file.

@item
Any example files (for example, sample configuration files) should
be placed in the directory @file{/usr/doc/examples}.  If the file is
normally a hidden file, such as @file{.emacs}, then please call it
@file{dot.emacs}, to avoid confusion.  Again, you may create a
subdirectory if it is needed.

@item
All symbolic links should be relative, not absolute.  Absolute links,
in general, cause problems when a file system is not mounted where it
``normally'' resides (for example, when mounted via NFS).  In certain
cases, however, relative links may also cause similar problems.  I
have generally made links into @file{/etc} and @file{/var} absolute
and all other links relative.  There may be other cases in which
absolute links are necessary.

Therefore, in the @file{Makefile} or @file{debian.rules}, do not do:
@smallexample
install: all
         [...]
         ln -fs /usr/bin/gcc /usr/bin/cc
         [...]
@end smallexample
Instead, do:
@smallexample
ln -fs gcc /usr/bin/cc
@end smallexample
or
@smallexample
( cd /usr/bin ; ln -fs gcc cc )
@end smallexample

Please do not create hard links in the manual page directories.  In
these cases, you should use relative symbolic links or files that
@file{.so} (roff for `source') others instead.

@item
All command scripts should have a @code{#!} line naming the shell to be
used to interpret them.

@item
In the case of Perl scripts this should be @code{#!/usr/bin/perl} or
sometimes @code{#!/bin/perl}, as follows: if the script is a critical
one that may be called when the @file{/usr} partition is unmounted or
broken it should use @file{/bin/perl}.  Otherwise (especially if the
script is not specifically targetted at Debian) it should use Perl's
standard location, @file{/usr/bin/perl}.

@item
Generally the following compilation parameters should be used:

@display
   CC = gcc
   CFLAGS = -O2 -g -Wall # sane warning options vary between programs
   LDFLAGS = # none (or -N, if appropriate; see below)
   install -s (or strip)
@end display

Note that all installed binaries should be stripped, either by using the
@code{-s} flag to @file{install}, or by calling @file{strip} on the
binaries after they have been copied into the @file{debian-tmp} but
before the tree is made into a package.

Make sure that you do not link with @code{-g}, as this makes a.out
compilers produce huge statically linked binaries.  The @code{-g} flag
is useful on compilation so that you have available a full set of
debugging symbols in your built source tree, in case anyone should file
a bug report involving (for example) a core dump.

@code{-N} should only be used on binaries that are very small (less than
8K with the @code{-N} option, roughly) and are not likely to have
multiple instances in memory.  Do not use @code{-N} on daemons, no
matter how small they are.

It is up to the package maintainer to decide what compilation options
are best for the package.  Certain binaries (such as
computationally-intensive programs) may function better with certain
flags (@code{-O3}, for example); feel free to use them.  Please use good
judgment here.  Don't add flags for the sake of adding flags; only add
flags if there is good reason to do so.

@item
Please make sure that you use only released versions of shared libraries
to build your packages; otherwise other users will not be able to run
your binaries properly.  Producing source packages that depend on
unreleased compilers is also usually a bad idea.

@item
Logfiles should usually be named @file{/var/log/<package>}, or
@file{/var/log/<package>.<something>} if you have several logfiles.  It
may be appropriate to create a directory.  Make sure that any logfiles
are rotated occasionally so that they don't grow indefinitely; the best
way to do this is to use @file{savelog} from the cron package in an
@file{/etc/cron.daily}, @file{/etc/cron.weekly} or
@file{/etc/cron.monthly} script.


@item
Please check with the base system maintainer (Ian Murdock) before using
users or groups other than @code{root} and others specified in this
document.
@end itemize



@node Source Package, Binary Package, Package Content, Top
@unnumbered Source Package

   The source package should contain a file called @file{debian.rules}
which contains at least the following targets, to be invoked in the top
level directory:

@smallexample
build
binary
clean
@end smallexample

@file{debian.rules} should start with

@smallexample
#!/usr/bin/make -f
@end smallexample

@noindent and be executable.  It is a good idea to arrange for it not
to fail obscurely when invoked in the wrong directory, for example by
testing for the existence of a file in the source directory.

@itemize @bullet
@item
The @file{build} target should perform all non-interactive configuration
and compilation of the package.  If a package has an interactive
pre-build configuration routine, the source package should be built
@emph{after} this has taken place.

   For some packages, notably ones where the same source tree is
compiled in different ways to produce two binary packages, the
@file{build} target does not make much sense.  For these packages it is
good enough to provide two (or more) targets (@file{build-a} and
@file{build-b} or whatever) for each of the ways of building the
package, and a @file{build} target that does nothing.  The @file{binary}
target will have to build the package in each of the possible ways and
make the binary package out of each.

@item
The @file{binary} target of @file{debian.rules} should be all that is
necessary for the user to build the binary package.  The binary package
should be created using @file{dpkg} and placed in the parent of the top
level directory.  The next section describes how to construct binary
packages from the @file{binary} target.

@item
The @file{clean} target should undo the effects of the @file{build}
target and the @file{binary} target, except that it should leave alone
any @file{../<@i{package}>-<@i{version}>.deb} file created by a run of
@file{binary}.

@item
Additional targets may exist in @file{debian.rules}.  We recommend using
@file{source} and @file{diff} targets to build the Debianised source
package and the Debianisation context diff, respectively.  These files
should be placed in @file{../foo-<@i{version}>.tar.gz} and
@file{../foo-<@i{version}>.diff.gz}.  The @file{install} target, for
installing into a running system direct from the Debianised source
tree, is no longer required.  The sample @file{debian.rules} provides
@file{source} and @file{diff} targets that should work with little or
no alteration, providing that the package-specific variables at the top
of the script have been properly defined.

@item
If you need to edit a @file{Makefile} where @file{configure} scripts
are used, you should edit the @file{.in} files rather than editing
the @file{Makefile} directly.  This allows the user to reconfigure
the package if necessary.  You should @emph{not} configure the package
and edit the generated @file{Makefile}!  This makes it impossible for
someone else to later reconfigure the package.

@item
Please document your changes to the source package so that future
package maintainers know what has been changed.  To do this, include
a description of your changes in the @file{debian.README} (which, as
described above, should already contain authorship and copyright
information!) and include relevant information such as your name,
electronic mail address, date, etc.  The @file{debian.README} file
should also document any `unusual' packages which must be installed for
this one to compile.

@item
If changes to the source code are made that are applicable to Linux
systems or systems in general please try to get them included in the
upstream version of the package by supplying the upstream authors with
the changes in whatever form they prefer.

If changes to the source code are made, please use a @file{define}.  If
they are changes required to compile or function under Linux in general,
use @file{LINUX}.  If it is a cosmetic or functional change, use
@file{DEBIAN}.

@item
Create the source package using @file{tar}, and use @file{gzip -9} to
compress it.  Source packages should be named in the form
<@i{package}>-<@i{version}>.tar.gz---for example,
@file{fileutils-3.9-3.tar.gz}.

NB, here @code{<@i{version}>} is the full Debian version number, in the
form @code{<@i{original_version}>-<@i{debian_revision}>} (see below),
but the tarfile should unpack into a directory named
@code{<@i{package}>-<@i{original_version}>} (again, see the section
below on version numbering).

@item
Create the unified context diff against the original package using
@file{diff -uNr}, and use @file{gzip -9} to compress it.  Diffs should
be named in the form <@i{package}>-<@i{version}>.diff.gz---for example,
@file{fileutils-3.9-3.diff.gz}.
@end itemize

   Please note that the package and patch filenames do @emph{not} need
to fit in MS-DOS 8+3.  They will be made available under an alternative
8+3 name in the archive by the archive maintainer, using a symlink.



@node Binary Package, Control Files, Source Package, Top
@unnumbered Binary Package

   The @file{binary} target of the source package @file{debian.rules}
file should do the following (see the sample @file{debian.rules}
for an implementation that you are free to modify and use in your own
packages, of course):

@itemize @bullet
@item
Create an empty directory in the top-level directory of the source
package (deleting it first, if necessary), and install the files
belonging to this package in that directory.  For example, the directory
could be called @file{debian-tmp} and would probably contain directories
@file{debian-tmp/usr/bin}, @file{debian-tmp/usr/lib}, etc.
(@file{debian-tmp} is the name traditionally used, and it is used in
the sample @file{debian.rules} file, so we will use that name in the
Guidelines.)

@item
Make sure that all the files under @file{debian-tmp} have the correct
ownerships and permissions (@pxref{Package Content}, for more information
about file locations, ownerships, and permissions.)

@item
Create a subdirectory of @file{debian-tmp} called @file{DEBIAN}.  This
directory contains the package control information, including at the
very least the master information file named @file{control}.  The next
section describes the semantics and syntax of the files required and
allowed here.

@item
Run @file{dpkg} to create the binary package, using something like

@smallexample
dpkg --build debian-tmp
@end smallexample

This will create a file called @file{debian-tmp.deb}, from the
@file{debian-tmp} directory.  You should rename this file to
@file{../<@i{package}>-<@i{version}>.deb} after it is built.

After the @file{binary} target has done all this, the
@file{<@i{package}>-<@i{version}>.deb} file in the parent directory is
the binary distribution.  This file may be distributed and installed on
any Debian Linux system with @file{dpkg} in the same manner and
using the same methods as all packages are installed to the system.

@item
If a single source package corresponds to several binary packages, there
should usually be a @file{debian.rules} file with a single @file{binary}
target that builds all the binary packages involved and move all packages
to the parent directory of that containing the source package.

In this case, you should choose binary package names which are meant to
make clear the close relationship between the binary packages and which
source package the binary packages came from (for example, the
@file{texinfo} source package build two binary packages: @file{texidoc}
and @file{texinfo}).  You should place the appropriate binary package
name in the @file{Package} field of the control file (not the source
package name), and you should consider whether the other binary packages
that come from the same source tree should be mentioned in the
@file{Depends}, @file{Recommends} or @file{Suggests} fields.  You
should put the source package name in the @file{Source} field.

You should retain the source package version numbering in the
@file{Version} field, if possible---the version number should be the
same for the Debianised source tree and all the binary packages
generated from it.  It is more important, though, that the version
numbers sort correctly.  See below for details of version numbers.
@end itemize



@node Control Files, Appendix, Binary Package, Top
@unnumbered Control Files

   Each binary package contains, in addition to the files that comprise
the actual package, a set of text files that control how @file{dpkg}
installs, configures, upgrades, removes, etc. the package.  These files
are called @dfn{control files}.  When creating the package, the control
files should placed in a directory called @file{DEBIAN}, as described
earlier (@pxref{Binary Package}, for further information).

The control information files are:

@table @code
@item control
The master package control information file.
@item conffiles
A list of package configuration files.
@item preinst
The package pre-installation script.
@item postinst
The package post-installation script.
@item prerm
The package pre-removal script.
@item postrm
The package post-removal script.
@end table

   Of these, only @file{control} is required.  The various installation
scripts, and the configuration files list, will only be used if they are
present.

@menu
* control::
* conffiles::
* Installation and Removal Scripts::
* Dependencies and Conflicts::
* Package Classification Fields::
@end menu

@node control, conffiles, Control Files, Control Files
@unnumberedsec control

   The @file{control} file contains a number of fields.  Each field
begins with a field name, such as @file{Package} or @file{Version}
(case insensitive), followed by a colon and optionally some spaces or
tabs (a single space is conventional).  Then comes the body of the
field, which may be several lines long; each continuation line must
start with at least one space or tab.  (These are the same rules as
apply to RFC822 mail headers.)  Blank lines are not permitted in the
control file.

   The required fields in the control file are the following:

@table @code
@item Package
The name of the package.
@item Description
The description of the package.  How to write an extended and more
usefull description field can be found in @pxref{How to write the Description control file field}.
@item Maintainer
The name and e-mail address of the maintainer of the package.
@item Version
The version number in the format
@code{<@i{original_version}>-<@i{debian_revision}>}.
@end table

   Each field has a particular format and meaning for the package
installation tools.

The value of @file{Package} should be the name of the package.  Package
names must start with an alphanumeric, must be at least two characters,
and may contain only alphanumerics and the characters - + . (that is,
hyphen, plus, stop) @footnote{The characters @@ : = % _ (at, colon,
equals, percent and underscore) used to be legal and are still accepted
when found in a package file, but may not be used in new packages}.
They are sort of case sensitive - please try to get the case right first
time.

   The @code{Maintainer} field should be in the form

@smallexample
Joe J. Bloggs <jbloggs@@foo.com>
@end smallexample

@noindent Note that this will not be useable as an email address if
the name given contains full stop characters, because of a silly
restriction in the Internet mail standards.  If you want to use this
as an email address in a program you should check for full stops and
change the string to the form @code{jbloggs@@foo.com (Joe J. Bloggs)}
if you find any.

   The @code{Version} field should be the version number of the
package.  For most packages which are not written specifically for
Debian, this should be in the form

@smallexample
Version: <@i{original_version}>-<@i{debian_revision}>
@end smallexample

@noindent where @file{<@i{original_version}>} is the original package
version number in whatever form the original package uses and
@file{<@i{debian_revision}>} indicates which ``debianisation'' this is
(this should usually be a plain number or perhaps a two numbers
separated by a full stop, and should be incremented each time the
package is changed or updated).

    Packages which are written specifically for Debian do not have a
@i{debian_revision}, and their version number should simply be
@i{version} (which should not contain any hyphens, to avoid
confusion).

    There is an ordering imposed on version numbers, described in
@file{version-ordering.txt}.  This ordering is designed to `do the right
thing' in most circumstances; if your package has an version number in
an unusual format you may need to reformat it somewhat to get the
ordering right.  This is important because @file{dpkg} is (for example)
reluctant to downgrade packages.

   The optional fields in the control file are the following:

@table @code
@item Depends
The names of prerequisite packages.
@item Recommends
The names of related, recommended packages.
@item Suggests
The names of related, optional packages.
@item Conflicts
The names of packages which conflict with this package.
@item Provides
The names of virtual packages which this package provides.
@item Priority
The `priority' of the package, as shown and used by @file{dselect}.
@item Section
The `section' of the package, as shown and used by @file{dselect}, and
used as a location for the package in the distribution.
@item Essential
A boolean field used by the base packages.
@item Pre-Depends
Used by base packages to ensure that (for example) shared libraries are
present before they are upgraded.  This feature is for expert use only.
@item Source
Gives the name of the source package when several binary packages are
generated from a single source tree.
@end table

@noindent See below for details of the semantics and syntax of these
fields.  Most packages will need at least a @code{Depends} field.

   An example of a @file{control} file would be:

@smallexample
Package: smail
Version: 3.1.29.1-13
Maintainer: Ian Jackson <iwj10@@cus.cam.ac.uk>
Recommends: pine | mailx | elm | emacs | mail-user-agent
Suggests: metamail
Depends: cron, libc5
Conflicts: sendmail
Provides: mail-transport-agent
Description: Electronic mail transport system.
 Smail is the recommended mail transport agent (MTA) for Debian.
 .
 An MTA is the innards of the mail system - it takes messages from
 user-friendly mailer programs and arranges for them to be delivered
 locally or passed on to other systems as required.
 .
 In order to make use of it you must have one or more user level
 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
 and VM as mailreaders) installed.  If you wish to send messages other
 than just to other users of your system you must also have appropriate
 networking support, in the form of IP or UUCP.
@end smallexample

   In this case, @file{mail-user-agent} is a virtual package
representing any user mailer program; the actual package names
@file{pine} is quoted for the reasons described in
@file{dependency-ordering.txt}, and the others because older versions
of those packages do not have the appropriate @file{Provides} field.

@node conffiles, Installation and Removal Scripts, control, Control Files
@unnumberedsec conffiles

   The contents of @file{conffiles} is simply a list of configuration
files in the package.  When installing the package, @file{dpkg} uses
an intelligent method to update these files.  This will ensure that
package-specific configuration files are not overwritten when a package
is upgraded, unless the user wishes the installation tools to do so.

   Typically, files listed in conffiles are package-specific
configuration files, which (according to the Linux Filesystem Standard)
are stored in @file{/etc}.  For example, the @code{sendmail} package may
contain the file @file{/etc/sendmail.cf}, which we do not wish to
overwrite automatically when the user upgrades the sendmail package.
Only those files listed in @file{DEBIAN/conffiles} will be updated
intelligently when a package is upgraded; all other files in the package
will be overwritten by the upgrade process.

   Configuration files which will be functional as shipped and will
probably need little or no local editing should simply be listed the
@file{conffiles} file; in this case you need read no further.

   For packages whose configuration files will need modification on
most systems there are two sensible approaches.  Which one is chosen
depends on how hard the configuration problem is and how much time the
package maintainer has available.

   One option is for you to ship a minimal `best-effort' file in
@file{/etc}, and list the file in @file{conffiles}.  This will mean that
the user will have to go and edit the file themselves to get the package
to work properly, of course.  The next time they upgrade the package, if
you haven't changed the file version, their old file will be left in
place.  If you have modified your version then the user will get a
prompt asking them which version of the file they want, theirs or yours.
They will then usually have to resolve the discrepancies manually.

   The other option is to be preferred, if you can do it: do not put a
copy of the configuration file in the package at all.  Instead, you
check in the postinst whether the file exists, and if it doesn't you
prompt the user for the information you need to create a good one.  This
is obviously harder work.

  You also have to remember that you will have to keep up with your
package's changes: if you discover a bug in the program which generates
the configuration file, or if the format of the file changes from one
version to the next, you will have to arrange for the postinst script to
do something sensible---usually this will mean editing the installed
configuration file to remove the problem or change the syntax.  You will
have to do this very carefully, since the user may have changed the
file, perhaps to fix the very problem that your script is trying to deal
with---you will have to detect these situations and deal with them
correctly.

  If you do go down this route it's probably a good idea to make the
program that generates the configuration file(s) a separate program in
@file{/usr/sbin}, by convention called @i{package}@code{config}, and
then run that if appropriate from the post-installation script.  The
@i{package}@code{config} program should not unquestioningly overwrite an
existing configuration---if its mode of operation is geared towards
setting up a package for the first time (rather than any arbitrary
reconfiguration later) you should have it check whether the
configuration already exists, and require a @code{--force} flag to
overwrite it.

   @file{conffiles} should almost certainly list all the files contained
in your package in the @file{/etc} directory.  There may also be other
files somewhere that the user is expected to edit, which should also be
included.  Note, however, that the FSSTND specifies that configuration
files must be in @file{/etc}.  No Debian package should contain
configuration files in @file{/usr/etc}, and all programs should refer to
configuration files in @file{/etc}.

@noindent For example, the TCP/IP package might use a conffiles which contains

@smallexample
/etc/init.d/netbase
/etc/gateways
/etc/protocols
/etc/services
/etc/hosts.allow
/etc/hosts.deny
/etc/rpc
@end smallexample

@noindent and so on; the files

@smallexample
/etc/hosts
/etc/inetd.conf
/etc/host.conf
/etc/networks
/etc/resolv.conf
@end smallexample

@noindent might be generated by an interactive configuration program,
and would then not be included in the package or listed in the
@file{conffiles}.

@node Installation and Removal Scripts, Dependencies and Conflicts, conffiles, Control Files
@unnumberedsec Installation and Removal Scripts

   The scripts @file{preinst}, @file{postinst}, @file{prerm}, and
@file{postrm} are optional (Bash or Perl) scripts.  As the names
would indicate, if these scripts exist, they will be executed before
installing the package, after installation, before package removal,
and after removal, respectively.

   They are given arguments which indicate the precise situation and
action being performed---see
@pxref{Maintainer script arguments and how dpkg does things} for
details of exactly when each of the scripts is invoked and what its
arguments are.  Extra arguments and situations may be added later, so
you should not test the number of arguments to your script to determine
the situation, and you should choose the sense of your `if it is this
then do this otherwise do that' tests carefully.

   These scripts can be used to perform any site-specific package
configuration.

   Because the scripts will be exectued by the dpkg front-end, it is
guaranteed that the scripts will be executed interactively.  User input
from the scripts should be read from standard input, not the user's
terminal.  Similarly, output should be sent to standard output.

   If your maintainer scripts need to prompt for passwords and/or do
@i{full-screen} interaction should do these things to and from
@file{/dev/tty}, since @file{dpkg} will at some point redirect scripts'
standard input and output so that it can log the installation process.
Likewise, because these scripts may be executed with standard output
redirected into a pipe for logging purposes, Perl scripts should set
unbuffered output by setting @code{$|=1} so that the output is printed
immediately rather than being buffered.

   The scripts must be idempotent, and they must clean up after
themselves properly.  Ie, they must do the right thing if run multiple
times, even if previous runs failed halfway through.  This is so that if
any errors occur, or if the @file{dpkg} run is interrupted, the user can
recover by rerunning @file{dpkg}, and/or by upgrading to a new version
and then rerunning the failed operation.

   These scripts should avoid producing output which it is unnecessary
for the user to see and should rely on @file{dpkg} to stave off boredom
on the part of a user installing many packages.  This means, amongst
other things, using the @file{--quiet} option on @file{install-info}.

   Packages should try to minimise the amount of prompting they need to
do, and they should ensure that the user will only every be asked each
question once.  This means that packages should try to use appropriate
shared configuration files (such as @file{/etc/papersize} and
@file{/etc/news/server}), rather than each prompting for their own list
of required pieces of information.

   It also means that an upgrade should not ask the same questions
again, unless the user has used @code{dpkg --purge} to remove the
package's configuration.  The answers to configuration questions should
be stored in an appropriate place in @file{/etc} so that the user can
modify them, and how this has been done should be documented.

   If a package has a vitally important piece of information to pass to
the user (such as "don't run me as I am, you must edit the following
configuration files first or you risk your system emitting
badly-formatted messages"), it should display this in the
@file{postinst} script and prompt the user to hit Return to acknowledge
the message.  Copyright messages do not count as vitally important (they
belong in @file{/usr/doc/copyright}; neither do instructions on how to
use a program (these should be in on line documentation, where all the
users can see them).

   They should return a zero exit status for success, or a nonzero one
for failure.  Note that if a script is a @code{#!/bin/sh} script it
should probably start with @code{set -e}, to avoid continuing after
errors---see @file{bash}(1) for details.  Perl scripts should check for
errors when making calls such as @code{open}, @code{print},
@code{close}, @code{rename} and @code{system}.

   If these scripts exist they should be left in the @file{DEBIAN}
directory with execute permission enabled and should contain an
appropriate @code{#!} line, such as @code{#!/bin/bash} for a
@code{bash} script or @code{#!/bin/perl} for a Perl script (see
above).

@node Dependencies and Conflicts, Package Classification Fields, Installation and Removal Scripts, Control Files
@unnumberedsec Conflicts, Depends, Suggests, Recommends and Provides

   The @file{Depends} field lists packages that are required for this
package to provide a significant amount of functionality.  The package
maintenance software will not allow a package to be installed without
also installing packages listed in its @code{Depends} field, and will
run the @code{postinst} scripts of packages listed in @code{Depends}
fields before those of the packages which depend on them, and run the
@code{prerm} scripts before.

   Packages containing dynamically-linked executable binaries (this
includes almost all C programs) should include a @file{Depends} field
which mentions the shared C library required for the program to run.
For a.out binaries linked against @file{libc.so.4} the relevant package
name is @file{libc} (for the a.out stable 0.93 tree) or @file{libc4}
(for the unstable development 1.1 tree); for ELF binaries linked against
@file{libc.so.5} the relevant package name is @file{libc5}.

   The @code{Recommends} field lists packages that would be found
together with this one in all but unusual installations.  The user-level
package maintenance program @file{dselect} will warn the user if they
select a package without those listed in its @code{Recommends} field.
Note that @code{Recommends} fields do not currently have any implications
for the order in which the maintainer scripts are run.

   The @code{Suggests} field lists packages that are related to this one
and can perhaps enhance its usefulness, but without which installing
this package is perfectly reasonable.  The package maintenance software
will not moan at the user for not selecting @code{Suggests} related
packages, but may use the information in the @code{Suggests} field to
assist the user during package selection.

   The syntax of @code{Depends}, @code{Recommends} and @code{Suggests}
is a list of groups of alternative packages.  Each group is a list of
packages separated by vertical bar (or `pipe') symbols, @code{|}.  The
groups are separated by commas.  Each package is a package name
optionally followed by a version number specification in parentheses.  A
version number may start with a @code{>=}, in which case that version or
any later will match, or @code{<=} for that version or any earlier
version. A version number starting with a @code{>>} or @code{<<} will
respectively match any later or earlier version. If a version number or
a version number starting with @code{=} is specified an exact match is
required. Commas are to be read as `AND', and pipes as `OR', with pipes
binding more tightly.

   Versions of dpkg before 1.0.9 used @code{<} and @code{>} for
@code{<=} and @code{>=} (these are still supported for backward
compatibility), and did not support @code{<<} and @code{>>}.

   The @code{Conflicts} field lists packages that conflict with this
one, for example by containing files with the same names (an example
would be Smail vs. Sendmail).  The package maintenance software will not
allow conflicting packages to be installed.  Two conflicting packages
should each include a @code{Conflicts} line mentioning the other.

   The syntax of @code{Conflicts} is a list of package names (with
optional version numbers), separated by commas (and optional
whitespace).  In the @code{Conflicts} field the comma should be read as
`OR'.

   The @code{Provides} field lists the names of any `virtual packages'
of which this packages is to be considered an instantiation.  Virtual
packages are used to allow packages to refer to a service they require
(such as the availability of @file{/usr/sbin/sendmail}) without having
to know the names of all the relevant packages.  The virtual package
names defined in @code{Provides} fields may be used in other packages'
@code{Depends}, @code{Recommends}, @code{Suggests} and @code{Conflicts}
fields.  For more information about how to use virtual packages and
which virtual package names to use read @pxref{Virtual dependencies} and
@file{doc/package-developer/virtual-package-names-list.text}.

   The syntax of @code{Provides} is a list of package names separated by
commas (and optional whitespace).

@node Package Classification Fields,  , Dependencies and Conflicts, Control Files
@unnumberedsec Priority, Section and Essential

   The @code{Priority} and @code{Section} fields are used by
@file{dselect} when displaying the list of packages to the user.  There
is no need to put them into a package, since these are usually set by
the distribution maintainers in the @file{Packages} file.

   However, if a user installs a package which is not part of the
standard distribution, or without downloading and updating from a new
@file{Packages} file, the information about the priority and section of
a package will be absent, and the @file{dselect} package listing will
have the package listed under `unclassified'.  It is permissible for a
package to include @code{Section} or @code{Priority} fields to improve
this; however, if you do this you should make sure you keep the
information up to date so that users are not shown conflicting
information.  The @code{Section} field can also be used by the
distribution maintainers as a suggestion about which section you think
is most appropriate for your package.

  The values for the @code{Section} and @code{Priority} fields should be
determined by the distribution maintainers; if you don't know what to
put in them just leave them out.  You can add them later, if you like,
but remember that you'll then have to reissue your package if the
distribution maintainers change the classification of your package.

  The @code{Essential} field should only appear in packages in the
installation's base system.  If it is set to @code{yes} then @file{dpkg}
will not remove the package even if asked to, and will make certain
minor modifications to its installation procedures.  The only other
legal value is @code{no}, which is equivalent to the absence of the
field.

@appendix
@node Appendix,  , Control Files, Top
@unnumbered Appendix
@comment  node-name,  next,  previous,  up
@menu
* configuration files -- /etc/skel vs /usr/doc/examples::
* How to write the Description control file field::
* Configuration of init::
* Maintainer script arguments and how dpkg does things::
* Mail processing packages::
* Virtual dependencies::
@end menu

@node configuration files -- /etc/skel vs /usr/doc/examples, How to write the Description control file field, Appendix, Appendix
@comment  node-name,  next,  previous,  up
@unnumberedsec configuration files -- /etc/skel vs /usr/doc/examples

There seems to be a certain amount of confusion about @file{/etc/skel}
and @file{/usr/doc/examples}. The most important thing to remember is
the following:

Files in @file{/etc/skel} will @emph{automatically} be copied into
@emph{new} user accounts by @file{adduser}.  They should not
be referenced there by any program. Files in @file{/usr/doc/examples}
should not be installed automatically.

Therefore, if the program in question need a dotfile to exist in advance
in @file{$HOME} to work @emph{sensibly} that dotfile should be installed
in @file{/etc/skel} (and listed in conffiles; @pxref{conffiles}).

However, programs that require dotfiles in order to operate sensibly
(dotfiles that they do not create themselves automatically, that is) are
a bad thing, and that programs should be configured by the Debian
default installation as close to normal as possible.

Therefore, if a program in a Debian package needs to be configured in
some way in order to operate sensibly that configuration should be done
in a site-wide global configuration file elsewhere in @file{/etc} (and
that file should be listed in conffiles).  Only if the program doesn't
support a site-wide default configuration should a default per-user file
be placed in @file{/etc/skel} (and listed in conffiles;
@pxref{conffiles}).

The idea is as follows:

The sysadmin should ideally not have to do any configuration other than
that done @w{(semi-)}automatically by the postinst script.

However, if they wish to change their configuration themselves
(because the configuration they want is beyond the scope of the
autoconfiguration, or because the autoconfiguration doesn't exist yet,
or because they just want to do it themselves for any reason) then
@file{/usr/doc/examples} exists as @emph{documentation} for their benefit.

The only time these files should be read are by the sysadmin using their
favourite editor or pager, or @emph{perhaps} (in very complex packages)
by the postinst as a template to build on or modify.

@file{/etc/skel} is part of the @emph{implementation} of this
configuration.  It contains the files that are copied into new user
accounts.  It should probably be as empty as we can make it.

Examples:
@table @code
@item .profile
@file{/etc/skel} should not contain a @file{.profile} file.  Anything
that needs to be done there should be done in @file{/etc/profile}.
Anything that should not go in @file{/etc/profile} (users can't avoid
running @file{/etc/profile}) probably should not be in the default
configuration.  bash has generally good default behaviour.

@item .bash_logout
Likewise, bash functions perfectly happily without a
@file{.bash_logout}, so none should be provided, since anything in it is
a deviation from the sensible default behaviour.

@item .xsession
@file{/etc/skel} should not contain a @file{.xsession}.  @file{xdm}'s
system-wide startup file @file{/usr/lib/X11/xdm/Xsession} supports a
system-wide default user configuration (which should probably be
@file{/etc/X11/Xsession} or some such) which may be overridden by
@file{.xsession} in the user's home directory.  Therefore there is no
need for a @file{.xsession} to be installed by default and none should
be provided.

Instead, a sensible @file{/etc/X11/Xsession} should be provided, and if
desired this can be used as a template by users who wish to install
their own configuration, or alternatively a more comprehensive example
with much commented-out interesting stuff could be put in
@file{/usr/doc/examples}.

If the sysadmin wishes to change the system-wide default they should
probably do this by editing @file{/etc/X11/Xsession} rather than
creating the file in @file{/etc/skel}, because the former will affect
all user accounts that haven't explicitly overridden things by creating
their own file while the latter will only affect new accounts.

All the configuration necessary for a program to function should be
provided.  Therefore sysadmins will not need to go through
@file{/usr/doc/examples} while editing configuration files in
@file{/etc} except in extreme cases (like INN) where the configuration
was too difficult to do automatically.

@item site-wide defaults
Site-wide defaults should not go in @file{/etc/skel}.  In the case of
twm, for example, the system-wide default should be in
@file{/etc/X11/system.twmrc}.  (The default location for this in X11R5,
btw, is in @file{/usr/lib/X11} somewhere, but we can't put it on
@file{/usr} because of CDROM distributions, etc - hence the FSSTND's
mandate to put configuration files in @file{/etc}.)

@item .twmrc
There should be no @file{.twmrc} file in @file{/etc/skel}.  You can have
one in @file{/usr/doc/examples} if you @emph{like}, but why bother if
@file{system.twmrc} is a good example (and indeed is the one the user is
using before they create their own)?

@item m4
@file{/usr/doc/examples} isn't mainly for example @emph{configuration
files}.  It's for any kind of example file distributed with a package.
For example, GNU m4 comes with a whole pile of example m4 macro scripts,
which is exactly what @file{/usr/doc/examples} is for.
@end table

Summary

Files that should be installed in new user accounts should be in
@file{/etc/skel}, as that will ensure that they @emph{are} installed in
new user accounts!  However, we should try to avoid the need for this.

@file{/usr/doc/examples} is just what it says: documentation in the form
of examples.  If a sysadmin is required to go and read these files for
their system to work they should be told about it.  For example, here
is what the Smail postinst script says right at the start:

@smallexample
I can do certain kinds of automatic configuration of your
mail system, by asking you a number of questions.  Later you
may to confirm and/or correct your answers.  In any case,
comprehensive information on configuring Smail is in
smail(5) and in /usr/doc/examples/smail and
/usr/doc/smail-admin-guide.
@end smallexample

@node How to write the Description control file field, Configuration of init, configuration files -- /etc/skel vs /usr/doc/examples, Appendix
@unnumberedsec How to write the Description control file field

The format of the @code{Description} field is as follows:

@smallexample
Description: <single line synopsis>
 <extended description over several lines>
@end smallexample

The extended description has several kinds of line:

@itemize @bullet
@item
Those starting with a single space are part of a paragraph.  Successive
lines of this form will be word-wrapped when displayed.  The leading
space will usually be stripped off.

@item
Those starting with two or more spaces.  These will be displayed
verbatim.  If the display cannot be panned horizontally the displaying
program will linewrap them `hard' (ie, without taking account of word
breaks).  If it can they will be allowed to trail off to the right.
None, one or two initial spaces may be deleted, but the number of spaces
deleted from each line will be the same (so that you can have indenting
work correctly, for example).

@item
Those containing a single space followed by a single full stop
character.  These are rendered as blank lines.  This is the @emph{only}
way to get a blank line - see below.

@item
Those containing a space, a full stop and some more characters.  These
are for future expansion.  @emph{Do not} use them.
@end itemize

IMPORTANT and not so important TIPS:

@itemize @bullet
@item
@emph{Always} start extended description lines with at least @emph{one}
whitespace character.  Fields in the control file and in the Packages
file are separated by field names starting in the first column, just as
in RFC822.  Forgetting the whitespace will cause @file{dpkg-deb}
(>=0.93.23) to produce a syntax error when trying to build the package.
If you force it to build anyway @file{dpkg} will refuse to install the
resulting mess.

@item
@emph{Do not} include any completely @emph{empty} lines. These separate
different records in the Packages file, and are forbidden in control
files.  See the previous paragraph for what happens if you get this
wrong.

@item
The single line synopsis should be kept brief - certainly under 80
characters.  @file{dselect} displays the @emph{first 49} characters if
you're using an 80-column terminal.

@item
Do not include the package name in the synopsis line.  The display
software knows how to display this already, and you do not need to
state it.  Remember that in many situations the user may only see the
synopsis line - make it as informative as you can.

@item
The extended description should describe what the package does and how
it relates to the rest of the system (in terms of, for example, which
subsystem it is which part of).

@item
Put important information first, both in the synopis and extended
description.  Sometimes only the first part of the synopsis or of the
description will be displayed.  You can assume that there will usually
be a way to see the whole extended description.

@item
You may include information about dependencies and so forth in the
extended description, if you wish.

@item
Do not use tab characters.  Their effect is not predictable.
@end itemize

Example control file for Smail:

@smallexample
Package: smail
Version: 3.1.29.1-13
Maintainer: Ian Jackson <iwj10@@cus.cam.ac.uk>
Recommends: pine | mailx | elm | emacs | mail-user-agent
Suggests: metamail
Depends: cron, libc5
Conflicts: sendmail
Provides: mail-transport-agent
Description: Electronic mail transport system.
 Smail is the recommended mail transport agent (MTA) for Debian.
 .
 An MTA is the innards of the mail system - it takes messages from
 user-friendly mailer programs and arranges for them to be delivered
 locally or passed on to other systems as required.
 .
 In order to make use of it you must have one or more user level
 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
 and VM as mailreaders) installed.  If you wish to send messages other
 than just to other users of your system you must also have appropriate
 networking support, in the form of IP or UUCP.
@end smallexample

@node Configuration of init, Maintainer script arguments and how dpkg does things, How to write the Description control file field, Appendix
@unnumberedsec Configuration of init

The @file{/etc/init.d} directory contains the scripts executed by
init(8) when init state (or "runlevel") is changed.  This includes the
boot process, when the multi-user state begins.  Several of these
scripts are included with init and are intended to be executed
@emph{once}, usually at boot time.  An example is
@file{/etc/init.d/boot}, which is executed at boot time to check and
mount file systems, activate swap, load kernel modules, etc.--everything
that needs to be done before the multi-user state begins.
@file{/etc/init.d} also contains the scripts that are executed when
entering runlevel 0 (halt), runlevel 1 (single-user) and runlevel 6
(reboot).

Packages can (and should) place scripts in @file{/etc/init.d} to start
or stop services at boot time or during a change of runlevel.  These
scripts should be named @file{/etc/init.d/}<package>, and they should
accept one of two arguments: "start", which starts the services, or
"stop", which stops the services.  These scripts should ensure that they
will behave sensibly if invoked with "start" when the service is already
running, or with "stop" when it isn't---the best way to achieve this is
often to use @file{start-stop-daemon}.

This script should not fail obscurely when the configuration files
remain but the package has been removed, as the default in dpkg is to
leave configuration files on the system after the package has been
removed.  Only when it is executed with the `--purge' option will dpkg
remove configuration files.  Therefore, you should include a `test'
statement at the top of the script, like this:

@smallexample
test -f <program-executed-later-in-script> || exit 0
@end smallexample

These scripts should be referenced, when appropriate, by symbolic links
in the @file{/etc/rc?.d} directories, as below.

When changing runlevels, init looks in the directory @file{/etc/rc<n>.d}
for the scripts it should execute, where <n> is the runlevel that is
being changed to.  Please note that the "scripts" in @file{/etc/rc?.d}
are not actually scripts; they are symbolic links, referencing actual
scripts in @file{/etc/init.d}.  For simplicity, we refer to them as
"scripts".

First, the scripts prefixed with a "K" are executed, followed by the
scripts prefixed with an "S".  The "K" scripts are responsible for
killing certain services and the "S" scripts for starting certain
services upon @emph{entering} the runlevel.  For example, if we are
changing from runlevel 2 to runlevel 3, init will first execute all of
the "K" prefixed scripts it finds in @file{/etc/rc3.d} (to kill
services), and then all of the "S" prefixed scripts it finds in
@file{/etc/rc3.d} (to start services).  The "K" scripts will execute the
file it references with an argument of "stop", and the "S" scripts will
execute this file with an argument of "start".

After the "K" or "S" prefix, there should be a number specified, and
this number should be between 00 and 99.  The number determines the
order in which the scripts are run.  For example, the "K20" scripts will
be executed before the "K30" scripts.  You can use this number to make
sure that a certain service is started before another.  For example, on
some machines, the program @file{setserial} may need to properly set an
IRQ before the @file{ppp} program uses a modem to connect to a network.
In this case, the script that runs @file{setserial} should have a lower
number than the script that starts @file{ppp} so that it runs first:

@smallexample
@file{/etc/rc2.d/S10setserial}
@file{/etc/rc2.d/S20ppp}
@end smallexample

If it does not matter when or in which order the script is run, use the
number "20".  If it does, then you should talk to the maintainer of the
@code{sysvinit} package or post to @code{debian-devel}, and they will
help you choose a number.

In Debian Linux, we try to ship our software in as much of a
"default" state as possible.  Therefore, unless there is a good reason
for doing differently, we ask that you start the services in each of the
multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
runlevel (0), the single-user runlevel (1) and the reboot runlevel (6).

The system administrator will have the opportunity to customize
runlevels by simply adding, moving, or removing the symbolic links in
@file{/etc/rc?.d}.  This is why we default to running everything in the
multi-user state--a reasonable default--and the administrator can easily
customize init to be as complex and sophisticated as he or she wants it
to be beyond this.

We provide a script, @file{update-rc.d}, to make it easier for package
maintainers to arrange for the proper creation and removal of
@file{/etc/rc?.d} symbolic links from their postinst and postrm scripts.
You should use this script to make changes to @file{/etc/rc?.d} and
@emph{never} include any @file{/etc/rc.?.d} symbolic links in the actual
archive.

@itemize @bullet
@item
In the postinst script, you need only do the following to setup
@file{/etc/rc?.d}.  You should redirect standard output to
@file{/dev/null}, as @file{update-rc.d} produces insignificant output:

@smallexample
update-rc.d <package> default >/dev/null
@end smallexample

where <package> is the name of the file as it appears in
@file{/etc/init.d}.  It will use the default number of "20", as
mentioned above.  If you need to use a different number, you can specify
it after "default":

@smallexample
update-rc.d <package> default 30 >/dev/null
@end smallexample

@item
In the postrm script, you need only do the following @emph{if and only
if} it is called with the `purge' argument:

@smallexample
if [ purge = "$1" ]
then
  update-rc.d <package> remove >/dev/null
fi
@end smallexample
@end itemize

@unnumberedsubsec Important Note:

@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in the
archive!  @emph{This will cause problems!}  You should create them with
update-rc.d, as above.

@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in
conffiles!  @emph{This will cause problems!}  @emph{Do}, however,
include the @file{/etc/init.d} scripts in conffiles.


@unnumberedsubsec Example:

The process accounting package wants to make sure that process
accounting is started at boot time and that it is stopped before the
system is halted, enters the single-user state, or is rebooted (so
that the @file{/var} file system can be properly unmounted).  It puts
a script that does this in @file{/etc/init.d}, naming the script
appropriately "acct".  This script accepts one of two arguments:
either "start", which starts process accounting, or "stop", which
stops it.  To ensure that it does not fail obscurely when the
configuration files remain but the package has been removed, we
include a `test' statement at the top of the script:

@smallexample
#! /bin/sh
#
# Start process accounting.
. /etc/init.d/functions
test -f /usr/sbin/accton || exit 0
case "$1" in
  start)
    echo "Starting process accounting"
    /usr/sbin/accton /var/account/pacct
    ;;
  stop)
    echo "Stopping process accounting"
    /usr/sbin/accton
    ;;
  *)
    echo "Usage: /etc/init.d/acct @{start|stop@}"
    exit 1
esac
exit 0
@end smallexample

You may find a skeletal script from which to base your @file{/etc/init.d}
scripts in @file{/etc/init.d/skeleton}.

We want to stop then (re)start process accounting when entering a
multi-user state--runlevels 2, 3, 4, and 5--and we want to stop it when
leaving such a state--runlevels 0 (halt), 1 (single) and 6 (reboot).
These are good defaults, and we accomplish this by including the
following in the postinst:

@smallexample
update-rc.d acct default >/dev/null
@end smallexample

When the user removes the acct packages with the `--purge' option, we
want to make sure the @file{/etc/rc?.d} symbolic links are properly
removed, so we include the following in the postrm:

@smallexample
update-rc.d acct remove >/dev/null
@end smallexample

Otherwise, the @file{/etc/rc?.d} symbolic links will remain on the system
along with @file{/etc/init.d/acct} script.

@node Maintainer script arguments and how dpkg does things, Mail processing packages, Configuration of init, Appendix
@unnumberedsec Maintainer script arguments and how dpkg does things

This appendix describes exactly how maintainer scripts are called, with
what arguments, in what order, and what @file{dpkg} does in between.

In all cases version numbers are <version>-<revision>, if the package
has both, or just <version>.  @code{upgrade} is used even when the new
version number looks lower than the old.  If there is no appropriate
version then the argument may be the empty string (or, in versions of
dpkg before 1.2.1, @code{<unknown>}).


@unnumberedsubsec Summary

@smallexample
<new preinst> install
<new preinst> install <old-version>
<new preinst> upgrade <old-version>
<old preinst> abort-upgrade <new-version>

<postinst> configure <most-recently-configured-version>
<old postinst> abort-upgrade <new version>
<conflictor's postinst> abort-remove in-favour <package> <new version>
<deconfigured's postinst> abort-deconfigure \
              in-favour <package-being-installed-but-failed> <version>
              removing <conflicting-package> <version>

<prerm> remove
<old prerm> upgrade <new version>
<new prerm> failed-upgrade <old-vppersion>
<conflictor's prerm> remove in-favour <package> <new version>
<deconfigured's prerm> deconfigure \
              in-favour <package-being-installed> <version> \
              removing <conflicting-package> <version>

<postrm> remove
<postrm> purge
<old postrm> upgrade <new-version>
<new postrm> failed-upgrade <old-version>
<new postrm> abort-install
<new postrm> abort-install <old-version>
<new postrm> abort-upgrade <old-version>
<disappearer's postrm> disappear <overwriter> <new version>
@end smallexample


@unnumberedsubsec Details of unpack phase of installation or upgrade

The procedure on installation/upgrade/overwrite/disappear (ie, when
running @code{dpkg --unpack}, or the unpack stage of @code{dpkg
--install}) is as follows.  In each case if an error occurs the actions
in are general run backwards - this means that the maintainer scripts
are run with different arguments in reverse order.  These are the `error
unwind' calls listed below.

@enumerate
@item
@noindent @enumerate a
@item
If a version the package is already
installed, call
@smallexample
<old prerm> upgrade <new version>
@end smallexample
@item
If this gives an error (ie, a non-zero exit status), dpkg will
attempt instead:
@smallexample
<new prerm> failed-upgrade <old-version>
@end smallexample
@noindent error unwind, for both the above cases:
@smallexample
<old postinst> abort-upgrade <new version>
@end smallexample
@end enumerate
@item
If a `conflicting' package is being removed at the same time:
@noindent @enumerate a
@item
If any packages depended on that conflicting package and
@code{--auto-deconfigure} is specified, call, for each such package:
@smallexample
<deconfigured's prerm> deconfigure \
 in-favour <package-being-installed> <version> \
 removing <conflicting-package> <version>
@end smallexample
@noindent error unwind:
@smallexample
<deconfigured's postinst> abort-deconfigure \
 in-favour <package-being-installed-but-failed> <version>
 removing <conflicting-package> <version>
@end smallexample
The deconfigured packages are marked as requiring configuration, so
that if --install is used they will be configured again if possible.
@item
To prepare for removal of the conflicting package, call:
@smallexample
<conflictor's prerm> remove in-favour <package> <new version>
@end smallexample
@noindent error unwind:
@smallexample
<conflictor's postinst> abort-remove in-favour <package> <new version>
@end smallexample
@end enumerate
@item
@noindent @enumerate a
@item
If the package is being upgraded, call
@smallexample
<new preinst> upgrade <old-version>
@end smallexample
@item
otherwise, if the package had some configuration files from a previous
version installed (ie, it is in the conffiles-only state):
@smallexample
<new preinst> install <old-version>
@end smallexample
@item
otherwise (ie, the package was completely purged):
@smallexample
<new preinst> install
@end smallexample
@noindent error unwind versions, respectively:
@smallexample
<new postrm> abort-upgrade <old-version>
<new postrm> abort-install <old-version>
<new postrm> abort-install
@end smallexample
@end enumerate
@item
The new package's files are unpacked, overwriting any that may be on the
system already, for example any from the old package or from another
package (backups of the old files are left around, and if anything goes
wrong dpkg will attempt to put them back as part of the error unwind).
@item
@noindent @enumerate a
@item
If the package is being upgraded, call
@smallexample
<old postrm> upgrade <new-version>
@end smallexample
@item
If this fails, dpkg will attempt:
@smallexample
<new postrm> failed-upgrade <old-version>
@end smallexample
@noindent error unwind, for both cases:
@smallexample
<old preinst> abort-upgrade <new-version>
@end smallexample
@end enumerate
This is the point of no return - if dpkg gets this far, it won't back
off past this point if an error occurs.  This will leave the package in
a fairly bad state, which will require a successful reinstallation to
clear up, but it's when dpkg starts doing things that are irreversible.
@item
Any files which were in the old version of the package but not in the
new are removed.
@item
The new file list replaces the old.
@item
The new maintainer scripts replace the old.
@item
Any packages all of whose files have been overwritten during the
installation, and which aren't required for dependencies, are considered
to have been removed.  For each such package,
@noindent @enumerate a
@item
dpkg calls:
@smallexample
<disappearer's postrm> disappear <overwriter> <new version>
@end smallexample
@item
The package's maintainer scripts are removed.
@item
It is noted in the status database as being in a sane state, namely not
installed (any conffiles it may have are ignored).  Note that
disappearing packages do not have their prerm called, because dpkg
doesn't know in advance that the package is going to vanish.
@end enumerate
@item
Any files in the package we're unpacking that are also listed in the
file lists of other packages are removed from those lists.  (This will
lobotomise the file list of the `conflicting' package if there is one.)
@item
The backup files made at 4. are deleted.
@item
The new package's status is now sane, and recorded as `unpacked'.  Here
is another point of no return - if the conflicting package's removal
fails we do not unwind the rest of the installation; the conflicting
package is left in a half-removed limbo.
@item
If there was a conflicting package we go and do the removal actions,
starting from point 2. of the removal, below.
@end enumerate


@unnumberedsubsec Details of configuration

When we configure a package (this happens with @code{dpkg --install}, or with
@code{--configure}), we first update the conffiles and then call:
@smallexample
<postinst> configure <most-recently-configured-version>
@end smallexample

No attempt is made to unwind after errors during configuration.


@unnumberedsubsec Details of removal and/or configration purging

@enumerate
@item
@smallexample
<prerm> remove
@end smallexample
@item
The package's files are removed (except conffiles).
@item
@smallexample
<postrm> remove
@end smallexample
@item
All the maintainer scripts except the postrm are removed.

If we aren't purging the package we stop here.  Note that packages which
have no postrm and no conffiles are automatically purged when removed,
as there is no difference except for the dpkg status.

@item
The conffiles and any backup files (@samp{~}-files, @samp{#*#} files,
@samp{%}-files, .dpkg-@{old,new,tmp@}, etc.) are removed.
@item
@smallexample
<postrm> purge
@end smallexample
@item
The package's file list is removed.
@end enumerate
No attempt is made to unwind after errors during removal.

@node Mail processing packages, Virtual dependencies, Maintainer script arguments and how dpkg does things, Appendix
@unnumberedsec Mail processing packages

Debian packages which process electronic mail (whether mail-user-agents
(MUA) or alternative mail-transport-agents (MTA)) @emph{must} make sure
that they are compatible with the configuration decisions below.
Failure to do this may result in lost mail, broken @code{From:} lines,
and other serious brain damage!

@itemize @bullet
@item
The mail spool is @file{/var/spool/mail} and the interface to send a
mail message is @file{/usr/sbin/sendmail} (as per the FSSTND).  The mail
spool is part of the base and not part of the MTA package.

@item
Mailboxes are locked using the @file{.lock} lockfile convention, rather
than fcntl, flock or lockf.

@item
Mailboxes are generally 660 @file{<user>.mail} unless the user has
chosen otherwise.  A MUA may remove a mailbox (unless it has nonstandard
permissions) in which case the MTA or another MUA must recreate it if
needed.  Mailboxes must be writeable by group mail.

@item
The mail spool is 2775 mail.mail, and MUA's need to be setgid mail to do
the locking mentioned above (and obviously need to avoid accessing other
users' mailboxes using this privilege).

@item
@file{/etc/aliases} is the source file for the system mail aliases (e.g.
postmaster, usenet, etc.) - it is the one which the sysadmin and
postinst scripts may edit.

@item
The convention of writing `forward to <address>' in the mailbox itself
is not supported.  Use a @file{.forward} file instead.

@item
The location for the @file{rmail} program used by UUCP for incoming mail
is @file{/usr/sbin/rmail}, as per the FSSTND.  Likewise, @file{rsmtp},
for receiving batch-SMTP-over-UUCP, is in @file{/usr/sbin/rsmtp} if it
is supported.

@item
Smail is not using HoneyDanBer UUCP, whose uux apparently accepts -a and
-g options.

@item
If you need to know what name to use (for example) on outgoing news and
mail messages which are generated locally, you should use the file
@file{/etc/mailname}.  It will contain the portion after the username
and @samp{@@} sign for email addresses of users on the machine (followed
by a newline).
@end itemize

A package should check for the existence of this file.  If it exists it
should use it without comment @footnote{An MTA's prompting configuration
script may wish to prompt the user even if it finds this file exists.}.
If it does not exist it should prompt the user for the value and store
it in @file{/etc/mailname} as well as using it in the package's
configuration.  The prompt should make it clear that the name will not
just be used by that package.  E.g., in the same situation the INN
package says:

@smallexample
Please enter the `mail name' of your system.  This is the hostname
portion of the address to be shown on outgoing news and mail messages.
The default is `$syshostname', your system's host name.
Mail name [`$syshostname']:
@end smallexample
($syshostname is the output of `hostname --fqdn').

@node  Virtual dependencies, , Mail processing packages, Appendix
@comment  node-name,  next,  previous,  up
@unnumberedsec Virtual dependencies

Virtual packages are in the same namespace as real packages, and may
have the same name.  The meaning of a virtual package in a
dependency/conflicts list is exactly that of listing all the real
packages which state that they are an instantiation of that virtual
package.

This is done with a new Provides field in the control file, with a
syntax much like the Conflicts field.

The idea is that we can have something like:
@smallexample
Package: elm
Depends: mta

Package: smail
Provides: mta
Conflicts: mta

Package: sendmail
Provides: mta
Conflicts: mta
@end smallexample
@noindent The result is equivalent to elm having said
@smallexample
Package: elm
Depends: smail | sendmail
@end smallexample

(There'll be a special case to say that a package may conflict with a
virtual package which it provides - clearly ...)

If there are both a real and a virtual package of the same name then
the dependency may be satisfied (or the conflict caused) by either the
real package or any of the virtual packages which provide it.  This is
so that, for example, supposing we have
@smallexample
Package: lout
Optional: ghostview
@end smallexample
(this is a fictional example - the Lout package should not mention
ghostview), and someone else comes up with a nice PostScript
previewer, then they can just say
@smallexample
Package: marvelpostview
Provides: ghostview
@end smallexample
and all will work in the interim (until, say, the Lout maintainer
changes things).

If a dependency or a conflict has a version number attached then only
real packages will be considered to see whether the relationship is
satisfied (or prohibited, for a conflict) - it is assumed that a real
package which provides virtual package is not of the `right' version.
If there is demand it can be arranged that a package which provides a
virtual package may mention a version number, though this is unlikely to
be helpful:
@smallexample
Provides: mta (2.0)
@end smallexample

If you want to specify which of a set of real packages should be the
default to satisfy a particular dependency on a virtual package, you can
simply list the real package as alternative before the virtual one:
@smallexample
Package: xbaseR6
Recommended: xsvga | x-server
Provides: x-base, xr6shlib

Package: xsvga
Recommended: x-base
Provides: x-server

Package: x8514
Recommended: x-base
Provides: x-server
@end smallexample

Virtual package names should generally not be used in the names of
@file{/etc/init.d} scripts, configuration files, logfiles, and so on, so
that several programs providing the same virtual package name can be
installed.

@bye