man/file-hierarchy.xml

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