Latest revision as of 20:59, 11 May 2012

The Funtoo Filesystem Hierarchy is derived from the Filesystem Hierarchy Standard, and updated to address Funtoo Linux and Gentoo Linux-specific conventions.

[edit] 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.

[edit] 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.

[edit] 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.)

[edit] The Root Filesystem

[edit] The /usr Hierarchy

[edit] The /var Hierarchy

[edit] Operating System Specific Annex

This section is for additional requirements and recommendations that only apply to a specific operating system. The material in this section should never conflict with the base standard.

[edit] Linux

This is the annex for the Linux operating system.

[edit] / : Root directory

On Linux systems, if the kernel is located in /, we recommend using the names vmlinux or vmlinuz, which have been used in recent Linux kernel source packages.

[edit] /bin : Essential user command binaries (for use by all users)

Linux systems which require them place these additional files into /bin:

* setserial

[edit] /dev : Devices and special files

The following devices must exist under /dev.

/dev/null

   All data written to this device is discarded. A read from this device will return an EOF condition.

/dev/zero

   This device is a source of zeroed out data. All data written to this device is discarded. A read from this device will return as many bytes containing the value zero as was requested.

/dev/tty

   This device is a synonym for the controlling terminal of a process. Once this device is opened, all reads and writes will behave as if the actual controlling terminal device had been opened.

Tip Rationale

Previous versions of the FHS had stricter requirements for /dev. Other devices may also exist in /dev. Device names may exist as symbolic links to other device nodes located in /dev or subdirectories of /dev. There is no requirement concerning major/minor number values.

[edit] /etc : Host-specific system configuration

Linux systems which require them place these additional files into /etc.

   *

     lilo.conf

[edit] /lib64 and /lib32 : 64/32-bit libraries (architecture dependent)

The 64-bit architectures PPC64, s390x, sparc64 and AMD64 must place 64-bit libraries in /lib64, and 32-bit (or 31-bit on s390) libraries in /lib.

The 64-bit architecture IA64 must place 64-bit libraries in /lib.

Tip Rationale

This is a refinement of the general rules for /lib<qual> and /usr/lib<qual>. The architectures PPC64, s390x, sparc64 and AMD64 support support both 32-bit (for s390 more precise 31-bit) and 64-bit programs. Using lib for 32-bit binaries allows existing binaries from the 32-bit systems to work without any changes: such binaries are expected to be numerous. IA-64 uses a different scheme, reflecting the deprecation of 32-bit binaries (and hence libraries) on that architecture.

[edit] /proc : Kernel and process information virtual filesystem

The proc filesystem is the de-facto standard Linux method for handling process and system information, rather than /dev/kmem and other similar methods. We strongly encourage this for the storage and retrieval of process information as well as other kernel and memory information.

[edit] /sbin : Essential system binaries

Linux systems place these additional files into /sbin.

   *

     Second extended filesystem commands (optional):

         o

           badblocks
         o

           dumpe2fs
         o

           e2fsck
         o

           mke2fs
         o

           mklost+found
         o

           tune2fs
   *

     Boot-loader map installer (optional):

         o

           lilo

Optional files for /sbin:

   *

     Static binaries:

         o

           ldconfig
         o

           sln
         o

           ssync

     Static ln (sln) and static sync (ssync) are useful when things go wrong. The primary use of sln (to repair incorrect symlinks in /lib after a poorly orchestrated upgrade) is no longer a major concern now that the ldconfig program (usually located in /usr/sbin) exists and can act as a guiding hand in upgrading the dynamic libraries. Static sync is useful in some emergency situations. Note that these need not be statically linked versions of the standard ln and sync, but may be.

     The ldconfig binary is optional for /sbin since a site may choose to run ldconfig at boot time, rather than only when upgrading the shared libraries. (It's not clear whether or not it is advantageous to run ldconfig on each boot.) Even so, some people like ldconfig around for the following (all too common) situation:

        1.

           I've just removed /lib/<file>.
        2.

           I can't find out the name of the library because ls is dynamically linked, I'm using a shell that doesn't have ls built-in, and I don't know about using "echo *" as a replacement.
        3.

           I have a static sln, but I don't know what to call the link.
   *

     Miscellaneous:

         o

           ctrlaltdel
         o

           kbdrate

     So as to cope with the fact that some keyboards come up with such a high repeat rate as to be unusable, kbdrate may be installed in /sbin on some systems.

     Since the default action in the kernel for the Ctrl-Alt-Del key combination is an instant hard reboot, it is generally advisable to disable the behavior before mounting the root filesystem in read-write mode. Some init suites are able to disable Ctrl-Alt-Del, but others may require the ctrlaltdel program, which may be installed in /sbin on those systems.

[edit] /usr/include : Header files included by C programs

These symbolic links are required if a C or C++ compiler is installed and only for systems not based on glibc.

   /usr/include/asm -> /usr/src/linux/include/asm-<arch>
   /usr/include/linux -> /usr/src/linux/include/linux

[edit] /usr/src : Source code

For systems based on glibc, there are no specific guidelines for this directory. For systems based on Linux libc revisions prior to glibc, the following guidelines and rationale apply:

The only source code that should be placed in a specific location is the Linux kernel source code. It is located in /usr/src/linux.

If a C or C++ compiler is installed, but the complete Linux kernel source code is not installed, then the include files from the kernel source code must be located in these directories:

   /usr/src/linux/include/asm-<arch>
   /usr/src/linux/include/linux

<arch> is the name of the system architecture.

Note Note

/usr/src/linux may be a symbolic link to a kernel source code tree.

Tip Rationale

It is important that the kernel include files be located in /usr/src/linux and not in /usr/include so there are no problems when system administrators upgrade their kernel version for the first time.

[edit] /var/spool/cron : cron and at jobs

This directory contains the variable data for the cron and at programs.

[edit] Appendix

[edit] Background of the FHS

The process of developing a standard filesystem hierarchy began in August 1993 with an effort to restructure the file and directory structure of Linux. The FSSTND, a filesystem hierarchy standard specific to the Linux operating system, was released on February 14, 1994. Subsequent revisions were released on October 9, 1994 and March 28, 1995.

In early 1995, the goal of developing a more comprehensive version of FSSTND to address not only Linux, but other UNIX-like systems was adopted with the help of members of the BSD development community. As a result, a concerted effort was made to focus on issues that were general to UNIX-like systems. In recognition of this widening of scope, the name of the standard was changed to Filesystem Hierarchy Standard or FHS for short.

Volunteers who have contributed extensively to this standard are listed at the end of this document. This standard represents a consensus view of those and other contributors.

[edit] General Guidelines

Here are some of the guidelines that have been used in the development of this standard:

* Solve technical problems while limiting transitional difficulties.
* Make the specification reasonably stable.
* Gain the approval of distributors, developers, and other decision-makers in relevant development groups and encourage their participation.
* Provide a standard that is attractive to the implementors of different UNIX-like systems.

[edit] Scope

This document specifies a standard filesystem hierarchy for FHS filesystems by specifying the location of files and directories, and the contents of some system files.

This standard has been designed to be used by system integrators, package developers, and system administrators in the construction and maintenance of FHS compliant filesystems. It is primarily intended to be a reference and is not a tutorial on how to manage a conforming filesystem hierarchy.

The FHS grew out of earlier work on FSSTND, a filesystem organization standard for the Linux operating system. It builds on FSSTND to address interoperability issues not just in the Linux community but in a wider arena including 4.4BSD-based operating systems. It incorporates lessons learned in the BSD world and elsewhere about multi-architecture support and the demands of heterogeneous networking.

Although this standard is more comprehensive than previous attempts at filesystem hierarchy standardization, periodic updates may become necessary as requirements change in relation to emerging technology. It is also possible that better solutions to the problems addressed here will be discovered so that our solutions will no longer be the best possible solutions. Supplementary drafts may be released in addition to periodic updates to this document. However, a specific goal is backwards compatibility from one release of this document to the next.

Comments related to this standard are welcome. Any comments or suggestions for changes may be directed to the FHS editor (Daniel Quinlan <quinlan@pathname.com>) or the FHS mailing list. Typographical or grammatical comments should be directed to the FHS editor.

Before sending mail to the mailing list it is requested that you first contact the FHS editor in order to avoid excessive re-discussion of old topics.

Questions about how to interpret items in this document may occasionally arise. If you have need for a clarification, please contact the FHS editor. Since this standard represents a consensus of many participants, it is important to make certain that any interpretation also represents their collective opinion. For this reason it may not be possible to provide an immediate response unless the inquiry has been the subject of previous discussion.

[edit] Acknowledgments

The developers of the FHS wish to thank the developers, system administrators, and users whose input was essential to this standard. We wish to thank each of the contributors who helped to write, compile, and compose this standard.

The FHS Group also wishes to thank those Linux developers who supported the FSSTND, the predecessor to this standard. If they hadn't demonstrated that the FSSTND was beneficial, the FHS could never have evolved.

[edit] Original Contributors

Several people contributed to the filesystem hierarchy standard used as a basis for this document. Those people include:

• Brandon S. Allbery
• Keith Bostic
• Drew Eckhardt
• Rik Faith
• Stephen Harris
• Ian Jackson
• Andreas Jaeger
• John A. Martin
• Ian McCloghrie
• Chris Metcalf
• Ian Murdock
• David C. Niemi
• Daniel Quinlan
• Eric S. Raymond
• Rusty Russell
• Mike Sangrey
• David H. Silber
• Thomas Sippel-Dau
• Theodore Ts'o
• Stephen Tweedie
• Fred N. van Kempen
• Bernd Warken
• Christopher Yeoh

[edit] Notes