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).
82 <term><filename>/boot</filename></term>
83 <listitem><para>The boot partition
84 used for bringing up the system. On
85 EFI systems this is possibly the EFI
86 System Partition, also see
87 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
88 directory is usually strictly local
89 to the host, and should be considered
90 read-only, except when a new kernel or
91 boot loader is installed. This
92 directory only exists on systems that
93 run on physical or emulated hardware
95 loaders.</para></listitem>
99 <term><filename>/etc</filename></term>
100 <listitem><para>System-specific
101 configuration. This directory may or
102 may not be read-only. Frequently, this
103 directory is pre-populated with
104 vendor-supplied configuration files,
105 but applications should not make
106 assumptions about this directory
107 being fully populated or populated at
108 all, and should fall back to defaults
109 if configuration is missing.</para></listitem>
113 <term><filename>/home</filename></term>
114 <listitem><para>The location for
116 directories. Possibly shared with
117 other systems, and never
118 read-only. This directory should only
119 be used for normal users, never for
120 system users. This directory and
121 possibly the directories contained
122 within it might only become available
123 or writable in late boot or even only
124 after user authentication. This directory
125 might be placed on limited-functionality
126 network file systems, hence
127 applications should not assume the
128 full set of file API is available on
129 this directory. Applications should
130 generally not reference this directory
131 directly, but via the per-user
132 <varname>$HOME</varname> environment
133 variable, or via the home directory
135 database.</para></listitem>
139 <term><filename>/root</filename></term>
140 <listitem><para>The home directory of
141 the root user. The root user's home
142 directory is located outside of
143 <filename>/home</filename> in order to
144 make sure the root user may log in
145 even without <filename>/home</filename>
147 mounted.</para></listitem>
151 <term><filename>/srv</filename></term>
152 <listitem><para>The place to store
153 general server payload, managed by the
154 administrator. No restrictions are
155 made how this directory is organized
156 internally. Generally writable, and
157 possibly shared among systems. This
158 directory might become available or
159 writable only very late during
160 boot.</para></listitem>
164 <term><filename>/tmp</filename></term>
165 <listitem><para>The place for small
166 temporary files. This directory is
168 a <literal>tmpfs</literal> instance, and
169 should hence not be used for larger
171 <filename>/var/tmp</filename> for
172 larger files.) Since the directory is
173 accessible to other users of the
174 system it is essential that this
175 directory is only written to with the
176 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
178 and related calls. This directory is
179 usually flushed at boot-up. Also,
180 files that are not accessed within a
181 certain time are usually automatically
182 deleted. If applications find the
184 <varname>$TMP</varname> set they
185 should prefer using the directory
186 specified in it over directly
188 <filename>/tmp</filename>.</para></listitem>
195 <title>Runtime Data</title>
199 <term><filename>/run</filename></term>
201 <literal>tmpfs</literal> file system
202 for system packages to place runtime
203 data in. This directory is flushed on
204 boot, and generally writable for
206 only. Always writable.</para></listitem>
210 <term><filename>/run/log</filename></term>
211 <listitem><para>Runtime system
212 logs. System components may place
213 private logs in this directory. Always
215 <filename>/var/log</filename> might
217 yet.</para></listitem>
221 <term><filename>/run/user</filename></term>
222 <listitem><para>Contains per-user
223 runtime directories, each usually
225 <literal>tmpfs</literal>
226 instances. Always writable, flushed at
227 each reboot and when the user logs
228 out. User code should not reference
229 this directory directly, but via the
230 <varname>$XDG_RUNTIME_DIR</varname>
231 environment variable, as documented in
233 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
235 Specification</ulink>.</para></listitem>
241 <title>Vendor-supplied Operating System Resources</title>
246 <term><filename>/usr</filename></term>
247 <listitem><para>Vendor-supplied
248 operating system resources. Usually
249 read-only, but this is not
250 required. Possibly shared between
251 multiple hosts. This directory should
252 not be modified by the administrator,
253 except when installing or removing
255 packages.</para></listitem>
259 <term><filename>/usr/bin</filename></term>
260 <listitem><para>Binaries for user
261 commands, that shall appear in the
262 <varname>$PATH</varname> search
263 path. It is recommended not to place
264 binaries in this directory that are
265 not useful for invocation from a shell
266 (such as daemon binaries); these
267 should be placed in a subdirectory of
268 <filename>/usr/lib</filename>
269 instead.</para></listitem>
273 <term><filename>/usr/include</filename></term>
274 <listitem><para>C and C++ API header
276 libraries.</para></listitem>
280 <term><filename>/usr/lib</filename></term>
281 <listitem><para>Static vendor data
282 that is compatible with all
283 architectures (though not necessarily
284 architecture-independent). Note that
285 this includes internal
286 executables or other binaries that are
287 not regularly invoked from a
288 shell. Such binaries may be for any
289 architecture supported by the
290 system. Do not place public libraries
291 in this directory, use
292 <varname>$libdir</varname> (see
293 below), instead.</para></listitem>
297 <term><varname>$libdir</varname></term>
298 <listitem><para>Location for placing
299 dynamic libraries in. The precise
300 location depends on the operating
301 system and the architecture, and is
303 <filename>/usr/lib</filename>,
304 <filename>/use/lib64</filename> or
305 <filename>/usr/lib/</filename>
306 suffixed by an architecture
307 identifier. This directory should not
308 be used for package-specific data,
310 architecture-dependent, too. To query
311 <varname>$libdir</varname> for the
312 primary architecture of the system,
314 <programlisting># pkg-config --variable=libdir systemd</programlisting></para></listitem>
318 <term><filename>/usr/share</filename></term>
319 <listitem><para>Resources shared
320 between multiple packages, such as
321 documentation, man pages, time zone
322 information, fonts and other
323 resources. Usually, the precise
324 location and format of files stored
325 below this directory is subject to
326 specifications that ensure
327 interoperability.</para></listitem>
331 <term><filename>/usr/share/doc</filename></term>
332 <listitem><para>Documentation for the
333 operating system or system
334 packages.</para></listitem>
338 <term><filename>/usr/share/factory/etc</filename></term>
339 <listitem><para>Repository for
340 vendor-supplied default configuration
341 files. This directory should be
342 populated with pristine vendor versions
343 of all configuration files that may be
345 <filename>/etc</filename>. This is
346 useful to compare the local
347 configuration of a system with vendor
348 defaults and to populate the local
350 defaults.</para></listitem>
354 <term><filename>/usr/share/factory/var</filename></term>
356 <listitem><para>Similar to
357 <filename>/usr/share/factory/etc</filename>
358 but for vendor versions of files in
359 the variable, persistent data
361 <filename>/var</filename>.</para></listitem>
368 <title>Persistent Variable System Data</title>
372 <term><filename>/var</filename></term>
373 <listitem><para>Persistent, variable
374 system data. Must be writable. This
375 directory might be pre-populated with
376 vendor-supplied data, but applications
377 should be able to reconstruct
378 necessary files and directories in
379 this subhierarchy should they be
380 missing, as the system might start up
381 without this directory being
382 populated. Persistency is recommended,
383 but optional, to support ephemeral
384 systems. This directory might become
385 available or writable only very late
386 during boot. Components that are
387 required to operate during early boot
388 hence shall not unconditionally rely
389 on this directory.</para></listitem>
393 <term><filename>/var/cache</filename></term>
394 <listitem><para>Persistent system
395 cache data. System components may
396 place non-essential data in this
397 directory. Flushing this directory
398 should have no effect on operation of
399 programs, except for increased
400 runtimes necessary to rebuild these
401 caches.</para></listitem>
405 <term><filename>/var/lib</filename></term>
406 <listitem><para>Persistent system
407 data. System components may
408 place private data in this
409 directory.</para></listitem>
413 <term><filename>/var/log</filename></term>
414 <listitem><para>Persistent system
415 logs. System components may place
416 private logs in this directory, though
417 it is recommended to do most logging
419 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
421 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
422 calls.</para></listitem>
426 <term><filename>/var/spool</filename></term>
427 <listitem><para>Persistent system
428 spool data, such as printer or mail
429 queues.</para></listitem>
433 <term><filename>/var/tmp</filename></term>
434 <listitem><para>The place for larger
435 and persistent temporary files. In
436 contrast to <filename>/tmp</filename>
437 this directory is usually mounted from
438 a persistent physical file system and
439 can thus accept larger files. (Use
440 <filename>/tmp</filename> for smaller
441 files.) This directory is generally
442 not flushed at boot-up, but time-based
443 cleanup of files that have not been
444 accessed for a certain time is
445 applied. The same security
447 <filename>/tmp</filename> apply, and
449 <citerefentry><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
450 <citerefentry><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
451 or similar calls should be used to
452 make use of this directory. If
453 applications find the environment
454 variable <varname>$TMP</varname> set
455 they should prefer using the directory
456 specified in it over directly
458 <filename>/var/tmp</filename>.
466 <title>Virtual Kernel and API File Systems</title>
470 <term><filename>/dev</filename></term>
471 <listitem><para>The root directory for
472 device nodes. Usually this directory
474 <literal>devtmpfs</literal> instance,
475 but might be of a different type in
476 sandboxed/containerized setups. This
477 directory is managed jointly by the
479 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
480 and should not be written to by other
481 components. A number of special
482 purpose virtual file systems might be
484 directory.</para></listitem>
488 <term><filename>/dev/shm</filename></term>
489 <listitem><para>Place for POSIX shared
490 memory segments, as created via
491 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
492 directory is flushed on boot, and is a
493 <literal>tmpfs</literal> file
494 system. Since all users have write
495 access to this directory, special care
496 should be taken to avoid name clashes
497 and vulnerabilities. For normal users,
498 shared memory segments in this
499 directory are usually deleted when the
500 user logs out. Usually it is a better
501 idea to use memory mapped files in
502 <filename>/run</filename> (for system
504 <varname>$XDG_RUNTIME_DIR</varname>
505 (for user programs) instead of POSIX
506 shared memory segments, since those
507 directories are not world-writable and
508 hence not vulnerable to
509 security-sensitive name
510 clashes.</para></listitem>
514 <term><filename>/proc</filename></term>
515 <listitem><para>A virtual kernel file
516 system exposing the process list and
517 other functionality. This file system
518 is mostly an API to interface with the
519 kernel and not a place where normal
520 files may be stored. For details, see
521 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
522 number of special purpose virtual file
523 systems might be mounted below this
524 directory.</para></listitem>
528 <term><filename>/proc/sys</filename></term>
529 <listitem><para>A hierarchy below
530 <filename>/proc</filename> that
531 exposes a number of kernel
532 tunables. The primary way to configure
533 the settings in this API file tree is
535 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
536 files. In sandboxed/containerized
537 setups this directory is generally
538 mounted read-only.</para></listitem>
542 <term><filename>/sys</filename></term>
543 <listitem><para>A virtual kernel file
544 system exposing discovered devices and
545 other functionality. This file system
546 is mostly an API to interface with the
547 kernel and not a place where normal
548 files may be stored. In
549 sandboxed/containerized setups this
550 directory is generally mounted
551 read-only. A number of special purpose
552 virtual file systems might be mounted
554 directory.</para></listitem>
562 <title>Compatibility Symlinks</title>
566 <term><filename>/bin</filename></term>
567 <term><filename>/sbin</filename></term>
568 <term><filename>/usr/sbin</filename></term>
570 <listitem><para>These compatibility
572 <filename>/usr/bin</filename>,
573 ensuring that scripts and binaries
574 referencing these legacy paths
575 correctly find their binaries.</para></listitem>
579 <term><filename>/lib</filename></term>
581 <listitem><para>This compatibility
583 <filename>/usr/lib</filename>,
584 ensuring that programs referencing
585 this legacy path correctly find
586 their resources.</para></listitem>
590 <term><filename>/lib64</filename></term>
592 <listitem><para>On some architecture
593 ABIs this compatibility symlink points
594 to <varname>$libdir</varname>,
595 ensuring that binaries referencing
596 this legacy path correctly find their
597 dynamic loader. This symlink only
598 exists on architectures whose ABI
599 places the dynamic loader in this
600 path.</para></listitem>
604 <term><filename>/var/run</filename></term>
606 <listitem><para>This compatibility
608 <filename>/run</filename>, ensuring
609 that programs referencing this legacy
610 path correctly find their runtime
611 data.</para></listitem>
618 <title>System Packages</title>
620 <para>Developers of system packages should follow
621 strict rules when placing their own files in the file
622 system. The following table lists recommended
623 locations for specific types of files.</para>
626 <title>System Package Data Location</title>
627 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
628 <colspec colname="directory" />
629 <colspec colname="purpose" />
632 <entry>Directory</entry>
633 <entry>Purpose</entry>
638 <entry><filename>/usr/bin</filename></entry>
639 <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>
642 <entry><filename>$libdir</filename></entry>
643 <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>
646 <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
647 <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
650 <entry><filename>$libdir/<replaceable>package</replaceable></filename></entry>
651 <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>
654 <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
655 <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
658 <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
659 <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>
662 <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
663 <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>
666 <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
667 <entry>Runtime log data for the package.</entry>
670 <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
671 <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>
674 <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
675 <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>
678 <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
679 <entry>Persistent log data of the package.</entry>
682 <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
683 <entry>Persistent spool/queue data of the package.</entry>
691 <title>See Also</title>
693 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
694 <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
695 <citerefentry><refentrytitle>systemd-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
696 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
697 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>