man/file-hierarchy.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="file-hierarchy" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>file-hierarchy</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>file-hierarchy</refentrytitle>
  15     <manvolnum>7</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>file-hierarchy</refname>
  20     <refpurpose>File system hierarchy overview</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Description</title>
  25
  26     <para>Operating systems using the
  27     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> system and
  28     service manager are organized based on a file system hierarchy inspired by UNIX, more specifically the
  29     hierarchy described in the <ulink url="http://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html">File
  30     System Hierarchy</ulink> specification and <citerefentry
  31     project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with
  32     various extensions, partially documented in the <ulink
  33     url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory
  34     Specification</ulink> and <ulink url="https://www.freedesktop.org/wiki/Software/xdg-user-dirs">XDG User
  35     Directories</ulink>. This manual page describes a more generalized, though minimal and modernized subset
  36     of these specifications that defines more strictly the suggestions and restrictions systemd makes on the
  37     file system hierarchy. Note that this document makes no attempt to define the directory structure
  38     comprehensively, it only documents a skeleton of a directory tree, that downstreams can extend. Because
  39     of that traditional directories such as <filename>/usr/include/</filename> or
  40     <filename>/var/spool/</filename> are not covered, even though it might (or might not) make a lot of sense
  41     to include them in the structure of an actually deployed OS.</para>
  42
  43     <para>Many of the paths described here can be queried
  44     with the
  45     <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  46     tool.</para>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>General Structure</title>
  51
  52     <variablelist>
  53       <varlistentry>
  54         <term><filename>/</filename></term>
  55         <listitem><para>The file system root. Usually writable, but this is not required. Possibly a
  56         temporary file system (<literal>tmpfs</literal>). Not shared with other hosts (unless
  57         read-only).</para></listitem>
  58       </varlistentry>
  59
  60       <varlistentry>
  61         <term><filename>/boot/</filename></term>
  62         <listitem><para>The boot partition used for bringing up the system. On EFI systems, this is possibly
  63         the EFI System Partition (ESP), also see
  64         <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  65         This directory is usually strictly local to the host, and should be considered read-only, except when
  66         a new kernel or boot loader is installed. This directory only exists on systems that run on physical
  67         or emulated hardware that requires boot loaders.</para></listitem>
  68       </varlistentry>
  69
  70       <varlistentry>
  71         <term><filename>/efi/</filename></term>
  72         <listitem><para>If the boot partition <filename>/boot/</filename> is maintained separately from the
  73         EFI System Partition (ESP), the latter is mounted here. Tools that need to operate on the EFI system
  74         partition should look for it at this mount point first, and fall back to <filename>/boot/</filename>
  75         — if the former doesn't qualify (for example if it is not a mount point or does not have the correct
  76         file system type <constant>MSDOS_SUPER_MAGIC</constant>).</para></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><filename>/etc/</filename></term>
  81         <listitem><para>System-specific configuration. This directory may or may not be
  82         read-only. Frequently, this directory is pre-populated with vendor-supplied configuration files, but
  83         applications should not make assumptions about this directory being fully populated or populated at
  84         all, and should fall back to defaults if configuration is missing.</para></listitem>
  85       </varlistentry>
  86
  87       <varlistentry>
  88         <term><filename>/home/</filename></term>
  89         <listitem><para>The location for normal user's home directories. Possibly shared with other systems,
  90         and never read-only. This directory should only be used for normal users, never for system
  91         users. This directory and possibly the directories contained within it might only become available or
  92         writable in late boot or even only after user authentication.  This directory might be placed on
  93         limited-functionality network file systems, hence applications should not assume the full set of file
  94         API is available on this directory.  Applications should generally not reference this directory
  95         directly, but via the per-user <varname>$HOME</varname> environment variable, or via the home
  96         directory field of the user database.</para></listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><filename>/root/</filename></term>
 101         <listitem><para>The home directory of the root user. The root user's home directory is located
 102         outside of <filename>/home/</filename> in order to make sure the root user may log in even without
 103         <filename>/home/</filename> being available and mounted.</para></listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><filename>/srv/</filename></term>
 108         <listitem><para>The place to store general server payload, managed by the administrator. No
 109         restrictions are made how this directory is organized internally. Generally writable, and possibly
 110         shared among systems. This directory might become available or writable only very late during
 111         boot.</para></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><filename>/tmp/</filename></term>
 116         <listitem><para>The place for small temporary files. This directory is usually mounted as a
 117         <literal>tmpfs</literal> instance, and should hence not be used for larger files. (Use
 118         <filename>/var/tmp/</filename> for larger files.) This directory is usually flushed at boot-up. Also,
 119         files that are not accessed within a certain time may be automatically deleted.</para>
 120
 121         <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
 122         the directory specified in it instead of <filename>/tmp/</filename> (see <citerefentry
 123         project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
 124         <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE
 125         Std 1003.1</ulink> for details).</para>
 126
 127         <para>Since <filename>/tmp/</filename> is accessible to other users of the system, it is essential
 128         that files and subdirectories under this directory are only created with <citerefentry
 129         project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 130         <citerefentry
 131         project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 132         and similar calls. For more details, see <ulink url="https://systemd.io/TEMPORARY_DIRECTORIES">Using
 133         /tmp/ and /var/tmp/ Safely</ulink>.</para></listitem>
 134       </varlistentry>
 135
 136     </variablelist>
 137   </refsect1>
 138
 139   <refsect1>
 140     <title>Runtime Data</title>
 141
 142     <variablelist>
 143       <varlistentry>
 144         <term><filename>/run/</filename></term>
 145         <listitem><para>A <literal>tmpfs</literal> file system for system packages to place runtime data,
 146         socket files, and similar. This directory is flushed on boot, and generally writable for privileged
 147         programs only. Always writable.</para></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><filename>/run/log/</filename></term>
 152         <listitem><para>Runtime system logs. System components may place private logs in this
 153         directory. Always writable, even when <filename>/var/log/</filename> might not be accessible
 154         yet.</para></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><filename>/run/user/</filename></term>
 159         <listitem><para>Contains per-user runtime directories, each usually individually mounted
 160         <literal>tmpfs</literal> instances. Always writable, flushed at each reboot and when the user logs
 161         out. User code should not reference this directory directly, but via the
 162         <varname>$XDG_RUNTIME_DIR</varname> environment variable, as documented in the <ulink
 163         url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory
 164         Specification</ulink>.</para></listitem>
 165       </varlistentry>
 166     </variablelist>
 167   </refsect1>
 168
 169   <refsect1>
 170     <title>Vendor-supplied Operating System Resources</title>
 171
 172     <variablelist>
 173
 174       <varlistentry>
 175         <term><filename>/usr/</filename></term>
 176         <listitem><para>Vendor-supplied operating system resources.  Usually read-only, but this is not
 177         required. Possibly shared between multiple hosts. This directory should not be modified by the
 178         administrator, except when installing or removing vendor-supplied packages.</para></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><filename>/usr/bin/</filename></term>
 183         <listitem><para>Binaries and executables for user commands that shall appear in the
 184         <varname>$PATH</varname> search path.  It is recommended not to place binaries in this directory that
 185         are not useful for invocation from a shell (such as daemon binaries); these should be placed in a
 186         subdirectory of <filename>/usr/lib/</filename> instead.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><filename>/usr/lib/</filename></term>
 191         <listitem><para>Static, private vendor data that is compatible with all architectures (though not
 192         necessarily architecture-independent). Note that this includes internal executables or other binaries
 193         that are not regularly invoked from a shell. Such binaries may be for any architecture supported by
 194         the system. Do not place public libraries in this directory, use <varname>$libdir</varname> (see
 195         below), instead.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><filename>/usr/lib/<replaceable>arch-id</replaceable>/</filename></term>
 200         <listitem><para>Location for placing dynamic libraries into, also called
 201         <varname>$libdir</varname>. The architecture identifier to use is defined on <ulink
 202         url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink>
 203         list. Legacy locations of <varname>$libdir</varname> are <filename>/usr/lib/</filename>,
 204         <filename>/usr/lib64/</filename>. This directory should not be used for package-specific data, unless
 205         this data is architecture-dependent, too.</para>
 206
 207         <para>To query <varname>$libdir</varname> for the primary architecture of the system, invoke:
 208         <programlisting>systemd-path system-library-arch</programlisting></para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><filename>/usr/share/</filename></term>
 213         <listitem><para>Resources shared between multiple packages, such as documentation, man pages, time
 214         zone information, fonts and other resources. Usually, the precise location and format of files stored
 215         below this directory is subject to specifications that ensure interoperability.</para>
 216
 217         <para>Note that resources placed in this directory typically are under shared ownership,
 218         i.e. multiple different packages have provide and consume these resources, on equal footing, without
 219         any obvious primary owner. This makes makes things systematically different from
 220         <filename>/usr/lib/</filename>, where ownership is generally not shared.</para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><filename>/usr/share/doc/</filename></term>
 225         <listitem><para>Documentation for the operating system or system packages.</para></listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><filename>/usr/share/factory/etc/</filename></term>
 230         <listitem><para>Repository for vendor-supplied default configuration files. This directory should be
 231         populated with pristine vendor versions of all configuration files that may be placed in
 232         <filename>/etc/</filename>. This is useful to compare the local configuration of a system with vendor
 233         defaults and to populate the local configuration with defaults.</para></listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term><filename>/usr/share/factory/var/</filename></term>
 238
 239         <listitem><para>Similar to
 240         <filename>/usr/share/factory/etc/</filename>, but for vendor
 241         versions of files in the variable, persistent data directory
 242         <filename>/var/</filename>.</para></listitem>
 243       </varlistentry>
 244     </variablelist>
 245   </refsect1>
 246
 247   <refsect1>
 248     <title>Persistent Variable System Data</title>
 249
 250     <variablelist>
 251       <varlistentry>
 252         <term><filename>/var/</filename></term>
 253         <listitem><para>Persistent, variable system data. Writable during normal system operation. This
 254         directory might be pre-populated with vendor-supplied data, but applications should be able to
 255         reconstruct necessary files and directories in this subhierarchy should they be missing, as the
 256         system might start up without this directory being populated. Persistency is recommended, but
 257         optional, to support ephemeral systems. This directory might become available or writable only very
 258         late during boot. Components that are required to operate during early boot hence shall not
 259         unconditionally rely on this directory.</para></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><filename>/var/cache/</filename></term>
 264         <listitem><para>Persistent system cache data. System components may place non-essential data in this
 265         directory.  Flushing this directory should have no effect on operation of programs, except for
 266         increased runtimes necessary to rebuild these caches.</para></listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><filename>/var/lib/</filename></term>
 271         <listitem><para>Persistent system data. System components may place private data in this
 272         directory.</para></listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><filename>/var/log/</filename></term>
 277         <listitem><para>Persistent system logs. System components may place private logs in this directory,
 278         though it is recommended to do most logging via the <citerefentry
 279         project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
 280         <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 281         calls.</para></listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><filename>/var/tmp/</filename></term>
 286         <listitem><para>The place for larger and persistent temporary files. In contrast to
 287         <filename>/tmp/</filename>, this directory is usually mounted from a persistent physical file system
 288         and can thus accept larger files. (Use <filename>/tmp/</filename> for small ephemeral files.) This
 289         directory is generally not flushed at boot-up, but time-based cleanup of files that have not been
 290         accessed for a certain time is applied.</para>
 291
 292         <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
 293         the directory specified in it instead of <filename>/var/tmp/</filename> (see <citerefentry
 294         project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 295         details).</para>
 296
 297         <para>The same security restrictions as with <filename>/tmp/</filename> apply: <citerefentry
 298         project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 299         <citerefentry
 300         project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 301         and similar calls should be used. For further details about this directory, see <ulink
 302         url="https://systemd.io/TEMPORARY_DIRECTORIES">Using /tmp/ and /var/tmp/
 303         Safely</ulink>.</para></listitem>
 304       </varlistentry>
 305
 306     </variablelist>
 307   </refsect1>
 308
 309   <refsect1>
 310     <title>Virtual Kernel and API File Systems</title>
 311
 312     <variablelist>
 313       <varlistentry>
 314         <term><filename>/dev/</filename></term>
 315         <listitem><para>The root directory for device nodes. Usually, this directory is mounted as a
 316         <literal>devtmpfs</literal> instance, but might be of a different type in sandboxed/containerized
 317         setups. This directory is managed jointly by the kernel and
 318         <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 319         and should not be written to by other components. A number of special purpose virtual file systems
 320         might be mounted below this directory.</para></listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><filename>/dev/shm/</filename></term>
 325         <listitem><para>Place for POSIX shared memory segments, as created via <citerefentry
 326         project='die-net'><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 327         This directory is flushed on boot, and is a <literal>tmpfs</literal> file system. Since all users
 328         have write access to this directory, special care should be taken to avoid name clashes and
 329         vulnerabilities. For normal users, shared memory segments in this directory are usually deleted when
 330         the user logs out. Usually, it is a better idea to use memory mapped files in
 331         <filename>/run/</filename> (for system programs) or <varname>$XDG_RUNTIME_DIR</varname> (for user
 332         programs) instead of POSIX shared memory segments, since these directories are not world-writable and
 333         hence not vulnerable to security-sensitive name clashes.</para></listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><filename>/proc/</filename></term>
 338         <listitem><para>A virtual kernel file system exposing the process list and other functionality. This
 339         file system is mostly an API to interface with the kernel and not a place where normal files may be
 340         stored. For details, see <citerefentry
 341         project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.  A
 342         number of special purpose virtual file systems might be mounted below this
 343         directory.</para></listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term><filename>/proc/sys/</filename></term>
 348         <listitem><para>A hierarchy below <filename>/proc/</filename> that exposes a number of kernel
 349         tunables. The primary way to configure the settings in this API file tree is via
 350         <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 351         files. In sandboxed/containerized setups, this directory is generally mounted
 352         read-only.</para></listitem>
 353       </varlistentry>
 354
 355       <varlistentry>
 356         <term><filename>/sys/</filename></term>
 357         <listitem><para>A virtual kernel file system exposing discovered devices and other
 358         functionality. This file system is mostly an API to interface with the kernel and not a place where
 359         normal files may be stored. In sandboxed/containerized setups, this directory is generally mounted
 360         read-only. A number of special purpose virtual file systems might be mounted below this
 361         directory.</para></listitem>
 362       </varlistentry>
 363
 364       <varlistentry>
 365         <term><filename>/sys/fs/cgroup/</filename></term>
 366         <listitem><para>A virtual kernel file system exposing process control groups (cgroups). This file
 367         system is an API to interface with the kernel and not a place where normal files may be stored. On
 368         current systems running in the default "unified" mode, this directory serves as the mount point for
 369         the <literal>cgroup2</literal> filesystem, which provides a unified cgroup hierarchy for all resource
 370         controllers. On systems with non-default configurations, this directory may instead be a tmpfs
 371         filesystem containing mount points for various <literal>cgroup</literal> (v1) resource controllers;
 372         in such configurations, if <literal>cgroup2</literal> is mounted it will be mounted on
 373         <filename>/sys/fs/cgroup/unified/</filename>, but cgroup2 will not have resource controllers
 374         attached. In sandboxed/containerized setups, this directory may either not exist or may include a
 375         subset of functionality.</para></listitem>
 376       </varlistentry>
 377     </variablelist>
 378   </refsect1>
 379
 380   <refsect1>
 381     <title>Compatibility Symlinks</title>
 382
 383     <variablelist>
 384       <varlistentry>
 385         <term><filename>/bin/</filename></term>
 386         <term><filename>/sbin/</filename></term>
 387         <term><filename>/usr/sbin/</filename></term>
 388
 389         <listitem><para>These compatibility symlinks point to <filename>/usr/bin/</filename>, ensuring that
 390         scripts and binaries referencing these legacy paths correctly find their binaries.</para></listitem>
 391       </varlistentry>
 392
 393       <varlistentry>
 394         <term><filename>/lib/</filename></term>
 395
 396         <listitem><para>This compatibility symlink points to <filename>/usr/lib/</filename>, ensuring that
 397         programs referencing this legacy path correctly find their resources.</para></listitem>
 398       </varlistentry>
 399
 400       <varlistentry>
 401         <term><filename>/lib64/</filename></term>
 402
 403         <listitem><para>On some architecture ABIs, this compatibility symlink points to
 404         <varname>$libdir</varname>, ensuring that binaries referencing this legacy path correctly find their
 405         dynamic loader. This symlink only exists on architectures whose ABI places the dynamic loader in this
 406         path.</para></listitem>
 407       </varlistentry>
 408
 409       <varlistentry>
 410         <term><filename>/var/run/</filename></term>
 411
 412         <listitem><para>This compatibility symlink points to <filename>/run/</filename>, ensuring that
 413         programs referencing this legacy path correctly find their runtime data.</para></listitem>
 414       </varlistentry>
 415
 416     </variablelist>
 417   </refsect1>
 418
 419   <refsect1>
 420     <title>Home Directory</title>
 421
 422     <para>User applications may want to place files and directories in
 423     the user's home directory. They should follow the following basic
 424     structure. Note that some of these directories are also
 425     standardized (though more weakly) by the <ulink
 426     url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
 427     Base Directory Specification</ulink>. Additional locations for
 428     high-level user resources are defined by <ulink
 429     url="https://www.freedesktop.org/wiki/Software/xdg-user-dirs">xdg-user-dirs</ulink>.</para>
 430
 431     <variablelist>
 432       <varlistentry>
 433         <term><filename>~/.cache/</filename></term>
 434
 435         <listitem><para>Persistent user cache data. User programs may place non-essential data in this
 436         directory. Flushing this directory should have no effect on operation of programs, except for
 437         increased runtimes necessary to rebuild these caches. If an application finds
 438         <varname>$XDG_CACHE_HOME</varname> set, it should use the directory specified in it instead of this
 439         directory.</para></listitem>
 440       </varlistentry>
 441
 442       <varlistentry>
 443         <term><filename>~/.config/</filename></term>
 444
 445         <listitem><para>Application configuration. When a new user is created, this directory will be empty
 446         or not exist at all. Applications should fall back to defaults should their configuration in this
 447         directory be missing. If an application finds <varname>$XDG_CONFIG_HOME</varname> set, it should use
 448         the directory specified in it instead of this directory.</para></listitem>
 449       </varlistentry>
 450
 451       <varlistentry>
 452         <term><filename>~/.local/bin/</filename></term>
 453
 454         <listitem><para>Executables that shall appear in the user's <varname>$PATH</varname> search path. It
 455         is recommended not to place executables in this directory that are not useful for invocation from a
 456         shell; these should be placed in a subdirectory of <filename>~/.local/lib/</filename> instead. Care
 457         should be taken when placing architecture-dependent binaries in this place, which might be
 458         problematic if the home directory is shared between multiple hosts with different
 459         architectures.</para></listitem>
 460       </varlistentry>
 461
 462       <varlistentry>
 463         <term><filename>~/.local/lib/</filename></term>
 464
 465         <listitem><para>Static, private vendor data that is compatible with all
 466         architectures.</para></listitem>
 467       </varlistentry>
 468
 469       <varlistentry>
 470         <term><filename>~/.local/lib/<replaceable>arch-id</replaceable>/</filename></term>
 471
 472         <listitem><para>Location for placing public dynamic libraries. The architecture identifier to use is
 473         defined on <ulink url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers
 474         (Tuples)</ulink> list.</para></listitem>
 475       </varlistentry>
 476
 477       <varlistentry>
 478         <term><filename>~/.local/share/</filename></term>
 479
 480         <listitem><para>Resources shared between multiple packages, such as fonts or artwork. Usually, the
 481         precise location and format of files stored below this directory is subject to specifications that
 482         ensure interoperability. If an application finds <varname>$XDG_DATA_HOME</varname> set, it should use
 483         the directory specified in it instead of this directory.</para></listitem>
 484       </varlistentry>
 485
 486       <varlistentry>
 487         <term><filename>~/.local/state/</filename></term>
 488
 489         <listitem><para>Application state. When a new user is created, this directory will be empty or not
 490         exist at all. Applications should fall back to defaults should their state in this directory be
 491         missing. If an application finds <varname>$XDG_STATE_HOME</varname> set, it should use the directory
 492         specified in it instead of this directory.</para></listitem>
 493       </varlistentry>
 494
 495     </variablelist>
 496   </refsect1>
 497
 498   <refsect1>
 499     <title>Write Access</title>
 500
 501     <refsect2>
 502       <title>Unprivileged Write Access</title>
 503
 504       <para>Unprivileged processes generally lack write access to most of the hierarchy.</para>
 505
 506       <para>The exceptions for normal users are
 507       <filename>/tmp/</filename>,
 508       <filename>/var/tmp/</filename>,
 509       <filename>/dev/shm/</filename>, as well as the home directory
 510       <varname>$HOME</varname> (usually found below
 511       <filename>/home/</filename>) and the runtime directory
 512       <varname>$XDG_RUNTIME_DIR</varname> (found below
 513       <filename>/run/user/</filename>) of the user, which are all
 514       writable.</para>
 515
 516       <para>For unprivileged system processes, only
 517       <filename>/tmp/</filename>,
 518       <filename>/var/tmp/</filename> and
 519       <filename>/dev/shm/</filename> are writable. If an
 520       unprivileged system process needs a private writable directory in
 521       <filename>/var/</filename> or <filename>/run/</filename>, it is
 522       recommended to either create it before dropping privileges in the
 523       daemon code, to create it via
 524       <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 525       fragments during boot, or via the
 526       <varname>StateDirectory=</varname> and <varname>RuntimeDirectory=</varname>
 527       directives of service units (see
 528       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 529       for details).</para>
 530
 531       <para><filename>/tmp/</filename>, <filename>/var/tmp/</filename> and <filename>/dev/shm/</filename>
 532       should be mounted <option>nosuid</option> and <option>nodev</option>, which means that set-user-id mode
 533       and character or block special devices are not interpreted on those file systems. In general it is not
 534       possible to mount them <option>noexec</option>, because various programs use those directories for
 535       dynamically generated or optimized code, and with that flag those use cases would break. Using this
 536       flag is OK on special-purpose installations or systems where all software that may be installed is
 537       known and doesn't require such functionality. See the discussion of
 538       <option>nosuid</option>/<option>nodev</option>/<option>noexec</option> in <citerefentry
 539       project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
 540       <constant>PROT_EXEC</constant> in <citerefentry
 541       project='man-pages'><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
 542       </para>
 543     </refsect2>
 544
 545     <refsect2>
 546       <title>Lack of Write Access on Read-Only Systems and during System Recovery</title>
 547
 548       <para>As noted above, some systems operate with the <filename>/usr</filename> and
 549       <filename>/etc</filename> hierarchies mounted read-only, possibly only allowing write access during
 550       package upgrades. Other part of the hierarchy are generally mounted read-write (in particular
 551       <filename>/var</filename> and <filename>/var/tmp</filename>), but may be read-only when the kernel
 552       remounts the file system read-only in response to errors, or when the system is booted read-only for
 553       recovery purposes. To the extent reasonable, applications should be prepared to execute without write
 554       access, so that for example, failure to save non-essential data to <filename>/var/cache/</filename> or
 555       failure to create a custom log file under <filename>/var/log</filename> does not prevent the
 556       application from running.</para>
 557
 558       <para>The <filename>/run/</filename> directory is available since the earliest boot and is always
 559       writable. It should be used for any runtime data and sockets, so that write access to e.g.
 560       <filename>/etc</filename> or <filename>/var</filename> is not needed.</para>
 561     </refsect2>
 562   </refsect1>
 563
 564   <refsect1>
 565     <title>Node Types</title>
 566
 567     <para>Unix file systems support different types of file nodes,
 568     including regular files, directories, symlinks, character and
 569     block device nodes, sockets and FIFOs.</para>
 570
 571     <para>It is strongly recommended that <filename>/dev/</filename> is
 572     the only location below which device nodes shall be placed.
 573     Similarly, <filename>/run/</filename> shall be the only location to
 574     place sockets and FIFOs. Regular files, directories and symlinks
 575     may be used in all directories.</para>
 576
 577     <para>Applications should expect that a security policy might be enforced on a system that enforces these
 578     rules.</para>
 579   </refsect1>
 580
 581   <refsect1>
 582     <title>System Packages</title>
 583
 584     <para>Developers of system packages should follow strict rules when placing their files in the file
 585     system. The following table lists recommended locations for specific types of files supplied by the
 586     vendor.</para>
 587
 588     <table>
 589       <title>System package vendor files locations</title>
 590       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 591         <colspec colname="directory" />
 592         <colspec colname="purpose" />
 593         <thead>
 594           <row>
 595       <entry>Directory</entry>
 596       <entry>Purpose</entry>
 597           </row>
 598         </thead>
 599         <tbody>
 600           <row>
 601       <entry><filename>/usr/bin/</filename></entry>
 602       <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
 603           </row>
 604           <row>
 605       <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/</filename></entry>
 606       <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
 607           </row>
 608           <row>
 609       <entry><filename>/usr/lib/<replaceable>package</replaceable>/</filename></entry>
 610       <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
 611           </row>
 612           <row>
 613       <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable>/</filename></entry>
 614       <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry>
 615           </row>
 616         </tbody>
 617       </tgroup>
 618     </table>
 619
 620     <para>Additional static vendor files with shared ownership may be installed in the
 621     <filename>/usr/share/</filename> hierarchy to the locations defined by the various relevant
 622     specifications.</para>
 623
 624     <para>The following directories shall be used by the package for local configuration and files created
 625     during runtime:</para>
 626
 627     <table>
 628       <title>System package variable files locations</title>
 629       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 630         <colspec colname="directory" />
 631         <colspec colname="purpose" />
 632         <thead>
 633           <row>
 634       <entry>Directory</entry>
 635       <entry>Purpose</entry>
 636           </row>
 637         </thead>
 638         <tbody>
 639           <row>
 640       <entry><filename>/etc/<replaceable>package</replaceable>/</filename></entry>
 641       <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory/</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry>
 642           </row>
 643           <row>
 644       <entry><filename>/run/<replaceable>package</replaceable>/</filename></entry>
 645       <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot, or the <varname>RuntimeDirectory=</varname> directive of service units may be used to create them at service startup (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details).</entry>
 646           </row>
 647           <row>
 648       <entry><filename>/run/log/<replaceable>package</replaceable>/</filename></entry>
 649       <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry>
 650           </row>
 651           <row>
 652       <entry><filename>/var/cache/<replaceable>package</replaceable>/</filename></entry>
 653       <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary. To create an empty directory, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment or the <varname>CacheDirectory=</varname> directive of service units (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) may be used.</entry>
 654           </row>
 655           <row>
 656       <entry><filename>/var/lib/<replaceable>package</replaceable>/</filename></entry>
 657       <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. To create an empty directory, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment or the <varname>StateDirectory=</varname> directive of service units (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) may be used.</entry>
 658           </row>
 659           <row>
 660       <entry><filename>/var/log/<replaceable>package</replaceable>/</filename></entry>
 661       <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> or <varname>LogsDirectory=</varname> (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), as it might be missing.</entry>
 662           </row>
 663         </tbody>
 664       </tgroup>
 665     </table>
 666   </refsect1>
 667
 668   <refsect1>
 669     <title>User Packages</title>
 670
 671     <para>Programs running in user context should follow strict rules when placing their own files in the
 672     user's home directory. The following table lists recommended locations in the home directory for specific
 673     types of files supplied by the vendor if the application is installed in the home directory. (User
 674     applications installed system-wide are covered by the rules outlined above for vendor files.)</para>
 675
 676     <table>
 677       <title>Vendor package file locations under the home directory of the user</title>
 678       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 679         <colspec colname="directory" />
 680         <colspec colname="purpose" />
 681         <thead>
 682           <row>
 683       <entry>Directory</entry>
 684       <entry>Purpose</entry>
 685           </row>
 686         </thead>
 687         <tbody>
 688           <row>
 689       <entry><filename>~/.local/bin/</filename></entry>
 690       <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
 691           </row>
 692           <row>
 693       <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/</filename></entry>
 694       <entry>Public shared libraries of the package. As above, be careful with using overly generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
 695           </row>
 696           <row>
 697       <entry><filename>~/.local/lib/<replaceable>package</replaceable>/</filename></entry>
 698       <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry>
 699           </row>
 700           <row>
 701       <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable>/</filename></entry>
 702       <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry>
 703           </row>
 704         </tbody>
 705       </tgroup>
 706     </table>
 707
 708     <para>Additional static vendor files with shared ownership may be installed in the
 709     <filename>~/.local/share/</filename> hierarchy, mirroring the subdirectories specified in the section
 710     "Vendor-supplied operating system resources" above.</para>
 711
 712     <para>The following directories shall be used by the package for per-user local configuration and files
 713     created during runtime:</para>
 714
 715     <table>
 716       <title>User package variable file locations</title>
 717       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 718         <colspec colname="directory" />
 719         <colspec colname="purpose" />
 720         <thead>
 721           <row>
 722       <entry>Directory</entry>
 723       <entry>Purpose</entry>
 724           </row>
 725         </thead>
 726         <tbody>
 727           <row>
 728       <entry><filename>~/.config/<replaceable>package</replaceable>/</filename></entry>
 729       <entry>User-specific configuration for the package. It is required to default to safe fallbacks if this configuration is missing.</entry>
 730           </row>
 731           <row>
 732       <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable>/</filename></entry>
 733       <entry>User runtime data for the package.</entry>
 734           </row>
 735           <row>
 736       <entry><filename>~/.cache/<replaceable>package</replaceable>/</filename></entry>
 737       <entry>Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
 738           </row>
 739           <row>
 740       <entry><filename>~/.local/state/<replaceable>package</replaceable>/</filename></entry>
 741       <entry>Persistent state data of the package.</entry>
 742           </row>
 743         </tbody>
 744       </tgroup>
 745     </table>
 746   </refsect1>
 747
 748   <refsect1>
 749     <title>See Also</title>
 750     <para>
 751       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 752       <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 753       <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 754       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 755       <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 756       <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 757       <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 758       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 759     </para>
 760   </refsect1>
 761
 762 </refentry>