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>
68 <title>General Structure</title>
72 <term><filename>/</filename></term>
73 <listitem><para>The file system
74 root. Usually writable, but this is
75 not required. Possibly a temporary
76 file system (<literal>tmpfs</literal>). Not shared with
77 other hosts (unless read-only). The
78 administrator may create additional
79 top-level subdirectories in this tree,
80 if required and the name does not
81 conflict with any of the directories
82 listed below.</para></listitem>
86 <term><filename>/boot</filename></term>
87 <listitem><para>The boot partition
88 used for bringing up the system. On
89 EFI systems this is possibly the EFI
90 System Partition, also see
91 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
92 directory is usually strictly local
93 the host, and should be considered
94 read-only, except when a new kernel or
95 boot loader is installed. This
96 directory only exists on systems that
97 run on physical or emulated hardware
99 loaders.</para></listitem>
103 <term><filename>/etc</filename></term>
104 <listitem><para>System-specific
105 configuration. This directory may or
106 may not be read-only. Frequently, this
107 directory is pre-populated with
108 vendor-supplied configuration files,
109 but applications should not make
110 assumptions about this directory
111 being fully populated or populated at
112 all, and should fall back to defaults
113 if configuration is missing.</para></listitem>
117 <term><filename>/home</filename></term>
118 <listitem><para>The location for
120 directories. Possibly shared with
121 other systems, and never
122 read-only. This directory should only
123 be used for normal users, never for
124 system users. This directory and
125 possibly the directories contained
126 within it might only become available
127 or writable in late boot or even on
128 user login only. This directory might
129 be placed on limited-functionality
130 network file systems, hence
131 applications should not assume the
132 full set of file API is available on
133 this directory. Applications should
134 generally not reference this directory
135 directly, but via the per-user
136 <varname>$HOME</varname> environment
137 variable, or via the home directory
139 database.</para></listitem>
143 <term><filename>/root</filename></term>
144 <listitem><para>The home directory of
145 the root user. The root user's home
146 directory is located outside of
147 <filename>/home</filename> in order to
148 make sure the root user may log in
149 even without <filename>/home</filename>
151 mounted.</para></listitem>
155 <term><filename>/srv</filename></term>
156 <listitem><para>The place to store
157 general server payload, managed by the
158 administrator. No restrictions are
159 made how this directory is organized
160 internally. Generally writable, and
161 possibly shared among systems. This
162 directory might become available or
163 writable only very late during
164 boot.</para></listitem>
168 <term><filename>/tmp</filename></term>
169 <listitem><para>The place for small
170 temporary files. This directory is
172 <literal>tmpfs</literal> instance, and
173 should hence not be used for larger
175 <filename>/var/tmp</filename> for
176 larger files.) Since the directory is
177 accessible to other users of the
178 system it is essential that this
179 directory is only written to with the
180 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
182 and related calls. This directory is
183 usually flushed at boot-up. Also,
184 files that are not accessed within a
185 certain time are usually automatically
186 deleted. If applications find the
188 <varname>$TMP</varname> set they
189 should prefer using the directory
190 specified in it over directly
192 <filename>/tmp</filename>.</para></listitem>
199 <title>Runtime Data</title>
203 <term><filename>/run</filename></term>
205 <literal>tmpfs</literal> file system
206 for system packages to place runtime
207 data in. This directory is flushed on
208 boot, and generally writable for
210 only. Always writable.</para></listitem>
214 <term><filename>/run/log</filename></term>
215 <listitem><para>Runtime system
216 logs. System components may place
217 private logs in this directory. Always
219 <filename>/var/log</filename> might
221 yet.</para></listitem>
225 <term><filename>/run/user</filename></term>
226 <listitem><para>Contains per-user
227 runtime directories, each usually
229 <literal>tmpfs</literal>
230 instances. Always writable, flushed at
231 each reboot and when the user logs
232 out. User code should not reference
233 this directory directly, but via the
234 <varname>$XDG_RUNTIME_DIR</varname>
235 environment variable, as documented in
237 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
239 Specification</ulink>.</para></listitem>
245 <title>Vendor-supplied Operating System Resources</title>
250 <term><filename>/usr</filename></term>
251 <listitem><para>Vendor-supplied
252 operating system resources. Usually
253 read-only, but this is not
254 required. Possibly shared between
255 multiple hosts. This directory should
256 not be modified by the administrator,
257 except when installing or removing
259 packages.</para></listitem>
263 <term><filename>/usr/bin</filename></term>
264 <listitem><para>Binaries for user
265 commands, that shall appear in the
266 <varname>$PATH</varname> search
267 path. It is recommended not to place
268 binaries in this directory that are
269 not useful for invocation from a shell
270 (such as daemon binaries); these
271 should be placed in a subdirectory of
272 <filename>/usr/lib</filename>
273 instead.</para></listitem>
277 <term><filename>/usr/include</filename></term>
278 <listitem><para>C and C++ API header
280 libraries.</para></listitem>
284 <term><filename>/usr/lib</filename></term>
285 <listitem><para>Static vendor data
286 that is compatible with all
287 architectures (though not necessarily
288 architecture-independent). Note that
289 this includes internal
290 executables or other binaries that are
291 not regularly invoked from a
292 shell. Such binaries may be for any
293 architecture supported by the
294 system. Do not place public libraries
295 in this directory, use
296 <varname>$libdir</varname> (see
297 below), instead.</para></listitem>
301 <term><varname>$libdir</varname></term>
302 <listitem><para>Location for placing
303 dynamic libraries in. The precise
304 location depends on the operating
305 system and the architecture, and is
307 <filename>/usr/lib</filename>,
308 <filename>/use/lib64</filename> or
309 <filename>/usr/lib/</filename>
310 suffixed by an architecture
311 identifier. This directory should not
312 be used for package-specific data,
314 architecture-dependent,
315 too.</para></listitem>
319 <term><filename>/usr/share</filename></term>
320 <listitem><para>Resources shared
321 between multiple packages, such as
322 documentation, man pages, time zone
323 information, fonts and other
324 resources. Usually, the precise
325 location and format of files stored
326 below this directory is subject to
327 specifications that ensure
328 interoperability.</para></listitem>
332 <term><filename>/usr/share/doc</filename></term>
333 <listitem><para>Documentation for the
334 operating system or system
335 packages.</para></listitem>
339 <term><filename>/usr/share/factory/etc</filename></term>
340 <listitem><para>Repository for
341 vendor-supplied default configuration
342 files. This directory should be
343 populated with pristine vendor versions
344 of all configuration files that may be
346 <filename>/etc</filename>. This is
347 useful to compare the local
348 configuration of a system with vendor
349 defaults and to populate the local
351 defaults.</para></listitem>
355 <term><filename>/usr/share/factory/var</filename></term>
357 <listitem><para>Similar to
358 <filename>/usr/share/factory/etc</filename>
359 but for vendor versions of files in
360 the variable, persistent data
362 <filename>/var</filename>.</para></listitem>
369 <title>Persistent Variable System Data</title>
373 <term><filename>/var</filename></term>
374 <listitem><para>Persistent, variable
375 system data. Must be writable. This
376 directory might be pre-populated with
377 vendor-supplied data, but applications
378 should be able to reconstruct
379 necessary files and directories in
380 this subhierarchy should they be
381 missing, as the system might start up
382 without this directory being
383 populated. Persistency is recommended,
384 but optional, to support ephemeral
385 systems. This directory might become
386 available or writable only very late
387 during boot. Components that are
388 required to operate during early boot
389 hence shall not unconditionally rely
390 on this directory.</para></listitem>
394 <term><filename>/var/cache</filename></term>
395 <listitem><para>Persistent system
396 cache data. System components may
397 place non-essential data in this
398 directory. Flushing this directory
399 should have no effect on operation of
400 programs, except for increased
401 runtimes necessary to rebuild these
402 caches.</para></listitem>
406 <term><filename>/var/lib</filename></term>
407 <listitem><para>Persistent system
408 data. System components may
409 place private data in this
410 directory.</para></listitem>
414 <term><filename>/var/log</filename></term>
415 <listitem><para>Persistent system
416 logs. System components may place
417 private logs in this directory, though
418 it is recommended to do most logging
420 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
422 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
423 calls.</para></listitem>
427 <term><filename>/var/spool</filename></term>
428 <listitem><para>Persistent system
429 spool data, such as printer or mail
430 queues.</para></listitem>
434 <term><filename>/var/tmp</filename></term>
435 <listitem><para>The place for larger
436 and persistent temporary files. In
437 contrast to <filename>/tmp</filename>
438 this directory is usually mounted from
439 a persistent physical file system and
440 can thus accept larger files. (Use
441 <filename>/tmp</filename> for smaller
442 files.) This directory is generally
443 not flushed at boot-up, but time-based
444 cleanup of files that have not been
445 accessed for a certain time is
446 applied. The same security
448 <filename>/tmp</filename> apply, and
450 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
451 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
452 or similar calls should be used to
453 make use of this directory. If
454 applications find the environment
455 variable <varname>$TMP</varname> set
456 they should prefer using the directory
457 specified in it over directly
459 <filename>/var/tmp</filename>.
467 <title>Virtual Kernel and API File Systems</title>
471 <term><filename>/dev</filename></term>
472 <listitem><para>The root directory for
473 device nodes. Usually this directory
475 <literal>devtmpfs</literal> instance,
476 but might be of a different type in
477 sandboxed/containerized setups. This
478 directory is managed jointly by the
480 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
481 and should not be written to by other
482 components. A number of special
483 purpose virtual file systems might be
485 directory.</para></listitem>
489 <term><filename>/dev/shm</filename></term>
490 <listitem><para>Place for POSIX shared
491 memory segments, as created via
492 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
493 directory is flushed on boot, and is a
494 <literal>tmpfs</literal> file
495 system. Since all users have write
496 access to this directory, special care
497 should be taken to avoid name clashes
498 and vulnerabilities. For normal users,
499 shared memory segments in this
500 directory are usually deleted when the
501 user logs out. Usually it is a better
502 idea to use memory mapped files in
503 <filename>/run</filename> (for system
505 <varname>$XDG_RUNTIME_DIR</varname>
506 (for user programs) instead of POSIX
507 shared memory segments, since they
508 directories are not world-writable and
509 hence not vulnerable to
510 security-sensitive name
511 clashes.</para></listitem>
515 <term><filename>/proc</filename></term>
516 <listitem><para>A virtual kernel file
517 system exposing the process list and
518 other functionality. This file system
519 is mostly an API to interface with the
520 kernel and not a place where normal
521 files may be stored. For details, see
522 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
523 number of special purpose virtual file
524 systems might be mounted below this
525 directory.</para></listitem>
529 <term><filename>/proc/sys</filename></term>
530 <listitem><para>A hierarchy below
531 <filename>/proc</filename> that
532 exposes a number of kernel
533 tunables. The primary way to configure
534 the settings in this API file tree is
536 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
537 files. In sandboxed/containerized
538 setups this directory is generally
539 mounted read-only.</para></listitem>
543 <term><filename>/sys</filename></term>
544 <listitem><para>A virtual kernel file
545 system exposing discovered devices and
546 other functionality. This file system
547 is mostly an API to interface with the
548 kernel and not a place where normal
549 files may be stored. In
550 sandboxed/containerized setups this
551 directory is generally mounted
552 read-only. A number of special purpose
553 virtual file systems might be mounted
555 directory.</para></listitem>
563 <title>Compatibility Symlinks</title>
567 <term><filename>/bin</filename></term>
568 <term><filename>/sbin</filename></term>
569 <term><filename>/usr/sbin</filename></term>
571 <listitem><para>These compatibility
573 <filename>/usr/bin</filename>,
574 ensuring that scripts and binaries
575 referencing these legacy paths
576 correctly find their binaries.</para></listitem>
580 <term><filename>/lib</filename></term>
582 <listitem><para>This compatibility
584 <filename>/usr/lib</filename>,
585 ensuring that programs referencing
586 this legacy path correctly find
587 their resources.</para></listitem>
591 <term><filename>/lib64</filename></term>
593 <listitem><para>On some architecture
594 ABIs this compatibility symlink points
595 to <varname>$libdir</varname>,
596 ensuring that binaries referencing
597 this legacy path correctly find their
598 dynamic loader. This symlink only
599 exists on architectures whose ABI
600 places the dynamic loader in this
601 path.</para></listitem>
605 <term><filename>/var/run</filename></term>
607 <listitem><para>This compatibility
609 <filename>/run</filename>, ensuring
610 that programs referencing this legacy
611 path correctly find their runtime
612 data.</para></listitem>
619 <title>System Packages</title>
621 <para>Developers of system packages should follow
622 strict rules when placing their own files in the file
623 system. The following table lists recommended
624 locations for specific types of files.</para>
627 <title>System Package Data Location</title>
628 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
629 <colspec colname="directory" />
630 <colspec colname="purpose" />
633 <entry>Directory</entry>
634 <entry>Purpose</entry>
639 <entry><filename>/usr/bin</filename></entry>
640 <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for the primary architecture of the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
643 <entry><filename>$libdir</filename></entry>
644 <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>
647 <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
648 <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
651 <entry><filename>$libdir/<replaceable>package</replaceable></filename></entry>
652 <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private exectuables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry>
655 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
656 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
659 <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
660 <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>
663 <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
664 <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.</entry>
667 <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
668 <entry>Runtime log data for the package.</entry>
671 <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
672 <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed done due to the need to rebuild any local cache files.</entry>
675 <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
676 <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>
679 <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
680 <entry>Persistent log data of the package.</entry>
683 <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
684 <entry>Persistent spool/queue data of the package.</entry>
692 <title>See Also</title>
694 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
695 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
696 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
697 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,