Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume21/amd/part13

Internet Message Format | 1990-04-10 | 51.4 KB

Subject:  v21i101:  An Automounter for NFS systems, Part13/13
Newsgroups: comp.sources.unix
Approved: [e-mail]
X-Checksum-Snefru: 61f3d124 582498ed 5ead014e 5c88b119

Submitted-by: Jan-Simon Pendry <[e-mail]>
Posting-number: Volume 21, Issue 101
Archive-name: amd/part13

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 13 (of 13)."
# Contents:  doc/amd.tex.1
# Wrapped by [e-mail] on Tue Apr 10 15:12:17 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/amd.tex.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'doc/amd.tex.1'\"
else
echo shar: Extracting \"'doc/amd.tex.1'\" \(49780 characters\)
sed "s/^X//" >'doc/amd.tex.1' <<'END_OF_FILE'
X%
X% Run this through \LaTeX...
X%
X% $Id: amd.tex,v 5.1.1.3 90/01/11 17:05:26 jsp Exp Locker: jsp $
X%
X% Copyright (c) 1989 Jan-Simon Pendry
X% Copyright (c) 1989 Imperial College of Science, Technology & Medicine
X% Copyright (c) 1989 The Regents of the University of California.
X% All rights reserved.
X%
X% This code is derived from software contributed to Berkeley by
X% Jan-Simon Pendry at Imperial College, London.
X%
X% Redistribution and use in source and binary forms are permitted
X% provided that the above copyright notice and this paragraph are
X% duplicated in all such forms and that any documentation,
X% advertising materials, and other materials related to such
X% distribution and use acknowledge that the software was developed
X% by Imperial College of Science, Technology and Medicine, London, UK.
X% The names of the College and University may not be used to endorse
X% or promote products derived from this software without specific
X% prior written permission.
X% THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
X% IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
X% WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
X%
X%    %W% (Berkeley) %G%
X
X
X%
X% Set this to Report for a report
X% or Article for an article
X%
X\def\ArticleReport{Article}
X
X
X\def\Article{Article}
X\def\ifarticle{\ifx\ArticleReport\Article}
X
X%\documentstyle[a4,nh,11pt,twoside,openbib,draft]{report}
X
X%\documentstyle[a4,nh,11pt,openbib,draft]{report}
X\ifarticle
X\documentstyle[a4,nh]{article}
X\else
X\documentstyle[a4,nh,11pt,openbib]{report}
X\fi
X\newcommand{\DRAFT}{}%{DRAFT}
X\newcommand{\VERSION}{5.1c}
X
X%
X% The next block of commands are only used in report mode
X%
X\ifarticle
X\newcommand{\Chapter}{\section}\renewcommand{\chapter}{\section}
X\newcommand{\Section}{\subsection}
X\newcommand{\Subsection}{\subsubsection}
X\else
X\newcommand{\Chapter}{\chapter}
X\newcommand{\Section}{\section}
X\newcommand{\Subsection}{\subsection}
X\fi
X
X\pagestyle{footers}
X\pagenumbering{roman}
X
X\newcommand{\Edition}{Second}
X
X\newcommand{\see}{}
X
X\setheader{}
X\setfooter{}
X\setchapterfoot{}
X
X\ifarticle\else
X\setcounter{tocdepth}{2}
X\setcounter{secnumdepth}{2}
X\fi
X
X\newcommand{\C}{{\sf C}}
X\newcommand{\Unix}{{\sc Unix}}
X\newcommand{\NFS}{{\sf NFS}}
X\newcommand{\UFS}{{\sf UFS}}
X\newcommand{\Amd}{{\sf Amd}}
X\newcommand{\Amq}{{\sf Amq}}
X\newcommand{\amd}{{\sf amd}}
X\newcommand{\amq}{{\sf amq}}
X\newcommand{\opt}[1]{{\tt #1}}
X\newcommand{\Ref}[1]{{\S\ref{#1},~p\pageref{#1}}}
X\newcommand{\Var}[1]{{\tt \$\{{#1}\}}}
X\newcommand{\etc}{{\em etc\/}}
X\newcommand{\ie}{{\em\/ie\/}}
X\newcommand{\eg}{{\em\/eg\/}}
X
X\begin{document}
X
X\begin{titlepage}
X\vskip 6.6em
X\begin{center}
X{\LARGE\Amd\ -- An Automounter}\\[.2cm]
X{
X%\Large \Edition\ Edition \\[.1cm]
X{\DRAFT}
X}
X\par
X\vskip 2.2em
X{\large \lineskip .75em
X\begin{tabular}[t]{c}
X{\Large\em Jan-Simon Pendry} \\
X{\tt <[e-mail]>}\\
XDepartment of Computing,\\
XImperial College,\\
XLondon SW7 2BZ
X\end{tabular}\par}
X
X\vskip 1.3em
X
X{\small December 1989\par}
X{\small Printed \today}
X\end{center}\par
X
X\vskip 6em
X
X\begin{center}
X{\Large\bf Abstract}
X\end{center}
X{\parindent 0pt
X{\bf amd}, {\em $\acute{e}$i$\acute{e}$md$\acute{\imath}$:},
Xa program providing an automounting service
X[fr. {\em A}uto{\em M}ount {\em D}aemon]\par
X{\bf automount}, {\em \"{o}'t\={o}-mownt, v.i.}
Xto mount a filesystem automatically
X[Gr.\ {\em automatos}, self-moving $+$ \Unix\ {\bf mount}(2)]%---L.
X%{\em m\={o}ns, montis}, mountain]
X}
X\par\mbox{}\par
X
XAn {\em automounter} maintains a cache of mounted filesystems.
XFilesystems are mounted on demand when they are first referenced
Xand unmounted after a period of inactivity.
X\par\mbox{}\par
X
X\Amd\ may be used as a replacement for Sun's automounter \cite{usenix:automounter}.
XThe choice of which filesystem to mount can be controlled dynamically
Xwith {\em selectors}.
XSelectors allow decisions of the form
X``hostname is {\em this}\,'' or ``architecture is not {\em that}.''
XSelectors may be combined arbitrarily.
X\Amd\ also supports a variety of filesystem types,
Xincluding \NFS, \UFS\ and the novel {\em program}
Xfilesystem.
XThe combination of selectors and multiple filesystem types allows
Xidentical configuration files to be used on each machine so
Xreducing the administrative overhead.
X
X\Amd\ ensures that it will not hang if a remote server
Xgoes down.  Moreover, \amd\ can determine when a remote
Xserver has become inaccessible and then mount replacement
Xfilesystems as and when they become available.
X\par\mbox{}\par
X\Amd\ contains no proprietary source code and
Xhas been ported to numerous flavours of \Unix.
X
X%\ifarticle\else
X\newpage
X\vspace*{30pt}
X%{\large
X%\parindent 0pt
X%WARNING:
X%%warnings go here
X%}\par
X\vspace{4in}
X{\parindent 0pt
XThis document describes release ``\VERSION'' of \amd.\par
X\vskip 1ex
XCopyright \copyright\ 1989 Jan-Simon Pendry\\
XCopyright \copyright\ 1989 Imperial College of Science, Technology \& Medicine\\
XCopyright \copyright\ 1989 The Regents of the University of California.
X\vskip 1ex
XAll Rights Reserved.
X\vskip 1ex
X\begin{flushleft}
XPermission to copy this document, or any portion of it, as\\
Xnecessary for use of this software is granted provided this\\
Xcopyright notice and statement of permission are included.
X\end{flushleft}
X}
X%\fi %!article
X\end{titlepage}
X
X\setheader{\vbox{\hbox to\hsize{\rightmark\hfill\thepage}\vskip 2pt\hrule}}
X%\setbothheaders
X%{\vbox{\hbox to\hsize{\thepage\hfill\leftmark}\vskip 2pt\hrule}}%
X%{\vbox{\hbox to\hsize{\rightmark\hfill\thepage}\vskip 2pt\hrule}}
X
X%\setfooter{\hfil\Edition\ Edition {\DRAFT}\hfil}
X\setfooter{\hfil{\DRAFT}\hfil}
X%\setbothfooters
X%{\thepage\hfil\Edition\ Edition {\DRAFT}}%
X%{\Edition\ Edition {\DRAFT}\hfil\thepage}
X
X%\setchapterfoot{\thepage\hfil\Edition\ Edition {\DRAFT}\hfil\thepage}
X%\setchapterfoot{\Edition\ Edition {\DRAFT}\hfil\thepage}
X\setchapterfoot{{\DRAFT}\hfil\thepage\hfil}
X
X\ifarticle\else
X\tableofcontents
X\fi
X
X\Chapter{Overview}
X\pagenumbering{arabic}
X
X\Amd\ maintains a cache of mounted filesystems.  Filesystems are {\em demand-mounted}
Xwhen they are first referenced and unmounted after a period of inactivity.
X\Amd\ may be used as a replacement for Sun's {\bf automount}(8) \cite{sun:automount} program.
XIt contains no proprietary source code and has been ported
Xto numerous flavours of \Unix.
X
X\Amd\ was designed as the basis for experimenting with filesystem
Xlayout and management.  Although \amd\ has many direct applications it
Xis loaded with additional features which have little use.
XAt some point the infrequently used components may be removed to
Xstreamline the production system.
X
X\Amd\ supports the notion of {\em replicated} filesystems by evaluating
Xeach member of a list of possible filesystem locations in parallel.
X\Amd\ checks that each cached mapping remains valid.  Should a mapping be
Xlost -- such as happens when a fileserver goes down -- \amd\ automatically
Xselects a replacement should one be available.
X
XThe fundamental concept is to separate the name used to refer to
Xa file from the name used to refer to its physical storage location.
XThis allows the same files to be accessed with the same name regardless of where
Xin the network the name is used.  This is very different from placing
X{\tt /n/hostname} in front of the pathname since that includes location
Xdependent information which may change if files are moved to another
Xmachine.
XBy placing the required mappings in a centrally administered database,
Xfilesystems can be re-organised without requiring changes to password
Xfiles, shell scripts and so on.
X
X\Section{Filesystem Namespace}
X
X\Unix\ provides two forms of binding between names and files.
XA {\em hard link} completes the binding when the name is added to the filesystem.
XA {\em soft link} delays the binding until the name is accessed.
XAn {\em automounter} adds a further form in which the binding of name to
Xfilesystem is delayed until the name is accessed.
X
X\Amd\ operates by introducing new mount points into the filesystem.
XThe kernel sees these mount points as \NFS\ \cite{sun:nfs} filesystems being served by \amd.
XHaving attached itself to the filesystem, \amd\ is now able to control
Xthe view the rest of the system has of those mount points.
X
X\Section{Operational Principles}
X
X\Amd\ receives requests from the kernel one at a time.
XThe requests are RPC \cite{sun:rpc} calls using the \NFS\ protocol.
X
XWhen a {\em lookup} call is received \amd\ mounts the required
Xfilesystem if it is not already mounted and then returns a symbolic link
Xpointing to the real mount point.
XOnce the symbolic link is returned, the kernel will send all
Xother requests direct to the mounted filesystem.
XIf a filesystem is not yet mounted, \amd\ consults a configuration
X{\em mount-map} corresponding to the automount point.
X\Amd\ then makes a runtime decision on what and where to mount
Xa filesystem based on the information obtained from the map.
X
X\Amd\ does not implement all the \NFS\ requests; only those
Xrelevant to name binding such as {\em lookup}, {\em readlink}
Xand {\em readdir}.  Some other calls are also implemented
Xbut most simply return an error code; for example {\em mkdir}
Xalways returns ``Read-only filesystem''.
X
X\Section{Mounting a Filesystem}
X
XEach automount point has a mount map.  The mount map contains
Xa list of key--value pairs.  The key is the name of the filesystem to
Xbe mounted.  The value is a list of locations describing where the
Xfilesystem is stored.
XIn the source for the map the value would look like
X\begin{quote}
X${\em location}_1\ \ {\em location}_2\ \ \ldots\ \ {\em location}_n$
X\end{quote}
X
X\Amd\ examines each location in turn.  Each location may contain {\em selectors}
Xwhich control whether \amd\ can use that location.  For example, the location
Xmay be restricted to use by certain hosts.  Those locations which cannot be used
Xare ignored.
X
X\Amd\ attempts to mount the filesystem described by each remaining location
Xuntil a mount succeeds or \amd\ can no longer proceed.
XThe latter can occur in three ways:
X\begin{itemize}
X\item
XIf none of
Xthe locations could be used, or if all of the locations caused an error,
Xthen the last error is returned.
X
X\item
XIf a location could be used but was mounted in the background then \amd\ marks
Xthat mount as being in progress and continues with the next request; no reply
Xis sent to the kernel.
X
X\item
XLastly, one or more of the mounts may have been {\em deferred}.
XA mount is deferred if extra information is required before the mount
Xcan proceed.  When the information becomes available the mount will
Xtake place, but in the mean time no reply is sent to the kernel.
XIf the mount is deferred, \amd\ continues to try any remaining locations.
X\end{itemize}
X
X\Section{Non-blocking Operation}
X
XSince there is only one instance of \amd\ for each automount point,
Xand usually only one instance on each machine, it is important
Xthat it is always available to service kernel calls.
X\Amd\ goes to great lengths to ensure that it does not block in a system call.
XAs a last resort \amd\ will fork before it attempts a system call that may block
Xindefinitely, such as mounting an \NFS\ filesystem.
XOther tasks such as obtaining filehandle information for an \NFS\ filesystem,
Xare done using a purpose built non-blocking RPC library which is integrated
Xwith \amd's task scheduler (\see \Ref{task scheduler}).
XThis library is also used to implement \NFS\ keep-alives (\see \Ref{keepalives}).
X
XWhenever a mount is deferred or backgrounded, \amd\ must wait for it to complete
Xbefore replying to the kernel.  However, this would cause \amd\ to block waiting
Xfor a reply to be constructed.  Rather than do this, \amd\ simply {\em drops}
Xthe call under the assumption that the kernel RPC mechanism will automatically
Xretry the request.
X
X\Section{Task Scheduling}\label{task scheduler}
X
X\Amd\ provides a task scheduler to support its non-blocking semantics.
XThe basic operation of the scheduler is to call a procedure when
Xa particular event occurs.  A general sleep/wakeup mechanism is used
Xand sub-process support is built on that.  The scheduler maintains
Xtwo queues: one of blocked calls and one of callbacks waiting to
Xbe made.
XWhen a child process exits, its exit status is picked up by a signal
Xhandler and a wakeup is issued on the internal job descriptor for that sub-process.
XA timeout/untimeout mechanism provides for time dependent processing.
X
X\Section{Automatic Unmounting}
X
XTo avoid an ever increasing number of filesystem mounts, \amd\ unmounts
Xa filesystem that appears not to have been used recently.  A time-to-live
Xinterval is associated with each mounted filesystem and when that interval
Xexpires, \amd\ unmounts the filesystem.
XIf the unmount fails, for example the filesystem is still active,
Xthe time-to-live interval is extended.
XThe global default for this grace period is controlled by the ``-w'' command-line
Xoption (\see \Ref{opt:wait}).  It is also possible to set this value on a per-mount basis
X(\see \Ref{opt:utimeout}).
X
X\Section{Keep-alives}\label{keepalives}
X
XUse of some filesystem types requires the presence of a server on another machine.
XIf a machine crashes then it is of no concern to processes on that machine
Xthat the filesystem is unavailable.  However, to processes on a remote host using
Xthat machine as a fileserver this event is important.  This situation is
Xmost widely recognised when an \NFS\ server crashes and the behaviour observed
Xon client machines is that more and more processes hang.
X
XIn order to provide the possibility of recovery, \amd\ implements a {\em keep-alive}
Xinterval timer for some filesystem types.
XCurrently only \NFS\ makes use of this service.
X
XThe basis of the \NFS\ keep-alive implementation is the observation that
Xmost sites maintain replicated copies of common system data such as manual
Xpages, most or all programs, system source code and so on.
XIf one of those servers goes down it would be reasonable to mount one of
Xthe others as a replacement.
X
X\Amd\ keeps track of which servers are up and which are down.
XIt does this by sending RPC requests to the servers' \NFS\ {\sc NullProc} and
Xchecking whether a reply is returned.  If no replies are received after a
Xshort period, \amd\ marks the fileserver {\em down}.
XRPC requests continue to be sent so that it will notice when a fileserver
Xcomes back up.
XICMP echo packets \cite{rfc:icmp} are not used because it is the availability
Xof the \NFS\ service that is important, not the existence of a base kernel.
X
XWhenever a reference to a fileserver which is down is made via \amd\, an alternate
Xfilesystem is mounted if one is available.  Although this action does not protect
Xuser files, which are unique on the network, or processes which do not access files
Xvia \amd\ or already have open files on the hung filesystem, it can prevent most new
Xprocesses from hanging.
X
XWith a suitable combination of filesystem management and mount-maps,
Xmachines can be protected against most server downtime.  This can be
Xenhanced by allocating boot-servers dynamically which allows a diskless
Xworkstation to be quickly restarted if necessary.  Once the root filesystem
Xis mounted, \amd\ can be started and allowed to mount the remainder of
Xthe filesystem from whichever fileservers are available.
X
X
X\Chapter{Mount-maps}
X
X\Amd\ has no built-in knowledge of machines or filesystems.
XExternal {\em mount-maps} are used to provide the required information.
XSpecifically, \amd\ needs to know when and under what conditions it should
Xmount filesystems.
X
XThe map entry corresponding to the requested name contains
Xa list of possible locations from which to resolve the request.
XEach location specifies  filesystem type, information required by that
Xfilesystem (for example the block special device in the case of \UFS), and
Xsome information describing where to mount the filesystem (\see \Ref{mount location}).
XA location may also contain {\em selectors} (\see \Ref{selectors}).
X
X\Section{Map Types}
X
XA mount-map can be implemented as a regular file, an ndbm database
Xa YP map \cite{sun:yp} or via
Xthe {\em Hesiod} \cite{mit:hesiod} name server.\footnote{
XIn future, gdbm databases will also be supported.}
XA mount-map name is a sequence of characters.
XWhen an automount point is created a handle on the mount-map
Xis obtained.  If the the map name begins with the sequence
X``{\tt hesiod.}''\ then the {\em Hesiod} name server will be used.
XOtherwise the map name is referenced as a file,
Xthen as an ndbm database by that name and then as a YP map.
XAs soon as a valid reference is found the map type is noted
Xfor future use but any resources held are released, for example
Xany open file descriptors are closed.
XThe available map types are a configurable component of \amd\ and
Xcan be displayed by running the command {\tt amd~-v}.
X
XBy default, \amd\ does not cache any data retrieved from a mount map.
XThis is a policy decision based on the observation that most workstations
Xhave more available CPU time than spare memory.
XHowever, on a multi-user service or larger workstation the faster
Xresponse provided by a cache can be preferable.  The \opt{cache}
Xoption can be specified on automount points to alter the
Xcaching behaviour (\see \Ref{auto-fs}).
X
X\Subsection{File maps}
XWhen \amd\ searches a file for a map entry it does some simple parsing of the file
Xand supports both comments and continuation lines.
X
XContinuation lines are indicated by a backslash character (``{\verb+\+}'') as
Xthe last character of a line in the file.  The backslash, newline character
X{\em and any leading white space on the following line} are discarded.  A maximum
Xline length of 2047 characters is enforced.  Each line must be terminated by
Xa newline character; that is newlines are terminators, not separators.
X
XAfter a complete line has been read from the file, including continuations,
X\amd\ determines whether there is a comment on the line.
XA comment begins with a hash (``{\tt \#}'') character and continues to the
Xend of the line.
XThere is no way to escape or change the comment lead-in hash character.
X
XFile maps have a default cache mode of {\tt all} (\see \Ref{afs:cache}).
X
X\Subsection{ndbm maps}\label{ndbm-maps}
XAn ndbm map may be used as a fast access form of a file map.
XA program, {\tt mk-amd-map}, converts a normal map file into
Xan ndbm database.  Note that ndbm format files {\em may not} be
Xsharable across machine architectures.
XThe notion of speed generally only applies to large maps;
Xa small map, less than a single disk block, is almost certainly
Xbetter implemented as a file map.
X
Xndbm maps do not support cache mode {\tt all} and
Xhave a default cache mode of {\tt inc} (\see \Ref{afs:cache}).
X
X\Subsection{YP maps}
XWhen using YP, an \amd\ map is implemented directly by the
Xunderlying YP map.
XComments are {\em not} supported
Xin the automounter and must be stripped when constructing the YP server's database.
X
XYP maps do not support cache mode {\tt all} and
Xhave a default cache mode of {\tt inc} (\see \Ref{afs:cache}).
X
X\Subsection{Hesiod}
XWhen the map name begins with the string {\tt hesiod.}\ lookups
Xare made using the {\em Hesiod} name server.  The string following
Xthe dot is used as a name qualifier and is prepended with
Xthe key being resolved.  For example, if the map name is {\tt hesiod.homes}
Xand the key is {\tt jsp} then {\em Hesiod} is asked to resolve
X{\tt jsp.homes.automount}.
X
X%\Subsection{Gdbm}
X
X\Section{Map Lookup}
X
XThe key is located in the map whose type was determined when the
Xautomount point was first created.
XIn general the key is a pathname component.
XIn some circumstances this may be modified by variable expansion
X(\see \Ref{var-expansion})
Xand prefixing.
XIf the automount point has a prefix, specified by the \opt{pref} option, then
Xthat is prepended to the search key before the map is searched.
X
XIf the key cannot be found then a {\em wildcard} match is attempted.
XCurrently this simply attempts to locate a special key ``{\tt *}''.
XIf the wildcard is not found then an error code is propagated back to the
Xkernel, otherwise \amd\ proceeds as if an exact match had been found.
XThe value field is then used to resolve the mount request (\see \Ref{filesystems}).
X
X
X\Section{Location Format}\label{opts:values}
X
XThe value field from the lookup provides the information required to mount a filesystem.
XThe information is parsed according to the syntax shown in figure \ref{figure:so-grammar}.
X\begin{figure}[htb]
X\begin{tabbing}
XIndent \= Long Gram Rule \= \kill
X       \> {\em location-list}:\\
X       \>              \> {\em location}\\
X       \>              \> {\em location-selection}\ {\tt ||}\ {\em location}\\
X       \> {\em location-selection}:\\
X       \>              \> {\em location}\\
X       \>              \> {\em location-selection}\ \ {\em location}\\
X       \> {\em location}:\\
X       \>              \> {\em location-info}\\
X       \>              \> {\tt -}{\em location-info}\\
X       \> {\em location-info}:\\
X       \>              \> {\em sel-or-opt}\\
X       \>              \> {\em location-info}{\tt ;}{\em sel-or-opt}\\
X       \> {\em sel-or-opt}:\\
X       \>              \> {\em selection}\\
X       \>              \> {\em opt-ass}\\
X       \> {\em selection}:\\
X       \>              \> {\rm selector}{\tt ==}{\em value}\\
X       \>              \> {\rm selector}{\tt !=}{\em value}\\
X       \> {\em opt-ass}:\\
X       \>              \> {\rm option}{\tt :=}{\em value}\\
X\end{tabbing}
X\caption{\label{figure:so-grammar}Location syntax}
X\end{figure}
XNote that unquoted whitespace is not allowed in a location description.
X
XA {\em location-selection} is a list of possible filesystems with which to
Xsatisfy the request.  location-selections are separated by the {\tt ||}
Xoperator.  The effect of this operator is to prevent use of location-selections
Xon its right if any of the location-selections on its left were selected
X(see \Ref{selectors}).
X
XThe location-selection, and singleton{\em  location-list},
X{\tt type:=ufs;dev:=/dev/xd1g} would inform \amd\ to mount a
X\UFS\ filesystem from the block special device {\tt /dev/xd1g}.
X
XThe {\em sel-or-opt} component is either the name of an option required by a
Xspecific filesystem, or it is the name of a built-in, predefined selector such
Xas the architecture type.
XThe value may be quoted with double quotes ``{\tt "}'',
Xfor example {\tt type:="ufs";dev:="/dev/xd1g"}.  These quotes are
Xstripped when the value is parsed and there is no way to get a double quote
Xinto a value field.  Double quotes are used to get white space into a value field
Xwhich is needed for the program filesystem (\see \Ref{pfs}).
X
X\label{defaults}A location beginning with a dash ``{\tt -}'' is used
Xto specify default values for subsequent locations.
XAny previously specified defaults are discarded.  The
Xdefault string can be empty in which case no defaults apply.
XThe location {\tt -fs:=/mnt;opts:=ro} would set the local mount point
Xto {\tt /mnt} and cause mounts to be read-only by default.
XDefaults specified this way are appended to, and
Xoverride, any global map defaults given
Xwith {\tt /defaults}\label{/defaults}).
XA {\tt /defaults} value {\em gdef} and a location list
X\begin{quote}
X${\tt -}{\em def}_a\ {\em loc}_{a_1}\ {\em loc}_{a_2}\ \ {\tt -}{\em def}_b\ {\em loc}_{b_1}\ \ldots$
X\end{quote}
Xis equivalent to
X\begin{quote}
X${\tt -}{\em gdef}{\tt ;}{\em def}_a\ {\em loc}_{a_1}\ {\em loc}_{a_2}\ \ {\tt -}{\em gdef}{\tt ;}{\em def}_b\ {\em loc}_{b_1}\ \ldots$
X\end{quote}
X
X\Subsection{Variable expansion}\label{var-expansion}
X
XTo allow generic location specifications \amd\ does variable expansion
Xon each location and also on some of the option strings.
XAny option or selector appearing in the form \Var{{\em var}}
Xis replaced by the current value of that option or selector.
XFor example, if the value of \Var{key} was {\tt bin}, \Var{autodir} was {\tt /a}
Xand \Var{fs} was \Var{autodir}{\tt /local/}\Var{key} then after
Xexpansion \Var{fs} would have the value {\tt /a/local/bin}.
XAny environment variable can be accessed in a similar way.
X
XTwo pathname operators are available when expanding a variable.
XIf the variable name begins with ``{\tt /}'' then only the
Xlast component of then pathname is substituted.  For example,
Xif \Var{path} was {\tt /foo/bar} then \Var{/path} would be
Xexpanded to {\tt bar}.
XSimilarly, if the variable name ends with ``{\tt /}'' then all but
Xthe last component of the pathname is substituted.
XIn the previous example, \Var{path/} would be expanded to {\tt /foo}.
X
XTwo types of expansion are used: the options are expanded and
Xthe selectors are left unexpanded, or {\em vice versa}.
XBefore a map is consulted, any selectors in the name received from the kernel are expanded.
XFor example, if the name is \Var{arch}{\tt .bin} and the
Xmachine architecture is {\tt vax}, the value given to \Var{key}
Xwill be {\tt vax.bin}.
XNext, each location has any selectors expanded.
XFinally, before they are used, the following options have any options expanded:
X\opt{rhost}, \opt{mount}, \opt{unmount}, \opt{sublink}, \opt{rfs} and \opt{fs}.
XIn general this sequence does ``the right thing'' except when one of
Xthe options references one of the other options in which case the
Xordering of expansions becomes significant.
X
X\Subsection{Selectors}\label{selectors}
X
XSelectors are used to control the use of a location.
XIt is possible to share a mount map between many machines in
Xsuch a way that filesystem location, architecture and operating
Xsystem differences are hidden from the users.
XA selector of the form {\tt arch==sun3;os==sos4} would only apply
Xon Sun-3's running SunOS 4.$x$.
X
XSelectors are evaluated left to right.  If a selector fails then that
Xlocation is ignored.  Thus the selectors form a conjunction and the
Xlocations form a disjunction.
XIf all the locations are ignored or otherwise fail then \amd\ uses
Xthe {\em error} filesystem (\see \Ref{error-fs}).  This is equivalent
Xto having a location {\tt type:=error} at the end of each mount-map
Xentry.
X
XThe selectors currently implemented are:
X
X\begin{list}{}%
X{\settowidth{\labelwidth}{{\tt autodir}}\setlength{\leftmargin}{1.2\labelwidth}}
X\item[\tt arch\hfill]
Xthe machine architecture which was automatically determined at compile time.
XThe architecture type can be displayed by running the command {\tt amd~-v}.
XThe currently supported architectures are listed in table \ref{table:arch}.
X\begin{table}[htb]
X\centering
X\begin{tabular}{ll}
XName        & Architecture \\ \hline
X\tt alliant    & Alliant FX/4 \\
X\tt arm        & Acorn ARM \\
X\tt encore      & Encore (reserved) \\
X\tt hp9000    & HP 9000/300 family \\
X\tt hp9k8       & HP 9000/800 family (reserved) \\
X\tt ibm032    & IBM RT PC \\
X\tt macII    & Apple Mac II \\
X\tt mips    & MIPS R2000 \\
X\tt multimax    & Encore Multimax \\
X\tt orion105    & HLH Orion 1/05 \\
X\tt powernode    & Gould Powernode family \\
X\tt sun3    & Sun-3 family \\
X\tt sun4    & Sun-4 family \\
X\tt vax        & DEC \sc Vax \\
X\end{tabular}
X\caption{\label{table:arch}Architectures supported by \amd}
X\end{table}
X
X\item[\tt autodir\hfill]
Xthe default directory under which to mount filesystems.
XThis may be changed by the ``-a'' command line option.
XSee the \opt{fs} option.
X
X\item[\tt byte\hfill]\label{byte-selector}
Xthe machine's byte ordering.  This is either {\tt little}, indicating
Xlittle-endian, or {\tt big}, indicating big-endian.
XOne possible use is to share {\tt rwhod} databases.
XAnother is to share ndbm databases,
Xhowever this use can be considered a courageous juggling act.
X
X\item[\tt cluster\hfill]
Xis provided as a hook for the name of the local cluster.  This can
Xbe used to decide which servers to use for copies of replicated filesystems.
X\Var{cluster} defaults to the value of \Var{domain} unless a different
Xvalue is set with the ``-C'' command line option.
X
X\item[\tt domain\hfill]
Xthe local domain name as specified by the ``-d'' command line option.
XSee {\tt host}.
X
X\item[\tt host\hfill]
Xthe local hostname as determined by {\bf gethostname}(2).
XIf no domain name was specified on the command line
Xand the hostname contains a period ``{\tt .}'' then the string
Xbefore the period is used as the host name, and the string
Xafter the period is assigned to \Var{domain}.
XFor example, if the hostname is {\tt styx.doc.ic.ac.uk} the {\tt host}
Xwould be {\tt styx} and {\tt domain} would be {\tt doc.ic.ac.uk}.
X{\tt hostd} would be {\tt styx.doc.ic.ac.uk}.
X
X\item[\tt hostd\hfill]
Xis \Var{host} and \Var{domain} concatenated with a ``{\tt .}'' inserted between them
Xif required.
XIf \Var{domain} is an empty string then \Var{host} and \Var{hostd} will
Xbe identical.
X
X\item[\tt karch\hfill]
Xis provided as a hook for the kernel architecture.  This is used
Xby SunOS 4, for example to distinguish between different {\tt /usr/kvm} volumes.
X\Var{karch} defaults to the value of \Var{arch} unless a different
Xvalue is set with the ``-k'' command line option.
X
X\item[\tt os\hfill]
Xthe operating system.
XLike the machine architecture, this is automatically determined at compile time.
XThe operating system name can be displayed by running the command {\tt amd~-v}.
XThe currently supported operating systems are listed in table \ref{table:os}.
X\begin{table}[htb]
X\centering
X\begin{tabular}{ll}
XName        & System \\ \hline
X\tt acis43    & 4.3 BSD for IBM RT PC \\
X\tt aux        & System V for Mac-II \\
X\tt bsd44    & 4.4 BSD \\
X\tt concentrix    & Concentrix 5.0 \\
X\tt hlh42    & HLH OTS 1.$x$ (4.2 BSD) \\
X\tt hpux    & HP-UX 6.$x$ \\
X\tt riscix    & Acorn RISC iX \\
X\tt sos3    & SunOS 3.4 \& 3.5 \\
X\tt sos4    & SunOS 4.$x$ \\
X\tt umax43    & Umax 4.3 BSD \\
X\tt u2\_2    & Ultrix 2.2 \\
X\tt u3\_0    & Ultrix 3.0 \\
X\tt utx32    & Gould UTX/32 Rel 2.$x$ \\
X\tt xinu43    & mt Xinu MORE/bsd \\
X\end{tabular}
X\caption{\label{table:os}Operating systems supported by \amd}
X\end{table}
X\end{list}
X
XThe following selectors are also provided.  Unlike the other selectors,
Xthey vary for each lookup.
XNote that when the name from the kernel is expanded prior to a map
Xlookup, these selectors are all defined as empty strings.
X\begin{list}{}%
X{\settowidth{\labelwidth}{{\tt autodir}}\setlength{\leftmargin}{1.2\labelwidth}}
X\item[\tt key\hfill]
Xthe name being resolved.
XFor example, if {\tt /home} is an automount point, then accessing
X{\tt /home/foo}\label{foo-path} would set \Var{key} to the string {\tt foo}.
XThe key is prefixed by the \opt{pref} option set in the parent mount point.
XThe default prefix is an empty string.  If the prefix was {\tt blah/} then
X\Var{key} would be set to {\tt blah/foo}.
X
X\item[\tt map\hfill]
Xthe name of the mount map being used.
X
X\item[\tt path\hfill]
Xthe full pathname of the name being resolved.  For example {\tt /home/foo}
Xin the example above.
X
X\end{list}
X
XSelectors can be negated by using {\tt !=} instead of {\tt ==}.
XFor example to select a location
Xon all non-{\sc Vax} machines the selector {\tt arch!=vax} would be used.
X
X\Subsection{Options}\label{options}
X
XOptions are parsed concurrently with selectors.  The difference is that
Xwhen an option is seen the string following the ``{\tt :=}'' is recorded for
Xlater use.  As a minimum the \opt{type} option must be specified.
XEach filesystem type has other options which must also be specified.
XThe filesystem specific options are detailed in \Ref{filesystems}.
X
XThe following options apply to more than one filesystem type:
X\begin{list}{}
X{\settowidth{\labelwidth}{{\tt sublink}}\setlength{\leftmargin}{1.2\labelwidth}}
X\item[\tt delay\hfill]
Xthe delay, in seconds, before an attempt will be made to mount from the current location.
XAuxilliary data, such as network address, file handles and so on are computed
Xregardless of this value.
XA delay can be used to implement the notion of primary and secondary file servers.
XThe secondary servers would have a delay of a few seconds,
Xthus giving the primary servers a chance to respond first.
X
X\item[\tt fs\hfill]\label{mount location}
Xthe local mount point.
XThe semantics of this option vary between filesystems.
X
XFor \NFS\ and \UFS\ filesystems the value of \Var{fs} is used as the local
Xmount point.  It is important that this string uniquely identifies the
Xfilesystem being mounted.  To satisfy this requirement, it should contain the
Xname of the host on which the filesystem is resident and the pathname
Xof the filesystem on the local or remote host.
X
XThe reason for
Xrequiring the hostname is clear if replicated filesystems are considered.
XIf a fileserver goes down and a replacement filesystem is mounted then the {\em local}
Xmount point {\em must} be different from that of the filesystem which
Xis hung.
XSome encoding of the filesystem name is required if more than one filesystem
Xis to be mounted from any given host.
X
XIf the hostname is first in the path then all mounts from a particular
Xhost will be gathered below a single directory.  If that server goes
Xdown then the hung mount points are less likely to be accidentally referenced,
Xfor example when {\bf getwd}(3) traverses the namespace to find the pathname
Xof the current directory.
X
XThe {\tt fs} defaults to \Var{autodir}/\Var{rhost}\Var{rfs}.
XIn addition, {\tt rhost} defaults to the local host name (\Var{host}) and
X{\tt rfs} defaults to the value of \Var{path}, which
Xis the full path of the requested file; {\tt /home/foo}
Xin the example above (\see \Ref{foo-path}).
X\Var{autodir} defaults to {\tt /a} but may be changed with the ``-a''
Xcommand line option\footnote{Sun's automounter defaults to {\tt /tmp\_mnt}}.
XNote that there is no ``{\tt /}'' between the \Var{rhost} and \Var{rfs} since
X\Var{rfs} begins with a ``{\tt /}''.
X
X\item[\tt opts\hfill]
Xthe options to pass to the mount system call.
XA leading ``{\tt -}'' is silently ignored.
XThe mount options supported generally correspond to
Xthose used by {\bf mount}(8) and are listed in table \ref{table:mount opts}.
XSome additional pseudo-options are interpreted by \amd\ and
Xare listed in table \ref{table:pseudo-mount opts}.
XUnless specifically overridden, each of the system default mount
Xoptions applies.
XAny options not recognised are ignored.
XIf no options list is supplied the string {\tt rw,defaults} is used
Xand all the system default mount options apply.
X\begin{table}[htb]
X\centering
X\begin{tabular}{lp{4in}}
XOption        & Semantics \\\hline
X\tt grpid    & Use BSD directory group-id semantics. \\
X\tt intr    & Allow keyboard interrupts on hard mounts. \\
X\tt nodevs    & Don't allow local special devices on this filesystem. \\
X\tt nosuid    & Don't allow set-uid or set-gid executables on this filesystem. \\
X\tt quota    & Enable quota checking on this mount. \\
X\tt retrans=$n$    & The number of \NFS\ retransmits made before a user error is generated
X          by a {\tt soft} mounted filesystem, and before a
X          {\tt hard} mounted filesystem reports {\tt NFS server {\em yoyo}
X          not responding still trying}. \\
X\tt ro        & Mount this filesystem readonly. \\
X\tt soft    & Give up after {\em retrans} retransmissions. \\
X\tt timeo=$n$    & The \NFS\ timeout, in tenth-seconds, before a request is retransmitted. \\
X\end{tabular}
X\caption{Mount options passed to the mount system call\label{table:mount opts}}
X\end{table}
X
X\begin{table}[htb]
X\centering
X\begin{tabular}{lp{4in}}
XOption        & Semantics \\\hline
X\tt notimeout    & Configures the mount so that its time-to-live will
X          never expire.  This is also the default for some
X          filesystem types. \\
X%
X% Implementation broken:
X%\tt ping=$n$    & The interval, in seconds, between keep-alive pings.  When four
X%          consecutive pings have failed the mount point is
X%          marked as hung.  This interval defaults to 3 seconds.  \\
X%
X\tt retry=$n$    & The number of times to retry the mount system call. \\
X\tt utimeout=$n$& The interval, in seconds, by which the mount's
X          time-to-live\label{opt:utimeout}
X          is extended after an unmount attempt has failed.
X          In fact the interval is extended before the unmount
X          is attempted to avoid thrashing. \\
X\end{tabular}
X\caption{Mount options interpreted by \amd\label{table:pseudo-mount opts}}
X\end{table}
X
X\item[\tt sublink\hfill]
Xthe subdirectory within the mounted filesystem to which the reference
Xshould point.
XThis can be used to prevent duplicate mounts in cases where multiple
Xdirectories in the same mounted filesystem are used.
X
X\item[\tt type\hfill]
Xthe filesystem type to be used.  A full description of each
Xtype is given in \Ref{filesystems}.
X
X\end{list}
X
XSuperfluous option specifications are ignored and are not reported
Xas errors.
X
X\Chapter{Command Line Options}
XMany of \amd's parameters can be set from the command line.
XThe command line is also used to specify automount points
Xand maps.
X
XThe general format of a command line is
X\begin{quote}
X{\tt amd} {\em options} directory map-name [{\tt -}{\em map-options}] \ldots
X\end{quote}
XFor each directory and map-name given, \amd\ establishes an automount point.
X%In addition, unless the ``-m'' option is given (see below), \amd\ enumerates
X%the YP maps {\tt am.master} and {\tt auto.master} to obtain a further list of
X%automount points to create.
XThe {\em map-options} may be any sequence of options or selectors as described
Xin \Ref{opts:values}.
XThe {\em map-options} apply only to \amd's mount point.  Default options for
Xa map are read from a special entry in the map whose key is the string
X{\tt /defaults}.
XWhen default options are given they are prepended to any
Xoptions specified in the mount-map locations as explained in \Ref{/defaults}.
X
XThe {\em options} are any combination of the following:
X
X\begin{description}
X\item[\tt -a \em directory]\mbox{}\\
Xspecifies the default mount directory.
XThis option changes the variable \Var{autodir} which
Xotherwise defaults to {\tt /a}.
XFor example, some sites prefer {\tt /am}.
X\begin{quote}
X\tt
Xamd -a /am ...
X\end{quote}
X
X\item[\tt -c \em cache-interval]\mbox{}\\
Xselects the period for which a name is cached by \amd.  If no
Xreference is made to the filesystem in this period,
X\amd\ attempts to unmount the filesystem.
XIf the unmount fails the interval is extended by a further period
Xas specified by the {\tt -w} command line option or by the {\tt utimeout} mount option.
XThe default {\em cache-interval} is five minutes.
X
X\item[\tt -d \em domain]\mbox{}\\
Xspecifies the host's domain.  This sets the internal variable \Var{domain}
Xand affects the \Var{hostd} variable.
XIf this option is not specified and
Xthe hostname already contains the local domain then that is
Xused, otherwise the default value of \Var{domain} is {\tt unknown.domain}.
XFor example, if the local domain was {\tt doc.ic.ac.uk}, \amd\ could be
Xstarted as follows:
X\begin{quote}
X\tt
Xamd -d doc.ic.ac.uk ...
X\end{quote}
X
X\item[\tt -k \em kernel-architecture]\mbox{}\\
Xspecifies the kernel architecture of the system.  This is usually
Xthe output of {\tt arch -k} and its only effect is to set the
Xvariable \Var{karch}.  If this option is not given, \Var{karch}
Xhas the same value as \Var{arch}.
XThis would be used as follows:
X\begin{quote}
X\tt
Xamd -k `arch -k` ...
X\end{quote}
X
X\item[\tt -l \em log-option]\mbox{}\\
Xselects the form of logging to be made.
XTwo special {\em log-option}s are recognised.
XIf {\em log-option} is the string {\tt syslog}, \amd\ will use
Xthe {\bf syslog}(3) mechanism.
XIf {\em log-option} is the string {\tt /dev/stderr}\footnote{
XThis pathname is interpreted internally by \amd; a {\tt /dev/fd}
Xdriver is not required.
X}, \amd\ will use
Xstandard error which is also the default value.
XAny other string is taken as a filename to
Xuse for logging.  Log messages are appended to the file if it already
Xexists, otherwise a new file is created.
XIf the syslog option is specified but the system does not support syslog or
Xif the named file cannot be opened or created, \amd\ will use standard error.
XError messages generated before \amd\ has finished parsing the command line
Xare printed on standard error.
XUsing {\tt syslog} is usually best, in which case \amd\ would be
Xstarted as follows:
X\begin{quote}
X\tt
Xamd -l syslog ...
X\end{quote}
X
X%\item[\tt -m]\mbox{}\\
X%is an obsolete option that was the equivalent of appending
X%{\tt `ypcat -k am.master`} to the command line.
X%tells \amd\ {\em not} to obtain a list of automount points from Yellow Pages.
X%By default, \amd\ attempts to enumerate the YP maps {\tt am.master} and {\tt auto.master}.
X%The default YP domain is used unless the ``-y'' option is given.
X%{\em This option will be removed in the next release.}
X
X\item[\tt -n]\mbox{}\\
Xnormalises the remote hostname before using it.
XNormalisation is done by replacing the value of \Var{rhost} with the primary name returned by
Xa hostname lookup.
XThis option should be used if several names are used to refer to a single host in a
Xmount map.
X
X\item[\tt -p]\mbox{}\\
Xcauses \amd's process id to be printed on standard output.
XThis can be redirected to a suitable file for use with kill:
X\begin{quote}
X\tt
Xamd -p > /etc/amd.pid ...
X\end{quote}
X
X\item[\tt -r]\mbox{}\\
Xtells \amd\ to restart existing mounts (see the Inheritance File System \Ref{ifs}).
X%{\em This option will be made the default in the next release.}
X
X\item[\tt -t \em afs-timeout.afs-retransmit]\mbox{}\\
Xspecifies the RPC timeout and retransmit intervals used by the kernel to communicate
Xto \amd.  These are used to set the {\tt timeo} and {\tt retrans} mount options.
X\Amd\ relies on the kernel RPC retry mechanism to trigger mount retries.  The
Xvalue of this parameter changes the retry interval.  Too long an interval
Xgives poor interactive response, too short an interval causes excessive
Xretries.
X
X\item[\tt -v]\mbox{}\\
Xprint version information on standard error and then exit.
XThe output is of the form:
X\begin{verbatim}
XAmd 5.0.1.8 of 89/10/23 12:22:00 beta20 #37: Wed Nov  1 11:03:09 GMT 1989
XBuilt by [e-mail] for a sun4 running sos4 (big-endian)
XMap support for: root, hesiod, yp, ndbm, file, error.
X\end{verbatim}
XThe information includes the version number, release date and name
Xof the release.
XThe architecture (\see \Ref{table:arch}), operating system (\see \Ref{table:os})
Xand byte ordering are also printed as they appear in the \Var{os},
X\Var{arch} and \Var{byte} variables.
X
X\item[\tt -w \em wait-timeout]\label{opt:wait}\mbox{}\\
Xselects the interval between unmount attempts after
Xthe initial time-to-live has expired.
XThis defaults to 120 seconds.
X
X\item[\tt -x \em opts]\mbox{}\\
Xspecifies the type and verbosity of log messages.  {\em opts} is
Xa comma separated list selected from the options in table \ref{table:x opts}.
X\begin{table}[htb]
X\centering
X\begin{tabular}{ll}
XLog option  & Messages logged \\\hline
X\tt fatal   & Fatal errors \\
X\tt error   & Non-fatal errors \\
X\tt user    & Non-fatal user errors \\
X\tt warn    & Recoverable errors \\
X\tt warning & Alias for \tt warn \\
X\tt info    & Information messages \\
X\tt map     & Mount map usage \\
X\tt all     & All of the above \\
X\end{tabular}
X\caption{Logging options\label{table:x opts}}
X\end{table}
XThe default logging option is {\tt -x~all,nomap}.
XIn general production use, the
Xoption {\tt -x~fatal,error} is most useful.  The {\tt info} messages
Xinclude details of what is mounted and unmounted and when filesystems
Xhave timed out.  The messages given by {\tt user} relate to errors
Xin the mount maps, so these are useful when new maps are installed.
X
XThe options can be prefixed by the string {\tt no} to indicate
Xthat this option should be turned off.  For example, to obtain all
Xbut {\tt info} messages the option {\tt -x~all,noinfo} would be used
Xor, since {\tt -x~all} is the default, simply {\tt -x~noinfo}.
X
X\item[\tt -y \em yp-domain]\mbox{}\\
Xselects an alternate YP domain.  This is useful for debugging and
Xcross-domain shared mounting.
XIf this flag is specified, \amd\ immediately attempts to
Xbind to a server for this domain.
X%\Amd\ refers to YP maps when it starts, unless the ``-m'' option
X%is specified, and whenever required in a mount map.
X
X\item[\tt -C \em cluster-name]\mbox{}\\
Xspecifies the name of the cluster of which the local machine is a member.
XThe only effect is to set the variable \Var{cluster}.
XThe {\em cluster-name} is will usually obtained by running another command which uses
Xa database to map the local hostname into a cluster name.
X\Var{cluster} can then be used as a selector to restrict mounting of
Xreplicated data.
XIf this option is not given, \Var{cluster} has the same value as \Var{domain}.
XThis would be used as follows:
X\begin{quote}
X\tt
Xamd -C `clustername` ...
X\end{quote}
X
X\item[\tt -D {\em opts}]\mbox{}\\
Xcontrols the verbosity and coverage of the debugging trace;
X{\em opts} is a comma separated list of debugging options.
XThe ``-D'' option is only available if \amd\ was compiled with {\tt -DDEBUG}.
XThe memory debugging facilities are
Xonly available if \amd\ was compiled with {\tt -DDEBUG\_MEM}
X(in addition to {\tt -DDEBUG}).
XThe most common options to use are {\tt -D~trace} and {\tt -D~test}
X(which turns on all the useful debug options).
XSee the program source for a more detailed explanation of the available options.
X
X\end{description}
X
XWhen the command line has been parsed, the automount points are mounted.
XThe mount points are created if they do not already exist, in which case they
Xwill be removed when \amd\ exits.
XFinally, \amd\ disassociates itself from its controlling terminal and
Xforks into the background.
X
X{\em Note\/}: Even if \amd\ has been built with {\tt -DDEBUG} it
Xwill still background itself and disassociate itself from the controlling terminal.
XTo use a debugger it is necessary to
Xspecify {\tt -D~nodaemon} on the command line.
X
X\Chapter{Filesystems}\label{filesystems}
X
XFrom the point of view of \amd, a {\em filesystem} is anything
Xthat can resolve an incoming name lookup.
XAn important feature is support for multiple filesystem types.
XSome of these filesystems are implemented in
Xthe local kernel and some on remote fileservers, whilst the others are implemented
Xinternally by \amd.
X
XThe two common filesystem types are \UFS\ and \NFS.
XFour other user accessible filesystems ({\tt link}, {\tt program}, {\tt auto}
Xand {\tt direct}) are also implemented
Xinternally by \amd\ and these are described below.
XThere are two additional filesystem
Xtypes internal to \amd\ which are not directly accessible
Xto the user ({\tt inherit} and {\tt error}).  Their use is described since they may
Xstill have an effect visible to the user.
X
X\Section[Network Filesystem]{Network Filesystem ({\tt type:=nfs})}
X
XThe {\em nfs} filesystem type provides access to Sun's \NFS.
XThe following options may be specified:
X\begin{description}
X\item[\tt rhost]
Xthe remote fileserver.  This must be an entry in the hosts database.
XIP addresses \cite{rfc:ip} are not accepted.
XThe default value is taken from the local host name (\Var{host})
Xif no other value is specified.
X
X\item[\tt rfs]
Xthe remote filesystem.
XIf no value is specified for this option, an internal default of
X\Var{path} is used.
X
X\end{description}
X
X\NFS\ mounts require a two stage process.  First, the {\em file handle} of
Xthe remote file system must be obtained from the server.  Then a mount
Xsystem call must be done on the local system.
X\Amd\ keeps a cache of file handles for remote file systems.  The cache
Xentries have a lifetime of a few minutes.
X
XIf a required file handle is not in the cache, \amd\ sends a request
Xto the remote server to obtain it.  \Amd\ {\em does not} wait for
Xa response; it notes that one of the locations needs retrying, but
Xcontinues with any remaining locations.  When the file handle becomes
Xavailable, and assuming none of the other locations was successfully
Xmounted, \amd\ will retry the mount.  This mechanism allows several
X\NFS\ filesystems to be mounted in parallel\footnote{The mechanism
Xis general, however \NFS\ is the only filesystem
Xfor which the required hooks have been written.}.
XThe first one which
Xresponds with a valid file handle will be used.
X
XAn \NFS\ entry might be:
X\begin{quote}
X\tt
Xjsp\ \ host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp
X\end{quote}
X
XThe mount system call and any unmount attempts are always done
Xin a new task to avoid the possibilty of blocking \amd.
X
X\Section[\Unix\ Filesystem]{\Unix\ Filesystem ({\tt type:=ufs})}
X
XThe {\em ufs} filesystem type provides access to the system's
Xstandard disk filesystem---usually the Berkeley Fast Filesystem \cite{bsd:ufs}.
XThe following option must be specified:
X\begin{description}
X\item[\tt dev]
Xthe block special device to be mounted.
X\end{description}
X
XA \UFS\ entry might be:
X\begin{quote}
X\tt
Xjsp\ \ \ host==charm;type:=ufs;dev:=/dev/xd0g;sublink:=jsp
X\end{quote}
X
X\Section[Program Filesystem]{Program Filesystem ({\tt type:=program})}\label{pfs}
X
XThe {\em program} filesystem type allows a program to be run
Xwhenever a mount or unmount is required.  This allows easy
Xaddition of support for other filesystem types, such as MIT's
XRemote Virtual Disk (RVD) \cite{mit:rvd} which has a programmatic interface via
Xthe commands {\tt rvdmount} and {\tt rvdunmount}.
X
XThe following options must be specified:
X\begin{description}
X\item[mount]
Xthe program which will perform the mount.
X
X\item[unmount]
Xthe program which will perform the unmount.
X\end{description}
X
XThe exit code from these two programs is interpreted as a \Unix\ error
Xcode.  As usual, exit code zero indicates success.
XTo execute the program \amd\ splits the string on whitespace to
Xcreate an array of substrings.
XSingle quotes ``{\tt '}'' can be used to quote whitespace if that is
Xrequired in an argument.  There is no way to escape or change the quote character.
XTo run the program {\tt rvdmount} with a host name and filesystem as
Xarguments would be specified by {\tt mount:="/etc/rvdmount rvdmount fserver \$\{path\}"}.
X
XThe first element in the array is taken as the pathname of the program
Xto execute.  The other members of the array form the argument vector
Xto be passed to the program, {\em including argument zero}.  This means
Xthat the split string must have at least two elements.
XThe program is directly executed by \amd, not via a shell.
X
END_OF_FILE
if test 49780 -ne `wc -c <'doc/amd.tex.1'`; then
    echo shar: \"'doc/amd.tex.1'\" unpacked with wrong size!
fi
# end of 'doc/amd.tex.1'
fi
echo shar: End of archive 13 \(of 13\).
cp /dev/null ark13isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 13 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
exit 0 # Just in case...