944 lines
40 KiB
Plaintext
944 lines
40 KiB
Plaintext
Filesystem Standard Group Daniel Quinlan
|
|
draft submitted: 93/10/15 quinlan@bucknell.edu
|
|
|
|
|
|
Advance Draft on Linux Filesystem Structure
|
|
|
|
|
|
Status of this draft
|
|
|
|
This draft is being distributed to the members of the Linux community
|
|
in order to solicit their reactions to the array of ideas, concepts,
|
|
and proposals included within it. While the entire content of the
|
|
draft may not meet everyone's individual approval, they may be a good
|
|
beginning to solving many problems.
|
|
|
|
This draft is the product of the Filesystem Standard (FSSTND) unit
|
|
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.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
ABSTRACT
|
|
|
|
This document is an extensive undertaking 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.
|
|
|
|
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.
|
|
|
|
(2) In the most widely used filesystem hierarchies, the directories
|
|
are not well structured and differ gratuitously from more modern
|
|
standards.
|
|
|
|
(3) The current layout is confusing for new users and equally
|
|
unsettling in nature for well-experienced Unix users.
|
|
|
|
(4) The incompatibilities between primary installation packages and
|
|
other software packages are typically 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 first contact the draft coordinator, Daniel
|
|
Quinlan <quinlan@bucknell.edu>, 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 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).
|
|
|
|
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 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, we are willing 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-specific configuration files in it, a kernel
|
|
that is 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 you may be sharing this problem with a
|
|
large number of users.
|
|
|
|
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.*" and "libm.so.*")
|
|
|- lost+found : files and directories found by 'fsck'
|
|
|- 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 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 (from Linus Torvalds) is "vmlinux".
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 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.
|
|
|
|
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
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, w, zcat }
|
|
|
|
/* possible removal: od */
|
|
|
|
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.
|
|
|
|
{ ftp, netstat, ping, telnet }
|
|
|
|
/* possible removal: ftp, telnet */
|
|
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
RECOMMENDED files for /bin:
|
|
|
|
These files should appear in /bin if space is not at a premium
|
|
|
|
{ "an interactive shell" (preferably csh), "a pager" (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 are be better
|
|
placed in /usr/bin.
|
|
|
|
{ awk, basename, dirname, expr, head, pstree, tload, top, sed, "other
|
|
login shells deemed necessary (bash, tcsh, zsh, et cetera)" }
|
|
|
|
/* possible removal: awk, sed
|
|
musing: tail
|
|
possible move up: basename, dirname, expr (often used in sh scripts) */
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 and
|
|
the activate command is left out of this scheme because its future is
|
|
uncertain at this time.
|
|
|
|
Extra kernel images should be stored in /boot. The main kernel can
|
|
either be placed in / or in /boot according to personal preference. If
|
|
placed in /, the kernel may possibly be a symlink to a kernel image in
|
|
/boot.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 <rick@ee.uwm.edu>, the Linux Device Registrar.
|
|
|
|
/* where is the device standard stored? */
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 }
|
|
|
|
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
|
|
|
|
/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 ("/home/jane", "/home/bill", "/home/xavier", et
|
|
cetera).
|
|
|
|
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, et
|
|
cetera.
|
|
|
|
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 (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/cpp -> /usr/lib/gcc-lib/i-?86-linux/2.4.?/cpp". No binaries
|
|
should be added to /lib in addition to cpp.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 way 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.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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
|
|
dangerous in /sbin if you (and programmers) have done the job right. It
|
|
is 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 everyone uses
|
|
and commands that *only* administrators use (99.9% of the time).
|
|
|
|
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
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 so that users do not have to use a reduced functionality
|
|
command.
|
|
|
|
========================================================================
|
|
|
|
/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
|
|
|
|
X11 is possibly a symlink to /usr/X386 or something else.
|
|
|
|
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
|
|
|
|
Most of the above symlinks should in time become unneeded as packages
|
|
are changed to support /var in addition to /usr.
|
|
|
|
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.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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_ directory stubs.
|
|
|
|
Let me spell it out for the concept impaired, "E M P T Y".
|
|
|
|
It should also be untouched during system upgrades.
|
|
|
|
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 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).
|
|
|
|
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 langauges
|
|
appear, especially other langauges starting with the same letter
|
|
(Gaelic, Greek, 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.
|
|
|
|
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.
|
|
|
|
Using the language itself (/usr/man/deutsch) rather than the English
|
|
(/usr/man/german) was strongly considered, but this was met with
|
|
disapproval from many people, including those who do not speak English
|
|
as a first language. Reasons: simplicity, the difficulty in displaying
|
|
many languages' names in 7 bit characters, and the fact that everyone
|
|
can hopefully recognize what their language is 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/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 for the first time.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/var : Directories of files that vary on different systems and machines
|
|
|- adm : System logging and accounting files
|
|
|- domain : DNS files (for named), networking only
|
|
|- lock : 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. 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.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/var/domain : DNS and named stuff
|
|
|- forward
|
|
\- reverse
|
|
|
|
This is only needed for systems using DNS (networking protocol for
|
|
name servers).
|
|
|
|
/* I am hoping to add a *much* more extensive explanation after some
|
|
contact is made with Linux networking developers. There is a very
|
|
excellent proposal from Drew Eckhardt (that has precedence as well)
|
|
that will eventually be discussed. */
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/var/lock : Lock files
|
|
|- device : Device locks
|
|
\- 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/uucp and the serial lock files that were contained within it.
|
|
|
|
However, 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 to recompile Emacs to do this or to place an appropriate
|
|
symlink where the Emacs lock file directory lies.
|
|
|
|
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
/var/lock/device: Device lock files
|
|
|
|
All lock files for devices should now be placed in /var/lock/device
|
|
rather than /usr/spool/uucp or whereever they were stored in the past.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
/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 direcotry
|
|
|- {printer name} : Spools for a specific printer
|
|
\- {printer name}.LOCK : Lock file for a specific printer
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
Issues and Addtional 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, telnet, ping)
|
|
/sbin : anything only root needs and is considered
|
|
essential (ifconfig, route)
|
|
/usr/bin : any binaries a user will want to use, but are not
|
|
essential (finger, rcp, rlogin, 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 note that in this draft, there is no /usr/share. 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.
|
|
|
|
The reason that we do not include /usr/share in this standard is that
|
|
/usr/share is very difficult to set up *without* another architecture to
|
|
examine when defining the structure. Keep in mind that things commonly
|
|
specified, like "/usr/share/man" are obvious . . . and wrong. After
|
|
all, some manual pages (like the man pages for the devices:
|
|
/usr/man/man4) will be architecture specific. In addition, there may be
|
|
other files which may actually turn out to be architecture specific
|
|
simply because the DBM formats are not compatible.
|
|
|
|
Thus, we are going to wait on /usr/share for now. If we need /usr/share
|
|
in the future, it is simple enough to put in symlinks from the current
|
|
existing structure into /usr/share. So the primary directory names
|
|
which programs should reference should be /usr/man, and then if
|
|
appropriate certain directories in /usr/man can be symlinked to
|
|
/usr/share/man. This avoid "gotcha's" like /usr/man/man4 that people
|
|
will probably forget about if we try to design /usr/share without
|
|
actually mapping out a NFS supported /usr that supports multiple
|
|
architectures.
|
|
|
|
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|
|
|
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/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, 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 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, compile, and compose this,
|
|
a consensus standard.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
Contributors:
|
|
|
|
[in alphabetical order]
|
|
|
|
Drew Eckhardt <drew@kinglear.cs.colorado.edu>
|
|
Ian Jackson <ijackson@nyx.cs.du.edu>
|
|
Ian McCloghrie <ian@ucsd.edu>
|
|
Daniel Quinlan <quinlan@bucknell.edu>
|
|
Mike Sangrey <mike@sojurn.lns.pa.us>
|
|
David H. Silber <dhs@glowworm.firefly.com>
|
|
Theodore Ts'o <tytso@athena.mit.edu>
|
|
Stephen Tweedie <sct@dcs.ed.ac.uk>
|