netif Option
------------

   This defines the set of network interfaces configured on the machine.
The interface attributes collected by FSinfo are the IP address, subnet
mask and hardware address.  Multiple interfaces may be defined for
hosts with several interfaces by an entry for each interface.  The
values given are sanity checked, but are currently unused for anything
else.

     netif       : "netif" <STRING> "{" list(netif_attrs) "}" ;

     netif_attrs : netif_attr "=" <STRING> ;

     netif_attr  : "inaddr" | "netmask" | "hwaddr" ;

   Examples:

     netif ie0 {
         inaddr  = 129.31.81.37
         netmask = 0xfffffe00
         hwaddr  = "08:00:20:01:a6:a5"
     }

     netif ec0 { }

config Option
-------------

   This option allows you to specify configuration variables for the
startup scripts (`rc' scripts).  A simple string should immediately
follow the keyword.

   Example:

     config "NFS_SERVER=true"
     config "ZEPHYR=true"

   This option is currently unsupported.

arch Option
-----------

   This defines the architecture of the machine.  For example:

     arch = hp300

   This is intended to be of use when building architecture specific
mountmaps, however, the option is currently unsupported.

os Option
---------

   This defines the operating system type of the host.  For example:

     os = hpux

   This information is used when creating the `fstab' files, for
example in choosing which format to use for the `fstab' entries within
the file.

cluster Option
--------------

   This is used for specifying in which cluster the machine belongs.
For example:

     cluster = "theory"

   The cluster is intended to be used when generating the automount
maps, although it is currently unsupported.

FSinfo filesystems
==================

   The list of physically attached filesystems follows the machine
attributes.  These should define all the filesystems available from this
machine, whether exported or not.  In addition to the device name,
filesystems have several attributes, such as filesystem type, mount
options, and `fsck' pass number which are needed to generate `fstab'
entries.

     filesystem  : "fs" <DEVICE> "{" list(fs_data) "}" ;

     fs_data     : fs_data_attr "=" <STRING>
                 | mount
                 ;

     fs_data_attr
                 : "fstype" | "opts" | "passno"
                 | "freq" | "dumpset" | "log"
                 ;

   Here, <DEVICE> is the device name of the disk (for example,
`/dev/dsk/2s0').  The device name is used for building the mount maps
and for the `fstab' file.  The attributes that can be specified are
shown in the following section.

   The FSinfo configuration file for `dylan.doc.ic.ac.uk' is listed
below.

     host dylan.doc.ic.ac.uk

     fs /dev/dsk/0s0 {
     	fstype = swap
     }

     fs /dev/dsk/0s0 {
     	fstype = hfs
     	opts = rw,noquota,grpid
     	passno = 0;
     	freq = 1;
     	mount / { }
     }

     fs /dev/dsk/1s0 {
     	fstype = hfs
     	opts = defaults
     	passno = 1;
     	freq = 1;
     	mount /usr {
     		local {
     			exportfs "dougal eden dylan zebedee brian"
     			volname /nfs/hp300/local
     		}
     	}
     }

     fs /dev/dsk/2s0 {
     	fstype = hfs
     	opts = defaults
     	passno = 1;
     	freq = 1;
     	mount default {
     		exportfs "toytown_clients hangers_on"
     		volname /home/dylan/dk2
     	}
     }

     fs /dev/dsk/3s0 {
     	fstype = hfs
     	opts = defaults
     	passno = 1;
     	freq = 1;
     	mount default {
     		exportfs "toytown_clients hangers_on"
     		volname /home/dylan/dk3
     	}
     }

     fs /dev/dsk/5s0 {
     	fstype = hfs
     	opts = defaults
     	passno = 1;
     	freq = 1;
     	mount default {
     		exportfs "toytown_clients hangers_on"
     		volname /home/dylan/dk5
     	}
     }

fstype Option
-------------

   This specifies the type of filesystem being declared and will be
placed into the `fstab' file as is.  The value of this option will be
handed to `mount' as the filesystem type--it should have such values as
`4.2', `nfs' or `swap'.  The value is not examined for correctness.

   There is one special case.  If the filesystem type is specified as
`export' then the filesystem information will not be added to the
host's `fstab' information, but it will still be visible on the
network.  This is useful for defining hosts which contain referenced
volumes but which are not under full control of FSinfo.

   Example:

     fstype = swap

opts Option
-----------

   This defines any options that should be given to mount(8) in the
`fstab' file.  For example:

     opts = rw,nosuid,grpid

passno Option
-------------

   This defines the fsck(8) pass number in which to check the
filesystem.  This value will be placed into the `fstab' file.

   Example:

     passno = 1

freq Option
-----------

   This defines the interval (in days) between dumps.  The value is
placed as is into the `fstab' file.

   Example:

     freq = 3

mount Option
------------

   This defines the mountpoint at which to place the filesystem.  If the
mountpoint of the filesystem is specified as `default', then the
filesystem will be mounted in the automounter's tree under its volume
name and the mount will automatically be inherited by the automounter.

   Following the mountpoint, namespace information for the filesystem
may be described.  The options that can be given here are `exportfs',
`volname' and `sel'.

   The format is:

     mount       : "mount" vol_tree ;

     vol_tree    : list(vol_tree_attr) ;

     vol_tree_attr
                 :  <STRING> "{" list(vol_tree_info) vol_tree "}" ;

     vol_tree_info
                 : "exportfs" <EXPORT-DATA>
                 | "volname" <VOLNAME>
                 | "sel" <SELECTOR-LIST>
                 ;

   Example:

     mount default {
         exportfs "dylan dougal florence zebedee"
         volname /vol/andrew
     }

   In the above example, the filesystem currently being declared will
have an entry placed into the `exports' file allowing the filesystem to
be exported to the machines `dylan', `dougal', `florence' and
`zebedee'.  The volume name by which the filesystem will be referred to
remotely, is `/vol/andrew'.  By declaring the mountpoint to be
`default', the filesystem will be mounted on the local machine in the
automounter tree, where Amd will automatically inherit the mount as
`/vol/andrew'.

`exportfs'
     a string defining which machines the filesystem may be exported to.
     This is copied, as is, into the `exports' file--no sanity checking
     is performed on this string.

`volname'
     a string which declares the remote name by which to reference the
     filesystem.  The string is entered into a dictionary and allows
     you to refer to this filesystem in other places by this volume
     name.

`sel'
     a string which is placed into the automounter maps as a selector
     for the filesystem.

dumpset Option
--------------

   This provides support for Imperial College's local file backup tools
and is not documented further here.

log Option
----------

   Specifies the log device for the current filesystem. This is ignored
if not required by the particular filesystem type.

FSinfo static mounts
====================

   Each host may also have a number of statically mounted filesystems.
For example, the host may be a diskless workstation in which case it
will have no `fs' declarations.  In this case the `mount' declaration
is used to determine from where its filesystems will be mounted.  In
addition to being added to the `fstab' file, this information can also
be used to generate a suitable `bootparams' file.

     mount       : "mount" <VOLNAME> list(localinfo) ;

     localinfo   : localinfo_attr <STRING> ;

     localinfo_attr
                 : "as"
                 | "from"
                 | "fstype"
                 | "opts"
                 ;

   The filesystem specified to be mounted will be searched for in the
dictionary of volume names built when scanning the list of hosts'
definitions.

   The attributes have the following semantics:
`from MACHINE'
     mount the filesystem from the machine with the hostname of
     "machine".

`as MOUNTPOINT'
     mount the filesystem locally as the name given, in case this is
     different from the advertised volume name of the filesystem.

`opts OPTIONS'
     native mount(8) options.

`fstype TYPE'
     type of filesystem to be mounted.

   An example:

     mount /export/exec/hp300/local as /usr/local

   If the mountpoint specified is either `/' or `swap', the machine
will be considered to be booting off the net and this will be noted for
use in generating a `bootparams' file for the host which owns the
filesystems.

Defining an Amd Mount Map in FSinfo
===================================

   The maps used by Amd can be constructed from FSinfo by defining all
the automount trees.  FSinfo takes all the definitions found and builds
one map for each top level tree.

   The automount tree is usually defined last.  A single automount
configuration will usually apply to an entire management domain.  One
`automount' declaration is needed for each Amd automount point.  FSinfo
determines whether the automount point is "direct" (see Direct Automount Filesystem.)
or "indirect" (see Top-level Filesystem.).
Direct automount points are distinguished by the fact that there is no
underlying "automount_tree".

     automount   : "automount" opt(auto_opts) automount_tree ;

     auto_opts   : "opts" <MOUNT-OPTIONS> ;

     automount_tree
                 : list(automount_attr)
                 ;

     automount_attr
                 : <STRING> "=" <VOLNAME>
                 | <STRING> "->" <SYMLINK>
                 | <STRING> "{" automount_tree "}"
                 ;

   If <MOUNT-OPTIONS> is given, then it is the string to be placed in
the maps for Amd for the `opts' option.

   A "map" is typically a tree of filesystems, for example `home'
normally contains a tree of filesystems representing other machines in
the network.

   A map can either be given as a name representing an already defined
volume name, or it can be a tree.  A tree is represented by placing
braces after the name.  For example, to define a tree `/vol', the
following map would be defined:

     automount /vol { }

   Within a tree, the only items that can appear are more maps.  For
example:

     automount /vol {
         andrew { }
         X11 { }
     }

   In this case, FSinfo will look for volumes named `/vol/andrew' and
`/vol/X11' and a map entry will be generated for each.  If the volumes
are defined more than once, then FSinfo will generate a series of
alternate entries for them in the maps.

   Instead of a tree, either a link (NAME `->' DESTINATION) or a
reference can be specified (NAME `=' DESTINATION).  A link creates a
symbolic link to the string specified, without further processing the
entry.  A reference will examine the destination filesystem and
optimise the reference.  For example, to create an entry for `njw' in
the `/homes' map, either of the two forms can be used:

     automount /homes {
         njw -> /home/dylan/njw
     }

   or

     automount /homes {
         njw = /home/dylan/njw
     }

   In the first example, when `/homes/njw' is referenced from Amd, a
link will be created leading to `/home/dylan/njw' and the automounter
will be referenced a second time to resolve this filename.  The map
entry would be:

     njw type:=link;fs:=/home/dylan/njw

   In the second example, the destination directory is analysed and
found to be in the filesystem `/home/dylan' which has previously been
defined in the maps. Hence the map entry will look like:

     njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw

   Creating only one symbolic link, and one access to Amd.

FSinfo Command Line Options
===========================

   FSinfo is started from the command line by using the command:

     fsinfo [options] files ...

   The input to FSinfo is a single set of definitions of machines and
automount maps.  If multiple files are given on the command-line, then
the files are concatenated together to form the input source.  The files
are passed individually through the C pre-processor before being parsed.

   Several options define a prefix for the name of an output file.  If
the prefix is not specified no output of that type is produced.  The
suffix used will correspond either to the hostname to which a file
belongs, or to the type of output if only one file is produced.
Dumpsets and the `bootparams' file are in the latter class.  To put the
output into a subdirectory simply put a `/' at the end of the prefix,
making sure that the directory has already been made before running
`fsinfo'.

`-a' AUTODIR
------------

   Specifies the directory name in which to place the automounter's
mountpoints.  This defaults to `/a'.  Some sites have the autodir set
to be `/amd', and this would be achieved by:

     fsinfo -a /amd ...

`-b' BOOTPARAMS
---------------

   This specifies the prefix for the `bootparams' filename.  If it is
not given, then the file will not be generated.  The `bootparams' file
will be constructed for the destination machine and will be placed into
a file named `bootparams' and prefixed by this string.  The file
generated contains a list of entries describing each diskless client
that can boot from the destination machine.

   As an example, to create a `bootparams' file in the directory
`generic', the following would be used:

     fsinfo -b generic/ ...

`-d' DUMPSETS
-------------

   This specifies the prefix for the `dumpsets' file.  If it is not
specified, then the file will not be generated.  The file will be for
the destination machine and will be placed into a filename `dumpsets',
prefixed by this string.  The `dumpsets' file is for use by Imperial
College's local backup system.

   For example, to create a dumpsets file in the directory `generic',
then you would use the following:

     fsinfo -d generic/ ...

`-e' EXPORTFS
-------------

   Defines the prefix for the `exports' files.  If it is not given,
then the file will not be generated.  For each machine defined in the
configuration files as having disks, an `exports' file is constructed
and given a filename determined by the name of the machine, prefixed
with this string.  If a machine is defined as diskless, then no
`exports' file will be created for it.  The files contain entries for
directories on the machine that may be exported to clients.

   Example: To create the `exports' files for each diskful machine and
place them into the directory `exports':

     fsinfo -e exports/ ...

`-f' FSTAB
----------

   This defines the prefix for the `fstab' files.  The files will only
be created if this prefix is defined.  For each machine defined in the
configuration files, a `fstab' file is created with the filename
determined by prefixing this string with the name of the machine.  These
files contain entries for filesystems and partitions to mount at boot
time.

   Example, to create the files in the directory `fstabs':

     fsinfo -f fstabs/ ...

`-h' HOSTNAME
-------------

   Defines the hostname of the destination machine to process for.  If
this is not specified, it defaults to the local machine name, as
returned by gethostname(2).

   Example:

     fsinfo -h dylan.doc.ic.ac.uk ...

`-m' MOUNT-MAPS
---------------

   Defines the prefix for the automounter files.  The maps will only be
produced if this prefix is defined.  The mount maps suitable for the
network defined by the configuration files will be placed into files
with names calculated by prefixing this string to the name of each map.

   For example, to create the automounter maps and place them in the
directory `automaps':

     fsinfo -m automaps/ ...

`-q'
----

   Selects quiet mode.  FSinfo suppress the "running commentary" and
only outputs any error messages which are generated.

`-v'
----

   Selects verbose mode.  When this is activated, the program will
display more messages, and display all the information discovered when
performing the semantic analysis phase.  Each verbose message is output
to `stdout' on a line starting with a `#' character.

`-D' NAME[=DEFN]
----------------

   Defines a symbol "name" for the preprocessor when reading the
configuration files.  Equivalent to `#define' directive.

`-I' DIRECTORY
--------------

   This option is passed into the preprocessor for the configuration
files.  It specifies directories in which to find include files

`-U' NAME
---------

   Removes any initial definition of the symbol "name".  Inverse of the
`-D' option.

Errors produced by FSinfo
=========================

   The following table documents the errors and warnings which FSinfo
may produce.

can't open FILENAME for writing
     Occurs if any errors are encountered when opening an output file.

unknown host attribute
     Occurs if an unrecognised keyword is used when defining a host.

unknown filesystem attribute
     Occurs if an unrecognised keyword is used when defining a host's
     filesystems.

not allowed '/' in a directory name
     When reading the configuration input, if there is a filesystem
     definition which contains a pathname with multiple directories for
     any part of the mountpoint element, and it is not a single
     absolute path, then this message will be produced by the parser.

unknown directory attribute
     If an unknown keyword is found while reading the definition of a
     hosts's filesystem mount option.

unknown mount attribute
     Occurs if an unrecognised keyword is found while parsing the list
     of static mounts.

" expected
     Occurs if an unescaped newline is found in a quoted string.

unknown \ sequence
     Occurs if an unknown escape sequence is found inside a string.
     Within a string, you can give the standard C escape sequences for
     strings, such as newlines and tab characters.

FILENAME: cannot open for reading
     If a file specified on the command line as containing
     configuration data could not be opened.

end of file within comment
     A comment was unterminated before the end of one of the
     configuration files.

host field "FIELD-NAME" already set
     If duplicate definitions are given for any of the fields with a
     host definition.

duplicate host HOSTNAME!
     If a host has more than one definition.

netif field FIELD-NAME already set
     Occurs if you attempt to define an attribute of an interface more
     than once.

malformed IP dotted quad: ADDRESS
     If the Internet address of an interface is incorrectly specified.
     An Internet address definition is handled to inet_addr(3N) to see
     if it can cope.  If not, then this message will be displayed.

malformed netmask: NETMASK
     If the netmask cannot be decoded as though it were a hexadecimal
     number, then this message will be displayed.  It will typically be
     caused by incorrect characters in the NETMASK value.

fs field "FIELD-NAME" already set
     Occurs when multiple definitions are given for one of the
     attributes of a host's filesystem.

mount tree field "FIELD-NAME" already set
     Occurs when the FIELD-NAME is defined more than once during the
     definition of a filesystems mountpoint.

mount field "FIELD-NAME" already set
     Occurs when a static mount has multiple definitions of the same
     field.

no disk mounts on HOSTNAME
     If there are no static mounts, nor local disk mounts specified for
     a machine, this message will be displayed.

HOST:DEVICE needs field "FIELD-NAME"
     Occurs when a filesystem is missing a required field. FIELD-NAME
     could be one of `fstype', `opts', `passno' or `mount'.

FILESYSTEM has a volname but no exportfs data
     Occurs when a volume name is declared for a file system, but the
     string specifying what machines the filesystem can be exported to
     is missing.

sub-directory DIRECTORY of DIRECTORY-TREE starts with '/'
     Within the filesystem specification for a host, if an element
     DIRECTORY of the mountpoint begins with a `/' and it is not the
     start of the tree.

HOST:DEVICE has no mount point
     Occurs if the `mount' option is not specified for a host's
     filesystem.

HOST:DEVICE has more than one mount point
     Occurs if the mount option for a host's filesystem specifies
     multiple trees at which to place the mountpoint.

no volname given for HOST:DEVICE
     Occurs when a filesystem is defined to be mounted on `default', but
     no volume name is given for the file system, then the mountpoint
     cannot be determined.

HOST:mount field specified for swap partition
     Occurs if a mountpoint is given for a filesystem whose type is
     declared to be `swap'.

ambiguous mount: VOLUME is a replicated filesystem
     If several filesystems are declared as having the same volume
     name, they will be considered replicated filesystems.  To mount a
     replicated filesystem statically, a specific host will need to be
     named, to say which particular copy to try and mount, else this
     error will result.

cannot determine localname since volname VOLUME is not uniquely defined
     If a volume is replicated and an attempt is made to mount the
     filesystem statically without specifying a local mountpoint,
     FSinfo cannot calculate a mountpoint, as the desired pathname
     would be ambiguous.

volname VOLUME is unknown
     Occurs if an attempt is made to mount or reference a volume name
     which has not been declared during the host filesystem definitions.

volname VOLUME not exported from MACHINE
     Occurs if you attempt to mount the volume VOLUME from a machine
     which has not declared itself to have such a filesystem available.

network booting requires both root and swap areas
     Occurs if a machine has mount declarations for either the root
     partition or the swap area, but not both.  You cannot define a
     machine to only partially boot via the network.

unknown volname VOLUME automounted [ on <name> ]
     Occurs if VOLUME is used in a definition of an automount map but
     the volume name has not been declared during the host filesystem
     definitions.

not allowed '/' in a directory name
     Occurs when a pathname with multiple directory elements is
     specified as the name for an automounter tree.  A tree should only
     have one name at each level.

DEVICE has duplicate exportfs data
     Produced if the `exportfs' option is used multiple times within the
     same branch of a filesytem definition. For example, if you attempt
     to set the `exportfs' data at different levels of the mountpoint
     directory tree.

sub-directory of DIRECTORY-TREE is named "default"
     `default' is a keyword used to specify if a mountpoint should be
     automatically calculated by FSinfo.  If you attempt to specify a
     directory name as this, it will use the filename of `default' but
     will produce this warning.

pass number for HOST:DEVICE is non-zero
     Occurs if DEVICE has its `fstype' declared to be `swap' or
     `export' and the fsck(8) pass number is set. Swap devices should
     not be fsck'd.  See FSinfo filesystems fstype

dump frequency for HOST:DEVICE is non-zero
     Occurs if DEVICE has its `fstype' declared to be `swap' or
     `export' and the `dump' option is set to a value greater than
     zero.  Swap devices should not be dumped.

Examples
********

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
/home/machine.

   Typically, the `/etc/fstab' file contained a long list of entries
such as:

     machine:/home/machine /home/machine nfs ...

   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, `/etc/fstab' must be
updated on every machine, the mount directory created and the filesystem
mounted.

   In many 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 `localhost' which is used for users such as the
operator (`opr') who have a home directory on most machine as
`/home/localhost/opr'.

     /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}
     ...

   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

     amd /home amd.home

   Note that when mounting a remote filesystem, the "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).

Home Directories
================

   One convention for home directories is to locate them in `/homes' so
user `jsp''s home directory is `/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:

     amd /homes amd.homes

   where the map `amd.homes' contained the entries:

     /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

   Whenever a login name is accessed in `/homes' a symbolic link
appears pointing to the real location of that user's home directory.  In
this example, `/homes/jsp' would appear to be a symbolic link pointing
to `/home/charm/jsp'.  Of course, `/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 `/homes' map.  The
required map is simple, but long, and its creation is best automated.
The entry for `jsp' could be:

     jsp   -sublink:=${key};rfs:=/home/charm \
                    host==charm;type:=ufs;dev:=/dev/xd0g \
                    host!=charm;type:=nfs;rhost:=charm

   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
`/etc/fstab', taking care that they are mounted in the same place that
Amd would have automounted them.  In most cases this would be something
like `/a/"host"/home/"host"' and `/etc/fstab' on host `charm' would
have a line:

     /dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5

   The map can then be changed to:

     /defaults    type:=nfs;sublink:=${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/${key}
     sjv          rhost:=ganymede;rfs:=/home/ganymede

   This map operates as usual on a remote machine (ie `${host}' not
equal to `${rhost}').  On the machine where the filesystem is stored
(ie `${host}' equal to `${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 Inheritance Filesystem.).  If "-r" is not used then a
loopback NFS mount will be made.  This type of mount is known to cause
a deadlock on many systems.

Architecture Sharing
====================

   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 `fserver' in the example):

     local/tex
     local/tex/fonts
     local/tex/lib
     local/tex/bin
     local/tex/bin/sun3
     local/tex/bin/sun4
     local/tex/bin/hp9000
     ...

   In this example, the subdirectories of `local/tex/bin' should be
hidden when accessed via the automount point (conventionally `/vol').
A mount-map for `/vol' to achieve this would look like:

     /defaults   sublink:=${/key};rhost:=fserver;type:=link
     tex         type:=auto;fs:=${map};pref:=${key}/
     tex/fonts   host!=fserver;type:=nfs;rfs:=/vol/tex \
                 host==fserver;fs:=/usr/local/tex
     tex/lib     host!=fserver;type:=nfs;rfs:=/vol/tex \
                 host==fserver;fs:=/usr/local/tex
     tex/bin     -sublink:=${/key}/${arch} host!=fserver;type:=nfs;rfs:=/vol/tex \
                 host:=fserver;fs:=/usr/local/tex

   When `/vol/tex/bin' is referenced, the current machine architecture
is automatically appended to the path by the `${sublink}' variable.
This means that users can have `/vol/tex/bin' in their `PATH' without
concern for architecture dependencies.

Wildcard names & Replicated Servers
===================================

   By using the wildcard facility, Amd can "overlay" an existing
directory with additional entries.  The system files are usually
mounted under `/usr'.  If instead Amd is mounted on `/usr', additional
names can be overlayed to augment or replace names in the "master"
`/usr'.  A map to do this would have the form:

     local  type:=auto;fs:=local-map
     share  type:=auto;fs:=share-map
     *      -type:=nfs;rfs:=/export/exec/${arch};sublink:="${key}" \
             rhost:=fserv1  rhost:=fserv2  rhost:=fserv3

   Note that the assignment to `${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
`/usr/local' or `/usr/share' to another automount point.

   In this example, it is assumed that the `/usr' files are replicated
on three fileservers: `fserv1', `fserv2' and `fserv3'.  For any
references other than to `local' and `share' one of the servers is used
and a symbolic link to ${autodir}/${rhost}/export/exec/${arch}/whatever
is returned once an appropriate filesystem has been mounted.

`rwho' servers
==============

   The `/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:

     /defaults         type:=nfs
     usr/spool/rwho    -byte==little;rfs:=/usr/spool/rwho \
                           rhost:=vaxA  rhost:=vaxB \
                       || -rfs:=/usr/spool/rwho \
                           rhost:=sun4  rhost:=hp300

`/vol'
======

   `/vol' is used as a catch-all for volumes which do not have other
conventional names.

   Below is part of the `/vol' map for the domain `doc.ic.ac.uk'.  The
`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
`/vol/r+d/{bin,ucb}' in their path.

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

     /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

Internals
*********

Log Messages
============

   In the following sections a brief explanation is given of some of the
log messages made by Amd.  Where the message is in `typewriter' font,
it corresponds exactly to the message produced by Amd.  Words in
"italic" are replaced by an appropriate string.  Variables, `${var}',
indicate that the value of the appropriate variable is output.

   Log messages are either sent direct to a file, or logged via the
syslog(3) mechanism.  Messages are logged with facility `LOG_DAEMON'
when using syslog(3).  In either case, entries in the file are of the
form:
     date-string  hostname amd[pid]  message

Fatal errors
------------

   Amd attempts to deal with unusual events.  Whenever it is not
possible to deal with such an error, Amd will log an appropriate
message and, if it cannot possibly continue, will either exit or abort.
These messages are selected by `-x fatal' on the command line.  When
syslog(3) is being used, they are logged with level `LOG_FATAL'.  Even
if Amd continues to operate it is likely to remain in a precarious
state and should be restarted at the earliest opportunity.

Attempting to inherit not-a-filesystem
     The prototype mount point created during a filesystem restart did
     not contain a reference to the restarted filesystem.  This erorr
     "should never happen".

Can't bind to domain "NIS-domain"
     A specific NIS domain was requested on the command line, but no
     server for that domain is available on the local net.

Can't determine IP address of this host (hostname)
     When Amd starts it determines its own IP address.  If this lookup
     fails then Amd cannot continue.  The hostname it looks up is that
     obtained returned by gethostname(2) system call.

Can't find root file handle for automount point
     Amd creates its own file handles for the automount points.  When it
     mounts itself as a server, it must pass these file handles to the
     local kernel.  If the filehandle is not obtainable the mount point
     is ignored.  This error "should never happen".

Must be root to mount filesystems (euid = euid)
     To prevent embarrassment, Amd makes sure it has appropriate system
     privileges.  This amounts to having an euid of 0.  The check is
     made after argument processing complete to give non-root users a
     chance to access the "-v" option.

No work to do - quitting
     No automount points were given on the command line and so there is
     no work to do.

Out of memory in realloc
     While attempting to realloc some memory, the memory space
     available to Amd was exhausted.  This is an unrecoverable error.

Out of memory
     While attempting to malloc some memory, the memory space available
     to Amd was exhausted.  This is an unrecoverable error.

cannot create rpc/udp service
     Either the NFS or AMQ endpoint could not be created.

gethostname: description
     The gethostname(2) system call failed during startup.

host name is not set
     The gethostname(2) system call returned a zero length host name.
     This can happen if Amd is started in single user mode just after
     booting the system.

ifs_match called!
     An internal error occurred while restarting a pre-mounted
     filesystem.  This error "should never happen".

mount_afs: description
     An error occured while Amd was mounting itself.

run_rpc failed
     Somehow the main NFS server loop failed.  This error "should never
     happen".

unable to free rpc arguments in amqprog_1
     The incoming arguments to the AMQ server could not be free'ed.

unable to free rpc arguments in nfs_program_1
     The incoming arguments to the NFS server could not be free'ed.

unable to register (AMQ_PROGRAM, AMQ_VERSION, udp)
     The AMQ server could not be registered with the local portmapper
     or the internal RPC dispatcher.

unable to register (NFS_PROGRAM, NFS_VERSION, 0)
     The NFS server could not be registered with the internal RPC
     dispatcher.

Info messages
-------------

   Amd generates information messages to record state changes.  These
messages are selected by `-x info' on the command line.  When syslog(3)
is being used, they are logged with level `LOG_INFO'.

   The messages listed below can be generated and are in a format
suitable for simple statistical analysis.  "mount-info" is the string
that is displayed by "Amq" in its mount information column and placed
in the system mount table.

mount of "${path}" on ${fs} timed out
     Attempts to mount a filesystem for the given automount point have
     failed to complete within 30 seconds.

"${path}" forcibly timed out
     An automount point has been timed out by the Amq command.

restarting mount-info on ${fs}
     A pre-mounted file system has been noted.

"${path}" has timed out
     No access to the automount point has been made within the timeout
     period.

file server ${rhost} is down - timeout of "${path}" ignored
     An automount point has timed out, but the corresponding file
     server is known to be down.  This message is only produced once
     for each mount point for which the server is down.

Re-synchronizing cache for map ${map}
     The named map has been modified and the internal cache is being
     re-synchronized.

Filehandle denied for "${rhost}:${rfs}"
     The mount daemon refused to return a file handle for the requested
     filesystem.

Filehandle error for "${rhost}:${rfs}": description
     The mount daemon gave some other error for the requested
     filesystem.

file server ${rhost} type nfs starts up
     A new NFS file server has been referenced and is known to be up.

file server ${rhost} type nfs starts down
     A new NFS file server has been referenced and is known to be down.

file server ${rhost} type nfs is up
     An NFS file server that was previously down is now up.

file server ${rhost} type nfs is down
     An NFS file server that was previously up is now down.

Finishing with status exit-status
     Amd is about to exit with the given exit status.

mount-info mounted fstype ${type} on ${fs}
     A new file system has been mounted.

mount-info restarted fstype ${type} on ${fs}
     Amd is using a pre-mounted filesystem to satisfy a mount request.

mount-info unmounted fstype ${type} from ${fs}
     A file system has been unmounted.

mount-info unmounted fstype ${type} from ${fs} link ${fs}/${sublink}
     A file system of which only a sub-directory was in use has been
     unmounted.

Acknowledgements & Trademarks
*****************************

   Thanks to the Formal Methods Group at Imperial College for suffering
patiently while Amd was being developed on their machines.

   Thanks to the many people who have helped with the development of
Amd, especially Piete Brooks at the Cambridge University Computing Lab
for many hours of testing, experimentation and discussion.

   * DEC, VAX and Ultrix are registered trademarks of Digital Equipment
     Corporation.

   * AIX and IBM are registered trademarks of International Business
     Machines Corporation.

   * Sun, NFS and SunOS are registered trademarks of Sun Microsystems,
     Inc.

   * Unix is a registered trademark of AT&T Unix Systems Laboratories
     in the USA and other countries.