% $Id: examples.tex,v 1.1.1.1 2018/04/24 16:12:57 root Exp $
%
% 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.
%
%	@(#)examples.tex	5.1 (Berkeley) 7/19/90


\Chapter{Examples}

\Section{Starting \Amd}
\Amd\ is best started from {\tt /etc/rc.local}:
\begin{verbatim}
if [ -f /usr/local/etc/amd.start ]; then
        sh /usr/local/etc/amd.start; (echo -n ' amd')      >/dev/console
fi
\end{verbatim}
The shell script, {\tt amd.start}, contains:
\begin{verbatim}
PATH=/usr/local/etc:/bin:/usr/bin:/usr/ucb:$PATH export PATH

#
# Either name of logfile or "syslog"
#
LOGFILE=syslog
#LOGFILE=/var/adm/am.log

#
# Figure out whether domain name is in host name
# If the hostname is just the machine name then
# pass in the name of the local domain so that the
# hostnames in the map are domain stripped correctly.
#
case `hostname` in
*.*) dmn= ;;
*) dmn='-d doc.ic.ac.uk'
esac

#
# Zap earlier log file
#
case "$LOGFILE" in
*/*)
        mv "$LOGFILE" "$LOGFILE"-
        > "$LOGFILE"
        ;;
syslog)
        : nothing
        ;;
esac

cd /usr/local/etc
#
# -r            restart
# -d dmn        local domain
# -w wait       wait between unmount attempts
# -l log        logfile or "syslog"
#
eval ./amd -r $dmn -w 240 -l "$LOGFILE" \
        /homes amd.homes -cache:=inc \
        /home amd.home -cache:=inc \
        /vol amd.vol -cache:=inc \
        /n amd.net -cache:=inc
\end{verbatim}

If the list of automount points and maps is contained in a file or YP map
it is easily incorporated onto the command line:
\begin{verbatim}
...
eval ./amd -r $dmn -w 240 -l "$LOGFILE" `ypcat -k auto.master`
\end{verbatim}

\Section{User Filesystems}
With more than one fileserver, the directories most frequently
cross-mounted are those containing user home directories.
A common convention used at Imperial College is to mount
the user disks under {\tt /home/}{\em machine}.
Typically, the {\tt /etc/fstab} file\footnote{{\tt /etc/checklist}
on System V} contained a long list of entries
such as:
\begin{quote}
{\em machine}{\tt :/home/}{\em machine}\ \ \tt /home/{\em machine}\ nfs \ldots
\end{quote}
for each fileserver on the network.

There are numerous problems with this system.
The mount list can become quite large and some of the machines
may be down when a system is booted.
When a new fileserver is installed, {\tt /etc/fstab} must be
updated on every machine, the mount directory created and
the filesystem mounted.
In research environments most
people use the same few workstations, but it is convenient to go
to a colleague's machine and access your own files.
When a server goes down, it can cause a process on a client machine to
hang.  By minimising the mounted filesystems to only include those
actively being used, there is less chance that a filesystem will be mounted
when a server goes down.

The following is a short extract from a map taken from a research fileserver
at Imperial College.
Note the entry for {\tt localhost} which is used for users such as
the operator ({\tt opr}) who have a home directory on most machine as
{\tt /home/localhost/opr}.
\begin{verbatim}
/defaults       opts:=rw,intr,grpid,nosuid
charm           host!=${key};type:=nfs;rhost:=${key};rfs:=/home/${key} \
                host==${key};type:=ufs;dev:=/dev/xd0g
#
...

#
localhost       type:=link;fs:=${host}
...
#
# dylan has two user disks so have a
# top directory in which to mount them.
#
dylan           type:=auto;fs:=${map};pref:=${key}/
#
dylan/dk2       host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/${key} \
                host==dylan;type:=ufs;dev:=/dev/dsk/2s0
#
dylan/dk5       host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/${key} \
                host==dylan;type:=ufs;dev:=/dev/dsk/5s0
...
#
toytown         host!=${key};type:=nfs;rhost:=${key};rfs:=/home/${key} \
                host==${key};type:=ufs;dev:=/dev/xy1g
...
#
zebedee         host!=${key};type:=nfs;rhost:=${key};rfs:=/home/${key} \
                host==${key};type:=ufs;dev:=/dev/dsk/1s0
#
# Just for access...
#
gould           type:=auto;fs:=${map};pref:=${key}/
gould/staff     host!=gould;type:=nfs;rhost:=gould;rfs:=/home/${key}
#
gummo           host!=${key};type:=nfs;rhost:=${key};rfs:=/home/${key}
...
\end{verbatim}

This map is shared by most of the machines listed so on those
systems any of the user disks is accessible via a consistent name.
\Amd\ is started with the following command
\begin{quote}
\tt amd /home amd.home
\end{quote}

Note that when mounting a remote filesystem, the {\em automounted}
mount point is referenced, so that the filesystem will be mounted if
it is not yet (at the time the remote mountd obtains the file handle).

\Section{Home Directories}
One convention for home directories is to locate them in {\tt /homes} so
user {\tt jsp}'s home directory is {\tt /homes/jsp}.
With more than a single fileserver it is convenient
to spread user files across several machines.
All that is required is a mount-map
which converts login names to an automounted directory.

Such a map might be started by the command:
\begin{quote}
\tt amd /homes amd.homes
\end{quote}
where the map {\tt amd.homes} contained the entries:
\begin{quote}\raggedright
\tt
/defaults\ \ \ type:=link\ \ \ \# All the entries are of type:=link \\
jsp\ \ \ \ \ \ \ \ \ fs:=/home/charm/jsp\\
njw\ \ \ \ \ \ \ \ \ fs:=/home/dylan/dk5/njw\\
...\\
phjk\ \ \ \ \ \ \ \ fs:=/home/toytown/ai/phjk\\
sjv\ \ \ \ \ \ \ \ \ fs:=/home/ganymede/sjv
\end{quote}
Whenever a login name is accessed in {\tt /homes} a symbolic link
appears pointing to the real location of that user's home directory.
In this example, {\tt /homes/jsp} would appear to be a symbolic link
pointing to {\tt /home/charm/jsp}.
Of course, {\tt /home} would also be an automount point.

This system causes an extra level of symbolic links to be used.
Although that turns out to be relatively inexpensive, an alternative is
to directly mount the required filesystems in the {\tt /homes}
map.  The required map is simple, but long, and its creation best automated.
The entry for {\tt jsp} could be:
{\tt\begin{tabbing}
jsp\ \ \ \ \ \ \= -sublink:=\$\{key\};rfs:=/home/charm {\verb+\+}\kill \\
jsp            \> -sublink:=\$\{key\};rfs:=/home/charm {\verb+\+}\\
               \> host==charm;type:=ufs;dev:=/dev/xd0g {\verb+\+}\\
               \> host!=charm;type:=nfs;rhost:=charm
\end{tabbing}}

This map can become quite big if it contains a large number of
entries.  By combining two other features of \amd\ it can be greatly
simplified.  First the \UFS\ partitions should be mounted under the
control of {\tt /etc/fstab}, taking care that they are mounted in the
same place that \amd\ would have automounted them, {\ie\ {\tt /a/{\em host}/home/{\em host}}}.
In this case {\tt /etc/fstab} on host {\tt charm} would have a line
\begin{verbatim}
/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5
\end{verbatim}
The map can then be changed to:
\begin{quote}\raggedright
\tt
/defaults\ \ \ \ type:=nfs;sublink:=\Var{key};opts:=rw,intr,nosuid,grpid\\
jsp\ \ \ \ \ \ \ \ \ \ rhost:=charm;rfs:=/home/charm\\
njw\ \ \ \ \ \ \ \ \ \ rhost:=dylan;rfs:=/home/dylan/dk5\\
...\\
phjk\ \ \ \ \ \ \ \ \ rhost:=toytown;rfs:=/home/toytown;sublink:=ai/\Var{key}\\
sjv\ \ \ \ \ \ \ \ \ \ rhost:=ganymede;rfs:=/home/ganymede
\end{quote}

This map operates as usual on a remote machine (ie \Var{host} $\not=$ \Var{rhost}).
On the machine where the filesystem is stored (ie \Var{host} $=$ \Var{rhost}),
\amd\ will construct a local filesystem mount point which corresponds to
the name of the locally mounted \UFS\ partition.  If \amd\ is started
with the ``-r'' option then instead of attempting an \NFS\ mount, \amd\ will
simply inherit the \UFS\ mount (\see \Ref{ifs}).

%\Section{System Filesystem}

\Section{Architecture Sharing}
%At the moment some of the research machines have sets of software
%mounted in {\tt /vol}.  This contains subdirectories for \TeX,
%system sources, local sources, prolog libraries and so on.
Often a filesystem will be shared by machines of different architectures.
Separate trees can be maintained for the executable images for each
architecture, but it may be more convenient to have a shared tree,
with distinct subdirectories.

A shared tree might have the following structure on the fileserver (called
{\tt fserver} in the example):
\begin{quote}\raggedright
\tt
local/tex \\
local/tex/fonts \\
local/tex/lib \\
local/tex/bin \\
local/tex/bin/sun3 \\
local/tex/bin/sun4 \\
local/tex/bin/hp9000 \\
...
\end{quote}
In this example, the subdirectories of {\tt local/tex/bin} should be
hidden when accessed via the automount point (conventionally {\tt /vol}).
A mount-map for {\tt /vol} to achieve this would look like:
{\tt\begin{tabbing}
tex/fonts\ \ \ \ \ \= \kill \\
/defaults          \> rfs:=/vol;sublink:=\$\{key\};rhost:=fserver;type:=link\\
tex                \> type:=auto;fs:=\$\{map\};pref:=\$\{key\}/\\
tex/fonts          \> host!=fserver;type:=nfs\ {\verb+\+}\\
                   \> host==fserver;fs:=/usr/local \\
tex/lib            \> host!=fserver;type:=nfs\ {\verb+\+}\\
                   \> host==fserver;fs:=/usr/local \\
tex/bin            \> -sublink:=\$\{key\}/\$\{arch\} host!=fserver;type:=nfs\ {\verb+\+}\\
                   \> host:=fserver;fs:=/usr/local
\end{tabbing}}
When {\tt /vol/tex/bin} is referenced, the current machine architecture
is automatically appended to the path by the \Var{sublink} variable.
This means that users can have {\tt /vol/tex/bin} in their {\tt PATH}
without concern for architecture dependencies.

\Section{Wildcard names \& Replicated Servers}
By using the wildcard facility, \amd\ can {\em overlay} an existing
directory with additional entries.
The system files are usually mounted under {\tt /usr}.  If instead
\amd\ is mounted on {\tt /usr}, additional
names can be overlayed to augment or replace names in the ``master'' {\tt /usr}.
A map to do this would have the form:
{\tt\begin{tabbing}
local\ \ \ \ \ \= blah \kill \\
local          \> type:=auto;fs:=local-map\\
share          \> type:=auto;fs:=share-map\\
{}*            \> -type:=nfs;rfs:=/export/exec/\$\{arch\};sublink:="\$\{key\}"\ \verb+\+\\
               \> \ \ \ \ rhost:=fserv1\ \ rhost:=fserv2\ \ rhost:=fserv3 \\
\end{tabbing}}
Note that the assignment to \Var{sublink} is surrounded by double quotes to
prevent the incoming key from causing the map to be misinterpreted.
This map has the effect of directing any access to {\tt /usr/local} or {\tt /usr/share}
to another automount point.
In this example, it is assumed that the {\tt /usr} files are replicated on
three fileservers: {\tt fserv1}, {\tt fserv2} and {\tt fserv3}.
For any references other than to {\tt local}
and {\tt share} one of the servers is used and a symbolic link to
{\tt \Var{autodir}/\Var{rhost}/export/exec/\Var{arch}/}{\em whatever}
is returned once an appropriate filesystem has been mounted.

\Section{{\tt rwho} servers\label{example:rwho}}

The {\tt /usr/spool/rwho} directory is a good candidate for automounting.
For efficiency reasons it is best to capture the rwho data on a small
number of machines and then mount that information onto a large number
of clients.  The data written into the rwho files is byte order dependent
so only servers with the correct byte ordering can be used by a client:
{\tt\begin{tabbing}
usr/spool/rwho\ \ \ \ \ \= blah \kill \\
/defaults               \> type:=nfs \\
usr/spool/rwho          \> -byte==little;rfs:=/usr/spool/rwho \verb+\+\\
                        \>\ \ \ \ rhost:=vaxA\ \ rhost:=vaxB \verb+\+\\
                        \>|| -rfs:=/usr/spool/rwho \verb+\+\\
                        \>\ \ \ \ rhost:=sun4\ \ rhost:=hp300\\
\end{tabbing}}

\Section{{\tt /vol}}
{\tt /vol} is used as a catch-all for volumes which do not have other conventional names.

Below is part of the {\tt /vol} map for the domain {\tt doc.ic.ac.uk}.
The {\tt r+d} tree is used for new or experimental software that needs to be
available everywhere without installing it on all the fileservers.  Users wishing to
try out the new software then simply include {\tt /vol/r+d/{bin,ucb}} in their path.

The main tree resides on one host {\tt gould.doc.ic.ac.uk}, which has different
{\tt bin}, {\tt etc}, {\tt lib} and {\tt ucb} sub-directories for each machine
architecture.  For example, {\tt /vol/r+d/bin} for a Sun-4 would be stored in
the sub-directory {\tt bin/sun4} of the filesystem {\tt /usr/r+d}.  When it was
accessed a symbolic link pointing to {\tt /a/gould/usr/r+d/bin/sun4} would be
returned.

\begin{verbatim}
/defaults    type:=nfs;opts:=rw,grpid,nosuid,intr,soft
wp           -opts:=rw,grpid,nosuid;rhost:=charm \
             host==charm;type:=link;fs:=/usr/local/wp \
             host!=charm;type:=nfs;rfs:=/vol/wp
...
#
src          -opts:=rw,grpid,nosuid;rhost:=charm \
             host==charm;type:=link;fs:=/usr/src \
             host!=charm;type:=nfs;rfs:=/vol/src
#
r+d          type:=auto;fs:=${map};pref:=r+d/
# per architecture bin,etc,lib&ucb...
r+d/bin      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}/${arch}
r+d/etc      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}/${arch}
r+d/include  rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}
r+d/lib      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}/${arch}
r+d/man      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}
r+d/src      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}
r+d/ucb      rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=${/key}/${arch}
# hades pictures
pictures     -opts:=rw,grpid,nosuid;rhost:=thpfs \
             host==thpfs;type:=link;fs:=/nbsd/pictures \
             host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures
# hades tools
hades        -opts:=rw,grpid,nosuid;rhost:=thpfs \
             host==thpfs;type:=link;fs:=/nbsd/hades \
             host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades
# bsd tools for hp.
bsd          -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \
             host==thpfs;type:=link;fs:=/nbsd/bsd \
             host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd
\end{verbatim}