14 The location of all files and directories must comply with the
15 Filesystem Hierarchy Standard (FHS), version 2.3, with the exceptions
16 noted below, and except where doing so would violate other terms of
17 Debian Policy. The following exceptions to the FHS apply:
19 1. The FHS requirement that architecture-independent
20 application-specific static files be located in ``/usr/share`` is
21 relaxed to a suggestion. In particular, a subdirectory of
22 ``/usr/lib`` may be used by a package (or a collection of packages)
23 to hold a mixture of architecture-independent and
24 architecture-dependent files. However, when a directory is entirely
25 composed of architecture-independent files, it should be located in
28 2. The optional rules related to user specific configuration files for
29 applications are stored in the user's home directory are relaxed. It
30 is recommended that such files start with the '``.``' character (a
31 "dot file"), and if an application needs to create more than one dot
32 file then the preferred placement is in a subdirectory with a name
33 starting with a '.' character, (a "dot directory"). In this case it
34 is recommended the configuration files not start with the '.'
37 3. The requirement for amd64 to use ``/lib64`` for 64 bit binaries is
38 removed. Only the dynamic linker is allowed to use this directory.
40 4. The requirement for object files, internal binaries, and libraries,
41 including ``libc.so.*``, to be located directly under ``/lib{,32}``
42 and ``/usr/lib{,32}`` is amended, permitting files to instead be
43 installed to ``/lib/triplet`` and ``/usr/lib/triplet``, where
44 ``triplet`` is the value returned by ``dpkg-architecture -qDEB_HOST_MULTIARCH`` for the architecture of the
45 package. Packages may *not* install files to any triplet path other
46 than the one matching the architecture of that package; for
47 instance, an ``Architecture: amd64`` package containing 32-bit x86
48 libraries may not install these libraries to
49 ``/usr/lib/i386-linux-gnu``. [#]_
51 No package for a 64 bit architecture may install files in
52 ``/usr/lib64/`` or in a subdirectory of it.
54 The requirement for C and C++ headers files to be accessible through
55 the search path ``/usr/include/`` is amended, permitting files to be
56 accessible through the search path ``/usr/include/triplet`` where
57 ``triplet`` is as above. [#]_
59 Applications may also use a single subdirectory under
62 The execution time linker/loader, ld\*, must still be made available
63 in the existing location under /lib or /lib64 since this is part of
64 the ELF ABI for the architecture.
66 5. The requirement that ``/usr/local/share/man`` be "synonymous" with
67 ``/usr/local/man`` is relaxed to a recommendation
69 6. The requirement that windowmanagers with a single configuration file
70 call it ``system.*wmrc`` is removed, as is the restriction that the
71 window manager subdirectory be named identically to the window
74 7. The requirement that boot manager configuration files live in
75 ``/etc``, or at least are symlinked there, is relaxed to a
78 8. The additional directory ``/run`` in the root file system is
79 allowed. ``/run`` replaces ``/var/run``, and the subdirectory
80 ``/run/lock`` replaces ``/var/lock``, with the ``/var`` directories
81 replaced by symlinks for backwards compatibility. ``/run`` and
82 ``/run/lock`` must follow all of the requirements in the FHS for
83 ``/var/run`` and ``/var/lock``, respectively, such as file naming
84 conventions, file format requirements, or the requirement that files
85 be cleared during the boot process. Files and directories residing
86 in ``/run`` should be stored on a temporary file system.
88 9. The ``/sys`` directory in the root filesystem is additionally
91 10. The ``/var/www`` directory is additionally allowed.
93 11. The requirement for ``/usr/local/libqual`` to exist if ``/libqual``
94 or ``/usr/libqual`` exists (where ``libqual`` is a variant of
95 ``lib`` such as ``lib32`` or ``lib64``) is removed.
97 12. On GNU/Hurd systems, the following additional directories are
98 allowed in the root filesystem: ``/hurd`` and ``/servers``. [#]_
100 The version of this document referred here can be found in the
101 ``debian-policy`` package or on `FHS (Debian
102 copy) <https://www.debian.org/doc/packaging-manuals/fhs/>`_ alongside
103 this manual (or, if you have the debian-policy installed, you can try
104 `FHS (local copy) <file:///usr/share/doc/debian-policy/fhs/>`_). The
105 latest version, which may be a more recent version, may be found on `FHS
106 (upstream) <http://www.pathname.com/fhs/>`_. Specific questions about
107 following the standard may be asked on the ``debian-devel`` mailing
108 list, or referred to the FHS mailing list (see the `FHS web
109 site <http://www.pathname.com/fhs/>`_ for more information).
113 Site-specific programs
114 ~~~~~~~~~~~~~~~~~~~~~~
116 As mandated by the FHS, packages must not place any files in
117 ``/usr/local``, either by putting them in the file system archive to be
118 unpacked by ``dpkg`` or by manipulating them in their maintainer
121 However, the package may create empty directories below ``/usr/local``
122 so that the system administrator knows where to place site-specific
123 files. These are not directories *in* ``/usr/local``, but are children
124 of directories in ``/usr/local``. These directories
125 (``/usr/local/*/dir/``) should be removed on package removal if they are
128 Note that this applies only to directories *below* ``/usr/local``, not
129 *in* ``/usr/local``. Packages must not create sub-directories in the
130 directory ``/usr/local`` itself, except those listed in FHS, section
131 4.5. However, you may create directories below them as you wish. You
132 must not remove any of the directories listed in 4.5, even if you
135 Since ``/usr/local`` can be mounted read-only from a remote server,
136 these directories must be created and removed by the ``postinst`` and
137 ``prerm`` maintainer scripts and not be included in the ``.deb``
138 archive. These scripts must not fail if either of these operations fail.
140 For example, the ``emacsen-common`` package could contain something like
144 if [ ! -e /usr/local/share/ema.. [#]; then
145 if mkdir /usr/local/share/emacs 2>/dev/null; then
146 if chown root:staff /usr/local/share/emacs; then
147 chmod 2775 /usr/local/share/emacs || true
152 in its ``postinst`` script, and
156 rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
157 rmdir /usr/local/share/emacs 2>/dev/null || true
159 in the ``prerm`` script. (Note that this form is used to ensure that if
160 the script is interrupted, the directory ``/usr/local/share/emacs`` will
163 If you do create a directory in ``/usr/local`` for local additions to a
164 package, you should ensure that settings in ``/usr/local`` take
165 precedence over the equivalents in ``/usr``.
167 However, because ``/usr/local`` and its contents are for exclusive use
168 of the local administrator, a package must not rely on the presence or
169 absence of files or directories in ``/usr/local`` for normal operation.
171 The ``/usr/local`` directory itself and all the subdirectories created
172 by the package should (by default) have permissions 2775 (group-writable
173 and set-group-id) and be owned by ``root:staff``.
177 The system-wide mail directory
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180 The system-wide mail directory is ``/var/mail``. This directory is part
181 of the base system and should not be owned by any particular mail
182 agents. The use of the old location ``/var/spool/mail`` is deprecated,
183 even though the spool may still be physically located there.
187 ``/run`` and ``/run/lock``
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~
190 The directory ``/run`` is cleared at boot, normally by being a mount
191 point for a temporary file system. Packages therefore must not assume
192 that any files or directories under ``/run`` other than ``/run/lock``
193 exist unless the package has arranged to create those files or
194 directories since the last reboot. Normally, this is done by the package
195 via an init script. See :ref:`s-writing-init` for more
198 Packages must not include files or directories under ``/run``, or under
199 the older ``/var/run`` and ``/var/lock`` paths. The latter paths will
200 normally be symlinks or other redirections to ``/run`` for backwards
213 The Debian system can be configured to use either plain or shadow
216 Some user ids (UIDs) and group ids (GIDs) are reserved globally for use
217 by certain packages. Because some packages need to include files which
218 are owned by these users or groups, or need the ids compiled into
219 binaries, these ids must be used on any Debian system only for the
220 purpose for which they are allocated. This is a serious restriction, and
221 we should avoid getting in the way of local administration policies. In
222 particular, many sites allocate users and/or local system groups
225 Apart from this we should have dynamically allocated ids, which should
226 by default be arranged in some sensible order, but the behavior should
229 Packages other than ``base-passwd`` must not modify ``/etc/passwd``,
230 ``/etc/shadow``, ``/etc/group`` or ``/etc/gshadow``.
237 The UID and GID numbers are divided into classes as follows:
240 Globally allocated by the Debian project, the same on every Debian
241 system. These ids will appear in the ``passwd`` and ``group`` files
242 of all Debian systems, new ids in this range being added
243 automatically as the ``base-passwd`` package is updated.
245 Packages which need a single statically allocated uid or gid should
246 use one of these; their maintainers should ask the ``base-passwd``
250 Dynamically allocated system users and groups. Packages which need a
251 user or group, but can have this user or group allocated dynamically
252 and differently on each system, should use ``adduser --system`` to
253 create the group and/or user. ``adduser`` will check for the
254 existence of the user or group, and if necessary choose an unused id
255 based on the ranges specified in ``adduser.conf``.
258 Dynamically allocated user accounts. By default ``adduser`` will
259 choose UIDs and GIDs for user accounts in this range, though
260 ``adduser.conf`` may be used to modify this behavior.
263 Globally allocated by the Debian project, but only created on
264 demand. The ids are allocated centrally and statically, but the
265 actual accounts are only created on users' systems on demand.
267 These ids are for packages which are obscure or which require many
268 statically-allocated ids. These packages should check for and create
269 the accounts in ``/etc/passwd`` or ``/etc/group`` (using ``adduser``
270 if it has this facility) if necessary. Packages which are likely to
271 require further allocations should have a "hole" left after them in
272 the allocation, to give them room to grow.
278 User ``nobody``. The corresponding gid refers to the group
282 This value *must not* be used, because it was the error return
283 sentinel value when ``uid_t`` was 16 bits.
286 Dynamically allocated user accounts. By default ``adduser`` will not
287 allocate UIDs and GIDs in this range, to ease compatibility with
288 legacy systems where ``uid_t`` is still 16 bits.
291 ``(uid_t)(-2) == (gid_t)(-2)`` *must not* be used, because it is
292 used as the anonymous, unauthenticated user by some NFS
296 ``(uid_t)(-1) == (gid_t)(-1)`` *must not* be used, because it is the
297 error return sentinel value.
301 Non-existent home directories
302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
304 The canonical non-existent home directory is ``/nonexistent``. Users
305 who should not have a home directory should have their home directory
308 The Debian autobuilders set HOME to ``/nonexistent`` so that packages
309 which try to write to a home directory will fail to build.
313 System run levels and ``init.d`` scripts
314 ----------------------------------------
321 The ``/etc/init.d`` directory contains the scripts executed by ``init``
322 at boot time and when the init state (or "runlevel") is changed (see
325 There are at least two different, yet functionally equivalent, ways of
326 handling these scripts. For the sake of simplicity, this document
327 describes only the symbolic link method. However, it must not be assumed
328 by maintainer scripts that this method is being used, and any automated
329 manipulation of the various runlevel behaviors by maintainer scripts
330 must be performed using ``update-rc.d`` as described below and not by
331 manually installing or removing symlinks. For information on the
332 implementation details of the other method, implemented in the
333 ``file-rc`` package, please refer to the documentation of that package.
335 These scripts are referenced by symbolic links in the ``/etc/rcn.d``
336 directories. When changing runlevels, ``init`` looks in the directory
337 ``/etc/rcn.d`` for the scripts it should execute, where ``n`` is the
338 runlevel that is being changed to, or ``S`` for the boot-up scripts.
340 The names of the links all have the form ``Smmscript`` or ``Kmmscript``
341 where mm is a two-digit number and script is the name of the script
342 (this should be the same as the name of the actual script in
345 When ``init`` changes runlevel first the targets of the links whose
346 names start with a ``K`` are executed, each with the single argument
347 ``stop``, followed by the scripts prefixed with an ``S``, each with the
348 single argument ``start``. (The links are those in the ``/etc/rcn.d``
349 directory corresponding to the new runlevel.) The ``K`` links are
350 responsible for killing services and the ``S`` link for starting
351 services upon entering the runlevel.
353 For example, if we are changing from runlevel 2 to runlevel 3, init will
354 first execute all of the ``K`` prefixed scripts it finds in
355 ``/etc/rc3.d``, and then all of the ``S`` prefixed scripts in that
356 directory. The links starting with ``K`` will cause the referred-to file
357 to be executed with an argument of ``stop``, and the ``S`` links with an
358 argument of ``start``.
360 The two-digit number mm is used to determine the order in which to run
361 the scripts: low-numbered links have their scripts run first. For
362 example, the ``K20`` scripts will be executed before the ``K30``
363 scripts. This is used when a certain service must be started before
364 another. For example, the name server ``bind`` might need to be started
365 before the news server ``inn`` so that ``inn`` can set up its access
366 lists. In this case, the script that starts ``bind`` would have a lower
367 number than the script that starts ``inn`` so that it runs first:
374 The two runlevels 0 (halt) and 6 (reboot) are slightly different. In
375 these runlevels, the links with an ``S`` prefix are still called after
376 those with a ``K`` prefix, but they too are called with the single
384 Packages that include daemons for system services should place scripts
385 in ``/etc/init.d`` to start or stop services at boot time or during a
386 change of runlevel. These scripts should be named
387 ``/etc/init.d/package``, and they should accept one argument, saying
397 stop and restart the service if it's already running, otherwise
401 restart the service if it's already running, otherwise just report
405 cause the configuration of the service to be reloaded without
406 actually stopping and restarting the service,
409 cause the configuration to be reloaded if the service supports this,
410 otherwise restart the service.
413 report the current status of the service
415 The ``start``, ``stop``, ``restart``, and ``force-reload`` options
416 should be supported by all scripts in ``/etc/init.d``. Supporting
417 ``status`` is recommended but not required. The ``reload`` and
418 ``try-restart`` options are optional.
420 The ``init.d`` scripts must ensure that they will behave sensibly (i.e.,
421 returning success and not starting multiple copies of a service) if
422 invoked with ``start`` when the service is already running, or with
423 ``stop`` when it isn't, and that they don't kill unfortunately-named
424 user processes. The best way to achieve this is usually to use
425 ``start-stop-daemon`` with the ``--oknodo`` option.
427 Be careful of using ``set -e`` in ``init.d`` scripts. Writing correct
428 ``init.d`` scripts requires accepting various error exit statuses when
429 daemons are already running or already stopped without aborting the
430 ``init.d`` script, and common ``init.d`` function libraries are not safe
431 to call with ``set -e`` in effect. [#]_ For ``init.d`` scripts, it's
432 often easier to not use ``set -e`` and instead check the result of each
435 If a service reloads its configuration automatically (as in the case of
436 ``cron``, for example), the ``reload`` option of the ``init.d`` script
437 should behave as if the configuration has been reloaded successfully.
439 The ``/etc/init.d`` scripts must be treated as configuration files,
440 either (if they are present in the package, that is, in the .deb file)
441 by marking them as ``conffile``\ s, or, (if they do not exist in the
442 .deb) by managing them correctly in the maintainer scripts (see
443 :ref:`s-config-files`). This is important since we want
444 to give the local system administrator the chance to adapt the scripts
445 to the local system, e.g., to disable a service without de-installing
446 the package, or to specify some special command line options when
447 starting a service, while making sure their changes aren't lost during
448 the next package upgrade.
450 These scripts should not fail obscurely when the configuration files
451 remain but the package has been removed, as configuration files remain
452 on the system after the package has been removed. Only when ``dpkg`` is
453 executed with the ``--purge`` option will configuration files be
454 removed. In particular, as the ``/etc/init.d/package`` script itself is
455 usually a ``conffile``, it will remain on the system if the package is
456 removed but not purged. Therefore, you should include a ``test``
457 statement at the top of the script, like this:
461 test -f program-executed-later-in-script || exit 0
463 Often there are some variables in the ``init.d`` scripts whose values
464 control the behavior of the scripts, and which a system administrator is
465 likely to want to change. As the scripts themselves are frequently
466 ``conffile``\ s, modifying them requires that the administrator merge in
467 their changes each time the package is upgraded and the ``conffile``
468 changes. To ease the burden on the system administrator, such
469 configurable values should not be placed directly in the script.
470 Instead, they should be placed in a file in ``/etc/default``, which
471 typically will have the same base name as the ``init.d`` script. This
472 extra file should be sourced by the script when the script runs. It must
473 contain only variable settings and comments in SUSv3 ``sh`` format. It
474 may either be a ``conffile`` or a configuration file maintained by the
475 package maintainer scripts. See :ref:`s-config-files` for
478 To ensure that vital configurable values are always available, the
479 ``init.d`` script should set default values for each of the shell
480 variables it uses, either before sourcing the ``/etc/default/`` file or
481 afterwards using something like the ``: ${VAR:=default}`` syntax. Also,
482 the ``init.d`` script must behave sensibly and not fail if the
483 ``/etc/default`` file is deleted.
485 Files and directories under ``/run``, including ones referred to via the
486 compatibility paths ``/var/run`` and ``/var/lock``, are normally stored
487 on a temporary filesystem and are normally not persistent across a
488 reboot. The ``init.d`` scripts must handle this correctly. This will
489 typically mean creating any required subdirectories dynamically when the
490 ``init.d`` script is run. See :ref:`s-fhs-run` for more
495 Interfacing with init systems
496 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498 Maintainers should use the abstraction layer provided by the
499 ``update-rc.d`` and ``invoke-rc.d`` programs to deal with initscripts in
500 their packages' scripts such as ``postinst``, ``prerm`` and ``postrm``.
502 Directly managing the /etc/rc?.d links and directly invoking the
503 ``/etc/init.d/`` initscripts should be done only by packages providing
504 the initscript subsystem (such as ``sysv-rc`` and ``file-rc``).
511 The program ``update-rc.d`` is provided for package maintainers to
512 arrange for the proper creation and removal of ``/etc/rcn.d`` symbolic
513 links, or their functional equivalent if another method is being used.
514 This may be used by maintainers in their packages' ``postinst`` and
517 You must not include any ``/etc/rcn.d`` symbolic links in the actual
518 archive or manually create or remove the symbolic links in maintainer
519 scripts; you must use the ``update-rc.d`` program instead. (The former
520 will fail if an alternative method of maintaining runlevel information
521 is being used.) You must not include the ``/etc/rcn.d`` directories
522 themselves in the archive either. (Only the ``sysvinit`` package may do
525 To get the default behavior for your package, put in your ``postinst``
530 update-rc.d package defaults
532 and in your ``postrm``
536 if [ "$1" = pur.. [#]; then
537 update-rc.d package remove
540 Note that if your package changes runlevels or priority, you may have to
541 remove and recreate the links, since otherwise the old links may
542 persist. Refer to the documentation of ``update-rc.d``.
544 For more information about using ``update-rc.d``, please consult its man
545 page, update-rc.d(8).
547 It is easiest for packages not to call ``update-rc.d`` directly, but
548 instead use debhelper programs that add the required ``update-rc.d``
549 calls automatically. See ``dh_installinit``, ``dh_systemd_enable``, etc.
556 The program ``invoke-rc.d`` is provided to make it easier for package
557 maintainers to properly invoke an initscript, obeying runlevel and other
558 locally-defined constraints that might limit a package's right to start,
559 stop and otherwise manage services. This program may be used by
560 maintainers in their packages' scripts.
562 The package maintainer scripts must use ``invoke-rc.d`` to invoke the
563 ``/etc/init.d/*`` initscripts or equivalent, instead of calling them
566 By default, ``invoke-rc.d`` will pass any action requests (start, stop,
567 reload, restart...) to the ``/etc/init.d`` script, filtering out
568 requests to start or restart a service out of its intended runlevels.
570 Most packages will simply use:
574 invoke-rc.d package action
576 in their ``postinst`` and ``prerm`` scripts.
578 A package should register its initscript services using ``update-rc.d``
579 before it tries to invoke them using ``invoke-rc.d``. Invocation of
580 unregistered services may fail.
582 For more information about using ``invoke-rc.d``, please consult its man
583 page, invoke-rc.d(8).
585 It is easiest for packages not to call ``invoke-rc.d`` directly, but
586 instead use debhelper programs that add the required ``invoke-rc.d``
587 calls automatically. See ``dh_installinit``, ``dh_systemd_start``, etc.
591 Boot-time initialization
592 ~~~~~~~~~~~~~~~~~~~~~~~~
594 This section has been deleted.
601 Examples on which you can base your systemd integration on is available in
602 the man page systemd.unit(8). An example on which you can base your
603 ``/etc/init.d`` scripts is found in ``/etc/init.d/skeleton``.
607 Console messages from ``init.d`` scripts
608 ----------------------------------------
610 This section has been deleted.
617 Packages must not modify the configuration file ``/etc/crontab``, and
618 they must not modify the files in ``/var/spool/cron/crontabs``.
620 If a package wants to install a job that has to be executed via cron, it
621 should place a file named as specified in
622 :ref:`s-cron-files` into one or more of the following
625 - ``/etc/cron.hourly``
627 - ``/etc/cron.daily``
629 - ``/etc/cron.weekly``
631 - ``/etc/cron.monthly``
633 As these directory names imply, the files within them are executed on an
634 hourly, daily, weekly, or monthly basis, respectively. The exact times
635 are listed in ``/etc/crontab``.
637 All files installed in any of these directories must be scripts (e.g.,
638 shell scripts or Perl scripts) so that they can easily be modified by
639 the local system administrator. In addition, they must be treated as
642 If a certain job has to be executed at some other frequency or at a
643 specific time, the package should install a file in ``/etc/cron.d`` with
644 a name as specified in :ref:`s-cron-files`. This file
645 uses the same syntax as ``/etc/crontab`` and is processed by ``cron``
646 automatically. The file must also be treated as a configuration file.
647 (Note that entries in the ``/etc/cron.d`` directory are not handled by
648 ``anacron``. Thus, you should only use this directory for jobs which may
649 be skipped if the system is not running.)
651 Unlike ``crontab`` files described in the IEEE Std 1003.1-2008 (POSIX.1)
652 available from `The Open
653 Group <https://www.opengroup.org/onlinepubs/9699919799/>`_, the files
654 in ``/etc/cron.d`` and the file ``/etc/crontab`` have seven fields;
661 3. Day of the month [1,31]
663 4. Month of the year [1,12]
665 5. Day of the week ([0,6] with 0=Sunday)
671 Ranges of numbers are allowed. Ranges are two numbers separated with a
672 hyphen. The specified range is inclusive. Lists are allowed. A list is a
673 set of numbers (or ranges) separated by commas. Step values can be used
674 in conjunction with ranges.
676 The scripts or ``crontab`` entries in these directories should check if
677 all necessary programs are installed before they try to execute them.
678 Otherwise, problems will arise when a package was removed but not purged
679 since configuration files are kept on the system in this situation.
681 Any ``cron`` daemon must provide ``/usr/bin/crontab`` and support normal
682 ``crontab`` entries as specified in POSIX. The daemon must also support
683 names for days and months, ranges, and step values. It has to support
684 ``/etc/crontab``, and correctly execute the scripts in ``/etc/cron.d``.
685 The daemon must also correctly execute scripts in
686 ``/etc/cron.{hourly,daily,weekly,monthly}``.
693 The file name of a cron job file should normally match the name of the
694 package from which it comes.
696 If a package supplies multiple cron job files files in the same
697 directory, the file names should all start with the name of the package
698 (possibly modified as described below) followed by a hyphen (``-``) and
701 A cron job file name must not include any period or plus characters
702 (``.`` or ``+``) characters as this will cause cron to ignore the file.
703 Underscores (``_``) should be used instead of ``.`` and ``+``
711 Packages shipping applications that comply with minimal requirements
712 described below for integration with desktop environments should
713 register these applications in the desktop menu, following the
714 *FreeDesktop* standard, using text files called *desktop entries*. Their
715 format is described in the *Desktop Entry Specification* at
716 https://standards.freedesktop.org/desktop-entry-spec/latest/ and
717 complementary information can be found in the *Desktop Menu
718 Specification* at https://standards.freedesktop.org/menu-spec/latest/.
720 The desktop entry files are installed by the packages in the directory
721 ``/usr/share/applications`` and the FreeDesktop menus are refreshed
722 using *dpkg triggers*. It is therefore not necessary to depend on
723 packages providing FreeDesktop menu systems.
725 Entries displayed in the FreeDesktop menu should conform to the
726 following minima for relevance and visual integration.
728 - Unless hidden by default, the desktop entry must point to a PNG or
729 SVG icon with a transparent background, providing at least the 22×22
730 size, and preferably up to 64×64. The icon should be neutral enough
731 to integrate well with the default icon themes. It is encouraged to
732 ship the icon in the default *hicolor* icon theme directories, or to
733 use an existing icon from the *hicolor* theme.
735 - If the menu entry is not useful in the general case as a standalone
736 application, the desktop entry should set the ``NoDisplay`` key to
737 true, so that it can be configured to be displayed only by those who
740 - In doubt, the package maintainer should coordinate with the
741 maintainers of menu implementations through the *debian-desktop*
742 mailing list in order to avoid problems with categories or bad
743 interactions with other icons. Especially for packages which are part
744 of installation tasks, the contents of the
745 ``NotShowIn``/``OnlyShowIn`` keys should be validated by the
746 maintainers of the relevant environments.
748 Since the FreeDesktop menu is a cross-distribution standard, the desktop
749 entries written for Debian should be forwarded upstream, where they will
750 benefit to other users and are more likely to receive extra
751 contributions such as translations.
753 If a package installs a FreeDesktop desktop entry, it must not also
754 install a Debian menu entry.
761 Media types (formerly known as MIME types, Multipurpose Internet Mail
762 Extensions, RFCs 2045-2049) is a mechanism for encoding files and data
763 streams and providing meta-information about them, in particular their
764 type and format (e.g. ``image/png``, ``text/html``, ``audio/ogg``).
766 Registration of media type handlers allows programs like mail user
767 agents and web browsers to invoke these handlers to view, edit or
768 display media types they don't support directly.
770 There are two overlapping systems to associate media types to programs
771 which can handle them. The *mailcap* system is found on a large number
772 of Unix systems. The *FreeDesktop* system is aimed at Desktop
773 environments. In Debian, FreeDesktop entries are automatically
774 translated in mailcap entries, therefore packages already using desktop
775 entries should not use the mailcap system directly.
777 .. _s-media-types-freedesktop:
779 Registration of media type handlers with desktop entries
780 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
782 Packages shipping an application able to view, edit or point to files of
783 a given media type, or open links with a given URI scheme, should list
784 it in the ``MimeType`` key of the application's `desktop
785 entry <#s-menus>`_. For URI schemes, the relevant MIME types are
786 ``x-scheme-handler/*`` (e.g. ``x-scheme-handler/https``).
790 Registration of media type handlers with mailcap entries
791 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
793 Packages that are not using desktop entries for registration should
794 install a file in mailcap(5) format (RFC 1524) in the directory
795 ``/usr/lib/mime/packages/``. The file name should be the binary
798 The mime-support package provides the ``update-mime`` program, which
799 integrates these registrations in the ``/etc/mailcap`` file, using dpkg
802 Packages installing desktop entries should not install mailcap entries
803 for the same program, because the mime-support package already reads
806 Packages using these facilities *should not* depend on, recommend, or
807 suggest ``mime-support``.
809 .. _s-file-media-type:
811 Providing media types to files
812 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
814 The media type of a file is discovered by inspecting the file's
815 extension or its magic(5) pattern, and interrogating a database
816 associating them with media types.
818 To support new associations between media types and files, their
819 characteristic file extensions and magic patterns should be registered
820 to the IANA (Internet Assigned Numbers Authority). See
821 https://www.iana.org/assignments/media-types and RFC 6838 for details.
822 This information will then propagate to the systems discovering file
823 media types in Debian, provided by the shared-mime-info, mime-support
824 and file packages. If registration and propagation can not be waited
825 for, support can be asked to the maintainers of the packages mentioned
828 For files that are produced and read by a single application, it is also
829 possible to declare this association to the *Shared MIME Info* system by
830 installing in the directory ``/usr/share/mime/packages`` a file in the
831 XML format specified at
832 https://standards.freedesktop.org/shared-mime-info-spec/latest/.
836 Keyboard configuration
837 ----------------------
839 To achieve a consistent keyboard configuration so that all applications
840 interpret a keyboard event the same way, all programs in the Debian
841 distribution must be configured to comply with the following guidelines.
843 The following keys must have the specified interpretations:
846 delete the character to the left of the cursor
849 delete the character to the right of the cursor
852 emacs: the help prefix
854 The interpretation of any keyboard events should be independent of the
855 terminal that is used, be it a virtual console, an X terminal emulator,
856 an rlogin/telnet session, etc.
858 The following list explains how the different programs should be set up
861 - ``<--`` generates ``KB_BackSpace`` in X.
863 - ``Delete`` generates ``KB_Delete`` in X.
865 - X translations are set up to make ``KB_Backspace`` generate ASCII
866 DEL, and to make ``KB_Delete`` generate ``ESC [ 3 ~`` (this is the vt220 escape code for the "delete
867 character" key). This must be done by loading the X resources using
868 ``xrdb`` on all local X displays, not using the application defaults,
869 so that the translation resources used correspond to the ``xmodmap``
872 - The Linux console is configured to make ``<--`` generate DEL, and
873 ``Delete`` generate ``ESC [ 3 ~``.
875 - X applications are configured so that ``<`` deletes left, and
876 ``Delete`` deletes right. Motif applications already work like this.
878 - Terminals should have ``stty erase ^?`` .
880 - The ``xterm`` terminfo entry should have ``ESC [ 3 ~`` for ``kdch1``,
881 just as for ``TERM=linux`` and ``TERM=vt220``.
883 - Emacs is programmed to map ``KB_Backspace`` or the ``stty erase``
884 character to ``delete-backward-char``, and ``KB_Delete`` or ``kdch1``
885 to ``delete-forward-char``, and ``^H`` to ``help`` as always.
887 - Other applications use the ``stty erase`` character and ``kdch1`` for
888 the two delete keys, with ASCII DEL being "delete previous character"
889 and ``kdch1`` being "delete character under cursor".
891 This will solve the problem except for the following cases:
893 - Some terminals have a ``<--`` key that cannot be made to produce
894 anything except ``^H``. On these terminals Emacs help will be
895 unavailable on ``^H`` (assuming that the ``stty erase`` character
896 takes precedence in Emacs, and has been set correctly). ``M-x help`` or ``F1`` (if available) can be used instead.
898 - Some operating systems use ``^H`` for ``stty erase``. However, modern
899 telnet versions and all rlogin versions propagate ``stty`` settings,
900 and almost all UNIX versions honour ``stty erase``. Where the
901 ``stty`` settings are not propagated correctly, things can be made to
902 work by using ``stty`` manually.
904 - Some systems (including previous Debian versions) use ``xmodmap`` to
905 arrange for both ``<--`` and ``Delete`` to generate ``KB_Delete``. We
906 can change the behavior of their X clients using the same X resources
907 that we use to do it for our own clients, or configure our clients
908 using their resources when things are the other way around. On
909 displays configured like this ``Delete`` will not work, but ``<--``
912 - Some operating systems have different ``kdch1`` settings in their
913 ``terminfo`` database for ``xterm`` and others. On these systems the
914 ``Delete`` key will not work correctly when you log in from a system
915 conforming to our policy, but ``<--`` will.
919 Environment variables
920 ---------------------
922 Programs installed on the system PATH (``/bin``, ``/usr/bin``,
923 ``/sbin``, ``/usr/sbin``, or similar directories) must not depend on
924 custom environment variable settings to get reasonable defaults. This is
925 because such environment variables would have to be set in a system-wide
926 configuration file such as a file in ``/etc/profile.d``, which is not
927 supported by all shells.
929 If a program usually depends on environment variables for its
930 configuration, the program should be changed to fall back to a
931 reasonable default configuration if these environment variables are not
932 present. If this cannot be done easily (e.g., if the source code of a
933 non-free program is not available), the program must be replaced by a
934 small "wrapper" shell script that sets the environment variables if they
935 are not already defined, and calls the original program.
937 Here is an example of a wrapper script for this purpose:
942 BAR=${BAR:-/var/lib/fubar}
944 exec /usr/lib/foo/foo "$@"
948 Registering Documents using doc-base
949 ------------------------------------
951 The doc-base package implements a flexible mechanism for handling and
952 presenting documentation. The recommended practice is for every Debian
953 package that provides online documentation (other than just manual
954 pages) to register these documents with doc-base by installing a
955 doc-base control file in ``/usr/share/doc-base/``.
957 Please refer to the documentation that comes with the doc-base package
958 for information and details.
962 Alternate init systems
963 ----------------------
965 A number of other init systems are available now in Debian that can be
966 used in place of sysvinit. Alternative init implementations must support
967 running SysV init scripts as described at
968 :ref:`s-sysvinit` for compatibility.
970 Packages may integrate with these replacement init systems by providing
971 implementation-specific configuration information about how and when to
972 start a service or in what order to run certain tasks at boot time.
973 However, any package integrating with other init systems must also be
974 backwards-compatible with sysvinit by providing a SysV-style init script
975 with the same name as and equivalent functionality to any init-specific
976 job, as this is the only start-up configuration method guaranteed to be
977 supported by all init implementations. An exception to this rule is
978 scripts or jobs provided by the init implementation itself; such jobs
979 may be required for an implementation-specific equivalent of the
980 ``/etc/rcS.d/`` scripts and may not have a one-to-one correspondence
981 with the init scripts.
985 Event-based boot with upstart
986 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
988 The ``upstart`` event-based boot system is no longer maintained in
989 Debian, so this section has been removed.
992 This is necessary in order to reserve the directories for use in
993 cross-installation of library packages from other architectures, as
994 part of ``multiarch``.
997 This is necessary for architecture-dependent headers file to coexist
998 in a ``multiarch`` setup.
1001 This directory is used as mount point to mount virtual filesystems to
1002 get access to kernel information.
1005 These directories are used to store translators and as a set of
1006 standard names for mount points, respectively.
1009 ``/lib/lsb/init-functions``, which assists in writing LSB-compliant
1010 init scripts, may fail if ``set -e`` is in effect and echoing status messages to the
1011 console fails, for example.
1014 Creating, modifying or removing a file in
1015 ``/usr/lib/mime/packages/`` using maintainer scripts will not
1016 activate the trigger. In that case, it can be done by calling
1017 ``dpkg-trigger --no-await /usr/lib/mime/packages`` from the
1018 maintainer script after creating, modifying, or removing the file.