Maintainer
information
Maintainer
field with the correct name
and a working email address for the Debian maintainer of the package.
If one person maintains several packages they should try to avoid
having different forms of their name and address in different
Maintainer
fields.
All packages must use virtual package names where appropriate, and arrange to create new ones if necessary. They must not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.
The latest version of the authoritative list of virtual package names
can be found on ftp.debian.org
in
/debian/doc/package-developer/virtual-package-names-list.text
or your local mirror. The procedure for updating it is described at
the top of the file.
Section
and Priority
non-free
, contrib
or
the main distribution - see Package copyright, chapter 2, and put an
appropriate value for the distribution in the debian/changelog
file.
The Priority
and Section
control file fields give
information for classifying the package in dselect and say
which directory to place it in the FTP archive.
They are ultimately the responsibility of the distribution
maintainers; however, you should suggest values for them in your
.changes
information when you upload a package. You do this by
including appropriate information in the debian/control
file
before building the packages.
For a list of the currently in-use sections, please see the FTP
archive. Packages in the non-free and contrib areas should have
section non-free
and contrib
, respectively.
Priority
values
required
required
packages are necessary for the proper functioning of the
system. You must not remove these packages or your system may become
totally broken and you may probably not even be able to use
dpkg to put things back. Systems with only the required
packages are probably unuseable, but they do have enough functionality
to allow the sysadmin to boot and install more software.
important
important
. This is an
important criterion because we are trying to produce, amongst other
things, a free Unix. Other packages without which the system will not
run well or be useable should also be here. This does not
include Emacs or X11 or TeX or any other large applications. The
important
packages are just a bare minimum of commonly-expected
and necessary tools.
standard
optional
[4]extra
Priority values are not case-sensitive.
Section: base
and are in the base
subdirectory on the FTP archives. These are the packages that are
supplied on the base disks. They are the minimum sensible set for
installing new packages (perhaps via a network).
Most of these packages should have Priority: required
or at least
Priority: important
, and many will be essential (see below).
Pre-Depends
and the Essential
flag
Pre-Depends
or Essential: yes
unless your package
is absolutely vital to the functioning of the system and the
installation of other packages. Do not do either of these things
without consultation with the distribution maintainers or on
debian-devel.Usually, neither of these fields should be used unless removing a package really will completely hose the system, making it impossible to recover by (re)installing packages with dpkg.
Essential
should not be used for a shared library package - the
dependencies will prevent its premature removal, and we need to be
able to remove it when it has been superseded.
It is not necessary for other packages to declare any dependencies
they have on other packages which are marked Essential
.
Priority
and Section
in the .deb
control file
-is
, -isp
or
-ip
option to dpkg-gencontrol, so that the Section
and/or Priority
is copied into the actual control information in
the .deb
file. However, if you do this you should make sure you
keep the information up to date so that users are not shown
conflicting information.
Description
control file field
The description should be written so that it tells the user what they
need to know to decide whether to install the package. This
description should not just be copied from the blurb for the program.
Instructions for configuring or using the package should not be
included - that is what installation scripts, manpages, Info files and
/usr/doc/
package are for. Copyright statements and other
administrivia should not be included - that is what
/usr/doc/
package/copyright
is for.
If you wish to include a list in your extended with entries which are a line or more each you must indent each entry by one space to make sure that it doesn't get wordwrapped. The start of each list entry should be marked with an asterisk, followed by a single space. You must wrap the list entries yourself to 75 columns, and should start continuation lines indented by three spaces so that they line up with the start of the text on the first line of each list entry.
See the programmers' manual for further requirements and pitfalls.
tsx-11.mit.edu
in
/pub/linux/docs/linux-standards/fsstnd/
. Specific
questions about following the standard may be asked on
debian-devel, or referred to Daniel Quinlan, the FSSTND
coordinator, at quinlan@pathname.com.
/usr/man
. You should only use sections 1 to 9
(see the FSSTND for more details). You must not install a
preformatted `cat page'.
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 undocumented(7)
manual page should be provided. This symbolic link can be
created from debian/rules
like this:
ln -s ../man7/undocumented.7.gz \ debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gzThis manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has (you can report it yourself, if you like). Do not close the bug report until a proper manpage is available.
You may forward a complaint about a missing manpage to the upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do not in general consider the lack of a manpage to be a bug, we do - if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open anyway.
Manpages should be installed compressed using gzip -9
.
If one manpage needs to be accesssible via several names it is better
to use a symbolic link than the .so
feature, but there is no need
to fiddle with the relevant parts of the upstream source to change
from .so
to symlinks - don't do it unless it's easy. Do not
create hard links in the manual page directories, and do not put
absolute filenames in .so
directives. The filename in a .so
in a manpage should be relative to the base of the manpage tree
(usually /usr/man
).
/usr/info
. They should
be compressed with gzip -9
.
Your package must call install-info to update the Info dir
file, in its post-installation script:
install-info --quiet --section Development Development \ /usr/info/foobar.info
It is a good idea to specify a section for the location of your
program; this is done with the --section
switch. To determine
which section to use, you should look at /usr/info/dir
on your
system and choose the most relevant (or create a new section if none
of the current sections are relevant). Note that the --section
flag takes two arguments; the first is a regular expression to match
(case-insensitively) against an existing section, the second is used
when creating a new one.
You must remove the entries in the pre-removal script:
install-info --quiet --remove /usr/info/foobar.info
If install-info cannot find a description entry in the Info
file you will have to supply one. See install-info(8)
for details.
/usr/doc/
package
[5] and compressed with gzip -9
unless it is small.If a package comes with large amounts of documentation which many users of the package will not require you should create a separate binary package to contain it, so that it does not take up disk space on the machines of users who do not need or want it installed.
It is often a good idea to put text information files (README
s,
changelogs, and so forth) that come with the source package in
/usr/doc/
package in the binary package. However, you don't
need to install the instructions for building and installing the package, of
course!
If your package comes with extensive documentation in a markup format
that can be converted to various other formats you should if possible
ship HTML versions in the binary package, in the directory
/usr/doc/
package or its subdirectories.
Other formats such as PostScript may be provided at your option.
/usr/doc/
package/examples
.
These files should not be referenced by any program - they're there
for the benefit of the system administrator and users, as
documentation only.
/usr/doc/
package/changelog.Debian.gz
and /usr/doc/
package/changelog.upstream.gz
.
debian/changelog
file from your Debian source tree, and a copy of the upstream
changelog file if there is one. They should usually be installed in
/usr/doc/
package
as changelog.Debian.gz
and
changelog.gz
respectively.
Both should be installed compressed using gzip -9
, as they will
become large with time even if they start out small.
If the package has only one changelog which is used both as the Debian
changelog and the upstream one because there is no separate upstream
maintainer then that changelog should usually be installed as
/usr/doc/
package/changelog.gz
; if there is a separate
upstream maintainer, but no upstream changelog, then the Debian
changelog should still be called changelog.Debian.gz
.
/usr/doc/
package/copyright
It must contain the full text of the copyright notice and any
acknowledgements for the program and the licence terms under which the
program is distributed. If the package is distributed under the GNU
General Public Licence, the GNU Library General Public Licence, the
Regents of the University of California at Berkeley (BSD) licence or
Larry Wall's Artistic Licence please say so instead of including a
copy of the licence. The files BSD
, GPL
, LGPL
and
Artistic
are be available in /usr/doc/copyright
for you
to refer to.
The copyright file should not be compressed unless it is very large.
Do not use the copyright file as a general README
file. If your
package has such a file it should be installed in
/usr/doc/
package/README
or README.Debian
or some
other appropriate place.
In particular, symlinks from one part of /usr
to another
should be relative.
In certain cases, however, relative links may cause more problems.
For example, links into /etc
and /var
should be
absolute.
Note that when creating a relative link using ln it is not necessary for the target of the link to exist relative to the working directory you're running ln from; nor is it necessary to change directory to the directory where the link is to be made. Simply include the string that should appear as the target of the link (this will be a pathname relative to the directory in which the link resides) as the first argument to ln.
For example, in your Makefile or debian/rules
, do things
like:
ln -fs gcc $(prefix)/bin/cc ln -fs gcc debian/tmp/usr/bin/cc ln -fs ../sbin/sendmail $(prefix)/bin/runq ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
/var/log/
package.log
.
If you have many logfiles, or need a separate directory for
permissions reasons (/var/log
is writeable only by
root
), you should usually create a directory named
/var/log/
package
.
Make sure that any logfiles are rotated occasionally so that they
don't grow indefinitely; the best way to do this is to use
savelog program in an /etc/cron.daily
,
/etc/cron.weekly
or /etc/cron.monthly
script.
Make sure that any logfiles are removed when the package is purged (but not when it is only removed), by checking the argument to the postrm script (see the programmer's manual for details).
/usr/local
- for the use of the system administrator
/usr/local
, either by putting them in the filesystem archive to
be unpacked by dpkg or by manipulating them in their maintainer
scripts.
Every package that searches a number of directories or files for
something (for example, looking for shared libraries in /lib
or
/usr/lib
) should search an appropriate directory in
/usr/local
too.
In order that the system administrator may know where to place
additional files a package should create an empty directory in the
appropriate place in /usr/local
by supplying it in the
filesystem archive for unpacking by dpkg. The
/usr/local
directory itself and all the subdirectories created
by the package should have permissions 2775 (group-writeable and
set-group-id) and be owned by root.staff
.
In the future it will be possible to tell dpkg not to unpack
files matching certain patterns, so that system administrators who do
not wish these directories in /usr/local
do not need to have
them.
Files should be owned by root.root
, and made writeable only by
the owner and universally readable (and executable, if appropriate).
Directories should be mode 755 or (for group-writability) mode 2775. 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.
Setuid and setgid executables should be mode 4755 or 2755 respectively, and owned by the appropriate user or group. They should not be made unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no extra security, because anyone can find the binary in the freely available Debian package - it is merely inconvenient. For the same reason you should not restrict read or execute permissions on non-set-id executables.
Some setuid programs need to be restricted to particular sets of users, using file permissions. In this case they should be owned by the uid to which they are set-id, and by the group which should be allowed to execute them. They should have mode 4754; there is no point in making them unreadable to those users who must not be allowed to execute them.
Do not arrange that the system administrator can only reconfigure the package to correspond to their local security policy by changing the permissions on a binary. Ordinary files installed by dpkg (as opposed to conffiles and other similar objects) have their permissions reset to the distributed permissions when the package is reinstalled. Instead you should consider (for example) creating a group for people allowed to use the program(s) and making any setuid executables executable only by that group.
Shared libraries should be installed executable.
/etc
. If there are several you should consider creating a
subdirectory named after your package.
It is almost certain that any file in /etc
that is in your
package's filesystem archive should be listed in dpkg's
conffiles
control area file. (See the dpkg programmers'
manual).
--quiet
option on
install-info.
Packages should try to minimise the amount of prompting they need to
do, and they should ensure that the user will only ever be asked each
question once. This means that packages should try to use appropriate
shared configuration files (such as /etc/papersize
and
/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 dpkg --purge
to remove the package's
configuration. The answers to configuration questions should be
stored in an appropriate place in /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
postinst script and prompt the user to hit return to
acknowledge the message. Copyright messages do not count as vitally
important (they belong in /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).
Any necessary prompting should almost always be confined to the
post-installation script, and should be protected with a conditional
so that unnecssary prompting doesn't happen if a package's
installation fails and the postinst is called with
abort-upgrade
, abort-remove
or abort-deconfigure
.
Errors which occur during the execution of an installation script must be checked and the installation must not continue after an error.
The section below on scripts in general applies to package maintainer scripts too.
#!
line naming
the shell to be used to interpret them.
In the case of Perl scripts this should be #!/usr/bin/perl
.
Shell scripts (sh and bash) should almost certainly
start with set -e
so that errors are detected. Every script
must use set -e
or check the exit status of every
command.
Perl scripts should check for errors when making any system calls,
including open
, print
, close
, rename
and
system
.
csh and tcsh should be avoided as scripting languages.
See Csh Programming Considered Harmful, one of the comp.unix.*
FAQs. It can be found on rtfm.mit.edu
in
/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful
.
If an upstream package comes with csh scripts then you
must make sure that they start with #!/bin/csh
and make your
package depend on the c-shell virtual package.
For a straightforward library which has a development environment and
a runtime kit including just shared libraries you need to create two
packages: libraryname
soname
[6] and
libraryname
soname
-dev
.
If you prefer only to support one development version at a time you
may name the development package libraryname
-dev
; otherwise
you may wish to use dpkg's conflicts mechanism to ensure that
the user only installs one development version at a time (after all,
different development versions are likely to have the same header
files in them, causing a filename clash if both are installed).
Typically the development version will also need an exact version
dependency on the runtime library, to make sure that compilation and
linking happens correctly.
Packages which use the shared library should have a dependency on the
name of the shared library package,
libraryname
soname
. When the soname changes you
can have both versions of the library installed while moving from the
old library to the new.
If your package has some run-time support programs which use the
shared library you must not put them in the shared library
package. If you do that then you won't be able to install several
versions of the shared library without getting filename clashes.
Instead, either create a third package for the runtime binaries (this
package might typically be named libraryname
-runtime
- note
the absence of the soname in the package name) or if the
development package is small include them in there.
If you have several shared libraries built from the same source tree you can lump them all togther into a single shared library package, provided that you change all their sonames at once (so that you don't get filename clashes if you try to install different versions of the combined shared libraries package).
Follow the directions in the dpkg programmers' manual for
putting the shared library in its package, and make sure you include a
shlibs
control area file with details of the dependencies for
packages which use the library.
/etc/skel
/etc/skel
will automatically be copied into new user
accounts by adduser. They should not be referenced there by
any program.
Therefore, if a program needs a dotfile to exist in advance in
$HOME
to work sensibly that dotfile should be installed in
/etc/skel
(and listed in conffiles, if it is not generated and
modified dynamically by the package's installation scripts).
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 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
/etc
. Only if the program doesn't support a site-wide default
configuration and the package maintainer doesn't have time to add it
should a default per-user file be placed in /etc/skel
.
/etc/skel
should be as empty as we can make it. This is
particularly true because there is no easy mechanism for ensuring that
the appropriate dotfiles are copied into the accounts of existing
users when a package is installed.
Ideally the sysadmin should ideally not have to do any configuration other than that done (semi-)automatically by the postinst script.
root.root
.Each game decides on its own security policy.
Games which require protected, privileged access to high-score files,
savegames, &c, must be made set-group-id (mode 2755) and
owned by root.games
, and use files and directories with
appropriate permissions (770 root.games
, for example). They must
not be made set-user-id, as this causes security
problems.[7]
Some packages, for example some fortune cookie programs, are
configured by the upstream authors to install with their data files or
other static information made unreadable so that they can only be
accessed through set-id programs provided. Do not do this in a Debian
package: anyone can download the .deb
file and read the data from
it, so there is no point making the files unreadable. Not making the
files unreadable also means that you don't have to make so many
programs set-id, which reduces the risk of a security hole.
You must ask for a user or group id from the base system maintainer,
and must not release the package until you have been allocated one.
Once you have been allocated one you must make the package depend on a
version of the base system with the id present in /etc/passwd
or /etc/group
, or alternatively arrange for your package to
create the user or group itself with the correct id (using
adduser
) in its pre- or post-installation script (the latter is
to be preferred if it is possible).
On the other hand, the program may able to determine the uid or gid from the group name at runtime, so that a dynamic id can be used. In this case you must choose an appropriate user or group name, discussing this on debian-devel and checking with the base system maintainer that it is unique and that they do not wish you to use a statically allocated id instead. When this has been checked you must arrange for your package to create the user or group if necessary using adduser in the pre- or post-installation script (again, the latter is to be preferred if it is possible).
Note that changing the numeric value of an id associated with a name is very difficult, and involves searching the filesystem for all appropriate files. You need to think carefully whether a static or dynamic id is required, since changing your mind later will cause problems.
In order for update-alternatives to work correctly all the
packages which supply an instance of the `shared' command name (or, in
general, filename) must use it. You can use Conflicts
to force
the deinstallation of other packages supplying it which do not (yet)
use update-alternatives. It may in this case be appropriate to
specify a conflict on earlier versions on something - this is an
exception to the usual rule that this is not allowed.