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