man/file-hierarchy.xml

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