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