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