% "@(#)sag:$Id$"        
%--------------------------------------------------------------------
\chapter{Directory Tree Overview} \label{chap:walkabout}
%--------------------------------------------------------------------

        \begin{raggedleft}
        \it
        This chapter needs a quote.  Suggestions, anyone?  \\
        \end{raggedleft}
        \vspace{2em}

	\noindent
	This chapter describes the important parts of a standard
	Linux directory tree, based on the FSSTND filesystem
	standard.  It outlines the normal way of breaking the directory
	tree into separate filesystems with different purposes and gives
	the motivation behind this particular split.  Some alternative
	ways of splitting are also described.

	\meta The next version of the FSSTND (1.3?) will cause many
	minor changes, and some new ones, due to work to make the
	FSSTND work for BSD systems as well.

\section{Background}

	This chapter is loosely based on the Linux filesystem
	standard, FSSTND, version 1.2 (see the bibliography), which attempts
	to set a standard for how the directory tree in a Linux system
	is organized.  Such a standard has the advantage that
	it will be easier to
	write or port software for Linux, and to administer Linux
	machines, since everything will be in their usual places.  There
	is no authority behind the standard that forces anyone to comply
	to it, but it has got the support of most, if not all Linux
	distributions.  It is not a good idea to break with the FSSTND
	without very compelling reasons.  The FSSTND attempts to follow
	Unix tradition and current trends, making Linux systems familiar
	to those with experience with other Unix systems, and vice
	versa.

	This chapter is not as detailed as the FSSTND.  A system
	administrator should also read the FSSTND for a complete
	understanding.

	This chapter does not explain all files in detail.  The intention
	is not to describe every file, but to give an overview of the
	system from a filesystem point of view.  Further information of
	each file is available elsewhere in this manual or the manual
	pages.

	The full directory tree is intended to be breakable into smaller
	parts, each on its own disk or partition, to accomodate to disk
	size limits and to ease backup and other system administration.
	The major parts are the root, \fn{/usr}, \fn{/var}, and
	\fn{/home} filesystems.  Each part has a different purpose.
	The directory tree has been designed so that it works well in a
	network of Linux machines which may share some parts of the
	filesystems over a read-only device (e.g., a CD-ROM), or
	over the network with NFS.

	The roles of the different parts of the directory tree are
	described below.
		%
	\begin{itemize}
	\item
	The root filesystem is specific for each machine (it is generally
	stored on a local disk, although it could possibly be downloaded
	to a ramdisk during bootup) and contains the
	files that are necessary for booting the system up, and to bring
	it up to such a state that the other filesystems may be mounted.
	The contents of the root filesystem will therefore be sufficient
	for the single user state.  It will also contain tools for
	fixing a broken system, and for recovering lost files from backups.

	\item
	The \fn{/usr} filesystem contains all commands, libraries, manual
	pages, and other unchanging files needed during normal operation.
	No files in \fn{/usr} should be specific for any given machine,
	nor should they be modified during normal use.  This allows the
	files to be shared over the network, which can be cost-effective
	since it saves disk space (there can easily be hundreds of
	megabytes in \fn{/usr}), and can make administration easier
	(only the master \fn{/usr} needs to be changed when updating
	an application, not each machine separately).  Even if the
	filesystem is on a local disk, it could be mounted read-only,
	to lessen the chance of filesystem corruption during a crash.

	\item
	The \fn{/var} filesystem contains files that change, such as
	spool directories (for mail, news, printers, etc), log files,
	formatted manual pages, and temporary files.  Traditionally
	everything in \fn{/var} has been somewhere below \fn{/usr},
	but that made it impossible to mount \fn{/usr} read-only.

	\item
	The \fn{/home} filesystem contains the users' home directories,
	i.e., all the real data on the system.  Separating home directories
	to their own directory tree or filesystem makes backups easier;
	the other parts often do not have to be backed up, or at least not
	as often (they seldom change).  A big \fn{/home} might have to	
	be broken on several filesystems, which requires adding an extra
	naming level below \fn{/home}, e.g., \fn{/home/students} and
	\fn{/home/staff}.
	\end{itemize}
		%
	Although the different parts have been called filesystems above,
	there is no requirement that they actually be on separate filesystems.
	They could easily be kept in a single one if the system is
	a small single-user system and he wants to keep things simple.
	The directory tree might also be divided into filesystems differently,
	depending on how large the disks are, and how space is allocated
	for various purposes.
	The important part, though, is that all the standard \emph{names}
	work; even if, say, \fn{/var} and \fn{/usr} are actually on the
	same partition, the names \fn{/usr/lib/libc.a} and
	\fn{/var/adm/messages} must work, for example by moving files
	below \fn{/var} into \fn{/usr/var}, and making \fn{/var} a symlink
	to \fn{/usr/var}.

	The Unix filesystem structure groups files according to purpose,
	i.e., all commands are in one place, all data files in another,
	documentation in a third, and so on.  An alternative would be to
	group files files according to the program they belong to, i.e.,
	all Emacs files would be in one directory, all \TeX\ in another,
	and so on.  The problem with the latter approach is that it
	makes it difficult to share files (the program directory often
	contains both static and shareable and changing and
	non-shareable files), and sometimes to even find the files
	(e.g., manual pages in a huge number of places, and making the
	manual page programs find all of them is a maintenance
	nightmare).

\section{The root filesystem}

	The root filesystem should generally be small, since it contains
	very critical files and a small, infrequently modified
	filesystem has a better chance of not getting corrupted.  A
	corrupted root filesystem will generally mean that the system
	becomes unbootable except with special measures (e.g., from a
	floppy), so you don't want to risk it.

	The root directory generally doesn't contain any files, except
	perhaps the standard boot image for the system, usually called
	\fn{/vmlinuz}.  All other files are in subdirectories in the
	root filesystems:
		%
	\begin{dispitems}
	\item[\fn{/bin}]
		Commands needed during bootup that might be used
		by normal users (probably after bootup).
	\item[\fn{/sbin}]
		Like \fn{/bin}, but the commands are not intended
		for normal users, although they may use them if necessary
		and allowed.
	\item[\fn{/etc}]
		Configuration files specific to the machine.
	\item[\fn{/root}]
		The home directory for user \texttt{root}.
	\item[\fn{/lib}]
		Shared libraries needed by the programs on the root
		filesystem.
	\item[\fn{/lib/modules}]
		Loadable kernel modules, especially those that are needed
		to boot the system when recovering from disasters (e.g.,
		network and filesystem drivers).
	\item[\fn{/dev}]
		Device files.
	\item[\fn{/tmp}]
		Temporary files.  Programs running after bootup should
		use \fn{/var/tmp}, not \fn{/tmp}, since the former
		is probably on a disk with more space.
	\item[\fn{/boot}]
		Files used by the bootstrap loader, e.g., LILO.  Kernel
		images are often kept here instead of in the root
		directory.  If there are many kernel images, the directory
		can easily grow rather big, and it might be better to
		keep it in a separate filesystem.  Another reason would
		be to make sure the kernel images are within the first
		1024~cylinders of an IDE disk.
	\item[\fn{/mnt}]
		Mount point for temporary mounts by the system administrator.
		Programs aren't supposed to mount on \fn{/mnt} automatically.
		\fn{/mnt} might be divided into subdirectories (e.g.,
		\fn{/mnt/dosa} might be the floppy drive using an MS-DOS
		filesystem, and \fn{/mnt/exta} might be the same with an ext2
		filesystem).
	\item[\fn{/proc}, \fn{/usr}, \fn{/var}, \fn{/home}]
		Mount points for the other filesystems.
	\end{dispitems}

\subsection{The \fn{/etc} directory}

	The \fn{/etc} directory contains a lot of files.  Some of them
	are described below.  For others, you should determine which
	program they belong to and read the manual page for that program.
	Many networking configuration files are in \fn{/etc} as well,
	and are described in the Networking Administrators' Guide.
		%
	\begin{dispitems}
	\item[\fn{/etc/rc} or \fn{/etc/rc.d} or \fn{/etc/rc?.d}]
	Scripts or directories of scripts to run at startup or when
	changing the run level.
	See the chapter on \cmd{init} for further information.

	\item[\fn{/etc/passwd}]
	The user database, with fields giving the username, real name,
	home directory, encrypted password, and other information about
	each user.  The format is documented in the \man{passwd(5)}
	manual page.

	\item[\fn{/etc/fdprm}]
	Floppy disk parameter table.  Describes what different floppy
	disk formats look like.  Used by \cmd{setfdprm(1)}.  See
	the \man{setfdprm(8)} manual page for more information.

	\item[\fn{/etc/fstab}]
	Lists the filesystems mounted automatically at startup
	by the \cmd{mount -a} command (in \fn{/etc/rc} or equivalent
	startup file).  Under Linux, also contains information about swap
	areas used automatically by \cmd{swapon -a}.
	See section~\ref{subsec:mount} and the
	\man{mount(8)} manual page for more information.  

	\item[\fn{/etc/group}]
	Similar to \fn{/etc/passwd}, but describes
	groups instead of users.  See the \man{group(5)} manual page for
	more information.

	\item[\fn{/etc/inittab}]
	Configuration file for \cmd{init(8)}.

	\item[\fn{/etc/issue}]
	Output by \cmd{getty} before the login prompt.  Usually contains
	a short description or welcoming message to the system.  The
	contents are up to the system administrator.

	\item[\fn{/etc/magic}]
	The configuration file for \cmd{file(1)}.  Contains
	the descriptions of various file formats based on which
	\cmd{file} guesses the type of the file.  See the \man{magic(8)}
	and \man{file(1)} manual pages for more information.

	\item[\fn{/etc/motd}]
	The \defin{message of the day}, automatically output after
	a successful login.  Contents are up to the system administrator.
	Often used for getting information to every user, such as
	warnings about planned downtimes.

	\item[\fn{/etc/mtab}]
	List of currently mounted filesystems.  Initially set up by
	the scripts, and updated automatically by the \cmd{mount} command.
	Used when a list of mounted filesystems is needed, e.g., by
	the \cmd{df(1)} command.

	\item[\fn{/etc/shadow}]
	Shadow password file on systems with shadow password software
	installed.  Shadow passwords move the encrypted password from
	\fn{/etc/passwd} into \fn{/etc/shadow}; the latter is not
	readable by anyone except \texttt{root}.  This makes it harder
	to crack passwords.

	\item[\fn{/etc/login.defs}]
	Configuration file for the \cmd{login(1)} command.

	\item[\fn{/etc/printcap}]
	Like \fn{/etc/termcap}, but intended for printers.  Different
	syntax.

	\item[\fn{/etc/profile}, \fn{/etc/csh.login}, \fn{/etc/csh.cshrc}]
	Files executed at login or startup time by the Bourne or
	C shells.  These allow the system administrator to set global
	defaults for all users.
	See the manual pages for the respective shells.

	\item[\fn{/etc/securetty}]
	Identifies secure terminals, i.e., the terminals from which
	\texttt{root} is allowed to log in.
	Typically only the virtual
	consoles are listed, so that it becomes impossible (or at
	least harder) to gain superuser privileges by breaking into a
	system over a modem or a network.

	\item[\fn{/etc/shells}]
	Lists trusted shells.  The \cmd{chsh(1)} command allows users
	to change their login shell only to shells listed in this
	file.  \cmd{ftpd}, the server process that provides FTP
	services for a machine, will check that the user's shell is
	listed in \fn{/etc/shells} and will not let people log in
	unles the shell is listed there.

	\item[\fn{/etc/termcap}]
	The terminal capability database.  Describes by what ``escape
	sequences'' various terminals can be controlled.  Programs are
	written so that instead of directly outputting an escape
	sequence that only works on a particular brand of terminal,
	they look up the correct sequence to do whatever it is they
	want to do in \fn{/etc/termcap}.  As a result most programs
	work with most kinds of terminals.  See the 
	\man{termcap(5)}, \man{curs\_termcap(3)}, and \man{terminfo(5)}
	manual pages for more information.
	\end{dispitems}

	\meta HOSTNAME, adjtime, disktab, gettydefs, networking
	(exports, host.conf, hosts, hosts.equiv, inetd.conf, named.*,
	networks, ntp.conf, protocols, resolv.conf, rpc, services,
	syslog.conf), mtools, and so forth.

\subsection{The \fn{/dev} directory}

	The \fn{/dev} directory contains the special device files for
	all the devices.  The device files are named using special
	conventions; these are described in appendix~\ref{app:device-list}.
	The device files are created during installation, and later with
	the \cmd{/dev/MAKEDEV} script.  The \cmd{/dev/MAKEDEV.local} is
	a script written by the system administrator that creates local-only
	device files or links (i.e., those that are not part of the
	standard \cmd{MAKEDEV}, such as device files for some non-standard
	device driver).

\section{The \fn{/usr} filesystem}

	The \fn{/usr} filesystem is often large, since all programs
	are installed there.  All files in \fn{/usr} usually come from
	a Linux distribution; locally installed programs and other
	stuff goes below \fn{/usr/local}.  This makes it possible to 
	update the system from a new version of the distribution, or even
	a completely new distribution, without having to install all programs
	again.
	Some of the subdirectories of \fn{/usr} are listed below (some of
	the less important directories have been dropped; see the FSSTND
	for more information).
		%
	\begin{dispitems}
	\item[\fn{/usr/X11R6}]
		The X Window System, all files.  To simplify the development
		and installation of X, the X files have not been
		integrated into the rest of the system.  There is a
		directory tree below \fn{/usr/X11R6} similar to that below
		\fn{/usr} itself.
	\item[\fn{/usr/X386}]
		Similar to \fn{/usr/X11R6}, but for X11 Release 5.
	\item[\fn{/usr/bin}]
		Almost all user commands.  Some commands are in
		\fn{/bin} or in \fn{/usr/local/bin}.
	\item[\fn{/usr/sbin}]
		System administration commands that are not needed on
		the root filesystem, e.g., most server programs.
	\item[\fn{/usr/man}, \fn{/usr/info}, \fn{/usr/doc}]
		Manual pages, GNU Info documents, and miscellaneous
		other documentation files, respectively.
	\item[\fn{/usr/include}]
		Header files for the C programming language.  This should
		actually be below \fn{/usr/lib} for consistency, but
		the tradition is overwhelmingly in support for this name.
	\item[\fn{/usr/lib}]
		Unchanging data files for programs and subsystems, including
		some site-wide configuration files.  The name \texttt{lib}
		comes from library; originally libraries of programming
		subroutines were stored in \fn{/usr/lib}.
	\item[\fn{/usr/local}]
		The place for locally installed software and other files.
	\end{dispitems}

\section{The \fn{/var} filesystem}

	The \fn{/var} contains data that is changed when the system is
	running normally.  It is specific for each system, i.e., not
	shared over the network with other computers.
		%
	\begin{dispitems}
	\item[\fn{/var/catman}]
		A cache for man pages that are formatted on demand.
		The source for manual pages is usually stored in
		\fn{/usr/man/man*}; some manual pages might come with
		a pre-formatted version, which is stored in \fn{/usr/man/cat*}.
		Other manual pages need to be formatted when they are
		first viewed; the formatted version is then stored
		in \fn{/var/man} so that the next person to view the
		same page won't have to wait for it to be formatted.
		(\fn{/var/catman} is often cleaned in the same way
		temporary directories are cleaned.)
	\item[\fn{/var/lib}]
		Files that change while the system is running normally.
	\item[\fn{/var/local}]
		Variable data for programs that are installed in
		\fn{/usr/local} (i.e., programs that have been installed
		by the system administrator).  Note that even locally
		installed programs should use the other \fn{/var} directories
		if they are appropriate, e.g., \fn{/var/lock}.
	\item[\fn{/var/lock}]
		Lock files.  Many programs follow a convention to
		create a lock file in \fn{/var/lock} to indicate that
		they are using a particular device or file.  Other
		programs will notice the lock file and won't attempt
		to use the device or file.
	\item[\fn{/var/log}]
		Log files from various programs, especially \cmd{login}
		(\fn{/var/log/wtmp}, which logs all logins ans logouts
		into the system) and \cmd{syslog} (\fn{/var/log/messages},
		where all kernel and system program message are usually
		stored).  File in \fn{/var/log} can often grow indefinitely,
		and may require cleaning at regular intervals.
	\item[\fn{/var/run}]
		Files that contain information about the system that is
		valid until the system is next booted.  For example,
		\fn{/var/run/utmp} contains information about people
		currently logged in.
	\item[\fn{/var/spool}]
		Directories for mail, news, printer queues, and other
		queued work.  Each different spool has its own
		subdirectory below \fn{/var/spool}, e.g., the mailboxes
		of the users are in \fn{/var/spool/mail}.
	\item[\fn{/var/tmp}]
		Temporary files that are large or that need to exist
		for a longer time than what is allowed for \fn{/tmp}.
		(Although the system administrator might not allow
		very old files in \fn{/var/tmp} either.)
	\end{dispitems}


\section{The \fn{/proc} filesystem}

	The \fn{/proc} filesystem contains a illusionary filesystem.
	It does not exist on a disk.  Instead, the kernel creates it
	in memory.  It is used to provide information about the
	system (originally about processes, hence the name).  Some
	of the more important files and directories are explained
	below.  The \fn{/proc} filesystem is described in more detail
	in the \man{proc(5)} manual page.
		%
	\begin{dispitems}
	\item[\fn{/proc/1}]
		A directory with information about process number 1.
		Each process has a directory below \fn{/proc} with
		the name being its process identification number.
	\item[\fn{/proc/cpuinfo}]
		Information about the processor, such as its type, make,
		model, and perfomance.
	\item[\fn{/proc/devices}]
		List of device drivers configured into the currently
		running kernel.
	\item[\fn{/proc/dma}]
		Shows which DMA channels are being used at the moment.
	\item[\fn{/proc/filesystems}]
		Filesystems configured into the kernel.
	\item[\fn{/proc/interrupts}]
		Shows which interrupts are in use, and how many of each
		there have been.
	\item[\fn{/proc/ioports}]
		Which I/O ports are in use at the moment.
	\item[\fn{/proc/kcore}]
		An image of the physical memory of the system.  This
		is exactly the same size as your physical memory, but
		does not really take up that much memory; it is generated
		on the fly as programs access it.  (Remember: unless you
		copy it elsewhere, nothing under \fn{/proc} takes up
		any disk space at all.)
	\item[\fn{/proc/kmsg}]
		Messages output by the kernel.  These are also routed
		to \cmd{syslog}.
	\item[\fn{/proc/ksyms}]
		Symbol table for the kernel.
	\item[\fn{/proc/loadavg}]
		The `load average' of the system; three meaningless
		indicators of how much work the system has to do at
		the moment.
	\item[\fn{/proc/meminfo}]
		Information about memory usage, both physical and swap.
	\item[\fn{/proc/modules}]
		Which kernel modules are loaded at the moment.
	\item[\fn{/proc/net}]
		Status information about network protocols.
	\item[\fn{/proc/self}]
		A symbolic link to the process directory of the program
		that is looking at \fn{/proc}.  When two processes look
		at \fn{/proc}, they get different links.  This is mainly
		a convenience to make it easier for programs to get
		at their process directory.
	\item[\fn{/proc/stat}]
		Various statistics about the system, such as the number
		of page faults since the system was booted.
	\item[\fn{/proc/uptime}]
		The time the system has been up.
	\item[\fn{/proc/version}]
		The kernel version.
	\end{dispitems}
		%
	Note that while the above files tend to be easily readable text
	files, they can sometimes be formatted in a way that is not
	easily digestable.  There are many commands that do little more
	than read the above files and format them for easier understanding.
	For example, the \cmd{free} program reads \fn{/proc/meminfo}
	and converts the amounts given in bytes to kilobytes (and adds
	a little more information, as well).
