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 /var Hierarchy

/var contains variable data files. This includes spool directories and files, administrative and logging data, and transient and temporary files.

Some portions of /var are not shareable between different systems. For instance, /var/log, /var/lock, and /var/run. Other portions may be shared, notably /var/mail, /var/cache/man, /var/cache/fonts, and /var/spool/news.

/var is specified here in order to make it possible to mount /usr read-only. Everything that once went into /usr that is written to during system operation (as opposed to installation and software maintenance) must be in /var.

If /var cannot be made a separate partition, it is often preferable to move /var out of the root partition and into the /usr partition. (This is sometimes done to reduce the size of the root partition or when space runs low in the root partition.) However, /var must not be linked to /usr because this makes separation of /usr and /var more difficult and is likely to create a naming conflict. Instead, link /var to /usr/var.

Applications must generally not add directories to the top level of /var. Such directories should only be added if they have some system-wide implication, and in consultation with the FHS mailing list.

Requirements

The following directories, or symbolic links to directories, are required in /var.

Directory Description cache Application cache data lib Variable state information local Variable data for /usr/local lock Lock files log Log files and directories opt Variable data for /opt run Data relevant to running processes spool Application spool data tmp Temporary files preserved between system reboots

Several directories are `reserved' in the sense that they must not be used arbitrarily by some new application, since they would conflict with historical and/or local practice. They are:

   /var/backups
   /var/cron
   /var/msgs
   /var/preserve

Specific Options

The following directories, or symbolic links to directories, must be in /var, if the corresponding subsystem is installed:

Directory Description account Process accounting logs (optional) crash System crash dumps (optional) games Variable game data (optional) mail User mailbox files (optional) yp Network Information Service (NIS) database files (optional)

/var/account : Process accounting logs (optional)

This directory holds the current active process accounting log and the composite process usage data (as used in some UNIX-like systems by lastcomm and sa).

/var/cache : Application cache data

/var/cache is intended for cached data from applications. Such data is locally generated as a result of time-consuming I/O or calculation. The application must be able to regenerate or restore the data. Unlike /var/spool, the cached files can be deleted without data loss. The data must remain valid between invocations of the application and rebooting the system.

Files located under /var/cache may be expired in an application specific manner, by the system administrator, or both. The application must always be able to recover from manual deletion of these files (generally because of a disk space shortage). No other requirements are made on the data format of the cache directories.

Tip Rationale

The existence of a separate directory for cached data allows system administrators to set different disk and backup policies from other directories in /var.

Specific Options

Directory Description fonts Locally-generated fonts (optional) man Locally-formatted manual pages (optional) www WWW proxy or cache data (optional) <package> Package specific cache data (optional)

/var/cache/fonts : Locally-generated fonts (optional)

The directory /var/cache/fonts should be used to store any dynamically-created fonts. In particular, all of the fonts which are automatically generated by mktexpk must be located in appropriately-named subdirectories of /var/cache/fonts.

Specific Options

Other dynamically created fonts may also be placed in this tree, under appropriately-named subdirectories of /var/cache/fonts.

/var/cache/man : Locally-formatted manual pages (optional)

This directory provides a standard location for sites that provide a read-only /usr partition, but wish to allow caching of locally-formatted man pages. Sites that mount /usr as writable (e.g., single-user installations) may choose not to use /var/cache/man and may write formatted man pages into the cat