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.
Depends
field which mentions the shared C library required for
the program to run. For ELF binaries linked against libc.so.5
the relevant package name is libc5
.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
[2]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
.
Essential
flag
Essential: yes
control file field should not be used unless
removing a package really will completely hose the system; nor should
it 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.
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/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@yggdrasil.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 \ debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]This 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 uncompressed.
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 use 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
[3] 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 that come with
the source package in /usr/doc/
package in the binary
package. However, don't 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/copyright/
package
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 package's copyright file should not be compressed.
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. Do not make links between
/usr/doc/
package and the
copyright
directory.
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 using 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 every 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.
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 csh.
CC = gcc CFLAGS = -O2 -g -Wall # sane warning options vary between programs LDFLAGS = # none install -s # (or use strip on the files in debian/tmp)
Note that all installed binaries should be stripped, either by using
the -s
flag to install, or by calling strip on the
binaries after they have been copied into debian/tmp
but
before the tree is made into a package.
Make sure that you do not link with -g
, as this makes a.out
compilers produce huge statically linked binaries. The -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.
The -N
flag should not be used. On a.out systems it may have
been useful for some very small binaries, but for ELF it has no good
effect.
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 (-O3
, for example); feel free to use them. Please use good
judgment here. Don't use flags for the sake of it; only use them if
there is good reason to do so. Feel free to override the upstream
author's ideas about which compilation options are best - they are
often inappropriate for our environment.
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.
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
[4] and
libraryname
soname
-dev
.
If you prefer only to support one development version 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.
/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.
From:
lines, and other serious brain damage!
The mail spool is /var/spool/mail
and the interface to send a
mail message is /usr/sbin/sendmail
(as per the FSSTND). The
mail spool is part of the base system and not part of the MTA package.
Mailboxes are locked using the username
.lock
lockfile
convention, rather than fcntl, flock or lockf.
Mailboxes are generally 660 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.
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).
/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. After /etc/aliases
is edited
the program or human editing it must call newaliases. All MTA
packages should come with a newaliases program, even if it does
nothing, but older MTA packages do not do this so programs should not
fail if newaliases cannot be found.
The convention of writing forward to
address in the mailbox
itself is not supported. Use a
.forward
file instead.
The location for the rmail program used by UUCP for incoming
mail is /usr/sbin/rmail
, as per the FSSTND. Likewise,
rsmtp, for receiving batch-SMTP-over-UUCP, is in
/usr/sbin/rsmtp
if it is supported.
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
/etc/mailname
. It will contain the portion after the username
and @
(at) sign for email addresses of users on the machine
(followed by a newline).
A package should check for the existence of this file. If it exists
it should use it without comment.[5] If it does not exist it should prompt the user
for the value and store it in /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 this
situation the INN package says:
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']:where syshostname is the output of
hostname -fqdn
.
Such programs should be configured with X support, and should
declare a dependency on elf-x11r6lib
(for the X11R6 libraries).
Users who wish to use the program can install just the relatively
small xlib
package, and do not need to install the whole of X.
Do not create two versions (one with X support and one without) of your package.
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.[6]
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.