9.1.1.File System Structure

The location of all files and directories must comply with theFilesystem Hierarchy Standard (FHS), version 3.0, with the exceptionsnoted below, and except where doing so would violate other terms ofDebian Policy. The following exceptions to the FHS apply:

1. The FHS requirement that architecture-independentapplication-specific static files be located in/usr/share isrelaxed to a suggestion. In particular, a subdirectory of/usr/lib may be used by a package (or a collection of packages)to hold a mixture of architecture-independent andarchitecture-dependent files. However, when a directory is entirelycomposed of architecture-independent files, it should be located in/usr/share.

2. The optional rules related to user specific configuration files forapplications are stored in the user’s home directory are relaxed. Itis recommended that such files start with the ‘.’ character (a“dot file”), and if an application needs to create more than one dotfile then the preferred placement is in a subdirectory with a namestarting with a ‘.’ character, (a “dot directory”). In this case itis recommended the configuration files not start with the ‘.’character.

3. Only the dynamic linker and libc are allowed to install filesin/lib64.

4. The requirement for object files, internal binaries, and libraries,includinglibc.so.*, to be located directly under/lib{,32}and/usr/lib{,32} is amended, permitting files to instead beinstalled to/lib/triplet and/usr/lib/triplet, wheretriplet is the value returned bydpkg-architecture-qDEB_HOST_MULTIARCH for the architecture of thepackage. Packages must not install files to any triplet path otherthan the one matching the architecture of that package; forinstance, anArchitecture: amd64 package containing 32-bit x86libraries must not install these libraries to/usr/lib/i386-linux-gnu.[1]

   Packages for 64-bit architectures must not install files in/usr/lib64or in a subdirectory of it.

   The requirement for C and C++ headers files to be accessible throughthe search path/usr/include/ is amended, permitting files to beaccessible through the search path/usr/include/triplet wheretriplet is as above.[2]

   Applications may also use a single subdirectory under/usr/lib/triplet.

   The execution time linker/loader, ld*, must still be made availablein the existing location under /lib or /lib64 since this is part ofthe ELF ABI for the architecture.

5. The requirement that/usr/local/share/man be “synonymous” with/usr/local/man is relaxed to a recommendation

6. The requirement that window managers with a single configuration filecall itsystem.*wmrc is removed, as is the restriction that thewindow manager subdirectory be named identically to the windowmanager name itself.

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

8. /var/run is required to be a symbolic link to/run,and/var/lock is required to be a symbolic link to/run/lock.

9. The/var/www directory is additionally allowed.

10. The requirement for/usr/local/share/color to exist if/usr/share/color exists is relaxed to a recommendation.

11. The requirement for/usr/local/libqual to exist if/libqualor/usr/libqual exists (wherelibqual is a variant oflib such aslib32 orlib64) is removed.

12. On GNU/Hurd systems, the following additional directories areallowed in the root filesystem:/hurd and/servers.[3]

13. As an exception to the requirement for there to be no subdirectoriesin/usr/bin, themh mail-handling suite may create/usr/bin/mh/, as was allowed in FHS version 2.3. Othersubdirectories are not allowed.

The version of this document referred here can be found in thedebian-policy package or onFHS (Debiancopy) alongsidethis manual (or, if you have the debian-policy installed, you can tryFHS (local copy)). Thelatest version, which may be a more recent version, may be found onFHS(upstream). Specificquestions about following the standard may be asked on thedebian-devel mailing list, or referred to the FHS mailing list(see theFHS web sitefor 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 beunpacked bydpkg or by manipulating them in their maintainerscripts.

However, the package may create empty directories below/usr/localso that the system administrator knows where to place site-specificfiles. These are not directoriesin/usr/local, but are childrenof directories in/usr/local. These directories(/usr/local/*/dir/) should be removed on package removal if they areempty.

Note that this applies only to directoriesbelow/usr/local, notin/usr/local. Packages must not create sub-directories in thedirectory/usr/local itself, except those listed in FHS, section4.9. However, you may create directories below them as you wish. Youmust not remove any of the directories listed in 4.9, even if youcreated them.

If/etc/staff-group-for-usr-local does not exist,/usr/localand all subdirectories created by packages should have permissions0755 and be owned byroot:root. If/etc/staff-group-for-usr-local exists,/usr/local andsubdirectories should have permissions 2775 (group-writable andset-group-id) and be owned byroot:staff.

Since/usr/local can be mounted read-only from a remote server,/usr/local/*/dir/ directories must be created and removed by thepostinst andprerm maintainer scripts and not be included inthe.deb archive. These scripts must not fail if either of theseoperations fail.

For example, theemacsen-common package could contain something like

if [ ! -e /usr/local/share/emacs ]; then    if mkdir /usr/local/share/emacs 2>/dev/null; then        if test -e /etc/staff-group-for-usr-local ; then            if chown root:staff /usr/local/share/emacs; then                chmod 2775 /usr/local/share/emacs || true            fi        elif chown root:root /usr/local/share/emacs; then            chmod 0755 /usr/local/share/emacs || true        fi    fifi

in itspostinst script, and

rmdir/usr/local/share/emacs/site-lisp2>/dev/null||truermdir/usr/local/share/emacs2>/dev/null||true

in theprerm script. (Note that this form is used to ensure that ifthe script is interrupted, the directory/usr/local/share/emacs willstill be removed.)

If you do create a directory in/usr/local for local additions to apackage, you should ensure that settings in/usr/local takeprecedence over the equivalents in/usr.

However, because/usr/local and its contents are for exclusive useof the local administrator, a package must not rely on the presence orabsence of files or directories in/usr/local for normal operation.

9.1.3.The system-wide mail directory

The system-wide mail directory is/var/mail. This directory is partof the base system and should not be owned by any particular mailagents. The use of the old location/var/spool/mail is deprecated,even though the spool may still be physically located there.

9.1.4./run and/run/lock

The directory/run is cleared at boot, normally by being a mountpoint for a temporary file system. Packages therefore must not assumethat any files or directories under/run other than/run/lockexist unless the package has arranged to create those files ordirectories since the last reboot. Normally, this is done by the packagevia an init script. SeeWriting the scripts for moreinformation.

Packages must not include files or directories under/run, or underthe older/var/run and/var/lock paths. The latter paths willnormally be symlinks or other redirections to/run for backwardscompatibility.

9.2.1.Introduction

The Debian system can be configured to use either plain or shadowpasswords.

Some user ids (UIDs) and group ids (GIDs) are reserved globally for useby certain packages. Because some packages need to include files whichare owned by these users or groups, or need the ids compiled intobinaries, these ids must be used on any Debian system only for thepurpose for which they are allocated. This is a serious restriction, andwe should avoid getting in the way of local administration policies. Inparticular, many sites allocate users and/or local system groupsstarting at 100.

Apart from this we should have dynamically allocated ids, which shouldby default be arranged in some sensible order, but the behavior shouldbe configurable. When maintainers choose a new hardcoded or dynamicallygenerated username for packages to use, they should start this usernamewith an underscore. This minimizes collisions with locally created useraccounts.

Packages other thanbase-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:

0-99:

Globally allocated by the Debian project, the same on every Debiansystem. These ids will appear in thepasswd andgroup filesof all Debian systems, new ids in this range being addedautomatically as thebase-passwd package is updated.

Packages which need a single statically allocated uid or gid shoulduse one of these; their maintainers should ask thebase-passwdmaintainer for ids.

100-999:

Dynamically allocated system users and groups. Packages which need auser or group, but can have this user or group allocated dynamicallyand differently on each system, should useadduser--system tocreate the group and/or user.adduser will check for theexistence of the user or group, and if necessary choose an unused idbased on the ranges specified inadduser.conf.

1000-59999:

Dynamically allocated user accounts. By defaultadduser willchoose UIDs and GIDs for user accounts in this range, thoughadduser.conf may be used to modify this behavior.

60000-64999:

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

These ids are for packages which are obscure or which require manystatically-allocated ids. These packages should check for and createthe accounts in/etc/passwd or/etc/group (usingadduserif it has this facility) if necessary. Packages which are likely torequire further allocations should have a “hole” left after them inthe allocation, to give them room to grow.

65000-65533:

Reserved.

65534:

Usernobody. The corresponding gid refers to the groupnogroup.

65535:

This valuemust not be used, because it was the error returnsentinel value whenuid_t was 16 bits.

65536-4294967293:

Dynamically allocated user accounts. By defaultadduser will notallocate UIDs and GIDs in this range, to ease compatibility withlegacy systems whereuid_t is still 16 bits.

4294967294:

(uid_t)(-2)==(gid_t)(-2)must not be used, because it isused as the anonymous, unauthenticated user by some NFSimplementations.

4294967295:

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

9.2.3.Non-existent home directories

The canonical non-existent home directory is/nonexistent. Userswho should not have a home directory should have their home directoryset to this value.

The Debian autobuilders set HOME to/nonexistent so that packageswhich try to write to a home directory will fail to build.

9.3.1.Introduction

The default init system and service manager in Debian issystemd.Packages that wish to automatically start and stop system services mustincludesystemd service units to do so, unless the service is onlyintended for use on systems running alternate init systems. Seesystemd.service(5) for details on the syntax of a service unitfile.

In the common case that a package includes a single system service, theservice unit should have the same name as the package plus the.service extension.

Packages including a service unit may optionally include an init script tosupport other init systems. In this case, the init script should have thesame name as thesystemd service unit so thatsystemd will ignoreit and use the service unit instead. Packages may also support other initsystems by including configuration in the native format of those initsystems.

systemd uses dependency and ordering information contained within theenabled unit files to decide which services to run and in which order.Thesysv-rc runlevel system forsysvinit uses symlinks in/etc/rcn.d to decide which scripts to run and in which order at boottime and when the init state (or “runlevel”) is changed. See theREADME.runlevels file shipped withsysv-rc for implementationdetails. Other alternatives might exist.

The sections below describe how to write those scripts and configure thosesymlinks.

9.3.2.Writing the scripts

Init scripts are placed in/etc/init.d. In the common case that apackage starts a single service, they should be named/etc/init.d/package. They should accept one argument, saying what todo:

start

start the service,

stop

stop the service,

restart

stop and restart the service if it’s already running, otherwisestart the service

try-restart

restart the service if it’s already running, otherwise just reportsuccess.

reload

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

force-reload

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

status

report the current status of the service

Thestart,stop,restart, andforce-reload options shouldbe supported by all init scripts. Supportingstatus is encouraged.Thereload andtry-restart options are optional.

Theinit.d scripts must ensure that they will behave sensibly (i.e.,returning success and not starting multiple copies of a service) ifinvoked withstart when the service is already running, or withstop when it isn’t, and that they don’t kill unfortunately-nameduser processes. The best way to achieve this is usually to usestart-stop-daemon with the--oknodo option.

Be careful of usingset-e ininit.d scripts. Writing correctinit.d scripts requires accepting various error exit statuses whendaemons are already running or already stopped without aborting theinit.d script, and commoninit.d function libraries are not safeto call withset-e in effect.[4] Forinit.d scripts, it’soften easier to not useset-e and instead check the result of eachcommand separately.

If a service reloads its configuration automatically (as in the case ofcron, for example), thereload option of theinit.d scriptshould 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 asconffiles, or, (if they do not exist in the.deb) by managing them correctly in the maintainer scripts (seeConfiguration files). This is important since we wantto give the local system administrator the chance to adapt the scriptsto the local system, e.g., to disable a service without de-installingthe package, or to specify some special command line options whenstarting a service, while making sure their changes aren’t lost duringthe next package upgrade.

These scripts should not fail obscurely when the configuration filesremain but the package has been removed, as configuration files remainon the system after the package has been removed. Only whendpkg isexecuted with the--purge option will configuration files beremoved. In particular, as the/etc/init.d/package script itself isusually aconffile, it will remain on the system if the package isremoved but not purged. Therefore, you should include ateststatement at the top of the script, like this:

test-fprogram-executed-later-in-script||exit0

Often there are some variables in theinit.d scripts whose valuescontrol the behavior of the scripts, and which a system administrator islikely to want to change. As the scripts themselves are frequentlyconffiles, modifying them requires that the administrator merge intheir changes each time the package is upgraded and theconffilechanges. To ease the burden on the system administrator, suchconfigurable values should not be placed directly in the script.Instead, they should be placed in a file in/etc/default, whichtypically will have the same base name as theinit.d script. Thisextra file should be sourced by the script when the script runs. It mustcontain only variable settings and comments in POSIX.1-2017sh format. Itmust either be aconffile or a configuration file maintained by thepackage maintainer scripts. SeeConfiguration files formore details.

To ensure that vital configurable values are always available, theinit.d script should set default values for each of the shellvariables it uses, either before sourcing the/etc/default/ file orafterwards using something like the:${VAR:=default} syntax. Also,theinit.d script must behave sensibly and not fail if the/etc/default file is deleted.

Files and directories under/run, including ones referred to via thecompatibility paths/var/run and/var/lock, are normally storedon a temporary filesystem and are normally not persistent across areboot. Theinit.d scripts must handle this correctly. This willtypically mean creating any required subdirectories dynamically when theinit.d script is run. See/run and /run/lock for moreinformation.

9.3.3.Interfacing with init systems

Maintainer scripts for packages including init scripts must useupdate-rc.d as described below to interact with the service managerfor requests such as enabling or disabling services. They should useinvoke-rc.d as described below to invoke init scripts for requestssuch as starting and stopping service.

Directly managing the/etc/rc?.d links and directly invoking the/etc/init.d/ init scripts should be done only by packages providingthe init script subsystem (such asinit-system-helpers).

update-rc.dpackagedefaults

if["$1"=purge];thenupdate-rc.dpackageremovefi

update-rc.dpackagedefaults-disabled

invoke-rc.dpackageaction

9.3.4.Boot-time initialization

This section has been deleted.

9.3.5.Example

Examples on which you can base yoursystemd service units areavailable in the man pagesystemd.unit(5). An example on whichyou can base your init scripts is available in the man pageinit-d-script(5).

9.5.1.Cron job file names

The file name of a cron job file should normally match the name of thepackage from which it comes.

If a package supplies multiple cron job files files in the samedirectory, the file names should all start with the name of the package(possibly modified as described below) followed by a hyphen (-) anda suitable suffix.

A cron job file name must not include any period or plus characters(. or+) characters as this will cause cron to ignore the file.Underscores (_) should be used instead of. and+characters.

9.7.1.Registration of media type handlers with desktop entries

Packages shipping an application able to view, edit or point to files ofa given media type, or open links with a given URI scheme, should listit in theMimeType key of the application’sdesktopentry. For URI schemes, the relevant MIME types arex-scheme-handler/* (e.g.x-scheme-handler/https).

9.7.2.Registration of media type handlers with mailcap entries

Packages that are not using desktop entries for registration shouldinstall a file inmailcap(5) format (RFC 1524) in the directory/usr/lib/mime/packages/. The file name should be the binary package’sname.

The mailcap package provides theupdate-mime program, whichintegrates these registrations in the/etc/mailcap file, using dpkgtriggers.[5]

Packages installing desktop entries should not install mailcap entriesfor the same program, because the mailcap package already readsdesktop entries.

Packages using these facilitiesshould not depend on, recommend, orsuggestmailcap.

9.7.3.Providing media types to files

The media type of a file is discovered by inspecting the file’s extensionor itsmagic(5) pattern, and interrogating a databaseassociating them with media types.

To support new associations between media types and files, theircharacteristic file extensions and magic patterns should be registeredto the IANA (Internet Assigned Numbers Authority). Seehttps://www.iana.org/assignments/media-types and RFC 6838 for details.This information will then propagate to the systems discovering filemedia types in Debian, provided by the shared-mime-info, media-typesand file packages. If registration and propagation can not be waitedfor, support can be asked to the maintainers of the packages mentionedabove.

For files that are produced and read by a single application, it is alsopossible to declare this association to theShared MIME Info system byinstalling in the directory/usr/share/mime/packages a file in theXML format specified athttps://standards.freedesktop.org/shared-mime-info-spec/latest/.

9.11.1.Event-based boot with upstart

Theupstart event-based boot system is no longer maintained inDebian, so this section has been removed.

This is necessary in order to reserve the directories for use incross-installation of library packages from other architectures, aspart ofmultiarch.

This is necessary for architecture-dependent headers file to coexistin amultiarch setup.

These directories are used to store translators and as a set ofstandard names for mount points, respectively.

/lib/lsb/init-functions, which assists in writing LSB-compliantinit scripts, may fail ifset-e is in effect and echoing status messages to theconsole fails, for example.

Creating, modifying or removing a file in/usr/lib/mime/packages/ using maintainer scripts will notactivate the trigger. In that case, it can be done by callingdpkg-trigger--no-await/usr/lib/mime/packages from themaintainer script after creating, modifying, or removing the file.