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, too. To query
315 <varname>$libdir</varname> for the
316 primary architecture of the system,
318 <programlisting># pkg-config --variable=libdir systemd</programlisting></para></listitem>
322 <term><filename>/usr/share</filename></term>
323 <listitem><para>Resources shared
324 between multiple packages, such as
325 documentation, man pages, time zone
326 information, fonts and other
327 resources. Usually, the precise
328 location and format of files stored
329 below this directory is subject to
330 specifications that ensure
331 interoperability.</para></listitem>
335 <term><filename>/usr/share/doc</filename></term>
336 <listitem><para>Documentation for the
337 operating system or system
338 packages.</para></listitem>
342 <term><filename>/usr/share/factory/etc</filename></term>
343 <listitem><para>Repository for
344 vendor-supplied default configuration
345 files. This directory should be
346 populated with pristine vendor versions
347 of all configuration files that may be
349 <filename>/etc</filename>. This is
350 useful to compare the local
351 configuration of a system with vendor
352 defaults and to populate the local
354 defaults.</para></listitem>
358 <term><filename>/usr/share/factory/var</filename></term>
360 <listitem><para>Similar to
361 <filename>/usr/share/factory/etc</filename>
362 but for vendor versions of files in
363 the variable, persistent data
365 <filename>/var</filename>.</para></listitem>
372 <title>Persistent Variable System Data</title>
376 <term><filename>/var</filename></term>
377 <listitem><para>Persistent, variable
378 system data. Must be writable. This
379 directory might be pre-populated with
380 vendor-supplied data, but applications
381 should be able to reconstruct
382 necessary files and directories in
383 this subhierarchy should they be
384 missing, as the system might start up
385 without this directory being
386 populated. Persistency is recommended,
387 but optional, to support ephemeral
388 systems. This directory might become
389 available or writable only very late
390 during boot. Components that are
391 required to operate during early boot
392 hence shall not unconditionally rely
393 on this directory.</para></listitem>
397 <term><filename>/var/cache</filename></term>
398 <listitem><para>Persistent system
399 cache data. System components may
400 place non-essential data in this
401 directory. Flushing this directory
402 should have no effect on operation of
403 programs, except for increased
404 runtimes necessary to rebuild these
405 caches.</para></listitem>
409 <term><filename>/var/lib</filename></term>
410 <listitem><para>Persistent system
411 data. System components may
412 place private data in this
413 directory.</para></listitem>
417 <term><filename>/var/log</filename></term>
418 <listitem><para>Persistent system
419 logs. System components may place
420 private logs in this directory, though
421 it is recommended to do most logging
423 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
425 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
426 calls.</para></listitem>
430 <term><filename>/var/spool</filename></term>
431 <listitem><para>Persistent system
432 spool data, such as printer or mail
433 queues.</para></listitem>
437 <term><filename>/var/tmp</filename></term>
438 <listitem><para>The place for larger
439 and persistent temporary files. In
440 contrast to <filename>/tmp</filename>
441 this directory is usually mounted from
442 a persistent physical file system and
443 can thus accept larger files. (Use
444 <filename>/tmp</filename> for smaller
445 files.) This directory is generally
446 not flushed at boot-up, but time-based
447 cleanup of files that have not been
448 accessed for a certain time is
449 applied. The same security
451 <filename>/tmp</filename> apply, and
453 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
454 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
455 or similar calls should be used to
456 make use of this directory. If
457 applications find the environment
458 variable <varname>$TMP</varname> set
459 they should prefer using the directory
460 specified in it over directly
462 <filename>/var/tmp</filename>.
470 <title>Virtual Kernel and API File Systems</title>
474 <term><filename>/dev</filename></term>
475 <listitem><para>The root directory for
476 device nodes. Usually this directory
478 <literal>devtmpfs</literal> instance,
479 but might be of a different type in
480 sandboxed/containerized setups. This
481 directory is managed jointly by the
483 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
484 and should not be written to by other
485 components. A number of special
486 purpose virtual file systems might be
488 directory.</para></listitem>
492 <term><filename>/dev/shm</filename></term>
493 <listitem><para>Place for POSIX shared
494 memory segments, as created via
495 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
496 directory is flushed on boot, and is a
497 <literal>tmpfs</literal> file
498 system. Since all users have write
499 access to this directory, special care
500 should be taken to avoid name clashes
501 and vulnerabilities. For normal users,
502 shared memory segments in this
503 directory are usually deleted when the
504 user logs out. Usually it is a better
505 idea to use memory mapped files in
506 <filename>/run</filename> (for system
508 <varname>$XDG_RUNTIME_DIR</varname>
509 (for user programs) instead of POSIX
510 shared memory segments, since they
511 directories are not world-writable and
512 hence not vulnerable to
513 security-sensitive name
514 clashes.</para></listitem>
518 <term><filename>/proc</filename></term>
519 <listitem><para>A virtual kernel file
520 system exposing the process list and
521 other functionality. This file system
522 is mostly an API to interface with the
523 kernel and not a place where normal
524 files may be stored. For details, see
525 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
526 number of special purpose virtual file
527 systems might be mounted below this
528 directory.</para></listitem>
532 <term><filename>/proc/sys</filename></term>
533 <listitem><para>A hierarchy below
534 <filename>/proc</filename> that
535 exposes a number of kernel
536 tunables. The primary way to configure
537 the settings in this API file tree is
539 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
540 files. In sandboxed/containerized
541 setups this directory is generally
542 mounted read-only.</para></listitem>
546 <term><filename>/sys</filename></term>
547 <listitem><para>A virtual kernel file
548 system exposing discovered devices and
549 other functionality. This file system
550 is mostly an API to interface with the
551 kernel and not a place where normal
552 files may be stored. In
553 sandboxed/containerized setups this
554 directory is generally mounted
555 read-only. A number of special purpose
556 virtual file systems might be mounted
558 directory.</para></listitem>
566 <title>Compatibility Symlinks</title>
570 <term><filename>/bin</filename></term>
571 <term><filename>/sbin</filename></term>
572 <term><filename>/usr/sbin</filename></term>
574 <listitem><para>These compatibility
576 <filename>/usr/bin</filename>,
577 ensuring that scripts and binaries
578 referencing these legacy paths
579 correctly find their binaries.</para></listitem>
583 <term><filename>/lib</filename></term>
585 <listitem><para>This compatibility
587 <filename>/usr/lib</filename>,
588 ensuring that programs referencing
589 this legacy path correctly find
590 their resources.</para></listitem>
594 <term><filename>/lib64</filename></term>
596 <listitem><para>On some architecture
597 ABIs this compatibility symlink points
598 to <varname>$libdir</varname>,
599 ensuring that binaries referencing
600 this legacy path correctly find their
601 dynamic loader. This symlink only
602 exists on architectures whose ABI
603 places the dynamic loader in this
604 path.</para></listitem>
608 <term><filename>/var/run</filename></term>
610 <listitem><para>This compatibility
612 <filename>/run</filename>, ensuring
613 that programs referencing this legacy
614 path correctly find their runtime
615 data.</para></listitem>
622 <title>System Packages</title>
624 <para>Developers of system packages should follow
625 strict rules when placing their own files in the file
626 system. The following table lists recommended
627 locations for specific types of files.</para>
630 <title>System Package Data Location</title>
631 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
632 <colspec colname="directory" />
633 <colspec colname="purpose" />
636 <entry>Directory</entry>
637 <entry>Purpose</entry>
642 <entry><filename>/usr/bin</filename></entry>
643 <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>
646 <entry><filename>$libdir</filename></entry>
647 <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>
650 <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
651 <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
654 <entry><filename>$libdir/<replaceable>package</replaceable></filename></entry>
655 <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>
658 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
659 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
662 <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
663 <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>
666 <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
667 <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>
670 <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
671 <entry>Runtime log data for the package.</entry>
674 <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
675 <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>
678 <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
679 <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>
682 <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
683 <entry>Persistent log data of the package.</entry>
686 <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
687 <entry>Persistent spool/queue data of the package.</entry>
695 <title>See Also</title>
697 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
698 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
699 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
700 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
701 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>