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