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