The location of all installed files and directories must comply with the
Filesystem Hierarchy Standard (FHS), version 2.1, except where doing so would
violate other terms of Debian Policy. The version of this document referred
here can be found in the debian-policy package or on FHS (Debian
copy) alongside this manual. The latest version, which may be a
more recent version, may be found on FHS (upstream). Specific
questions about following the standard may be asked on the
debian-devel mailing list, or referred to the FHS mailing list
(see the FHS web site
for more information).
As mandated by the FHS, packages must not place any files in
/usr/local, either by putting them in the file system archive to
be unpacked by dpkg or by manipulating them in their maintainer
scripts.
However, the package may create empty directories below /usr/local so that the system administrator knows where to place site-specific files. These directories should be removed on package removal if they are empty.
Note, that this applies only to directories below /usr/local, not in /usr/local. Packages must not create sub-directories in the directory /usr/local itself, except those listed in FHS, section 4.5. However, you may create directories below them as you wish. You must not remove any of the directories listed in 4.5, even if you created them.
Since /usr/local can be mounted read-only from a remote server,
these directories must be created and removed by the postinst and
prerm maintainer scripts and not be included in the
.deb archive. These scripts must not fail if either of these
operations fail.
For example, the emacsen-common package could contain something like
if [ ! -e /usr/local/share/emacs ]
then
if mkdir /usr/local/share/emacs 2>/dev/null
then
chown root:staff /usr/local/share/emacs
chmod 2775 /usr/local/share/emacs
fi
fi
in its postinst script, and
rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
rmdir /usr/local/share/emacs 2>/dev/null || true
in the prerm script. (Note that this form is used to ensure that
if the script is interrupted, the directory /usr/local/share/emacs
will still be removed.)
If you do create a directory in /usr/local for local additions to a package, you should ensure that settings in /usr/local take precedence over the equivalents in /usr.
However, because /usr/local and its contents are for exclusive use of the local administrator, a package must not rely on the presence or absence of files or directories in /usr/local for normal operation.
The /usr/local directory itself and all the subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be owned by root.staff.
The system-wide mail directory is /var/mail. This directory is
part of the base system and should not owned by any particular mail agents.
The use of the old location /var/spool/mail is deprecated, even
though the spool may still be physically located there. To maintain partial
upgrade compatibility for systems which have /var/spool/mail as
their physical mail spool, packages using /var/mail must depend on
either libc6 (>= 2.1.3-13), or on base-files
(>= 2.2.0), or on later versions of either one of these packages.
The Debian system can be configured to use either plain or shadow passwords.
Some user ids (UIDs) and group ids (GIDs) are reserved globally for use by certain packages. Because some packages need to include files which are owned by these users or groups, or need the ids compiled into binaries, these ids must be used on any Debian system only for the purpose for which they are allocated. This is a serious restriction, and we should avoid getting in the way of local administration policies. In particular, many sites allocate users and/or local system groups starting at 100.
Apart from this we should have dynamically allocated ids, which should by default be arranged in some sensible order, but the behavior should be configurable.
Packages other than base-passwd must not modify /etc/passwd, /etc/shadow, /etc/group or /etc/gshadow.
The UID and GID numbers are divided into classes as follows:
Packages which need a single statically allocated uid or gid should use one of these; their maintainers should ask the base-passwd maintainer for ids.
adduser will check for the existence of the user or
group, and if necessary choose an unused id based on the ranges specified in
adduser.conf.
adduser will
choose UIDs and GIDs for user accounts in this range, though
adduser.conf may be used to modify this behavior.
These ids are for packages which are obscure or which require many
statically-allocated ids. These packages should check for and create the
accounts in /etc/passwd or /etc/group (using
adduser if it has this facility) if necessary. Packages which are
likely to require further allocations should have a `hole' left after them in
the allocation, to give them room to grow.
The /etc/init.d directory contains the scripts executed by
init at boot time and when the init state (or `runlevel') is
changed (see init(8)).
There are at least two different, yet functionally equivalent, ways of handling
these scripts. For the sake of simplicity, this document describes only the
symbolic link method. However, it must not be assumed by maintainer scripts
that this method is being used, and any automated manipulation of the various
runlevel behaviours by maintainer scripts must be performed using
update-rc.d as described below and not by manually installing or
removing symlinks. For information on the implementation details of the other
method, implemented in the file-rc package, please refer to the
documentation of that package.
These scripts are referenced by symbolic links in the
/etc/rcn.d directories. When changing runlevels,
init looks in the directory /etc/rcn.d for
the scripts it should execute, where n is the runlevel
that is being changed to, or S for the boot-up scripts.
The names of the links all have the form Smmscript or Kmmscript where mm is a two-digit number and script is the name of the script (this should be the same as the name of the actual script in /etc/init.d).
When init changes runlevel first the targets of the links whose
names start with a K are executed, each with the single argument
stop, followed by the scripts prefixed with an S,
each with the single argument start. (The links are those in the
/etc/rcn.d directory corresponding to the new
runlevel.) The K links are responsible for killing services and
the S link for starting services upon 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 /etc/rc3.d, and then all of the S prefixed scripts in that directory. The links starting with K will cause the referred-to file to be executed with an argument of stop, and the S links with an argument of start.
The two-digit number mm is used to determine the order in which to
run the scripts: low-numbered links have their scripts run first. For example,
the K20 scripts will be executed before the K30
scripts. This is used when a certain service must be started before another.
For example, the name server bind might need to be started before
the news server inn so that inn can set up its access
lists. In this case, the script that starts bind would have a
lower number than the script that starts inn so that it runs
first:
/etc/rc2.d/S17bind
/etc/rc2.d/S70inn
The two runlevels 0 (halt) and 6 (reboot) are slightly different. In these runlevels, the links with an S prefix are still called after those with a K prefix, but they too are called with the single argument stop.
Also, if the script name ends .sh, the script will be sourced in
runlevel S rather that being run in a forked subprocess, but will
be explicitly run by sh in all other runlevels.
Packages that include daemons for system services should place scripts in /etc/init.d to start or stop services at boot time or during a change of runlevel. These scripts should be named /etc/init.d/package, and they should accept one argument, saying what to do:
The start, stop, restart, and force-reload options should be supported by all scripts in /etc/init.d, the reload option is optional.
The init.d 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, and that they don't kill unfortunately-named
user processes. The best way to achieve this is usually to use
start-stop-daemon.
If a service reloads its configuration automatically (as in the case of
cron, for example), the reload option of the
init.d script should behave as if the configuration has been
reloaded successfully.
The /etc/init.d scripts must be treated as configuration files, either (if they are present in the package, that is, in the .deb file) by marking them as conffiles, or, (if they do not exist in the .deb) by managing them correctly in the maintainer scripts (see Configuration files, Section 11.7). This is important since we want to give the local system administrator the chance to adapt the scripts to the local system, e.g., to disable a service without de-installing the package, or to specify some special command line options when starting a service, while making sure her changes aren't lost during the next package upgrade.
These scripts should not fail obscurely when the configuration files remain but
the package has been removed, as configuration files remain on the system after
the package has been removed. Only when dpkg is executed with the
--purge option will configuration files be removed. In
particular, as the /etc/init.d/package script itself is
usually a conffile, it will remain on the system if the package is
removed but not purged. Therefore, you should include a test
statement at the top of the script, like this:
test -f program-executed-later-in-script || exit 0
Often there are some variables in the init.d scripts whose values
control the bahaviour of the scripts, and which a system administrator is
likely to want to change. As the scripts themselves are frequently
conffiles, modifying them requires that the administrator merge in
their changes each time the package is upgraded and the conffile
changes. To ease the burden on the system administrator, such configurable
values should not be placed directly in the script. Instead, they should be
placed in a file in /etc/default, which typically will have the
same base name as the init.d script. This extra file should be
sourced by the script when the script runs. It must contain only variable
settings and comments in POSIX sh format. It may either be a
conffile or a configuration file maintained by the package
maintainer scripts. See Configuration
files, Section 11.7 for more details.
To ensure that vital configurable values are always available, the init.d script should set default values for each of the shell variables it uses, either before sourcing the /etc/default/ file or afterwards using something like the : ${VAR:=default} syntax. Also, the init.d script must behave sensibly and not fail if the /etc/default file is deleted.
The program update-rc.d is provided for package maintainers to
arrange for the proper creation and removal of
/etc/rcn.d symbolic links, or their functional
equivalent if another method is being used. This may be used by maintainers in
their packages' postinst and postrm scripts.
You must not include any /etc/rcn.d symbolic links in
the actual archive or manually create or remove the symbolic links in
maintainer scripts; you must use the update-rc.d program instead.
(The former will fail if an alternative method of maintaining runlevel
information is being used.) You must not include the
/etc/rcn.d directories themselves in the archive
either. (Only the sysvinit package may do so.)
By default update-rc.d will start 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
/etc/rcn.d if symbolic links are being used, or by
modifying /etc/runlevel.conf if the file-rc method is
being used.
To get the default behavior for your package, put in your postinst
script
update-rc.d package defaults >/dev/null
and in your postrm
if [ "$1" = purge ]; then
update-rc.d package remove >/dev/null
fi
This will use a default sequence number of 20. If it does not matter when or
in which order the init.d script is run, use this default. If it
does, then you should talk to the maintainer of the sysvinit
package or post to debian-devel, and they will help you choose a
number.
For more information about using update-rc.d, please consult its
manpage update-rc.d(8).
There used to be another directory, /etc/rc.boot, which contained scripts which were run once per machine boot. This has been deprecated in favour of links from /etc/rcS.d to files in /etc/init.d as described in Introduction, Section 10.3.1. Packages must not place files in /etc/rc.boot.
The bind DNS (nameserver) package wants to make sure that the
nameserver is running in multiuser runlevels, and is properly shut down with
the system. It puts a script in /etc/init.d, naming the script
appropriately bind. As you can see, the script interprets the
argument reload to send the nameserver a HUP signal
(causing it to reload its configuration); this way the system administrator can
say /etc/init.d/bind reload to reload the name server. The script
has one configurable value, which can be used to pass parameters to the named
program at startup; this value is read from /etc/default/bind (see
below).
#!/bin/sh
#
# Original version by Robert Leslie
# <rob@mars.org>, edited by iwj and cs
test -x /usr/sbin/named || exit 0
# Source defaults file.
PARAMS=''
if [ -f /etc/default/bind ]; then
. /etc/default/bind
fi
case "$1" in
start)
echo -n "Starting domain name service: named"
start-stop-daemon --start --quiet --exec /usr/sbin/named \
-- $PARAMS
echo "."
;;
stop)
echo -n "Stopping domain name service: named"
start-stop-daemon --stop --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
echo "."
;;
restart)
echo -n "Restarting domain name service: named"
start-stop-daemon --stop --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
start-stop-daemon --start --verbose --exec /usr/sbin/named \
-- $PARAMS
echo "."
;;
force-reload|reload)
echo -n "Reloading configuration of domain name service: named"
start-stop-daemon --stop --signal 1 --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
echo "."
;;
*)
echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
exit 1
;;
esac
exit 0
Complementing the above init script is a configuration file
/etc/default/bind, which contains configurable parameters used by
the script. This would be created by the postinst script if it
was not already present, and removed on purge by the postrm
script.
# Specified parameters to pass to named. See named(8).
# You may uncomment the following line, and edit to taste.
#PARAMS="-u nobody"
Another example on which you can base your /etc/init.d scripts is found in /etc/init.d/skeleton.
If this package is happy with the default setup from update-rc.d,
namely an ordering number of 20 and having named running in all runlevels, it
can say in its postinst:
update-rc.d bind defaults >/dev/null
And in its postrm, to remove the links when the package is purged:
if [ "$1" = purge ]; then
update-rc.d bind remove >/dev/null
fi
This section describes the formats to be used for messages written to standard output by the /etc/init.d scripts. The intent is to improve the consistency of Debian's startup and shutdown look and feel. For this reason, please look very carefully at the details. We want the messages to have the same format in terms of wording, spaces, punctuation and case of letters.
Here is a list of overall rules that you should use when you create output messages. They can be useful if you have a non-standard message that is not covered specifically in the sections below.
I'm starting network daemons: nfsd mountd.
just say
Starting network daemons: nfsd mountd.
There are standard message formats for the following situations. They should be used by the init.d scripts.
If your script starts one or more daemons, the output should look like this (a single line, no leading spaces):
Starting description: daemon-1 ... daemon-n.
The description should describe the subsystem the daemon or set of daemons are part of, while daemon-1 up to daemon-n denote each daemon's name (typically the file name of the program).
For example, the output of /etc/init.d/lpd would look like:
Starting printer spooler: lpd.
This can be achieved by saying
echo -n "Starting printer spooler: lpd"
start-stop-daemon --start --quiet --exec /usr/sbin/lpd
echo "."
in the script. If you have more than one daemon to start, you should do the following:
echo -n "Starting remote file system services:"
echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
echo -n " mountd"; start-stop-daemon --start --quiet mountd
echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
echo "."
This makes it possible for the user to see what takes so long and when the final daemon has been started. You should be careful where to put spaces: in the example above the system administrator can easily comment out a line if he don't wants to start a specific daemon, while the displayed message still looks good.
If you have to set up different system parameters during the system boot, you should use this format:
Setting parameter to `value'.
You can use a statement such as the following to get the quotes right:
echo "Setting DNS domainname to \`$domainname'."
Note that the left quotation mark (`) is different from the right one (').
When you stop or restart a daemon, you should issue a message identical to the startup message, except that Starting is replaced with Stopping or Restarting respectively.
For example, stopping the printer daemon will like like this:
Stopping printer spooler: lpd.
There are several examples where you have to run a program at system startup or
shutdown to perform a specific task, for example, setting the system's clock
using netdate or killing all processes when the system shuts down.
Your message should look like this:
Doing something very useful...done.
You should print the done. immediately after the job has been completed, so that the user is informed why she has to wait. You can get this behavior by saying
echo -n "Doing something very useful..."
do_something
echo "done."
in your script.
When a daemon is forced to reload its configuration files you should use the following format:
Reloading description configuration...done.
where description is the same as in the daemon starting message.
Packages must not modify the configuration file /etc/crontab, and they must not modify the files in /var/spool/cron/crontabs.
If a package wants to install a job that has to be executed via cron, it should place a file with the name of the package in one or more of the following directories:
/etc/cron.daily
/etc/cron.weekly
/etc/cron.monthly
As these directory names imply, the files within them are executed on a daily, weekly, or monthly basis, respectively. The exact times are listed in /etc/crontab.
All files installed in any of these directories must be scripts (e.g., shell scripts or Perl scripts) so that they can easily be modified by the local system administrator. In addition, they should be treated as configuration files.
If a certain job has to be executed more frequently than daily, the package
should install a file /etc/cron.d/package. This file
uses the same syntax as /etc/crontab and is processed by
cron automatically. The file must also be treated as a
configuration file. (Note that entries in the /etc/cron.d
directory are not handled by anacron. Thus, you should only use
this directory for jobs which may be skipped if the system is not running.)
The scripts or crontab entries in these directories should check if all necessary programs are installed before they try to execute them. Otherwise, problems will arise when a package was removed but not purged since configuration files are kept on the system in this situation.
Menu entries should follow the current menu policy found in the
menu-policy files in the debian-policy package. It
may also be found on the Debian FTP site ftp.debian.org as the
file /debian/doc/package-developer/menu-policy.txt.gz,
or in the equivalent location on your local mirror.
The Debian menu package provides a standard interface between
packages providing applications and documents, and menu programs
(either X window managers or text-based menu programs such as
pdmenu).
All packages that provide applications that need not be passed any special command line arguments for normal operation should register a menu entry for those applications, so that users of the menu package will automatically get menu entries in their window managers, as well in shells like pdmenu.
Please also refer to the Debian Menu System documentation that comes with the menu package for information about how to register your applications and web documents.
Packages which provide the ability to view/show/play, compose, edit or print
MIME types should register themselves as such following the current MIME
support policy found in the mime-policy files in the
debian-policy package. It may also be found on the Debian FTP
site ftp.debian.org as the file /debian/doc/package-developer/mime-policy.txt.gz,
or in the equivalent location on your local mirror.
MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) is a mechanism for encoding files and data streams and providing meta-information about them, in particular their type (e.g. audio or video) and format (e.g. PNG, HTML, MP3).
Registration of MIME type handlers allows programs like mail user agents and web browsers to to invoke these handlers to view, edit or display MIME types they don't support directly.
To achieve a consistent keyboard configuration so that all applications interpret a keyboard event the same way, all programs in the Debian distribution must be configured to comply with the following guidelines.
The following keys must have the specified interpretations:
The interpretation of any keyboard events should be independent of the terminal that is used, be it a virtual console, an X terminal emulator, an rlogin/telnet session, etc.
The following list explains how the different programs should be set up to achieve this:
xrdb on all local X displays, not
using the application defaults, so that the translation resources used
correspond to the xmodmap settings.
This will solve the problem except for the following cases:
xmodmap to
arrange for both <-- and Delete to generate
KB_Delete. We can change the behavior of their X clients using
the same X resources that we use to do it for our own clients, or configure our
clients using their resources when things are the other way around. On
displays configured like this Delete will not work, but
<-- will.
A program must not depend on environment variables to get reasonable defaults. (That's because these environment variables would have to be set in a system-wide configuration file like /etc/profile, which is not supported by all shells.)
If a program usually depends on environment variables for its configuration, the program should be changed to fall back to a reasonable default configuration if these environment variables are not present. If this cannot be done easily (e.g., if the source code of a non-free program is not available), the program must be replaced by a small `wrapper' shell script which sets the environment variables if they are not already defined, and calls the original program.
Here is an example of a wrapper script for this purpose:
#!/bin/sh
BAR=${BAR:-/var/lib/fubar}
export BAR
exec /usr/lib/foo/foo "$@"
Furthermore, as /etc/profile is a configuration file of the
base-files package, other packages must not put any environment
variables or other commands into that file.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org