[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Ubuntu Policy Manual
Chapter 9 - The Operating System

9.1 File system hierarchy

9.1.1 File System Structure

The location of all installed files and directories must comply with the Filesystem Hierarchy Standard (FHS), version 2.3, with the exceptions noted below, and except where doing so would violate other terms of Ubuntu Policy. The following exceptions to the FHS apply:

  1. The optional rules related to user specific configuration files for applications are stored in the user's home directory are relaxed. It is recommended that such files start with the '.' character (a "dot file"), and if an application needs to create more than one dot file then the preferred placement is in a subdirectory with a name starting with a '.' character, (a "dot directory"). In this case it is recommended the configuration files not start with the '.' character.

  1. The requirement for amd64 to use /lib64 for 64 bit binaries is removed.

  1. The requirement that /usr/local/share/man be "synonymous" with /usr/local/man is relaxed to a recommendation

  1. The requirement that windowmanagers with a single configuration file call it system.*wmrc is removed, as is the restriction that the window manager subdirectory be named identically to the window manager name itself.

  1. The requirement that boot manager configuration files live in /etc, or at least are symlinked there, is relaxed to a recommendation.

The version of this document referred here can be found in the ubuntu-policy package or on FHS (Debian copy) alongside this manual (or, if you have the ubuntu-policy installed, you can try FHS (local copy)). 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 ubuntu-devel mailing list, or referred to the FHS mailing list (see the FHS web site for more information).

9.1.2 Site-specific programs

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 are not directories in /usr/local, but are children of directories in /usr/local. These directories (/usr/local/*/dir/) 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 ]
       if mkdir /usr/local/share/emacs 2>/dev/null
         chown root:staff /usr/local/share/emacs
         chmod 2775 /usr/local/share/emacs

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.

9.1.3 The system-wide mail directory

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.

9.2 Users and groups

9.2.1 Introduction

The Ubuntu 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 Ubuntu 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.

9.2.2 UID and GID classes

The UID and GID numbers are divided into classes as follows:


Globally allocated by the Debian project, the same on every Debian and Ubuntu system. These ids will appear in the passwd and group files of all Debian and Ubuntu systems, new ids in this range being added automatically as the base-passwd package is updated.

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.


Dynamically allocated system users and groups. Packages which need a user or group, but can have this user or group allocated dynamically and differently on each system, should use adduser --system to create the group and/or user. 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.


Dynamically allocated user accounts. By default adduser will choose UIDs and GIDs for user accounts in this range, though adduser.conf may be used to modify this behavior.




Globally allocated by the Debian project, but only created on demand. The ids are allocated centrally and statically, but the actual accounts are only created on users' systems on demand.

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.




User nobody. The corresponding gid refers to the group nogroup.


(uid_t)(-1) == (gid_t)(-1) must not be used, because it is the error return sentinel value.

9.3 System run levels and init.d scripts

9.3.1 Introduction

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 behaviors 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:


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.

9.3.2 Writing the scripts

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:


start the service,


stop the service,


stop and restart the service if it's already running, otherwise start the service


cause the configuration of the service to be reloaded without actually stopping and restarting the service,


cause the configuration to be reloaded if the service supports this, otherwise restart the service.

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 must ensure that they will behave sensibly (i.e., returning success and not starting multiple copies of a service) 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 with the --oknodo option.

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 10.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 their 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 behavior 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 SUSv3 sh format. It may either be a conffile or a configuration file maintained by the package maintainer scripts. See Configuration files, Section 10.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.

/var/run and /var/lock may be mounted as temporary filesystems[63], so the init.d scripts must handle this correctly. This will typically amount to creating any required subdirectories dynamically when the init.d script is run, rather than including them in the package and relying on dpkg to create them.

9.3.3 Interfacing with the initscript system

Maintainers should use the abstraction layer provided by the update-rc.d and invoke-rc.d programs to deal with initscripts in their packages' scripts such as postinst, prerm and postrm.

Directly managing the /etc/rc?.d links and directly invoking the /etc/init.d/ initscripts should be done only by packages providing the initscript subsystem (such as sysv-rc and file-rc). Managing the links

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

and in your postrm

     		if [ "$1" = purge ]; then
     		update-rc.d package remove

. Note that if your package changes runlevels or priority, you may have to remove and recreate the links, since otherwise the old links may persist. Refer to the documentation of update-rc.d.

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 ubuntu-devel, and they will help you choose a number.

For more information about using update-rc.d, please consult its man page update-rc.d(8). Running initscripts

The program invoke-rc.d is provided to make it easier for package maintainers to properly invoke an initscript, obeying runlevel and other locally-defined constraints that might limit a package's right to start, stop and otherwise manage services. This program may be used by maintainers in their packages' scripts.

The package maintainer scripts must use invoke-rc.d to invoke the /etc/init.d/* initscripts, instead of calling them directly.

By default, invoke-rc.d will pass any action requests (start, stop, reload, restart...) to the /etc/init.d script, filtering out requests to start or restart a service out of its intended runlevels.

Most packages will simply need to change:


in their postinst and prerm scripts to:

     	if which invoke-rc.d >/dev/null 2>&1; then
     		invoke-rc.d package <action>
     		/etc/init.d/package <action>

A package should register its initscript services using update-rc.d before it tries to invoke them using invoke-rc.d. Invocation of unregistered services may fail.

For more information about using invoke-rc.d, please consult its man page invoke-rc.d(8).

9.3.4 Boot-time initialization

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 9.3.1. Packages must not place files in /etc/rc.boot.

9.3.5 Example

An example on which you can base your /etc/init.d scripts is found in /etc/init.d/skeleton.

9.4 Console messages from init.d scripts

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 Ubuntu'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 should be used for messages generated by /etc/init.d scripts.

init.d script should use the following standard message formats for the situations enumerated below.

9.5 Cron jobs

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:


As these directory names imply, the files within them are executed on an hourly, 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 must be treated as configuration files.

If a certain job has to be executed at some other frequency or at a specific time, 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.

9.6 Menus

The Debian menu package provides a standard interface between packages providing applications 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.

Menu entries should follow the current menu policy.

The menu policy can be found in the menu-policy files in the debian-policy package. It is also available from the Debian web mirrors at /doc/packaging-manuals/menu-policy/.

Please also refer to the Debian Menu System documentation that comes with the menu package for information about how to register your applications.

9.7 Multimedia handlers

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 invoke these handlers to view, edit or display MIME types they don't support directly.

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.

The MIME support policy can be found in the mime-policy files in the debian-policy package. It is also available from the Debian web mirrors at /doc/packaging-manuals/mime-policy/.

9.8 Keyboard configuration

To achieve a consistent keyboard configuration so that all applications interpret a keyboard event the same way, all programs in the Ubuntu distribution must be configured to comply with the following guidelines.

The following keys must have the specified interpretations:


delete the character to the left of the cursor


delete the character to the right of the cursor


emacs: the help prefix

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:

This will solve the problem except for the following cases:

9.9 Environment variables

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:

     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.

9.10 Registering Documents using doc-base

The doc-base package implements a flexible mechanism for handling and presenting documentation. The recommended practice is for every Ubuntu package that provides online documentation (other than just manual pages) to register these documents with doc-base by installing a doc-base control file via the install-docs script at installation time and de-register the manuals again when the package is removed.

Please refer to the documentation that comes with the doc-base package for information and details.

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Ubuntu Policy Manual

version, 2009-06-19

The Debian Policy Mailing List
The Ubuntu Developers Mailing List