% $Id: fstype.tex,v 5.2 90/06/23 22:21:54 jsp Rel $
%
% Copyright (c) 1989 Jan-Simon Pendry
% Copyright (c) 1989 Imperial College of Science, Technology & Medicine
% Copyright (c) 1989 The Regents of the University of California.
% All rights reserved.
%
% This code is derived from software contributed to Berkeley by
% Jan-Simon Pendry at Imperial College, London.
%
% Redistribution and use in source and binary forms are permitted provided
% that: (1) source distributions retain this entire copyright notice and
% comment, and (2) distributions including binaries display the following
% acknowledgement:  ``This product includes software developed by the
% University of California, Berkeley and its contributors'' in the
% documentation or other materials provided with the distribution and in
% all advertising materials mentioning features or use of this software.
% Neither the name of the University nor the names of its contributors may
% be used to endorse or promote products derived from this software without
% specific prior written permission.
% THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
% WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
%
%	@(#)fstype.tex	5.1 (Berkeley) 7/19/90


\Chapter{Filesystem types}\label{filesystems}

To mount a volume, \amd\ must be told the type of filesystem to be used.
Each filesystem type typically requires additional information such as the fileserver
name for \NFS.

From the point of view of \amd, a {\em filesystem} is anything
that can resolve an incoming name lookup.
An important feature is support for multiple filesystem types.
Some of these filesystems are implemented in
the local kernel and some on remote fileservers, whilst the others are implemented
internally by \amd.

The two common filesystem types are \UFS\ and \NFS.
Four other user accessible filesystems ({\tt link}, {\tt program}, {\tt auto}
and {\tt direct}) are also implemented
internally by \amd\ and these are described below.
There are two additional filesystem
types internal to \amd\ which are not directly accessible
to the user ({\tt inherit} and {\tt error}).  Their use is described since they may
still have an effect visible to the user.

\Section[Network Filesystem]{Network Filesystem ({\tt type:=nfs})}

The {\em nfs} filesystem type provides access to Sun's \NFS.
The following options may be specified:
\begin{description}
\item[\tt rhost]
the remote fileserver.  This must be an entry in the hosts database.
IP addresses \cite{rfc:ip} are not accepted.
The default value is taken from the local host name (\Var{host})
if no other value is specified.

\item[\tt rfs]
the remote filesystem.
If no value is specified for this option, an internal default of
\Var{path} is used.

\end{description}

\NFS\ mounts require a two stage process.  First, the {\em file handle} of
the remote file system must be obtained from the server.  Then a mount
system call must be done on the local system.
\Amd\ keeps a cache of file handles for remote file systems.  The cache
entries have a lifetime of a few minutes.

If a required file handle is not in the cache, \amd\ sends a request
to the remote server to obtain it.  \Amd\ {\em does not} wait for
a response; it notes that one of the locations needs retrying, but
continues with any remaining locations.  When the file handle becomes
available, and assuming none of the other locations was successfully
mounted, \amd\ will retry the mount.  This mechanism allows several
\NFS\ filesystems to be mounted in parallel\footnote{The mechanism
is general, however \NFS\ is the only filesystem
for which the required hooks have been written.}.
The first one which
responds with a valid file handle will be used.

An \NFS\ entry might be:
\begin{quote}
\tt
jsp\ \ host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp
\end{quote}

The mount system call and any unmount attempts are always done
in a new task to avoid the possibilty of blocking \amd.

\Section[Network Host Filesystem]{Network Host Filesystem ({\tt type:=host})}

The {\em host} filesystem allows access to the entire export tree of
an \NFS\ server.  The implementation is layered above the {\tt nfs} implementation
so keep-alives work in the same way.
The only option which needs to specified is {\tt rhost} which is the name
of the fileserver to mount.

The {\tt host} filesystem type works by querying the mount daemon on the
given fileserver to obtain its export list.  \Amd\ then obtains filehandles
for each of the exported filesystems.  Any errors at this stage cause that
particular filesystem to be ignored.  Finally each filesystem is mounted.
Again, errors are logged but ignored.  One common reason for mounts to fail
is that the mount point does not exist.  Although \amd\ attempts to
automatically create the mount point, it may be on a remote filesystem
to which \amd\ does not have write permission.

Sun's automounter provides a special {\tt -hosts} map.  To achieve the same
effect with \amd\ requires two steps.  First a mount map must be created as
follows
\begin{verbatim}
/defaults  type:=host;fs:=${autodir}/${rhost}/root;rhost:=${key}
*          opts:=rw,nosuid,grpid
\end{verbatim}
and then start \amd\ with the following command
\begin{quote}
\tt
amd /n net.map
\end{quote}
where {\tt net.map} is the name of map described above.
Note that the value of \Var{fs} is overridden in the map.  This is done to
avoid a clash between the mount tree and any other filesystem already
mounted from the same fileserver.

If different mount options are needed for different hosts then additional
entries can be added to the map, for example
\begin{verbatim}
host2       opts:=ro,nosuid,soft
\end{verbatim}
would soft mount {\tt host2} read-only.

\Section[\Unix\ Filesystem]{\Unix\ Filesystem ({\tt type:=ufs})}

The {\em ufs} filesystem type provides access to the system's
standard disk filesystem---usually the Berkeley Fast Filesystem \cite{bsd:ufs}.
The following option must be specified:
\begin{description}
\item[\tt dev]
the block special device to be mounted.
\end{description}

A \UFS\ entry might be:
\begin{quote}
\tt
jsp\ \ \ host==charm;type:=ufs;dev:=/dev/xd0g;sublink:=jsp
\end{quote}

\Section[Program Filesystem]{Program Filesystem ({\tt type:=program})}\label{pfs}

The {\em program} filesystem type allows a program to be run
whenever a mount or unmount is required.  This allows easy
addition of support for other filesystem types, such as MIT's
Remote Virtual Disk (RVD) \cite{mit:rvd} which has a programmatic interface via
the commands {\tt rvdmount} and {\tt rvdunmount}.

The following options must be specified:
\begin{description}
\item[\tt mount]
the program which will perform the mount.

\item[\tt unmount]
the program which will perform the unmount.
\end{description}

The exit code from these two programs is interpreted as a \Unix\ error
code.  As usual, exit code zero indicates success.
To execute the program \amd\ splits the string on whitespace to
create an array of substrings.
Single quotes ``{\tt '}'' can be used to quote whitespace if that is
required in an argument.  There is no way to escape or change the quote character.
To run the program {\tt rvdmount} with a host name and filesystem as
arguments would be specified by {\tt mount:="/etc/rvdmount rvdmount fserver \$\{path\}"}.

The first element in the array is taken as the pathname of the program
to execute.  The other members of the array form the argument vector
to be passed to the program, {\em including argument zero}.  This means
that the split string must have at least two elements.
The program is directly executed by \amd, not via a shell.

If a filesystem type is to be heavily used, it may be worthwhile
adding a new filesystem type into \amd, but for most uses the
program filesystem should suffice.

When the program is run, standard input and standard error are inherited
from the current values used by \amd.  Standard output is a duplicate of
standard error.  The value specified with the ``-l'' command line option
has no effect on standard error.

\Section[Symbolic Link Filesystem]{Symbolic Link Filesystem ({\tt type:=link})}

The {\em link} filesystem type allows other parts of the filesystem
to be referenced as if they were mounted under the automounter.
Under SunOS 4.0 this can also be done using the loopback filesystem,
however that adds an unnecessary extra mount into the system.

One common use for the symlink filesystem is {\tt /homes}
which can be made to contain an entry for each user which points
to their (auto-mounted) home directory.  Although this may seem
rather expensive, it provides a great deal of administrative
flexibility.

The value of \opt{fs} option specifies the destination of the link, as modified
by the \opt{sublink} option.  If \opt{sublink} is non-null, it
is appended to \Var{fs}{\tt /} and the resulting string is used as the target.

The {\tt link} filesystem can be though of as identical to the {\tt ufs} filesystem
but without actually mounting anything.

An example entry might be
\begin{quote}
\tt
jsp\ \ \ host==charm;type:=link;fs:=/home/charm;sublink:=jsp
\end{quote}
which would return a symbolic link pointing to {\tt /home/charm/jsp}.

\Section[Automount Filesystem]{Automount Filesystem ({\tt type:=auto})}\label{auto-fs}

The {\em auto} filesystem type creates a new automount point
below an existing automount point.
Top-level automount points appear as system mount points.
An automount mount point can also appear as a sub-directory of an existing mount point.
This allows some additional structure to be added,
for example to mimic the mount tree of another
machine.%\footnote{
%Future work will allow a tree of automount points to be built by
%examining the exported mount tree of a remote fileserver.}

The following option may be specified:
\begin{description}
\item[\tt cache]\label{afs:cache}
specifies whether the data in this mount-map should be
cached.  The default value is {\tt none}, in which case
no caching is done in order to conserve memory.
However, better performance and reliability can be obtained by caching
some or all of a mount-map.  If the cache option specifies {\tt all},
the entire map is enumerated when the mount point is created.
If the cache option specifies {\tt inc}, caching is done incrementally
as and when data is required.
Some map types do not support cache mode {\tt all}, in which case {\tt inc}
is used whenever {\tt all} is requested.

The default cache mode is {\tt none} which means that no data will be cached.
Each mount map type has a default cache type, usually {\tt inc}, which
can be selected by specifying {\tt mapdefault}.

The cache mode for a mount map can only be selected on the command line.  Starting
\amd\ with the command
\begin{quote}
\tt
amd /homes hesiod.homes -cache:=inc
\end{quote}
will cause {\tt /homes} to be automounted using the {\em Hesiod} name server with local
incremental caching of all succesfully resolved names.

All cached data is forgotten whenever \amd\ receives
a {\tt SIGHUP} signal.  If cache {\tt all} mode was selected, the
cache will be reloaded.  This can be used to inform \amd\ that a map
has been updated.  In addition, whenever a cache lookup fails and \amd\ needs
to examine a map, the map's modify time is examined.  If the cache is out
of date with respect to the map then it is flushed as if a {\tt SIGHUP} had
been received.
\end{description}

The \opt{fs} option specifies the name of the mount map to use for the new
mount point.\footnote{
Arguably this should have been specified with the \Var{rfs} option but
we are now stuck with it due to historical accident.}
%If the string ``{\tt .}'' is used then the same map is used;
%in addition the lookup prefix is set to the name of the mount point followed
%by a slash ``{\tt /}''.
%This is the same as specifying {\tt fs:=\$\{map\};pref:=\$\{key\}/}.
The prefix alters the name that is looked up in the mount map.  If the
prefix is non-null then it is prepended to the name requested by
the kernel {\em before} the map is searched.
The prefix can be overridden with the \opt{pref} option.

The server {\tt dylan.doc.ic.ac.uk} has two user disks: {\tt /dev/dsk/2s0} and
{\tt /dev/dsk/5s0}.  These are accessed as {\tt /home/dylan/dk2} and
{\tt /home/dylan/dk5} respectively.  Since {\tt /home} is already an automount
point, this naming is achieved with the following map entries:
\begin{quote}\raggedright
\tt
dylan\ \ \ \ \ \ \ \ type:=auto;fs:=\Var{map};pref:=\Var{key}/ \\
dylan/dk2\ \ \ \ type:=ufs;dev:=/dev/dsk/2s0 \\
dylan/dk5\ \ \ \ type:=ufs;dev:=/dev/dsk/5s0
\end{quote}

\Section[Direct Automount Filesystem]{Direct Automount Filesystem ({\tt type:=direct})}\label{direct-fs}

The {\em direct} filesystem is almost identical to the automount filesystem.
Instead of appearing to be a directory of mount points, it appears
as a symbolic link to a mounted filesystem.  The mount is done at
the time the link is accessed.

Direct automount points are created by specifying the {\tt direct} filesystem
type on the command line:
\begin{quote}
\tt
amd ... /usr/man auto.direct -type:=direct
\end{quote}
where {\tt auto.direct} would contain an entry such as:
\begin{quote}\raggedright
\tt
usr/man\ \ \ \ -type:=nfs;rfs:=/usr/man \verb+\+ \\
\ \ \ \ \ \ \ \ \ \ \ rhost:=man-server1\ \ rhost:=man-server2
\end{quote}
In this example, {\tt man-server1} and {\tt man-server2} are file servers
which export copies of the manual pages.
Note that the key does {\em not} have a leading ``{\tt /}''.

\Section[Error Filesystem]{Error Filesystem ({\tt type:=error})}\label{error-fs}

The {\em error} filesystem type is used internally as a catch-all in
the case where none of the other filesystems was selected, or some other
error occurred.
Lookups always fail with ``No such file or directory''.
All other operations trivially succeed.

The error filesystem is not directly accessible.

\Section[Inheritance Filesystem]{Inheritance Filesystem ({\tt type:=inherit})}\label{ifs}

The inheritance filesystem is not directly accessible.
Instead, internal mount nodes of this type are automatically generated
when \amd\ is started with the ``-r'' option.
At this time the system mount table ({\tt /etc/mtab})\footnote{
in fact many systems maintain this information in the kernel
rather than a file.}
is scanned to locate
any filesystems which are already mounted.  If any reference to 
these filesystems is made through \amd\ then instead of attempting
to mount it, \amd\ simulates the mount and {\em inherits} the
filesystem.  This allows a new version of \amd\ to be installed
on a live system simply by killing the old daemon and starting
the new one.

This filesystem type is not generally visible externally, but it is
possible that the output from {\tt amq -m} may list {\tt inherit} as
the filesystem type.  This happens when an inherit operation cannot
be completed for some reason, usually because a fileserver is down.
