-*- text -*- Filesystem Standard Group Daniel Quinlan draft submitted: 93/10/01 quinlan@bucknell.edu A Linux Filesystem Structure Status of this draft This draft is being distributed to the members of the Linux community in order to solicit their reaction to the proposals contained in it. While the issues and solutions discussed may not meet everyone's specific approval, they may be a good beginning to solving many problems. This draft is a product of the Filesystem Standard (FSSTND) section of the linux-activists@niksula.hut.fi mailing list. This draft is a working document of the Filesystem Standard channel, the author, and all other groups collaborating to help create this draft. The distribution of this draft is limited at this time to those directly involved in its creation. ------------------------------------------------------------------------ ABSTRACT This document is an extensive attempt to correct outstanding problems with the de-facto filesystem standard in use by developers, programmers, administrators, and users. Our purpose and goal is to produce a draft of exceptional quality that developers and others will voluntarily adopt to solve well acknowledged problems. [ Author's note: My personal hope is that this draft will be eventually adopted as a better standard than the de-facto standard produced by the current disarray of ideas. ] We felt it desirable to first call attention to some fundamental problems with the current filesystem situation: (1) There is no single well-accepted Linux directory structure. There are many different ones, each incompatible with each other, and this alone is enough of a problem to justify this effort. (2) In the most common filesystem hierarchies, the directories are not well structured and differ gratuitously from more modern standards. (3) The current is known to be confusing to the new user and equally frustrating (different reasons, same cause) in nature for the experienced Unix user. (4) There are incompatibilities between installation packages and other releases that are usually solved by methods of a less than appealing nature. (5) Overall, symbolic links are used too often within the filesystem to fix problems. However, there are times when symbolic links need to be used to ensure backward compatibility or to allow specific systems to have an individual filesystem structure. The FSSTND group seeks to correct these problems by proposing a good filesystem structure that the Linux community may voluntarily follow. While developing this draft, approval and input was received from a number of Linux developers, noted Linux programmers, many system administrators, and both experienced and novice users. For this reason, I feel that following our recommendations is a good thing. If you feel that there is a problem with this effort or the substance of the draft, please contact me, Daniel Quinlan , with your comments. /* I think it may be of benefit to have a "This standard is supported by foo, bar, and blah" section here or elsewhere in the document, perhaps at then end. */ ------------------------------------------------------------------------ SPECIFIC PROBLEMS Naturally, while defining a Linux filesystem structure, there were some specific problems that we sought to correct. Here are some of the major and well-accepted ones: o Linux is not well prepared for a network installation including the possibility of a read-only /usr partition and diskless (or small local disk) workstations. o The primary binary directories, /bin and /usr/bin, do not have well defined divisions between them. The binaries that are in each path greatly differ between the various Linux installation packages. o Problems concerning /etc - Many configuration files that aren't essential appear in /etc. - Non-essential binaries, such as networking binaries, are often dumped into /etc and symbolic links applied to fix any compatibility problems - Including both binaries and configuration files in /etc makes it more confusing and harder to maintain for inexperienced users or system administrators with especially large systems. o The current implementation of /usr cannot be mounted read-only because it contains variable files and directories that need to be written to. o In a networked environment, certain filesystems contain information specific to a single machine. Therefore these filesystems cannot be shared (with NFS). o More than one temporary mount point is needed on the multiple disk systems of today's computers. ------------------------------------------------------------------------ OBJECTIVES In trying to solve the above problems, we saw several objectives that needed to be accomplished in addition to the more technical matters. These goals comprise the correction of outstanding problems as well as the validation of our discussion and work. o Solve the above problems while also creating as few possible problems with the past de-facto standards. o Gain approval of distributors, developers, and other important people in the Linux movement, as well as their suggestions. o Provide a standard that all of the Linux community would choose to follow because it will solve the above problems as well as provide the most elegant structure for Linux's filesystem. o While conformance to this or any other standard in Linux is obviously completely voluntary, we wish to impress upon developers that this organization is a very sensible way to lay out a Linux filesystem. If you, as a developer, wish to suggest any improvements, I am very eager to listen. ======================================================================== THE FILESYSTEM STRUCTURE This is the root directory structure. In general, enough should be contained in root partition to boot, restore, recover, and/or repair the system. Our primary concern was to keep root as small as reasonably possible in terms of number of directories, files, and disk space. You might ask, "Why is this desirable?" o The root is often mounted from very small media. For example, most people using Linux install and do recovery by mounting root off of a RAM disk which is copied from a single 1.44M or 1.2M floppy disk. o Root has many system unique configuration files in it, a kernel that may be specific to the system, a different hostname, etc. This means that root isn't usually shareable between networked systems. Keeping root small on networked systems minimizes the amount of space lost on servers to non-shareable files. It also allows workstations with smaller local hard drives. o While you may have a large root partition, and may be able to fill it to your heart's content, there will be people with smaller partitions. If you have more files installed, you may find incompatibilities with other systems using limited root partitions. If you are a developer then the problem is no longer just a personal one. No single package should have its own specific root directory. This structure provides more than enough flexibility for any package. Any package which does occupy a directory under root suffers from sheer arrogance. / : the root directory | |- bin : essential command binaries |- boot : static files of the boot loader |- dev : device files |- etc : essential system configuration |- home : user home directories |- lib : shared libraries (libc and libm) |- lost+found : files and directories found by 'fsck' |- mnt : mount points of temporary partitions |- proc : process information pseudo-filesystem |- root : home directory for 'root' |- sbin : essential system binaries |- tmp : temporary files |- usr : second major permanent mount point |- var : files that vary with time or by machine (non-configuration) \- {kernel image} Following this section, each directory is explained in full. The root directory always contains the current kernel image. The kernel image name is user configurable, but the name suggested by the current Linux kernel sources (by Linus Torvalds) is "vmlinux". I am one that agrees with Linus in this case. ------------------------------------------------------------------------ /boot : static files of the boot loader This directory contains everything for boot except configuration files and the map installer. This includes saved master boot sectors, sector map files, and anything else that is not directly edited by hand. The boot loader program should be placed into /sbin and configuration files for boot loaders into /etc. For LILO: Old location New location ------------------------ ----------------- /etc/lilo/config.defines /etc/lilo.defines /etc/lilo/config /etc/lilo.conf /etc/lilo/disktab /etc/disktab /etc/lilo/lilo /sbin/lilo /etc/lilo/boot.NNNN /boot/boot.NNNN /etc/lilo/part.NNNN /boot/part.NNNN /etc/lilo/map /boot/map /etc/lilo/*.b /boot/*.b *.b are the first and second stage boot loader, plus all those chain loaders. QuickInst should probably be placed into /usr/sbin and activate is left out of this scheme because its future is uncertain at this time. (The LILO distribution itself just puts them into the current directory.) ------------------------------------------------------------------------ /bin : essential binaries only (for use by all users) There should be no subdirectories within /bin. The /bin directory should not contain binaries that are only for use by root. All root-only binaries such as standard daemons, init, getty, mkfs, et al (previously found in /etc), shall now be placed in /sbin or /usr/sbin depending on the necessity of the command. For discussion and our definition of essential (necessity and related concepts) please read the "ISSUES" section towards the end of this draft. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REQUIRED files for /bin: general commands: The following commands have been added because of their essential nature in the system. A few have been added because of their traditional placement in /bin. { cat, chgrp, chmod, chown, cmp, compress, cp, date, dd, df, du, ed, false, free, grep, hostname, kill, killall, ln, login, ls, mkdir, mknod, mv, od, ps, pwd, rm, rmdir, sh, stty, su, sync, test, touch, true, uncompress, uptime, zcat } networking: These are deemed the only necessary networking binaries that both root and users will want or need to execute other than the ones in /usr/bin, obviously. { ftp, netstat, ping, telnet } . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RECOMMENDED files for /bin: These files should appear in /bin if space is not at a premium { more (or less), passwd, wall, write } . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPTIONAL files for /bin: These may appear in /bin at the discretion of system administrators, but are in no way required and may be better placed in /usr/bin. { awk, basename, dirname, expr, head, pstree, tload, top, sed, "any login shells deemed necessary (bash, tcsh, zsh, et cetera)" } ------------------------------------------------------------------------ /dev : Device files There are no subdirectories within /dev. /dev usually also contains a file, MAKEDEV, a shell script designed to create devices as needed. It also often contains a MAKEDEV.local for any local-only devices. Symbolic links within /dev "to make it easier to understand" are dangerous and not a good idea. The largest problem with symlinks in /dev is that they are often not updated when other devices are. If you feel you absolutely MUST create links in /dev then use hard links, and not symbolic ones. A good standard already exists for Linux devices. We believe that the current standard should by followed in all cases. The device list is maintained by Rick Miller , the Linux Device Registrar. ------------------------------------------------------------------------ /etc : Essential system configuration files No binaries or subdirectories should go directly into /etc. Commands which would have in the past been found in /etc should now be placed in /sbin. This includes such commands as init, getty, and update. Binaries such as hostname which are used by users as well as root should not be placed in /sbin, but in /bin. REQUIRED files for /etc: { adjtime, fdprm, fstab, group, initttab, issue, magic, motd, mtab, mtools, passwd, printcap, profile, protocols, rc*, securetty, services, shells, termcap, utmp } networking REQUIRED files (if networking is installed): { ftpusers, host, host.conf, hosts.equiv, networks } shadow REQUIRED files (if the shadow password suite is used): { shadow } Of course, there may be more configuration files than just these, but some that are not essential should be placed in /usr/etc rather than /etc. ------------------------------------------------------------------------ /home : User home directories Each user's directory is typically one of the many subdirectories of /home. /home is a fairly standard concept, but it is clearly a local filesystem. The setup will likely differ from machine to machine. For instance, administrators of larger systems may wish to subdivide users into separate directories such as 'staff', 'faculty', 'students', or 'guests'. Many people prefer to place user accounts in a variety of places and because of this reason, no programming should rely on this location. If you want to find out a user's home directory, you should use the field in /etc/passwd or another reliable method (I know of no other reliable methods). ------------------------------------------------------------------------ /lib : Shared libraries (needed to run dynamically linked binaries) Only the shared library images necessary to boot the system should be placed in /lib. The shared library images are "/lib/libc.so.*" and "/lib/libm.so.*" and not the actual ".a" files. Xfree86 libraries do not belong in /lib. Essentially, only the dynamic shared libraries needed to run programs in /bin and /sbin should be here. A single symbolic link for gcc currently exists in /lib pointing "/lib/gcc -> /usr/lib/gcc-lib/i-?86-linux/2.4.?/gcc". No binaries should be added to /lib in addition to gcc. ------------------------------------------------------------------------ /mnt : Major mount points for temporary partitions from local devices This directory should contain all temporary mount points. The naming convention that we recommend using is naming the mount point (subdirectories of /mnt) after the device that it is being mounted from. Examples are /mnt/fd0 and /mnt/hda2. It solves the problem of wanting to temporarily mount two drives at once as well as making the entire temporary mount business more logical and less confusing. Although DOS drives can be easily temporarily handled within this arrangement, some people may wish to have a permanent mounting point for their DOS drives. The most sensible proposals that have been extended by DOS users is to place DOS in a directory tree named '/dos' with subdirectories named according to traditional DOS schemes, i.e. '/dos/a', '/dos/b', and '/dos/c'. Other foreign operating systems can also probably be mounted in a similar manner. This paragraph is *not* an official part of the filesystem draft. ------------------------------------------------------------------------ /proc : Proc based process system The procps filesystem is becoming the standard Linux method for handling process information rather than /dev/kmem and other nasty methods. This is only recommended, but should in time become the standard for the storage and retrieval of process information as well as other kernel and memory information. ------------------------------------------------------------------------ /sbin : System binaries (binaries once kept in /etc) Utilities used for system administration (and other root-only commands) are stored in /sbin, /usr/sbin, and /usr/local/sbin. /sbin typically contains files essential for the booting phase of starting the system up. Any non-essential commands should be placed into /usr/sbin. Local-only system administration stuff should now be placed into /usr/local/sbin. The concept of what goes into "sbin" directories is simple. If a user will need to run it, then it should go somewhere else. If it will only be run by root (i.e. system administration commands, networking daemons, system startup), then it should go in /sbin (or in /usr/sbin if the item is not essential). Files such as 'chfn' and 'ac' which users only occasionally use should still be placed in /usr/bin. 'ping', although it is absolutely necessary for root (network recovery and diagnosis) is often used by users and should live in /bin for that reason. Let me state it one more time, if there is any chance at all that a user should need to run it, do not put it here! Users should never have to place /sbin (or any of the 'sbin' directories) in their path. It is true that they should probably not even be able to execute anything in /sbin if you (and programmers) have done the job right. (It is reasonable to let them see what files are in /sbin - please don't make the directory totally unreadable unless you must!) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REQUIRED files for /sbin: general: { getty, init, update, mkswap, swapon, swapoff } shutdown commands: { halt, reboot, shutdown } filesystem commands: { fsck, fsck.*, tunefs, mkfs, mkfs.*, mount, umount } networking: { ifconfig, route } . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . /sbin is traditionally known for statically linked files although as you can see we have not even mentioned linking anything statically yet. This is because we feel that the need for statically linked files is not great except in several cases: RECOMMENDED to be linked statically: ln, sync Yes, neither 'ln' or 'sync' are normally placed in /sbin. If the version of 'ln' and 'sync' that you possess are not a reduced (in functionality or interface) version of the normal commands then they should just replace the ones in /bin. If either is a reduced version that only offers minimal features then it should be kept separately in /sbin for obvious reasons. ======================================================================== /usr : Second major mount point (permanent) | |- X11 : The X windows directory version 11 |- bin : Most user commands |- dict : Spelling dictionaries |- doc : Miscellaneous documentation |- etc : Other configuration files (for programs in /usr/bin) |- g++-include : GNU C++ include files |- games : Games and educational binaries |- include : Header files included by C programs |- info : The GNU info documentation system's primary directory |- lib : Libraries |- local : Local directory (empty after main installation) |- man : Online manuals |- sbin : Non-essential system administration binaries \- src : Source code Unfortunately, at least the following list of directory symbolic links need to be added. This is done so that /usr can be read read only and the name /usr/X386 can be changed to the well-accepted /usr/X11. This only needs to be done until compatibility with the /var scheme can be assumed to exist (and the Xfree86 folks realize that 99% of the world uses /usr/X11 or /usr/X11R5). /usr/X386 -> /usr/X11 /usr/adm -> /var/adm /usr/lib/emacs/lock -> /var/lock/emacs (sometimes /usr/local/lib) /usr/preserve -> /var/preserve /usr/spool -> /var/spool /usr/tmp -> /var/tmp /* question on X11: should we make it X11R5, X11R6, etc. rather than just X11, I think this would make transition periods easier. */ ------------------------------------------------------------------------ /usr/X11 : X386 X11 installation directory |- bin |- doc |- include |- lib \- man This hierarchy is reserved for the use of the X386 release. The name "X386" is out of date and should really be replaced with the more accepted, X11, but in order to simplify matters and make X386 more compatible with other X11 packages from XFree86, our recommendation is to place a symbolic link, /usr/X386 pointing to /usr/X11. /* see the above question on the naming of /usr/X11 */ ------------------------------------------------------------------------ /usr/etc : Non-essential system configuration files All non-essential system configuration should be placed in here. Basically, files placed in here will be configuration for files in /usr/bin or /usr/sbin. ------------------------------------------------------------------------ /usr/lib : Libraries for programming and packages |- emacs : Support files for the GNU Emacs editor |- groff : Libaries/directories for the GNU groff system |- gcc-lib : System specific files/directories for GNU C compiler |- terminfo : Directories for terminfo database |- uucp : Commands for uucp \- zoneinfo : Timezone information and configuration The word, library, includes static data files and some internal binaries as well. ------------------------------------------------------------------------ /usr/local : Local directory |- bin : Local only binaries |- etc : Configuration for local only binaries |- games : Locally installed games |- lib : Libraries for /usr/local |- info : Local info pages |- man : Man page hierarchy for /usr/local |- sbin : Local only system administration \- src : Local source code This should be 100% empty after installing Linux, no exceptions other than the listed _empty_ directories. Let me spell it out for the concept impaired, "E-M-P-T-Y". It should also be untouched during system upgrades. ------------------------------------------------------------------------ /usr/man : Manual page hierarchy |- man1 : User programs |- man2 : System calls |- man3 : Library functions and subroutines |- man4 : Devices |- man5 : File formats |- man6 : Games |- man7 : Miscellaneous |- man8 : System Administration \- man9 : Kernel internal variables and functions The cat page sections (cat[1-9]) containing formatted manual page entries are also found within subdirectories of /usr/man, but are not required nor should they be distributed in lieu of formatted manual pages. Local manual pages should be stored in /usr/local/man which contains a similar directory structure (man[1-8], empty subdirectories can be omitted). X Windows manual pages should be stored in /usr/X11/man in an identical directory structure (man[1-8], empty subdirectories can be omitted). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A description of each section follows: man1: User programs Manual pages that describe publicly accessible commands are contained in this chapter. Most program documentation that a user will need to use is located here. man2: System calls This section describes all of the system calls which are entries to the Linux kernel (operating system). This section can be very useful to programmers, but users have little need of the items in section 2. man3: Library functions and subroutines Section 3 describes user-level library routines. This is another chapter that is only really of interest to programmers. man4: Special files Section 4 describes the special files, related driver functions, and networking support available in the system. Typically, the device files found in /dev. man5: File formats The formats for many nonintuitive data files are documented in the section 5. This includes various include files, program output files, and system files man6: Games This chapter documents games, demos, and generally trivial programs. Different people have various notions about how essential this is. man7: Miscellaneous Manual pages that are difficult to classify are designated as being section 7. The *roff and other text processing macro packages are found here. man8: System administration Documentation for programs used by system administrators for system operation and maintenance are documented here. Some of these programs are also occasionally useful for normal users. man9: Kernel internal variables and functions This appears on Linux systems to document the kernel source code. ------------------------------------------------------------------------ /usr/sbin : Non-essential standard system binaries Any non-essential system administration binaries, non-essential networking daemons (most other than those mentioned to be in /sbin), large system administration tools, interface programs, or anything used only by the sysadmin that isn't essential. Local system binaries and local administration shell scripts belong in /usr/local/sbin. ------------------------------------------------------------------------ /usr/src : Source code | \- linux : Source code for Linus' kernel Any non-local source code should be placed in this subdirectory, the only thing in /usr/src that should always be placed in a certain location is the kernel source (when present or linked in part to the /usr/include structure). [ Author's note: Also, if you have any taste, you'll learn to use subdirectories. ] The source code for the kernel should always be in place or at least the include files from the kernel source. Those files are located in these directories: /usr/src/linux/include/asm /usr/src/linux/include/linux /usr/include usually contains links to 'asm' and 'linux' in the source directory, therefore, at least those include files should always be distributed with installations. They should also be distributed in the /usr/src/linux directory so there are no problems when system administrators upgrade their kernel version. ------------------------------------------------------------------------ /var : Directories of files that vary on different systems and machines |- adm : System logging and accounting files |- domain : DNS files |- locks : Lock files |- preserve : Used to save text edited by 'vi' after crash or hangup |- spool : Directories for queuing work to be performed later \- tmp : Second temporary directory This directory contains the directories of all files that vary with time and is usually a local directory. These include logging files, accounting files, backup files for editors and other programs, and spool directories. The reason for a /var is to make it possible to mount /usr read-only. Everything that once went into /usr that is written to on a temporary basis, now goes into /var. Symbolic links, mentioned below, should be added to /usr for compatibility. This is very helpful if you are mounting /usr through NFS or if you want a read-only /usr. /* /var/domain should be included in the standard (with forward and reverse subdirectories) */ /* What was the suggested format for a lock file? Was it "{device-name}.LOCK" or "LOCK.{device-name}" or was it something very different? */ ------------------------------------------------------------------------ /var/spool : Spooling directories (queue work, work to be done later) |- at : at jobs |- cron : Cron jobs |- lpd : Printer spool directory |- mail : Directory for user mailboxes |- mqueue : Outgoing mail queue \- uucp : Spool directory for uucp /var/spool/lpd : Printer spool directory |- lpd/{printer device name} : Spools for a given printer \- {lpd lock files} /* I think all future (or not too entrenched) lock files belong in "/var/locks" */ ------------------------------------------------------------------------ ISSUES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What is Essential? The answer is: essential to clean, create, prepare, check, find and mount other filesystems (possibly on remote machines). There are other definitions, but this is a general definition that most people will at least incorporate into their own. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Networking Networking presented an interesting dilemma. Many people like to place networking binaries and configuration separate from other binaries and configuration. However, we disagree. We feel that networking is not a "package" in the way of Emacs or X386, but an integral part of most Unix machines. Networking files are certainly not required on a system, but once they do appear on a system, it is rare that they will need to be de-installed or upgraded in the same manner than one upgrades Emacs or Gcc. /bin : anything a user will want to use that is also considered essential (telnet, ping, ftp) /sbin : anything only root needs and is considered essential (ifconfig) /usr/bin : any binaries a user will want to use, that are not essential (rcp, rlogin, ...) /usr/sbin : any root only networking binaries that are not essential (networking daemons, lpd, et al.) While this may seem confusing at first (and it does take a moment to digest), it does make sense. If you can only mount root for some reason and you need access to networking to repair your system, you don't need the files to be off in /usr/etc (as they often are). Files that are needed to mount /usr in normal (and emergency situations) are placed on the root subtree and any others are placed in /usr in order to keep the size of root small. Configuration files for networking similarly go into /etc and /usr/etc dependent on how they are deemed, essential, or non-essential. This should coincide with any respective binaries in /sbin or /usr/sbin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Symbolic Links There are a wide range of uses for symbolic links (symlinks) in every filesystem. While symlinks are not encouraged for default setup (found after installing Linux) in a standard such as this, they are often used with good purpose on different systems. The point is that symlinks should be there to keep everything where everyone else expects find it Be prepared to accept that certain directories, even those contained on the root directory, are still going to be symlinks. For instance, on some systems /home will not be on the root, but symlinked to a /var directory, or to somewhere else. /home could also have its own physical partition, of course, and be mounted on its own. Similarly, because /usr might be on a central fileserver mounted via NFS, /usr/local could be symlinked to /var/local. Like /usr/emacs/lock, this change can be justified by recalling the definition of /var: "directories of files that vary on different systems and machines". Sometimes systems will also link /tmp to /var/tmp if the root partition becomes too small (or starts out too small). There are more examples of "good" uses of symbolic links, but the entire issue boils down to two things: packages should be able to find things where they expect them (within reason) and symbolic links can be used to solve the problem in many cases. However, problems also can arise from using too many symbolic links. These problems include overreliance on symbolic links to solve problems, confusion resulting from overuse of symbolic links, and the athethic preferences of different people. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statically linked binaries Linux is currently running on a wide variety of systems, some single user with small disks, some as servers in large networked environments. Because of this variety, this standard sets no rule regarding what binaries are static or dynamic with the following two exceptions. Both 'ln' and 'sync' should have static versions in /sbin in addition to dynamic versions in /bin since everyday users may wish to run these too. Large Linux systems may wish to include other statically linked binaries (sh, init, mkfs, fsck, tunefs, mount, umount, swapon, swapoff, getty, login, et al). The developers and/or system administrators are free to statically/dynamically link these and other binaries as they see fit, as long as the location of the binaries doesn't change. Networked systems (especially those of the future which may lack floppy drives), may want to make ifconfig, route, hostname, and ftp (meaning an additional static copy in /sbin) static as well. ------------------------------------------------------------------------ ACKNOWLEDGEMENTS Credit for this text should be given to the FSSTND activists, developers, users, and system administrators whose input was essential to this standard. I also wish to thank each of the contributors who helped me to write and compose this, a consensus standard. ------------------------------------------------------------------------ Major Contributors: Drew Eckhardt Ian Jackson Ian McCloghrie Daniel Quinlan Theodore Ts'o Other Contributors: Mike Sangrey David H. Silber Stephen Tweedie ------------------------------------------------------------------------