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 specificaly 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>System libraries and
287 data.</para></listitem>
291 <term><filename>/usr/lib64</filename></term>
292 <listitem><para>Secondary library
293 directory for placing 64bit versions
294 of system libraries in, if the primary
295 architecture of the system is 32bit,
296 and <filename>/usr/lib64</filename> is
297 defined in the platform ABI. This
298 directory should not be used for
299 package-specific data, unless this
300 data requires 64bit-specific versions,
301 too.</para></listitem>
305 <term><filename>/usr/share</filename></term>
306 <listitem><para>Resources shared
307 betwen multiple packages, such as
308 documentation, man pages, time zone
309 information, fonts and other
310 resources. Usually, the precise
311 location and format of files stored
312 below this directory is subject to
313 specifications that ensure
314 interoperability.</para></listitem>
318 <term><filename>/usr/share/doc</filename></term>
319 <listitem><para>Documentation for the
320 operating system or system
321 packages.</para></listitem>
325 <term><filename>/usr/share/factory/etc</filename></term>
326 <listitem><para>Repository for
327 vendor-supplied default configuration
328 files. This directory should be
329 populated with pristine vendor versions
330 of all configuration files that may be
332 <filename>/etc</filename>. This is
333 useful to compare the local
334 configuration of a system with vendor
335 defaults and to populate the local
337 defaults.</para></listitem>
341 <term><filename>/usr/share/factory/var</filename></term>
343 <listitem><para>Similar to
344 <filename>/usr/share/factory/etc</filename>
345 but for vendor versions of files in
346 the variable, persistent data
348 <filename>/var</filename>.</para></listitem>
355 <title>Persistent Variable System Data</title>
359 <term><filename>/var</filename></term>
360 <listitem><para>Persistent, variable
361 system data. Must be writable. This
362 directory might be pre-populated with
363 vendor-supplied data, but applications
364 should be able to reconstruct
365 necessary files and directories in
366 this subhierarchy should they be
367 missing, as the system might start up
368 without this directory being
369 populated. Persistency is recommended,
370 but optional, to support ephemeral
371 systems. This directory might become
372 available or writable only very late
373 during boot. Components that are
374 required to operate during early boot
375 hence shall not unconditionally rely
376 on this directory.</para></listitem>
380 <term><filename>/var/cache</filename></term>
381 <listitem><para>Persistent system
382 cache data. System components may
383 place non-essential data in this
384 directory. Flushing this directory
385 should have no effect on operation of
386 programs, except for increased
387 runtimes necessary to rebuild these
388 caches.</para></listitem>
392 <term><filename>/var/lib</filename></term>
393 <listitem><para>Persistent system
394 data. System components may
395 place private data in this
396 directory.</para></listitem>
400 <term><filename>/var/log</filename></term>
401 <listitem><para>Persistent system
402 logs. System components may place
403 private logs in this directory, though
404 it is recommended to do most logging
406 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
408 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
409 calls.</para></listitem>
413 <term><filename>/var/spool</filename></term>
414 <listitem><para>Persistent system
415 spool data, such as printer or mail
416 queues.</para></listitem>
420 <term><filename>/var/tmp</filename></term>
421 <listitem><para>The place for larger
422 and persistent temporary files. In
423 contrast to <filename>/tmp</filename>
424 this directory is usually mounted from
425 a persistent physical file system and
426 can thus accept larger files. (Use
427 <filename>/tmp</filename> for smaller
428 files.) This directory is generally
429 not flushed at boot-up, but time-based
430 cleanup of files that have not been
431 accessed for a certain time is
432 applied. The same security
434 <filename>/tmp</filename> apply, and
436 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
437 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
438 or similar calls should be used to
439 make use of this directory. If
440 applications find the environment
441 variable <varname>$TMP</varname> set
442 they should prefer using the directory
443 specified in it over directly
445 <filename>/var/tmp</filename>.
453 <title>Virtual Kernel and API File Systems</title>
457 <term><filename>/dev</filename></term>
458 <listitem><para>The root directory for
459 device nodes. Usually this directory
461 <literal>devtmpfs</literal> instance,
462 but might be of a different type in
463 sandboxed/containerized setups. This
464 directory is managed jointly by the
466 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
467 and should not be written to by other
468 components. A number of special
469 purpose virtual file systems might be
471 directory.</para></listitem>
475 <term><filename>/dev/shm</filename></term>
476 <listitem><para>Place for POSIX shared
477 memory segments, as created via
478 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
479 directory is flushed on boot, and is a
480 <literal>tmpfs</literal> file
481 system. Since all users have write
482 access to this directory, special care
483 should be taken to avoid name clashes
484 and vulnerabilities. For normal users,
485 shared memory segments in this
486 directory are usually deleted when the
487 user logs out. Usually it is a better
488 idea to use memory mapped files in
489 <filename>/run</filename> (for system
491 <varname>$XDG_RUNTIME_DIR</varname>
492 (for user programs) instead of POSIX
493 shared memory segments, since they
494 directories are not world-writable and
495 hence not vulnerable to
496 security-sensitive name
497 clashes.</para></listitem>
501 <term><filename>/proc</filename></term>
502 <listitem><para>A virtual kernel file
503 system exposing the process list and
504 other functionality. This file system
505 is mostly an API to interface with the
506 kernel and not a place where normal
507 files may be stored. For details, see
508 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
509 number of special purpose virtual file
510 systems might be mounted below this
511 directory.</para></listitem>
515 <term><filename>/proc/sys</filename></term>
516 <listitem><para>A hierarchy below
517 <filename>/proc</filename> that
518 exposes a number of kernel
519 tunables. The primary way to configure
520 the settings in this API file tree is
522 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
523 files. In sandboxed/containerized
524 setups this directory is generally
525 mounted read-only.</para></listitem>
529 <term><filename>/sys</filename></term>
530 <listitem><para>A virtual kernel file
531 system exposing discovered devices and
532 other functionality. This file system
533 is mostly an API to interface with the
534 kernel and not a place where normal
535 files may be stored. In
536 sandboxed/containerized setups this
537 directory is generally mounted
538 read-only. A number of special purpose
539 virtual file systems might be mounted
541 directory.</para></listitem>
549 <title>Compatibility Symlinks</title>
553 <term><filename>/bin</filename></term>
554 <term><filename>/sbin</filename></term>
555 <term><filename>/usr/sbin</filename></term>
557 <listitem><para>These compatibility
559 <filename>/usr/bin</filename>,
560 ensuring that scripts and binaries
561 referencing these legacy paths
562 correctly find their binaries.</para></listitem>
566 <term><filename>/lib</filename></term>
568 <listitem><para>This compatibility
570 <filename>/usr/lib</filename>,
571 ensuring that binaries referencing
572 this legacy path correctly find
573 their libraries.</para></listitem>
577 <term><filename>/lib64</filename></term>
579 <listitem><para>This compatibility
581 <filename>/usr/lib64</filename>,
582 ensuring that binaries referencing
583 this legacy path correctly find their
584 libraries. This symlink only exists on
585 architectures whose ABI requires a
586 64bit version of the library
587 directory.</para></listitem>
591 <term><filename>/var/run</filename></term>
593 <listitem><para>This compatibility
595 <filename>/run</filename>, ensuring
596 that programs referencing this legacy
597 path correctly find their runtime
598 data.</para></listitem>
605 <title>System Packages</title>
607 <para>Developers of system packages should follow
608 strict rules when placing their own files in the file
609 system. The following table lists recommended
610 locations for specific types of files.</para>
613 <title>System Package Data Location</title>
614 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
615 <colspec colname="directory" />
616 <colspec colname="purpose" />
619 <entry>Directory</entry>
620 <entry>Purpose</entry>
625 <entry><filename>/usr/bin</filename></entry>
626 <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. 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 take to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
629 <entry><filename>/usr/lib</filename></entry>
630 <entry>Public shared libraries of the package, compiled for the primary architecture of the operating system. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
633 <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
634 <entry>Private other vendor resources of the package, including private binaries and libraries, but also including any other kind of read-only vendor data.</entry>
637 <entry><filename>/usr/lib64</filename></entry>
638 <entry>Public shared libraries of the package, compiled for the secondary, 64bit architecture, if this is part of the platform ABI of the architecture.</entry>
641 <entry><filename>/usr/lib64/<replaceable>package</replaceable></filename></entry>
642 <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between primary and secondary architectures. Note that this generally does not include private binaries since binaries of the primary architecture may generally be invoked from secondary architecture code just fine.</entry>
645 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
646 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
649 <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
650 <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 directores from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry>
653 <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
654 <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>
657 <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
658 <entry>Runtime log data for the package.</entry>
661 <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
662 <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>
665 <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
666 <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>
669 <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
670 <entry>Persistent log data of the package.</entry>
673 <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
674 <entry>Persistent spool/queue data of the package.</entry>
682 <title>See Also</title>
684 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
685 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
686 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
687 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,