NAME
file-hierarchy - File system hierarchy overview
DESCRIPTION
Operating systems using the systemd(1) system and service manager are organized based on a file system hierarchy inspired by UNIX, more specifically the hierarchy described in the File System Hierarchy[1] specification and hier(7), with various extensions, partially documented in the XDG Base Directory Specification[2] and XDG User Directories[3]. This manual page describes a more generalized, though minimal and modernized subset of these specifications that defines more strictly the suggestions and restrictions systemd makes on the file system hierarchy. Note that this document makes no attempt to define the directory structure comprehensively, it only documents a skeleton of a directory tree, that downstreams can extend. Because of that traditional directories such as /usr/include/ or /var/spool/ are not covered, even though it might (or might not) make a lot of sense to include them in the structure of an actually deployed OS.
Many of the paths described here can be queried with the systemd-path(1) tool.
GENERAL STRUCTURE
/
/boot/
/efi/
/etc/
/home/
/root/
/srv/
/tmp/
If applications find the environment variable $TMPDIR set, they should use the directory specified in it instead of /tmp/ (see environ(7) and IEEE Std 1003.1[4] for details).
Since /tmp/ is accessible to other users of the system, it is essential that files and subdirectories under this directory are only created with mkstemp(3), mkdtemp(3), and similar calls. For more details, see Using /tmp/ and /var/tmp/ Safely[5].
RUNTIME DATA
/run/
/run/log/
/run/user/
VENDOR-SUPPLIED OPERATING SYSTEM RESOURCES
/usr/
/usr/bin/
/usr/lib/
/usr/lib/arch-id/
To query $libdir for the primary architecture of the system, invoke:
systemd-path system-library-arch/usr/share/
Note that resources placed in this directory typically are under shared ownership, i.e. multiple different packages have provided and consumed these resources, on equal footing, without any obvious primary owner. This makes things systematically different from /usr/lib/, where ownership is generally not shared.
/usr/share/doc/
/usr/share/factory/etc/
/usr/share/factory/var/
PERSISTENT VARIABLE SYSTEM DATA
/var/
/var/cache/
/var/lib/
/var/log/
/var/tmp/
If applications find the environment variable $TMPDIR set, they should use the directory specified in it instead of /var/tmp/ (see environ(7) for details).
The same security restrictions as with /tmp/ apply: mkstemp(3), mkdtemp(3), and similar calls should be used. For further details about this directory, see Using /tmp/ and /var/tmp/ Safely[5].
VIRTUAL KERNEL AND API FILE SYSTEMS
/dev/
/dev/shm/
/proc/
/proc/sys/
/sys/
/sys/fs/cgroup/
COMPATIBILITY SYMLINKS
/bin/, /sbin/, /usr/sbin/
/lib/
/lib64/
/var/run/
HOME DIRECTORY
User applications may want to place files and directories in the user's home directory. They should follow the following basic structure. Note that some of these directories are also standardized (though more weakly) by the XDG Base Directory Specification[2]. Additional locations for high-level user resources are defined by xdg-user-dirs[3].
~/.cache/
~/.config/
~/.local/bin/
~/.local/lib/
~/.local/lib/arch-id/
~/.local/share/
~/.local/state/
WRITE ACCESS
Unprivileged Write Access
Unprivileged processes generally lack write access to most of the hierarchy.
The exceptions for normal users are /tmp/, /var/tmp/, /dev/shm/, as well as the home directory $HOME (usually found below /home/) and the runtime directory $XDG_RUNTIME_DIR (found below /run/user/) of the user, which are all writable.
For unprivileged system processes, only /tmp/, /var/tmp/ and /dev/shm/ are writable. If an unprivileged system process needs a private writable directory in /var/ or /run/, it is recommended to either create it before dropping privileges in the daemon code, to create it via tmpfiles.d(5) fragments during boot, or via the StateDirectory= and RuntimeDirectory= directives of service units (see systemd.unit(5) for details).
/tmp/, /var/tmp/ and /dev/shm/ should be mounted nosuid and nodev, which means that set-user-id mode and character or block special devices are not interpreted on those file systems. In general it is not possible to mount them noexec, because various programs use those directories for dynamically generated or optimized code, and with that flag those use cases would break. Using this flag is OK on special-purpose installations or systems where all software that may be installed is known and does not require such functionality. See the discussion of nosuid/nodev/noexec in mount(8) and PROT_EXEC in mmap(2).
Lack of Write Access on Read-Only Systems and during System Recovery
As noted above, some systems operate with the /usr and /etc hierarchies mounted read-only, possibly only allowing write access during package upgrades. Other part of the hierarchy are generally mounted read-write (in particular /var and /var/tmp), but may be read-only when the kernel remounts the file system read-only in response to errors, or when the system is booted read-only for recovery purposes. To the extent reasonable, applications should be prepared to execute without write access, so that for example, failure to save non-essential data to /var/cache/ or failure to create a custom log file under /var/log does not prevent the application from running.
The /run/ directory is available since the earliest boot and is always writable. It should be used for any runtime data and sockets, so that write access to e.g. /etc or /var is not needed.
NODE TYPES
Unix file systems support different types of file nodes, including regular files, directories, symlinks, character and block device nodes, sockets and FIFOs.
It is strongly recommended that /dev/ is the only location below which device nodes shall be placed. Similarly, /run/ shall be the only location to place sockets and FIFOs. Regular files, directories and symlinks may be used in all directories.
Applications should expect that a security policy might be enforced on a system that enforces these rules.
SYSTEM PACKAGES
Developers of system packages should follow strict rules when placing their files in the file system. The following table lists recommended locations for specific types of files supplied by the vendor.
Table 1. System package vendor files locations
| Directory | Purpose |
| /usr/bin/ | Package executables that shall appear in the $PATH 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. |
| /usr/lib/ arch-id / | 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. |
| /usr/lib/ package / | Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data. |
| /usr/lib/ arch-id / package / | 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. |
Additional static vendor files with shared ownership may be installed in the /usr/share/ hierarchy to the locations defined by the various relevant specifications.
The following directories shall be used by the package for local configuration and files created during runtime:
Table 2. System package variable files locations
| Directory | Purpose |
| /etc/ package / | 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 tmpfiles.d (5) fragment may be used to copy or symlink the necessary files and directories from /usr/share/factory/ during boot, via the "L" or "C" directives. |
| /run/ package / | 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 tmpfiles.d (5) fragment may be used to create the necessary directories during boot, or the RuntimeDirectory= directive of service units may be used to create them at service startup (see systemd.unit (5) for details). |
| /run/log/ package / | 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. |
| /var/cache/ package / | 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. To create an empty directory, a tmpfiles.d (5) fragment or the CacheDirectory= directive of service units (see systemd.unit (5)) may be used. |
| /var/lib/ package / | 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. To create an empty directory, a tmpfiles.d (5) fragment or the StateDirectory= directive of service units (see systemd.unit (5)) may be used. |
| /var/log/ package / | Persistent log data of the package. As above, the package should make sure to create this directory if necessary, possibly using tmpfiles.d (5) or LogsDirectory= (see systemd.exec (5)), as it might be missing. |
USER PACKAGES
Programs running in user context should follow strict rules when placing their own files in the user's home directory. The following table lists recommended locations in the home directory for specific types of files supplied by the vendor if the application is installed in the home directory. (User applications installed system-wide are covered by the rules outlined above for vendor files.)
Table 3. Vendor package file locations under the home directory of the user
| Directory | Purpose |
| ~/.local/bin/ | Package executables that shall appear in the $PATH 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. |
| ~/.local/lib/ arch-id / | Public shared libraries of the package. As above, be careful with using overly generic names, and pick unique names for your libraries to place here to avoid name clashes. |
| ~/.local/lib/ package / | Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data. |
| ~/.local/lib/ arch-id / package / | Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. |
Additional static vendor files with shared ownership may be installed in the ~/.local/share/ hierarchy, mirroring the subdirectories specified in the section "Vendor-supplied operating system resources" above.
The following directories shall be used by the package for per-user local configuration and files created during runtime:
Table 4. User package variable file locations
| Directory | Purpose |
| ~/.config/ package / | User-specific configuration for the package. It is required to default to safe fallbacks if this configuration is missing. |
| $XDG_RUNTIME_DIR / package / | User runtime data for the package. |
| ~/.cache/ package / | 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. |
| ~/.local/state/ package / | Persistent state data of the package. |
SEE ALSO
systemd(1), hier(7), systemd-path(1), systemd-gpt-auto-generator(8), sysctl.d(5), tmpfiles.d(5), pkg-config(1), systemd.unit(5)
NOTES
- 1.
File System Hierarchy
- 2.
XDG Base Directory Specification
- 3.
XDG User Directories
- 4.
IEEE Std 1003.1
- 5.
Using /tmp/ and /var/tmp/ Safely
- 6.
Multiarch Architecture Specifiers (Tuples)