man/file-hierarchy.xml

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