This is am-utils.info, produced by makeinfo version 4.0b from
am-utils.texi.

START-INFO-DIR-ENTRY
* Am-utils: (am-utils).          The Amd automounter suite of utilities
END-INFO-DIR-ENTRY


File: am-utils.info,  Node: selectors_in_defaults Parameter,  Next: show_statfs_entries Parameter,  Prev: restart_mounts Parameter,  Up: Global Parameters

selectors_in_defaults Parameter
-------------------------------

   (type=boolean, default=`no').  If `yes', then the `/defaults' entry
of maps will search for and process any selectors before setting
defaults for all other keys in that map.  Useful when you want to set
different options for a complete map based on some parameters.  For
example, you may want to better the NFS performance over slow
slip-based networks as follows:

     /defaults \
         wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \
         wire!=slip-net;opts:=intr,rsize=8192,wsize=8192

   Deprecated form: selectors_on_default.


File: am-utils.info,  Node: show_statfs_entries Parameter,  Next: unmount_on_exit Parameter,  Prev: selectors_in_defaults Parameter,  Up: Global Parameters

show_statfs_entries Parameter
-----------------------------

   (type=boolean), default=`no').  If `yes', then all maps which are
browsable will also show the number of entries (keys) they have when
df(1) runs. (This is accomplished by returning non-zero values to the
statfs(2) system call).


File: am-utils.info,  Node: unmount_on_exit Parameter,  Next: vendor Parameter,  Prev: show_statfs_entries Parameter,  Up: Global Parameters

unmount_on_exit Parameter
-------------------------

   (type=boolean), default=`no').  If `yes', then Amd will attempt to
unmount all file systems which it knows about.  Normally it leaves all
(esp. NFS) mounted file systems intact.  Note that Amd does not know
about file systems mounted before it starts up, unless the
`restart_mounts' option is used (*note restart_mounts Parameter::).


File: am-utils.info,  Node: vendor Parameter,  Prev: unmount_on_exit Parameter,  Up: Global Parameters

vendor Parameter
----------------

   (type=string, default to compiled in value).  The name of the vendor
of the operating system.  Overrides the compiled-in vendor name.  Useful
when the compiled-in name is not desired.  For example, most Intel based
systems set the vendor name to `unknown', but you can set it to
`redhat'.


File: am-utils.info,  Node: Regular Map Parameters,  Next: amd.conf Examples,  Prev: Global Parameters,  Up: Amd Configuration File

Regular Map Parameters
======================

   The following parameters are applicable only to regular map sections.

* Menu:

* map_name Parameter::
* tag Parameter::


File: am-utils.info,  Node: map_name Parameter,  Next: tag Parameter,  Prev: Regular Map Parameters,  Up: Regular Map Parameters

map_name Parameter
------------------

   (type=string, must be specified).  Name of the map where the keys are
located.


File: am-utils.info,  Node: tag Parameter,  Prev: map_name Parameter,  Up: Regular Map Parameters

tag Parameter
-------------

   (type=string, default no tag).  Each map entry in the configuration
file can be tagged.  If no tag is specified, that map section will
always be processed by Amd.  If it is specified, then Amd will process
the map if the `-T' option was given to Amd, and the value given to that
command-line option matches that in the map section.


File: am-utils.info,  Node: amd.conf Examples,  Prev: Regular Map Parameters,  Up: Amd Configuration File

amd.conf Examples
=================

   The following is the actual `amd.conf' file I use at the Computer
Science Department of Columbia University.

     # GLOBAL OPTIONS SECTION
     [ global ]
     normalize_hostnames =    no
     print_pid =              no
     #pid_file =              /var/run/amd.pid
     restart_mounts =         yes
     #unmount_on_exit =       yes
     auto_dir =               /n
     log_file =               /var/log/amd
     log_options =            all
     #debug_options =         all
     plock =                  no
     selectors_in_defaults =  yes
     # config.guess picks up "sunos5" and I don't want to edit my maps yet
     os =                     sos5
     # if you print_version after setting up "os", it will show it.
     print_version =          no
     map_type =               file
     search_path =            /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib
     browsable_dirs =         yes
     fully_qualified_hosts =  no
     
     # DEFINE AN AMD MOUNT POINT
     [ /u ]
     map_name =               amd.u
     
     [ /proj ]
     map_name =               amd.proj
     
     [ /src ]
     map_name =               amd.src
     
     [ /misc ]
     map_name =               amd.misc
     
     [ /import ]
     map_name =               amd.import
     
     [ /tftpboot/.amd ]
     tag =                    tftpboot
     map_name =               amd.tftpboot


File: am-utils.info,  Node: Run-time Administration,  Next: FSinfo,  Prev: Amd Configuration File,  Up: Top

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

* Menu:

* Starting Amd::
* Stopping Amd::
* Restarting Amd::
* Controlling Amd::


File: am-utils.info,  Node: Starting Amd,  Next: Stopping Amd,  Prev: Run-time Administration,  Up: Run-time Administration

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

   Amd is best started from `/etc/rc.local' on BSD systems, or from the
appropriate start-level script in `/etc/init.d' on System V systems.

     if [ -f /usr/local/sbin/ctl-amd ]; then
         /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console
     fi

The shell script, `ctl-amd' is used to start, stop, or restart Amd.  It
is a relatively generic script.  All options you want to set should not
be made in this script, but rather updated in the `amd.conf' file.
*Note Amd Configuration File::.

   If you do not wish to use an Amd configuration file, you may start
Amd manually.  For example, getting the map entries via NIS:

     amd -r -l /var/log/amd `ypcat -k auto.master`


File: am-utils.info,  Node: Stopping Amd,  Next: Restarting Amd,  Prev: Starting Amd,  Up: Run-time Administration

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 primarily used for debugging.

   Actions taken for other signals are undefined.

   The easiest and safest way to stop Amd, without having to find its
process ID by hand, is to use the `ctl-amd' script, as with:

     ctl-amd stop


File: am-utils.info,  Node: Restarting Amd,  Next: Controlling Amd,  Prev: Stopping Amd,  Up: Run-time Administration

Restarting Amd
==============

   Before Amd can be started, it is vital to ensure that no other Amd
processes are managing any of the mount points, and that the previous
process(es) have terminated cleanly.  When a terminating signal is set
to Amd, the automounter does _not_ terminate right then.  Rather, it
starts by unmounting all of its managed mount mounts in the background,
and then terminates.  It usually takes a few seconds for this process
to happen, but it can take an arbitrarily longer time.  If two or more
Amd processes attempt to manage the same mount point, it usually will
result in a system lockup.

   The easiest and safest way to restart Amd, without having to find
its process ID by hand, sending it the `SIGTERM' signal, waiting for Amd
to die cleanly, and verifying so, is to use the `ctl-amd' script, as
with:

     ctl-amd restart

   The script will locate the process ID of Amd, kill it, and wait for
it to die cleanly before starting a new instance of the automounter.
`ctl-amd' will wait for a total of 30 seconds for Amd to die, and will
check once every 5 seconds if it had.


File: am-utils.info,  Node: Controlling Amd,  Prev: Restarting Amd,  Up: Run-time Administration

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.

* Menu:

* Amq default::       Default command behavior.
* Amq -f option::     Flushing the map cache.
* Amq -h option::     Controlling a non-local host.
* Amq -H-option::     Print help message.
* Amq -l option::     Controlling the log file.
* Amq -m option::     Obtaining mount statistics.
* Amq -p option::     Getting Amd's process ID.
* Amq -P-option::     Contacting alternate Amd processes.
* Amq -s option::     Obtaining global statistics.
* Amq -T option::     Use TCP transport.
* Amq -U-option::     Use UDP transport.
* Amq -u option::     Forcing volumes to time out.
* Amq -v option::     Version information.
* Amq -w option::     Print Amd current working directory.
* Other Amq options:: Three other special options.


File: am-utils.info,  Node: Amq default,  Next: Amq -f option,  Prev: Controlling Amd,  Up: Controlling Amd

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 count 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.


File: am-utils.info,  Node: Amq -f option,  Next: Amq -h option,  Prev: Amq default,  Up: Controlling Amd

Amq `-f' option
---------------

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


File: am-utils.info,  Node: Amq -h option,  Next: Amq -H-option,  Prev: Amq -f option,  Up: Controlling Amd

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.


File: am-utils.info,  Node: Amq -H-option,  Next: Amq -l option,  Prev: Amq -h option,  Up: Controlling Amd

Amq `-H' option
---------------

   Print a brief help and usage string.


File: am-utils.info,  Node: Amq -l option,  Next: Amq -m option,  Prev: Amq -H-option,  Up: Controlling Amd

Amq `-l' option
---------------

   Tell Amd to use log_file as the log file name.  For security
reasons, this _must_ be the same log file which Amd used when started.
This option is therefore only useful to refresh Amd's open file handle
on the log file, so that it can be rotated and compressed via daily
cron jobs.


File: am-utils.info,  Node: Amq -m option,  Next: Amq -p option,  Prev: Amq -l option,  Up: Controlling Amd

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 occurred.

   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.


File: am-utils.info,  Node: Amq -p option,  Next: Amq -P-option,  Prev: Amq -m option,  Up: Controlling Amd

Amq `-p' option
---------------

   Return the process ID of the remote or locally running Amd.  Useful
when you need to send a signal to the local Amd process, and would
rather not have to search through the process table.  This option is
used in the `ctl-amd' script.


File: am-utils.info,  Node: Amq -P-option,  Next: Amq -s option,  Prev: Amq -p option,  Up: Controlling Amd

Amq `-P' option
---------------

   Contact an alternate running Amd that had registered itself on a
different RPC PROGRAM_NUMBER and apply all other operations to that
instance of the automounter.  This is useful when you run multiple
copies of Amd, and need to manage each one separately.  If not
specified, Amq will use the default program number for Amd, 300019.
For security reasons, the only alternate program numbers Amd can use
range from 300019 to 300029, inclusive.

   For example, to kill an alternate running Amd:

     kill `amq -p -P 300020`


File: am-utils.info,  Node: Amq -s option,  Next: Amq -T option,  Prev: Amq -P-option,  Up: Controlling Amd

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.


File: am-utils.info,  Node: Amq -T option,  Next: Amq -U-option,  Prev: Amq -s option,  Up: Controlling Amd

Amq `-T' option
---------------

   The `-T' option causes the Amq to contact Amd using the TCP
transport only (connection oriented).  Normally, Amq will use TCP
first, and if that failed, will try UDP.


File: am-utils.info,  Node: Amq -U-option,  Next: Amq -u option,  Prev: Amq -T option,  Up: Controlling Amd

Amq `-U' option
---------------

   The `-U' option causes the Amq to contact Amd using the UDP
transport only (connectionless).  Normally, Amq will use TCP first, and
if that failed, will try UDP.


File: am-utils.info,  Node: Amq -u option,  Next: Amq -v option,  Prev: Amq -U-option,  Up: Controlling Amd

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.


File: am-utils.info,  Node: Amq -v option,  Next: Amq -w option,  Prev: Amq -u option,  Up: Controlling Amd

Amq `-v' option
---------------

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


File: am-utils.info,  Node: Amq -w option,  Next: Other Amq options,  Prev: Amq -v option,  Up: Controlling Amd

Amq `-w' option
---------------

   The `-w' option translates a full pathname as returned by getpwd(3)
into a short Amd pathname that goes through its mount points.  This
option requires that Amd is running.


File: am-utils.info,  Node: Other Amq options,  Prev: Amq -w option,  Up: Controlling Amd

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

   Two other operations are implemented.  These modify the state of Amd
as a whole, rather than any particular filesystem.  The `-x' and `-D'
options have exactly the same effect as Amd's corresponding command
line options.

   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 on since then can still be turned
off.  The `-D' option has a similar behavior.


File: am-utils.info,  Node: FSinfo,  Next: Hlfsd,  Prev: Run-time Administration,  Up: Top

FSinfo
******

   XXX: this chapter should be reviewed by someone knowledgeable with
fsinfo.

* Menu:

* FSinfo Overview::                 Introduction to FSinfo.
* Using FSinfo::                    Basic concepts.
* FSinfo Grammar::                  Language syntax, semantics and examples.
* FSinfo host definitions::         Defining a new host.
* FSinfo host attributes::          Definable host attributes.
* FSinfo filesystems::              Defining locally attached filesystems.
* FSinfo static mounts::            Defining additional static mounts.
* FSinfo automount definitions::
* FSinfo Command Line Options::
* FSinfo errors::


File: am-utils.info,  Node: FSinfo Overview,  Next: Using FSinfo,  Prev: FSinfo,  Up: 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'.


File: am-utils.info,  Node: Using FSinfo,  Next: FSinfo Grammar,  Prev: FSinfo Overview,  Up: FSinfo

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
(*note 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.


File: am-utils.info,  Node: FSinfo Grammar,  Next: FSinfo host definitions,  Prev: Using FSinfo,  Up: FSinfo

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 flavor.  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 ;

* Menu:

* FSinfo host definitions::
* FSinfo automount definitions::


File: am-utils.info,  Node: FSinfo host definitions,  Next: FSinfo host attributes,  Prev: FSinfo Grammar,  Up: FSinfo

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.

* Menu:

* FSinfo host attributes::
* FSinfo filesystems::
* FSinfo static mounts::


File: am-utils.info,  Node: FSinfo host attributes,  Next: FSinfo filesystems,  Prev: FSinfo host definitions,  Up: FSinfo host definitions

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.

* Menu:

* FSinfo netif Option::         FSinfo host netif.
* FSinfo config Option::        FSinfo host config.
* FSinfo arch Option::          FSinfo host arch.
* FSinfo os Option::            FSinfo host os.
* FSinfo cluster Option::       FSinfo host cluster.


File: am-utils.info,  Node: FSinfo netif Option,  Next: FSinfo config Option,  Up: FSinfo host attributes

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 { }


File: am-utils.info,  Node: FSinfo config Option,  Next: FSinfo arch Option,  Prev: FSinfo netif Option,  Up: FSinfo host attributes

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.


File: am-utils.info,  Node: FSinfo arch Option,  Next: FSinfo os Option,  Prev: FSinfo config Option,  Up: FSinfo host attributes

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.


File: am-utils.info,  Node: FSinfo os Option,  Next: FSinfo cluster Option,  Prev: FSinfo arch Option,  Up: FSinfo host attributes

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.


File: am-utils.info,  Node: FSinfo cluster Option,  Prev: FSinfo os Option,  Up: FSinfo host attributes

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.


File: am-utils.info,  Node: FSinfo filesystems,  Next: FSinfo static mounts,  Prev: FSinfo host attributes,  Up: FSinfo host definitions

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

* Menu:

* FSinfo fstype Option::        FSinfo filesystems fstype.
* FSinfo opts Option::          FSinfo filesystems opts.
* FSinfo passno Option::        FSinfo filesystems passno.
* FSinfo freq Option::          FSinfo filesystems freq.
* FSinfo mount Option::         FSinfo filesystems mount.
* FSinfo dumpset Option::       FSinfo filesystems dumpset.
* FSinfo log Option::           FSinfo filesystems log.


File: am-utils.info,  Node: FSinfo fstype Option,  Next: FSinfo opts Option,  Up: FSinfo filesystems

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


File: am-utils.info,  Node: FSinfo opts Option,  Next: FSinfo passno Option,  Prev: FSinfo fstype Option,  Up: FSinfo filesystems

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

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

     opts = rw,nosuid,grpid


File: am-utils.info,  Node: FSinfo passno Option,  Next: FSinfo freq Option,  Prev: FSinfo opts Option,  Up: FSinfo filesystems

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


File: am-utils.info,  Node: FSinfo freq Option,  Next: FSinfo mount Option,  Prev: FSinfo passno Option,  Up: FSinfo filesystems

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

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

   Example:

     freq = 3


File: am-utils.info,  Node: FSinfo mount Option,  Next: FSinfo dumpset Option,  Prev: FSinfo freq Option,  Up: FSinfo filesystems

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.


File: am-utils.info,  Node: FSinfo dumpset Option,  Next: FSinfo log Option,  Prev: FSinfo mount Option,  Up: FSinfo filesystems

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

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


File: am-utils.info,  Node: FSinfo log Option,  Prev: FSinfo dumpset Option,  Up: FSinfo filesystems

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

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


File: am-utils.info,  Node: FSinfo static mounts,  Next: FSinfo automount definitions,  Prev: FSinfo filesystems,  Up: FSinfo host definitions

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.


File: am-utils.info,  Node: FSinfo automount definitions,  Next: FSinfo Command Line Options,  Prev: FSinfo static mounts,  Up: FSinfo

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" (*note Direct
Automount Filesystem::) or "indirect" (*note 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
optimize 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 analyzed 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.


File: am-utils.info,  Node: FSinfo Command Line Options,  Next: FSinfo errors,  Prev: FSinfo automount definitions,  Up: FSinfo

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.

* Menu:

* -a FSinfo Option::    Amd automount directory:
* -b FSinfo Option::    Prefix for bootparams files.
* -d FSinfo Option::    Prefix for dumpset data files.
* -e FSinfo Option::    Prefix for exports files.
* -f FSinfo Option::    Prefix for fstab files.
* -h FSinfo Option::    Local hostname.
* -m FSinfo Option::    Prefix for automount maps.
* -q FSinfo Option::    Ultra quiet mode.
* -v FSinfo Option::    Verbose mode.
* -I FSinfo Option::    Define new #include directory.
* -D-FSinfo Option::    Define macro.
* -U FSinfo Option::    Undefine macro.


File: am-utils.info,  Node: -a FSinfo Option,  Next: -b FSinfo Option,  Prev: FSinfo Command Line Options,  Up: FSinfo Command Line Options

`-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 ...


File: am-utils.info,  Node: -b FSinfo Option,  Next: -d FSinfo Option,  Prev: -a FSinfo Option,  Up: FSinfo Command Line Options

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


File: am-utils.info,  Node: -d FSinfo Option,  Next: -e FSinfo Option,  Prev: -b FSinfo Option,  Up: FSinfo Command Line Options

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


File: am-utils.info,  Node: -e FSinfo Option,  Next: -f FSinfo Option,  Prev: -d FSinfo Option,  Up: FSinfo Command Line Options

`-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 diskfull machine and
place them into the directory `exports':

     fsinfo -e exports/ ...


File: am-utils.info,  Node: -f FSinfo Option,  Next: -h FSinfo Option,  Prev: -e FSinfo Option,  Up: FSinfo Command Line Options

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


File: am-utils.info,  Node: -h FSinfo Option,  Next: -m FSinfo Option,  Prev: -f FSinfo Option,  Up: FSinfo Command Line Options

`-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 ...


File: am-utils.info,  Node: -m FSinfo Option,  Next: -q FSinfo Option,  Prev: -h FSinfo Option,  Up: FSinfo Command Line Options

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


File: am-utils.info,  Node: -q FSinfo Option,  Next: -v FSinfo Option,  Prev: -m FSinfo Option,  Up: FSinfo Command Line Options

`-q'
----

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


File: am-utils.info,  Node: -v FSinfo Option,  Next: -D-FSinfo Option,  Prev: -q FSinfo Option,  Up: FSinfo Command Line Options

`-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.


File: am-utils.info,  Node: -D-FSinfo Option,  Next: -I FSinfo Option,  Prev: -v FSinfo Option,  Up: FSinfo Command Line Options

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

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


File: am-utils.info,  Node: -I FSinfo Option,  Next: -U FSinfo Option,  Prev: -D-FSinfo Option,  Up: FSinfo Command Line Options

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

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


File: am-utils.info,  Node: -U FSinfo Option,  Prev: -I FSinfo Option,  Up: FSinfo Command Line Options

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

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

