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">
6 This file is part of systemd.
8 Copyright 2014 Lennart Poettering
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.
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.
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/>.
24 <refentry id="file-hierarchy">
27 <title>file-hierarchy</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>file-hierarchy</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>file-hierarchy</refname>
47 <refpurpose>File system hierarchy overview</refpurpose>
51 <title>Description</title>
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 project='man-pages'><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>
66 <para>Many of the paths described here are queriable
68 <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>
73 <title>General Structure</title>
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).
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
100 loaders.</para></listitem>
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>
118 <term><filename>/home</filename></term>
119 <listitem><para>The location for
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
140 database.</para></listitem>
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>
152 mounted.</para></listitem>
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>
169 <term><filename>/tmp</filename></term>
170 <listitem><para>The place for small
171 temporary files. This directory is
173 a <literal>tmpfs</literal> instance, and
174 should hence not be used for larger
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 project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry project='man-pages'><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
189 <varname>$TMPDIR</varname> set they
190 should prefer using the directory
191 specified in it over directly
193 <filename>/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
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>
202 <title>Runtime Data</title>
206 <term><filename>/run</filename></term>
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
213 only. Always writable.</para></listitem>
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
222 <filename>/var/log</filename> might
224 yet.</para></listitem>
228 <term><filename>/run/user</filename></term>
229 <listitem><para>Contains per-user
230 runtime directories, each usually
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
240 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
242 Specification</ulink>.</para></listitem>
248 <title>Vendor-supplied Operating System Resources</title>
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
262 packages.</para></listitem>
266 <term><filename>/usr/bin</filename></term>
267 <listitem><para>Binaries and
268 executables for user commands, that
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>
281 <term><filename>/usr/include</filename></term>
282 <listitem><para>C and C++ API header
284 libraries.</para></listitem>
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>
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,
315 architecture-dependent, too. To query
316 <varname>$libdir</varname> for the
317 primary architecture of the system,
319 <programlisting># pkg-config --variable=libdir systemd</programlisting> or
320 <programlisting># systemd-path system-library-arch</programlisting>
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>
339 <term><filename>/usr/share/doc</filename></term>
340 <listitem><para>Documentation for the
341 operating system or system
342 packages.</para></listitem>
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
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
358 defaults.</para></listitem>
362 <term><filename>/usr/share/factory/var</filename></term>
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
369 <filename>/var</filename>.</para></listitem>
376 <title>Persistent Variable System Data</title>
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>
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>
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>
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
427 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
429 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
430 calls.</para></listitem>
434 <term><filename>/var/spool</filename></term>
435 <listitem><para>Persistent system
436 spool data, such as printer or mail
437 queues.</para></listitem>
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
455 <filename>/tmp</filename> apply, and
457 <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
458 <citerefentry project='man-pages'><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
466 <filename>/var/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
475 <title>Virtual Kernel and API File Systems</title>
479 <term><filename>/dev</filename></term>
480 <listitem><para>The root directory for
481 device nodes. Usually this directory
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
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
493 directory.</para></listitem>
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
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>
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 project='man-pages'><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>
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
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>
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
563 directory.</para></listitem>
571 <title>Compatibility Symlinks</title>
575 <term><filename>/bin</filename></term>
576 <term><filename>/sbin</filename></term>
577 <term><filename>/usr/sbin</filename></term>
579 <listitem><para>These compatibility
581 <filename>/usr/bin</filename>,
582 ensuring that scripts and binaries
583 referencing these legacy paths
584 correctly find their binaries.</para></listitem>
588 <term><filename>/lib</filename></term>
590 <listitem><para>This compatibility
592 <filename>/usr/lib</filename>,
593 ensuring that programs referencing
594 this legacy path correctly find
595 their resources.</para></listitem>
599 <term><filename>/lib64</filename></term>
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>
613 <term><filename>/var/run</filename></term>
615 <listitem><para>This compatibility
617 <filename>/run</filename>, ensuring
618 that programs referencing this legacy
619 path correctly find their runtime
620 data.</para></listitem>
627 <title>Home Directory</title>
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
638 url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para>
642 <term><filename>~/.cache</filename></term>
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>
659 <term><filename>~/.config</filename></term>
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
669 <varname>$XDG_CONFIG_HOME</varname> set
670 is should use the directory specified
671 in it instead of this
672 directory.</para></listitem>
676 <term><filename>~/.local/bin</filename></term>
678 <listitem><para>Executables that shall
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
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
693 architectures.</para></listitem>
697 <term><filename>~/.local/lib</filename></term>
699 <listitem><para>Static, private vendor
700 data that is compatible with all
701 architectures.</para></listitem>
705 <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term>
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>
715 <term><filename>~/.local/share</filename></term>
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
725 <varname>$XDG_DATA_HOME</varname> set
726 is should use the directory specified
727 in it instead of this
728 directory.</para></listitem>
736 <title>Unprivileged Write Access</title>
738 <para>Unprivileged processes generally lack
739 write access to most of the hierarchy.</para>
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>
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
764 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
769 <title>Node Types</title>
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>
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
785 <title>System Packages</title>
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
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" />
800 <entry>Directory</entry>
801 <entry>Purpose</entry>
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>
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>
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>
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>
822 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
823 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
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>
834 <para>During runtime and for local configuration and
835 state additional directories are defined:</para>
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" />
844 <entry>Directory</entry>
845 <entry>Purpose</entry>
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>
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>
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>
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>
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>
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>
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>
883 <title>User Packages</title>
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>
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" />
902 <entry>Directory</entry>
903 <entry>Purpose</entry>
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>
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>
916 <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry>
917 <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry>
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>
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>
932 <para>During runtime and for local configuration and
933 state additional directories are defined:</para>
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" />
942 <entry>Directory</entry>
943 <entry>Purpose</entry>
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>
952 <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry>
953 <entry>User runtime data for the package.</entry>
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>
965 <title>See Also</title>
967 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
968 <citerefentry project='man-pages'><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 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
974 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>