Filesystem Standard Group Daniel Quinlan date submitted: 93/11/22 quinlan@bucknell.edu Advance Draft on Linux Filesystem Structure Status of this draft This draft is being distributed to members of the Linux community in order to solicit their reactions to the series of ideas, concepts, and proposals included within it. While the entire content of this draft may not conform to what every individual desires, it should prove to be a good start to solving many problems. The draft is a product of the Filesystem Standard (FSSTND) channel 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 development or implementation. ________________________________________________________________________ ABSTRACT Introduction This document is an extensive undertaking to correct outstanding problems with the filesystem structures 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. The FSSTND group hopes 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 that it was desirable to first call attention to some of the fundamental problems with the current filesystem situation: (1) There is no single well-accepted Linux directory structure. Instead, there are many different ones, each being incompatible with each other. This is a problem that justifies our effort and should overshadow any differences in opinion, the same differences in opinion that make Linux filesystems an utter mess. (2) In the most widely used filesystem hierarchies, the directories are not well structured and differ gratuitously from more modern standards (such as POSIX, System V, BSD, and others). (3) The filesystem is disturbing to experienced UNIX users and administrators who have experience on more mainstream UNIX systems. (4) The current layout is confusing for Linux newcomers, especially those coming from a non-UNIX background. (5) The incompatibilities between primary installation packages and other software packages are typically solved by methods of a less than appealing nature. (6) 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, feel free to first contact the draft coordinator, Daniel Quinlan , with your comments. ------------------------------------------------------------------------ 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 The primary binary directories, /bin and /usr/bin, do not have well defined divisions between them. As a result, the binaries that are in found in each directory greatly differ between various Linux distributions. o 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 Often, configuration files for items which are not related to machine startup and are not machine-local are located in /etc. (Configuration files for items in /usr that are not specific to a single machine should be found in /usr/etc.) 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 it is desirable to serve software to workstations via a NFS mounted filesystem. Such filesystems need to be mounted read-only so that accidents or malice on one workstation cannot damage the files on the server. This requires identification and separation of files that a machine must write to and separation of files that are specific to a single machine. 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. While these are some of the major problems we addressed, there were numerous additional problems that needed to be solved. This draft attempts to address many of those other problems, but there may be something we missed. If you wish to bring something to our attention, please note there are some things we have discussed at length, but did not include in this draft (for good reasons). ------------------------------------------------------------------------ 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 limiting the possible transition difficulties resulting from moving away from the former 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 sensible structure for Linux's filesystem. o While conformance to this or any other standard in Linux is obviously completely voluntary, we wanted 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, we are quite willing to listen. ------------------------------------------------------------------------ History and Progress The original post that motivated this effort to restructure the Linux filesystem was written by Olaf Kirsh on August 2, 1993 to the NORMAL channel of the Linux activists mailing list. Soon thereafter, it was decided that the best way to accomplish such a restructuring of the Linux filesystem would be to create a mailing list for the purpose of trying to develop a consensus standard. After a comprehensive discussion, with surprisingly few flames, a preliminary draft was written. Then, with the help of several dedicated people, the draft was finished and that resulting draft submitted to the FSSTND channel for more discussion. The first draft was submitted to the channel on September 18, 1993. ;; more to be added ________________________________________________________________________ THE FILESYSTEM STRUCTURE The directory hierarchy is separated into unsharable data, "/" (root), and sharable data, "/usr". These two filesystems are divided according to the following two data types: static data and variable data. Static data includes binaries, libraries, documentation, and anything that does not change without system administrator intervention. Variable data is just about anything that does change in an unpredictable way. (Please note that "filesystem" can refer to either a single formatted partition for data, or it can mean the entire directory hierarchy... or at least in our usage it does.) We now have defined 4 orthogonal categories of file data: sharable, unsharable, variable, and static. We have defined /usr as sharable data and / as unsharable data. Each hierarchy, / and /usr, divides data into static and variable types. Throughout this document, and in any well planned filesystem, the acceptance of these facts will help guide the structure and lend it additional consistency. The distinction between sharable and unsharable data needed to be made for several reasons... (1) In a networked environment, certain filesystems contain information specific to a single machine. Therefore these filesystems cannot be shared (with NFS). (2) The current implementation of /usr cannot be mounted read-only because it contains variable files and directories that need to be written to. This is a factor that must be addressed when /usr is shared on a network or mounted read-only because of other considerations (safety). The "sharable" factor can be extended in two directions. (1) A /usr mounted (read-only) through the network (using NFS). (2) A /usr mounted from read-only media. (You can think of that CD-ROM drive as a networked, using postal mail, filesystem that you are sharing with other Linux systems.) While this is not something that is immensely practical or even used, it is something that we did not want to entirely rule out. The "static" vs. "variable" factor dramatically affects the filesystem in 2 major ways: (1) Since / contains both variable and static data, it needs to be mounted read-write. (2) Since /usr contains both variable and static data, and since we want to mount it read-only (see above), it is necessary to provide a method to have /usr mounted read-only. This is done through the creation of a /var hierarchy which is mounted read-write, taking over much of the /usr partition's traditional functionality. ------------------------------------------------------------------------ ROOT This is the root directory structure. In general, enough data should be contained in the root partition to boot, restore, recover, and/or repair the system: (1) To boot a system, enough must be present to mount /usr. This includes utilities, configuration, boot loader information, and other essential start-up data. (2) To recover and/or repair a system, those utilities needed by an experienced user to diagnose and reconstruct a damaged system should be present on root. (3) To restore a system, those utilities needed to restore a system from backups (on floppy, tape, etc.) should be present on root. The primary concern used to balance these desires (placing many things in root) is the goal of keeping root as small as reasonably possible. It is desirable to keep root small in terms of number of directories, files, and disk space for several reasons: (1) 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. (2) Root has many system-specific configuration files in it, a kernel that is specific to the system, a different hostname, etc. This means that root isn't always sharable between networked systems. Keeping root small on networked systems minimizes the amount of space lost on servers to unsharable files. It also allows workstations with smaller local hard drives. However, with diskless clients, this does not have to be entirely the case, unless each client has a different root image. (3) 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 you may be sharing this problem with a large number of users. (4) Disk errors on the root partition are a greater problem than errors on any other partition. A small root partition is less prone to corruption as the result of a system crash. Since root is small and host-specific (due to the division between / and /usr), this scheme necessitates a writeable root. However, this does not necessitate a fully locally stored root. The root partition doesn't have to be locally stored just to be system specific (i.e., root mounted from a NFS root server.) 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.so.*, libm.so.*, and ld.so) |- lost+found : files and directories found by `fsck' (Ext2 specific) |- mnt : mount point 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 tend to grow or vary in size \- {kernel image} Following this section, each directory is explained in full. The root directory normally contains the current kernel image. The kernel image name is locally configurable, but the name we suggest (that has been used in recent Linux kernel sources) is `vmlinux' which may or may not be a (symbolic-)link to the actual file, possibly depending on the system distribution used. More information on kernel placement is located in the /boot section of the draft. ------------------------------------------------------------------------ /bin : essential command binaries (for use by all users) There should be no subdirectories within /bin. The commands (static data) that are needed in single user mode by the super-user (root) are stored in /bin. However, the commands in /bin are for use by *both* root and other users. On the same note, the /bin directory should not contain anything that is to be used only by root (for system administration.) 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 and rationale section towards the end of this draft. Command binaries that are not essential enough to place into /bin should be placed into /usr/bin, instead. Items which are only used by non-root users are not essential (interactive shells, pagers, `passwd', et al.) and should be placed elsewhere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. { arch, cat, chgrp, chmod, chown, cp, date, dd, df, echo, ed, false, free, kill, ln, login, ls, mkdir, mknod, mv, ps, pwd, rm, rmdir, sh, stty, su, sync, true, uname } If /bin/sh is BASH, then /bin/sh should be a symbolic or hard link to /bin/bash since bash behaves differently when called as `sh' or `bash'. The same goes for `pdksh', which is often the /bin/sh on install disks and such (link from /bin/sh to /bin/ksh). I personally prefer the use of a symbolic link in these cases, because it allows users to easily see that /bin/sh is not a true Bourne shell. `[' and `test' are built into BASH, pdksh, zsh, recent Korn shells, essentially every Bourne shell replacement there is for Linux. They should be placed into /usr/bin. (That is, they must be included with any Linux system, attempting to comply with the POSIX.2 standard.) /bin/arch should produce the same output as "uname -m", specifically "i386" or "i486". restoration commands: These commands have been added to make restoration of a system possible (provided that / is intact). { tar, gzip, gunzip (link to gzip), zcat (link to gzip) } If system backups are made with a package other than `gzip' and `tar', then that administrator should include the minimal necessary restoration components in the root partition. For instance, many systems should include `cpio' as it is the next most commonly used backup utility after tar. Conversely, if no restoration from the root partition is ever expected, then these binaries may be omitted (i.e., a ROM chip root, mounting /usr through NFS). If restoration of a system is planned through FTP, then ftp or tftp (along with everything necessary to get an ftp connection) should be available on the root partition. 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 or /usr/local/bin. { domainname (link to hostname), hostname, netstat, ping } ------------------------------------------------------------------------ /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' (if used at all) should be placed into /usr/sbin. (The `activate' command is left out of this scheme because its future is uncertain at this time.) Extra kernel images may be stored in /boot. The main kernel can either be placed in / or in /boot according to preference of the administrator. If placed in /, the kernel may also possibly be a symlink to a kernel image in /boot. Note that the standard location for the kernel is still in /. ------------------------------------------------------------------------ /dev : Device files /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 in /dev should not be distributed with Linux systems, as the local setup will often differ from that on the distributor's development machine. Also, if a distribution install script configures the symlinks at install time, these symlinks will often not get updated if local changes are made in hardware. When used responsibly at a local level, however, they can be put to good use. A good standard already exists for Linux devices. We believe that the current standard should by followed. The device list is maintained by Rick Miller , the Linux Device Registrar. ------------------------------------------------------------------------ /etc : Essential system configuration files No binaries should go directly into /etc. Binaries which would have in the past been found in /etc should now be placed in /sbin. This includes such files 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. ;; this listing is not quite complete REQUIRED files for /etc: { adjtime, csh.login, fdprm, fstab, gettydefs, group, inittab, issue, motd, mtab, mtools, passwd, profile, securetty, shells, termcap, ttytype, utmp } networking REQUIRED files (if networking is installed): { ftpusers, hosts, host.conf, hosts.equiv, networks, printcap, protocols, resolv.conf, services } There are two models for setup of the "rc" command scripts which are invoked by init(8) at boot time, the /etc/rc.* (BSD model) and the /etc/rc.d/* (System V model). Either model is acceptable at this time. This is a local issue and the implementaion that is used should be determined by sysadmin or developer preference. Note: there are more configuration files than just these, but those that are sharable should be placed in /usr/etc rather than /etc. The `magic' file belongs in /usr/etc rather than /etc since the `file' utility is not stored on the root partition and the magic file can tend to get rather large. The `wtmp' logfile belongs in /var/adm because it can grow in size without bound. Systems which opt to use the shadow password suite will have additional files in /etc (/etc/shadow and whatever else) and /usr/sbin (useradd, usermod, et cetera). ------------------------------------------------------------------------ /home : User home directories /home is a fairly standard concept, but it is clearly a site-specific filesystem. The setup will differ from machine to machine. On small systems, each user's directory is typically one of the many subdirectories of /home such as /home/smith, /home/linus, /home/operator, etc. On large systems (especially when the /home directories are mounted across a number of machines using NFS) it is a good idea to subdivide user home directories. Subdivision can be accomplished by using subdirectories such as /home/staff, /home/guests, /home/students, etc. Different 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 (if a program is being run by a user, the $HOME variable is a fairly reliable method). ------------------------------------------------------------------------ /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.*", "/lib/libm.so.*", and "/lib/ld.so" (and not the actual ".a" files). XFree86 and other 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 the C preprocessor currently exists in /lib pointing /lib/cpp to /usr/bin/cpp which should be either be the actual `cpp' binary or a link to /usr/lib/gcc-lib/i?86-*-linux/2.5.?/cpp. No commands should be added to /lib in addition to `cpp'. /lib/cpp is where XFree86 and some other packages expect to find the C preprocessor. ------------------------------------------------------------------------ /mnt : Mount point for temporarily mounted filesystems This is the location where the system administrator may temporarily mount filesystems as needed. The setup of this directory is a local issue and should not affect the manner in which any program is run. ------------------------------------------------------------------------ /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. ------------------------------------------------------------------------ /root: home directory for root / is traditionally the home directory of the root account, although on most Linux systems this is found in /root. One thing that is certain is that the root account's home directory *must* be stored on the root partition. With sensible usage, the root account is not used for mundane things such as mail and news, but solely for systems administration purpose. For this reason, subdirectories such as "Mail" and "News" should not appear in the root account's home directory. (Mail is usually forwarded to a more appropriate account.) ------------------------------------------------------------------------ /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. Anything executed after /usr is known to be mounted (when there are no problems) 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 dangerous in /sbin if you (and programmers) have done the job right. It vis reasonable to want to let them see what files are in /sbin. Therefore, don't make the directory totally unreadable unless you must. /sbin was not created to protect users or to prevent them from seeing the OS, but to provide a good division between binaries that everyone uses and the commands that only administrators use (without exceptions). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REQUIRED files for /sbin: general: { getty, init, loadkeys, update, mkswap, swapon, swapoff } shutdown commands: { halt, reboot, shutdown } filesystem commands: { fdisk, fsck, fsck.*, tunefs (Ext2 only), mkfs, mkfs.*, mount, umount } "*" = (ext, ext2, minix, msdos, xiafs) LILO commands: { lilo } networking: { arp, ifconfig, ifsetup, 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 warranted except in several cases: OPTIONAL files for /sbin: Static ln and static sync are useful when things go wrong. The primary use of sln (to repair hosed symlinks in /lib after a poorly orchestrated upgrade) is no major longer a factor now that the ldconfig program exists and can act as a guiding hand in upgrading the dynamic libraries. Static sync is still useful in some emergency situations. { sln, ssync } ------------------------------------------------------------------------ /tmp : temporary files /tmp is used for temporary files, usually on a fast device (a memory based filesystem, for instance). The "persistence" of the data that is stored in /tmp is different than that which is stored in /usr/tmp. /tmp is usually cleaned out at boot time (or at relatively frequent intervals). Because of this, data stored in /tmp should not be expected to remain for any long period of time on the system... it is frequently deleted. Programs should use /tmp or /usr/tmp (usually symlinked to /var/tmp) according to the expected persistence of the data, but should not rely on any particular persistence for any tmp directories The precise arrangement of /tmp and /usr/tmp is a local issue. If there are distinct /usr/tmp and /tmp directories, then the persistance of /usr/tmp files should be at least as long as for /tmp, but beyond that, a site administrator or distributor can arrange these any way they want to, over ramdisk, symlinks or whatever. ------------------------------------------------------------------------ /usr /usr is the second major division of the filesystem. /usr is sharable data. That means that /usr should be sharable between various machines running Linux. Because it is sharable between machines, any information that is machine-local must be stored elsewhere, hence /var enters the picture. /usr : Second major mount point (permanent) | |- X11 : The X windows directory (X Windows 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 |- share : Architecture-independent data |- src : Source code \- tmp : Temporary files, used to keep /tmp small. X11 is possibly a symlink to /usr/X386 or something else (/usr/X11R5, for instance). The following list of directory symbolic links need to be added. This only needs to be done until compatibility with the /var scheme can be assumed to exist. /usr/adm -> /var/adm /usr/preserve -> /var/preserve /usr/spool -> /var/spool /usr/tmp -> /var/tmp /usr/spool/locks -> /var/lock Most of the above symlinks should in time become unneeded as packages are changed to support /var in addition to /usr. The exception, the directory that should be referenced in /usr rather than /var is /usr/tmp because some systems link it to different directories within /var. The GNU Emacs lock file directory, if Emacs is installed, should be a symlink pointing to /var/lock/emacs if you want to be able to mount /usr read-only. It is usually found in /usr/emacs, /usr/lib/emacs, or /usr/local/lib/emacs (preferably not the first). ------------------------------------------------------------------------ /usr/X11 : X386 X11 installation directory |- bin |- doc |- include |- lib \- man This hierarchy is reserved for the use of XFree86 X11 releases. 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/X11 pointing to /usr/X386 (or whatever directory your X11 package was compiled to utilize). ------------------------------------------------------------------------ /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. Configuration files placed in here have to be not only non-essential but non-host-specific, to allow /usr to be read-only and shared. ------------------------------------------------------------------------ /usr/lib : Libraries for programming and packages |- X11 : Symbolic link to /usr/X11/lib |- emacs : Support files for the GNU Emacs editor |- groff : Libraries/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 (`sendmail'). `smail', if used, should be stored in /usr/bin because it contains functionality that both administrators and users may utilize on the command line. ------------------------------------------------------------------------ /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 The "local" has an often misinterpreted meaning. It is for use by the system administrator to install software where he/she wishes that needs to be safe from overwriting when the system software is updated. More specifically, it is used to store anything that is sharable among a group of machines, but not found in /usr (not default). This directory should always be 100% empty after first installing Linux, no exceptions to this rule should be made other than the listed directory stubs. Locally installed software should be placed within /usr/local rather than /usr unless it is being installed to replace or upgrade software in /usr or it is felt that the installed software is "important enough" to place in /usr or in /. ------------------------------------------------------------------------ /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 nroff source manual pages. Local and X Windows manual pages (if present) should be stored in /usr/local/man and /usr/X11/man, respectively. These directories have a similar structure to /usr/man (man[1-8], cat[1-8], empty subdirectories being omitted). As Linux (and UNIX) is further utilized in foreign countries and manual pages are translated to non-English versions, there is the impending problem that these manual pages will have to be stored somewhere else. Some German releases of Linux have already created a manual page system that is placed in /usr/man with the suffix "g". This is a poor solution and will cause further problems in the long run as other languages appear, especially other languages starting with the same letter (Greek, Gaelic, whatever). Therefore, all non-English manual pages sections should be stored in subdirectories within /usr/man named according to the language that the the contained manual pages are written in (lowercase characters), hence, for the German manual pages: /usr/man/german/man[1-9] and possibly /usr/man/german/cat[1-9] Then, German-speaking Linux users can add /usr/man/german to their MANPATH before /usr/man so that /usr/man/german manual pages are referenced first. If a German manual page is not found for a given command then the English version may be referenced. This setup will be needed as the number of foreign (non-English) manual pages increases. German is the language mentioned here since it is the only non-English manual page system distributed with any Linux system at this time. Other languages will probably follow and they should follow this scheme as well. We only use German as our example because it was the first non-English manual system to be completed. The practice of placing non-English in subdirectories of /usr/man should be followed as well for other manual page hierarchies, such as /usr/local/man and /usr/X11/man. Note: Using the language itself (/usr/man/deutsch) rather than the English (/usr/man/german) was considered, but this was met with disapproval from many people, including those who do not speak English as a first language. The reasons include: simplicity, the difficulty in displaying many languages' names in ASCII characters, and the fact that everyone should be able to recognize their language name in English. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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/share : Architecture-independent data The specifications for /usr/share will be included in a supplementary draft to the main FSSTND draft. ------------------------------------------------------------------------ /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. Secondary note: Some people disagree with me on this one...] 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 for the first time. ------------------------------------------------------------------------ /usr/tmp : temporary files, used to keep /tmp small Files in /usr/tmp are stored for an arbitrary length of time (please remember that system temporary directories are not guaranteed to hold data for any length of time). Data stored in /usr/tmp is typically cleaned out "in a site-specific manner", but usually at less frequent intervals than /tmp. More information on temporary directories is in the section of the draft devoted to /tmp (above). /usr/tmp is usually symlinked to /var/tmp. ------------------------------------------------------------------------ /var : Directories of files that _tend_ to grow or vary in size |- adm : System logging and accounting files |- lock : Lock files |- named : DNS files (for `named'), networking only |- preserve : Used to save text edited by `vi' after crash or hang-up |- spool : Directories for queuing work to be performed later \- tmp : (symlink from /usr/tmp) The directory for variable length files. This includes spools, administrative files, logging files, transient files, and temporary files. A good reason to use /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. The aforementioned symbolic links, also mentioned below in the issues and rationale section, 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. ;; There is much more to /var than just this, but I am still trying to ;; figure out how to put it down... ------------------------------------------------------------------------ /var/adm : System logging and accounting files All system logging should be written to this subdirectory and not to /var/log. `wtmp' and `lastlog' should be stored here. ------------------------------------------------------------------------ /var/lock : Lock files \- emacs : Emacs lock files Lock files should be stored with a subdirectory of /var/lock appropriate subdirectory such as the emacs lock file directory. This directory *does not* replace older locations for lock files other than /usr/spool/locks and the serial lock files contained in /usr/spool/uucp. ;; I feel we should remove the *does not* clause If you are the maintainer of a program that uses lock files and you wish to add a subdirectory for lock files within /var/lock, then it is a good idea to contact the FSSTND channel or myself to discuss placement of a directory for your lock files. If you are interested in being able to mount /usr read-only then you may wish to recompile whatever package it is that uses /usr for lock files and place them in here, again - contact me if you want to add stuff on a permanent basis (i.e., you are a developer or a programmer of a Linux package). The Emacs editor's lock files should be saved in /var/lock/emacs. It is necessary (and easy) to recompile Emacs to do this or to place an appropriate symlink where the Emacs lock file directory lies. ------------------------------------------------------------------------ /var/named : DNS and `named' stuff This is only needed for systems using DNS (networking protocol for name servers). ;; more expansion coming eventually ------------------------------------------------------------------------ /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 |- {printer name} : Spools for a specific printer \- {printer name}.LOCK : Lock file for a specific printer ------------------------------------------------------------------------ Issues and Additional Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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", but an integral part of most UNIX machines. Because of this networking should not be placed into a single directory, but systematically placed in the appropriate directories. /bin : anything a user will want to use that is also considered essential (ftp, netstat, ping) /sbin : anything only root needs and is considered essential (arp, ifconfig, ifsetup, route) /usr/bin : any binaries a user will want to use, but are not essential (finger, rcp, rlogin, telnet, et al.) /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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Architecture-independent Structures Many people have noted that in this draft, that there was no /usr/share. There is now. The structure, /usr/share, typically contains architecture-independent files such as man-pages, timezone, terminfo information, et al. As of this time, there are no different architectures for Linux, but with the passage of time we should see Linux include other architectures and other UNIX systems. One note, no program should ever reference anything in /usr/share, for instance, a manual page program should never directly look in /usr/share/man/man1/ls.1, but it should reference /usr/man/man1/ls.1 at all times. Anything in /usr/share will be "pointed-to" by the use of symlinks from other areas in the filesystem, such as /usr/man, /usr/lib/{something}, etc. The specifications for /usr/share are still be worked out and discussion with on the FSSTND channel or with me is encouraged (by me). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 one definition of /var: "directories of files that vary on different systems and machines". Sometimes systems will also link /tmp to /var/{something} 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 over-reliance on symbolic links to solve problems, confusion resulting from overuse of symbolic links, and the aesthetic 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, etc.). 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 other networking utilities static as well. This is usually not needed. ------------------------------------------------------------------------ ACKNOWLEDGEMENTS Credit for this text should be given to the FSSTND activists, developers, system administrators, and users whose input was essential to this standard. I also wish to thank each of the contributors who helped me to write, compile, and compose this, a consensus standard. I also wish to give real credit to the Linux developers who have seen that giving Linux a common filesystem layout is something that be further the development of the Linux operating system. ------------------------------------------------------------------------ Original contributors: [in alphabetical order] Drew Eckhardt Ian Jackson Ian McCloghrie Daniel Quinlan Mike Sangrey David H. Silber Theodore Ts'o Stephen Tweedie ------------------------------------------------------------------------