This is Info file amdref.info, produced by Makeinfo-1.55 from the input file /usr/src/usr.sbin/amd/doc/amdref.texinfo.  File: amdref.info, Node: Amd Command Line Options, Next: Filesystem Types, Prev: Mount Maps, Up: Top 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--*note 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. *Note 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. * Menu: * -a Option:: Automount directory. * -c Option:: Cache timeout interval. * -d Option:: Domain name. * -k Option:: Kernel architecture. * -l Option:: Log file. * -n Option:: Hostname normalisation. * -p Option:: Output process id. * -r Option:: Restart existing mounts. * -t Option:: Kernel RPC timeout. * -v Option:: Version information. * -w Option:: Wait interval after failed unmount. * -x Option:: Log options. * -y Option:: NIS domain. * -C-Option:: Cluster name. * -D-Option:: Debug flags.  File: amdref.info, Node: -a Option, Next: -c Option, Prev: Amd Command Line Options, Up: Amd Command Line Options `-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 ...  File: amdref.info, Node: -c Option, Next: -d Option, Prev: -a Option, Up: Amd Command Line Options `-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).  File: amdref.info, Node: -d Option, Next: -k Option, Prev: -c Option, Up: Amd Command Line Options `-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 ...  File: amdref.info, Node: -k Option, Next: -l Option, Prev: -d Option, Up: Amd Command Line Options `-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` ...  File: amdref.info, Node: -l Option, Next: -n Option, Prev: -k Option, Up: Amd Command Line Options `-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 ...  File: amdref.info, Node: -n Option, Next: -p Option, Prev: -l Option, Up: Amd Command Line Options `-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.  File: amdref.info, Node: -p Option, Next: -r Option, Prev: -n Option, Up: Amd Command Line Options `-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.  File: amdref.info, Node: -r Option, Next: -t Option, Prev: -p Option, Up: Amd Command Line Options `-r' ==== Tells Amd to restart existing mounts (*note Inheritance Filesystem::.).  File: amdref.info, Node: -t Option, Next: -v Option, Prev: -r Option, Up: Amd Command Line Options `-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.  File: amdref.info, Node: -v Option, Next: -w Option, Prev: -t Option, Up: Amd Command Line Options `-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 (*note Supported Machine Architectures::.), operating system (*note Supported Operating Systems::.) and byte ordering are also printed as they appear in the `${os}', `${arch}' and `${byte}' variables.  File: amdref.info, Node: -w Option, Next: -x Option, Prev: -v Option, Up: Amd Command Line Options `-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).  File: amdref.info, Node: -x Option, Next: -y Option, Prev: -w Option, Up: Amd Command Line Options `-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.  File: amdref.info, Node: -y Option, Next: -C-Option, Prev: -x Option, Up: Amd 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.  File: amdref.info, Node: -C-Option, Next: -D-Option, Prev: -y Option, Up: Amd Command Line Options `-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` ...  File: amdref.info, Node: -D-Option, Prev: -C-Option, Up: Amd Command Line Options `-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.  File: amdref.info, Node: Filesystem Types, Next: Run-time Administration, Prev: Amd Command Line Options, Up: Top 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. * Menu: * Network Filesystem:: A single NFS filesystem. * Network Host Filesystem:: NFS mount a host's entire export tree. * Network Filesystem Group:: An atomic group of NFS filesystems. * Unix Filesystem:: Native disk filesystem. * Program Filesystem:: Generic Program mounts. * Symbolic Link Filesystem:: Local link referencing existing filesystem. * Symbolic Link Filesystem II:: More on referencing existing filesystems. * Automount Filesystem:: * Direct Automount Filesystem:: * Union Filesystem:: * Error Filesystem:: * Top-level Filesystem:: * Root Filesystem:: * Inheritance Filesystem::  File: amdref.info, Node: Network Filesystem, Next: Network Host Filesystem, Prev: Filesystem Types, Up: Filesystem Types 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.  File: amdref.info, Node: Network Host Filesystem, Next: Network Filesystem Group, Prev: Network Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Network Filesystem Group, Next: Unix Filesystem, Prev: Network Host Filesystem, Up: Filesystem Types 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'.  File: amdref.info, Node: Unix Filesystem, Next: Program Filesystem, Prev: Network Filesystem Group, Up: Filesystem Types 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  File: amdref.info, Node: Program Filesystem, Next: Symbolic Link Filesystem, Prev: Unix Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Symbolic Link Filesystem, Next: Symbolic Link Filesystem II, Prev: Program Filesystem, Up: Filesystem Types 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'.  File: amdref.info, Node: Symbolic Link Filesystem II, Next: Automount Filesystem, Prev: Symbolic Link Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Automount Filesystem, Next: Direct Automount Filesystem, Prev: Symbolic Link Filesystem II, Up: Filesystem Types 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  File: amdref.info, Node: Direct Automount Filesystem, Next: Union Filesystem, Prev: Automount Filesystem, Up: Filesystem Types 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. *Note 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 `/'.  File: amdref.info, Node: Union Filesystem, Next: Error Filesystem, Prev: Direct Automount Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Error Filesystem, Next: Top-level Filesystem, Prev: Union Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Top-level Filesystem, Next: Root Filesystem, Prev: Error Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Root Filesystem, Next: Inheritance Filesystem, Prev: Top-level Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Inheritance Filesystem, Prev: Root Filesystem, Up: Filesystem Types 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.  File: amdref.info, Node: Run-time Administration, Next: FSinfo, Prev: Filesystem Types, Up: Top Run-time Administration *********************** * Menu: * Starting Amd:: * Stopping Amd:: * Controlling Amd::  File: amdref.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': 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`  File: amdref.info, Node: Stopping Amd, Next: Controlling 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 primarly used for debugging. Actions taken for other signals are undefined.  File: amdref.info, Node: Controlling Amd, Prev: Stopping 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 behaviour. * Amq -f option:: Flushing the map cache. * Amq -h option:: Controlling a non-local host. * Amq -m option:: Obtaining mount statistics. * Amq -M-option:: Mounting a volume. * Amq -s option:: Obtaining global statistics. * Amq -u option:: Forcing volumes to time out. * Amq -v option:: Version information. * Other Amq options:: Three other special options.  File: amdref.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 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.  File: amdref.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 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 (*note Automount Filesystem::.).  File: amdref.info, Node: Amq -h option, Next: Amq -m 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: amdref.info, Node: Amq -m option, Next: Amq -M-option, Prev: Amq -h 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 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.  File: amdref.info, Node: Amq -M-option, Next: Amq -s option, Prev: Amq -m option, Up: Controlling 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.  File: amdref.info, Node: Amq -s option, Next: Amq -u option, Prev: Amq -M-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: amdref.info, Node: Amq -u option, Next: Amq -v option, Prev: Amq -s 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: amdref.info, Node: Amq -v option, Next: Other Amq options, 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: amdref.info, Node: Other Amq options, Prev: Amq -v option, Up: Controlling Amd 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.  File: amdref.info, Node: FSinfo, Next: Examples, Prev: Run-time Administration, Up: Top 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: amdref.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: amdref.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: amdref.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 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 , 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: amdref.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: amdref.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 : | "{" list(host_attrs) "}" ; host_attrs : host_attr "=" | 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: * netif Option: FSinfo host netif: * config Option: FSinfo host config: * arch Option: FSinfo host arch: * os Option: FSinfo host os: * cluster Option: FSinfo host cluster: