diff options
Diffstat (limited to 'usr.sbin/amd/doc/amdref.texinfo')
| -rw-r--r-- | usr.sbin/amd/doc/amdref.texinfo | 4554 |
1 files changed, 4554 insertions, 0 deletions
diff --git a/usr.sbin/amd/doc/amdref.texinfo b/usr.sbin/amd/doc/amdref.texinfo new file mode 100644 index 000000000000..4a6d8e944159 --- /dev/null +++ b/usr.sbin/amd/doc/amdref.texinfo @@ -0,0 +1,4554 @@ +\input texinfo @c -*-texinfo-*- +@c +@c Copyright (c) 1989 Jan-Simon Pendry +@c Copyright (c) 1989 Imperial College of Science, Technology & Medicine +@c Copyright (c) 1989 The Regents of the University of California. +@c All rights reserved. +@c +@c This code is derived from software contributed to Berkeley by +@c Jan-Simon Pendry at Imperial College, London. +@c +@c Redistribution and use in source and binary forms, with or without +@c modification, are permitted provided that the following conditions +@c are met: +@c 1. Redistributions of source code must retain the above copyright +@c notice, this list of conditions and the following disclaimer. +@c 2. Redistributions in binary form must reproduce the above copyright +@c notice, this list of conditions and the following disclaimer in the +@c documentation and/or other materials provided with the distribution. +@c 3. All advertising materials mentioning features or use of this software +@c must display the following acknowledgement: +@c This product includes software developed by the University of +@c California, Berkeley and its contributors. +@c 4. Neither the name of the University nor the names of its contributors +@c may be used to endorse or promote products derived from this software +@c without specific prior written permission. +@c +@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +@c +@c @(#)amdref.texinfo 8.1 (Berkeley) 6/6/93 +@c +@c $Id: amdref.texinfo,v 5.2.2.1 1992/02/09 15:11:50 jsp beta $ +@c +@setfilename amdref.info +@c @setfilename /usr/local/emacs/info/amd +@tex +\overfullrule=0pt +@end tex + +@settitle 4.4 BSD Automounter Reference Manual +@titlepage +@sp 6 +@center @titlefont{Amd} +@sp 2 +@center @titlefont{The 4.4 BSD Automounter} +@sp 2 +@center @titlefont{Reference Manual} +@sp 2 +@center @authorfont{Jan-Simon Pendry} +@sp +@center @i{and} +@sp +@center @authorfont{Nick Williams} +@sp 4 +@center Last updated March 1991 +@center Documentation for software revision 5.3 Alpha +@page +Copyright @copyright{} 1989 Jan-Simon Pendry +@sp -1 +Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine +@sp -1 +Copyright @copyright{} 1989 The Regents of the University of California. +@sp 0 +All Rights Reserved. +@vskip 1ex +Permission to copy this document, or any portion of it, as +necessary for use of this software is granted provided this +copyright notice and statement of permission are included. +@end titlepage +@page +@ifinfo +@node Top, License, , (DIR) + +Amd - The 4.4 BSD Automounter +***************************** + +Amd is the 4.4 BSD Automounter. This Info file describes how +to use and understand Amd. +@end ifinfo + +@menu +* License:: Explains the terms and conditions for using + and distributing Amd. +* Distrib:: How to get the latest Amd distribution. +* Intro:: An introduction to Automounting concepts. +* Overview:: An overview of Amd. +* Supported Platforms:: Machines and Systems supported by Amd. +* Mount Maps:: Details of mount maps +* Amd Command Line Options:: All the Amd command line options explained. +* Filesystem Types:: The different mount types supported by Amd. +* Run-time Administration:: How to start, stop and control Amd. +* FSinfo:: The FSinfo filesystem management tool. +* Internals:: Internals. +* Acknowledgements & Trademarks:: Legal notes. +* Examples:: Some examples showing how Amd might be used. +* Internals:: Implementation details. +* Acknowledgements & Trademarks:: + +Indexes +* Index:: An item for each concept. +@end menu + +@iftex +@unnumbered Preface + +This manual documents the use of the 4.4 BSD automounter---@i{Amd}. +This is primarily a reference manual. Unfortunately, no tutorial +exists. + +This manual comes in two forms: the published form and the Info form. +The Info form is for on-line perusal with the INFO program which is +distributed along with GNU Emacs. Both forms contain substantially the +same text and are generated from a common source file, which is +distributed with the @i{Amd} source. +@end iftex + +@node License, Distrib, Top, Top +@unnumbered License +@cindex License Information + +@i{Amd} is not in the public domain; it is copyrighted and there are +restrictions on its distribution. + +Redistribution and use in source and binary forms are permitted provided +that: (1) source distributions retain this entire copyright notice and +comment, and (2) distributions including binaries display the following +acknowledgement: ``This product includes software developed by The +University of California, Berkeley and its Contributors'' in the +documentation or other materials provided with the distribution and in +all advertising materials mentioning features or use of this software. +neither the name of the University nor the names of its Contributors may +be used to endorse or promote products derived from this software +without specific prior written permission. + +THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. + +@node Distrib, Intro, License, Top +@unnumbered Source Distribution +@cindex Source code distribution +@cindex Obtaining the source code + +If you have access to the Internet, you can get the latest distribution +version of @i{Amd} from host @file{usc.edu} using anonymous FTP. Move to +the directory @file{/pub/amd} on that host and fetch the file @file{amd.tar.Z}. + +If you are in the UK, you can get the latest distribution version of +@i{Amd} from the UKnet info-server. Start by sending email to +@file{info-server@@doc.ic.ac.uk}. + +Sites on the UK JANET network can get the latest distribution by using +anonymous NIFTP to fetch the file @samp{<AMD>amd.tar.Z} from host +@samp{uk.ac.imperial.doc.src}. + +Revision 5.2 was part of the 4.3 BSD Reno distribution. + +Revision 5.3bsdnet, a late alpha version of 5.3, was part +of the BSD network version 2 distribution + +@unnumberedsec Bug Reports +@cindex Bug reports + +Send all bug reports to @file{jsp@@doc.ic.ac.uk} quoting the details of +the release and your configuration. These can be obtained by running +the command @samp{amd -v}. + +@unnumberedsec Mailing List +@cindex Mailing list + +There is a mailing list for people interested in keeping uptodate with +developments. To subscribe, send a note to @file{amd-workers-request@@acl.lanl.gov}. + +@node Intro, Overview, Distrib, Top +@unnumbered Introduction +@cindex Introduction + +An @dfn{automounter} maintains a cache of mounted filesystems. +Filesystems are mounted on demand when they are first referenced, +and unmounted after a period of inactivity. + +@i{Amd} may be used as a replacement for Sun's automounter. The choice +of which filesystem to mount can be controlled dynamically with +@dfn{selectors}. Selectors allow decisions of the form ``hostname is +@var{this},'' or ``architecture is not @var{that}.'' Selectors may be +combined arbitrarily. @i{Amd} also supports a variety of filesystem +types, including NFS, UFS and the novel @dfn{program} filesystem. The +combination of selectors and multiple filesystem types allows identical +configuration files to be used on all machines so reducing the +administrative overhead. + +@i{Amd} ensures that it will not hang if a remote server goes down. +Moreover, @i{Amd} can determine when a remote server has become +inaccessible and then mount replacement filesystems as and when they +become available. + +@i{Amd} contains no proprietary source code and has been ported to +numerous flavours of Unix. + +@node Overview, Supported Platforms, Intro, Top +@chapter Overview + +@i{Amd} maintains a cache of mounted filesystems. Filesystems are +@dfn{demand-mounted} when they are first referenced, and unmounted after +a period of inactivity. @i{Amd} may be used as a replacement for Sun's +@b{automount}(8) program. It contains no proprietary source code and +has been ported to numerous flavours of Unix. @xref{Supported Operating +Systems}.@refill + +@i{Amd} was designed as the basis for experimenting with filesystem +layout and management. Although @i{Amd} has many direct applications it +is loaded with additional features which have little practical use. At +some point the infrequently used components may be removed to streamline +the production system. + +@c @i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating +@c each member of a list of possible filesystem locations in parallel. +@c @i{Amd} checks that each cached mapping remains valid. Should a mapping be +@c lost -- such as happens when a fileserver goes down -- @i{Amd} automatically +@c selects a replacement should one be available. +@c +@menu +* Fundamentals:: +* Filesystems and Volumes:: +* Volume Naming:: +* Volume Binding:: +* Operational Principles:: +* Mounting a Volume:: +* Automatic Unmounting:: +* Keep-alives:: +* Non-blocking Operation:: +@end menu + +@node Fundamentals, Filesystems and Volumes, Overview, Overview +@comment node-name, next, previous, up +@section Fundamentals +@cindex Automounter fundamentals + +The fundamental concept behind @i{Amd} is the ability to separate the +name used to refer to a file from the name used to refer to its physical +storage location. This allows the same files to be accessed with the +same name regardless of where in the network the name is used. This is +very different from placing @file{/n/hostname} in front of the pathname +since that includes location dependent information which may change if +files are moved to another machine. + +By placing the required mappings in a centrally administered database, +filesystems can be re-organised without requiring changes to +configuration files, shell scripts and so on. + +@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview +@comment node-name, next, previous, up +@section Filesystems and Volumes +@cindex Filesystem +@cindex Volume +@cindex Fileserver +@cindex sublink + +@i{Amd} views the world as a set of fileservers, each containg one or +more filesystems where each filesystem contains one or more +@dfn{volumes}. Here the term @dfn{volume} is used to refer to a +coherent set of files such as a user's home directory or a @TeX{} +distribution.@refill + +In order to access the contents of a volume, @i{Amd} must be told in +which filesystem the volume resides and which host owns the filesystem. +By default the host is assumed to be local and the volume is assumed to +be the entire filesystem. If a filesystem contains more than one +volume, then a @dfn{sublink} is used to refer to the sub-directory +within the filesystem where the volume can be found. + +@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview +@comment node-name, next, previous, up +@section Volume Naming +@cindex Volume names +@cindex Network-wide naming +@cindex Replicated volumes +@cindex Duplicated volumes +@cindex Replacement volumes + +Volume names are defined to be unique across the entire network. A +volume name is the pathname to the volume's root as known by the users +of that volume. Since this name uniquely identifies the volume +contents, all volumes can be named and accessed from each host, subject +to administrative controls. + +Volumes may be replicated or duplicated. Replicated volumes contain +identical copies of the same data and reside at two or more locations in +the network. Each of the replicated volumes can be used +interchangeably. Duplicated volumes each have the same name but contain +different, though functionally identical, data. For example, +@samp{/vol/tex} might be the name of a @TeX{} distribution which varied +for each machine architecture.@refill + +@i{Amd} provides facilities to take advantage of both replicated and +duplicated volumes. Configuration options allow a single set of +configuration data to be shared across an entire network by taking +advantage of replicated and duplicated volumes. + +@i{Amd} can take advantage of replacement volumes by mounting them as +required should an active fileserver become unavailable. + +@node Volume Binding, Operational Principles, Volume Naming, Overview +@comment node-name, next, previous, up +@section Volume Binding +@cindex Volume binding +@cindex Unix namespace +@cindex Namespace +@cindex Binding names to filesystems + +Unix implements a namespace of hierarchically mounted filesystems. Two +forms of binding between names and files are provided. A @dfn{hard +link} completes the binding when the name is added to the filesystem. A +@dfn{soft link} delays the binding until the name is accessed. An +@dfn{automounter} adds a further form in which the binding of name to +filesystem is delayed until the name is accessed.@refill + +The target volume, in its general form, is a tuple (host, filesystem, +sublink) which can be used to name the physical location of any volume +in the network. + +When a target is referenced, @i{Amd} ignores the sublink element and +determines whether the required filesystem is already mounted. This is +done by computing the local mount point for the filesystem and checking +for an existing filesystem mounted at the same place. If such a +filesystem already exists then it is assumed to be functionally +identical to the target filesystem. By default there is a one-to-one +mapping between the pair (host, filesystem) and the local mount point so +this assumption is valid. + +@node Operational Principles, Mounting a Volume, Volume Binding, Overview +@comment node-name, next, previous, up +@section Operational Principles +@cindex Operational principles + +@i{Amd} operates by introducing new mount points into the namespace. +These are called @dfn{automount} points. The kernel sees these +automount points as NFS filesystems being served by @i{Amd}. Having +attached itself to the namespace, @i{Amd} is now able to control the +view the rest of the system has of those mount points. RPC calls are +received from the kernel one at a time. + +When a @dfn{lookup} call is received @i{Amd} checks whether the name is +already known. If it is not, the required volume is mounted. A +symbolic link pointing to the volume root is then returned. Once the +symbolic link is returned, the kernel will send all other requests +direct to the mounted filesystem. + +If a volume is not yet mounted, @i{Amd} consults a configuration +@dfn{mount-map} corresponding to the automount point. @i{Amd} then +makes a runtime decision on what and where to mount a filesystem based +on the information obtained from the map. + +@i{Amd} does not implement all the NFS requests; only those relevant +to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. +Some other calls are also implemented but most simply return an error +code; for example @dfn{mkdir} always returns ``read-only filesystem''. + +@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview +@comment node-name, next, previous, up +@section Mounting a Volume +@cindex Mounting a volume +@cindex Location lists +@cindex Alternate locations +@cindex Mount retries +@cindex Background mounts + +Each automount point has a corresponding mount map. The mount map +contains a list of key--value pairs. The key is the name of the volume +to be mounted. The value is a list of locations describing where the +filesystem is stored in the network. In the source for the map the +value would look like + +@display +location1 location2 @dots{} locationN +@end display + +@i{Amd} examines each location in turn. Each location may contain +@dfn{selectors} which control whether @i{Amd} can use that location. +For example, the location may be restricted to use by certain hosts. +Those locations which cannot be used are ignored. + +@i{Amd} attempts to mount the filesystem described by each remaining +location until a mount succeeds or @i{Amd} can no longer proceed. The +latter can occur in three ways: + +@itemize @bullet +@item +If none of the locations could be used, or if all of the locations +caused an error, then the last error is returned. + +@item +If a location could be used but was being mounted in the background then +@i{Amd} marks that mount as being ``in progress'' and continues with +the next request; no reply is sent to the kernel. + +@item +Lastly, one or more of the mounts may have been @dfn{deferred}. A mount +is deferred if extra information is required before the mount can +proceed. When the information becomes available the mount will take +place, but in the mean time no reply is sent to the kernel. If the +mount is deferred, @i{Amd} continues to try any remaining locations. +@end itemize + +Once a volume has been mounted, @i{Amd} establishes a @dfn{volume +mapping} which is used to satisfy subsequent requests.@refill + +@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview +@comment node-name, next, previous, up +@section Automatic Unmounting + +To avoid an ever increasing number of filesystem mounts, @i{Amd} removes +volume mappings which have not been used recently. A time-to-live +interval is associated with each mapping and when that expires the +mapping is removed. When the last reference to a filesystem is removed, +that filesystem is unmounted. If the unmount fails, for example the +filesystem is still busy, the mapping is re-instated and its +time-to-live interval is extended. The global default for this grace +period is controlled by the ``-w'' command-line option (@pxref{-w +Option, -w}). It is also possible to set this value on a per-mount +basis (@pxref{opts Option, opts, opts}).@refill + +Filesystems can be forcefully timed out using the @i{Amq} command. +@xref{Run-time Administration}. + +@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview +@comment node-name, next, previous, up +@section Keep-alives +@cindex Keep-alives +@cindex Server crashes +@cindex NFS ping + +Use of some filesystem types requires the presence of a server on +another machine. If a machine crashes then it is of no concern to +processes on that machine that the filesystem is unavailable. However, +to processes on a remote host using that machine as a fileserver this +event is important. This situation is most widely recognised when an +NFS server crashes and the behaviour observed on client machines is that +more and more processes hang. In order to provide the possibility of +recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some +filesystem types. Currently only NFS makes use of this service. + +The basis of the NFS keep-alive implementation is the observation that +most sites maintain replicated copies of common system data such as +manual pages, most or all programs, system source code and so on. If +one of those servers goes down it would be reasonable to mount one of +the others as a replacement. + +The first part of the process is to keep track of which fileservers are +up and which are down. @i{Amd} does this by sending RPC requests to the +servers' NFS @code{NullProc} and checking whether a reply is returned. +While the server state is uncertain the requests are re-transmitted at +three second intervals and if no reply is received after four attempts +the server is marked down. If a reply is received the fileserver is +marked up and stays in that state for 30 seconds at which time another +NFS ping is sent. + +Once a fileserver is marked down, requests continue to be sent every 30 +seconds in order to determine when the fileserver comes back up. During +this time any reference through @i{Amd} to the filesystems on that +server fail with the error ``Operation would block''. If a replacement +volume is available then it will be mounted, otherwise the error is +returned to the user. + +@c @i{Amd} keeps track of which servers are up and which are down. +@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and +@c checking whether a reply is returned. If no replies are received after a +@c short period, @i{Amd} marks the fileserver @dfn{down}. +@c RPC requests continue to be sent so that it will notice when a fileserver +@c comes back up. +@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability +@c of the NFS service that is important, not the existence of a base kernel. +@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate +@c filesystem is mounted if one is available. +@c +Although this action does not protect user files, which are unique on +the network, or processes which do not access files via @i{Amd} or +already have open files on the hung filesystem, it can prevent most new +processes from hanging. + +By default, fileserver state is not maintained for NFS/TCP mounts. The +remote fileserver is always assumed to be up. +@c +@c With a suitable combination of filesystem management and mount-maps, +@c machines can be protected against most server downtime. This can be +@c enhanced by allocating boot-servers dynamically which allows a diskless +@c workstation to be quickly restarted if necessary. Once the root filesystem +@c is mounted, @i{Amd} can be started and allowed to mount the remainder of +@c the filesystem from whichever fileservers are available. + +@node Non-blocking Operation, , Keep-alives, Overview +@comment node-name, next, previous, up +@section Non-blocking Operation +@cindex Non-blocking operation +@cindex Multiple-threaded server +@cindex RPC retries + +Since there is only one instance of @i{Amd} for each automount point, +and usually only one instance on each machine, it is important that it +is always available to service kernel calls. @i{Amd} goes to great +lengths to ensure that it does not block in a system call. As a last +resort @i{Amd} will fork before it attempts a system call that may block +indefinitely, such as mounting an NFS filesystem. Other tasks such as +obtaining filehandle information for an NFS filesystem, are done using a +purpose built non-blocking RPC library which is integrated with +@i{Amd}'s task scheduler. This library is also used to implement NFS +keep-alives (@pxref{Keep-alives}). + +Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it +to complete before replying to the kernel. However, this would cause +@i{Amd} to block waiting for a reply to be constructed. Rather than do +this, @i{Amd} simply @dfn{drops} the call under the assumption that the +kernel RPC mechanism will automatically retry the request. + +@node Supported Platforms, Mount Maps, Overview, Top +@comment node-name, next, previous, up +@chapter Supported Platforms + +@i{Amd} has been ported to a wide variety of machines and operating systems. +The table below lists those platforms supported by the current release. + +@menu +* Supported Operating Systems:: +* Supported Machine Architectures:: +@end menu + +@node Supported Operating Systems, Supported Machine Architectures, Supported Platforms, Supported Platforms +@comment node-name, next, previous, up +@section Supported Operating Systems +@cindex Operating system names +@cindex Operating systems supported by Amd +@cindex Supported operating systems + +The following operating systems are currently supported by @i{Amd}. +@i{Amd}'s conventional name for each system is given. + +@table @code +@item acis43 +4.3 BSD for IBM RT. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item aix3 +AIX 3.1. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item aux +System V for Mac-II. Contributed by Julian Onions @t{<jpo@@cs.nott.ac.uk>} +@item bsd44 +4.4 BSD. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item concentrix +Concentrix 5.0. Contributed by Sjoerd Mullender @t{<sjoerd@@cwi.nl>} +@item convex +Convex OS 7.1. Contributed by Eitan Mizrotsky @t{<eitan@@shumuji.ac.il>} +@item dgux +Data General DG/UX. Contributed by Mark Davies @t{<mark@@comp.vuw.ac.nz>} +@item fpx4 +Celerity FPX 4.1/2. Contributed by Stephen Pope @t{<scp@@grizzly.acl.lanl.gov>} +@item hcx +Harris HCX/UX. Contributed by Chris Metcalf @t{<metcalf@@masala.lcs.mit.edu>} +@item hlh42 +HLH OTS 1.@i{x} (4.2 BSD). Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item hpux +HP-UX 6.@i{x} or 7.0. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item irix +SGI Irix. Contributed by Scott R. Presnell @t{<srp@@cgl.ucsf.edu>} +@item next +Mach for NeXT. Contributed by Bill Trost @t{<trost%reed@@cse.ogi.edu>} +@item pyrOSx +Pyramid OSx. Contributed by Stefan Petri @t{<petri@@tubsibr.UUCP>} +@item riscix +Acorn RISC iX. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} +@item sos3 +SunOS 3.4 & 3.5. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item sos4 +SunOS 4.@i{x}. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@item u2_2 +Ultrix 2.2. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} +@item u3_0 +Ultrix 3. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} +@item u4_0 +Ultrix 4.0. Contributed by Chris Lindblad @t{<cjl@@ai.mit.edu>} +@item umax43 +Umax 4.3 BSD. Contributed by Sjoerd Mullender @t{<sjoerd@@cwi.nl>} +@item utek +Utek 4.0. Contributed by Bill Trost @t{<trost%reed@@cse.ogi.edu>} +@item xinu43 +mt Xinu MORE/bsd. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} +@end table + +@node Supported Machine Architectures, , Supported Operating Systems, Supported Platforms +@comment node-name, next, previous, up +@section Supported Machine Architectures +@cindex Supported machine architectures +@cindex Machine architecture names +@cindex Machine architectures supported by Amd + +@table @code +@item alliant +Alliant FX/4 +@item arm +Acorn ARM +@item aviion +Data General AViiON +@item encore +Encore +@item fps500 +FPS Model 500 +@item hp9000 +HP 9000/300 family +@item hp9k8 +HP 9000/800 family +@item ibm032 +IBM RT +@item ibm6000 +IBM RISC System/6000 +@item iris4d +SGI Iris 4D +@item macII +Apple Mac II +@item mips +MIPS RISC +@item multimax +Encore Multimax +@item orion105 +HLH Orion 1/05 +@item sun3 +Sun-3 family +@item sun4 +Sun-4 family +@item tahoe +Tahoe family +@item vax +DEC Vax +@end table + +@node Mount Maps, Amd Command Line Options, Supported Platforms, Top +@comment node-name, next, previous, up +@chapter Mount Maps +@cindex Mount maps +@cindex Automounter configuration maps +@cindex Mount information + +@i{Amd} has no built-in knowledge of machines or filesystems. +External @dfn{mount-maps} are used to provide the required information. +Specifically, @i{Amd} needs to know when and under what conditions it +should mount filesystems. + +The map entry corresponding to the requested name contains a list of +possible locations from which to resolve the request. Each location +specifies filesystem type, information required by that filesystem (for +example the block special device in the case of UFS), and some +information describing where to mount the filesystem (@pxref{fs Option}). A +location may also contain @dfn{selectors} (@pxref{Selectors}).@refill + +@menu +* Map Types:: +* Key Lookup:: +* Location Format:: +@end menu + +@node Map Types, Key Lookup, Mount Maps, Mount Maps +@comment node-name, next, previous, up +@section Map Types +@cindex Mount map types +@cindex Map types +@cindex Configuration map types +@cindex Types of mount map +@cindex Types of configuration map +@cindex Determining the map type + +A mount-map provides the run-time configuration information to @i{Amd}. +Maps can be implemented in many ways. Some of the forms supported by +@i{Amd} are regular files, ndbm databases, NIS maps the @dfn{Hesiod} +name server and even the password file. + +A mount-map @dfn{name} is a sequence of characters. When an automount +point is created a handle on the mount-map is obtained. For each map +type configured @i{Amd} attempts to reference the a map of the +appropriate type. If a map is found, @i{Amd} notes the type for future +use and deletes the reference, for example closing any open file +descriptors. The available maps are configure when @i{Amd} is built and +can be displayed by running the command @samp{amd -v}. + +By default, @i{Amd} caches data in a mode dependent on the type of map. +This is the same as specifying @samp{cache:=mapdefault} and selects a +suitable default cache mode depending on the map type. The individual +defaults are described below. The @var{cache} option can be specified +on automount points to alter the caching behaviour (@pxref{Automount +Filesystem}).@refill + +The following map types have been implemented, though some are not +available on all machines. Run the command @samp{amd -v} to obtain a +list of map types configured on your machine. + +@menu +* File maps:: +* ndbm maps:: +* NIS maps:: +* Hesiod maps:: +* Password maps:: +* Union maps:: +@end menu + +@node File maps, ndbm maps, Map Types, Map Types +@comment node-name, next, previous, up +@subsection File maps +@cindex File maps +@cindex Flat file maps +@cindex File map syntactic conventions + +When @i{Amd} searches a file for a map entry it does a simple scan of +the file and supports both comments and continuation lines. + +Continuation lines are indicated by a backslash character (@samp{\}) as +the last character of a line in the file. The backslash, newline character +@emph{and any leading white space on the following line} are discarded. A maximum +line length of 2047 characters is enforced after continuation lines are read +but before comments are stripped. Each line must end with +a newline character; that is newlines are terminators, not separators. +The following examples illustrate this: + +@example +key valA valB; \ + valC +@end example + +specifies @emph{three} locations, and is identical to + +@example +key valA valB; valC +@end example + +However, + +@example +key valA valB;\ + valC +@end example + +specifies only @emph{two} locations, and is identical to + +@example +key valA valB;valC +@end example + +After a complete line has been read from the file, including +continuations, @i{Amd} determines whether there is a comment on the +line. A comment begins with a hash (``@samp{#}'') character and +continues to the end of the line. There is no way to escape or change +the comment lead-in character. + +Note that continuation lines and comment support @dfn{only} apply to +file maps, or ndbm maps built with the @code{mk-amd-map} program. + +When caching is enabled, file maps have a default cache mode of +@code{all} (@pxref{Automount Filesystem}). + +@node ndbm maps, NIS maps, File maps, Map Types +@comment node-name, next, previous, up +@subsection ndbm maps +@cindex ndbm maps + +An ndbm map may be used as a fast access form of a file map. The program, +@code{mk-amd-map}, converts a normal map file into an ndbm database. +This program supports the same continuation and comment conventions that +are provided for file maps. Note that ndbm format files may @emph{not} +be sharable across machine architectures. The notion of speed generally +only applies to large maps; a small map, less than a single disk block, +is almost certainly better implemented as a file map. + +ndbm maps do not support cache mode @samp{all} and, when caching is +enabled, have a default cache mode of @samp{inc} (@pxref{Automount Filesystem}). + +@node NIS maps, Hesiod maps, ndbm maps, Map Types +@comment node-name, next, previous, up +@subsection NIS maps +@cindex NIS (YP) maps + +When using NIS (formerly YP), an @i{Amd} map is implemented directly +by the underlying NIS map. Comments and continuation lines are +@emph{not} supported in the automounter and must be stripped when +constructing the NIS server's database. + +NIS maps do not support cache mode @code{all} and, when caching is +enabled, have a default cache mode of @code{inc} (@pxref{Automount Filesystem}). + +The following rule illustrates what could be added to your NIS @file{Makefile}, +in this case causing the @file{amd.home} map to be rebuilt: +@example +$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home + -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ + awk '@{ \ + for (i = 1; i <= NF; i++) \ + if (i == NF) @{ \ + if (substr($$i, length($$i), 1) == "\\") \ + printf("%s", substr($$i, 1, length($$i) - 1)); \ + else \ + printf("%s\n", $$i); \ + @} \ + else \ + printf("%s ", $$i); \ + @}' | \ + $(MAKEDBM) - $(YPDBDIR)/amd.home; \ + touch $(YPTSDIR)/amd.home.time; \ + echo "updated amd.home"; \ + if [ ! $(NOPUSH) ]; then \ + $(YPPUSH) amd.home; \ + echo "pushed amd.home"; \ + else \ + : ; \ + fi +@end example + +Here @code{$(YPTSDIR)} contains the time stamp files, and @code{$(YPDBDIR)} contains +the dbm format NIS files. + +@node Hesiod maps, Password maps, NIS maps, Map Types +@comment node-name, next, previous, up +@subsection Hesiod maps +@cindex Hesiod maps + +When the map name begins with the string @samp{hesiod.} lookups are made +using the @dfn{Hesiod} name server. The string following the dot is +used as a name qualifier and is prepended with the key being located. +The entire string is then resolved in the @code{automount} context. For +example, if the the key is @samp{jsp} and map name is +@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve +@samp{jsp.homes.automount}. + +Hesiod maps do not support cache mode @samp{all} and, when caching is +enabled, have a default cache mode of @samp{inc} (@pxref{Automount Filesystem}). + +The following is an example of a @dfn{Hesiod} map entry: + +@example +jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" +njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" +@end example + +@node Password maps, Union maps, Hesiod maps, Map Types +@comment node-name, next, previous, up +@subsection Password maps +@cindex Password file maps +@cindex /etc/passwd maps +@cindex User maps, automatic generation +@cindex Automatic generation of user maps +@cindex Using the password file as a map + +The password map support is unlike the four previous map types. When +the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user +name in the password file and re-arrange the home directory field to +produce a usable map entry. + +@i{Amd} assumes the home directory has the format +`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. +@c @footnote{This interpretation is not necessarily exactly what you want.} +It breaks this string into a map entry where @code{$@{rfs@}} has the +value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value +`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the +value @samp{login}.@refill + +Thus if the password file entry was + +@example +/home/achilles/jsp +@end example + +the map entry used by @i{Amd} would be + +@example +rfs:=/home/achilles;rhost:=achilles;sublink:=jsp +@end example + +Similarly, if the password file entry was + +@example +/home/cc/sugar/mjh +@end example + +the map entry used by @i{Amd} would be + +@example +rfs:=/home/sugar;rhost:=sugar.cc;sublink:=jsp +@end example + +@node Union maps, , Password maps, Map Types +@comment node-name, next, previous, up +@subsection Union maps +@cindex Union file maps + +The union map support is provided specifically for use with the union +filesystem, @pxref{Union Filesystem}. + +It is identified by the string @samp{union:} which is followed by a +colon separated list of directories. The directories are read in order, +and the names of all entries are recorded in the map cache. Later +directories take precedence over earlier ones. The union filesystem +type then uses the map cache to determine the union of the names in all +the directories. + +@c subsection Gdbm + +@node Key Lookup, Location Format, Map Types, Mount Maps +@comment node-name, next, previous, up +@section How keys are looked up +@cindex Key lookup +@cindex Map lookup +@cindex Looking up keys +@cindex How keys are looked up +@cindex Wildcards in maps + +The key is located in the map whose type was determined when the +automount point was first created. In general the key is a pathname +component. In some circumstances this may be modified by variable +expansion (@pxref{Variable Expansion}) and prefixing. If the automount +point has a prefix, specified by the @var{pref} option, then that is +prepended to the search key before the map is searched. + +If the map cache is a @samp{regexp} cache then the key is treated as an +egrep-style regular expression, otherwise a normal string comparison is +made. + +If the key cannot be found then a @dfn{wildcard} match is attempted. +@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and +attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. + +@group +For example, the following sequence would be checked if @file{home/dylan/dk2} was +being located: + +@example + home/dylan/dk2 + home/dylan/* + home/* + * +@end example +@end group + +At any point when a wildcard is found, @i{Amd} proceeds as if an exact +match had been found and the value field is then used to resolve the +mount request, otherwise an error code is propagated back to the kernel. +(@pxref{Filesystem Types}).@refill + +@node Location Format, , Key Lookup, Mount Maps +@comment node-name, next, previous, up +@section Location Format +@cindex Location format +@cindex Map entry format +@cindex How locations are parsed + +The value field from the lookup provides the information required to +mount a filesystem. The information is parsed according to the syntax +shown below. + +@display +@i{location-list}: + @i{location-selection} + @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} +@i{location-selection}: + @i{location} + @i{location-selection} @i{white-space} @i{location} +@i{location}: + @i{location-info} + @t{-}@i{location-info} + @t{-} +@i{location-info}: + @i{sel-or-opt} + @i{location-info}@t{;}@i{sel-or-opt} + @t{;} +@i{sel-or-opt}: + @i{selection} + @i{opt-ass} +@i{selection}: + selector@t{==}@i{value} + selector@t{!=}@i{value} +@i{opt-ass}: + option@t{:=}@i{value} +@i{white-space}: + space + tab +@end display + +Note that unquoted whitespace is not allowed in a location description. +White space is only allowed, and is mandatory, where shown with non-terminal +@samp{white-space}. + +A @dfn{location-selection} is a list of possible volumes with which to +satisfy the request. @dfn{location-selection}s are separated by the +@samp{||} operator. The effect of this operator is to prevent use of +location-selections to its right if any of the location-selections on +its left were selected whether or not any of them were successfully +mounted (@pxref{Selectors}).@refill + +The location-selection, and singleton @dfn{location-list}, +@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS +filesystem from the block special device @file{/dev/xd1g}. + +The @dfn{sel-or-opt} component is either the name of an option required +by a specific filesystem, or it is the name of a built-in, predefined +selector such as the architecture type. The value may be quoted with +double quotes @samp{"}, for example +@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the +value is parsed and there is no way to get a double quote into a value +field. Double quotes are used to get white space into a value field, +which is needed for the program filesystem (@pxref{Program Filesystem}).@refill + +@menu +* Map Defaults:: +* Variable Expansion:: +* Selectors:: +* Map Options:: +@end menu + +@node Map Defaults, Variable Expansion, Location Format, Location Format +@comment node-name, next, previous, up +@subsection Map Defaults +@cindex Map defaults +@cindex How to set default map parameters +@cindex Setting default map parameters + +A location beginning with a dash @samp{-} is used to specify default +values for subsequent locations. Any previously specified defaults in +the location-list are discarded. The default string can be empty in +which case no defaults apply. + +The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point +to @file{/mnt} and cause mounts to be read-only by default. Defaults +specified this way are appended to, and so override, any global map +defaults given with @samp{/defaults}). +@c +@c A @samp{/defaults} value @dfn{gdef} and a location list +@c \begin{quote} +@c $@samp{-}@dfn{def}_a $\verb*+ +$ @dfn{loc}_{a_1} $\verb*+ +$ @dfn{loc}_{a_2} $\verb*+ +$ @samp{-}@dfn{def}_b $\verb*+ +$ @dfn{loc}_{b_1} \ldots$ +@c \end{quote} +@c is equivalent to +@c \begin{quote} +@c $@samp{-}@dfn{gdef}@samp{;}@dfn{def}_a $\verb*+ +$ @dfn{loc}_{a_1} $\verb*+ +$ @dfn{loc}_{a_2} $\verb*+ +$ @samp{-}@dfn{gdef}@samp{;}@dfn{def}_b $\verb*+ +$ @dfn{loc}_{b_1} \ldots$ +@c \end{quote} +@c which is equivalent to +@c \begin{quote} +@c $@dfn{gdef}@samp{;}@dfn{def}_a@samp{;}@dfn{loc}_{a_1} $\verb*+ +$@dfn{gdef}@samp{;}@dfn{def}_a@samp{;}@dfn{loc}_{a_2} $\verb*+ +$@dfn{gdef}@samp{;}@dfn{def}_b@samp{;}@dfn{loc}_{b_1} \ldots$ +@c \end{quote} + +@node Variable Expansion, Selectors, Map Defaults, Location Format +@comment node-name, next, previous, up +@subsection Variable Expansion +@cindex Variable expansion +@cindex How variables are expanded +@cindex Pathname operators +@cindex Domain stripping +@cindex Domainname operators +@cindex Stripping the local domain name +@cindex Environment variables +@cindex How to access environment variables in maps + +To allow generic location specifications @i{Amd} does variable expansion +on each location and also on some of the option strings. Any option or +selector appearing in the form @code{$@dfn{var}} is replaced by the +current value of that option or selector. For example, if the value of +@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and +@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then +after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. +Any environment variable can be accessed in a similar way.@refill + +Two pathname operators are available when expanding a variable. If the +variable name begins with @samp{/} then only the last component of +then pathname is substituted. For example, if @code{$@{path@}} was +@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. +Similarly, if the variable name ends with @samp{/} then all but the +last component of the pathname is substituted. In the previous example, +@code{$@{path/@}} would be expanded to @samp{/foo}.@refill + +Two domain name operators are also provided. If the variable name +begins with @samp{.} then only the domain part of the name is +substituted. For example, if @code{$@{rhost@}} was +@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to +@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} +then only the host component is substituted. In the previous example, +@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill + +Variable expansion is a two phase process. Before a location is parsed, +all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The +location is then parsed, selections are evaluated and option assignments +recorded. If there were no selections or they all succeeded the +location is used and the values of the following options are expanded in +the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, +@var{remopts}, @var{mount} and @var{unmount}. + +Note that expansion of option values is done after @dfn{all} assignments +have been completed and not in a purely left to right order as is done +by the shell. This generally has the desired effect but care must be +taken if one of the options references another, in which case the +ordering can become significant. + +There are two special cases concerning variable expansion: + +@enumerate +@item +before a map is consulted, any selectors in the name received +from the kernel are expanded. For example, if the request from the +kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture +was @samp{vax}, the value given to @code{$@{key@}} would be +@samp{vax.bin}.@refill + +@item +the value of @code{$@{rhost@}} is expanded and normalized before the +other options are expanded. The normalization process strips any local +sub-domain components. For example, if @code{$@{domain@}} was +@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially +@samp{snow.Berkeley.EDU}, after the normalization it would simply be +@samp{snow}. Hostname normalization is currently done in a +@emph{case-dependent} manner.@refill +@end enumerate + +@node Selectors, Map Options, Variable Expansion, Location Format +@comment node-name, next, previous, up +@subsection Selectors +@cindex Selectors + +Selectors are used to control the use of a location. It is possible to +share a mount map between many machines in such a way that filesystem +location, architecture and operating system differences are hidden from +the users. A selector of the form @samp{arch==sun3;os==sos4} would only +apply on Sun-3s running SunOS 4.x. + +Selectors are evaluated left to right. If a selector fails then that +location is ignored. Thus the selectors form a conjunction and the +locations form a disjunction. If all the locations are ignored or +otherwise fail then @i{Amd} uses the @dfn{error} filesystem +(@pxref{Error Filesystem}). This is equivalent to having a location +@samp{type:=error} at the end of each mount-map entry.@refill + +The selectors currently implemented are: + +@table @samp +@cindex arch, mount selector +@cindex Mount selector; arch +@cindex Selector; arch +@item arch +the machine architecture which was automatically determined at compile +time. The architecture type can be displayed by running the command +@samp{amd -v}. @xref{Supported Machine Architectures}.@refill + +@item autodir +@cindex autodir, mount selector +@cindex Mount selector; autodir +@cindex Selector; autodir +the default directory under which to mount filesystems. This may be +changed by the ``-a'' command line option. See the @var{fs} option. + +@item byte +@cindex byte, mount selector +@cindex Mount selector; byte +@cindex Selector; byte +the machine's byte ordering. This is either @samp{little}, indicating +little-endian, or @samp{big}, indicating big-endian. One possible use +is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to +share ndbm databases, however this use can be considered a courageous +juggling act. + +@item cluster +@cindex cluster, mount selector +@cindex Mount selector; cluster +@cindex Selector; cluster +is provided as a hook for the name of the local cluster. This can be +used to decide which servers to use for copies of replicated +filesystems. @code{$@{cluster@}} defaults to the value of +@code{$@{domain@}} unless a different value is set with the ``-C'' +command line option. + +@item domain +@cindex domain, mount selector +@cindex Mount selector; domain +@cindex Selector; domain +the local domain name as specified by the ``-d'' command line option. +See @samp{host}. + +@item host +@cindex host, mount selector +@cindex Mount selector; host +@cindex Selector; host +the local hostname as determined by @b{gethostname}(2). If no domain +name was specified on the command line and the hostname contains a +period @samp{.} then the string before the period is used as the +host name, and the string after the period is assigned to +@code{$@{domain@}}. For example, if the hostname is +@samp{styx.doc.ic.ac.uk} then @code{host} would be @samp{styx} and +@code{domain} would be @samp{doc.ic.ac.uk}. @code{hostd} would be +@samp{styx.doc.ic.ac.uk}.@refill + +@item hostd +@cindex hostd, mount selector +@cindex Mount selector; hostd +@cindex Selector; hostd +is @code{$@{host@}} and @code{$@{domain@}} concatenated with a +@samp{.} inserted between them if required. If @code{$@{domain@}} +is an empty string then @code{$@{host@}} and @code{$@{hostd@}} will be +identical. + +@item karch +@cindex karch, mount selector +@cindex Mount selector; karch +@cindex Selector; karch +is provided as a hook for the kernel architecture. This is used on +SunOS 4, for example, to distinguish between different @samp{/usr/kvm} +volumes. @code{$@{karch@}} defaults to the value of @code{$@{arch@}} +unless a different value is set with the ``-k'' command line option. + +@item os +@cindex os, mount selector +@cindex Mount selector; os +@cindex Selector; os +the operating system. Like the machine architecture, this is +automatically determined at compile time. The operating system name can +be displayed by running the command @samp{amd -v}. @xref{Supported +Operating Systems}.@refill + +@end table + +The following selectors are also provided. Unlike the other selectors, +they vary for each lookup. Note that when the name from the kernel is +expanded prior to a map lookup, these selectors are all defined as empty +strings. + +@table @samp +@item key +@cindex key, mount selector +@cindex Mount selector; key +@cindex Selector; key +the name being resolved. For example, if @file{/home} is an automount +point, then accessing @file{/home/foo} would set @code{$@{key@}} to the +string @samp{foo}. The key is prefixed by the @var{pref} option set in +the parent mount point. The default prefix is an empty string. If the +prefix was @file{blah/} then @code{$@{key@}} would be set to +@file{blah/foo}.@refill + +@item map +@cindex map, mount selector +@cindex Mount selector; map +@cindex Selector; map +the name of the mount map being used. + +@item path +@cindex path, mount selector +@cindex Mount selector; path +@cindex Selector; path +the full pathname of the name being resolved. For example +@file{/home/foo} in the example above. + +@item wire +@cindex wire, mount selector +@cindex Mount selector; wire +@cindex Selector; wire +the name of the network to which the primary network interface is +attached. If a symbolic name cannot be found in the networks or hosts +database then dotted IP address format is used. This value is also +output by the ``-v'' option. + +@end table + +Selectors can be negated by using @samp{!=} instead of @samp{==}. For +example to select a location on all non-Vax machines the selector +@samp{arch!=vax} would be used. + +@node Map Options, , Selectors, Location Format +@comment node-name, next, previous, up +@subsection Map Options +@cindex Map options +@cindex Setting map options + +Options are parsed concurrently with selectors. The difference is that +when an option is seen the string following the @samp{:=} is +recorded for later use. As a minimum the @var{type} option must be +specified. Each filesystem type has other options which must also be +specified. @xref{Filesystem Types}, for details on the filesystem +specific options.@refill + +Superfluous option specifications are ignored and are not reported +as errors. + +The following options apply to more than one filesystem type. + +@menu +* delay Option:: +* fs Option:: +* opts Option:: +* remopts Option:: +* sublink Option:: +* type Option:: +@end menu + +@node delay Option, fs Option, Map Options, Map Options +@comment node-name, next, previous, up +@subsubsection delay Option +@cindex Setting a delay on a mount location +@cindex Delaying mounts from specific locations +@cindex Primary server +@cindex Secondary server +@cindex delay, mount option +@cindex Mount option; delay + +The delay, in seconds, before an attempt will be made to mount from the current location. +Auxilliary data, such as network address, file handles and so on are computed +regardless of this value. + +A delay can be used to implement the notion of primary and secondary file servers. +The secondary servers would have a delay of a few seconds, +thus giving the primary servers a chance to respond first. + +@node fs Option, opts Option, delay Option, Map Options +@comment node-name, next, previous, up +@subsubsection fs Option +@cindex Setting the local mount point +@cindex Overriding the default mount point +@cindex fs, mount option +@cindex Mount option; fs + +The local mount point. The semantics of this option vary between +filesystems. + +For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the +local mount point. For other filesystem types it has other meanings +which are described in the section describing the respective filesystem +type. It is important that this string uniquely identifies the +filesystem being mounted. To satisfy this requirement, it should +contain the name of the host on which the filesystem is resident and the +pathname of the filesystem on the local or remote host. + +The reason for requiring the hostname is clear if replicated filesystems +are considered. If a fileserver goes down and a replacement filesystem +is mounted then the @dfn{local} mount point @dfn{must} be different from +that of the filesystem which is hung. Some encoding of the filesystem +name is required if more than one filesystem is to be mounted from any +given host. + +If the hostname is first in the path then all mounts from a particular +host will be gathered below a single directory. If that server goes +down then the hung mount points are less likely to be accidentally +referenced, for example when @b{getwd}(3) traverses the namespace to +find the pathname of the current directory. + +The @samp{fs} option defaults to +@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, +@samp{rhost} defaults to the local host name (@code{$@{host@}}) and +@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full +path of the requested file; @samp{/home/foo} in the example above +(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may +be changed with the ``-a'' command line option. Sun's automounter +defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between +the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins +with a @samp{/}.@refill + +@node opts Option, remopts Option, fs Option, Map Options +@comment node-name, next, previous, up +@subsubsection opts Option +@cindex Setting system mount options +@cindex Passing parameters to the mount system call +@cindex mount system call +@cindex mount system call flags +@cindex The mount system call +@cindex opts, mount option +@cindex Mount option; opts + +The options to pass to the mount system call. A leading @samp{-} is +silently ignored. The mount options supported generally correspond to +those used by @b{mount}(8) and are listed below. Some additional +pseudo-options are interpreted by @i{Amd} and are also listed. + +Unless specifically overridden, each of the system default mount options +applies. Any options not recognised are ignored. If no options list is +supplied the string @samp{rw,defaults} is used and all the system +default mount options apply. Options which are not applicable for a +particular operating system are silently ignored. For example, only 4.4 +BSD is known to implement the @code{compress} and @code{spongy} options. + +@table @code +@item compress +Use NFS compression protocol. +@item grpid +Use BSD directory group-id semantics. +@item intr +Allow keyboard interrupts on hard mounts. +@item noconn +Don't make a connection on datagram transports. +@item nocto +No close-to-open consistency. +@item nodevs +Don't allow local special devices on this filesystem. +@item nosuid +Don't allow set-uid or set-gid executables on this filesystem. +@item quota +Enable quota checking on this mount. +@item retrans=@i{n} +The number of NFS retransmits made before a user error is generated by a +@samp{soft} mounted filesystem, and before a @samp{hard} mounted +filesystem reports @samp{NFS server @dfn{yoyo} not responding still +trying}. +@item ro +Mount this filesystem readonly. +@item rsize=@var{n} +The NFS read packet size. You may need to set this if you are using +NFS/UDP through a gateway. +@item soft +Give up after @dfn{retrans} retransmissions. +@item spongy +Like @samp{soft} for status requests, and @samp{hard} for data transfers. +@item tcp +Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not +support TCP/IP mounts. +@item timeo=@var{n} +The NFS timeout, in tenth-seconds, before a request is retransmitted. +@item wsize=@var{n} +The NFS write packet size. You may need to set this if you are using +NFS/UDP through a gateway. +@end table + +The following options are implemented by @i{Amd}, rather than being +passed to the kernel. + +@table @code +@item nounmount +Configures the mount so that its time-to-live will +never expire. This is also the default for some filesystem types. +@c +@c Implementation broken: +@item ping=@var{n} +The interval, in seconds, between keep-alive pings. When four +consecutive pings have failed the mount point is marked as hung. This +interval defaults to 30 seconds. If the ping interval is less than zero, +no pings are sent and the host is assumed to be always +up. By default, pings are not sent for an NFS/TCP mount. +@item retry=@var{n} +The number of times to retry the mount system call. +@item utimeout=@var{n} +The interval, in seconds, by which the mount's +time-to-live is extended after an unmount attempt +has failed. In fact the interval is extended before the unmount is +attempted to avoid thrashing. The default value is 120 seconds (two +minutes) or as set by the ``-w'' command line option. +@end table + +@node remopts Option, sublink Option, opts Option, Map Options +@comment node-name, next, previous, up +@subsubsection remopts Option +@cindex Setting system mount options for non-local networks +@cindex remopts, mount option +@cindex Mount option; remopts + +This option has the same use as @code{$@{opts@}} but applies only when +the remote host is on a non-local network. For example, when using NFS +across a gateway it is often necessary to use smaller values for the +data read and write sizes. This can simply be done by specifying the +small values in @var{remopts}. When a non-local host is accessed, the +smaller sizes will automatically be used. + +@i{Amd} determines whether a host is local by examining the network +interface configuration at startup. Any interface changes made after +@i{Amd} has been started will not be noticed. The likely effect will +be that a host may incorrectly be declared non-local. + +Unless otherwise set, the value of @code{$@{rem@}} is the same as the +value of @code{$@{opts@}}. + +@node sublink Option, type Option, remopts Option, Map Options +@comment node-name, next, previous, up +@subsubsection sublink Option +@cindex Setting the sublink option +@cindex sublink, mount option +@cindex Mount option; sublink + +The subdirectory within the mounted filesystem to which the reference +should point. This can be used to prevent duplicate mounts in cases +where multiple directories in the same mounted filesystem are used. + +@node type Option, , sublink Option, Map Options +@comment node-name, next, previous, up +@subsubsection type Option +@cindex Setting the filesystem type option +@cindex type, mount option +@cindex Mount option; type + +The filesystem type to be used. @xref{Filesystem Types}, for a full +description of each type.@refill + +@node Amd Command Line Options, Filesystem Types, Mount Maps, Top +@comment node-name, next, previous, up +@chapter @i{Amd} Command Line Options +@cindex Command line options, Amd +@cindex Amd command line options +@cindex Overriding defaults on the command line + +Many of @i{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 + +@example +amd [@i{options}] @{ @i{directory} @i{map-name} [-@i{map-options}] @} ... +@end example + +For each directory and map-name given, @i{Amd} establishes an +automount point. The @dfn{map-options} may be any sequence of options +or selectors---@pxref{Location Format}. The @dfn{map-options} +apply only to @i{Amd}'s mount point. + +@samp{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 @samp{/defaults}. When default options +are given they are prepended to any options specified in the mount-map +locations as explained in. @xref{Map Defaults}, for more details. + +The @dfn{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 @i{Amd} exits. +Finally, @i{Amd} disassociates itself from its controlling terminal and +forks into the background. + +Note: Even if @i{Amd} has been built with @samp{-DDEBUG} it will still +background itself and disassociate itself from the controlling terminal. +To use a debugger it is necessary to specify @samp{-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. +@end menu + +@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-a} @var{directory} +@cindex Automount directory +@cindex Setting the default mount directory + +Specifies the default mount directory. This option changes the variable +@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, +some sites prefer @file{/amd}. + +@example +amd -a /amd ... +@end example + +@node -c Option, -d Option, -a Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-c} @var{cache-interval} +@cindex Cache interval +@cindex Interval before a filesystem times out +@cindex Setting the interval before a filesystem times out +@cindex Changing the interval before a filesystem times out + +Selects the period, in seconds, for which a name is cached by @i{Amd}. +If no reference is made to the volume in this period, @i{Amd} discards +the volume name to filesystem mapping. + +Once the last reference to a filesystem has been removed, @i{Amd} +attempts to unmount the filesystem. If the unmount fails the interval +is extended by a further period as specified by the @samp{-w} command +line option or by the @samp{utimeout} mount option. + +The default @dfn{cache-interval} is 300 seconds (five minutes). + +@node -d Option, -k Option, -c Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-d} @var{domain} +@cindex Domain name +@cindex Setting the local domain name +@cindex Overriding the local domain name + +Specifies the host's domain. This sets the internal variable +@code{$@{domain@}} and affects the @code{$@{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 +@code{$@{domain@}} is @samp{unknown.domain}. + +For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could +be started as follows: + +@example +amd -d doc.ic.ac.uk ... +@end example + +@node -k Option, -l Option, -d Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-k} @var{kernel-architecture} +@cindex Setting the Kernel architecture + +Specifies the kernel architecture of the system. This is usually the +output of @samp{arch -k} and its only effect is to set the variable +@code{$@{karch@}}. If this option is not given, @code{$@{karch@}} has +the same value as @code{$@{arch@}}. + +This would be used as follows: + +@example +amd -k `arch -k` ... +@end example + +@node -l Option, -n Option, -k Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-l} @var{log-option} +@cindex Log filename +@cindex Setting the log file +@cindex Using syslog to log errors +@cindex syslog + +Selects the form of logging to be made. Two special @dfn{log-options} +are recognised. + +@enumerate +@item +If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the +@b{syslog}(3) mechanism.@refill + +@item +If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use +standard error, which is also the default target for log messages. To +implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} +driver. +@end enumerate + +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 @samp{syslog} option is specified but the system does not support +syslog or if the named file cannot be opened or created, @i{Amd} will +use standard error. Error messages generated before @i{Amd} has +finished parsing the command line are printed on standard error. + +Using @samp{syslog} is usually best, in which case @i{Amd} would be +started as follows: + +@example +amd -l syslog ... +@end example + +@node -n Option, -p Option, -l Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-n} +@cindex Hostname normalisation +@cindex Aliased hostnames +@cindex Resolving aliased hostnames +@cindex Normalising hostnames + +Normalises the remote hostname before using it. Normalisation is done +by replacing the value of @code{$@{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. + +@node -p Option, -r Option, -n Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-p} +@cindex Process id +@cindex Displaying the process id +@cindex process id of Amd daemon +@cindex pid file, creating with -p option +@cindex Creating a pid file + +Causes @i{Amd}'s process id to be printed on standard output. +This can be redirected to a suitable file for use with kill: + +@example +amd -p > /var/run/amd.pid ... +@end example + +This option only has an affect if @i{Amd} is running in daemon mode. +If @i{Amd} is started with the @code{-D nodaemon} debug flag, this +option is ignored. + +@node -r Option, -t Option, -p Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-r} +@cindex Restarting existing mounts +@cindex Picking up existing mounts + +Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). +@c @dfn{This option will be made the default in the next release.} + +@node -t Option, -v Option, -r Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-t} @var{timeout.retransmit} +@cindex Setting Amd's RPC parameters + +Specifies the RPC @dfn{timeout} and @dfn{retransmit} intervals used by +the kernel to communicate to @i{Amd}. These are used to set the +@samp{timeo} and @samp{retrans} mount options. + +@i{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. + +@node -v Option, -w Option, -t Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-v} +@cindex Version information +@cindex Discovering version information +@cindex How to discover your version of Amd + +Print version information on standard error and then exit. The output +is of the form: + +@example +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. +@end example + +The information includes the version number, release date and name of +the release. The architecture (@pxref{Supported Machine Architectures}), +operating system (@pxref{Supported Operating Systems}) +and byte ordering are also printed as they appear in the @code{$@{os@}}, +@code{$@{arch@}} and @code{$@{byte@}} variables.@refill + +@node -w Option, -x Option, -v Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-w} @var{wait-timeout} +@cindex Setting the interval between unmount attempts +@cindex unmount attempt backoff interval + +Selects the interval in seconds between unmount attempts after the +initial time-to-live has expired. + +This defaults to 120 seconds (two minutes). + +@node -x Option, -y Option, -w Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-x} @var{opts} +@cindex Log message selection +@cindex Selecting specific log messages +@cindex How to select log messages +@cindex syslog priorities + +Specifies the type and verbosity of log messages. @dfn{opts} is +a comma separated list selected from the following options: + +@table @code +@item fatal +Fatal errors +@item error +Non-fatal errors +@item user +Non-fatal user errors +@item warn +Recoverable errors +@item warning +Alias for @code{warn} +@item info +Information messages +@item map +Mount map usage +@item stats +Additional statistics +@item all +All of the above +@end table + +Initially a set of default logging flags is enabled. This is as if +@samp{-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 +@i{Amq}. This default set of options is useful for general production +use.@refill + +The @samp{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 @samp{info} messages then you simply +need @samp{-x noinfo}. The messages given by @samp{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.@refill + +@table @code +@item fatal +LOG_CRIT +@item error +LOG_ERR +@item user +LOG_WARNING +@item warning +LOG_WARNING +@item info +LOG_INFO +@item debug +LOG_DEBUG +@item map +LOG_DEBUG +@item stats +LOG_INFO +@end table + + +The options can be prefixed by the string @samp{no} to indicate +that this option should be turned off. For example, to obtain all +but @samp{info} messages the option @samp{-x all,noinfo} would be used. + +If @i{Amd} was built with debugging enabled the @code{debug} option is +automatically enabled regardless of the command line options. + +@node -y Option, -C-Option, -x Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-y} @var{NIS-domain} +@cindex NIS (YP) domain name +@cindex Overriding the NIS (YP) domain name +@cindex Setting the NIS (YP) domain name +@cindex YP domain name + +Selects an alternate NIS domain. This is useful for debugging and +cross-domain shared mounting. If this flag is specified, @i{Amd} +immediately attempts to bind to a server for this domain. +@c @i{Amd} refers to NIS maps when it starts, unless the ``-m'' option +@c is specified, and whenever required in a mount map. + +@node -C-Option, -D-Option, -y Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-C} @var{cluster-name} +@cindex Cluster names +@cindex Setting the cluster name + +Specifies the name of the cluster of which the local machine is a member. +The only effect is to set the variable @code{$@{cluster@}}. +The @dfn{cluster-name} is will usually obtained by running another command which uses +a database to map the local hostname into a cluster name. +@code{$@{cluster@}} can then be used as a selector to restrict mounting of +replicated data. +If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. +This would be used as follows: + +@example +amd -C `clustername` ... +@end example + +@node -D-Option, , -C-Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-D} @var{opts} +@cindex Debug options +@cindex Setting debug flags + +Controls the verbosity and coverage of the debugging trace; @dfn{opts} +is a comma separated list of debugging options. The ``-D'' option is +only available if @i{Amd} was compiled with @samp{-DDEBUG}. The memory +debugging facilities are only available if @i{Amd} was compiled with +@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}). + +The most common options to use are @samp{-D trace} and @samp{-D test} +(which turns on all the useful debug options). See the program source +for a more detailed explanation of the available options. + +@node Filesystem Types, Run-time Administration, Amd Command Line Options, Top +@comment node-name, next, previous, up +@chapter Filesystem Types +@cindex Filesystem types +@cindex Mount types +@cindex Types of filesystem + +To mount a volume, @i{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 @i{Amd}, a @dfn{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 @i{Amd}.@refill + +The two common filesystem types are UFS and NFS. Four other user +accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and +@samp{direct}) are also implemented internally by @i{Amd} and these are +described below. There are two additional filesystem types internal to +@i{Amd} which are not directly accessible to the user (@samp{inherit} +and @samp{error}). Their use is described since they may still have an +effect visible to the user.@refill + +@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. +* Automount Filesystem:: +* Direct Automount Filesystem:: +* Union Filesystem:: +* Error Filesystem:: +* Top-level Filesystem:: +* Root Filesystem:: +* Inheritance Filesystem:: +@end menu + +@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types +@comment node-name, next, previous, up +@section Network Filesystem (@samp{type:=nfs}) +@cindex NFS +@cindex Mounting an NFS filesystem +@cindex How to mount and NFS filesystem +@cindex nfs, filesystem type +@cindex Filesystem type; nfs + +The @dfn{nfs} filesystem type provides access to Sun's NFS. + +@noindent +The following options must be specified: + +@table @code +@cindex rhost, mount option +@cindex Mount option; rhost +@item 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 (@code{$@{host@}}) if no other value is +specified. + +@cindex rfs, mount option +@cindex Mount option; rfs +@item rfs +the remote filesystem. +If no value is specified for this option, an internal default of +@code{$@{path@}} is used. +@end table + +NFS mounts require a two stage process. First, the @dfn{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. @i{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, @i{Amd} sends a request +to the remote server to obtain it. @i{Amd} @dfn{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, @i{Amd} will retry the mount. This mechanism allows several +NFS filesystems to be mounted in parallel. +@c @footnote{The mechanism +@c is general, however NFS is the only filesystem +@c for which the required hooks have been written.} +The first one which responds with a valid file handle will be used. + +@noindent +An NFS entry might be: + +@example +jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp +@end example + +The mount system call and any unmount attempts are always done +in a new task to avoid the possibilty of blocking @i{Amd}. + +@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Network Host Filesystem (@samp{type:=host}) +@cindex Network host filesystem +@cindex Mounting entire export trees +@cindex How to mount all NFS exported filesystems +@cindex host, filesystem type +@cindex Filesystem type; host + +@c NOTE: the current implementation of the @dfn{host} filesystem type +@c sometimes fails to maintain a consistent view of the remote mount tree. +@c This happens when the mount times out and only some of the remote mounts +@c are successfully unmounted. To prevent this from occuring, use the +@c @samp{nounmount} mount option. + +The @dfn{host} filesystem allows access to the entire export tree of an +NFS server. The implementation is layered above the @samp{nfs} +implementation so keep-alives work in the same way. The only option +which needs to specified is @samp{rhost} which is the name of the +fileserver to mount. + +The @samp{host} filesystem type works by querying the mount daemon on +the given fileserver to obtain its export list. @i{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 @i{Amd} attempts to automatically create the mount point, it +may be on a remote filesystem to which @i{Amd} does not have write +permission. + +When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} +remounts any filesystems which had succesfully been unmounted. To do +this @i{Amd} queries the mount daemon again and obtains a fresh copy of +the export list. @i{Amd} then tries to mount any exported filesystems +which are not currently mounted. + +Sun's automounter provides a special @samp{-hosts} map. To achieve the +same effect with @i{Amd} requires two steps. First a mount map must +be created as follows: + +@example +/defaults type:=host;fs:=$@{autodir@}/$@{rhost@}/root;rhost:=$@{key@} +* opts:=rw,nosuid,grpid +@end example + +@noindent +and then start @i{Amd} with the following command + +@example +amd /n net.map +@end example + +@noindent +where @samp{net.map} is the name of map described above. Note that the +value of @code{$@{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 + +@example +host2 opts:=ro,nosuid,soft +@end example + +@noindent +would soft mount @samp{host2} read-only. + +@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Network Filesystem Group (@samp{type:=nfsx}) +@cindex Network filesystem group +@cindex Atomic NFS mounts +@cindex Mounting an atomic group of NFS filesystems +@cindex How to mount an atomic group of NFS filesystems +@cindex nfsx, filesystem type +@cindex Filesystem type; nfsx + +The @dfn{nfsx} filesystem allows a group of filesystems to be mounted +from a single NFS server. The implementation is layered above the +@samp{nfs} implementation so keep-alives work in the same way. + +The options are the same as for the @samp{nfs} filesystem with one +difference. + +@noindent +The following options must be specified: + +@table @code +@item 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 (@code{$@{host@}}) if no other value is specified. + +@item rfs +as a list of filesystems to mount. The list is in the form of a comma +separated strings. +@end table + +@noindent +For example: + +@example +pub type:=nfsx;rhost:=gould;\ + rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root +@end example + +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 @emph{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 @emph{three} filesystems, @samp{/public}, +@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill + +A local mount point, @code{$@{fs@}}, @emph{must} be specified. The +default local mount point will not work correctly in the general case. +A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill + +@node Unix Filesystem, Program Filesystem, Network Filesystem Group, Filesystem Types +@comment node-name, next, previous, up +@section Unix Filesystem (@samp{type:=ufs}) +@cindex Unix filesystem +@cindex UFS +@cindex Mounting a UFS filesystem +@cindex Mounting a local disk +@cindex How to mount a UFS filesystems +@cindex How to mount a local disk +@cindex Disk filesystems +@cindex ufs, filesystem type +@cindex Filesystem type; ufs + +The @dfn{ufs} filesystem type provides access to the system's +standard disk filesystem---usually a derivative of the Berkeley Fast Filesystem. + +@noindent +The following option must be specified: + +@table @code +@cindex dev, mount option +@cindex Mount option; dev +@item dev +the block special device to be mounted. +@end table + +A UFS entry might be: + +@example +jsp host==charm;type:=ufs;dev:=/dev/xd0g;sublink:=jsp +@end example + +@node Program Filesystem, Symbolic Link Filesystem, Unix Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Program Filesystem (@samp{type:=program}) +@cindex Program filesystem +@cindex Mount a filesystem under program control +@cindex program, filesystem type +@cindex Filesystem type; program + +The @dfn{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 +@samp{rvdmount} and @samp{rvdunmount}. + +@noindent +The following options must be specified: + +@table @code +@cindex mount, mount option +@cindex Mount option; mount +@item mount +the program which will perform the mount. + +@cindex unmount, mount option +@cindex Mount option; unmount +@item unmount +the program which will perform the unmount. +@end table + +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 @i{Amd} splits the string on whitespace to create an array of +substrings. Single quotes @samp{'} 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 @samp{rvdmount} with a host name and filesystem as +arguments would be specified by @samp{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, @dfn{including argument zero}. This means +that the split string must have at least two elements. The program is +directly executed by @i{Amd}, not via a shell. This means that scripts +must begin with a @code{#!} interpreter specification. + +If a filesystem type is to be heavily used, it may be worthwhile adding +a new filesystem type into @i{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 @i{Amd}. Standard output is a +duplicate of standard error. The value specified with the ``-l'' +command line option has no effect on standard error. + +@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Symbolic Link Filesystem (@samp{type:=link}) +@cindex Symbolic link filesystem +@cindex Referencing part of the local name space +@cindex Mounting part of the local name space +@cindex How to reference part of the local name space +@cindex link, filesystem type +@cindex symlink, link filesystem type +@cindex Filesystem type; link + +Each filesystem type creates a symbolic link to point from the volume +name to the physical mount point. The @samp{link} filesystem does the +same without any other side effects. This allows any part of the +machines name space to be accessed via @i{Amd}. + +One common use for the symlink filesystem is @file{/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. + +@noindent +The following option must be defined: + +@table @code +@item fs +The value of @var{fs} option specifies the destination of the link, as +modified by the @var{sublink} option. If @var{sublink} is non-null, it +is appended to @code{$@{fs@}}@code{/} and the resulting string is used +as the target. +@end table + +The @samp{link} filesystem can be though of as identical to the +@samp{ufs} filesystem but without actually mounting anything. + +An example entry might be: + +@example +jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp +@end example +which would return a symbolic link pointing to @file{/home/charm/jsp}. + +@node Symbolic Link Filesystem II, Automount Filesystem, Program Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Symbolic Link Filesystem II (@samp{type:=link}) +@cindex Symbolic link filesystem II +@cindex Referencing an existing part of the local name space +@cindex Mounting an existing part of the local name space +@cindex How to reference an existing part of the local name space +@cindex linkx, filesystem type +@cindex symlink, linkx filesystem type +@cindex Filesystem type; linkx + +The @samp{linkx} filesystem type is identical to @samp{link} with the +exception that the target of the link must exist. Existence is checked +with the @samp{lstat} system call. + +The @samp{linkx} filesystem type is particularly useful for wildcard map +entries. In this case, a list of possible targets can be give and +@i{Amd} will choose the first one which exists on the local machine. + +@node Automount Filesystem, Direct Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types +@comment node-name, next, previous, up +@section Automount Filesystem (@samp{type:=auto}) +@cindex Automount filesystem +@cindex Map cache types +@cindex Setting map cache parameters +@cindex How to set map cache parameters +@cindex How to start an indirect automount point +@cindex auto, filesystem type +@cindex Filesystem type; auto +@cindex SIGHUP signal +@cindex Map cache synchronising +@cindex Synchronising the map cache +@cindex Map cache options +@cindex Regular expressions in maps + +The @dfn{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: + +@table @code +@cindex cache, mount option +@cindex Mount option; cache +@item cache +specifies whether the data in this mount-map should be +cached. The default value is @samp{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 @samp{all}, +the entire map is enumerated when the mount point is created. + +If the cache option specifies @samp{inc}, caching is done incrementally +as and when data is required. +Some map types do not support cache mode @samp{all}, in which case @samp{inc} +is used whenever @samp{all} is requested. + +Caching can be entirely disabled by using cache mode @samp{none}. + +If the cache option specifies @samp{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 @samp{inc}, which +can be selected by specifying @samp{mapdefault}. + +The cache mode for a mount map can only be selected on the command line. +Starting @i{Amd} with the command: + +@example +amd /homes hesiod.homes -cache:=inc +@end example + +will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name +server with local incremental caching of all succesfully resolved names. + +All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} +signal and, if cache @samp{all} mode was selected, the cache will be +reloaded. This can be used to inform @i{Amd} that a map has been +updated. In addition, whenever a cache lookup fails and @i{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 +@samp{SIGHUP} had been received. + +An additional option (@samp{sync}) may be specified to force @i{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: + +@example +amd /homes hesiod.homes -cache:=inc,sync +@end example + +@item fs +specifies the name of the mount map to use for the new mount point. + +Arguably this should have been specified with the @code{$@{rfs@}} option but +we are now stuck with it due to historical accident. + +@c %If the string @samp{.} is used then the same map is used; +@c %in addition the lookup prefix is set to the name of the mount point followed +@c %by a slash @samp{/}. +@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. +@c + +@item pref +alters the name that is looked up in the mount map. If +@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended to +the name requested by the kernel @dfn{before} the map is searched. +@end table + +The server @samp{dylan.doc.ic.ac.uk} has two user disks: +@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as +@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since +@samp{/home} is already an automount point, this naming is achieved with +the following map entries:@refill + +@example +dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ +dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 +dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 +@end example + +@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Direct Automount Filesystem (@samp{type:=direct}) +@cindex Direct automount filesystem +@cindex How to start a direct automount point +@cindex direct, filesystem type +@cindex Filesystem type; direct + +The @dfn{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. @xref{Automount Filesystem} for a +list of required options. + +Direct automount points are created by specifying the @samp{direct} +filesystem type on the command line: + +@example +amd ... /usr/man auto.direct -type:=direct +@end example + +where @samp{auto.direct} would contain an entry such as: + +@example +usr/man -type:=nfs;rfs:=/usr/man \ + rhost:=man-server1 rhost:=man-server2 +@end example + +In this example, @samp{man-server1} and @samp{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 @samp{/}. + +@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Union Filesystem (@samp{type:=union}) +@cindex Union filesystem +@cindex union, filesystem type +@cindex Filesystem type; union + +The @dfn{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 @file{/tmp} and @file{/var/tmp} were to be merged +into a new directory called @file{/mtmp}, with files in @file{/var/tmp} +taking precedence. The following command could be used to achieve this +effect: + +@example +amd ... /mtmp union:/tmp:/var/tmp -type:=union +@end example + +Currently, the unioned directories must @emph{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 @i{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 +@i{Amd} is started, and are not kept uptodate with respect to the +underlying directories. Similarly, if a link is removed, for example +with the @samp{rm} command, it will be lost forever. + +@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Error Filesystem (@samp{type:=error}) +@cindex Error filesystem +@cindex error, filesystem type +@cindex Filesystem type; error + +The @dfn{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. + +@node Top-level Filesystem, Root Filesystem, Error Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Top-level Filesystem (@samp{type:=toplvl}) +@cindex Top level filesystem +@cindex toplvl, filesystem type +@cindex Filesystem type; toplvl + +The @dfn{toplvl} filesystems is derived from the @samp{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 @dfn{Amq} command. + +@node Root Filesystem, Inheritance Filesystem, Top-level Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Root Filesystem +@cindex Root filesystem +@cindex root, filesystem type +@cindex Filesystem type; root + +The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal +placeholder onto which @i{Amd} can pin @samp{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. + +@node Inheritance Filesystem, , Root Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Inheritance Filesystem +@cindex Inheritance filesystem +@cindex Nodes generated on a restart +@cindex inherit, filesystem type +@cindex Filesystem type; inherit + +The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly +accessible. Instead, internal mount nodes of this type are +automatically generated when @i{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 @i{Amd} then instead of attempting to mount it, @i{Amd} +simulates the mount and @dfn{inherits} the filesystem. This allows a +new version of @i{Amd} to be installed on a live system simply by +killing the old daemon with @code{SIGTERM} and starting the new one.@refill + +This filesystem type is not generally visible externally, but it is +possible that the output from @samp{amq -m} may list @samp{inherit} as +the filesystem type. This happens when an inherit operation cannot +be completed for some reason, usually because a fileserver is down. + +@node Run-time Administration, FSinfo, Filesystem Types, Top +@comment node-name, next, previous, up +@chapter Run-time Administration +@cindex Run-time administration +@cindex Amq command + +@menu +* Starting Amd:: +* Stopping Amd:: +* Controlling Amd:: +@end menu + +@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration +@comment node-name, next, previous, up +@section Starting @i{Amd} +@cindex Starting Amd +@cindex Additions to /etc/rc.local +@cindex /etc/rc.local additions +@cindex /etc/amd.start + +@i{Amd} is best started from @samp{/etc/rc.local}: + +@example +if [ -f /etc/amd.start ]; then + sh /etc/amd.start; (echo -n ' amd') >/dev/console +fi +@end example + +@noindent +The shell script, @samp{amd.start}, contains: + +@example +#!/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 +@end example + +If the list of automount points and maps is contained in a file or NIS map +it is easily incorporated onto the command line: + +@example +... +eval ./amd -r $dmn -w 240 -l "$LOGFILE" `ypcat -k auto.master` +@end example + +@node Stopping Amd, Controlling Amd, Starting Amd, Run-time Administration +@comment node-name, next, previous, up +@section Stopping @i{Amd} +@cindex Stopping Amd +@cindex SIGTERM signal +@cindex SIGINT signal + +@i{Amd} stops in response to two signals. + +@table @samp +@item SIGTERM +causes the top-level automount points to be unmounted and then @i{Amd} +to exit. Any automounted filesystems are left mounted. They can be +recovered by restarting @i{Amd} with the ``-r'' command line option.@refill + +@item SIGINT +causes @i{Amd} to attempt to unmount any filesystems which it has +automounted, in addition to the actions of @samp{SIGTERM}. This signal +is primarly used for debugging.@refill +@end table + +Actions taken for other signals are undefined. + +@node Controlling Amd, , Stopping Amd, Run-time Administration +@comment node-name, next, previous, up +@section Controlling @i{Amd} +@cindex Controlling Amd +@cindex Discovering what is going on at run-time +@cindex Listing currently mounted filesystems + +It is sometimes desirable or necessary to exercise external control +over some of @i{Amd}'s internal state. To support this requirement, +@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. +A variety of information is available. + +@i{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. +@end menu + +@node Amq default, Amq -f option, Controlling Amd, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} default information + +With no arguments, @dfn{Amq} obtains a brief list of all existing +mounts created by @i{Amd}. This is different from the list displayed by +@b{df}(1) since the latter only includes system mount points. + +@noindent +The output from this option includes the following information: + +@itemize @bullet +@item +the automount point, +@item +the filesystem type, +@item +the mount map or mount information, +@item +the internal, or system mount point. +@end itemize + +@noindent +For example: + +@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 +@end example + +@noindent +If an argument is given then statistics for that volume name will +be output. For example: + +@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 +@end example + +@table @code +@item What +the volume name. + +@item Uid +ignored. + +@item Getattr +the count of NFS @dfn{getattr} requests on this node. This should only be +non-zero for directory nodes. + +@item Lookup +the count of NFS @dfn{lookup} requests on this node. This should only be +non-zero for directory nodes. + +@item RdDir +the count of NFS @dfn{readdir} requests on this node. This should only +be non-zero for directory nodes. + +@item RdLnk +the count of NFS @dfn{readlink} requests on this node. This should be +zero for directory nodes. + +@item Statfs +the could of NFS @dfn{statfs} requests on this node. This should only +be non-zero for top-level automount points. + +@item Mounted@@ +the date and time the volume name was first referenced. +@end table + +@node Amq -f option, Amq -h option, Amq default, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -f option +@cindex Flushing the map cache +@cindex Map cache, flushing + +The ``-f'' option causes @i{Amd} to flush the internal mount map cache. +This is useful for Hesiod maps since @i{Amd} will not automatically +notice when they have been updated. The map cache can also be +synchronised with the map source by using the @samp{sync} option +(@pxref{Automount Filesystem}).@refill + +@node Amq -h option, Amq -m option, Amq -f option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -h option +@cindex Querying an alternate host + +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 @i{Amd} will +be running. To query @i{Amd} on another host the ``-h'' option should +be used. + +@node Amq -m option, Amq -M-option, Amq -h option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -m option + +The ``-m'' option displays similar information about mounted +filesystems, rather than automount points. The output includes the +following information: + +@itemize @bullet +@item +the mount information, +@item +the mount point, +@item +the filesystem type, +@item +the number of references to this filesystem, +@item +the server hostname, +@item +the state of the file server, +@item +any error which has occured. +@end itemize + +For example: + +@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 +@end example + +When the reference count is zero the filesystem is not mounted but +the mount point and server information is still being maintained +by @i{Amd}. + +@node Amq -M-option, Amq -s option, Amq -m option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -M option + +The ``-M'' option passes a new map entry to @i{Amd} and waits for it to +be evaluated, possibly causing a mount. For example, the following +command would cause @samp{/home/toytown} on host @samp{toytown} to be +mounted locally on @samp{/mnt/toytown}. + +@example +amq -M '/mnt/toytown type:=nfs;rfs:=/home/toytown;rhost:=toytown;fs:=$@{key@}' +@end example + +@i{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 @i{Amd} will include code to allow the @b{mount}(8) +command to mount automount points: + +@example +mount -t amd /vol hesiod.vol +@end example + +This will then allow @i{Amd} to be controlled from the standard system +filesystem mount list. + +@node Amq -s option, Amq -u option, Amq -M-option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -s option +@cindex Global statistics +@cindex Statistics + +The ``-s'' option displays global statistics. If any other options are specified +or any filesystems named then this option is ignored. For example: + +@example +requests stale mount mount unmount +deferred fhandles ok failed failed +1054 1 487 290 7017 +@end example + +@table @samp +@item Deferred requests +are those for which an immediate reply could not be constructed. For +example, this would happen if a background mount was required. + +@item Stale filehandles +counts the number of times the kernel passes a stale filehandle to @i{Amd}. +Large numbers indicate problems. + +@item Mount ok +counts the number of automounts which were successful. + +@item Mount failed +counts the number of automounts which failed. + +@item 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. +@end table + +@node Amq -u option, Amq -v option, Amq -s option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -u option +@cindex Forcing filesystem to time out +@cindex Unmounting a filesystem + +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 @samp{nounmount} +flag. + +@c The ``-H'' option informs @i{Amd} that the specified mount point has hung - +@c as if its keepalive timer had expired. + +@node Amq -v option, Other Amq options, Amq -u option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} -v option +@cindex Version information at run-time + +The ``-v'' option displays the version of @i{Amd} in a similar way to +@i{Amd}'s ``-v'' option. + +@node Other Amq options, , Amq -v option, Controlling Amd +@comment node-name, next, previous, up +@subsection Other @i{Amq} options + +Three other operations are implemented. These modify the state of +@i{Amd} as a whole, rather than any particular filesystem. The ``-l'', +``-x'' and ``-D'' options have exactly the same effect as @i{Amd}'s +corresponding command line options. The ``-l'' option is rejected by +@i{Amd} in the current version for obvious security reasons. When +@i{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 @emph{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. + +@node FSinfo, Examples, Run-time Administration, Top +@comment node-name, next, previous, up +@chapter FSinfo +@cindex FSinfo +@cindex Filesystem info package + +@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:: +@end menu + +@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo +@comment node-name, next, previous, up +@section @i{FSinfo} overview +@cindex FSinfo overview + +@i{FSinfo} is a filesystem management tool. It has been designed to +work with @i{Amd} to help system administrators keep track of the ever +increasing filesystem namespace under their control. + +The purpose of @i{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 +@i{Amd} maps which can be used amongst the set of hosts described in the +input data. + +@i{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. @i{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 @file{/etc/fstab}, +@file{/etc/exports}, @i{Amd} mount maps and +@file{/etc/bootparams}.@refill + +@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo +@comment node-name, next, previous, up +@section Using @i{FSinfo} +@cindex Using FSinfo + +The basic strategy when using @i{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: + +@itemize @bullet +@item +Hostname +@item +List of all filesystems and, optionally, their mount points. +@item +Names of volumes stored on each filesystem. +@item +NFS export information for each volume. +@item +The list of static filesystem mounts. +@end itemize + +The following information can also be entered into the same +configuration files so that all data can be kept in one place. + +@itemize @bullet +@item +List of network interfaces +@item +IP address of each interface +@item +Hardware address of each interface +@item +Dumpset to which each filesystem belongs +@item +and more @dots{} +@end itemize + +To generate @i{Amd} mount maps, the automount tree must also be defined +(@pxref{FSinfo automount definitions}). This will have been designed at +the time the volume names were allocated. Some volume names will not be +automounted, so @i{FSinfo} needs an explicit list of which volumes +should be automounted.@refill + +Hostnames are required at several places in the @i{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 @i{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. + +@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo +@comment node-name, next, previous, up +@section @i{FSinfo} grammar +@cindex FSinfo grammar +@cindex Grammar, FSinfo + +@i{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, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more +@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one +@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input +tokens. Items in angle brackets, @i{eg} @var{<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 ``@t{\}'' 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. + +@example +fsinfo : @i{list(}fsinfo_attr@i{)} ; + +fsinfo_attr : host | automount ; +@end example + +@menu +* FSinfo host definitions:: +* FSinfo automount definitions:: +@end menu + +@node FSinfo host definitions, FSinfo host attributes, FSinfo grammar, FSinfo +@comment node-name, next, previous, up +@section @i{FSinfo} host definitions +@cindex FSinfo host definitions +@cindex Defining a host, FSinfo + +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. + +@example +host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; +@end example + +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 @dfn{host data}. + +All the disks the machine has should then be described in the @dfn{list +of filesystems}. When describing disks, you can specify what +@dfn{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 @dfn{list of mounts} specifies all the filesystems that should be +statically mounted on the machine. + +@menu +* FSinfo host attributes:: +* FSinfo filesystems:: +* FSinfo static mounts:: +@end menu + +@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions +@comment node-name, next, previous, up +@section @i{FSinfo} host attributes +@cindex FSinfo host attributes +@cindex Defining host attributes, FSinfo + +The host data, @dfn{host_data}, always includes the @dfn{hostname}. In +addition, several other host attributes can be given. + +@example +host_data : @var{<hostname>} + | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} + ; + +host_attrs : host_attr "=" @var{<string>} + | netif + ; + +host_attr : "config" + | "arch" + | "os" + | "cluster" + ; +@end example + +The @dfn{hostname} is, typically, the fully qualified hostname of the +machine. + +Examples: + +@example +host dylan.doc.ic.ac.uk + +host @{ + os = hpux + arch = hp300 +@} dougal.doc.ic.ac.uk +@end example + +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: +@end menu + +@node FSinfo host netif, FSinfo host config, , FSinfo host attributes +@comment node-name, next, previous, up +@subsection netif Option + +This defines the set of network interfaces configured on the machine. +The interface attributes collected by @i{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. + +@example +netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; + +netif_attrs : netif_attr "=" @var{<string>} ; + +netif_attr : "inaddr" | "netmask" | "hwaddr" ; +@end example + +Examples: + +@example +netif ie0 @{ + inaddr = 129.31.81.37 + netmask = 0xfffffe00 + hwaddr = "08:00:20:01:a6:a5" +@} + +netif ec0 @{ @} +@end example + +@node FSinfo host config, FSinfo host arch, FSinfo host netif, FSinfo host attributes +@comment node-name, next, previous, up +@subsection config Option +@cindex FSinfo config host attribute +@cindex config, FSinfo host attribute + +This option allows you to specify configuration variables for the +startup scripts (@file{rc} scripts). A simple string should immediately +follow the keyword. + +Example: + +@example +config "NFS_SERVER=true" +config "ZEPHYR=true" +@end example + +This option is currently unsupported. + +@node FSinfo host arch, FSinfo host os, FSinfo host config, FSinfo host attributes +@comment node-name, next, previous, up +@subsection arch Option +@cindex FSinfo arch host attribute +@cindex arch, FSinfo host attribute + +This defines the architecture of the machine. For example: + +@example +arch = hp300 +@end example + +This is intended to be of use when building architecture specific +mountmaps, however, the option is currently unsupported. + +@node FSinfo host os, FSinfo host cluster, FSinfo host arch, FSinfo host attributes +@comment node-name, next, previous, up +@subsection os Option +@cindex FSinfo os host attribute +@cindex os, FSinfo host attribute + +This defines the operating system type of the host. For example: + +@example +os = hpux +@end example + +This information is used when creating the @file{fstab} files, for +example in choosing which format to use for the @file{fstab} entries +within the file. + +@node FSinfo host cluster, , FSinfo host os, FSinfo host attributes +@comment node-name, next, previous, up +@subsection cluster Option +@cindex FSinfo cluster host attribute +@cindex cluster, FSinfo host attribute + +This is used for specifying in which cluster the machine belongs. For +example: + +@example +cluster = "theory" +@end example + +The cluster is intended to be used when generating the automount maps, +although it is currently unsupported. + +@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions +@comment node-name, next, previous, up +@section @i{FSinfo} filesystems +@cindex 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 @samp{fsck} pass number which are needed to generate +@file{fstab} entries. + +@example +filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; + +fs_data : fs_data_attr "=" @var{<string>} + | mount + ; + +fs_data_attr + : "fstype" | "opts" | "passno" + | "freq" | "dumpset" | "log" + ; +@end example + +Here, @var{<device>} is the device name of the disk (for example, +@file{/dev/dsk/2s0}). The device name is used for building the mount +maps and for the @file{fstab} file. The attributes that can be +specified are shown in the following section. + +The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. + +@example +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 + @} +@} +@end example + +@menu +* fstype Option: FSinfo filesystems fstype: +* opts Option: FSinfo filesystems opts: +* passno Option: FSinfo filesystems passno: +* freq Option: FSinfo filesystems freq: +* mount Option: FSinfo filesystems mount: +* dumpset Option: FSinfo filesystems dumpset: +* log Option: FSinfo filesystems log: +@end menu + +@node FSinfo filesystems fstype, FSinfo filesystems opts, , FSinfo filesystems +@comment node-name, next, previous, up +@subsection fstype Option +@cindex FSinfo fstype filesystems option +@cindex fstype, FSinfo filesystems option +@cindex export, FSinfo special fstype + +This specifies the type of filesystem being declared and will be placed +into the @file{fstab} file as is. The value of this option will be +handed to @code{mount} as the filesystem type---it should have such +values as @code{4.2}, @code{nfs} or @code{swap}. The value is not +examined for correctness. + +There is one special case. If the filesystem type is specified as +@samp{export} then the filesystem information will not be added to the +host's @file{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 @i{FSinfo}. + +Example: + +@example +fstype = swap +@end example + +@node FSinfo filesystems opts, FSinfo filesystems passno,FSinfo filesystems fstype, FSinfo filesystems +@comment node-name, next, previous, up +@subsection opts Option +@cindex FSinfo opts filesystems option +@cindex opts, FSinfo filesystems option + +This defines any options that should be given to @b{mount}(8) in the +@file{fstab} file. For example: + +@example +opts = rw,nosuid,grpid +@end example + +@node FSinfo filesystems passno, FSinfo filesystems freq, FSinfo filesystems opts, FSinfo filesystems +@comment node-name, next, previous, up +@subsection passno Option +@cindex FSinfo passno filesystems option +@cindex passno, FSinfo filesystems option + +This defines the @b{fsck}(8) pass number in which to check the +filesystem. This value will be placed into the @file{fstab} file. + +Example: + +@example +passno = 1 +@end example + +@node FSinfo filesystems freq, FSinfo filesystems mount, FSinfo filesystems passno, FSinfo filesystems +@comment node-name, next, previous, up +@subsection freq Option +@cindex FSinfo freq filesystems option +@cindex freq, FSinfo filesystems option + +This defines the interval (in days) between dumps. The value is placed +as is into the @file{fstab} file. + +Example: + +@example +freq = 3 +@end example + +@node FSinfo filesystems mount, FSinfo filesystems dumpset, FSinfo filesystems freq, FSinfo filesystems +@comment node-name, next, previous, up +@subsection mount Option +@cindex FSinfo mount filesystems option +@cindex mount, FSinfo filesystems option +@cindex exportfs, FSinfo mount option +@cindex volname, FSinfo mount option +@cindex sel, FSinfo mount option + +This defines the mountpoint at which to place the filesystem. If the +mountpoint of the filesystem is specified as @code{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 @code{exportfs}, +@code{volname} and @code{sel}. + +The format is: + +@example +mount : "mount" vol_tree ; + +vol_tree : @i{list(}vol_tree_attr@i{)} ; + +vol_tree_attr + : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; + +vol_tree_info + : "exportfs" @var{<export-data>} + | "volname" @var{<volname>} + | "sel" @var{<selector-list>} + ; +@end example + +Example: + +@example +mount default @{ + exportfs "dylan dougal florence zebedee" + volname /vol/andrew +@} +@end example + +In the above example, the filesystem currently being declared will have +an entry placed into the @file{exports} file allowing the filesystem to +be exported to the machines @code{dylan}, @code{dougal}, @code{florence} +and @code{zebedee}. The volume name by which the filesystem will be +referred to remotely, is @file{/vol/andrew}. By declaring the +mountpoint to be @code{default}, the filesystem will be mounted on the +local machine in the automounter tree, where @i{Amd} will automatically +inherit the mount as @file{/vol/andrew}.@refill + +@table @samp +@item exportfs +a string defining which machines the filesystem may be exported to. +This is copied, as is, into the @file{exports} file---no sanity checking +is performed on this string.@refill + +@item 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.@refill + +@item sel +a string which is placed into the automounter maps as a selector for the +filesystem.@refill + +@end table + +@node FSinfo filesystems dumpset, FSinfo filesystems log, FSinfo filesystems mount, FSinfo filesystems +@comment node-name, next, previous, up +@subsection dumpset Option +@cindex FSinfo dumpset filesystems option +@cindex dumpset, FSinfo filesystems option + +This provides support for Imperial College's local file backup tools and +is not documented further here. + +@node FSinfo filesystems log, , FSinfo filesystems dumpset, FSinfo filesystems +@comment node-name, next, previous, up +@subsection log Option +@cindex FSinfo log filesystems option +@cindex log, FSinfo filesystems option + +Specifies the log device for the current filesystem. This is ignored if +not required by the particular filesystem type. + +@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions +@comment node-name, next, previous, up +@section @i{FSinfo} static mounts +@cindex FSinfo static mounts +@cindex Statically mounts filesystems, FSinfo + +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 @code{fs} declarations. In this case the @code{mount} +declaration is used to determine from where its filesystems will be +mounted. In addition to being added to the @file{fstab} file, this +information can also be used to generate a suitable @file{bootparams} +file.@refill + +@example +mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; + +localinfo : localinfo_attr @var{<string>} ; + +localinfo_attr + : "as" + | "from" + | "fstype" + | "opts" + ; +@end example + +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: +@table @samp +@item from @var{machine} +mount the filesystem from the machine with the hostname of +@dfn{machine}.@refill + +@item as @var{mountpoint} +mount the filesystem locally as the name given, in case this is +different from the advertised volume name of the filesystem. + +@item opts @var{options} +native @b{mount}(8) options. + +@item fstype @var{type} +type of filesystem to be mounted. +@end table + +An example: + +@example +mount /export/exec/hp300/local as /usr/local +@end example + +If the mountpoint specified is either @file{/} or @file{swap}, the +machine will be considered to be booting off the net and this will be +noted for use in generating a @file{bootparams} file for the host which +owns the filesystems. + +@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo +@comment node-name, next, previous, up +@section Defining an @i{Amd} Mount Map in @i{FSinfo} +@cindex FSinfo automount definitions +@cindex Defining an Amd mount map, FSinfo + +The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining +all the automount trees. @i{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 +@code{automount} declaration is needed for each @i{Amd} automount point. +@i{FSinfo} determines whether the automount point is @dfn{direct} +(@pxref{Direct Automount Filesystem}) or @dfn{indirect} +(@pxref{Top-level Filesystem}). Direct automount points are +distinguished by the fact that there is no underlying +@dfn{automount_tree}.@refill + +@example +automount : "automount" opt(auto_opts@i{)} automount_tree ; + +auto_opts : "opts" @var{<mount-options>} ; + +automount_tree + : @i{list(}automount_attr@i{)} + ; + +automount_attr + : @var{<string>} "=" @var{<volname>} + | @var{<string>} "->" @var{<symlink>} + | @var{<string>} "@{" automount_tree "@}" + ; +@end example + +If @var{<mount-options>} is given, then it is the string to be placed in +the maps for @i{Amd} for the @code{opts} option. + +A @dfn{map} is typically a tree of filesystems, for example @file{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 @file{/vol}, the +following map would be defined: + +@example +automount /vol @{ @} +@end example + +Within a tree, the only items that can appear are more maps. +For example: + +@example +automount /vol @{ + andrew @{ @} + X11 @{ @} +@} +@end example + +In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} +and @file{/vol/X11} and a map entry will be generated for each. If the +volumes are defined more than once, then @i{FSinfo} will generate +a series of alternate entries for them in the maps.@refill + +Instead of a tree, either a link (@var{name} @code{->} +@var{destination}) or a reference can be specified (@var{name} @code{=} +@var{destination}). A link creates a symbolic link to the string +specified, without further processing the entry. A reference will +examine the destination filesystem and optimise the reference. For +example, to create an entry for @code{njw} in the @file{/homes} map, +either of the two forms can be used:@refill + +@example +automount /homes @{ + njw -> /home/dylan/njw +@} +@end example + +or + +@example +automount /homes @{ + njw = /home/dylan/njw +@} +@end example + +In the first example, when @file{/homes/njw} is referenced from @i{Amd}, +a link will be created leading to @file{/home/dylan/njw} and the +automounter will be referenced a second time to resolve this filename. +The map entry would be: + +@example +njw type:=link;fs:=/home/dylan/njw +@end example + +In the second example, the destination directory is analysed and found +to be in the filesystem @file{/home/dylan} which has previously been +defined in the maps. Hence the map entry will look like: + +@example +njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw +@end example + +Creating only one symbolic link, and one access to @i{Amd}. + +@c --------------------------------------------- +@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo +@comment node-name, next, previous, up +@section @i{FSinfo} Command Line Options +@cindex FSinfo command line options +@cindex Command line options, FSinfo + +@i{FSinfo} is started from the command line by using the command: + +@example +fsinfo [@i{options}] files ... +@end example + +The input to @i{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 +@file{bootparams} file are in the latter class. To put the output into +a subdirectory simply put a @file{/} at the end of the prefix, making +sure that the directory has already been made before running +@samp{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. +@end menu + +@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-a} @var{autodir} + +Specifies the directory name in which to place the automounter's +mountpoints. This defaults to @file{/a}. Some sites have the autodir set +to be @file{/amd}, and this would be achieved by: + +@example +fsinfo -a /amd ... +@end example + +@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-b} @var{bootparams} +@cindex bootparams, FSinfo prefix + +This specifies the prefix for the @file{bootparams} filename. If it is +not given, then the file will not be generated. The @file{bootparams} +file will be constructed for the destination machine and will be placed +into a file named @file{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 @file{bootparams} file in the directory +@file{generic}, the following would be used: + +@example +fsinfo -b generic/ ... +@end example + +@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-d} @var{dumpsets} +@cindex dumpset, FSinfo prefix + +This specifies the prefix for the @file{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 +@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is +for use by Imperial College's local backup system. + +For example, to create a dumpsets file in the directory @file{generic}, +then you would use the following: + +@example +fsinfo -d generic/ ... +@end example + +@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-e} @var{exportfs} +@cindex exports, FSinfo prefix + +Defines the prefix for the @file{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 @file{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 +@file{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 @file{exports} files for each diskful machine +and place them into the directory @file{exports}: + +@example +fsinfo -e exports/ ... +@end example + +@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-f} @var{fstab} +@cindex fstab, FSinfo prefix + +This defines the prefix for the @file{fstab} files. The files will only +be created if this prefix is defined. For each machine defined in the +configuration files, a @file{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 @file{fstabs}: + +@example +fsinfo -f fstabs/ ... +@end example + +@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-h} @var{hostname} +@cindex hostname, FSinfo command line option + +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 +@b{gethostname}(2). + +Example: + +@example +fsinfo -h dylan.doc.ic.ac.uk ... +@end example + +@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-m} @var{mount-maps} +@cindex maps, FSinfo command line option + +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 @file{automaps}: + +@example +fsinfo -m automaps/ ... +@end example + +@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-q} +@cindex quiet, FSinfo command line option + +Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and +only outputs any error messages which are generated. + +@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-v} +@cindex verbose, FSinfo command line option + +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 @file{stdout} on a line starting with a @samp{#} character. + +@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-D} @var{name[=defn]} + +Defines a symbol @dfn{name} for the preprocessor when reading the +configuration files. Equivalent to @code{#define} directive. + +@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-I} @var{directory} + +This option is passed into the preprocessor for the configuration files. +It specifies directories in which to find include files + +@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options +@comment node-name, next, previous, up +@subsection @code{-U} @var{name} + +Removes any initial definition of the symbol @dfn{name}. Inverse of the +@code{-D} option. + +@node FSinfo errors, , FSinfo command line options, FSinfo +@comment node-name, next, previous, up +@section Errors produced by @i{FSinfo} +@cindex FSinfo error messages + +The following table documents the errors and warnings which @i{FSinfo} may produce. + +@table @t + +@item can't open @var{filename} for writing +Occurs if any errors are encountered when opening an output file.@refill + +@item unknown host attribute +Occurs if an unrecognised keyword is used when defining a host.@refill + +@item unknown filesystem attribute +Occurs if an unrecognised keyword is used when defining a host's +filesystems.@refill + +@item not allowed '/' in a directory name +When reading the configuration input, if there is a filesystem +definition which contains a pathname with multiple directories for any +part of the mountpoint element, and it is not a single absolute path, +then this message will be produced by the parser.@refill + +@item unknown directory attribute +If an unknown keyword is found while reading the definition of a hosts's +filesystem mount option. + +@item unknown mount attribute +Occurs if an unrecognised keyword is found while parsing the list of +static mounts.@refill + +@item " expected +Occurs if an unescaped newline is found in a quoted string. + +@item unknown \ sequence +Occurs if an unknown escape sequence is found inside a string. Within a +string, you can give the standard C escape sequences for strings, such +as newlines and tab characters.@refill + +@item @var{filename}: cannot open for reading +If a file specified on the command line as containing configuration data +could not be opened.@refill + +@item end of file within comment +A comment was unterminated before the end of one of the configuration +files. + +@item host field "@var{field-name}" already set +If duplicate definitions are given for any of the fields with a host +definition. + +@item duplicate host @var{hostname}! +If a host has more than one definition. + +@item netif field @var{field-name} already set +Occurs if you attempt to define an attribute of an interface more than +once. + +@item malformed IP dotted quad: @var{address} +If the Internet address of an interface is incorrectly specified. An +Internet address definition is handled to @b{inet_addr}(3N) to see if it +can cope. If not, then this message will be displayed. + +@item malformed netmask: @var{netmask} +If the netmask cannot be decoded as though it were a hexadecimal number, +then this message will be displayed. It will typically be caused by +incorrect characters in the @var{netmask} value.@refill + +@item fs field "@var{field-name}" already set +Occurs when multiple definitions are given for one of the attributes of a +host's filesystem. + +@item mount tree field "@var{field-name}" already set +Occurs when the @var{field-name} is defined more than once during the +definition of a filesystems mountpoint. + +@item mount field "@var{field-name}" already set +Occurs when a static mount has multiple definitions of the same field. + +@item no disk mounts on @var{hostname} +If there are no static mounts, nor local disk mounts specified for a +machine, this message will be displayed. + +@item @var{host}:@var{device} needs field "@var{field-name}" +Occurs when a filesystem is missing a required field. @var{field-name} could +be one of @code{fstype}, @code{opts}, @code{passno} or +@code{mount}.@refill + +@item @var{filesystem} has a volname but no exportfs data +Occurs when a volume name is declared for a file system, but the string +specifying what machines the filesystem can be exported to is +missing. + +@item sub-directory @var{directory} of @var{directory-tree} starts with '/' +Within the filesystem specification for a host, if an element +@var{directory} of the mountpoint begins with a @samp{/} and it is not +the start of the tree.@refill + +@item @var{host}:@var{device} has no mount point +Occurs if the @samp{mount} option is not specified for a host's +filesystem.@refill + +@item @var{host}:@var{device} has more than one mount point +Occurs if the mount option for a host's filesystem specifies multiple +trees at which to place the mountpoint.@refill + +@item no volname given for @var{host}:@var{device} +Occurs when a filesystem is defined to be mounted on @file{default}, but +no volume name is given for the file system, then the mountpoint cannot +be determined.@refill + +@item @var{host}:mount field specified for swap partition +Occurs if a mountpoint is given for a filesystem whose type is declared +to be @code{swap}.@refill + +@item ambiguous mount: @var{volume} is a replicated filesystem +If several filesystems are declared as having the same volume name, they +will be considered replicated filesystems. To mount a replicated +filesystem statically, a specific host will need to be named, to say +which particular copy to try and mount, else this error will +result.@refill + +@item cannot determine localname since volname @var{volume} is not uniquely defined +If a volume is replicated and an attempt is made to mount the filesystem +statically without specifying a local mountpoint, @i{FSinfo} cannot +calculate a mountpoint, as the desired pathname would be +ambiguous.@refill + +@item volname @var{volume} is unknown +Occurs if an attempt is made to mount or reference a volume name which +has not been declared during the host filesystem definitions.@refill + +@item volname @var{volume} not exported from @var{machine} +Occurs if you attempt to mount the volume @var{volume} from a machine +which has not declared itself to have such a filesystem +available.@refill + +@item network booting requires both root and swap areas +Occurs if a machine has mount declarations for either the root partition +or the swap area, but not both. You cannot define a machine to only +partially boot via the network.@refill + +@item unknown volname @var{volume} automounted @i{[} on <name> @i{]} +Occurs if @var{volume} is used in a definition of an automount map but the volume +name has not been declared during the host filesystem definitions.@refill + +@item not allowed '/' in a directory name +Occurs when a pathname with multiple directory elements is specified as +the name for an automounter tree. A tree should only have one name at +each level. + +@item @var{device} has duplicate exportfs data +Produced if the @samp{exportfs} option is used multiple times within the +same branch of a filesytem definition. For example, if you attempt to +set the @samp{exportfs} data at different levels of the mountpoint +directory tree.@refill + +@item sub-directory of @var{directory-tree} is named "default" +@samp{default} is a keyword used to specify if a mountpoint should be +automatically calculated by @i{FSinfo}. If you attempt to specify a +directory name as this, it will use the filename of @file{default} but +will produce this warning.@refill + +@item pass number for @var{host}:@var{device} is non-zero +Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} +or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices should not be +fsck'd. @xref{FSinfo filesystems fstype}@refill + +@item dump frequency for @var{host}:@var{device} is non-zero +Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} +or @samp{export} and the @samp{dump} option is set to a value greater +than zero. Swap devices should not be dumped.@refill + +@end table + +@node Examples, Internals, FSinfo, Top +@comment node-name, next, previous, up +@chapter Examples + +@menu +* User Filesystems:: +* Home Directories:: +* Architecture Sharing:: +* Wildcard names:: +* rwho servers:: +* /vol:: +@end menu + +@node User Filesystems, Home Directories, Examples, Examples +@comment node-name, next, previous, up +@section User Filesystems +@cindex User filesystems +@cindex Mounting user filesystems + +With more than one fileserver, the directories most frequently +cross-mounted are those containing user home directories. A common +convention used at Imperial College is to mount the user disks under +@t{/home/}@i{machine}. + +Typically, the @samp{/etc/fstab} file contained a long list of entries +such as: + +@example +@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... +@end example + +for each fileserver on the network. + +There are numerous problems with this system. The mount list can become +quite large and some of the machines may be down when a system is +booted. When a new fileserver is installed, @samp{/etc/fstab} must be +updated on every machine, the mount directory created and the filesystem +mounted. + +In many environments most people use the same few workstations, but +it is convenient to go to a colleague's machine and access your own +files. When a server goes down, it can cause a process on a client +machine to hang. By minimising the mounted filesystems to only include +those actively being used, there is less chance that a filesystem will +be mounted when a server goes down. + +The following is a short extract from a map taken from a research fileserver +at Imperial College. + +Note the entry for @samp{localhost} which is used for users such as +the operator (@samp{opr}) who have a home directory on most machine as +@samp{/home/localhost/opr}. + +@example +/defaults opts:=rw,intr,grpid,nosuid +charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ + host==$@{key@};type:=ufs;dev:=/dev/xd0g +# +... + +# +localhost type:=link;fs:=$@{host@} +... +# +# dylan has two user disks so have a +# top directory in which to mount them. +# +dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ +# +dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ + host==dylan;type:=ufs;dev:=/dev/dsk/2s0 +# +dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ + host==dylan;type:=ufs;dev:=/dev/dsk/5s0 +... +# +toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ + host==$@{key@};type:=ufs;dev:=/dev/xy1g +... +# +zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ + host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 +# +# Just for access... +# +gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ +gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} +# +gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} +... +@end example + +This map is shared by most of the machines listed so on those +systems any of the user disks is accessible via a consistent name. +@i{Amd} is started with the following command + +@example +amd /home amd.home +@end example + +Note that when mounting a remote filesystem, the @dfn{automounted} +mount point is referenced, so that the filesystem will be mounted if +it is not yet (at the time the remote @samp{mountd} obtains the file handle). + +@node Home Directories, Architecture Sharing, User Filesystems, Examples +@comment node-name, next, previous, up +@section Home Directories +@cindex Home directories +@cindex Example of mounting home directories +@cindex Mount home directories + +One convention for home directories is to locate them in @samp{/homes} +so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more +than a single fileserver it is convenient to spread user files across +several machines. All that is required is a mount-map which converts +login names to an automounted directory. + +Such a map might be started by the command: + +@example +amd /homes amd.homes +@end example + +where the map @samp{amd.homes} contained the entries: + +@example +/defaults type:=link # All the entries are of type:=link +jsp fs:=/home/charm/jsp +njw fs:=/home/dylan/dk5/njw +... +phjk fs:=/home/toytown/ai/phjk +sjv fs:=/home/ganymede/sjv +@end example + +Whenever a login name is accessed in @samp{/homes} a symbolic link +appears pointing to the real location of that user's home directory. In +this example, @samp{/homes/jsp} would appear to be a symbolic link +pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also +be an automount point. + +This system causes an extra level of symbolic links to be used. +Although that turns out to be relatively inexpensive, an alternative is +to directly mount the required filesystems in the @samp{/homes} +map. The required map is simple, but long, and its creation is best automated. +The entry for @samp{jsp} could be: + +@example +jsp -sublink:=$@{key@};rfs:=/home/charm \ + host==charm;type:=ufs;dev:=/dev/xd0g \ + host!=charm;type:=nfs;rhost:=charm +@end example + +This map can become quite big if it contains a large number of entries. +By combining two other features of @i{Amd} it can be greatly simplified. + +First the UFS partitions should be mounted under the control of +@samp{/etc/fstab}, taking care that they are mounted in the same place +that @i{Amd} would have automounted them. In most cases this would be +something like @samp{/a/@dfn{host}/home/@dfn{host}} and +@samp{/etc/fstab} on host @samp{charm} would have a line:@refill + +@example +/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 +@end example + +The map can then be changed to: + +@example +/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid +jsp rhost:=charm;rfs:=/home/charm +njw rhost:=dylan;rfs:=/home/dylan/dk5 +... +phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} +sjv rhost:=ganymede;rfs:=/home/ganymede +@end example + +This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} +not equal to @code{$@{rhost@}}). On the machine where the filesystem is +stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} +will construct a local filesystem mount point which corresponds to the +name of the locally mounted UFS partition. If @i{Amd} is started with +the ``-r'' option then instead of attempting an NFS mount, @i{Amd} will +simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If +``-r'' is not used then a loopback NFS mount will be made. This type of +mount is known to cause a deadlock on many systems. + +@node Architecture Sharing, Wildcard Names, Home Directories, Examples +@comment node-name, next, previous, up +@section Architecture Sharing +@cindex Architecture sharing +@cindex Sharing a fileserver between architectures +@cindex Architecture dependent volumes + +@c %At the moment some of the research machines have sets of software +@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, +@c %system sources, local sources, prolog libraries and so on. +Often a filesystem will be shared by machines of different architectures. +Separate trees can be maintained for the executable images for each +architecture, but it may be more convenient to have a shared tree, +with distinct subdirectories. + +A shared tree might have the following structure on the fileserver (called +@samp{fserver} in the example): + +@example +local/tex +local/tex/fonts +local/tex/lib +local/tex/bin +local/tex/bin/sun3 +local/tex/bin/sun4 +local/tex/bin/hp9000 +... +@end example + +In this example, the subdirectories of @samp{local/tex/bin} should be +hidden when accessed via the automount point (conventionally @samp{/vol}). +A mount-map for @samp{/vol} to achieve this would look like: + +@example +/defaults sublink:=$@{/key@};rhost:=fserver;type:=link +tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ +tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ + host==fserver;fs:=/usr/local/tex +tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ + host==fserver;fs:=/usr/local/tex +tex/bin -sublink:=$@{/key@}/$@{arch@} host!=fserver;type:=nfs;rfs:=/vol/tex \ + host:=fserver;fs:=/usr/local/tex +@end example + +When @samp{/vol/tex/bin} is referenced, the current machine architecture +is automatically appended to the path by the @code{$@{sublink@}} +variable. This means that users can have @samp{/vol/tex/bin} in their +@samp{PATH} without concern for architecture dependencies. + +@node Wildcard Names, rwho servers, Architecture Sharing, Examples +@comment node-name, next, previous, up +@section Wildcard names & Replicated Servers + +By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing +directory with additional entries. +The system files are usually mounted under @samp{/usr}. If instead +@i{Amd} is mounted on @samp{/usr}, additional +names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. +A map to do this would have the form: + +@example +local type:=auto;fs:=local-map +share type:=auto;fs:=share-map +* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ + rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 +@end example + +Note that the assignment to @code{$@{sublink@}} is surrounded by double +quotes to prevent the incoming key from causing the map to be +misinterpreted. This map has the effect of directing any access to +@samp{/usr/local} or @samp{/usr/share} to another automount point. + +In this example, it is assumed that the @samp{/usr} files are replicated +on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. +For any references other than to @samp{local} and @samp{share} one of +the servers is used and a symbolic link to +@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is +returned once an appropriate filesystem has been mounted.@refill + +@node rwho servers, /vol, Wildcard Names, Examples +@comment node-name, next, previous, up +@section @samp{rwho} servers +@cindex rwho servers +@cindex Architecture specific mounts +@cindex Example of architecture specific mounts + +The @samp{/usr/spool/rwho} directory is a good candidate for automounting. +For efficiency reasons it is best to capture the rwho data on a small +number of machines and then mount that information onto a large number +of clients. The data written into the rwho files is byte order dependent +so only servers with the correct byte ordering can be used by a client: + +@example +/defaults type:=nfs +usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ + rhost:=vaxA rhost:=vaxB \ + || -rfs:=/usr/spool/rwho \ + rhost:=sun4 rhost:=hp300 +@end example + +@node /vol, , rwho servers, Examples +@comment node-name, next, previous, up +@section @samp{/vol} +@cindex /vol +@cindex Catch-all mount point +@cindex Generic volume name + +@samp{/vol} is used as a catch-all for volumes which do not have other +conventional names. + +Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. +The @samp{r+d} tree is used for new or experimental software that needs +to be available everywhere without installing it on all the fileservers. +Users wishing to try out the new software then simply include +@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill + +The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has +different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} +sub-directories for each machine architecture. For example, +@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory +@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed +a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be +returned.@refill + +@example +/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft +wp -opts:=rw,grpid,nosuid;rhost:=charm \ + host==charm;type:=link;fs:=/usr/local/wp \ + host!=charm;type:=nfs;rfs:=/vol/wp +... +# +src -opts:=rw,grpid,nosuid;rhost:=charm \ + host==charm;type:=link;fs:=/usr/src \ + host!=charm;type:=nfs;rfs:=/vol/src +# +r+d type:=auto;fs:=$@{map@};pref:=r+d/ +# per architecture bin,etc,lib&ucb... +r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} +r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} +r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} +r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} +r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} +r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} +r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} +# hades pictures +pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ + host==thpfs;type:=link;fs:=/nbsd/pictures \ + host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures +# hades tools +hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ + host==thpfs;type:=link;fs:=/nbsd/hades \ + host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades +# bsd tools for hp. +bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ + host==thpfs;type:=link;fs:=/nbsd/bsd \ + host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd +@end example + +@node Internals, Acknowledgements & Trademarks, Examples, Top +@comment node-name, next, previous, up +@chapter Internals + +@menu +* Log Messages:: +@end menu + +@node Log Messages, , Internals, Internals +@comment node-name, next, previous, up +@section Log Messages + +In the following sections a brief explanation is given of some of the +log messages made by @i{Amd}. Where the message is in @samp{typewriter} +font, it corresponds exactly to the message produced by @i{Amd}. Words +in @dfn{italic} are replaced by an appropriate string. Variables, +@code{$@{var@}}, indicate that the value of the appropriate variable is +output. + +Log messages are either sent direct to a file, +or logged via the @b{syslog}(3) mechanism. +Messages are logged with facility @samp{LOG_DAEMON} when using @b{syslog}(3). +In either case, entries in the file are of the form: +@example +@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} +@end example + +@menu +* Fatal errors:: +* Info messages:: +@end menu + +@node Fatal errors, Info messages, Log Messages, Log Messages +@comment node-name, next, previous, up +@subsection Fatal errors + +@i{Amd} attempts to deal with unusual events. Whenever it is not +possible to deal with such an error, @i{Amd} will log an appropriate +message and, if it cannot possibly continue, will either exit or abort. +These messages are selected by @samp{-x fatal} on the command line. +When @b{syslog}(3) is being used, they are logged with level +@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to +remain in a precarious state and should be restarted at the earliest +opportunity. + +@table @asis +@item @t{Attempting to inherit not-a-filesystem} +The prototype mount point created during a filesystem restart did not +contain a reference to the restarted filesystem. This erorr ``should +never happen''. + +@item @t{Can't bind to domain "@i{NIS-domain}"} +A specific NIS domain was requested on the command line, but no server +for that domain is available on the local net. + +@item @t{Can't determine IP address of this host (@i{hostname})} +When @i{Amd} starts it determines its own IP address. If this lookup +fails then @i{Amd} cannot continue. The hostname it looks up is that +obtained returned by @b{gethostname}(2) system call. + +@item @t{Can't find root file handle for @i{automount point}} +@i{Amd} creates its own file handles for the automount points. When it +mounts itself as a server, it must pass these file handles to the local +kernel. If the filehandle is not obtainable the mount point is ignored. +This error ``should never happen''. + +@item @t{Must be root to mount filesystems (euid = @i{euid})} +To prevent embarrassment, @i{Amd} makes sure it has appropriate system +privileges. This amounts to having an euid of 0. The check is made +after argument processing complete to give non-root users a chance to +access the ``-v'' option. + +@item @t{No work to do - quitting} +No automount points were given on the command line and so there is no +work to do. + +@item @t{Out of memory in realloc} +While attempting to realloc some memory, the memory space available to +@i{Amd} was exhausted. This is an unrecoverable error. + +@item @t{Out of memory} +While attempting to malloc some memory, the memory space available to +@i{Amd} was exhausted. This is an unrecoverable error. + +@item @t{cannot create rpc/udp service} +Either the NFS or AMQ endpoint could not be created. + +@item @t{gethostname:} @i{description} +The @b{gethostname}(2) system call failed during startup. + +@item @t{host name is not set} +The @b{gethostname}(2) system call returned a zero length host name. +This can happen if @i{Amd} is started in single user mode just after +booting the system. + +@item @t{ifs_match called!} +An internal error occurred while restarting a pre-mounted filesystem. +This error ``should never happen''. + +@item @t{mount_afs:} @i{description} +An error occured while @i{Amd} was mounting itself. + +@item @t{run_rpc failed} +Somehow the main NFS server loop failed. This error ``should never +happen''. + +@item @t{unable to free rpc arguments in amqprog_1} +The incoming arguments to the AMQ server could not be free'ed. + +@item @t{unable to free rpc arguments in nfs_program_1} +The incoming arguments to the NFS server could not be free'ed. + +@item @t{unable to register (AMQ_PROGRAM, AMQ_VERSION, udp)} +The AMQ server could not be registered with the local portmapper or the +internal RPC dispatcher. + +@item @t{unable to register (NFS_PROGRAM, NFS_VERSION, 0)} +The NFS server could not be registered with the internal RPC dispatcher. + +@end table + +@node Info messages, , Fatal errors, Log Messages +@comment node-name, next, previous, up +@subsection Info messages + +@i{Amd} generates information messages to record state changes. These +messages are selected by @samp{-x info} on the command line. When +@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. + +The messages listed below can be generated and are in a format suitable +for simple statistical analysis. @dfn{mount-info} is the string +that is displayed by @dfn{Amq} in its mount information column and +placed in the system mount table. + +@table @asis +@item @t{mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out} +Attempts to mount a filesystem for the given automount point have failed +to complete within 30 seconds. + +@item @t{"@t{$@{@i{path}@}}" forcibly timed out} +An automount point has been timed out by the @i{Amq} command. + +@item @t{restarting @i{mount-info} on @t{$@{@i{fs}@}}} +A pre-mounted file system has been noted. + +@item @t{"@t{$@{@i{path}@}}" has timed out} +No access to the automount point has been made within the timeout +period. + +@item @t{file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored} +An automount point has timed out, but the corresponding file server is +known to be down. This message is only produced once for each mount +point for which the server is down. + +@item @t{Re-synchronizing cache for map @t{$@{@i{map}@}}} +The named map has been modified and the internal cache is being re-synchronized. + +@item @t{Filehandle denied for "@t{$@{@i{rhost}@}}:@t{$@{@i{rfs}@}}"} +The mount daemon refused to return a file handle for the requested filesystem. + +@item @t{Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}":} @i{description} +The mount daemon gave some other error for the requested filesystem. + +@item @t{file server @t{$@{@i{rhost}@}} type nfs starts up} +A new NFS file server has been referenced and is known to be up. + +@item @t{file server @t{$@{@i{rhost}@}} type nfs starts down} +A new NFS file server has been referenced and is known to be down. + +@item @t{file server @t{$@{@i{rhost}@}} type nfs is up} +An NFS file server that was previously down is now up. + +@item @t{file server @t{$@{@i{rhost}@}} type nfs is down} +An NFS file server that was previously up is now down. + +@item @t{Finishing with status @i{exit-status}} +@i{Amd} is about to exit with the given exit status. + +@item @t{@i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}}} +A new file system has been mounted. + +@item @t{@i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}}} +@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. + +@item @t{@i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}}} +A file system has been unmounted. + +@item @t{@i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}}} +A file system of which only a sub-directory was in use has been unmounted. + +@end table + +@node Acknowledgements & Trademarks, Index, Internals, Top +@comment node-name, next, previous, up +@unnumbered Acknowledgements & Trademarks + +Thanks to the Formal Methods Group at Imperial College for +suffering patiently while @i{Amd} was being developed on their machines. + +Thanks to the many people who have helped with the development of +@i{Amd}, especially Piete Brooks at the Cambridge University Computing +Lab for many hours of testing, experimentation and discussion. + +@itemize @bullet +@item +@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital +Equipment Corporation. +@item +@b{AIX} and @b{IBM} are registered trademarks of International Business +Machines Corporation. +@item +@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun +Microsystems, Inc. +@item +@b{Unix} is a registered trademark of AT&T Unix Systems Laboratories +in the USA and other countries. +@end itemize + +@node Index, Intro, Acknowledgements & Trademarks, Top +@comment node-name, next, previous, up +@unnumbered Index + +@printindex cp + +@contents +@bye |