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