Amd Command Line Options
************************

   Many of Amd's parameters can be set from the command line.  The
command line is also used to specify automount points and maps.

   The general format of a command line is

     amd [options] { directory map-name [-map-options] } ...

   For each directory and map-name given, Amd establishes an automount
point.  The "map-options" may be any sequence of options or
selectors--see Location Format..  The "map-options" apply only to
Amd's mount point.

   `type:=toplvl;cache:=mapdefault;fs:=${map}' is the default value for
the map options.  Default options for a map are read from a special
entry in the map whose key is the string `/defaults'.  When default
options are given they are prepended to any options specified in the
mount-map locations as explained in.  See Map Defaults, for more
details.

   The "options" are any combination of those listed below.

   Once the command line has been parsed, the automount points are
mounted.  The mount points are created if they do not already exist, in
which case they will be removed when Amd exits.  Finally, Amd
disassociates itself from its controlling terminal and forks into the
background.

   Note: Even if Amd has been built with `-DDEBUG' it will still
background itself and disassociate itself from the controlling terminal.
To use a debugger it is necessary to specify `-D nodaemon' on the
command line.

`-a' DIRECTORY
==============

   Specifies the default mount directory.  This option changes the
variable `${autodir}' which otherwise defaults to `/a'.  For example,
some sites prefer `/amd'.

     amd -a /amd ...

`-c' CACHE-INTERVAL
===================

   Selects the period, in seconds, for which a name is cached by Amd.
If no reference is made to the volume in this period, Amd discards the
volume name to filesystem mapping.

   Once the last reference to a filesystem has been removed, Amd
attempts to unmount the filesystem.  If the unmount fails the interval
is extended by a further period as specified by the `-w' command line
option or by the `utimeout' mount option.

   The default "cache-interval" is 300 seconds (five minutes).

`-d' DOMAIN
===========

   Specifies the host's domain.  This sets the internal variable
`${domain}' and affects the `${hostd}' variable.

   If this option is not specified and the hostname already contains the
local domain then that is used, otherwise the default value of
`${domain}' is `unknown.domain'.

   For example, if the local domain was `doc.ic.ac.uk', Amd could be
started as follows:

     amd -d doc.ic.ac.uk ...

`-k' KERNEL-ARCHITECTURE
========================

   Specifies the kernel architecture of the system.  This is usually the
output of `arch -k' and its only effect is to set the variable
`${karch}'.  If this option is not given, `${karch}' has the same value
as `${arch}'.

   This would be used as follows:

     amd -k `arch -k` ...

`-l' LOG-OPTION
===============

   Selects the form of logging to be made.  Two special "log-options"
are recognised.

  1. If "log-option" is the string `syslog', Amd will use the syslog(3)
     mechanism.

  2. If "log-option" is the string `/dev/stderr', Amd will use standard
     error, which is also the default target for log messages.  To
     implement this, Amd simulates the effect of the `/dev/fd' driver.

   Any other string is taken as a filename to use for logging.  Log
messages are appended to the file if it already exists, otherwise a new
file is created.  The file is opened once and then held open, rather
than being re-opened for each message.

   If the `syslog' option is specified but the system does not support
syslog or if the named file cannot be opened or created, Amd will use
standard error.  Error messages generated before Amd has finished
parsing the command line are printed on standard error.

   Using `syslog' is usually best, in which case Amd would be started
as follows:

     amd -l syslog ...

`-n'
====

   Normalises the remote hostname before using it.  Normalisation is
done by replacing the value of `${rhost}' with the primary name
returned by a hostname lookup.

   This option should be used if several names are used to refer to a
single host in a mount map.

`-p'
====

   Causes Amd's process id to be printed on standard output.  This can
be redirected to a suitable file for use with kill:

     amd -p > /var/run/amd.pid ...

   This option only has an affect if Amd is running in daemon mode.  If
Amd is started with the `-D nodaemon' debug flag, this option is
ignored.

`-r'
====

   Tells Amd to restart existing mounts (see Inheritance Filesystem.).

`-t' TIMEOUT.RETRANSMIT
=======================

   Specifies the RPC "timeout" and "retransmit" intervals used by the
kernel to communicate to Amd.  These are used to set the `timeo' and
`retrans' mount options.

   Amd relies on the kernel RPC retransmit mechanism to trigger mount
retries.  The value of this parameter changes the retry interval.  Too
long an interval gives poor interactive response, too short an interval
causes excessive retries.

`-v'
====

   Print version information on standard error and then exit.  The
output is of the form:

     amd 5.2.1.11 of 91/03/17 18:04:05 5.3Alpha11 #0: Sun Mar 17 18:07:28 GMT 1991
     Built by pendry@vangogh.Berkeley.EDU for a hp300 running bsd44 (big-endian).
     Map support for: root, passwd, union, file, error.
     FS: ufs, nfs, nfsx, host, link, program, union, auto, direct, toplvl, error.
     Primary network is 128.32.130.0.

   The information includes the version number, release date and name of
the release.  The architecture (see Supported Machine Architectures.),
operating system (see Supported Operating Systems.)
and byte ordering are also printed as they appear in the
`${os}', `${arch}' and `${byte}' variables.

`-w' WAIT-TIMEOUT
=================

   Selects the interval in seconds between unmount attempts after the
initial time-to-live has expired.

   This defaults to 120 seconds (two minutes).

`-x' OPTS
=========

   Specifies the type and verbosity of log messages.  "opts" is a comma
separated list selected from the following options:

`fatal'
     Fatal errors

`error'
     Non-fatal errors

`user'
     Non-fatal user errors

`warn'
     Recoverable errors

`warning'
     Alias for `warn'

`info'
     Information messages

`map'
     Mount map usage

`stats'
     Additional statistics

`all'
     All of the above

   Initially a set of default logging flags is enabled.  This is as if
`-x all,nomap,nostats' had been selected.  The command line is parsed
and logging is controlled by the "-x" option.  The very first set of
logging flags is saved and can not be subsequently disabled using Amq.
This default set of options is useful for general production use.

   The `info' messages include details of what is mounted and unmounted
and when filesystems have timed out.  If you want to have the default
set of messages without the `info' messages then you simply need `-x
noinfo'.  The messages given by `user' relate to errors in the mount
maps, so these are useful when new maps are installed.  The following
table lists the syslog priorites used for each of the message types.

`fatal'
     LOG_CRIT

`error'
     LOG_ERR

`user'
     LOG_WARNING

`warning'
     LOG_WARNING

`info'
     LOG_INFO

`debug'
     LOG_DEBUG

`map'
     LOG_DEBUG

`stats'
     LOG_INFO

   The options can be prefixed by the string `no' to indicate that this
option should be turned off.  For example, to obtain all but `info'
messages the option `-x all,noinfo' would be used.

   If Amd was built with debugging enabled the `debug' option is
automatically enabled regardless of the command line options.

`-y' NIS-DOMAIN
===============

   Selects an alternate NIS domain.  This is useful for debugging and
cross-domain shared mounting.  If this flag is specified, Amd
immediately attempts to bind to a server for this domain.

`-C' CLUSTER-NAME
=================

   Specifies the name of the cluster of which the local machine is a
member.  The only effect is to set the variable `${cluster}'.  The
"cluster-name" is will usually obtained by running another command
which uses a database to map the local hostname into a cluster name.
`${cluster}' can then be used as a selector to restrict mounting of
replicated data.  If this option is not given, `${cluster}' has the
same value as `${domain}'.  This would be used as follows:

     amd -C `clustername` ...

`-D' OPTS
=========

   Controls the verbosity and coverage of the debugging trace; "opts"
is a comma separated list of debugging options.  The "-D" option is
only available if Amd was compiled with `-DDEBUG'.  The memory
debugging facilities are only available if Amd was compiled with
`-DDEBUG_MEM' (in addition to `-DDEBUG').

   The most common options to use are `-D trace' and `-D test' (which
turns on all the useful debug options).  See the program source for a
more detailed explanation of the available options.

Filesystem Types
****************

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

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

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

Network Filesystem (`type:=nfs')
================================

   The "nfs" filesystem type provides access to Sun's NFS.

The following options must be specified:

`rhost'
     the remote fileserver.  This must be an entry in the hosts
     database.  IP addresses are not accepted.  The default value is
     taken from the local host name (`${host}') if no other value is
     specified.

`rfs'
     the remote filesystem.  If no value is specified for this option,
     an internal default of `${path}' is used.

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

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

An NFS entry might be:

     jsp  host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp

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

Network Host Filesystem (`type:=host')
======================================

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

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

   When an attempt to unmount a `host' filesystem mount fails, Amd
remounts any filesystems which had succesfully been unmounted.  To do
this Amd queries the mount daemon again and obtains a fresh copy of the
export list.  Amd then tries to mount any exported filesystems which
are not currently mounted.

   Sun's automounter provides a special `-hosts' map.  To achieve the
same effect with Amd requires two steps.  First a mount map must be
created as follows:

     /defaults  type:=host;fs:=${autodir}/${rhost}/root;rhost:=${key}
     *          opts:=rw,nosuid,grpid

and then start Amd with the following command

     amd /n net.map

where `net.map' is the name of map described above.  Note that the
value of `${fs}' is overridden in the map.  This is done to avoid a
clash between the mount tree and any other filesystem already mounted
from the same fileserver.

   If different mount options are needed for different hosts then
additional entries can be added to the map, for example

     host2       opts:=ro,nosuid,soft

would soft mount `host2' read-only.

Network Filesystem Group (`type:=nfsx')
=======================================

   The "nfsx" filesystem allows a group of filesystems to be mounted
from a single NFS server.  The implementation is layered above the
`nfs' implementation so keep-alives work in the same way.

   The options are the same as for the `nfs' filesystem with one
difference.

The following options must be specified:

`rhost'
     the remote fileserver.  This must be an entry in the hosts
     database.  IP addresses are not accepted.  The default value is
     taken from the local host name (`${host}') if no other value is
     specified.

`rfs'
     as a list of filesystems to mount.  The list is in the form of a
     comma separated strings.

For example:

     pub      type:=nfsx;rhost:=gould;\
     		rfs:=/public,/,graphics,usenet;fs:=${autodir}/${rhost}/root

   The first string defines the root of the tree, and is applied as a
prefix to the remaining members of the list which define the individual
filesystems.  The first string is *not* used as a filesystem name.  A
parallel operation is used to determine the local mount points to
ensure a consistent layout of a tree of mounts.

   Here, the *three* filesystems, `/public', `/public/graphics' and
`/public/usenet', would be mounted.

   A local mount point, `${fs}', *must* be specified.  The default
local mount point will not work correctly in the general case.  A
suggestion is to use `fs:=${autodir}/${rhost}/root'.

Unix Filesystem (`type:=ufs')
=============================

   The "ufs" filesystem type provides access to the system's standard
disk filesystem--usually a derivative of the Berkeley Fast Filesystem.

The following option must be specified:

`dev'
     the block special device to be mounted.

   A UFS entry might be:

     jsp   host==charm;type:=ufs;dev:=/dev/xd0g;sublink:=jsp

Program Filesystem (`type:=program')
====================================

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

The following options must be specified:

`mount'
     the program which will perform the mount.

`unmount'
     the program which will perform the unmount.

   The exit code from these two programs is interpreted as a Unix error
code.  As usual, exit code zero indicates success.  To execute the
program Amd splits the string on whitespace to create an array of
substrings.  Single quotes `'' can be used to quote whitespace if that
is required in an argument.  There is no way to escape or change the
quote character.

   To run the program `rvdmount' with a host name and filesystem as
arguments would be specified by `mount:="/etc/rvdmount rvdmount fserver
${path}"'.

   The first element in the array is taken as the pathname of the
program to execute.  The other members of the array form the argument
vector to be passed to the program, "including argument zero".  This
means that the split string must have at least two elements.  The
program is directly executed by Amd, not via a shell.  This means that
scripts must begin with a `#!' interpreter specification.

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

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

Symbolic Link Filesystem (`type:=link')
=======================================

   Each filesystem type creates a symbolic link to point from the volume
name to the physical mount point.  The `link' filesystem does the same
without any other side effects.  This allows any part of the machines
name space to be accessed via Amd.

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

The following option must be defined:

`fs'
     The value of FS option specifies the destination of the link, as
     modified by the SUBLINK option.  If SUBLINK is non-null, it is
     appended to `${fs}'`/' and the resulting string is used as the
     target.

   The `link' filesystem can be though of as identical to the `ufs'
filesystem but without actually mounting anything.

   An example entry might be:

     jsp   host==charm;type:=link;fs:=/home/charm;sublink:=jsp
   which would return a symbolic link pointing to `/home/charm/jsp'.

Symbolic Link Filesystem II (`type:=link')
==========================================

   The `linkx' filesystem type is identical to `link' with the
exception that the target of the link must exist.  Existence is checked
with the `lstat' system call.

   The `linkx' filesystem type is particularly useful for wildcard map
entries.  In this case, a list of possible targets can be give and Amd
will choose the first one which exists on the local machine.

Automount Filesystem (`type:=auto')
===================================

   The "auto" filesystem type creates a new automount point below an
existing automount point.  Top-level automount points appear as system
mount points.  An automount mount point can also appear as a
sub-directory of an existing automount point.  This allows some
additional structure to be added, for example to mimic the mount tree of
another machine.

   The following options may be specified:

`cache'
     specifies whether the data in this mount-map should be cached.
     The default value is `none', in which case no caching is done in
     order to conserve memory.  However, better performance and
     reliability can be obtained by caching some or all of a mount-map.

     If the cache option specifies `all', the entire map is enumerated
     when the mount point is created.

     If the cache option specifies `inc', caching is done incrementally
     as and when data is required.  Some map types do not support cache
     mode `all', in which case `inc' is used whenever `all' is
     requested.

     Caching can be entirely disabled by using cache mode `none'.

     If the cache option specifies `regexp' then the entire map will be
     enumerated and each key will be treated as an egrep-style regular
     expression.  The order in which a cached map is searched does not
     correspond to the ordering in the source map so the regular
     expressions should be mutually exclusive to avoid confusion.

     Each mount map type has a default cache type, usually `inc', which
     can be selected by specifying `mapdefault'.

     The cache mode for a mount map can only be selected on the command
     line.  Starting Amd with the command:

          amd /homes hesiod.homes -cache:=inc

     will cause `/homes' to be automounted using the "Hesiod" name
     server with local incremental caching of all succesfully resolved
     names.

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

     An additional option (`sync') may be specified to force Amd to
     check the map's modify time whenever a cached entry is being used.
     For example, an incremental, synchronised cache would be created
     by the following command:

          amd /homes hesiod.homes -cache:=inc,sync

`fs'
     specifies the name of the mount map to use for the new mount point.

     Arguably this should have been specified with the `${rfs}' option
     but we are now stuck with it due to historical accident.

`pref'
     alters the name that is looked up in the mount map.  If `${pref}',
     the "prefix", is non-null then it is prepended to the name
     requested by the kernel "before" the map is searched.

   The server `dylan.doc.ic.ac.uk' has two user disks: `/dev/dsk/2s0'
and `/dev/dsk/5s0'.  These are accessed as `/home/dylan/dk2' and
`/home/dylan/dk5' respectively.  Since `/home' is already an automount
point, this naming is achieved with the following map entries:

     dylan        type:=auto;fs:=${map};pref:=${key}/
     dylan/dk2    type:=ufs;dev:=/dev/dsk/2s0
     dylan/dk5    type:=ufs;dev:=/dev/dsk/5s0

Direct Automount Filesystem (`type:=direct')
============================================

   The "direct" filesystem is almost identical to the automount
filesystem.  Instead of appearing to be a directory of mount points, it
appears as a symbolic link to a mounted filesystem.  The mount is done
at the time the link is accessed.  See Automount Filesystem for a
list of required options.

   Direct automount points are created by specifying the `direct'
filesystem type on the command line:

     amd ... /usr/man auto.direct -type:=direct

   where `auto.direct' would contain an entry such as:

     usr/man    -type:=nfs;rfs:=/usr/man \
                rhost:=man-server1  rhost:=man-server2

   In this example, `man-server1' and `man-server2' are file servers
which export copies of the manual pages.  Note that the key which is
looked up is the name of the automount point without the leading `/'.

Union Filesystem (`type:=union')
================================

   The "union" filesystem type allows the contents of several
directories to be merged and made visible in a single directory.  This
can be used to overcome one of the major limitations of the Unix mount
mechanism which only allows complete directories to be mounted.

   For example, supposing `/tmp' and `/var/tmp' were to be merged into
a new directory called `/mtmp', with files in `/var/tmp' taking
precedence.  The following command could be used to achieve this effect:

     amd ... /mtmp union:/tmp:/var/tmp -type:=union

   Currently, the unioned directories must *not* be automounted.  That
would cause a deadlock.  This seriously limits the current usefulness of
this filesystem type and the problem will be addressed in a future
release of Amd.

   Files created in the union directory are actually created in the last
named directory.  This is done by creating a wildcard entry which points
to the correct directory.  The wildcard entry is visible if the union
directory is listed, so allowing you to see which directory has
priority.

   The files visible in the union directory are computed at the time
Amd is started, and are not kept uptodate with respect to the
underlying directories.  Similarly, if a link is removed, for example
with the `rm' command, it will be lost forever.

Error Filesystem (`type:=error')
================================

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

   The error filesystem is not directly accessible.

Top-level Filesystem (`type:=toplvl')
=====================================

   The "toplvl" filesystems is derived from the `auto' filesystem and
is used to mount the top-level automount nodes.  Requests of this type
are automatically generated from the command line arguments and can
also be passed in by using the "-M" option of the "Amq" command.

Root Filesystem
===============

   The "root" (`type:=root') filesystem type acts as an internal
placeholder onto which Amd can pin `toplvl' mounts.  Only one node of
this type need ever exist and one is created automatically during
startup.  The effect of creating a second root node is undefined.

Inheritance Filesystem
======================

   The "inheritance" (`type:=inherit') filesystem is not directly
accessible.  Instead, internal mount nodes of this type are
automatically generated when Amd is started with the "-r" option.  At
this time the system mount table is scanned to locate any filesystems
which are already mounted.  If any reference to these filesystems is
made through Amd then instead of attempting to mount it, Amd simulates
the mount and "inherits" the filesystem.  This allows a new version of
Amd to be installed on a live system simply by killing the old daemon
with `SIGTERM' and starting the new one.

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

Run-time Administration
***********************

Starting Amd
============

   Amd is best started from `/etc/rc.local':

     if [ -f /etc/amd.start ]; then
             sh /etc/amd.start; (echo -n ' amd')      >/dev/console
     fi

The shell script, `amd.start', contains:

     #!/bin/sh -
     PATH=/etc:/bin:/usr/bin:/usr/ucb:$PATH export PATH

     #
     # Either name of logfile or "syslog"
     #
     LOGFILE=syslog
     #LOGFILE=/var/log/amd

     #
     # 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/sbin
     #
     # -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

   If the list of automount points and maps is contained in a file or
NIS map it is easily incorporated onto the command line:

     ...
     eval ./amd -r $dmn -w 240 -l "$LOGFILE" `ypcat -k auto.master`

Stopping Amd
============

   Amd stops in response to two signals.

`SIGTERM'
     causes the top-level automount points to be unmounted and then Amd
     to exit.  Any automounted filesystems are left mounted.  They can
     be recovered by restarting Amd with the "-r" command line option.

`SIGINT'
     causes Amd to attempt to unmount any filesystems which it has
     automounted, in addition to the actions of `SIGTERM'.  This signal
     is primarly used for debugging.

   Actions taken for other signals are undefined.

Controlling Amd
===============

   It is sometimes desirable or necessary to exercise external control
over some of Amd's internal state.  To support this requirement, Amd
implements an RPC interface which is used by the "Amq" program.  A
variety of information is available.

   Amq generally applies an operation, specified by a single letter
option, to a list of mount points.  The default operation is to obtain
statistics about each mount point.  This is similar to the output shown
above but includes information about the number and type of accesses to
each mount point.

Amq default information
-----------------------

   With no arguments, "Amq" obtains a brief list of all existing mounts
created by Amd.  This is different from the list displayed by df(1)
since the latter only includes system mount points.

The output from this option includes the following information:

   * the automount point,

   * the filesystem type,

   * the mount map or mount information,

   * the internal, or system mount point.

For example:

     /            root   "root"                    sky:(pid75)
     /homes       toplvl /usr/local/etc/amd.homes  /homes
     /home        toplvl /usr/local/etc/amd.home   /home
     /homes/jsp   nfs    charm:/home/charm         /a/charm/home/charm/jsp
     /homes/phjk  nfs    toytown:/home/toytown     /a/toytown/home/toytown/ai/phjk

If an argument is given then statistics for that volume name will be
output.  For example:

     What            Uid   Getattr Lookup RdDir   RdLnk   Statfs Mounted@
     /homes          0     1196    512    22      0       30     90/09/14 12:32:55
     /homes/jsp      0     0       0      0       1180    0      90/10/13 12:56:58

`What'
     the volume name.

`Uid'
     ignored.

`Getattr'
     the count of NFS "getattr" requests on this node.  This should
     only be non-zero for directory nodes.

`Lookup'
     the count of NFS "lookup" requests on this node.  This should only
     be non-zero for directory nodes.

`RdDir'
     the count of NFS "readdir" requests on this node.  This should only
     be non-zero for directory nodes.

`RdLnk'
     the count of NFS "readlink" requests on this node.  This should be
     zero for directory nodes.

`Statfs'
     the could of NFS "statfs" requests on this node.  This should only
     be non-zero for top-level automount points.

`Mounted@'
     the date and time the volume name was first referenced.

Amq -f option
-------------

   The "-f" option causes Amd to flush the internal mount map cache.
This is useful for Hesiod maps since Amd will not automatically notice
when they have been updated.  The map cache can also be synchronised
with the map source by using the `sync' option (see Automount Filesystem.).

Amq -h option
-------------

   By default the local host is used.  In an HP-UX cluster the root
server is used since that is the only place in the cluster where Amd
will be running.  To query Amd on another host the "-h" option should
be used.

Amq -m option
-------------

   The "-m" option displays similar information about mounted
filesystems, rather than automount points.  The output includes the
following information:

   * the mount information,

   * the mount point,

   * the filesystem type,

   * the number of references to this filesystem,

   * the server hostname,

   * the state of the file server,

   * any error which has occured.

   For example:

     "root"           truth:(pid602)     root   1 localhost is up
     hesiod.home      /home              toplvl 1 localhost is up
     hesiod.vol       /vol               toplvl 1 localhost is up
     hesiod.homes     /homes             toplvl 1 localhost is up
     amy:/home/amy    /a/amy/home/amy    nfs    5 amy is up
     swan:/home/swan  /a/swan/home/swan  nfs    0 swan is up (Permission denied)
     ex:/home/ex      /a/ex/home/ex      nfs    0 ex is down

   When the reference count is zero the filesystem is not mounted but
the mount point and server information is still being maintained by Amd.

Amq -M option
-------------

   The "-M" option passes a new map entry to Amd and waits for it to be
evaluated, possibly causing a mount.  For example, the following
command would cause `/home/toytown' on host `toytown' to be mounted
locally on `/mnt/toytown'.

     amq -M '/mnt/toytown type:=nfs;rfs:=/home/toytown;rhost:=toytown;fs:=${key}'

   Amd applies some simple security checks before allowing this
operation.  The check tests whether the incoming request is from a
privileged UDP port on the local machine.  "Permission denied" is
returned if the check fails.

   A future release of Amd will include code to allow the mount(8)
command to mount automount points:

     mount -t amd /vol hesiod.vol

   This will then allow Amd to be controlled from the standard system
filesystem mount list.

Amq -s option
-------------

   The "-s" option displays global statistics.  If any other options
are specified or any filesystems named then this option is ignored.
For example:

     requests  stale     mount     mount     unmount
     deferred  fhandles  ok        failed    failed
     1054      1         487       290       7017

`Deferred requests'
     are those for which an immediate reply could not be constructed.
     For example, this would happen if a background mount was required.

`Stale filehandles'
     counts the number of times the kernel passes a stale filehandle to
     Amd.  Large numbers indicate problems.

`Mount ok'
     counts the number of automounts which were successful.

`Mount failed'
     counts the number of automounts which failed.

`Unmount failed'
     counts the number of times a filesystem could not be unmounted.
     Very large numbers here indicate that the time between unmount
     attempts should be increased.

Amq -u option
-------------

   The "-u" option causes the time-to-live interval of the named mount
points to be expired, thus causing an unmount attempt.  This is the only
safe way to unmount an automounted filesystem.  It is not possible to
unmount a filesystem which has been mounted with the `nounmount' flag.

Amq -v option
-------------

   The "-v" option displays the version of Amd in a similar way to
Amd's "-v" option.

Other Amq options
-----------------

   Three other operations are implemented.  These modify the state of
Amd as a whole, rather than any particular filesystem.  The "-l", "-x"
and "-D" options have exactly the same effect as Amd's corresponding
command line options.  The "-l" option is rejected by Amd in the
current version for obvious security reasons.  When Amd receives a
"-x"flag it limits the log options being modified to those which were
not enabled at startup.  This prevents a user turning *off* any logging
option which was specified at startup, though any which have been
turned off since then can still be turned off.  The "-D" option has a
similar behaviour.

FSinfo
******

FSinfo overview
===============

   FSinfo is a filesystem management tool.  It has been designed to
work with Amd to help system administrators keep track of the ever
increasing filesystem namespace under their control.

   The purpose of FSinfo is to generate all the important standard
filesystem data files from a single set of input data.  Starting with a
single data source guarantees that all the generated files are
self-consistent.  One of the possible output data formats is a set of
Amd maps which can be used amongst the set of hosts described in the
input data.

   FSinfo implements a declarative language.  This language is
specifically designed for describing filesystem namespace and physical
layouts.  The basic declaration defines a mounted filesystem including
its device name, mount point, and all the volumes and access
permissions.  FSinfo reads this information and builds an internal map
of the entire network of hosts.  Using this map, many different data
formats can be produced including `/etc/fstab', `/etc/exports', Amd
mount maps and `/etc/bootparams'.

Using FSinfo
============

   The basic strategy when using FSinfo is to gather all the
information about all disks on all machines into one set of
declarations.  For each machine being managed, the following data is
required:

   * Hostname

   * List of all filesystems and, optionally, their mount points.

   * Names of volumes stored on each filesystem.

   * NFS export information for each volume.

   * The list of static filesystem mounts.

   The following information can also be entered into the same
configuration files so that all data can be kept in one place.

   * List of network interfaces

   * IP address of each interface

   * Hardware address of each interface

   * Dumpset to which each filesystem belongs

   * and more ...

   To generate Amd mount maps, the automount tree must also be defined
(see FSinfo automount definitions.).  This will have been designed
at the time the volume names were allocated.  Some volume names will
not be automounted, so FSinfo needs an explicit list of which volumes
should be automounted.

   Hostnames are required at several places in the FSinfo language.  It
is important to stick to either fully qualified names or unqualified
names.  Using a mixture of the two will inevitably result in confusion.

   Sometimes volumes need to be referenced which are not defined in the
set of hosts being managed with FSinfo.  The required action is to add a
dummy set of definitions for the host and volume names required.  Since
the files generated for those particular hosts will not be used on them,
the exact values used is not critical.

FSinfo grammar
==============

   FSinfo has a relatively simple grammar.  Distinct syntactic
constructs exist for each of the different types of data, though they
share a common flavour.  Several conventions are used in the grammar
fragments below.

   The notation, list(xxx), indicates a list of zero or more xxx's.
The notation, opt(xxx), indicates zero or one xxx.  Items in double
quotes, eg "host", represent input tokens.  Items in angle brackets, eg
<HOSTNAME>, represent strings in the input.  Strings need not be in
double quotes, except to differentiate them from reserved words.
Quoted strings may include the usual set of C "\" escape sequences with
one exception: a backslash-newline-whitespace sequence is squashed into
a single space character.  To defeat this feature, put a further
backslash at the start of the second line.

   At the outermost level of the grammar, the input consists of a
sequence of host and automount declarations.  These declarations are
all parsed before they are analyzed.  This means they can appear in any
order and cyclic host references are possible.

     fsinfo      : list(fsinfo_attr) ;

     fsinfo_attr : host | automount ;

FSinfo host definitions
=======================

   A host declaration consists of three parts: a set of machine
attribute data, a list of filesystems physically attached to the
machine, and a list of additional statically mounted filesystems.

     host        : "host" host_data list(filesystem) list(mount) ;

   Each host must be declared in this way exactly once.  Such things as
the hardware address, the architecture and operating system types and
the cluster name are all specified within the "host data".

   All the disks the machine has should then be described in the "list
of filesystems".  When describing disks, you can specify what "volname"
the disk/partition should have and all such entries are built up into a
dictionary which can then be used for building the automounter maps.

   The "list of mounts" specifies all the filesystems that should be
statically mounted on the machine.

FSinfo host attributes
======================

   The host data, "host_data", always includes the "hostname".  In
addition, several other host attributes can be given.

     host_data   : <HOSTNAME>
                 | "{" list(host_attrs) "}" <HOSTNAME>
                 ;

     host_attrs  : host_attr "=" <STRING>
                 | netif
                 ;

     host_attr   : "config"
                 | "arch"
                 | "os"
                 | "cluster"
                 ;

   The "hostname" is, typically, the fully qualified hostname of the
machine.

   Examples:

     host dylan.doc.ic.ac.uk

     host {
         os = hpux
         arch = hp300
     } dougal.doc.ic.ac.uk

   The options that can be given as host attributes are shown below.