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">
   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.) This directory is usually flushed at boot-up. Also,
 131         files that are not accessed within a certain time may be automatically deleted.</para>
 132
 133         <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
 134         the directory specified in it instead of <filename>/tmp/</filename> (see <citerefentry
 135         project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
 136         <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE
 137         Std 1003.1</ulink> for details).</para>
 138
 139         <para>Since <filename>/tmp/</filename> is accessible to other users of the system, it is essential
 140         that files and subdirectories under this directory are only created with <citerefentry
 141         project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142         <citerefentry
 143         project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 144         and similar calls. For more details, see <ulink url="https://systemd.io/TEMPORARY_DIRECTORIES">Using
 145         /tmp/ and /var/tmp/ Safely</ulink>.</para>
 146         </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 small ephemeral files.) This
 341         directory is generally not flushed at boot-up, but time-based cleanup of files that have not been
 342         accessed for a certain time is applied.</para>
 343
 344         <para>If applications find the environment variable <varname>$TMPDIR</varname> set, they should use
 345         the directory specified in it instead of <filename>/var/tmp/</filename> (see <citerefentry
 346         project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
 347         details).</para>
 348
 349         <para>The same security restrictions as with <filename>/tmp/</filename> apply: <citerefentry
 350         project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 351         <citerefentry
 352         project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 353         and similar calls should be used. For further details about this directory, see <ulink
 354         url="https://systemd.io/TEMPORARY_DIRECTORIES">Using /tmp/ and /var/tmp/ Safely</ulink>.</para>
 355         </listitem>
 356       </varlistentry>
 357
 358     </variablelist>
 359   </refsect1>
 360
 361   <refsect1>
 362     <title>Virtual Kernel and API File Systems</title>
 363
 364     <variablelist>
 365       <varlistentry>
 366         <term><filename>/dev/</filename></term>
 367         <listitem><para>The root directory for device nodes. Usually,
 368         this directory is mounted as a <literal>devtmpfs</literal>
 369         instance, but might be of a different type in
 370         sandboxed/containerized setups. This directory is managed
 371         jointly by the kernel and
 372         <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 373         and should not be written to by other components. A number of
 374         special purpose virtual file systems might be mounted below
 375         this directory.</para></listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><filename>/dev/shm/</filename></term>
 380         <listitem><para>Place for POSIX shared memory segments, as
 381         created via
 382         <citerefentry project='die-net'><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 383         This directory is flushed on boot, and is a
 384         <literal>tmpfs</literal> file system. Since all users have
 385         write access to this directory, special care should be taken
 386         to avoid name clashes and vulnerabilities. For normal users,
 387         shared memory segments in this directory are usually deleted
 388         when the user logs out. Usually, it is a better idea to use
 389         memory mapped files in <filename>/run/</filename> (for system
 390         programs) or <varname>$XDG_RUNTIME_DIR</varname> (for user
 391         programs) instead of POSIX shared memory segments, since these
 392         directories are not world-writable and hence not vulnerable to
 393         security-sensitive name clashes.</para></listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><filename>/proc/</filename></term>
 398         <listitem><para>A virtual kernel file system exposing the
 399         process list and other functionality. This file system is
 400         mostly an API to interface with the kernel and not a place
 401         where normal files may be stored. For details, see
 402         <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 403         A number of special purpose virtual file systems might be
 404         mounted below this directory.</para></listitem>
 405       </varlistentry>
 406
 407       <varlistentry>
 408         <term><filename>/proc/sys/</filename></term>
 409         <listitem><para>A hierarchy below <filename>/proc/</filename>
 410         that exposes a number of kernel tunables. The primary way to
 411         configure the settings in this API file tree is via
 412         <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 413         files. In sandboxed/containerized setups, this directory is
 414         generally mounted read-only.</para></listitem>
 415       </varlistentry>
 416
 417       <varlistentry>
 418         <term><filename>/sys/</filename></term>
 419         <listitem><para>A virtual kernel file system exposing
 420         discovered devices and other functionality. This file system
 421         is mostly an API to interface with the kernel and not a place
 422         where normal files may be stored. In sandboxed/containerized
 423         setups, this directory is generally mounted read-only. A number
 424         of special purpose virtual file systems might be mounted below
 425         this directory.</para></listitem>
 426       </varlistentry>
 427
 428     </variablelist>
 429   </refsect1>
 430
 431   <refsect1>
 432     <title>Compatibility Symlinks</title>
 433
 434     <variablelist>
 435       <varlistentry>
 436         <term><filename>/bin/</filename></term>
 437         <term><filename>/sbin/</filename></term>
 438         <term><filename>/usr/sbin/</filename></term>
 439
 440         <listitem><para>These compatibility symlinks point to
 441         <filename>/usr/bin/</filename>, ensuring that scripts and
 442         binaries referencing these legacy paths correctly find their
 443         binaries.</para></listitem>
 444       </varlistentry>
 445
 446       <varlistentry>
 447         <term><filename>/lib/</filename></term>
 448
 449         <listitem><para>This compatibility symlink points to
 450         <filename>/usr/lib/</filename>, ensuring that programs
 451         referencing this legacy path correctly find their
 452         resources.</para></listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><filename>/lib64/</filename></term>
 457
 458         <listitem><para>On some architecture ABIs, this compatibility
 459         symlink points to <varname>$libdir</varname>, ensuring that
 460         binaries referencing this legacy path correctly find their
 461         dynamic loader. This symlink only exists on architectures
 462         whose ABI places the dynamic loader in this
 463         path.</para></listitem>
 464       </varlistentry>
 465
 466       <varlistentry>
 467         <term><filename>/var/run/</filename></term>
 468
 469         <listitem><para>This compatibility symlink points to
 470         <filename>/run/</filename>, ensuring that programs referencing
 471         this legacy path correctly find their runtime
 472         data.</para></listitem>
 473       </varlistentry>
 474
 475     </variablelist>
 476   </refsect1>
 477
 478   <refsect1>
 479     <title>Home Directory</title>
 480
 481     <para>User applications may want to place files and directories in
 482     the user's home directory. They should follow the following basic
 483     structure. Note that some of these directories are also
 484     standardized (though more weakly) by the <ulink
 485     url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
 486     Base Directory Specification</ulink>. Additional locations for
 487     high-level user resources are defined by <ulink
 488     url="https://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para>
 489
 490     <variablelist>
 491       <varlistentry>
 492         <term><filename>~/.cache/</filename></term>
 493
 494         <listitem><para>Persistent user cache data. User programs may
 495         place non-essential data in this directory. Flushing this
 496         directory should have no effect on operation of programs,
 497         except for increased runtimes necessary to rebuild these
 498         caches. If an application finds
 499         <varname>$XDG_CACHE_HOME</varname> set, it should use the
 500         directory specified in it instead of this
 501         directory.</para></listitem>
 502       </varlistentry>
 503
 504       <varlistentry>
 505         <term><filename>~/.config/</filename></term>
 506
 507         <listitem><para>Application configuration and state. When a
 508         new user is created, this directory will be empty or not exist
 509         at all. Applications should fall back to defaults should their
 510         configuration or state in this directory be missing. If an
 511         application finds <varname>$XDG_CONFIG_HOME</varname> set, it
 512         should use the directory specified in it instead of this
 513         directory.</para></listitem>
 514       </varlistentry>
 515
 516       <varlistentry>
 517         <term><filename>~/.local/bin/</filename></term>
 518
 519         <listitem><para>Executables that shall appear in the user's
 520         <varname>$PATH</varname> search path. It is recommended not to
 521         place executables in this directory that are not useful for
 522         invocation from a shell; these should be placed in a
 523         subdirectory of <filename>~/.local/lib/</filename> instead.
 524         Care should be taken when placing architecture-dependent
 525         binaries in this place, which might be problematic if the home
 526         directory is shared between multiple hosts with different
 527         architectures.</para></listitem>
 528       </varlistentry>
 529
 530       <varlistentry>
 531         <term><filename>~/.local/lib/</filename></term>
 532
 533         <listitem><para>Static, private vendor data that is compatible
 534         with all architectures.</para></listitem>
 535       </varlistentry>
 536
 537       <varlistentry>
 538         <term><filename>~/.local/lib/<replaceable>arch-id</replaceable>/</filename></term>
 539
 540         <listitem><para>Location for placing public dynamic libraries.
 541         The architecture identifier to use is defined on <ulink
 542         url="https://wiki.debian.org/Multiarch/Tuples">Multiarch
 543         Architecture Specifiers (Tuples)</ulink>
 544         list.</para></listitem>
 545       </varlistentry>
 546
 547       <varlistentry>
 548         <term><filename>~/.local/share/</filename></term>
 549
 550         <listitem><para>Resources shared between multiple packages,
 551         such as fonts or artwork. Usually, the precise location and
 552         format of files stored below this directory is subject to
 553         specifications that ensure interoperability. If an application
 554         finds <varname>$XDG_DATA_HOME</varname> set, it should use the
 555         directory specified in it instead of this
 556         directory.</para></listitem>
 557       </varlistentry>
 558
 559     </variablelist>
 560   </refsect1>
 561
 562   <refsect1>
 563     <title>Unprivileged Write Access</title>
 564
 565     <para>Unprivileged processes generally lack write access to most
 566     of the hierarchy.</para>
 567
 568     <para>The exceptions for normal users are
 569     <filename>/tmp/</filename>,
 570     <filename>/var/tmp/</filename>,
 571     <filename>/dev/shm/</filename>, as well as the home directory
 572     <varname>$HOME</varname> (usually found below
 573     <filename>/home/</filename>) and the runtime directory
 574     <varname>$XDG_RUNTIME_DIR</varname> (found below
 575     <filename>/run/user/</filename>) of the user, which are all
 576     writable.</para>
 577
 578     <para>For unprivileged system processes, only
 579     <filename>/tmp/</filename>,
 580     <filename>/var/tmp/</filename> and
 581     <filename>/dev/shm/</filename> are writable. If an
 582     unprivileged system process needs a private writable directory in
 583     <filename>/var/</filename> or <filename>/run/</filename>, it is
 584     recommended to either create it before dropping privileges in the
 585     daemon code, to create it via
 586     <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 587     fragments during boot, or via the
 588     <varname>StateDirectory=</varname> and <varname>RuntimeDirectory=</varname>
 589     directives of service units (see
 590     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 591     for details).</para>
 592
 593     <para><filename>/tmp/</filename>, <filename>/var/tmp/</filename> and <filename>/dev/shm/</filename>
 594     should be mounted <option>nosuid</option> and <option>nodev</option>, which means that set-user-id mode
 595     and character or block special devices are not interpreted on those file systems. In general it is not
 596     possible to mount them <option>noexec</option>, because various programs use those directories for
 597     dynamically generated or optimized code, and with that flag those use cases would break. Using this flag
 598     is OK on special-purpose installations or systems where all software that may be installed is known and
 599     doesn't require such functionality. See the discussion of
 600     <option>nosuid</option>/<option>nodev</option>/<option>noexec</option> in <citerefentry
 601     project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
 602     <constant>PROT_EXEC</constant> in <citerefentry
 603     project='man-pages'><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
 604     </para>
 605   </refsect1>
 606
 607   <refsect1>
 608     <title>Node Types</title>
 609
 610     <para>Unix file systems support different types of file nodes,
 611     including regular files, directories, symlinks, character and
 612     block device nodes, sockets and FIFOs.</para>
 613
 614     <para>It is strongly recommended that <filename>/dev/</filename> is
 615     the only location below which device nodes shall be placed.
 616     Similarly, <filename>/run/</filename> shall be the only location to
 617     place sockets and FIFOs. Regular files, directories and symlinks
 618     may be used in all directories.</para>
 619   </refsect1>
 620
 621   <refsect1>
 622     <title>System Packages</title>
 623
 624     <para>Developers of system packages should follow strict rules when placing their files in the file
 625     system. The following table lists recommended locations for specific types of files supplied by the
 626     vendor.</para>
 627
 628     <table>
 629       <title>System package vendor files locations</title>
 630       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 631         <colspec colname="directory" />
 632         <colspec colname="purpose" />
 633         <thead>
 634           <row>
 635       <entry>Directory</entry>
 636       <entry>Purpose</entry>
 637           </row>
 638         </thead>
 639         <tbody>
 640           <row>
 641       <entry><filename>/usr/bin/</filename></entry>
 642       <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>
 643           </row>
 644           <row>
 645       <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/</filename></entry>
 646       <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>
 647           </row>
 648           <row>
 649       <entry><filename>/usr/lib/<replaceable>package</replaceable>/</filename></entry>
 650       <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
 651           </row>
 652           <row>
 653       <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable>/</filename></entry>
 654       <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>
 655           </row>
 656           <row>
 657       <entry><filename>/usr/include/<replaceable>package</replaceable>/</filename></entry>
 658       <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
 659           </row>
 660         </tbody>
 661       </tgroup>
 662     </table>
 663
 664     <para>Additional static vendor files may be installed in the
 665     <filename>/usr/share/</filename> hierarchy to the locations
 666     defined by the various relevant specifications.</para>
 667
 668     <para>The following directories shall be used by the package for local configuration and files created
 669     during runtime:</para>
 670
 671     <table>
 672       <title>System package variable files locations</title>
 673       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 674         <colspec colname="directory" />
 675         <colspec colname="purpose" />
 676         <thead>
 677           <row>
 678       <entry>Directory</entry>
 679       <entry>Purpose</entry>
 680           </row>
 681         </thead>
 682         <tbody>
 683           <row>
 684       <entry><filename>/etc/<replaceable>package</replaceable>/</filename></entry>
 685       <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>
 686           </row>
 687           <row>
 688       <entry><filename>/run/<replaceable>package</replaceable>/</filename></entry>
 689       <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>
 690           </row>
 691           <row>
 692       <entry><filename>/run/log/<replaceable>package</replaceable>/</filename></entry>
 693       <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>
 694           </row>
 695           <row>
 696       <entry><filename>/var/cache/<replaceable>package</replaceable>/</filename></entry>
 697       <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>
 698           </row>
 699           <row>
 700       <entry><filename>/var/lib/<replaceable>package</replaceable>/</filename></entry>
 701       <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>
 702           </row>
 703           <row>
 704       <entry><filename>/var/log/<replaceable>package</replaceable>/</filename></entry>
 705       <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>
 706           </row>
 707           <row>
 708       <entry><filename>/var/spool/<replaceable>package</replaceable>/</filename></entry>
 709       <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>
 710           </row>
 711         </tbody>
 712       </tgroup>
 713     </table>
 714   </refsect1>
 715
 716   <refsect1>
 717     <title>User Packages</title>
 718
 719     <para>Programs running in user context should follow strict rules when placing their own files in the
 720     user's home directory. The following table lists recommended locations in the home directory for specific
 721     types of files supplied by the vendor if the application is installed in the home directory. (User
 722     applications installed system-wide are covered by the rules outlined above for vendor files.)</para>
 723
 724     <table>
 725       <title>Vendor package file locations under the home directory of the user</title>
 726       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 727         <colspec colname="directory" />
 728         <colspec colname="purpose" />
 729         <thead>
 730           <row>
 731       <entry>Directory</entry>
 732       <entry>Purpose</entry>
 733           </row>
 734         </thead>
 735         <tbody>
 736           <row>
 737       <entry><filename>~/.local/bin/</filename></entry>
 738       <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>
 739           </row>
 740           <row>
 741       <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/</filename></entry>
 742       <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>
 743           </row>
 744           <row>
 745       <entry><filename>~/.local/lib/<replaceable>package</replaceable>/</filename></entry>
 746       <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry>
 747           </row>
 748           <row>
 749       <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable>/</filename></entry>
 750       <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry>
 751           </row>
 752         </tbody>
 753       </tgroup>
 754     </table>
 755
 756     <para>Additional static vendor files may be installed in the <filename>~/.local/share/</filename>
 757     hierarchy, mirroring the subdirectories specified in the section "Vendor-supplied operating system
 758     resources" above.</para>
 759
 760     <para>The following directories shall be used by the package for per-user local configuration and files
 761     created during runtime:</para>
 762
 763     <table>
 764       <title>User package variable file locations</title>
 765       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
 766         <colspec colname="directory" />
 767         <colspec colname="purpose" />
 768         <thead>
 769           <row>
 770       <entry>Directory</entry>
 771       <entry>Purpose</entry>
 772           </row>
 773         </thead>
 774         <tbody>
 775           <row>
 776       <entry><filename>~/.config/<replaceable>package</replaceable>/</filename></entry>
 777       <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry>
 778           </row>
 779           <row>
 780       <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable>/</filename></entry>
 781       <entry>User runtime data for the package.</entry>
 782           </row>
 783           <row>
 784       <entry><filename>~/.cache/<replaceable>package</replaceable>/</filename></entry>
 785       <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>
 786           </row>
 787         </tbody>
 788       </tgroup>
 789     </table>
 790   </refsect1>
 791
 792   <refsect1>
 793     <title>See Also</title>
 794     <para>
 795       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 796       <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 797       <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 798       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 799       <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 800       <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 801       <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 802       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 803     </para>
 804   </refsect1>
 805
 806 </refentry>