Funtoo Filesystem Hierarchy
The Funtoo Filesystem Hierarchy is derived from the Filesystem Hierarchy Standard, and updated to address Funtoo Linux and Gentoo Linux-specific conventions.
License and Copyright
In accordance with the upstream documentation, this document is distributed under the following terms:
Copyright © 1994-2004 Daniel Quinlan
Copyright © 2001-2004 Paul 'Rusty' Russell
Copyright © 2003-2004 Christopher Yeoh
Copyright © 2010 Funtoo Technologies
Permission is granted to make and distribute verbatim copies of this standard provided the copyright and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this standard under the conditions for verbatim copying, provided also that the title page is labeled as modified including a reference to the original standard, provided that information on retrieving the original standard is included, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this standard into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the copyright holder.
Introduction
This standard enables:
- Software to predict the location of installed files and directories, and
- Users to predict the location of installed files and directories.
We do this by:
- Specifying guiding principles for each area of the filesystem,
- Specifying the minimum files and directories required,
- Enumerating exceptions to the principles, and
- Enumerating specific cases where there has been historical conflict.
The FHS document is used by:
- Independent software suppliers to create applications which are FHS compliant, and work with distributions which are FHS complaint,
- OS creators to provide systems which are FHS compliant, and
- Users to understand and maintain the FHS compliance of a system.
The FHS document has a limited scope:
- Local placement of local files is a local issue, so FHS does not attempt to usurp system administrators.
- FHS addresses issues where file placements need to be coordinated between multiple parties such as local sites, distributions, applications, documentation, etc.
The Filesystem
This standard assumes that the operating system underlying an FHS-compliant file system supports the same basic security features found in most UNIX filesystems.
It is possible to define two independent distinctions among files: shareable vs. unshareable and variable vs. static. In general, files that differ in either of these respects should be located in different directories. This makes it easy to store files with different usage characteristics on different filesystems.
"Shareable" files are those that can be stored on one host and used on others. "Unshareable" files are those that are not shareable. For example, the files in user home directories are shareable whereas device lock files are not.
"Static" files include binaries, libraries, documentation files and other files that do not change without system administrator intervention. "Variable" files are files that are not static.
Tip Rationale
Shareable files can be stored on one host and used on several others. Typically, however, not all files in the filesystem hierarchy are shareable and so each system has local storage containing at least its unshareable files. It is convenient if all the files a system requires that are stored on a foreign host can be made available by mounting one or a few directories from the foreign host.
Static and variable files should be segregated because static files, unlike variable files, can be stored on read-only media and do not need to be backed up on the same schedule as variable files.
Historical UNIX-like filesystem hierarchies contained both static and variable files under both /usr and /etc. In order to realize the advantages mentioned above, the /var hierarchy was created and all variable files were transferred from /usr to /var. Consequently /usr can now be mounted read-only (if it is a separate filesystem). Variable files have been transferred from /etc to /var over a longer period as technology has permitted.
Here is an example of a FHS-compliant system. (Other FHS-compliant layouts are possible.)
| shareable | unshareable | |
|---|---|---|
| static | /usr | /etc |
| /opt | /boot | |
| variable | /var/mail | /var/run |
| /var/spool/news | /var/lock |
The Root Filesystem
The /usr Hierarchy
/usr is the second major section of the filesystem. /usr is shareable, read-only data. That means that /usr should be shareable between various FHS-compliant hosts and must not be written to. Any information that is host-specific or varies with time is stored elsewhere.
Large software packages must not use a direct subdirectory under the /usr hierarchy.
Requirements
The following directories, or symbolic links to directories, are required in /usr.
Directory Description bin Most user commands include Header files included by C programs lib Libraries local Local hierarchy (empty after main installation) sbin Non-vital system binaries share Architecture-independent data
Specific Options
Directory Description X11R6 XWindow System, version 11 release 6 (optional) games Games and educational binaries (optional) lib<qual> Alternate Format Libraries (optional) src Source code (optional)
An exception is made for the X Window System because of considerable precedent and widely-accepted practice.
The following symbolic links to directories may be present. This possibility is based on the need to preserve compatibility with older systems until all implementations can be assumed to use the /var hierarchy.
/usr/spool -> /var/spool /usr/tmp -> /var/tmp /usr/spool/locks -> /var/lock
Once a system no longer requires any one of the above symbolic links, the link may be removed, if desired.
/usr/X11R6 : X Window System, Version 11 Release 6 (optional)
This hierarchy is reserved for the X Window System, version 11 release 6, and related files.
To simplify matters and make XFree86 more compatible with the X Window System on other systems, the following symbolic links must be present if /usr/X11R6 exists:
/usr/bin/X11 -> /usr/X11R6/bin /usr/lib/X11 -> /usr/X11R6/lib/X11 /usr/include/X11 -> /usr/X11R6/include/X11
In general, software must not be installed or managed via the above symbolic links. They are intended for utilization by users only. The difficulty is related to the release version of the X Window System — in transitional periods, it is impossible to know what release of X11 is in use.
Specific Options
Host-specific data in /usr/X11R6/lib/X11 should be interpreted as a demonstration file. Applications requiring information about the current host must reference a configuration file in /etc/X11, which may be linked to a file in /usr/X11R6/lib. [1]
/usr/bin : Most user commands
This is the primary directory of executable commands on the system.
Specific Options
The following directories, or symbolic links to directories, must be in /usr/bin, if the corresponding subsystem is installed:
Directory Description mh Commands for the MH mail handling system (optional)
/usr/bin/X11 must be a symlink to /usr/X11R6/bin if the latter exists.
The following files, or symbolic links to files, must be in /usr/bin, if the corresponding subsystem is installed:
Command Description perl The Practical Extraction and Report Language (optional) python The Python interpreted language (optional) tclsh Simple shell containing Tcl interpreter (optional) wish Simple Tcl/Tk windowing shell (optional) expect Program for interactive dialog (optional)
Tip Rationale
Because shell script interpreters (invoked with #!<path> on the first line of a shell script) cannot rely on a path, it is advantageous to standardize their locations. The Bourne shell and C-shell interpreters are already fixed in /bin, but Perl, Python, and Tcl are often found in many different places. They may be symlinks to the physical location of the shell interpreters.
/usr/include : Directory for standard include files.
This is where all of the system's general-use include files for the C programming language should be placed.
Specific Options
The following directories, or symbolic links to directories, must be in /usr/include, if the corresponding subsystem is installed:
Directory Description bsd BSD compatibility include files (optional)
The symbolic link /usr/include/X11 must link to /usr/X11R6/include/X11 if the latter exists.
/usr/lib : Libraries for programming and packages
/usr/lib includes object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts. [2]
Applications may use a single subdirectory under /usr/lib. If an application uses a subdirectory, all architecture-dependent data exclusively used by the application must be placed within that subdirectory. [3]
Specific Options
For historical reasons, /usr/lib/sendmail must be a symbolic link to /usr/sbin/sendmail if the latter exists. [4]
If /lib/X11 exists, /usr/lib/X11 must be a symbolic link to /lib/X11, or to whatever /lib/X11 is a symbolic link to. [5]
/usr/lib<qual> : Alternate format libraries (optional)
/usr/lib<qual> performs the same role as /usr/lib for an alternate binary format, except that the symbolic links /usr/lib<qual>/sendmail and /usr/lib<qual>/X11 are not required. [6]
/usr/local : Local hierarchy
The /usr/local hierarchy is for use by the system administrator when installing software locally. It needs to be safe from being overwritten when the system software is updated. It may be used for programs and data that are shareable amongst a group of hosts, but not found in /usr.
Locally installed software must be placed within /usr/local rather than /usr unless it is being installed to replace or upgrade software in /usr. [7]
Requirements
The following directories, or symbolic links to directories, must be in /usr/local
Directory Description bin Local binaries etc Host-specific system configuration for local binaries games Local game binaries include Local C header files lib Local libraries man Local online manuals sbin Local system binaries share Local architecture-independent hierarchy src Local source code
No other directories, except those listed below, may be in /usr/local after first installing a FHS-compliant system.
Specific Options
If directories /lib<qual> or /usr/lib<qual> exist, the equivalent directories must also exist in /usr/local.
/usr/local/etc may be a symbolic link to /etc/local.
Tip Rationale
The consistency of /usr/local/etc is beneficial to installers, and is already used in other systems. As all of /usr/local needs to be backed up to reproduce a system, it introduces no additional maintenance overhead, but a symlink to /etc/local is suitable if systems want alltheir configuration under one hierarchy.
Note that /usr/etc is still not allowed: programs in /usr should place configuration files in /etc.
The requirements for the contents of this directory are the same as /usr/share. The only additional constraint is that /usr/local/share/man and /usr/local/man directories must be synonomous (usually this means that one of them must be a symbolic link). [8]
/usr/sbin : Non-essential standard system binaries
This directory contains any non-essential binaries used exclusively by the system administrator. System administration programs that are required for system repair, system recovery, mounting /usr, or other essential functions must be placed in /sbin instead. [9]
The /usr/share hierarchy is for all read-only architecture independent data files. [10]
This hierarchy is intended to be shareable among all architecture platforms of a given OS; thus, for example, a site with i386, Alpha, and PPC platforms might maintain a single /usr/share directory that is centrally-mounted. Note, however, that /usr/share is generally not intended to be shared by different OSes or by different releases of the same OS.
Any program or package which contains or requires data that doesn't need to be modified should store that data in /usr/share (or /usr/local/share, if installed locally). It is recommended that a subdirectory be used in /usr/share for this purpose.
Game data stored in /usr/share/games must be purely static data. Any modifiable files, such as score files, game play logs, and so forth, should be placed in /var/games.
Requirements
The following directories, or symbolic links to directories, must be in /usr/share
Directory Description man Online manuals misc Miscellaneous architecture-independent data
Specific Options
The following directories, or symbolic links to directories, must be in /usr/share, if the corresponding subsystem is installed:
Directory Description dict Word lists (optional) doc Miscellaneous documentation (optional) games Static data files for /usr/games (optional) info GNU Info system s primary directory (optional) locale Locale information (optional) nls Message catalogs for Native language support (optional) sgml SGML data (optional) terminfo Directories for terminfo database (optional) tmac troff macros not distributed with groff (optional) xml XML data (optional) zoneinfo Timezone information and configuration (optional)
It is recommended that application-specific, architecture-independent directories be placed here. Such directories include groff, perl, ghostscript, texmf, and kbd (Linux) or syscons (BSD). They may, however, be placed in /usr/lib for backwards compatibility, at the distributor's discretion. Similarly, a /usr/lib/games hierarchy may be used in addition to the /usr/share/games hierarchy if the distributor wishes to place some game data there.
This directory is the home for word lists on the system; Traditionally this directory contains only the English words file, which is used by look(1) and various spelling programs. words may use either American or British spelling.
Tip Rationale
The reason that only word lists are located here is that they are the only files common to all spell checkers.
Specific Options
The following files, or symbolic links to files, must be in /usr/share/dict, if the corresponding subsystem is installed:
File Description words List of English words (optional)
Sites that require both American and British spelling may link words to /usr/share/dict/american-english or /usr/share/dict/british-english.
Word lists for other languages may be added using the English name for that language, e.g., /usr/share/dict/french, /usr/share/dict/danish, etc. These should, if possible, use an ISO 8859 character set which is appropriate for the language in question; if possible the Latin1 (ISO 8859-1) character set should be used (this is often not possible).
Other word lists must be included here, if present.
This section details the organization for manual pages throughout the system, including /usr/share/man. Also refer to the section on /var/cache/man.
The primary <mandir> of the system is /usr/share/man. /usr/share/man contains manual information for commands and data under the / and /usr filesystems. [11]
Manual pages are stored in <mandir>/<locale>/man
Cite error: <ref> tags exist, but no <references/> tag was found
