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