The Funtoo Linux project has transitioned to "Hobby Mode" and this wiki is now read-only.
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. [1]
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<section> directories in /usr/share/man directly. We recommend that most sites use one of the following options instead:
*
Preformat all manual pages alongside the unformatted versions. *
Allow no caching of formatted man pages, and require formatting to be done each time a man page is brought up. *
Allow local caching of formatted man pages in /var/cache/man.
The structure of /var/cache/man needs to reflect both the fact of multiple man page hierarchies and the possibility of multiple language support.
Given an unformatted manual page that normally appears in <path>/man/<locale>/man<section>, the directory to place formatted man pages in is /var/cache/man/<catpath>/<locale>/cat<section>, where <catpath> is derived from <path> by removing any leading usr and/or trailing share pathname components. (Note that the <locale> component may be missing.) [2]
Man pages written to /var/cache/man may eventually be transferred to the appropriate preformatted directories in the source man hierarchy or expired; likewise formatted man pages in the source man hierarchy may be expired if they are not accessed for a period of time.
If preformatted manual pages come with a system on read-only media (a CD-ROM, for instance), they must be installed in the source man hierarchy (e.g. /usr/share/man/cat<section>). /var/cache/man is reserved as a writable cache for formatted manual pages.
Tip Rationale
Release 1.2 of the standard specified /var/catman for this hierarchy. The path has been moved under /var/cache to better reflect the dynamic nature of the formatted man pages. The directory name has been changed to man to allow for enhancing the hierarchy to include post-processed formats other than "cat", such as PostScript, HTML, or DVI.
/var/crash : System crash dumps (optional)
This directory holds system crash dumps. As of the date of this release of the standard, system crash dumps were not supported under Linux but may be supported by other systems which may comply with the FHS.
/var/games : Variable game data (optional)
Any variable data relating to games in /usr should be placed here. /var/games should hold the variable data previously found in /usr; static data, such as help text, level descriptions, and so on, must remain elsewhere, such as /usr/share/games.
Tip Rationale
/var/games has been given a hierarchy of its own, rather than leaving it merged in with the old /var/lib as in release 1.2. The separation allows local control of backup strategies, permissions, and disk usage, as well as allowing inter-host sharing and reducing clutter in /var/lib. Additionally, /var/games is the path traditionally used by BSD.
/var/lib : Variable state information
This hierarchy holds state information pertaining to an application or the system. State information is data that programs modify while they run, and that pertains to one specific host. Users must never need to modify files in /var/lib to configure a package's operation.
State information is generally used to preserve the condition of an application (or a group of inter-related applications) between invocations and between different instances of the same application. State information should generally remain valid after a reboot, should not be logging output, and should not be spooled data.
An application (or a group of inter-related applications) must use a subdirectory of /var/lib for its data. There is one required subdirectory, /var/lib/misc, which is intended for state files that don't need a subdirectory; the other subdirectories should only be present if the application in question is included in the distribution. [3]
/var/lib/<name> is the location that must be used for all distribution packaging support. Different distributions may use different names, of course.
Requirements
The following directories, or symbolic links to directories, are required in /var/lib:
Directory Description misc Miscellaneous state data
Specific Options
The following directories, or symbolic links to directories, must be in /var/lib, if the corresponding subsystem is installed:
Directory Description <editor> Editor backup files and state (optional) <pkgtool> Packaging support files (optional) <package> State data for packages and subsystems (optional) hwclock State directory for hwclock (optional) xdm X display manager variable data (optional)
/var/lib/<editor> : Editor backup files and state (optional)
These directories contain saved files generated by any unexpected termination of an editor (e.g., elvis, jove, nvi).
Other editors may not require a directory for crash-recovery files, but may require a well-defined place to store other information while the editor is running. This information should be stored in a subdirectory under /var/lib (for example, GNU Emacs would place lock files in /var/lib/emacs/lock).
Future editors may require additional state information beyond crash-recovery files and lock files — this information should also be placed under /var/lib/<editor>.
Tip Rationale
Previous Linux releases, as well as all commercial vendors, use /var/preserve for vi or its clones. However, each editor uses its own format for these crash-recovery files, so a separate directory is needed for each editor.
Editor-specific lock files are usually quite different from the device or resource lock files that are stored in /var/lock and, hence, are stored under /var/lib.
/var/lib/hwclock : State directory for hwclock (optional)
This directory contains the file /var/lib/hwclock/adjtime.
Tip Rationale
In FHS 2.1, this file was /etc/adjtime, but as hwclock updates it, that was obviously incorrect.
/var/lib/misc : Miscellaneous variable data
This directory contains variable data not placed in a subdirectory in /var/lib. An attempt should be made to use relatively unique names in this directory to avoid namespace conflicts. [4]
/var/lock : Lock files
Lock files should be stored within the /var/lock directory structure.
Lock files for devices and other resources shared by multiple applications, such as the serial device lock files that were originally found in either /usr/spool/locks or /usr/spool/uucp, must now be stored in /var/lock. The naming convention which must be used is "LCK.." followed by the base name of the device. For example, to lock /dev/ttyS0 the file "LCK..ttyS0" would be created. [5]
The format used for the contents of such lock files must be the HDB UUCP lock file format. The HDB format is to store the process identifier (PID) as a ten byte ASCII decimal number, with a trailing newline. For example, if process 1230 holds a lock file, it would contain the eleven characters: space, space, space, space, space, space, one, two, three, zero, and newline.
/var/log : Log files and directories
This directory contains miscellaneous log files. Most logs must be written to this directory or an appropriate subdirectory.
Specific Options
The following files, or symbolic links to files, must be in /var/log, if the corresponding subsystem is installed:
File Description lastlog record of last login of each user messages system messages from syslogd wtmp record of all logins and logouts
/var/mail : User mailbox files (optional)
The mail spool must be accessible through /var/mail and the mail spool files must take the form <username>. [6]
User mailbox files in this location must be stored in the standard UNIX mailbox format.
Tip Rationale
The logical location for this directory was changed from /var/spool/mail in order to bring FHS in-line with nearly every UNIX implementation. This change is important for inter-operability since a single /var/mail is often shared between multiple hosts and multiple UNIX implementations (despite NFS locking issues).
It is important to note that there is no requirement to physically move the mail spool to this location. However, programs and header files must be changed to use /var/mail.
/var/opt : Variable data for /opt
Variable data of the packages in /opt must be installed in /var/opt/<subdir>, where <subdir> is the name of the subtree in /opt where the static data from an add-on software package is stored, except where superseded by another file in /etc. No structure is imposed on the internal arrangement of /var/opt/<subdir>.
Tip Rationale
Refer to the rationale for /opt.
/var/run : Run-time variable data
This directory contains system information data describing the system since it was booted. Files under this directory must be cleared (removed or truncated as appropriate) at the beginning of the boot process. Programs may have a subdirectory of /var/run; this is encouraged for programs that use more than one run-time file. [7] Process identifier (PID) files, which were originally placed in /etc, must be placed in /var/run. The naming convention for PID files is <program-name>.pid. For example, the crond PID file is named /var/run/crond.pid.
Requirements
The internal format of PID files remains unchanged. The file must consist of the process identifier in ASCII-encoded decimal, followed by a newline character. For example, if crond was process number 25, /var/run/crond.pid would contain three characters: two, five, and newline.
Programs that read PID files should be somewhat flexible in what they accept; i.e., they should ignore extra whitespace, leading zeroes, absence of the trailing newline, or additional lines in the PID file. Programs that create PID files should use the simple specification located in the above paragraph.
The utmp file, which stores information about who is currently using the system, is located in this directory.
System programs that maintain transient UNIX-domain sockets must place them in this directory.
/var/spool : Application spool data
/var/spool contains data which is awaiting some kind of later processing. Data in /var/spool represents work to be done in the future (by a program, user, or administrator); often data is deleted after it has been processed. [8]
Specific Options
The following directories, or symbolic links to directories, must be in /var/spool, if the corresponding subsystem is installed:
Directory Description lpd Printer spool directory (optional) mqueue Outgoing mail queue (optional) news News spool directory (optional) rwho Rwhod files (optional) uucp Spool directory for UUCP (optional)
/var/spool/lpd : Line-printer daemon print queues (optional)
The lock file for lpd, lpd.lock, must be placed in /var/spool/lpd. It is suggested that the lock file for each printer be placed in the spool directory for that specific printer and named lock.
Specific Options
Directory Description printer Spools for a specific printer (optional)
/var/spool/rwho : Rwhod files (optional)
This directory holds the rwhod information for other systems on the local net.
Tip Rationale
Some BSD releases use /var/rwho for this data; given its historical location in /var/spool on other systems and its approximate fit to the definition of `spooled' data, this location was deemed more appropriate.
/var/tmp : Temporary files preserved between system reboots
The /var/tmp directory is made available for programs that require temporary files or directories that are preserved between system reboots. Therefore, data stored in /var/tmp is more persistent than data in /tmp.
Files and directories located in /var/tmp must not be deleted when the system is booted. Although data stored in /var/tmp is typically deleted in a site-specific manner, it is recommended that deletions occur at a less frequent interval than /tmp.
/var/yp : Network Information Service (NIS) database files (optional)
Variable data for the Network Information Service (NIS), formerly known as the Sun Yellow Pages (YP), must be placed in this directory.
Tip Rationale
/var/yp is the standard directory for NIS (YP) data and is almost exclusively used in NIS documentation and systems. [9]
Notes
- ↑ This standard does not currently incorporate the TeX Directory Structure (a document that describes the layout TeX files and directories), but it may be useful reading. It is located at [1]
- ↑ For example, /usr/share/man/man1/ls.1 is formatted into /var/cache/man/cat1/ls.1, and /usr/X11R6/man/<locale>/man3/XtClass.3x into /var/cache/man/X11R6/<locale>/cat3/XtClass.3x.
- ↑ An important difference between this version of this standard and previous ones is that applications are now required to use a subdirectory of /var/lib.
- ↑ This hierarchy should contain files stored in /var/db in current BSD releases. These include locate.database and mountdtab, and the kernel symbol database(s).
- ↑ Then, anything wishing to use /dev/ttyS0 can read the lock file and act accordingly (all locks in /var/lock should be world-readable).
- ↑ Note that /var/mail may be a symbolic link to another directory.
- ↑ /var/run should be unwritable for unprivileged users (root or users running daemons); it is a major security problem if any user can write in this directory.
- ↑ UUCP lock files must be placed in /var/lock. See the above section on /var/lock.
- ↑ NIS should not be confused with Sun NIS+, which uses a different directory, /var/nis.