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