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