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><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><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
189 <varname>$TMPDIR</varname> set they
190 should prefer using the directory
191 specified in it over directly
193 <filename>/tmp</filename> (see <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details).</para></listitem>
200 <title>Runtime Data</title>
204 <term><filename>/run</filename></term>
206 <literal>tmpfs</literal> file system
207 for system packages to place runtime
208 data in. This directory is flushed on
209 boot, and generally writable for
211 only. Always writable.</para></listitem>
215 <term><filename>/run/log</filename></term>
216 <listitem><para>Runtime system
217 logs. System components may place
218 private logs in this directory. Always
220 <filename>/var/log</filename> might
222 yet.</para></listitem>
226 <term><filename>/run/user</filename></term>
227 <listitem><para>Contains per-user
228 runtime directories, each usually
230 <literal>tmpfs</literal>
231 instances. Always writable, flushed at
232 each reboot and when the user logs
233 out. User code should not reference
234 this directory directly, but via the
235 <varname>$XDG_RUNTIME_DIR</varname>
236 environment variable, as documented in
238 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
240 Specification</ulink>.</para></listitem>
246 <title>Vendor-supplied Operating System Resources</title>
251 <term><filename>/usr</filename></term>
252 <listitem><para>Vendor-supplied
253 operating system resources. Usually
254 read-only, but this is not
255 required. Possibly shared between
256 multiple hosts. This directory should
257 not be modified by the administrator,
258 except when installing or removing
260 packages.</para></listitem>
264 <term><filename>/usr/bin</filename></term>
265 <listitem><para>Binaries and
266 executables for user commands, that
268 <varname>$PATH</varname> search
269 path. It is recommended not to place
270 binaries in this directory that are
271 not useful for invocation from a shell
272 (such as daemon binaries); these
273 should be placed in a subdirectory of
274 <filename>/usr/lib</filename>
275 instead.</para></listitem>
279 <term><filename>/usr/include</filename></term>
280 <listitem><para>C and C++ API header
282 libraries.</para></listitem>
286 <term><filename>/usr/lib</filename></term>
287 <listitem><para>Static, private vendor
288 data that is compatible with all
289 architectures (though not necessarily
290 architecture-independent). Note that
291 this includes internal executables or
292 other binaries that are not regularly
293 invoked from a shell. Such binaries
294 may be for any architecture supported
295 by the system. Do not place public
296 libraries in this directory, use
297 <varname>$libdir</varname> (see
298 below), instead.</para></listitem>
302 <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term>
303 <listitem><para>Location for placing
304 dynamic libraries, also called <varname>$libdir</varname>.
305 The architecture identifier to use is defined on <ulink
306 url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink>
307 list. Legacy locations of <varname>$libdir</varname> are
308 <filename>/usr/lib</filename>,
309 <filename>/usr/lib64</filename>.
310 This directory should not
311 be used for package-specific data,
313 architecture-dependent, too. To query
314 <varname>$libdir</varname> for the
315 primary architecture of the system,
317 <programlisting># pkg-config --variable=libdir systemd</programlisting> or
318 <programlisting># systemd-path system-library-arch</programlisting>
324 <term><filename>/usr/share</filename></term>
325 <listitem><para>Resources shared
326 between multiple packages, such as
327 documentation, man pages, time zone
328 information, fonts and other
329 resources. Usually, the precise
330 location and format of files stored
331 below this directory is subject to
332 specifications that ensure
333 interoperability.</para></listitem>
337 <term><filename>/usr/share/doc</filename></term>
338 <listitem><para>Documentation for the
339 operating system or system
340 packages.</para></listitem>
344 <term><filename>/usr/share/factory/etc</filename></term>
345 <listitem><para>Repository for
346 vendor-supplied default configuration
347 files. This directory should be
348 populated with pristine vendor versions
349 of all configuration files that may be
351 <filename>/etc</filename>. This is
352 useful to compare the local
353 configuration of a system with vendor
354 defaults and to populate the local
356 defaults.</para></listitem>
360 <term><filename>/usr/share/factory/var</filename></term>
362 <listitem><para>Similar to
363 <filename>/usr/share/factory/etc</filename>
364 but for vendor versions of files in
365 the variable, persistent data
367 <filename>/var</filename>.</para></listitem>
374 <title>Persistent Variable System Data</title>
378 <term><filename>/var</filename></term>
379 <listitem><para>Persistent, variable
380 system data. Must be writable. This
381 directory might be pre-populated with
382 vendor-supplied data, but applications
383 should be able to reconstruct
384 necessary files and directories in
385 this subhierarchy should they be
386 missing, as the system might start up
387 without this directory being
388 populated. Persistency is recommended,
389 but optional, to support ephemeral
390 systems. This directory might become
391 available or writable only very late
392 during boot. Components that are
393 required to operate during early boot
394 hence shall not unconditionally rely
395 on this directory.</para></listitem>
399 <term><filename>/var/cache</filename></term>
400 <listitem><para>Persistent system
401 cache data. System components may
402 place non-essential data in this
403 directory. Flushing this directory
404 should have no effect on operation of
405 programs, except for increased
406 runtimes necessary to rebuild these
407 caches.</para></listitem>
411 <term><filename>/var/lib</filename></term>
412 <listitem><para>Persistent system
413 data. System components may
414 place private data in this
415 directory.</para></listitem>
419 <term><filename>/var/log</filename></term>
420 <listitem><para>Persistent system
421 logs. System components may place
422 private logs in this directory, though
423 it is recommended to do most logging
425 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
427 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
428 calls.</para></listitem>
432 <term><filename>/var/spool</filename></term>
433 <listitem><para>Persistent system
434 spool data, such as printer or mail
435 queues.</para></listitem>
439 <term><filename>/var/tmp</filename></term>
440 <listitem><para>The place for larger
441 and persistent temporary files. In
442 contrast to <filename>/tmp</filename>
443 this directory is usually mounted from
444 a persistent physical file system and
445 can thus accept larger files. (Use
446 <filename>/tmp</filename> for smaller
447 files.) This directory is generally
448 not flushed at boot-up, but time-based
449 cleanup of files that have not been
450 accessed for a certain time is
451 applied. The same security
453 <filename>/tmp</filename> apply, and
455 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
456 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
457 or similar calls should be used to
458 make use of this directory. If
459 applications find the environment
460 variable <varname>$TMPDIR</varname>
461 set they should prefer using the
462 directory specified in it over
464 <filename>/var/tmp</filename> (see <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details).
472 <title>Virtual Kernel and API File Systems</title>
476 <term><filename>/dev</filename></term>
477 <listitem><para>The root directory for
478 device nodes. Usually this directory
480 <literal>devtmpfs</literal> instance,
481 but might be of a different type in
482 sandboxed/containerized setups. This
483 directory is managed jointly by the
485 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
486 and should not be written to by other
487 components. A number of special
488 purpose virtual file systems might be
490 directory.</para></listitem>
494 <term><filename>/dev/shm</filename></term>
495 <listitem><para>Place for POSIX shared
496 memory segments, as created via
497 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
498 directory is flushed on boot, and is a
499 <literal>tmpfs</literal> file
500 system. Since all users have write
501 access to this directory, special care
502 should be taken to avoid name clashes
503 and vulnerabilities. For normal users,
504 shared memory segments in this
505 directory are usually deleted when the
506 user logs out. Usually it is a better
507 idea to use memory mapped files in
508 <filename>/run</filename> (for system
510 <varname>$XDG_RUNTIME_DIR</varname>
511 (for user programs) instead of POSIX
512 shared memory segments, since those
513 directories are not world-writable and
514 hence not vulnerable to
515 security-sensitive name
516 clashes.</para></listitem>
520 <term><filename>/proc</filename></term>
521 <listitem><para>A virtual kernel file
522 system exposing the process list and
523 other functionality. This file system
524 is mostly an API to interface with the
525 kernel and not a place where normal
526 files may be stored. For details, see
527 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
528 number of special purpose virtual file
529 systems might be mounted below this
530 directory.</para></listitem>
534 <term><filename>/proc/sys</filename></term>
535 <listitem><para>A hierarchy below
536 <filename>/proc</filename> that
537 exposes a number of kernel
538 tunables. The primary way to configure
539 the settings in this API file tree is
541 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
542 files. In sandboxed/containerized
543 setups this directory is generally
544 mounted read-only.</para></listitem>
548 <term><filename>/sys</filename></term>
549 <listitem><para>A virtual kernel file
550 system exposing discovered devices and
551 other functionality. This file system
552 is mostly an API to interface with the
553 kernel and not a place where normal
554 files may be stored. In
555 sandboxed/containerized setups this
556 directory is generally mounted
557 read-only. A number of special purpose
558 virtual file systems might be mounted
560 directory.</para></listitem>
568 <title>Compatibility Symlinks</title>
572 <term><filename>/bin</filename></term>
573 <term><filename>/sbin</filename></term>
574 <term><filename>/usr/sbin</filename></term>
576 <listitem><para>These compatibility
578 <filename>/usr/bin</filename>,
579 ensuring that scripts and binaries
580 referencing these legacy paths
581 correctly find their binaries.</para></listitem>
585 <term><filename>/lib</filename></term>
587 <listitem><para>This compatibility
589 <filename>/usr/lib</filename>,
590 ensuring that programs referencing
591 this legacy path correctly find
592 their resources.</para></listitem>
596 <term><filename>/lib64</filename></term>
598 <listitem><para>On some architecture
599 ABIs this compatibility symlink points
600 to <varname>$libdir</varname>,
601 ensuring that binaries referencing
602 this legacy path correctly find their
603 dynamic loader. This symlink only
604 exists on architectures whose ABI
605 places the dynamic loader in this
606 path.</para></listitem>
610 <term><filename>/var/run</filename></term>
612 <listitem><para>This compatibility
614 <filename>/run</filename>, ensuring
615 that programs referencing this legacy
616 path correctly find their runtime
617 data.</para></listitem>
624 <title>Home Directory</title>
626 <para>User applications may want to place files and
627 directories in the user's home directory. They should
628 follow the following basic structure. Note that some
629 of these directories are also standardized (though
630 more weakly) by the <ulink
631 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
632 Base Directory Specification</ulink>. Additional
633 locations for high-level user resources are defined by
635 url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para>
639 <term><filename>~/.cache</filename></term>
641 <listitem><para>Persistent user cache
642 data. User programs may place
643 non-essential data in this
644 directory. Flushing this directory
645 should have no effect on operation of
646 programs, except for increased
647 runtimes necessary to rebuild these
648 caches. If an application finds
649 <varname>$XDG_CACHE_HOME</varname> set
650 is should use the directory specified
651 in it instead of this
652 directory.</para></listitem>
656 <term><filename>~/.config</filename></term>
658 <listitem><para>Application
659 configuration and state. When a new
660 user is created this directory will be
661 empty or not exist at
662 all. Applications should fall back to
663 defaults should their configuration or
664 state in this directory be missing. If
666 <varname>$XDG_CONFIG_HOME</varname> set
667 is should use the directory specified
668 in it instead of this
669 directory.</para></listitem>
673 <term><filename>~/.local/bin</filename></term>
675 <listitem><para>Executables that shall
677 <varname>$PATH</varname> search
678 path. It is recommended not to place
679 executables in this directory that are
680 not useful for invocation from a
681 shell; these should be placed in a
683 <filename>~/.local/lib</filename>
684 instead. Care should be taken when
685 placing architecture-dependent
686 binaries in this place which might be
687 problematic if the home directory is
688 shared between multiple hosts with
690 architectures.</para></listitem>
694 <term><filename>~/.local/lib</filename></term>
696 <listitem><para>Static, private vendor
697 data that is compatible with all
698 architectures.</para></listitem>
702 <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term>
704 <listitem><para>Location for placing
705 public dynamic libraries. The architecture
706 identifier to use, is defined on <ulink
707 url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink>
708 list.</para></listitem>
712 <term><filename>~/.local/share</filename></term>
714 <listitem><para>Resources shared
715 between multiple packages, such as
716 fonts or artwork. Usually, the precise
717 location and format of files stored
718 below this directory is subject to
719 specifications that ensure
722 <varname>$XDG_DATA_HOME</varname> set
723 is should use the directory specified
724 in it instead of this
725 directory.</para></listitem>
733 <title>Unprivileged Write Access</title>
735 <para>Unprivileged processes generally lack
736 write access to most of the hierarchy.</para>
738 <para>The exceptions for normal users are
739 <filename>/tmp</filename>,
740 <filename>/var/tmp</filename>,
741 <filename>/dev/shm</filename>, as well as the home
742 directory <varname>$HOME</varname> (usually found
743 below <filename>/home</filename>) and the runtime
744 directory <varname>$XDG_RUNTIME_DIR</varname> (found
745 below <filename>/run/user</filename>) of the
746 user, which are all writable.</para>
748 <para>For unprivileged system processes only
749 <filename>/tmp</filename>,
750 <filename>/var/tmp</filename> and
751 <filename>/dev/shm</filename> are writable. If an
752 unprivileged system process needs a private, writable
753 directory in <filename>/var</filename> or
754 <filename>/run</filename>, it is recommended to either
755 create it before dropping privileges in the daemon
756 code, to create it via
757 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
758 fragments during boot, or via the
759 <varname>RuntimeDirectory=</varname> directive of
761 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
766 <title>Node Types</title>
768 <para>Unix file systems support different types of file
769 nodes, including regular files, directories, symlinks,
770 character and block device nodes, sockets and FIFOs.</para>
772 <para>It is strongly recommended that
773 <filename>/dev</filename> is the only location below
774 which device nodes shall be placed. Similar,
775 <filename>/run</filename> shall be the only location
776 to place sockets and FIFOs. Regular files,
777 directories and symlinks may be used in all
782 <title>System Packages</title>
784 <para>Developers of system packages should follow
785 strict rules when placing their own files in the file
786 system. The following table lists recommended
787 locations for specific types of files supplied by the
791 <title>System Package Vendor Files Locations</title>
792 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
793 <colspec colname="directory" />
794 <colspec colname="purpose" />
797 <entry>Directory</entry>
798 <entry>Purpose</entry>
803 <entry><filename>/usr/bin</filename></entry>
804 <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>
807 <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry>
808 <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
811 <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
812 <entry>Private, static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
815 <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry>
816 <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry>
819 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
820 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
826 <para>Additional static vendor files may be installed
827 in the <filename>/usr/share</filename> hierarchy, to
828 the locations defined by the various relevant
829 specifications.</para>
831 <para>During runtime and for local configuration and
832 state additional directories are defined:</para>
835 <title>System Package Variable Files Locations</title>
836 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
837 <colspec colname="directory" />
838 <colspec colname="purpose" />
841 <entry>Directory</entry>
842 <entry>Purpose</entry>
847 <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
848 <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry>
851 <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
852 <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry>
855 <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
856 <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry>
859 <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
860 <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
863 <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
864 <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry>
867 <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
868 <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
871 <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
872 <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
880 <title>User Packages</title>
882 <para>Programs running in user context should follow
883 strict rules when placing their own files in the
884 user's home directory. The following table lists
885 recommended locations in the home directory for
886 specific types of files supplied by the vendor if the
887 application is installed in the home directory. (Note
888 however, that user applications installed system-wide
889 should follow the rules outlined above regarding
890 placing vendor files.)</para>
893 <title>User Package Vendor File Locations</title>
894 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
895 <colspec colname="directory" />
896 <colspec colname="purpose" />
899 <entry>Directory</entry>
900 <entry>Purpose</entry>
905 <entry><filename>~/.local/bin</filename></entry>
906 <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
909 <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry>
910 <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
913 <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry>
914 <entry>Private, static vendor resources of the package, compatible wih any architecture, or any other kind of read-only vendor data.</entry>
917 <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry>
918 <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry>
924 <para>Additional static vendor files may be installed
925 in the <filename>~/.local/share</filename> hierarchy,
926 to the locations defined by the various relevant
927 specifications.</para>
929 <para>During runtime and for local configuration and
930 state additional directories are defined:</para>
933 <title>User Package Variable File Locations</title>
934 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
935 <colspec colname="directory" />
936 <colspec colname="purpose" />
939 <entry>Directory</entry>
940 <entry>Purpose</entry>
945 <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry>
946 <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry>
949 <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry>
950 <entry>User runtime data for the package.</entry>
953 <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry>
954 <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
962 <title>See Also</title>
964 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
965 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
966 <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
967 <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
968 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
969 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
970 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
971 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>