diff options
Diffstat (limited to 'contrib/amd/doc/am-utils.texi')
| -rw-r--r-- | contrib/amd/doc/am-utils.texi | 7816 |
1 files changed, 7816 insertions, 0 deletions
diff --git a/contrib/amd/doc/am-utils.texi b/contrib/amd/doc/am-utils.texi new file mode 100644 index 0000000..ca54503 --- /dev/null +++ b/contrib/amd/doc/am-utils.texi @@ -0,0 +1,7816 @@ +\input texinfo @c -*-texinfo-*- +@c +@c Copyright (c) 1997-1998 Erez Zadok +@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 acknowledgment: +@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 %W% (Berkeley) %G% +@c +@c $Id: am-utils.texi,v 6.0 1997/02/09 15:11:50 ezk beta $ +@c +@setfilename am-utils.info + +@include version.texi + +@c info directory entry +@direntry +* Am-utils: (am-utils). The Amd automounter suite of utilities +@end direntry + +@titlepage +@title Am-utils (4.4BSD Automounter Utilities) +@subtitle For version @value{VERSION}, @value{UPDATED} + +@author Erez Zadok +(Originally by Jan-Simon Pendry and Nick Williams) + +@page +Copyright @copyright{} 1997-1998 Erez Zadok +@* +Copyright @copyright{} 1989 Jan-Simon Pendry +@* +Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine +@* +Copyright @copyright{} 1989 The Regents of the University of California. +@sp +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 + +@c Define a new index for options. +@syncodeindex pg cp +@syncodeindex vr cp + +@ifinfo + +@c ################################################################ +@node Top, License, , (DIR) +Am-utils - The 4.4BSD Automounter Tool Suite +********************************************* + +Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd +automounter, the Amq query and control program, the Hlfsd daemon, and +other tools. This Info file describes how to use and understand the +tools within Am-utils. +@end ifinfo + +@menu +* License:: Explains the terms and conditions for using + and distributing Am-utils. +* Distrib:: How to get the latest Am-utils distribution. +* Intro:: An introduction to Automounting concepts. +* History:: History of am-utils' development. +* 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. +* Amd Configuration File:: The amd.conf file syntax and meaning. +* Run-time Administration:: How to start, stop and control Amd. +* FSinfo:: The FSinfo filesystem management tool. +* Hlfsd:: The Home-Link Filesystem server. +* Assorted Tools:: Other tools which come with am-utils. +* Examples:: Some examples showing how Amd might be used. +* Internals:: Implementation details. +* Acknowledgments & Trademarks:: Legal Notes + +Indexes +* Index:: An item for each concept. +@end menu + +@iftex +@unnumbered Preface + +This manual documents the use of the 4.4BSD automounter tool suite, +which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is +primarily a reference manual. While no tutorial exists, there are +examples available. @xref{Examples}. + +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 texinfo package (a version of which is +available for GNU Emacs).@footnote{GNU packages can be found in +@url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially +the same text and are generated from a common source file, which is +distributed with the @i{Am-utils} source. +@end iftex + +@c ################################################################ +@node License, Distrib, Top, Top +@unnumbered License +@cindex License Information + +@i{Am-utils} is not in the public domain; it is copyrighted and there are +restrictions on its distribution. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +@enumerate + +@item +Redistributions of source code must retain the above copyright notice, +this list of conditions and the following disclaimer. + +@item +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +@item +All advertising materials mentioning features or use of this software +must display the following acknowledgment: + +@cartouche +``This product includes software developed by the University of +California, Berkeley and its contributors, as well as the Trustees of +Columbia University.'' +@end cartouche + +@item +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. + +@end enumerate + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS +BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +THE POSSIBILITY OF SUCH DAMAGE. + +@c ################################################################ +@node Distrib, Intro, License, Top +@unnumbered Source Distribution +@cindex Source code distribution +@cindex Obtaining the source code + +The @i{Am-utils} home page is located in +@example +@url{http://www.cs.columbia.edu/~ezk/am-utils/} +@end example + +You can get the latest distribution version of @i{Am-utils} from +@example +@url{ftp://shekel.mcl.cs.columbia.edu/pub/am-utils/am-utils.tar.gz} +@end example + +Alpha and beta distributions are available in +@example +@url{ftp://shekel.mcl.cs.columbia.edu/pub/am-utils/}. +@end example + +Revision 5.2 was part of the 4.3BSD Reno distribution. + +Revision 5.3bsdnet, a late alpha version of 5.3, was part +of the BSD network version 2 distribution + +Revision 6.0 was made independently by @email{ezk@@cs.columbia.edu,Erez +Zadok} at the @uref{http://www.cs.columbia.edu/,Computer Science +Department} of @uref{http://www.columbia.edu/,Columbia University}, as +part of his @uref{http://www.cs.columbia.edu/~ezk/research/tp/thesis_proposal.html,PhD thesis work}. @xref{History} for more details. + +@unnumberedsec Bug Reports +@cindex Bug reports + +Before reporting a bug, see if it is a known one in the +@uref{http://www.cs.columbia.edu/~ezk/am-utils/BUGS.txt,bugs} file. +Send all bug reports to @email{amd-dev@@majordomo.cs.columbia.edu} +quoting the details of the release and your configuration. These can be +obtained by running the command @samp{amd -v}. It would greatly help if +you could provide a reproducible procedure for detecting the bug you are +reporting. + +Providing working patches is highly encouraged. Every patch +incorporated, however small, will get its author an honorable mention in +the @uref{http://www.cs.columbia.edu/~ezk/am-utils/AUTHORS.txt,authors +file}. + +@unnumberedsec Mailing List +@cindex Mailing list + +There are two mailing lists for people interested in keeping up-to-date +with developments. + +@c ############### + +@enumerate + +@item +The older list, @samp{amd-workers} is for general "how to" questions and +announcements. To subscribe, send a note to +@email{amd-workers-request@@majordomo.glue.umd.edu}.@footnote{Note that +the older address, @email{amd-workers-request@@acl.lanl.gov}, is +defunct.} To post a message to this list, send mail to +@email{amd-workers@@majordomo.glue.umd.edu}. + +@item +The developers only list, @samp{amd-dev} is for + +@itemize @minus +@item +announcements of alpha and beta releases of am-utils +@item +reporting of bugs and patches +@item +discussions of new features for am-utils +@item +implementation and porting issues +@end itemize + +To subscribe, send a note to @email{majordomo@@majordomo.cs.columbia.edu} +with the single body text line @samp{subscribe amd-dev}. To post a +message to this list, send mail to +@email{amd-dev@@majordomo.cs.columbia.edu}. To avoid as much spam as +possible, only subscribers to this list may post to it. + +Subscribers of @samp{amd-dev} are most suitable if they have the time +and resources to test new and buggy versions of amd, on as many +different platforms as possible. They should also be prepared to learn +and use the GNU Autoconf, Automake, and Libtool packages, and of course, +be very familiar with the complex code in the am-utils package. In +other words, subscribers on this list should be able to contribute +meaningfully to the development of amd. + +@end enumerate + +@c ################################################################ +@node Intro, History, 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 thus 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 flavors of Unix. + +@c ################################################################ +@node History, Overview, Intro, Top +@unnumbered History +@cindex History + +The @i{Amd} package has been without an official maintainer since 1992. +Several people have stepped in to maintain it unofficially. Most +notable were the `upl' (Unofficial Patch Level) releases of @i{Amd}, +created by me (@email{ezk@@cs.columbia.edu,Erez Zadok}), and available from +@url{ftp://ftp.cs.columbia.edu/pub/amd/}. The last such unofficial +release was `upl102'. + +Through the process of patching and aging, it was becoming more and more +apparent that @i{Amd} was in much need of revitalizing. Maintaining +@i{Amd} had become a difficult task. I took it upon myself to cleanup +the code, so that it would be easier to port to new platforms, add new +features, keep up with the many new feature requests, and deal with the +never ending stream of bug reports. + +I have been working on such a release of @i{Amd} on and off since +January of 1996. The new suite of tools is currently named "am-utils" +(AutoMounter Utilities), in line with GNU naming conventions, befitting +the contents of the package. In October of 1996 I had received enough +offers to help me with this task that I decided to make a mailing list +for this group of people. Around the same time, @i{Amd} had become a +necessary part of my PhD thesis work, resulting in more work performed +on am-utils. + +Am-utils version 6.0 was numbered with a major new release number to +distinguish it from the last official release of @i{Amd} (5.x). Many +new features have been added such as a GNU @code{configure} system, NFS +Version 3, Autofs support, a run-time configuration file (`amd.conf'), +many new ports, more scripts and programs, as well as numerous bug +fixes. Another reason for the new major release number was to alert +users of am-utils that user-visible interfaces may have changed. In +order to make @i{Amd} work well for the next 10 years, and be easier to +maintain, it was necessary to remove old or unused features, change +various syntax files, etc. However, great care was taken to ensure the +maximum possible backwards compatibility. + +@c ################################################################ +@node Overview, Supported Platforms, History, 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 flavors of Unix. @xref{Supported +Platforms}.@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-organized 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 containing 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 @code{-w} command-line option (@pxref{-w +Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval} +(@pxref{dismount_interval Parameter}). It is also possible to set this +value on a per-mount basis (@pxref{opts Option, opts, opts}). + +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 recognized when an +NFS server crashes and the behavior 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. + +@c ################################################################ +@node Supported Platforms, Mount Maps, Overview, Top +@comment node-name, next, previous, up +@chapter Supported Platforms +@cindex Supported Platforms +@cindex shared libraries +@cindex NFS V.3 support + +@i{Am-utils} has been ported to a wide variety of machines and operating +systems. @i{Am-utils}'s code works for little-endian and big-endian +machines, as well as 32 bit and 64 bit architectures. Furthermore, when +@i{Am-utils} ports to an Operating System on one architecture, it is generally +readily portable to the same Operating System on all platforms on which +it is available. + +The table below lists those platforms supported by the latest release. +The listing is based on the standard output from GNU's +@code{config.guess} script. Since significant changes have been made to +am-utils, not all systems listed here have been verified working for all +features. + +@multitable {Auto-Configured System Name} {Config} {Compile} {Amd} {NFS3} {Shlib} {Hlfsd} + +@item @b{Auto-Configured System Name} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab @b{Config} @tab @b{Compile} @tab @b{Amd} @tab @b{NFS3} @tab @b{Shlib} @tab @b{Hlfsd} + +@item @b{alpha-dec-osf2.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab @tab @tab + +@item @b{alpha-dec-osf4.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab @tab + +@item @b{alphaev5-unknown-linux-gnu} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{hppa1.0-hp-hpux11.00} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab no @tab @tab + +@item @b{hppa1.1-hp-hpux10.10} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab no @tab + +@item @b{hppa1.1-hp-hpux10.20} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab no @tab + +@item @b{hppa1.1-hp-hpux9.01} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{hppa1.1-hp-hpux9.05} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{hppa1.1-hp-hpux9.07} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{i386-pc-bsdi2.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{i386-pc-bsdi3.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{i386-pc-bsdi3.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{i386-pc-solaris2.5.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes + +@item @b{i386-pc-solaris2.6} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes + +@item @b{i386-unknown-freebsd2.1.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{i386-unknown-freebsd2.2.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{i386-unknown-freebsd3.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{i386-unknown-netbsd1.2.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{i386-unknown-netbsd1.3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{i386-unknown-netbsd1.3.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{i386-unknown-openbsd2.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{i486-ncr-sysv4.3.03} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab @tab yes @tab @tab + +@item @b{i486-pc-linux-gnulibc1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{i586-pc-linux-gnulinc1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{i686-pc-linux-gnu} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{m68k-hp-hpux9.00} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{m68k-sun-sunos4.1.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{m68k-next-nextstep3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{mips-dec-ultrix4.3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{mips-sgi-irix5.2} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab @tab @tab @tab @tab @tab + +@item @b{mips-sgi-irix5.3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab @tab + +@item @b{mips-sgi-irix6.2} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab @tab + +@item @b{mips-sgi-irix6.4} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{powerpc-ibm-aix4.1.5.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{powerpc-ibm-aix4.2.1.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab @tab + +@item @b{rs6000-ibm-aix3.2} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{rs6000-ibm-aix3.2.5} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{rs6000-ibm-aix4.1.4.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{rs6000-ibm-aix4.1.5.0} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{sparc-sun-solaris2.3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab @tab + +@item @b{sparc-sun-solaris2.4} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-sun-solaris2.5} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab + +@item @b{sparc-sun-solaris2.5.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes + +@item @b{sparc-sun-solaris2.6} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes + +@item @b{sparc-sun-sunos4.1.1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-sun-sunos4.1.3} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-sun-sunos4.1.3C} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-sun-sunos4.1.3_U1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-sun-sunos4.1.4} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-unknown-linux-gnulibc1} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab n/a @tab yes @tab + +@item @b{sparc-unknown-netbsd1.2E} +@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} +@tab yes @tab yes @tab yes @tab @tab @tab + +@end multitable + +See the @file{INSTALL} in the distribution for more specific details on +building and/or configuring for some systems. + +@c ################################################################ +@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 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 configured when @i{Amd} is built +and can be displayed by running the command @samp{amd -v}. + +When using an @i{Amd} configuration file (@pxref{Amd Configuration File}) +and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may +force the map used to any type. + +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 behavior (@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:: +* NIS+ maps:: +* Hesiod maps:: +* Password maps:: +* Union maps:: +* LDAP 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 have a default cache mode of @samp{all} (@pxref{Automount Filesystem}). + +@node NIS maps, NIS+ 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 have a default cache mode of @code{all} (@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 NIS+ maps, Hesiod maps, NIS maps, Map Types +@comment node-name, next, previous, up +@subsection NIS+ maps +@cindex NIS+ maps + +NIS+ maps do not support cache mode @samp{all} and, when caching is +enabled, have a default cache mode of @samp{inc}. + +XXX: FILL IN WITH AN EXAMPLE. + +@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, or +the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base +Parameter}). 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 @i{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, LDAP 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. + +@node LDAP maps, , Union maps, Map Types +@comment node-name, next, previous, up +@subsection LDAP maps +@cindex LDAP maps +@cindex Lightweight Directory Access Protocol + +LDAP (Lightweight Directory Access Protocol) maps do not support cache +mode @samp{all} and, when caching is enabled, have a default cache mode +of @samp{inc}. + +For example, an @i{Amd} map @samp{amd.home} that looks as follows: + +@example +/defaults opts:=rw,intr;type:=link + +zing -rhost:=shekel \ + host==shekel \ + host!=shekel;type:=nfs +@end example +@noindent +when converted to LDAP (@pxref{amd2ldif}), will result in the following +LDAP database: +@example +$ amd2ldif amd.home CUCS < amd.home +dn: cn=amdmap timestamp, CUCS +cn : amdmap timestamp +objectClass : amdmapTimestamp +amdmapTimestamp: 873071363 + +dn: cn=amdmap amd.home[/defaults], CUCS +cn : amdmap amd.home[/defaults] +objectClass : amdmap +amdmapName : amd.home +amdmapKey : /defaults +amdmapValue : opts:=rw,intr;type:=link + +dn: cn=amdmap amd.home[], CUCS +cn : amdmap amd.home[] +objectClass : amdmap +amdmapName : amd.home +amdmapKey : +amdmapValue : + +dn: cn=amdmap amd.home[zing], CUCS +cn : amdmap amd.home[zing] +objectClass : amdmap +amdmapName : amd.home +amdmapKey : zing +amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs +@end example + +@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{*}. + +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 + +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 +@i{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 the +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 + +@c====================================================================== +@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==sunos4} would only +apply on Sun-3s running SunOS 4.x. + +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. + +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 default value of many of the selectors listed here can be overridden +by an @i{Amd} command line switch or in an @i{Amd} configuration file. +@xref{Amd Configuration File}. + +These are the selectors currently implemented. + +@menu +* arch Selector Variable:: +* autodir Selector Variable:: +* byte Selector Variable:: +* cluster Selector Variable:: +* domain Selector Variable:: +* host Selector Variable:: +* hostd Selector Variable:: +* karch Selector Variable:: +* os Selector Variable:: +* osver Selector Variable:: + +* key Selector Variable:: +* map Selector Variable:: +* netnumber Selector Variable:: +* network Selector Variable:: +* path Selector Variable:: +* wire Selector Variable:: + +* exists Selector Function:: +* false Selector Function:: +* netgrp Selector Function:: +* in_network Selector Function:: +* true Selector Function:: +@end menu + +@c ---------------------------------------------------------------- +@node arch Selector Variable, autodir Selector Variable, Selectors, Selectors +@comment node-name, next, previous, up +@subsubsection arch Selector Variable +@cindex arch Selector Variable +@cindex arch, mount selector +@cindex Mount selector; arch +@cindex Selector; 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 Platforms}.@refill + +@c ---------------------------------------------------------------- +@node autodir Selector Variable, byte Selector Variable, arch Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection autodir Selector Variable +@cindex autodir Selector Variable +@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 @code{-a} command line option. @xref{fs Option}. + +@c ---------------------------------------------------------------- +@node byte Selector Variable, cluster Selector Variable, autodir Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection byte Selector Variable +@cindex byte Selector Variable +@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. + +@c ---------------------------------------------------------------- +@node cluster Selector Variable, domain Selector Variable, byte Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection cluster Selector Variable +@cindex cluster Selector Variable +@cindex cluster, mount selector +@cindex Mount selector; cluster +@cindex Selector; cluster + +This 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 @code{-C} +command line option. + +@c ---------------------------------------------------------------- +@node domain Selector Variable, host Selector Variable, cluster Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection domain Selector Variable +@cindex domain Selector Variable +@cindex domain, mount selector +@cindex Mount selector; domain +@cindex Selector; domain + +The local domain name as specified by the @code{-d} command line option. +@xref{host Selector Variable}. + +@c ---------------------------------------------------------------- +@node host Selector Variable, hostd Selector Variable, domain Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection host Selector Variable +@cindex host Selector Variable +@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 + +@c ---------------------------------------------------------------- +@node hostd Selector Variable, karch Selector Variable, host Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection hostd Selector Variable +@cindex hostd Selector Variable +@cindex hostd, mount selector +@cindex Mount selector; hostd +@cindex Selector; hostd + +This resolves to the @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. + +@c ---------------------------------------------------------------- +@node karch Selector Variable, os Selector Variable, hostd Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection karch Selector Variable +@cindex karch Selector Variable +@cindex karch, mount selector +@cindex Mount selector; karch +@cindex Selector; karch + +This is provided as a hook for the kernel architecture. This is used on +SunOS 4 and SunOS 5, for example, to distinguish between different +@samp{/usr/kvm} volumes. @code{$@{karch@}} defaults to the ``machine'' +value gotten from @b{uname}(2). If the @b{uname}(2) system call is not +available, the value of @code{$@{karch@}} defaults to that of +@code{$@{arch@}}. Finally, a different value can be set with the @code{-k} +command line option. + +@c ---------------------------------------------------------------- +@node os Selector Variable, osver Selector Variable, karch Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection os Selector Variable +@cindex os Selector Variable +@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 +Platforms}.@refill + +@c ---------------------------------------------------------------- +@node osver Selector Variable, key Selector Variable, os Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection osver Selector Variable +@cindex osver Selector Variable +@cindex osver, mount selector +@cindex Mount selector; osver +@cindex Selector; osver + +The operating system version. 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 +Platforms}.@refill + +@c ---------------------------------------------------------------- +@ifhtml +<HR> +@end ifhtml +@sp 3 +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. + +@c ---------------------------------------------------------------- +@node key Selector Variable, map Selector Variable, osver Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection key Selector Variable +@cindex key Selector Variable +@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 + +@c ---------------------------------------------------------------- +@node map Selector Variable, netnumber Selector Variable, key Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection map Selector Variable +@cindex map Selector Variable +@cindex map, mount selector +@cindex Mount selector; map +@cindex Selector; map + +The name of the mount map being used. + +@c ---------------------------------------------------------------- +@node netnumber Selector Variable, network Selector Variable, map Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection netnumber Selector Variable +@cindex netnumber Selector Variable +@cindex netnumber, mount selector +@cindex Mount selector; netnumber +@cindex Selector; netnumber + +This selector is identical to the @samp{in_network} selector function, +see @ref{in_network Selector Function}. It will match either the name +or number of @i{any} network interface on which this host is connected +to. The names and numbers of all attached interfaces are available from +the output of @samp{amd -v}. + +@c ---------------------------------------------------------------- +@node network Selector Variable, path Selector Variable, netnumber Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection network Selector Variable +@cindex network Selector Variable +@cindex network, mount selector +@cindex Mount selector; network +@cindex Selector; network + +This selector is identical to the @samp{in_network} selector function, +see @ref{in_network Selector Function}. It will match either the name +or number of @i{any} network interface on which this host is connected +to. The names and numbers of all attached interfaces are available from +the output of @samp{amd -v}. + +@c ---------------------------------------------------------------- +@node path Selector Variable, wire Selector Variable, network Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection path Selector Variable +@cindex path Selector Variable +@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. + +@c ---------------------------------------------------------------- +@node wire Selector Variable, exists Selector Function, path Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection wire Selector Variable +@cindex wire Selector Variable +@cindex wire, mount selector +@cindex Mount selector; wire +@cindex Selector; wire + +This selector is identical to the @samp{in_network} selector function, +see @ref{in_network Selector Function}. It will match either the name +or number of @i{any} network interface on which this host is connected +to. The names and numbers of all attached interfaces are available from +the output of @samp{amd -v}. + +@c ---------------------------------------------------------------- +@ifhtml +<HR> +@end ifhtml +@sp 2 +The following boolean functions are selectors which take an argument +@i{ARG}. They return a value of true or false, and thus do not need to +be compared with a value. Each of these may be negated by prepending +@samp{!} to their name. + +@c ---------------------------------------------------------------- +@node exists Selector Function, false Selector Function, wire Selector Variable, Selectors +@comment node-name, next, previous, up +@subsubsection exists Selector Function +@cindex exists Selector Function +@cindex exists, boolean mount selector +@cindex !exists, boolean mount selector +@cindex Mount selector; exists +@cindex Selector; exists + +If the file listed by @i{ARG} exists (via @b{lstat}(2)), this function +evaluates to true. Otherwise it evaluates to false. + +@c ---------------------------------------------------------------- +@node false Selector Function, netgrp Selector Function, exists Selector Function, Selectors +@comment node-name, next, previous, up +@subsubsection false Selector Function +@cindex false Selector Function +@cindex false, boolean mount selector +@cindex !false, boolean mount selector +@cindex Mount selector; false +@cindex Selector; false + +Always evaluates to false. @i{ARG} is ignored. + +@c ---------------------------------------------------------------- +@node netgrp Selector Function, in_network Selector Function, false Selector Function, Selectors +@comment node-name, next, previous, up +@subsubsection netgrp Selector Function +@cindex netgrp Selector Function +@cindex netgrp, boolean mount selector +@cindex !netgrp, boolean mount selector +@cindex Mount selector; netgrp +@cindex Selector; netgrp + +If the current host as determined by the value of @code{$@{host@}} is a +member of the netgroup @i{ARG}, this selector evaluates to true. +Otherwise it evaluates to false. + +For example, suppose you have a netgroup @samp{ppp-hosts}, and for +reasons of performance, these have a local @file{/home} partition, while +all other clients on the faster network can access a shared home +directory. A common map to use for both might look like the following: + +@example +home/* netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \ + !netgrp(ppp-hosts);type:=nfs;rhost=serv1;rfs:=/remote/$@{key@} +@end example + +@c ---------------------------------------------------------------- +@node in_network Selector Function, true Selector Function, netgrp Selector Function, Selectors +@comment node-name, next, previous, up +@subsubsection in_network Selector Function +@cindex in_network Selector Function +@cindex in_network, boolean mount selector +@cindex !in_network, boolean mount selector +@cindex Mount selector; in_network +@cindex Selector; in_network + +If the current host has any network interface that is locally attached +to the network specified in @i{ARG} (either via name or number), this +selector evaluates to true. Otherwise it evaluates to false. + +For example, suppose you have two servers that have an exportable +@file{/opt} that smaller clients can NFS mount. The two servers are +say, @samp{serv1} on network @samp{foo-net.site.com} and @samp{serv2} on +network @samp{123.4.5.0}. You can write a map to be used by all clients +that will attempt to mount the closest one as follows: + +@example +opt in_network(foo-net.site.com);rhost:=serv1;rfs:=/opt \ + in_network(123.4.5.0);rhost:=serv2;rfs:=/opt \ + rhost:=fallback-server +@end example + +@c ---------------------------------------------------------------- +@node true Selector Function, , in_network Selector Function, Selectors +@comment node-name, next, previous, up +@subsubsection true Selector Function +@cindex true Selector Function +@cindex true, boolean mount selector +@cindex !true, boolean mount selector +@cindex Mount selector; true +@cindex Selector; true + +Always evaluates to true. @i{ARG} is ignored. + +@c ================================================================ +@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 +* addopts Option:: +* delay Option:: +* fs Option:: +* opts Option:: +* remopts Option:: +* sublink Option:: +* type Option:: +@end menu + +@node addopts Option, delay Option, Map Options, Map Options +@comment node-name, next, previous, up +@subsubsection addopts Option +@cindex Setting additional options on a mount location +@cindex Overriding or adding options to a mount +@cindex addopts, mount option +@cindex Mount option; addopts + +This option adds additional options to default options normally +specified in the @samp{/defaults} entry or the defaults of the key entry +being processed (@xref{opts Option}). Normally when you specify +@samp{opts} in both the @samp{/defaults} and the map entry, the latter +overrides the former completely. But with @samp{addopts} it will +append the options and override any conflicting ones. + +Options which start with @samp{no} will override those with the same +name that do not start with @samp{no} and vice verse. Special handling +is given to inverted options such as @samp{soft} and @samp{hard}, +@samp{bg} and @samp{fg}, @samp{ro} and @samp{rw}, etc. + +For example, if the default options specified were +@example +opts:=rw,nosuid,intr,rsize=1024,wsize=1024,quota,posix +@end example + +and the ones specified in a map entry were + +@example +addopts:=grpid,suid,ro,rsize=2048,quota,nointr +@end example + +then the actual options used would be + +@example +wsize=1024,posix,grpid,suid,ro,rsize=2048,quota,nointr +@end example + +@node delay Option, fs Option, addopts Option, 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. Auxiliary 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{getcwd}(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 @code{-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 recognized 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.4BSD +is known to implement the @code{compress} and @code{spongy} options. + +@table @code + +@item acdirmax=@var{n} +@cindex Mount flags; acdirmax +Set the maximum directory attribute cache timeout to @var{n}. + +@item acdirmin=@var{n} +@cindex Mount flags; acdirmin +Set the minimum directory attribute cache timeout to @var{n}. + +@item acregmax=@var{n} +@cindex Mount flags; acregmax +Set the maximum file attribute cache timeout to @var{n}. + +@item acregmin=@var{n} +@cindex Mount flags; acregmin +Set the minimum file attribute cache timeout to @var{n}. + +@item actimeo=@var{n} +@cindex Mount flags; actimeo +Set the overall attribute cache timeout to @var{n}. + +@item auto +@cindex Mount flags; auto +@itemx ignore +@cindex Mount flags; ignore +Ignore this mount by @b{df}(1). + +@item cache +@cindex Mount flags; cache +Allow data to be cached from a remote server for this mount. + +@item compress +@cindex Mount flags; compress +Use NFS compression protocol. + +@item defperm +@cindex Mount flags; defperm +Ignore the permission mode bits, and default file permissions to 0555, +UID 0, and GID 0. Useful for CD-ROMs formatted as ISO-9660. + +@item dev +@cindex Mount flags; dev +Allow local special devices on this filesystem. + +@item dumbtimr +@cindex Mount flags; dumbtimr +(XXX: a dumb timer?) + +@item fsid +@cindex Mount flags; fsid +Set ID of filesystem. + +@item grpid +@cindex Mount flags; grpid +Use BSD directory group-id semantics. + +@item int +@cindex Mount flags; int +@itemx intr +@cindex Mount flags; intr +Allow keyboard interrupts on hard mounts. + +@item multi +@cindex Mount flags; multi +Perform multi-component lookup on files. + +@item maxgroups +@cindex Mount flags; maxgroups +Set the maximum number of groups to allow for this mount. + +@item nfsv3 +@cindex Mount flags; nfsv3 +Use NFS Version 3 for this mount. + +@item noac +@cindex Mount flags; noac +Turn off the attribute cache. + +@item noauto +@cindex Mount flags; noauto +(XXX: No automatic what?) + +@item nocache +@cindex Mount flags; nocache +Do not allow data to be cached from a remote server for this +mount. + +@item noconn +@cindex Mount flags; noconn +Don't make a connection on datagram transports. + +@item nocto +@cindex Mount flags; nocto +No close-to-open consistency. + +@item nodefperm +@cindex Mount flags; nodefperm +Do not ignore the permission mode bits. Useful for CD-ROMS formatted as +ISO-9660. + +@item nodev +@cindex Mount flags; nodev +@itemx nodevs +@cindex Mount flags; nodevs +Don't allow local special devices on this filesystem. + +@item noint +@cindex Mount flags; noint +Do not allow keyboard interrupts for this mount + +@item nosub +@cindex Mount flags; nosub +Disallow mounts beneath this mount. + +@item nosuid +@cindex Mount flags; nosuid +Don't allow set-uid or set-gid executables on this filesystem. + +@item noversion +@cindex Mount flags; noversion +Strip the extension @samp{;#} from the version string of files recorded +on an ISO-9660 CD-ROM. + +@item overlay +@cindex Mount flags; overlay +Overlay this mount on top of an existing mount, if any. + +@item pgthresh=@var{n} +@cindex Mount flags; pgthresh +Set the paging threshold to @var{n} kilobytes. + +@item port=@var{n} +@cindex Mount flags; port +Set the NFS port to @var{n}. + +@item posix +@cindex Mount flags; posix +Turn on POSIX static pathconf for mounts. + +@item proto=@var{s} +@cindex Mount flags; proto +Use transport protocol @var{s} for NFS (can be @code{"tcp"} or @code{"udp"}). + +@item quota +@cindex Mount flags; quota +Enable quota checking on this mount. + +@item rdonly +@cindex Mount flags; rdonly +@itemx ro +@cindex Mount flags; ro +Mount this filesystem readonly. + +@item resvport +@cindex Mount flags; resvport +Use a reserved port (smaller than 1024) for remote NFS mounts. Most +systems assume that, but some allow for mounts to occur on non-reserved +ports. This causes problems when such a system tries to NFS mount one +that requires reserved ports. It is recommended that this option always +be on. + +@item retrans=@i{n} +@cindex Mount flags; retrans +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 retry +@cindex Mount flags; retry +Set the NFS retry counter. + +@item rrip +@cindex Mount flags; rrip +Uses the Rock Ridge Interchange Protocol (RRIP) extensions to ISO-9660. + +@item rsize=@var{n} +@cindex Mount flags; rsize +The NFS read packet size. You may need to set this if you are using +NFS/UDP through a gateway or a slow link. + +@item rw +@cindex Mount flags; rw +Allow reads and writes on this filesystem. + +@item soft +@cindex Mount flags; soft +Give up after @dfn{retrans} retransmissions. + +@item spongy +@cindex Mount flags; spongy +Like @samp{soft} for status requests, and @samp{hard} for data transfers. + +@item suid +@cindex Mount flags; suid +Allow set-uid programs on this mount. + +@item symttl +@cindex Mount flags; symttl +Turn of the symbolic link cache time-to-live. + +@item sync +@cindex Mount flags; sync +Perform synchronous filesystem operations on this mount. + +@item tcp +@cindex Mount flags; tcp +Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not +support TCP/IP mounts. + +@item timeo=@var{n} +@cindex Mount flags; timeo +The NFS timeout, in tenth-seconds, before a request is retransmitted. + +@item vers=@var{n} +@cindex Mount flags; vers + Use NFS protocol version number @var{n} (can be 2 or 3). + +@item wsize=@var{n} +@cindex Mount flags; wsize +The NFS write packet size. You may need to set this if you are using +NFS/UDP through a gateway or a slow link. + +@end table + +The following options are implemented by @i{Amd}, rather than being +passed to the kernel. + +@table @code + +@item nounmount +@cindex Mount flags; 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} +@cindex Mount flags; ping +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} +@cindex Mount flags; retry=@var{n} +The number of times to retry the mount system call. + +@item utimeout=@var{n} +@cindex Mount flags; 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 @code{-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{$@{remopts@}} 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 + +@c ################################################################ +@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 or specified in the +@file{amd.conf} file, @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 @ref{Map Defaults}. + +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} (via +@code{configure --enable-debug}), 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. +However, even with all of this, mounts and unmounts are performed in the +background, and @i{Amd} will always fork before doing them. Therefore, +debugging what happens closely during un/mounts is more challenging. + +@emph{All} of @i{Amd}'s command options (save @code{-F} and @code{-T}) +can be specified in the @file{amd.conf} file. @xref{Amd Configuration +File}. If @i{Amd} is invoked without any command line options, it will +default to using the configuration file @file{/etc/amd.conf}, if one +exists. + +@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 normalization. +* -o Option:: Operating system version. +* -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. +* -F Option:: Amd configuration file. +* -H Option:: Show brief help. +* -O-Option:: Operating system name. +* -S Option:: Lock executable pages in memory. +* -T-Option:: Set tag for configuration file. +@end menu + +@c ---------------------------------------------------------------- +@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} or @file{/n}. + +@example +amd -a /amd ... +@end example + +@c ---------------------------------------------------------------- +@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). + +@c ---------------------------------------------------------------- +@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 + +@c ---------------------------------------------------------------- +@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{uname -m} (the ``machine'' value gotten from +@b{uname}(2)). If the @b{uname}(2) system call is not available, the +value of @code{$@{karch@}} defaults to that of @code{$@{arch@}}. + +The only effect of this option is to set the variable @code{$@{karch@}}. + +This option would be used as follows: + +@example +amd -k `arch -k` ... +@end example + +@c ---------------------------------------------------------------- +@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. Several special @dfn{log-options} +are recognized. + +@enumerate +@item +If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the +@b{syslog}(3) mechanism. If your system supports syslog facilities, then +the default facility used is @samp{LOG_DAEMON}. + +@item +@cindex syslog facility; specifying an alternate +When using syslog, if you wish to change the facility, append its name +to the log option name, delimited by a single colon. For example, if +@dfn{log-options} is the string @samp{syslog:local7} then @b{Amd} will +log messages via @b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If +the facility name specified is not recognized, @i{Amd} will default to +@samp{LOG_DAEMON}. Note: while you can use any syslog facility +available on your system, it is generally a bad idea to use those +reserved for other services such as @samp{kern}, @samp{lpr}, +@samp{cron}, etc. + +@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. + +Normally, when long-running daemons hold an open file descriptor on a +log file, it is impossible to ``rotate'' the log file and compress older +logs on a daily basis. The daemon needs to be told to discard (via +@b{close}(2)) its file handle, and re-open the log file. This is done +using @code{amq -l} @i{log-option}. @xref{Amq -l option}. + +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. + +Since @i{Amd} tends to generate a lot of logging information (especially +if debugging was turned on), and due to it being an important program +running on the system, it is usually best to log to a separate disk +file. In that case @i{Amd} would be started as follows: + +@example +amd -l /var/log/amd ... +@end example + +@c ---------------------------------------------------------------- +@node -n Option, -o Option, -l Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-n} +@cindex Hostname normalization +@cindex Aliased hostnames +@cindex Resolving aliased hostnames +@cindex Normalizing hostnames + +Normalizes the remote hostname before using it. Normalization is done +by replacing the value of @code{$@{rhost@}} with the (generally fully +qualified) 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. + +@c ---------------------------------------------------------------- +@node -o Option, -p Option, -n Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-o} @var{op-sys-ver} +@cindex Operating System version +@cindex Setting the Operating System version + +Override the compiled-in version number of the operating system, with +@var{op-sys-ver}. Useful when the built-in version is not desired for +backward compatibility reasons. For example, if the built-in version is +@samp{2.5.1}, you can override it to @samp{5.5.1}, and use older maps +that were written with the latter in mind. + +@c ---------------------------------------------------------------- +@node -p Option, -r Option, -o 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. + +@c ---------------------------------------------------------------- +@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.} + +@c ---------------------------------------------------------------- +@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. + +@c ---------------------------------------------------------------- +@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 +Copyright (c) 1997-1998 Erez Zadok +Copyright (c) 1990 Jan-Simon Pendry +Copyright (c) 1990 Imperial College of Science, Technology & Medicine +Copyright (c) 1990 The Regents of the University of California. +am-utils version 6.0a15 (build 61). +Built by ezk@@cs.columbia.edu on date Wed Oct 22 15:21:03 EDT 1997. +cpu=sparc (big-endian), arch=sun4, karch=sun4u. +full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun. +Map support for: root, passwd, union, nisplus, nis, ndbm, file, error. +AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit, + ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error. +FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, ufs. +Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13). +Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14). +Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16). +@end example + +The information includes the version number, number of times @i{Amd} was +compiled on the local system, release date and name of the release. +Following come the cpu type, byte ordering, and the architecture and +kernel architecture as @code{$@{arch@}} and @code{$@{karch@}}, +respectively. The next line lists the full name of the system, the +variables @code{$@{os@}} and @code{$@{osver@}}, and the vendor's +name. @xref{Supported Platforms}. + +Then come a list of map types supported, filesystems internally +supported by @i{Amd} (AMFS), and generic filesystems available (FS). +Finally all known networks (if any) of this host are listed by name +and number. They are available via the variables +@code{$@{wire@}} or @code{$@{network@}}, and +@code{$@{netnumber@}} (@pxref{Selectors}) or the @samp{in_network} +selector function (@pxref{in_network Selector Function}). + +@c ---------------------------------------------------------------- +@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). + +@c ---------------------------------------------------------------- +@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 @code{-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 priorities used for each +of the message types.@refill + +@table @code +@item fatal +@samp{LOG_CRIT} +@item error +@samp{LOG_ERR} +@item user +@samp{LOG_WARNING} +@item warning +@samp{LOG_WARNING} +@item info +@samp{LOG_INFO} +@item debug +@samp{LOG_DEBUG} +@item map +@samp{LOG_DEBUG} +@item stats +@samp{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. + +@c ---------------------------------------------------------------- +@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 @code{-m} option +@c is specified, and whenever required in a mount map. + +@c ---------------------------------------------------------------- +@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 + +@c ---------------------------------------------------------------- +@node -D-Option, -F 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 @code{-D} option is +only available if @i{Amd} was compiled with @samp{-DDEBUG}, or +configured with @code{configure --enable-debug}. The memory debugging +facilities (@samp{mem}) are only available if @i{Amd} was compiled with +@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}), or configured with +@code{configure --enable-debug=mem}. + +The most common options to use are @samp{-D trace} and @samp{-D test} +(which turns on all the useful debug options). As usual, every option +can be prefixed with @samp{no} to turn it off. + +@table @code +@item all +all options +@item amq +register for amq +@item daemon +enter daemon mode +@item fork +fork server +@item full +program trace +@item info +@cindex debugging hesiod resolver service +@cindex Hesiod: turning on RES_DEBUG +info service specific debugging (hesiod, nis, etc.) In the case of +hesiod maps, turns on the hesiod RES_DEBUG internal debugging option. +@item mem +trace memory allocations +@item mtab +use local @file{./mtab} file +@item str +debug string munging +@item test +full debug but no daemon +@item trace +protocol trace +@end table + +You may also refer to the program source for a more detailed explanation +of the available options. + +@c ---------------------------------------------------------------- +@node -F Option, -H Option, -D-Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-F} @var{conf-file} +@cindex Amd configuration file; specifying name +@cindex Amd configuration file +@cindex amd.conf file + +Specify an @i{Amd} configuration file @var{conf-file} to use. For a +description of the format and syntax, @pxref{Amd Configuration File}. +This configuration file is used to specify any options in lieu of typing +many of them on the command line. The @file{amd.conf} file includes +directives for every command line option @i{Amd} has, and many more that +are only available via the configuration file facility. The +configuration file specified by this option is processed after all other +options had been processed, regardless of the actual location of this +option on the command line. + +@c ---------------------------------------------------------------- +@node -H Option, -O-Option, -F Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-H} +@cindex Displaying brief help +@cindex Help; showing from Amd + +Print a brief help and usage string. + +@c ---------------------------------------------------------------- +@node -O-Option, -S Option, -H Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-O} @var{op-sys-name} +@cindex Operating System name +@cindex Setting the Operating System name + +Override the compiled-in name of the operating system, with +@var{op-sys-name}. Useful when the built-in name is not desired for +backward compatibility reasons. For example, if the build in name is +@samp{sunos5}, you can override it to the old name @samp{sos5}, and use +older maps which were written with the latter in mind. + +@c ---------------------------------------------------------------- +@node -S Option, -T-Option, -O-Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-S} +@cindex plock; using +@cindex locking executable pages in memory + +Do @emph{not} lock the running executable pages of @i{Amd} into memory. +To improve @i{Amd}'s performance, systems that support the @b{plock}(3) +call lock the @i{Amd} process into memory. This way there is less +chance the operating system will schedule, page out, and swap the +@i{Amd} process as needed. This tends to improve @i{Amd}'s performance, +at the cost of reserving the memory used by the @i{Amd} process (making +it unavailable for other processes). If this behavior is not desired, +use the @code{-S} option. + +@c ---------------------------------------------------------------- +@node -T-Option, , -S Option, Amd Command Line Options +@comment node-name, next, previous, up +@section @code{-T} @var{tag} +@cindex Tags for Amd configuration file +@cindex Configuration file; tags + +Specify a tag to use with @file{amd.conf}. All map entries tagged with +@var{tag} will be processed. Map entries that are not tagged are always +processed. Map entries that are tagged with a tag other than @var{tag} +will not be processed. + +@c ################################################################ +@node Filesystem Types, Amd Configuration File, 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. +* Caching Filesystem:: Caching from remote server filesystem. +* CD-ROM Filesystem:: ISO9660 CD ROM. +* Loopback Filesystem:: Local loopback-mount filesystem. +* Memory/RAM Filesystem:: A memory or RAM-based filesystem. +* Null Filesystem:: 4.4BSD's loopback-mount filesystem. +* Floppy Filesystem:: MS-DOS Floppy filesystem. +* Translucent Filesystem:: The directory merging filesystem. +* Shared Memory+Swap Filesystem:: Sun's tmpfs filesystem. +* User ID Mapping Filesystem:: 4.4BSD's umapfs filesystem. +* Program Filesystem:: Generic Program mounts. +* Symbolic Link Filesystem:: Local link. +* Symbolic Link Filesystem II:: Local link referencing existing filesystem. +* NFS-Link Filesystem:: Link if path exists, NFS otherwise. +* Automount Filesystem:: +* Direct Automount Filesystem:: +* Union Filesystem:: +* Error Filesystem:: +* Top-level Filesystem:: +* Autofs Filesystem:: Sun's kernel-based automounter filesystem. +* Root Filesystem:: +* Inheritance Filesystem:: +@end menu + +@c ---------------------------------------------------------------- +@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types +@comment node-name, next, previous, up +@section Network Filesystem (@samp{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} (@samp{type:=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 possibility of blocking @i{Amd}. + +@c ---------------------------------------------------------------- +@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Network Host Filesystem (@samp{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 occurring, use the +@c @samp{nounmount} mount option. + +The @dfn{host} (@samp{type:=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 be 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 successfully 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 +* type:=host;rhost:=$@{key@};fs:=$@{autodir@}/$@{rhost@}/root +@end example + +@noindent +and then start @i{Amd} with the following command + +@example +amd /net 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. + +@c ---------------------------------------------------------------- +@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Network Filesystem Group (@samp{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} (@samp{type:=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 + +@c ---------------------------------------------------------------- +@node Unix Filesystem, Caching Filesystem, Network Filesystem Group, Filesystem Types +@comment node-name, next, previous, up +@section Unix Filesystem (@samp{ufs}, @samp{xfs}, or @samp{efs}) +@cindex Unix filesystem +@cindex UFS +@cindex XFS +@cindex EFS +@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 +@cindex xfs, filesystem type +@cindex Filesystem type; xfs +@cindex efs, filesystem type +@cindex Filesystem type; efs + +The @dfn{ufs} (@samp{type:=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/sd0d;sublink:=jsp +@end example + +UFS is the default Unix disk-based file system, which Am-utils picks up +during the autoconfiguration phase. Some systems have more than one +type, such as IRIX, that comes with EFS (Extent File System) and XFS +(Extended File System). In those cases, you may explicitly set the file +system type, by using entries such: + +@example +ez1 type:=efs;dev:=/dev/xd0a +ez2 type:=xfs;dev:=/dev/sd3c +@end example + +@c ---------------------------------------------------------------- +@node Caching Filesystem, CD-ROM Filesystem, Unix Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Caching Filesystem (@samp{cachefs}) +@cindex Caching Filesystem +@cindex cachefs, filesystem type +@cindex Filesystem type; cachefs + +The @dfn{cachefs} (@samp{type:=cachefs}) filesystem caches files from +one location onto another, presumably providing faster access. It is +particularly useful to cache from a larger and remote (slower) NFS +partition to a smaller and local (faster) UFS directory. + +@noindent +The following options must be specified: + +@table @code +@cindex cachedir, mount option +@cindex Mount option; cachedir +@item cachedir +the directory where the cache is stored. +@item rfs +the path name to the ``back file system'' to be cached from. +@item fs +the ``front file system'' mount point to the cached files, where @i{Amd} +will set a symbolic link pointing to. +@end table + +A CacheFS entry for, say, the @file{/import} @i{Amd} mount point, might +be: + +@example +copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt +@end example + +Access to the pathname @file{/import/copt} will follow a symbolic link +to @file{/n/import/copt}. The latter is the mount point for a caching +file system, that caches from @file{/import/opt} to @file{/cache}. + +@b{Caveats}: +@enumerate +@item This file system is currently only implemented for Solaris 2.x! +@item Before being used for the first time, the cache directory @i{must} be +initialized with @samp{cfsadmin -c @var{cachedir}}. See the manual page for +@b{cfsadmin}(1M) for more information. +@item The ``back file system'' mounted must be a complete file system, not +a subdirectory thereof; otherwise you will get an error ``Invalid Argument''. +@item If @i{Amd} aborts abnormally, the state of the cache may be +inconsistent, requiring running the command @file{fsck -F cachefs +@var{cachedir}}. Otherwise you will get the error ``No Space Left on Device''. +@end enumerate + +@c ---------------------------------------------------------------- +@node CD-ROM Filesystem, Loopback Filesystem, Caching Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section CD-ROM Filesystem (@samp{cdfs}) +@cindex CD-ROM Filesystem +@cindex cdfs, filesystem type +@cindex Filesystem type; cdfs + +The @dfn{cdfs} (@samp{type:=cdfs}) filesystem mounts a CD-ROM with an +ISO9660 format filesystem on it. + +@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 cdfs entry might be: + +@example +cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ + os==sunos5;type:=cdfs;dev:=/dev/dsk/c0t6d0s2 +@end example + +@c ---------------------------------------------------------------- +@node Loopback Filesystem, Memory/RAM Filesystem, CD-ROM Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Loopback Filesystem (@samp{lofs}) +@cindex Loopback Filesystem +@cindex lofs, filesystem type +@cindex Filesystem type; lofs + +The @dfn{lofs} (@samp{type:=lofs}) filesystem is also called the +loopback filesystem. It mounts a local directory on another, thus +providing mount-time binding to another location (unlike symbolic +links). + +The loopback filesystem is particularly useful within the context of a +chroot-ed directory (via @b{chroot}(2)), to provide access to +directories otherwise inaccessible. + +@noindent +The following option must be specified: + +@table @code +@cindex rfs, mount option +@cindex Mount option; rfs +@item rfs +the pathname to be mounted on top of @code{$@{fs@}}. +@end table + +Usually, the FTP server runs in a chroot-ed environment, for security +reasons. In this example, lofs is used to provide a subdirectory within +a user's home directory, also available for public ftp. + +@example +lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk +@end example + +@c ---------------------------------------------------------------- +@node Memory/RAM Filesystem, Null Filesystem, Loopback Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Memory/RAM Filesystem (@samp{mfs}) +@cindex Memory/RAM Filesystem +@cindex mfs, filesystem type +@cindex Filesystem type; mfs + +The @dfn{mfs} (@samp{type:=mfs}) filesystem is available in 4.4BSD, +Linux, and other systems. It creates a filesystem in a portion of the +system's memory, thus providing very fast file (volatile) access. + +XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! + +@c ---------------------------------------------------------------- +@node Null Filesystem, Floppy Filesystem, Memory/RAM Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Null Filesystem (@samp{nullfs}) +@cindex Null Filesystem +@cindex nullfs, filesystem type +@cindex Filesystem type; nullfs + +The @dfn{nullfs} (@samp{type:=nullfs}) filesystem is available from 4.4BSD, +and is very similar to the loopback filesystem, @dfn{lofs}. + +XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! + +@c ---------------------------------------------------------------- +@node Floppy Filesystem, Translucent Filesystem, Null Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Floppy Filesystem (@samp{pcfs}) +@cindex Floppy Filesystem +@cindex pcfs, filesystem type +@cindex Filesystem type; pcfs + +The @dfn{pcfs} (@samp{type:=pcfs}) filesystem mounts a floppy previously +formatted for the MS-DOS format. + +@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 pcfs entry might be: + +@example +pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ + os==sunos5;type:=pcfs;dev:=/dev/diskette +@end example + +@c ---------------------------------------------------------------- +@node Translucent Filesystem, Shared Memory+Swap Filesystem, Floppy Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Translucent Filesystem (@samp{tfs}) +@cindex Translucent Filesystem +@cindex tfs, filesystem type +@cindex Filesystem type; tfs + +The @dfn{tfs} (@samp{type:=tfs}) filesystem is an older version of the +4.4BSD @dfn{unionfs}. + +XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! + +@c ---------------------------------------------------------------- +@node Shared Memory+Swap Filesystem, User ID Mapping Filesystem, Translucent Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Shared Memory+Swap Filesystem (@samp{tmpfs}) +@cindex Shared Memory and Swap Filesystem +@cindex tmpfs, filesystem type +@cindex Filesystem type; tmpfs + +The @dfn{tmpfs} (@samp{type:=tmpfs}) filesystem shares memory between a +the swap device and the rest of the system. It is generally used to +provide a fast access @file{/tmp} directory, one that uses memory that +is otherwise unused. This filesystem is available in SunOS 4.x and 5.x. + +XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! + +@c ---------------------------------------------------------------- +@node User ID Mapping Filesystem, Program Filesystem, Shared Memory+Swap Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section User ID Mapping Filesystem (@samp{umapfs}) +@cindex User ID Mapping Filesystem +@cindex umapfs, filesystem type +@cindex Filesystem type; umapfs + +The @dfn{umapfs} (@samp{type:=umapfs}) filesystem maps User IDs of file +ownership, and is available from 4.4BSD. + +XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! + +@c ---------------------------------------------------------------- +@node Program Filesystem, Symbolic Link Filesystem, User ID Mapping Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Program Filesystem (@samp{program}) +@cindex Program filesystem +@cindex Mount a filesystem under program control +@cindex program, filesystem type +@cindex Filesystem type; program + +The @dfn{program} (@samp{type:=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 @code{-l} +command line option has no effect on standard error. + +@c ---------------------------------------------------------------- +@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Symbolic Link Filesystem (@samp{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 thought 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}. + +@c ---------------------------------------------------------------- +@node Symbolic Link Filesystem II, NFS-Link Filesystem, Symbolic Link Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Symbolic Link Filesystem II (@samp{linkx}) +@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 @dfn{linkx} (@samp{type:=linkx}) filesystem type is identical to @samp{link} with the +exception that the target of the link must exist. Existence is checked +with the @b{lstat}(2) system call. + +The @samp{linkx} filesystem type is particularly useful for wildcard map +entries. In this case, a list of possible targets can be given and +@i{Amd} will choose the first one which exists on the local machine. + +@c ---------------------------------------------------------------- +@node NFS-Link Filesystem, Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types +@comment node-name, next, previous, up +@section NFS-Link Filesystem (@samp{nfsl}) +@cindex NFS-Link filesystem II +@cindex Referencing an existing part of the name space if target exists +@cindex Mounting a remote part of the name space if target is missing +@cindex Symlink if target exists, NFS otherwise +@cindex nfsl, filesystem type +@cindex symlink, nfsl filesystem type +@cindex Filesystem type; nfsl + +The @dfn{nfsl} (@samp{type:=nfsl}) filesystem type is a combination of two others: +@samp{link} and @samp{nfs}. If the local host name is equal to the +value of @code{$@{rhost@}}, or if the target pathname listed in +@code{$@{fs@}} exists, @samp{nfsl} will behave exactly as +@samp{type:=link}, and refer to the target as a symbolic link. If the +local host name is not equal to the value of @code{$@{rhost@}}, or if +the target of the link does not exist, @i{Amd} will treat it as +@samp{type:=nfs}, and will mount a remote pathname for it. + +The @samp{nfsl} filesystem type is particularly useful as a shorthand +for the more cumbersome and yet one of the most popular @i{Amd} +entries. For example, you can simplify all map entries that look like: + +@example +zing -fs:=/n/shekel/u/zing \ + host!=shekel;type:=nfs;rhost:=shekel;rfs:=$@{fs@} \ + host==shekel;type:=link +@end example + +or + +@example +zing -fs:=/n/shekel/u/zing \ + exists($@{fs@});type:=link \ + !exists($@{fs@});type:=nfs;rhost:=shekel;rfs:=$@{fs@} +@end example + +into a shorter form + +@example +zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=$@{fs@} +@end example + +Not just does it make the maps smaller and simpler, but it avoids +possible mistakes that often happen when forgetting to set up the two +entries (one for @samp{type:=nfs} and the other for @samp{type:=link}) +necessary to perform transparent mounts of existing or remote mounts. + +@c ---------------------------------------------------------------- +@node Automount Filesystem, Direct Automount Filesystem, NFS-Link Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Automount Filesystem (@samp{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 synchronizing +@cindex Synchronizing the map cache +@cindex Map cache options +@cindex Regular expressions in maps + +The @dfn{auto} (@samp{type:=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 successfully 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, synchronized 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 + +@c ---------------------------------------------------------------- +@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Direct Automount Filesystem (@samp{direct}) +@cindex Direct automount filesystem +@cindex How to start a direct automount point +@cindex direct, filesystem type +@cindex Filesystem type; direct + +The @dfn{direct} (@samp{type:=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{/}. + +@c ---------------------------------------------------------------- +@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Union Filesystem (@samp{union}) +@cindex Union filesystem +@cindex union, filesystem type +@cindex Filesystem type; union + +The @dfn{union} (@samp{type:=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 up-to-date with respect to the +underlying directories. Similarly, if a link is removed, for example +with the @samp{rm} command, it will be lost forever. + +@c ---------------------------------------------------------------- +@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Error Filesystem (@samp{error}) +@cindex Error filesystem +@cindex error, filesystem type +@cindex Filesystem type; error + +The @dfn{error} (@samp{type:=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. + +@c ---------------------------------------------------------------- +@node Top-level Filesystem, Autofs Filesystem, Error Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Top-level Filesystem (@samp{toplvl}) +@cindex Top level filesystem +@cindex toplvl, filesystem type +@cindex Filesystem type; toplvl + +The @dfn{toplvl} (@samp{type:=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 @code{-M} option of the @dfn{Amq} command. +That option is insecure, and is unavailable unless am-utils was +configured with @samp{--with-amq-mount}. + +@c ---------------------------------------------------------------- +@node Root Filesystem, Inheritance Filesystem, Autofs Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Root Filesystem (@samp{root}) +@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 having more than one root node is +undefined. + +The root filesystem is not directly accessible. + +@c ---------------------------------------------------------------- +@node Autofs Filesystem, Root Filesystem, Top-level Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Autofs Filesystem (@samp{autofs}) +@cindex Autofs filesystem +@cindex autofs, filesystem type +@cindex Filesystem type; autofs + +The @dfn{autofs} (@samp{type:=autofs}) filesystem uses Sun's kernel-based automounter +supporting filesystem for @i{Amd}'s mount points. Hence it is another +type of top level filesystem. + +The autofs filesystem is not directly accessible from @i{Amd} maps, but +only from the @file{amd.conf} file (@pxref{mount_type Parameter}). + +Note that Autofs support is still very early. See the distribution file +@file{README.autofs} for detail of what works and what does not. + +@c ---------------------------------------------------------------- +@node Inheritance Filesystem, , Root Filesystem, Filesystem Types +@comment node-name, next, previous, up +@section Inheritance Filesystem (@samp{inherit}) +@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 @code{-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 @samp{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. + +@c ################################################################ +@node Amd Configuration File, Run-time Administration, Filesystem Types, Top +@comment node-name, next, previous, up +@chapter Amd Configuration File +@cindex Amd Configuration File +@cindex amd.conf + +The @samp{amd.conf} file is the configuration file for @i{Amd}, as part +of the am-utils suite. This file contains runtime configuration +information for the @i{Amd} automounter program. + +@menu +* File Format:: +* The Global Section:: +* Regular Map Sections:: +* Common Parameters:: +* Global Parameters:: +* Regular Map Parameters:: +* amd.conf Examples:: +@end menu + +@c ================================================================ +@node File Format, The Global Section, Amd Configuration File, Amd Configuration File +@comment node-name, next, previous, up +@section File Format +@cindex amd.conf file format + +The @samp{amd.conf} file consists of sections and parameters. A section +begins with the name of the section in square brackets @samp{[]} and +continues until the next section begins or the end of the file is reached. +Sections contain parameters of the form @samp{name = value}. + +The file is line-based --- that is, each newline-terminated line +represents either a comment, a section name or a parameter. No +line-continuation syntax is available. + +Section names, parameter names and their values are case sensitive. + +Only the first equals sign in a parameter is significant. Whitespace +before or after the first equals sign is discarded. Leading, trailing +and internal whitespace in section and parameter names is irrelevant. +Leading and trailing whitespace in a parameter value is discarded. +Internal whitespace within a parameter value is not allowed, unless the +whole parameter value is quoted with double quotes as in @samp{name = +"some value"}. + +Any line beginning with a pound sign @samp{#} is ignored, as are lines +containing only whitespace. + +The values following the equals sign in parameters are all either a +string (no quotes needed if string does not include spaces) or a +boolean, which may be given as @samp{yes}/@samp{no}. Case is significant in all +values. Some items such as cache timeouts are numeric. + +@c ================================================================ +@node The Global Section, Regular Map Sections, File Format, Amd Configuration File +@comment node-name, next, previous, up +@section The Global Section +@cindex amd.conf global section + +The global section must be specified as @samp{[global]}. Parameters in +this section either apply to @i{Amd} as a whole, or to all other regular map +sections which follow. There should be only one global section defined +in one configuration file. + +It is highly recommended that this section be specified first in the +configuration file. If it is not, then regular map sections which +precede it will not use global values defined later. + +@c ================================================================ +@node Regular Map Sections, Common Parameters, The Global Section, Amd Configuration File +@comment node-name, next, previous, up +@section Regular Map Sections +@cindex amd.conf regular map sections + +Parameters in regular (non-global) sections apply to a single map entry. +For example, if the map section @samp{[/homes]} is defined, then all +parameters following it will be applied to the @file{/homes} +@i{Amd}-managed mount point. + +@c ================================================================ +@node Common Parameters, Global Parameters, Regular Map Sections, Amd Configuration File +@comment node-name, next, previous, up +@section Common Parameters +@cindex amd.conf common parameters + +These parameters can be specified either in the global or a map-specific +section. Entries specified in a map-specific section override the default +value or one defined in the global section. If such a common parameter is +specified only in the global section, it is applicable to all regular map +sections that follow. + +@menu +* browsable_dirs Parameter:: +* map_options Parameter:: +* map_type Parameter:: +* mount_type Parameter:: +* search_path Parameter:: +@end menu + +@c ---------------------------------------------------------------- +@node browsable_dirs Parameter, map_options Parameter, Common Parameters, Common Parameters +@comment node-name, next, previous, up +@subsection @t{browsable_dirs} Parameter +@cindex browsable_dirs Parameter + +(type=string, default=@samp{no}). If @samp{yes}, then @i{Amd}'s top-level +mount points will be browsable to @b{readdir}(3) calls. This means you +could run for example @b{ls}(1) and see what keys are available to mount +in that directory. Not all entries are made visible to @b{readdir}(3): +the @samp{/defaults} entry, wildcard entries, and those with a @file{/} +in them are not included. If you specify @samp{full} to this option, +all but the @samp{/defaults} entry will be visible. Note that if you run +a command which will attempt to @b{stat}(2) the entries, such as often +done by @samp{ls -l} or @samp{ls -F}, @i{Amd} will attempt to mount +@i{every} entry in that map. This is often called a ``mount storm''. + +@c ---------------------------------------------------------------- +@node map_options Parameter, map_type Parameter, browsable_dirs Parameter, Common Parameters +@comment node-name, next, previous, up +@subsection @t{map_options} Parameter +@cindex map_options Parameter + +(type=string, default no options). This option is the same as +specifying map options on the command line to @i{Amd}, such as +@samp{cache:=all}. + +@c ---------------------------------------------------------------- +@node map_type Parameter, mount_type Parameter, map_options Parameter, Common Parameters +@comment node-name, next, previous, up +@subsection @t{map_type} Parameter +@cindex map_type Parameter + +(type=string, default search all map types). If specified, @i{Amd} will +initialize the map only for the type given. This is useful to avoid the +default map search type used by @i{Amd} which takes longer and can have +undesired side-effects such as initializing NIS even if not used. +Possible values are + +@table @samp +@item file +plain files +@item hesiod +Hesiod name service from MIT +@item ldap +Lightweight Directory Access Protocol +@item ndbm +(New) dbm style hash files +@item nis +Network Information Services (version 2) +@item nisplus +Network Information Services Plus (version 3) +@item passwd +local password files +@item union +union maps +@end table + +@c ---------------------------------------------------------------- +@node mount_type Parameter, search_path Parameter, map_type Parameter, Common Parameters +@comment node-name, next, previous, up +@subsection @t{mount_type} Parameter +@cindex mount_type Parameter + +(type=string, default=@samp{nfs}). All @i{Amd} mount types default to NFS. +That is, @i{Amd} is an NFS server on the map mount points, for the local +host it is running on. If @samp{autofs} is specified, @i{Amd} will be +an autofs server for those mount points. + +@c ---------------------------------------------------------------- +@node search_path Parameter, , mount_type Parameter, Common Parameters +@comment node-name, next, previous, up +@subsection @t{search_path} Parameter +@cindex search_path Parameter + +(type=string, default no search path). This provides a +(colon-delimited) search path for file maps. Using a search path, +sites can allow for local map customizations and overrides, and can +distributed maps in several locations as needed. + +@c ================================================================ +@node Global Parameters, Regular Map Parameters, Common Parameters, Amd Configuration File +@comment node-name, next, previous, up +@section Global Parameters +@cindex amd.conf global parameters + +The following parameters are applicable to the @samp{[global]} section only. + +@menu +* arch Parameter:: +* auto_dir Parameter:: +* cache_duration Parameter:: +* cluster Parameter:: +* debug_options Parameter:: +* dismount_interval Parameter:: +* fully_qualified_hosts Parameter:: +* hesiod_base Parameter:: +* karch Parameter:: +* ldap_base Parameter:: +* ldap_cache_maxmem Parameter:: +* ldap_cache_seconds Parameter:: +* ldap_hostports Parameter:: +* local_domain Parameter:: +* log_file Parameter:: +* log_options Parameter:: +* nfs_retransmit_counter Parameter:: +* nfs_retry_interval Parameter:: +* nis_domain Parameter:: +* normalize_hostnames Parameter:: +* os Parameter:: +* osver Parameter:: +* pid_file Parameter:: +* plock Parameter:: +* portmap_program Parameter:: +* print_pid Parameter:: +* print_version Parameter:: +* restart_mounts Parameter:: +* selectors_on_default Parameter:: +* show_statfs_entries Parameter:: +* unmount_on_exit Parameter:: +@end menu + +@c ---------------------------------------------------------------- +@node arch Parameter, auto_dir Parameter, Global Parameters, Global Parameters +@comment node-name, next, previous, up +@subsection @t{arch} Parameter +@cindex arch Parameter + +(type=string, default to compiled in value). Allows you to override the +value of the @i{arch} @i{Amd} variable. + +@c ---------------------------------------------------------------- +@node auto_dir Parameter, cache_duration Parameter, arch Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{auto_dir} Parameter +@cindex auto_dir Parameter + +(type=string, default=@samp{/a}). Same as the @code{-a} option to @i{Amd}. +This sets the private directory where @i{Amd} will create +sub-directories for its real mount points. + +@c ---------------------------------------------------------------- +@node cache_duration Parameter, cluster Parameter, auto_dir Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{cache_duration} Parameter +@cindex cache_duration Parameter + +(type=numeric, default=300). Same as the @code{-c} option to +@i{Amd}. Sets the duration in seconds that looked up map entries remain +in the cache. + +@c ---------------------------------------------------------------- +@node cluster Parameter, debug_options Parameter, cache_duration Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{cluster} Parameter +@cindex cluster Parameter + +(type=string, default no cluster). Same as the @code{-C} option to +@i{Amd}. Specifies the alternate HP-UX cluster to use. + +@c ---------------------------------------------------------------- +@node debug_options Parameter, dismount_interval Parameter, cluster Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{debug_options} Parameter +@cindex debug_options Parameter + +(type=string, default no debug options). Same as the @code{-D} +option to @i{Amd}. Specify any debugging options for @i{Amd}. Works +only if am-utils was configured for debugging using the +@code{--enable-debug} option. The @samp{mem} option alone can be turned +on via @code{--enable-debug=mem}. Otherwise debugging options are +ignored. Options are comma delimited, and can be preceded by the string +@samp{no} to negate their meaning. You can get the list of supported +debugging options by running @code{amd -v}. Possible values are: + +@table @samp +@item all +all options +@item amq +register for amq +@item daemon +enter daemon mode +@item fork +fork server +@item full +program trace +@item mem +trace memory allocations +@item mtab +use local @file{./mtab} file +@item str +debug string munging +@item test +full debug but no daemon +@item trace +protocol trace +@end table + +@c ---------------------------------------------------------------- +@node dismount_interval Parameter, fully_qualified_hosts Parameter, debug_options Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{dismount_interval} Parameter +@cindex dismount_interval Parameter + +(type=numeric, default=120). Same as the @code{-w} option to +@i{Amd}. Specify in seconds, the time between attempts to dismount file +systems that have exceeded their cached times. + +@c ---------------------------------------------------------------- +@node fully_qualified_hosts Parameter, hesiod_base Parameter, dismount_interval Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{fully_qualified_hosts} Parameter +@cindex fully_qualified_hosts Parameter + +(type=string, default=@samp{no}). If @samp{yes}, @i{Amd} will perform RPC +authentication using fully-qualified host names. This is necessary for +some systems, and especially when performing cross-domain mounting. For +this function to work, the @i{Amd} variable @samp{$@{hostd@}} is used, +requiring that @samp{$@{domain@}} not be null. + +@c ---------------------------------------------------------------- +@node hesiod_base Parameter, karch Parameter, fully_qualified_hosts Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{hesiod_base} Parameter +@cindex hesiod_base Parameter + +(type=string, default=@samp{automount}). Specify the base name for +hesiod maps. + +@c ---------------------------------------------------------------- +@node karch Parameter, ldap_base Parameter, hesiod_base Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{karch} Parameter +@cindex karch Parameter + +(type=string, default to karch of the system). Same as the @code{-k} +option to @i{Amd}. Allows you to override the kernel-architecture of +your system. Useful for example on Sun (Sparc) machines, where you can +build one @i{Amd} binary, and run it on multiple machines, yet you want +each one to get the correct @i{karch} variable set (for example, sun4c, +sun4m, sun4u, etc.) Note that if not specified, @i{Amd} will use +@b{uname}(2) to figure out the kernel architecture of the machine. + +@c ---------------------------------------------------------------- +@node ldap_base Parameter, ldap_cache_maxmem Parameter, karch Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{ldap_base} Parameter +@cindex ldap_base Parameter + +(type=string, default not set). Specify the base name for +LDAP. + +@c ---------------------------------------------------------------- +@node ldap_cache_maxmem Parameter, ldap_cache_seconds Parameter, ldap_base Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{ldap_cache_maxmem} Parameter +@cindex ldap_cache_maxmem Parameter + +(type=numeric, default=131072). Specify the maximum memory @i{Amd} +should use to cache LDAP entries. + +@c ---------------------------------------------------------------- +@node ldap_cache_seconds Parameter, ldap_hostports Parameter, ldap_cache_maxmem Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{ldap_cache_seconds} Parameter +@cindex ldap_cache_seconds Parameter + +(type=numeric, default=0). Specify the number of seconds to keep +entries in the cache. + +@c ---------------------------------------------------------------- +@node ldap_hostports Parameter, local_domain Parameter, ldap_cache_seconds Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{ldap_hostports} Parameter +@cindex ldap_hostports Parameter + +(type=string, default not set). Specify +LDAP-specific values such as country and organization. + +@c ---------------------------------------------------------------- +@node local_domain Parameter, log_file Parameter, ldap_hostports Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{local_domain} Parameter +@cindex local_domain Parameter + +(type=string, default no sub-domain). Same as the @code{-d} option +to @i{Amd}. Specify the local domain name. If this option is not given +the domain name is determined from the hostname, by removing the first +component of the fully-qualified host name. + +@c ---------------------------------------------------------------- +@node log_file Parameter, log_options Parameter, local_domain Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{log_file} Parameter +@cindex log_file Parameter + +(type=string, default=@samp{stderr}). Same as the @code{-l} option to +@i{Amd}. Specify a file name to log @i{Amd} events to. +If the string @samp{/dev/stderr} is specified, +@i{Amd} will send its events to the standard error file descriptor. + +If the string @samp{syslog} is given, @i{Amd} will record its events +with the system logger @b{syslogd}(8). If your system supports syslog +facilities, then the default facility used is @samp{LOG_DAEMON}. + +When using syslog, if you wish to change the facility, append its name +to the option name, delimited by a single colon. For example, if it is +the string @samp{syslog:local7} then @i{Amd} will log messages via +@b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If the facility +name specified is not recognized, @i{Amd} will default to @samp{LOG_DAEMON}. +Note: while you can use any syslog facility available on your system, it +is generally a bad idea to use those reserved for other services such as +@samp{kern}, @samp{lpr}, @samp{cron}, etc. + +@c ---------------------------------------------------------------- +@node log_options Parameter, nfs_retransmit_counter Parameter, log_file Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{log_options} Parameter +@cindex log_options Parameter + +(type=string, default no logging options). Same as the @code{-x} +option to @i{Amd}. Specify any logging options for @i{Amd}. Options +are comma delimited, and can be preceded by the string @samp{no} to +negate their meaning. The @samp{debug} logging option is only available +if am-utils was configured with @code{--enable-debug}. You can get the +list of supported debugging options by running @code{amd -v}. Possible +values are: + +@table @samp +@item all +all messages +@item debug +debug messages +@item error +non-fatal system errors +@item fatal +fatal errors +@item info +information +@item map +map errors +@item stats +additional statistical information +@item user +non-fatal user errors +@item warn +warnings +@item warning +warnings +@end table + +@c ---------------------------------------------------------------- +@node nfs_retransmit_counter Parameter, nfs_retry_interval Parameter, log_options Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{nfs_retransmit_counter} Parameter +@cindex nfs_retransmit_counter Parameter + +(type=numeric, default=110). Same as the @i{counter} part of the +@code{-t} @i{interval.counter} option to @i{Amd}. Specifies the +retransmit counter's value in @emph{tenths} of seconds. + +@c ---------------------------------------------------------------- +@node nfs_retry_interval Parameter, nis_domain Parameter, nfs_retransmit_counter Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{nfs_retry_interval} Parameter +@cindex nfs_retry_interval Parameter + +(type=numeric, default=8). Same as the @i{interval} part of the +@code{-t} @i{interval.counter} option to @i{Amd}. Specifies the +interval in @emph{tenths} of seconds, between NFS/RPC/UDP retries. + +@c ---------------------------------------------------------------- +@node nis_domain Parameter, normalize_hostnames Parameter, nfs_retry_interval Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{nis_domain} Parameter +@cindex nis_domain Parameter + +(type=string, default to local NIS domain name). Same as the +@code{-y} option to @i{Amd}. Specify an alternative NIS domain from +which to fetch the NIS maps. The default is the system domain name. +This option is ignored if NIS support is not available. + +@c ---------------------------------------------------------------- +@node normalize_hostnames Parameter, os Parameter, nis_domain Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{normalize_hostnames} Parameter +@cindex normalize_hostnames Parameter + +(type=boolean, default=@samp{no}). Same as the @code{-n} option to @i{Amd}. +If @samp{yes}, then the name referred to by @code{$@{rhost@}} is normalized +relative to the host database before being used. The effect is to +translate aliases into ``official'' names. + +@c ---------------------------------------------------------------- +@node os Parameter, osver Parameter, normalize_hostnames Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{os} Parameter +@cindex os Parameter + +(type=string, default to compiled in value). Same as the @code{-O} +option to @i{Amd}. Allows you to override the compiled-in name of the +operating system. Useful when the built-in name is not desired for +backward compatibility reasons. For example, if the built-in name is +@samp{sunos5}, you can override it to @samp{sos5}, and use older maps +which were written with the latter in mind. + +@c ---------------------------------------------------------------- +@node osver Parameter, pid_file Parameter, os Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{osver} Parameter +@cindex osver Parameter + +(type=string, default to compiled in value). Same as the @code{-o} +option to @i{Amd}. Allows you to override the compiled-in version +number of the operating system. Useful when the built-in version is not +desired for backward compatibility reasons. For example, if the build +in version is @samp{2.5.1}, you can override it to @samp{5.5.1}, and use +older maps that were written with the latter in mind. + +@c ---------------------------------------------------------------- +@node pid_file Parameter, plock Parameter, osver Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{pid_file} Parameter +@cindex pid_file Parameter + +(type=string, default=@samp{/dev/stdout}). Specify a file to store the process +ID of the running daemon into. If not specified, @i{Amd} will print its +process id onto the standard output. Useful for killing @i{Amd} after +it had run. Note that the PID of a running @i{Amd} can also be +retrieved via @i{Amq} (@pxref{Amq -p option}). + +This file is used only if the @samp{print_pid} option is on +(@pxref{print_pid Parameter}). + +@c ---------------------------------------------------------------- +@node plock Parameter, portmap_program Parameter, pid_file Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{plock} Parameter +@cindex plock Parameter + +(type=boolean, default=@samp{yes}). Same as the @code{-S} option to @i{Amd}. +If @samp{yes}, lock the running executable pages of @i{Amd} into memory. +To improve @i{Amd}'s performance, systems that support the @b{plock}(3) +call can lock the @i{Amd} process into memory. This way there is less +chance the operating system will schedule, page out, and swap the +@i{Amd} process as needed. This improves @i{Amd}'s performance, at the +cost of reserving the memory used by the @i{Amd} process (making it +unavailable for other processes). + +@c ---------------------------------------------------------------- +@node portmap_program Parameter, print_pid Parameter, plock Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{portmap_program} Parameter +@cindex portmap_program Parameter + +(type=numeric, default=300019). Specify an alternate Port-mapper RPC +program number, other than the official number. This is useful when +running multiple @i{Amd} processes. For example, you can run another +@i{Amd} in ``test'' mode, without affecting the primary @i{Amd} process +in any way. For safety reasons, the alternate program numbers that can +be specified must be in the range 300019-300029, inclusive. @i{Amq} has +an option @code{-P} which can be used to specify an alternate program +number of an @i{Amd} to contact. In this way, amq can fully control any +number of @i{Amd} processes running on the same host. + +@c ---------------------------------------------------------------- +@node print_pid Parameter, print_version Parameter, portmap_program Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{print_pid} Parameter +@cindex print_pid Parameter + +(type=boolean, default=@samp{no}). Same as the @code{-p} option to @i{Amd}. +If @samp{yes}, @i{Amd} will print its process ID upon starting. + +@c ---------------------------------------------------------------- +@node print_version Parameter, restart_mounts Parameter, print_pid Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{print_version} Parameter +@cindex print_version Parameter + +(type=boolean, default=@samp{no}). Same as the @code{-v} option to @i{Amd}, +but the version prints and @i{Amd} continues to run. If @samp{yes}, @i{Amd} +will print its version information string, which includes some +configuration and compilation values. + +@c ---------------------------------------------------------------- +@node restart_mounts Parameter, selectors_on_default Parameter, print_version Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{restart_mounts} Parameter +@cindex restart_mounts Parameter + +(type=boolean, default=@samp{no}). Same as the @code{-r} option to @i{Amd}. +If @samp{yes} @i{Amd} will scan the mount table to determine which file +systems are currently mounted. Whenever one of these would have been +auto-mounted, @i{Amd} inherits it. + +@c ---------------------------------------------------------------- +@node selectors_on_default Parameter, show_statfs_entries Parameter, restart_mounts Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{selectors_on_default} Parameter +@cindex selectors_on_default Parameter + +(type=boolean, default=@samp{no}). If @samp{yes}, then the @samp{/defaults} entry of +maps will be looked for and any selectors processed before setting defaults +for all other keys in that map. Useful when you want to set different +options for a complete map based on some parameters. For example, you +may want to better the NFS performance over slow slip-based networks as +follows: + +@example +/defaults \ + wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \ + wire!=slip-net;opts:=intr,rsize=8192,wsize=8192 +@end example + +@c ---------------------------------------------------------------- +@node show_statfs_entries Parameter, unmount_on_exit Parameter , selectors_on_default Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{show_statfs_entries} Parameter +@cindex show_statfs_entries Parameter + +(type=boolean), default=@samp{no}). If @samp{yes}, then all maps which are +browsable will also show the number of entries (keys) they have when +@b{df}(1) runs. (This is accomplished by returning non-zero values to +the @b{statfs}(2) system call). + +@c ---------------------------------------------------------------- +@node unmount_on_exit Parameter, , show_statfs_entries Parameter, Global Parameters +@comment node-name, next, previous, up +@subsection @t{unmount_on_exit} Parameter +@cindex unmount_on_exit Parameter + +(type=boolean), default=@samp{no}). If @samp{yes}, then @i{Amd} will attempt +to unmount all file systems which it knows about. Normally it leaves +all (esp. NFS) mounted file systems intact. Note that @i{Amd} does not +know about file systems mounted before it starts up, unless the +@samp{restart_mounts} option is used (@pxref{restart_mounts Parameter}). + +@c ================================================================ +@node Regular Map Parameters, amd.conf Examples, Global Parameters, Amd Configuration File +@comment node-name, next, previous, up +@section Regular Map Parameters +@cindex amd.conf regular map parameters + +The following parameters are applicable only to regular map sections. + +@menu +* map_name Parameter:: +* tag Parameter:: +@end menu + +@c ---------------------------------------------------------------- +@node map_name Parameter, tag Parameter, Regular Map Parameters, Regular Map Parameters +@comment node-name, next, previous, up +@subsection map_name Parameter +@cindex map_name Parameter + +(type=string, must be specified). Name of the map where the keys are +located. + +@c ---------------------------------------------------------------- +@node tag Parameter, , map_name Parameter, Regular Map Parameters +@comment node-name, next, previous, up +@subsection tag Parameter +@cindex tag Parameter + +(type=string, default no tag). Each map entry in the configuration file +can be tagged. If no tag is specified, that map section will always be +processed by @i{Amd}. If it is specified, then @i{Amd} will process the map +if the @code{-T} option was given to @i{Amd}, and the value given to that +command-line option matches that in the map section. + +@c ================================================================ +@node amd.conf Examples, , Regular Map Parameters, Amd Configuration File +@comment node-name, next, previous, up +@section amd.conf Examples +@cindex amd.conf examples + +The following is the actual @code{amd.conf} file I use at the +Computer Science Department of Columbia University. + +@example +# GLOBAL OPTIONS SECTION +[ global ] +normalize_hostnames = no +print_pid = no +#pid_file = /var/run/amd.pid +restart_mounts = yes +#unmount_on_exit = yes +auto_dir = /n +log_file = /var/log/amd +log_options = all +#debug_options = all +plock = no +selectors_on_default = yes +# config.guess picks up "sunos5" and I don't want to edit my maps yet +os = sos5 +# if you print_version after setting up "os", it will show it. +print_version = no +map_type = file +search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib +browsable_dirs = yes +fully_qualified_hosts = no + +# DEFINE AN AMD MOUNT POINT +[ /u ] +map_name = amd.u + +[ /proj ] +map_name = amd.proj + +[ /src ] +map_name = amd.src + +[ /misc ] +map_name = amd.misc + +[ /import ] +map_name = amd.import + +[ /tftpboot/.amd ] +tag = tftpboot +map_name = amd.tftpboot +@end example + +@c ################################################################ +@node Run-time Administration, FSinfo, Amd Configuration File, Top +@comment node-name, next, previous, up +@chapter Run-time Administration +@cindex Run-time administration +@cindex Amq command + +@menu +* Starting Amd:: +* Stopping Amd:: +* Restarting 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 ctl-amd + +@i{Amd} is best started from @samp{/etc/rc.local} on BSD systems, or +from the appropriate start-level script in @samp{/etc/init.d} on System V +systems. + +@example +if [ -f /usr/local/sbin/ctl-amd ]; then + /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console +fi +@end example + +@noindent +The shell script, @samp{ctl-amd} is used to start, stop, or restart +@i{Amd}. It is a relatively generic script. All options you want to +set should not be made in this script, but rather updated in the +@file{amd.conf} file. @xref{Amd Configuration File}. + +If you do not wish to use an @i{Amd} configuration file, you may start +@i{Amd} manually. For example, getting the map entries via NIS: + +@example +amd -r -l /var/log/amd `ypcat -k auto.master` +@end example + +@node Stopping Amd, Restarting 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 @code{-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 primarily used for debugging.@refill +@end table + +Actions taken for other signals are undefined. + +The easiest and safest way to stop @i{Amd}, without having to find its +process ID by hand, is to use the @file{ctl-amd} script, as with: + +@example +ctl-amd stop +@end example + +@node Restarting Amd, Controlling Amd, Stopping Amd, Run-time Administration +@comment node-name, next, previous, up +@section Restarting @i{Amd} +@cindex Restarting Amd +@cindex Killing and starting Amd + +Before @i{Amd} can be started, it is vital to ensure that no other +@i{Amd} processes are managing any of the mount points, and that the +previous process(es) have terminated cleanly. When a terminating signal +is set to @i{Amd}, the automounter does @emph{not} terminate right then. +Rather, it starts by unmounting all of its managed mount mounts in the +background, and then terminates. It usually takes a few seconds for +this process to happen, but it can take an arbitrarily longer time. If +two or more @i{Amd} processes attempt to manage the same mount point, it +usually will result in a system lockup. + +The easiest and safest way to restart @i{Amd}, without having to find +its process ID by hand, sending it the @samp{SIGTERM} signal, waiting for @i{Amd} +to die cleanly, and verifying so, is to use the @file{ctl-amd} script, +as with: + +@example +ctl-amd restart +@end example + +The script will locate the process ID of @i{Amd}, kill it, and wait for +it to die cleanly before starting a new instance of the automounter. +@file{ctl-amd} will wait for a total of 30 seconds for @i{Amd} to die, +and will check once every 5 seconds if it had. + +@node Controlling Amd, , Restarting 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 behavior. +* Amq -f option:: Flushing the map cache. +* Amq -h option:: Controlling a non-local host. +* Amq -l option:: Controlling the log file. +* Amq -m option:: Obtaining mount statistics. +* Amq -M-option:: Mounting a volume. +* Amq -p option:: Getting Amd's process ID. +* Amq -P-option:: Contacting alternate Amd processes. +* Amq -s option:: Obtaining global statistics. +* Amq -T option:: Use TCP transport. +* Amq -U-option:: Use UDP transport. +* Amq -u option:: Forcing volumes to time out. +* Amq -v option:: Version information. +* Other Amq options:: Three other special options. +@end menu + +@c ---------------------------------------------------------------- +@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 count 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 + +@c ---------------------------------------------------------------- +@node Amq -f option, Amq -h option, Amq default, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-f} option +@cindex Flushing the map cache +@cindex Map cache, flushing + +The @code{-f} option causes @i{Amd} to flush the internal mount map cache. +This is useful for example in Hesiod maps since @i{Amd} will not +automatically notice when they have been updated. The map cache can +also be synchronized with the map source by using the @samp{sync} option +(@pxref{Automount Filesystem}).@refill + +@c ---------------------------------------------------------------- +@node Amq -l option, Amq -m option, Amq -h option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-l} option +@cindex Resetting the Amd log file +@cindex Setting the Amd log file via Amq +@cindex Log file, resetting + +Tell @i{Amd} to use @i{log_file} as the log file name. For security +reasons, this @emph{must} be the same log file which @i{Amd} used when +started. This option is therefore only useful to refresh @i{Amd}'s open +file handle on the log file, so that it can be rotated and compressed +via daily cron jobs. + +@c ---------------------------------------------------------------- +@node Amq -h option, Amq -l option, Amq -f option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-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 @code{-h} option should +be used. + +@c ---------------------------------------------------------------- +@node Amq -m option, Amq -M-option, Amq -l option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-m} option + +The @code{-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 occurred. +@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}. + +@c ---------------------------------------------------------------- +@node Amq -M-option, Amq -p option, Amq -m option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-M} option + +The @code{-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. + +This option is very insecure as it is vulnerable to attacks such as IP +Spoofing. In other words, it is relatively easy for an attacker who +really wants to, to make your @i{Amd} process mount any filesystem from +the Internet! Therefore, the @emph{complete} code which supports the +@code{-M} option in @i{Amd} and @i{Amq} is turned off by default. To turn +it on, you have to reconfigure am-utils with @code{configure +--enable-amq-mount}. Think twice before doing so, and use this option +only if you absolutely need to. + +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. + +@c ---------------------------------------------------------------- +@node Amq -p option, Amq -P-option, Amq -M-option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-p} option +@cindex Process ID; Amd +@cindex Amd's process ID +@cindex Amd's PID +@cindex PID; Amd + +Return the process ID of the remote or locally running @i{Amd}. Useful +when you need to send a signal to the local @i{Amd} process, and would +rather not have to search through the process table. This option is +used in the @file{ctl-amd} script. + +@c ---------------------------------------------------------------- +@node Amq -P-option, Amq -s option, Amq -p option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-P} option +@cindex Multiple Amd processes +@cindex Running multiple Amd +@cindex Debugging a new Amd configuration +@cindex RPC Program numbers; Amd + +Contact an alternate running @i{Amd} that had registered itself on a +different RPC @var{program_number} and apply all other operations to +that instance of the automounter. This is useful when you run multiple +copies of @i{Amd}, and need to manage each one separately. If not +specified, @i{Amq} will use the default program number for @i{Amd}, 300019. +For security reasons, the only alternate program numbers @i{Amd} can use +range from 300019 to 300029, inclusive. + +For example, to kill an alternate running @i{Amd}: + +@example +kill `amq -p -P 300020` +@end example + +@c ---------------------------------------------------------------- +@node Amq -s option, Amq -T option, Amq -P-option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-s} option +@cindex Global statistics +@cindex Statistics + +The @code{-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 + +@c ---------------------------------------------------------------- +@node Amq -T option, Amq -U-option, Amq -s option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-T} option +@cindex Forcing Amq to use a TCP transport +@cindex TCP; using with Amq + +The @code{-T} option causes the @i{Amq} to contact @i{Amd} using the TCP +transport only (connection oriented). Normally, @i{Amq} will use TCP +first, and if that failed, will try UDP. + +@c ---------------------------------------------------------------- +@node Amq -U-option, Amq -u option, Amq -T option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-U} option +@cindex Forcing Amq to use a UDP transport +@cindex UDP; using with Amq + +The @code{-U} option causes the @i{Amq} to contact @i{Amd} using the UDP +transport only (connectionless). Normally, @i{Amq} will use TCP first, +and if that failed, will try UDP. + +@c ---------------------------------------------------------------- +@node Amq -u option, Amq -v option, Amq -U-option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-u} option +@cindex Forcing filesystem to time out +@cindex Unmounting a filesystem + +The @code{-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 @code{-H} option informs @i{Amd} that the specified mount point has hung - +@c as if its keepalive timer had expired. + +@c ---------------------------------------------------------------- +@node Amq -v option, Other Amq options, Amq -u option, Controlling Amd +@comment node-name, next, previous, up +@subsection @i{Amq} @code{-v} option +@cindex Version information at run-time + +The @code{-v} option displays the version of @i{Amd} in a similar way to +@i{Amd}'s @code{-v} option. + +@c ---------------------------------------------------------------- +@node Other Amq options, , Amq -v option, Controlling Amd +@comment node-name, next, previous, up +@subsection Other @i{Amq} options +@cindex Logging options via Amq +@cindex Debugging options via Amq + +Two other operations are implemented. These modify the state of @i{Amd} +as a whole, rather than any particular filesystem. The @code{-x} and +@code{-D} options have exactly the same effect as @i{Amd}'s corresponding +command line options. + +When @i{Amd} receives a @code{-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 on since then can still be +turned off. The @code{-D} option has a similar behavior. + +@c ################################################################ +@node FSinfo, Hlfsd, Run-time Administration, Top +@comment node-name, next, previous, up +@chapter FSinfo +@cindex FSinfo +@cindex Filesystem info package + +XXX: this chapter should be reviewed by someone knowledgeable with +fsinfo. + +@menu +* FSinfo Overview:: Introduction to FSinfo. +* Using FSinfo:: Basic concepts. +* FSinfo Grammar:: Language syntax, semantics and examples. +* FSinfo host definitions:: Defining a new host. +* FSinfo host attributes:: Definable host attributes. +* FSinfo filesystems:: Defining locally attached filesystems. +* FSinfo static mounts:: Defining additional static mounts. +* FSinfo automount definitions:: +* FSinfo Command Line Options:: +* FSinfo errors:: +@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 flavor. 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" @i{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 optimize 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 analyzed 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}. + +@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}] @i{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 +@i{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 @file{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 diskfull 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 " expected +Occurs if an unescaped newline is found in a quoted string. + +@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. + +@item can't open @var{filename} for writing +Occurs if any errors are encountered when opening an output file. + +@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. + +@item @var{device} has duplicate exportfs data +Produced if the @samp{exportfs} option is used multiple times within the +same branch of a filesystem definition. For example, if you attempt to +set the @samp{exportfs} data at different levels of the mountpoint +directory tree. + +@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. + +@item duplicate host @var{hostname}! +If a host has more than one definition. + +@item end of file within comment +A comment was unterminated before the end of one of the configuration +files. + +@item @var{filename}: cannot open for reading +If a file specified on the command line as containing configuration data +could not be opened. + +@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 fs field "@var{field-name}" already set +Occurs when multiple definitions are given for one of the attributes of a +host's filesystem. + +@item host field "@var{field-name}" already set +If duplicate definitions are given for any of the fields with a host +definition. + +@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. + +@item @var{host}:@var{device} has no mount point +Occurs if the @samp{mount} option is not specified for a host's +filesystem. + +@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 @samp{fstype}, @samp{opts}, @samp{passno} or +@samp{mount}. + +@item @var{host}:mount field specified for swap partition +Occurs if a mountpoint is given for a filesystem whose type is declared +to be @samp{swap}. + +@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. + +@item mount field "@var{field-name}" already set +Occurs when a static mount has multiple definitions of the same field. + +@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 netif field @var{field-name} already set +Occurs if you attempt to define an attribute of an interface more than +once. + +@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. + +@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 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. + +@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 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}. + +@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. + +@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. + +@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. + +@item unknown directory attribute +If an unknown keyword is found while reading the definition of a host's +filesystem mount option. + +@item unknown filesystem attribute +Occurs if an unrecognized keyword is used when defining a host's +filesystems. + +@item unknown host attribute +Occurs if an unrecognized keyword is used when defining a host. + +@item unknown mount attribute +Occurs if an unrecognized keyword is found while parsing the list of +static mounts. + +@item unknown volname @var{volume} automounted @i{[} on @i{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. + +@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. + +@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. + +@end table + +@c ################################################################ +@node Hlfsd, Assorted Tools, FSinfo, Top +@comment node-name, next, previous, up +@chapter Hlfsd +@pindex Hlfsd +@cindex Home-Link Filesystem + +@i{Hlfsd} is a daemon which implements a filesystem containing a +symbolic link to subdirectory within a user's home directory, depending +on the user which accessed that link. It was primarily designed to +redirect incoming mail to users' home directories, so that it can be read +from anywhere. It was designed and implemented by +@email{ezk@@cs.columbia.edu,Erez Zadok} and +@email{dupuy@@cs.columbia.edu,Alexander Dupuy}, at the +@uref{http://www.cs.columbia.edu/,Computer Science Department} of +@uref{http://www.columbia.edu/,Columbia University}. A +@uref{http://www.cs.columbia.edu/~ezk/research/hlfsd/hlfsd.html,paper} +on @i{Hlfsd} was presented at the Usenix LISA VII conference in 1993. + +@i{Hlfsd} operates by mounting itself as an NFS server for the directory +containing @i{linkname}, which defaults to @file{/hlfs/home}. Lookups +within that directory are handled by @i{Hlfsd}, which uses the +password map to determine how to resolve the lookup. The directory will +be created if it doesn't already exist. The symbolic link will be to +the accessing user's home directory, with @i{subdir} appended to it. If +not specified, @i{subdir} defaults to @file{.hlfsdir}. This directory +will also be created if it does not already exist. + +A @samp{SIGTERM} sent to @i{Hlfsd} will cause it to shutdown. A @samp{SIGHUP} will +flush the internal caches, and reload the password map. It will also +close and reopen the log file, to enable the original log file to be +removed or rotated. A @samp{SIGUSR1} will cause it to dump its internal table +of user IDs and home directories to the file @file{/tmp/hlfsddump}. + +@menu +* Introduction to Hlfsd:: +* Background to Mail Delivery:: +* Using Hlfsd:: +@end menu + +@c ================================================================ +@node Introduction to Hlfsd, Background to Mail Delivery, Hlfsd, Hlfsd +@comment node-name, next, previous, up +@section Introduction to Hlfsd +@cindex Introduction to Hlfsd +@cindex Hlfsd; introduction + +Electronic mail has become one of the major applications for many +computer networks, and use of this service is expected to increase over +time, as networks proliferate and become faster. Providing a convenient +environment for users to read, compose, and send electronic mail has +become a requirement for systems administrators (SAs). + +Widely used methods for handling mail usually require users to be logged +into a designated ``home'' machine, where their mailbox files reside. +Only on that one machine can they read newly arrived mail. Since users +have to be logged into that system to read their mail, they often find +it convenient to run all of their other processes on that system as +well, including memory and CPU-intensive jobs. For example, in our +department, we have allocated and configured several multi-processor +servers to handle such demanding CPU/memory applications, but these were +underutilized, in large part due to the inconvenience of not being able +to read mail on those machines. (No home directories were located on +these designated CPU-servers, since we did not want NFS service for +users' home directories to have to compete with CPU-intensive jobs. At the +same time, we discouraged users from running demanding applications on +their home machines.) + +Many different solutions have been proposed to allow users to read their +mail on any host. However, all of these solutions fail in one or more +of several ways: + +@itemize @bullet + +@item +they introduce new single points of failure + +@item +they require using different mail transfer agents (MTAs) or user agents +(UAs) + +@item +they do not solve the problem for all cases, i.e. the solution is only +partially successful for a particular environment. + +@end itemize + +We have designed a simple filesystem, called the @dfn{Home-Link File +System}, to provide the ability to deliver mail to users' home +directories, without modification to mail-related applications. We have +endeavored to make it as stable as possible. Of great importance to us +was to make sure the HLFS daemon, @file{hlfsd} , would not hang under +any circumstances, and would take the next-best action when faced with +problems. Compared to alternative methods, @i{Hlfsd} is a stable, more +general solution, and easier to install/use. In fact, in some ways, we +have even managed to improve the reliability and security of mail +service. + +Our server implements a small filesystem containing a symbolic link +to a subdirectory of the invoking user's home directory, and named symbolic +links to users' mailbox files. + +The @i{Hlfsd} server finds out the @var{uid} of the process that is +accessing its mount point, and resolves the pathname component @samp{home} as a +symbolic link to a subdirectory within the home directory given by the +@var{uid}'s entry in the password file. If the @var{gid} of the process +that attempts to access a mailbox file is a special one (called +HLFS_GID), then the server maps the name of the @emph{next} pathname +component directly to the user's mailbox. This is necessary so that +access to a mailbox file by users other than the owner can succeed. The +server has safety features in case of failures such as hung filesystems +or home directory filesystems that are inaccessible or full. + +On most of our machines, mail gets delivered to the directory +@file{/var/spool/mail}. Many programs, including UAs, depend on that +path. @i{Hlfsd} creates a directory @file{/mail}, and mounts itself on +top of that directory. @i{Hlfsd} implements the path name component +called @samp{home}, pointing to a subdirectory of the user's home directory. +We have made @file{/var/spool/mail} a symbolic link to +@file{/mail/home}, so that accessing @file{/var/spool/mail} actually +causes access to a subdirectory within a user's home directory. + +The following table shows an example of how resolving the pathname +@file{/var/mail/@i{NAME}} to @file{/users/ezk/.mailspool/@i{NAME}} proceeds. + +@multitable {Resolving Component} {Pathname left to resolve} {Value if symbolic link} + +@item @b{Resolving Component} +@tab @b{Pathname left to resolve} +@tab @b{Value if symbolic link} + +@item @t{/} +@tab @t{var/mail/}@i{NAME} + +@item @t{var/} +@tab @t{mail/}@i{NAME} + +@item @t{mail}@@ +@tab @t{/mail/home/}@i{NAME} +@tab @t{mail}@@ -> @t{/mail/home} + +@item @t{/} +@tab @t{mail/home/}@i{NAME} + +@item @t{mail/} +@tab @t{home/}@i{NAME} + +@item @t{home}@@ +@tab @i{NAME} +@tab @t{home}@@ -> @t{/users/ezk/.mailspool} + +@item @t{/} +@tab @t{users/ezk/.mailspool/}@i{NAME} + +@item @t{users/} +@tab @t{ezk/.mailspool/}@i{NAME} + +@item @t{ezk/} +@tab @t{.mailspool/}@i{NAME} + +@item @t{.mailspool/} +@tab @i{NAME} + +@item @i{NAME} + +@end multitable + +@c ================================================================ +@node Background to Mail Delivery, Using Hlfsd, Introduction to Hlfsd, Hlfsd +@comment node-name, next, previous, up +@section Background to Mail Delivery +@cindex Background to Mail Delivery +@cindex Hlfsd; background + +This section provides an in-depth discussion of why available methods +for delivering mail to home directories are not as good as the one used +by @i{Hlfsd}. + +@menu +* Single-Host Mail Spool Directory:: +* Centralized Mail Spool Directory:: +* Distributed Mail Spool Service:: +* Why Deliver Into the Home Directory?:: +@end menu + +@c ---------------------------------------------------------------- +@node Single-Host Mail Spool Directory, Centralized Mail Spool Directory, Background to Mail Delivery, Background to Mail Delivery +@comment node-name, next, previous, up +@subsection Single-Host Mail Spool Directory +@cindex Single-Host Mail Spool Directory + +The most common method for mail delivery is for mail to be appended to a +mailbox file in a standard spool directory on the designated ``mail +home'' machine of the user. The greatest advantage of this method is +that it is the default method most vendors provide with their systems, +thus very little (if any) configuration is required on the SA's part. +All they need to set up are mail aliases directing mail to the host on +which the user's mailbox file is assigned. (Otherwise, mail is +delivered locally, and users find mailboxes on many machines.) + +As users become more sophisticated, and aided by windowing systems, they +find themselves logging in on multiple hosts at once, performing several +tasks concurrently. They ask to be able to read their mail on any host +on the network, not just the one designated as their ``mail home''. + +@c ---------------------------------------------------------------- +@node Centralized Mail Spool Directory, Distributed Mail Spool Service, Single-Host Mail Spool Directory, Background to Mail Delivery +@comment node-name, next, previous, up +@subsection Centralized Mail Spool Directory +@cindex Centralized Mail Spool Directory + +A popular method for providing mail readability from any host is to have +all mail delivered to a mail spool directory on a designated +``mail-server'' which is exported via NFS to all of the hosts on the +network. Configuring such a system is relatively easy. On most +systems, the bulk of the work is a one-time addition to one or two +configuration files in @file{/etc}. The file-server's spool directory +is then hard-mounted across every machine on the local network. In +small environments with only a handful of hosts this can be an +acceptable solution. In our department, with a couple of hundred active +hosts and thousands of mail messages processed daily, this was deemed +completely unacceptable, as it introduced several types of problems: + +@table @b + +@item Scalability and Performance + +As more and more machines get added to the network, more mail traffic +has to go over NFS to and from the mail-server. Users like to run +mail-watchers, and read their mail often. The stress on the shared +infrastructure increases with every user and host added; loads on the +mail server would most certainly be high since all mail delivery goes +through that one machine.@footnote{ Delivery via NFS-mounted filesystems +may require usage of @samp{rpc.lockd} and @samp{rpc.statd} to provide +distributed file-locking, both of which are widely regarded as unstable +and unreliable. Furthermore, this will degrade performance, as local +processes as well as remote @samp{nfsd} processes are kept busy.} This +leads to lower reliability and performance. To reduce the number of +concurrent connections between clients and the server host, some SAs +have resorted to automounting the mail-spool directory. But this +solution only makes things worse: since users often run mail watchers, +and many popular applications such as @samp{trn}, @samp{emacs}, +@samp{csh} or @samp{ksh} check periodically for new mail, the +automounted directory would be effectively permanently mounted. If it +gets unmounted automatically by the automounter program, it is most +likely to get mounted shortly afterwards, consuming more I/O resources +by the constant cycle of mount and umount calls. + +@item Reliability + +The mail-server host and its network connectivity must be very reliable. +Worse, since the spool directory has to be hard-mounted,@footnote{No SA +in their right minds would soft-mount read/write partitions --- the +chances for data loss are too great.} many processes which access the +spool directory (various shells, @samp{login}, @samp{emacs}, etc.) +would be hung as long as connectivity to the mail-server is severed. To +improve reliability, SAs may choose to backup the mail-server's spool +partition several times a day. This may make things worse since reading +or delivering mail while backups are in progress may cause backups to be +inconsistent; more backups consume more backup-media resources, and +increase the load on the mail-server host. + +@end table + +@c ---------------------------------------------------------------- +@node Distributed Mail Spool Service, Why Deliver Into the Home Directory?, Centralized Mail Spool Directory, Background to Mail Delivery +@comment node-name, next, previous, up +@subsection Distributed Mail Spool Service +@cindex Distributed Mail Spool Service + +Despite the existence of a few systems that support delivery to users' +home directories, mail delivery to home directories hasn't caught on. +We believe the main reason is that there are too many programs that +``know'' where mailbox files reside. Besides the obvious (the delivery +program @file{/bin/mail} and mail readers like @file{/usr/ucb/Mail}, +@samp{mush}, @samp{mm}, etc.), other programs that know mailbox location +are login, from, almost every shell, @samp{xbiff}, @samp{xmailbox}, and +even some programs not directly related to mail, such as @samp{emacs} +and @samp{trn}. Although some of these programs can be configured to +look in different directories with the use of environment variables and +other resources, many of them cannot. The overall porting work is +significant. + +Other methods that have yet to catch on require the use of a special +mail-reading server, such as IMAP or POP. The main disadvantage of +these systems is that UAs need to be modified to use these services --- +a long and involved task. That is why they are not popular at this +time. + +Several other ideas have been proposed and even used in various +environments. None of them is robust. They are mostly very +specialized, inflexible, and do not extend to the general case. Some of +the ideas are plain bad, potentially leading to lost or corrupt mail: + +@table @b + +@item automounters + +Using an automounter such as @i{Amd} to provide a set of symbolic links +from the normal spool directory to user home directories is not +sufficient. UAs rename, unlink, and recreate the mailbox as a regular +file, therefore it must be a real file, not a symbolic link. +Furthermore, it must reside in a real directory which is writable by the +UAs and MTAs. This method may also require populating +@file{/var/spool/mail} with symbolic links and making sure they are +updated. Making @i{Amd} manage that directory directly fails, since +many various lock files need to be managed as well. Also, @i{Amd} does +not provide all of the NFS operations which are required to write mail +such as write, create, remove, and unlink. + +@item @code{$MAIL} + +Setting this variable to an automounted directory pointing to the user's +mail spool host only solves the problem for those programs which know +and use @code{$MAIL}. Many programs don't, therefore this solution is partial +and of limited flexibility. Also, it requires the SAs or the users to +set it themselves --- an added level of inconvenience and possible +failures. + +@item @t{/bin/mail} + +Using a different mail delivery agent could be the solution. One such +example is @samp{hdmail}. However, @samp{hdmail} still requires +modifying all UAs, the MTA's configuration, installing new daemons, and +changing login scripts. This makes the system less upgradable or +compatible with others, and adds one more complicated system for SAs to +deal with. It is not a complete solution because it still requires each +user have their @code{$MAIL} variable setup correctly, and that every program +use this variable. + +@end table + +@c ---------------------------------------------------------------- +@node Why Deliver Into the Home Directory?, , Distributed Mail Spool Service, Background to Mail Delivery +@comment node-name, next, previous, up +@subsection Why Deliver Into the Home Directory? +@cindex Why Deliver Into the Home Directory? +@cindex Hlfsd; Why Deliver Into the Home Directory? + +There are several major reasons why SAs might want to deliver mail +directly into the users' home directories: + +@table @b + +@item Location + +Many mail readers need to move mail from the spool directory to the +user's home directory. It speeds up this operation if the two are on +the same filesystem. If for some reason the user's home directory is +inaccessible, it isn't that useful to be able to read mail, since there +is no place to move it to. In some cases, trying to move mail to a +non-existent or hung filesystem may result in mail loss. + +@item Distribution + +Having all mail spool directories spread among the many more filesystems +minimizes the chances that complete environments will grind to a halt +when a single server is down. It does increase the chance that there +will be someone who is not able to read their mail when a machine is +down, but that is usually preferred to having no one be able to read +their mail because a centralized mail server is down. The problem of +losing some mail due to the (presumably) higher chances that a user's +machine is down is minimized in HLFS. + +@item Security + +Delivering mail to users' home directories has another advantage --- +enhanced security and privacy. Since a shared system mail spool +directory has to be world-readable and searchable, any user can see +whether other users have mail, when they last received new mail, or when +they last read their mail. Programs such as @samp{finger} display this +information, which some consider an infringement of privacy. While it +is possible to disable this feature of @samp{finger} so that remote +users cannot see a mailbox file's status, this doesn't prevent local +users from getting the information. Furthermore, there are more +programs which make use of this information. In shared environments, +disabling such programs has to be done on a system-wide basis, but with +mail delivered to users' home directories, users less concerned with +privacy who do want to let others know when they last received or read +mail can easily do so using file protection bits. + +@c Lastly, on systems that do not export their NFS filesystem with +@c @t{anon=0}, superusers are less likely to snoop around others' mail, as +@c they become ``nobodies'' across NFS. + +@end table + +In summary, delivering mail to home directories provides users the +functionality sought, and also avoids most of the problems just +discussed. + +@c ================================================================ +@node Using Hlfsd, , Background to Mail Delivery, Hlfsd +@comment node-name, next, previous, up +@section Using Hlfsd +@cindex Using Hlfsd +@cindex Hlfsd; using + +@menu +* Controlling Hlfsd:: +* Hlfsd Options:: +* Hlfsd Files:: +@end menu + +@c ---------------------------------------------------------------- +@node Controlling Hlfsd, Hlfsd Options, Using Hlfsd, Using Hlfsd +@comment node-name, next, previous, up +@subsection Controlling Hlfsd +@cindex Controlling Hlfsd +@cindex Hlfsd; controlling +@pindex ctl-hlfsd + +Much the same way @i{Amd} is controlled by @file{ctl-amd}, so does +@i{Hlfsd} get controlled by the @file{ctl-hlfsd} script: + +@table @t + +@item ctl-hlfsd start +Start a new @i{Hlfsd}. + +@item ctl-hlfsd stop +Stop a running @i{Hlfsd}. + +@item ctl-hlfsd restart +Stop a running @i{Hlfsd}, wait for 10 seconds, and then start a new +one. It is hoped that within 10 seconds, the previously running +@i{Hlfsd} terminate properly; otherwise, starting a second one could +cause system lockup. + +@end table + +For example, on our systems, we start @i{Hlfsd} within @file{ctl-hlfsd} +as follows on Solaris 2 systems: + +@example +hlfsd -a /var/alt_mail -x all -l /var/log/hlfsd /mail/home .mailspool +@end example + +The directory @file{/var/alt_mail} is a directory in the root partition +where alternate mail will be delivered into, when it cannot be delivered +into the user's home directory. + +Normal mail gets delivered into @file{/var/mail}, but on our systems, +that is a symbolic link to @file{/mail/home}. @file{/mail} is managed +by @i{Hlfsd}, which creates a dynamic symlink named @samp{home}, +pointing to the subdirectory @file{.mailspool} @emph{within} the +accessing user's home directory. This results in mail which normally +should go to @file{/var/mail/@code{$USER}}, to go to +@file{@code{$HOME}/.mailspool/@code{$USER}}. + +@i{Hlfsd} does not create the @file{/var/mail} symlink. This needs to +be created (manually) once on each host, by the system administrators, +as follows: + +@example +mv /var/mail /var/alt_mail +ln -s /mail/home /var/mail +@end example + +@c ---------------------------------------------------------------- +@node Hlfsd Options, Hlfsd Files, Controlling Hlfsd, Using Hlfsd +@comment node-name, next, previous, up +@subsection Hlfsd Options +@cindex Hlfsd Options +@cindex Hlfsd; Options + +@table @t + +@item -a @var{alt_dir} +Alternate directory. The name of the directory to which the symbolic +link returned by @i{Hlfsd} will point, if it cannot access the home +directory of the user. This defaults to @file{/var/hlfs}. This +directory will be created if it doesn't exist. It is expected that +either users will read these files, or the system administrators will +run a script to resend this ``lost mail'' to its owner. + +@item -c @var{cache-interval} +Caching interval. @i{Hlfsd} will cache the validity of home directories +for this interval, in seconds. Entries which have been verified within +the last @var{cache-interval} seconds will not be verified again, since +the operation could be expensive, and the entries are most likely still +valid. After the interval has expired, @i{Hlfsd} will re-verify the +validity of the user's home directory, and reset the cache time-counter. +The default value for @var{cache-interval} is 300 seconds (5 minutes). + +@item -f +Force fast startup. This option tells @i{Hlfsd} to skip startup-time +consistency checks such as existence of mount directory, alternate spool +directory, symlink to be hidden under the mount directory, their +permissions and validity. + +@item -g @var{group} +Set the special group HLFS_GID to @var{group}. Programs such as +@file{/usr/ucb/from} or @file{/usr/sbin/in.comsat}, which access the +mailboxes of other users, must be setgid @samp{HLFS_GID} to work properly. The +default group is @samp{hlfs}. If no group is provided, and there is no +group @samp{hlfs}, this feature is disabled. + +@item -h +Help. Print a brief help message, and exit. + +@item -i @var{reload-interval} +Map-reloading interval. Each @var{reload-interval} seconds, @i{Hlfsd} +will reload the password map. @i{Hlfsd} needs the password map for the +UIDs and home directory pathnames. @i{Hlfsd} schedules a @samp{SIGALRM} to +reload the password maps. A @samp{SIGHUP} sent to @i{Hlfsd} will force it to +reload the maps immediately. The default value for +@var{reload-interval} is 900 seconds (15 minutes.) + +@item -l @var{logfile} +Specify a log file to which @i{Hlfsd} will record events. If +@var{logfile} is the string @samp{syslog} then the log messages will be +sent to the system log daemon by @b{syslog}(3), using the @samp{LOG_DAEMON} +facility. This is also the default. + +@item -n +No verify. @i{Hlfsd} will not verify the validity of the symbolic link +it will be returning, or that the user's home directory contains +sufficient disk-space for spooling. This can speed up @i{Hlfsd} at the +cost of possibly returning symbolic links to home directories which are +not currently accessible or are full. By default, @i{Hlfsd} validates +the symbolic-link in the background. The @code{-n} option overrides the +meaning of the @code{-c} option, since no caching is necessary. + +@item -o @var{mount-options} +Mount options which @i{Hlfsd} will use to mount itself on top of +@var{dirname}. By default, @var{mount-options} is set to @samp{ro}. If +the system supports symbolic-link caching, default options are set +to @samp{ro,nocache}. + +@item -p +Print PID. Outputs the process-id of @i{Hlfsd} to standard output where +it can be saved into a file. + +@item -v +Version. Displays version information to standard error. + +@item -x @var{log-options} +Specify run-time logging options. The options are a comma separated +list chosen from: @samp{fatal}, @samp{error}, @samp{user}, @samp{warn}, @samp{info}, @samp{map}, @samp{stats}, @samp{all}. + +@item -C +Force @i{Hlfsd} to run on systems that cannot turn off the NFS +attribute-cache. Use of this option on those systems is discouraged, as +it may result in loss or misdelivery of mail. The option is ignored on +systems that can turn off the attribute-cache. + +@item -D @var{log-options} +Select from a variety of debugging options. Prefixing an option with +the string @samp{no} reverses the effect of that option. Options are +cumulative. The most useful option is @samp{all}. Since this option is +only used for debugging other options are not documented here. A fuller +description is available in the program source. A @samp{SIGUSR1} sent +to @i{Hlfsd} will cause it to dump its internal password map to the file +@file{/usr/tmp/hlfsd.dump.XXXXXX}, where @samp{XXXXXX} will be replaced +by a random string generated by @b{mktemp}(3) or (the more secure) +@b{mkstemp}(3). + +@item -P @var{password-file} +Read the user-name, user-id, and home directory information from the +file @var{password-file}. Normally, @i{Hlfsd} will use @b{getpwent}(3) +to read the password database. This option allows you to override the +default database, and is useful if you want to map users' mail files to +a directory other than their home directory. Only the username, uid, +and home-directory fields of the file @var{password-file} are read and +checked. All other fields are ignored. The file @var{password-file} +must otherwise be compliant with Unix Version 7 colon-delimited format +@b{passwd}(4). + +@end table + +@c ---------------------------------------------------------------- +@node Hlfsd Files, , Hlfsd Options, Using Hlfsd +@comment node-name, next, previous, up +@subsection Hlfsd Files +@cindex Hlfsd Files +@cindex Hlfsd; Files + +The following files are used by @i{Hlfsd}: + +@table @file + +@item /hlfs +directory under which @i{Hlfsd} mounts itself and manages the symbolic +link @file{home}. + +@item .hlfsdir +default sub-directory in the user's home directory, to which the +@file{home} symbolic link returned by @i{Hlfsd} points. + +@item /var/hlfs +directory to which @file{home} symbolic link returned by @i{Hlfsd} +points if it is unable to verify the that user's home directory is +accessible. + +@end table + +For discussion on other files used by @i{Hlfsd}, see @ref{lostaltmail} and +@ref{lostaltmail.conf-sample}. + +@c ################################################################ +@node Assorted Tools, Examples, Hlfsd, Top +@comment node-name, next, previous, up +@chapter Assorted Tools +@cindex Assorted Tools + +The following are additional utilities and scripts included with +am-utils, and get installed. + +@menu +* am-eject:: +* amd.conf-sample:: +* amd2ldif:: +* amd2sun:: +* ctl-amd:: +* ctl-hlfsd:: +* expn:: +* fix-amd-map:: +* fixmount:: +* fixrmtab:: +* lostaltmail:: +* lostaltmail.conf-sample:: +* mk-amd-map:: +* pawd:: +* wait4amd:: +* wait4amd2die:: +* wire-test:: +@end menu + +@c ---------------------------------------------------------------- +@node am-eject, amd.conf-sample, Assorted Tools, Assorted Tools +@comment node-name, next, previous, up +@section am-eject +@pindex am-eject + +A shell script unmounts a floppy or CD-ROM that is automounted, and +then attempts to eject the removable device. + +@c ---------------------------------------------------------------- +@node amd.conf-sample, amd2ldif, am-eject, Assorted Tools +@comment node-name, next, previous, up +@section amd.conf-sample +@pindex amd.conf-sample + +A sample @i{Amd} configuration file. @xref{Amd Configuration File}. + +@c ---------------------------------------------------------------- +@node amd2ldif, amd2sun, amd.conf-sample, Assorted Tools +@comment node-name, next, previous, up +@section amd2ldif +@pindex amd2ldif + +A script to convert @i{Amd} maps to LDAP input files. Use it as follows: + +@example +amd2ldif @i{mapname} @i{base} < @i{amd.mapfile} > @i{mapfile.ldif} +@end example + +@c ---------------------------------------------------------------- +@node amd2sun, ctl-amd, amd2ldif, Assorted Tools +@comment node-name, next, previous, up +@section amd2sun +@pindex amd2sun + +A script to convert @i{Amd} maps to Sun Automounter maps. Use it as +follows + +@example +amd2sun < @i{amd.mapfile} > @i{auto_mapfile} +@end example + +@c ---------------------------------------------------------------- +@node ctl-amd, ctl-hlfsd, amd2sun, Assorted Tools +@comment node-name, next, previous, up +@section ctl-amd +@pindex ctl-amd + +A script to start, stop, or restart @i{Amd}. Use it as follows: + +@table @t +@item ctl-amd start +Start a new @i{Amd} process. +@item ctl-amd stop +Stop the running @i{Amd}. +@item ctl-amd restart +Stop the running @i{Amd} (if any), safely wait for it to terminate, and +then start a new process --- only if the previous one died cleanly. +@end table + +@xref{Run-time Administration} for more details. + +@c ---------------------------------------------------------------- +@node ctl-hlfsd, expn, ctl-amd, Assorted Tools +@comment node-name, next, previous, up +@section ctl-hlfsd +@pindex ctl-hlfsd + +A script for controlling @i{Hlfsd}, much the same way @file{ctl-amd} +controls @i{Amd}. Use it as follows: + +@table @t +@item ctl-hlfsd start +Start a new @i{Hlfsd} process. +@item ctl-hlfsd stop +Stop the running @i{Hlfsd}. +@item ctl-hlfsd restart +Stop the running @i{Hlfsd} (if any), wait for 10 seconds for it to +terminate, and then start a new process --- only if the previous one +died cleanly. +@end table + +@xref{Hlfsd} for more details. + +@c ---------------------------------------------------------------- +@node expn, fix-amd-map, ctl-hlfsd, Assorted Tools +@comment node-name, next, previous, up +@section expn +@pindex expn + +A script to expand email addresses into their full name. It is +generally useful when using with the @file{lostaltmail} script, but is a +useful tools otherwise. + +@example +$ expn -v ezk@@cs.columbia.edu +ezk@@cs.columbia.edu -> + ezk@@shekel.mcl.cs.columbia.edu +ezk@@shekel.mcl.cs.columbia.edu -> + Erez Zadok <"| /usr/local/mh/lib/slocal -user ezk || exit 75> + Erez Zadok <\ezk> + Erez Zadok </u/zing/ezk/.mailspool/backup> +@end example + +@c ---------------------------------------------------------------- +@node fix-amd-map, fixmount, expn, Assorted Tools +@comment node-name, next, previous, up +@section fix-amd-map +@pindex fix-amd-map + +Am-utils changed some of the syntax and default values of some +variables. For example, the default value for @samp{$@{os@}} for +Solaris 2.x (aka SunOS 5.x) systems used to be @samp{sos5}, it is now +more automatically generated from @file{config.guess} and its value is +@samp{sunos5}. + +This script converts older @i{Amd} maps to new ones. Use it as follows: + +@example +fix-amd-map < @i{old.map} > @i{new.map} +@end example + +@c ---------------------------------------------------------------- +@node fixmount, fixrmtab, fix-amd-map, Assorted Tools +@comment node-name, next, previous, up +@section fixmount +@pindex fixmount + +@samp{fixmount} is a variant of @b{showmount}(8) that can delete bogus +mount entries in remote @b{mountd}(8) daemons. This is useful to +cleanup otherwise ever-accumulating ``junk''. Use it for example: + +@example +fixmount -r @i{host} +@end example + +See the online manual page for @samp{fixmount} for more details of its +usage. + +@c ---------------------------------------------------------------- +@node fixrmtab, lostaltmail, fixmount, Assorted Tools +@comment node-name, next, previous, up +@section fixrmtab +@pindex fixrmtab + +A script to invalidate @file{/etc/rmtab} entries for hosts named. Also +restart mountd for changes to take effect. Use it for example: + +@example +fixrmtab @i{host1} @i{host2} @i{...} +@end example + +@c ---------------------------------------------------------------- +@node lostaltmail, lostaltmail.conf-sample, fixrmtab, Assorted Tools +@comment node-name, next, previous, up +@section lostaltmail +@pindex lostaltmail + +A script used with @i{Hlfsd} to resend any ``lost'' mail. @i{Hlfsd} +redirects mail which cannot be written into the user's home directory to +an alternate directory. This is useful to continue delivering mail, +even if the user's file system was unavailable, full, or over quota. +But, the mail which gets delivered to the alternate directory needs to +be resent to its respective users. This is what the @samp{lostaltmail} +script does. + +Use it as follows: + +@example +lostaltmail +@end example + +This script needs a configuration file @samp{lostaltmail.conf} set up +with the right parameters to properly work. @xref{Hlfsd} for more +details. + +@c ---------------------------------------------------------------- +@node lostaltmail.conf-sample, mk-amd-map, lostaltmail, Assorted Tools +@comment node-name, next, previous, up +@section lostaltmail.conf-sample +@pindex lostaltmail.conf-sample +@cindex lostaltmail; configuration file + +This is a text file with configuration parameters needed for the +@samp{lostaltmail} script. The script includes comments explaining each +of the configuration variables. See it for more information. Also +@pxref{Hlfsd} for general information. + +@c ---------------------------------------------------------------- +@node mk-amd-map, pawd, lostaltmail.conf-sample, Assorted Tools +@comment node-name, next, previous, up +@section mk-amd-map +@pindex mk-amd-map + +This program converts a normal @i{Amd} map file into an ndbm database +with the same prefix as the named file. Use it as follows: + +@example +mk-amd-map @i{mapname} +@end example + +@c ---------------------------------------------------------------- +@node pawd, wait4amd, mk-amd-map, Assorted Tools +@comment node-name, next, previous, up +@section pawd +@pindex pawd + +@i{Pawd} is used to print the current working directory, adjusted to +reflect proper paths that can be reused to go through the automounter +for the shortest possible path. In particular, the path printed back +does not include any of @i{Amd}'s local mount points. Using them is +unsafe, because @i{Amd} may unmount managed file systems from the mount +points, and thus including them in paths may not always find the files +within. + +Without any arguments, @i{Pawd} will print the automounter adjusted +current working directory. With any number of arguments, it will print +the adjusted path of each one of the arguments. + +@c ---------------------------------------------------------------- +@node wait4amd, wait4amd2die, pawd, Assorted Tools +@comment node-name, next, previous, up +@section wait4amd +@pindex wait4amd + +A script to wait for @i{Amd} to start on a particular host before +performing an arbitrary command. The command is executed repeatedly, +with 1 second intervals in between. You may interrupt the script using +@samp{^C} (or whatever keyboard sequence your terminal's @samp{intr} function +is bound to). + +Examples: + +@table @t +@item wait4amd saturn amq -p -h saturn +When @i{Amd} is up on host @samp{saturn}, get the process ID of that +running @i{Amd}. +@item wait4amd pluto rlogin pluto +Remote login to host @samp{pluto} when @i{Amd} is up on that host. It +is generally necessary to wait for @i{Amd} to properly start and +initialize on a remote host before logging in to it, because otherwise +user home directories may not be accessible across the network. +@item wait4amd pluto +A short-hand version of the previous command, since the most useful +reason for this script is to login to a remote host. I use it very +often when testing out new versions of @i{Amd}, and need to reboot hung +hosts. +@end table + +@c ---------------------------------------------------------------- +@node wait4amd2die, wire-test, wait4amd, Assorted Tools +@comment node-name, next, previous, up +@section wait4amd2die +@pindex wait4amd2die + +This script is used internally by @samp{ctl-amd} when used to restart +@i{Amd}. It waits for @i{Amd} to terminate. If it detected that +@i{Amd} terminated cleanly, this script will return an exist status of +zero. Otherwise, it will return a non-zero exit status. + +The script tests for @i{Amd}'s existence once every 5 seconds, six +times, for a total of 30 seconds. It will return a zero exist status as +soon as it detects that @i{Amd} dies. + +@c ---------------------------------------------------------------- +@node wire-test, , wait4amd2die, Assorted Tools +@comment node-name, next, previous, up +@section wire-test +@pindex wire-test + +A simple program to test if some of the most basic networking functions +in am-util's library @file{libamu} work. It also tests the combination +of NFS protocol and version number that are supported from the current +host, to a remote one. + +For example, in this test a machine which only supports NFS Version 2 is +contacting a remote host that can support the same version, but using +both UDP and TCP. If no host name is specified, @samp{wire-test} will +try @file{localhost}. + +@example +$ wire-test moisil +Network name is "mcl-lab-net.cs.columbia.edu" +Network number is "128.59.13" +Network name is "old-net.cs.columbia.edu" +Network number is "128.59.16" +My IP address is 0x7f000001. +NFS Version and protocol tests to host "moisil"... + testing vers=2, proto="udp" -> found version 2. + testing vers=3, proto="udp" -> failed! + testing vers=2, proto="tcp" -> found version 2. + testing vers=3, proto="tcp" -> failed! +@end example + +@c ################################################################ +@node Examples, Internals, Assorted Tools, Top +@comment node-name, next, previous, up +@chapter Examples + +@menu +* User Filesystems:: +* Home Directories:: +* Architecture Sharing:: +* Wildcard Names:: +* rwho servers:: +* /vol:: +* /defaults with selectors:: +* /tftpboot in a chroot-ed environment:: + +@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 minimizing 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 @code{-r} option then instead of attempting an NFS mount, @i{Amd} will +simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If +@code{-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, /defaults with selectors, 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 /defaults with selectors, /tftpboot in a chroot-ed environment, /vol, Examples +@comment node-name, next, previous, up +@section @samp{/defaults} with selectors +@cindex /defaults with selectors +@cindex selectors on default + +It is sometimes useful to have different defaults for a given map. To +achieve this, the @samp{/defaults} entry must be able to process normal +selectors. This feature is turned on by setting +@samp{selectors_on_default = yes} in the @file{amd.conf} file. +@xref{selectors_on_default Parameter}. + +In this example, I set different default NFS mount options for hosts +which are running over a slower network link. By setting a smaller size +for the NFS read and write buffer sizes, you can greatly improve remote +file service performance. + +@example +/defaults \ + wire==slip-net;opts:=rw,intr,rsize=1024,wsize=1024,timeo=20,retrans=10 \ + wire!=slip-net;opts:=rw,intr +@end example + +@node /tftpboot in a chroot-ed environment, , /defaults with selectors, Examples +@comment node-name, next, previous, up +@section @samp{/tftpboot} in a chroot-ed environment +@cindex /tftpboot in a chroot-ed environment +@cindex chroot: /tftpboot example + +In this complex example, we attempt to run an @i{Amd} process +@emph{inside} a chroot-ed environment. @samp{tftpd} (Trivial FTP) is +used to trivially retrieve files used to boot X-Terminals, Network +Printers, Network routers, diskless workstations, and other such +devices. For security reasons, @samp{tftpd} (and also @samp{ftpd}) +processes are run using the @b{chroot}(2) system call. This provides an +environment for these processes, where access to any files outside the +directory where the chroot-ed process runs is denied. + +For example, if you start @samp{tftpd} on your system with + +@example +chroot /tftpboot /usr/sbin/tftpd +@end example + +@noindent +then the @samp{tftpd} process will not be able to access any files +outside @file{/tftpboot}. This ensures that no one can retrieve files +such as @file{/etc/passwd} and run password crackers on it. + +Since the TFTP service works by broadcast, it is necessary to have at +least one TFTP server running on each subnet. If you have lots of files +that you need to make available for @samp{tftp}, and many subnets, it +could take significant amounts of disk space on each host serving them. + +A solution we implemented at Columbia University was to have every host +run @samp{tftpd}, but have those servers retrieve the boot files from +two replicated servers. Those replicated servers have special +partitions dedicated to the many network boot files. + +We start @i{Amd} as follows: + +@example +amd /tftpboot/.amd amd.tftpboot +@end example + +That is, @i{Amd} is serving the directory @file{/tftpboot/.amd}. The +@samp{tftp} server runs inside @file{/tftpboot} and is chroot-ed in that +directory too. The @file{amd.tftpboot} map looks like: + +@example +# +# Amd /tftpboot directory -> host map +# + +/defaults opts:=nosuid,ro,intr,soft;fs:=/tftpboot/import;type:=nfs + +tp host==lol;rfs:=/n/lol/import/tftpboot;type:=lofs \ + host==ober;rfs:=/n/ober/misc/win/tftpboot;type:=lofs \ + rhost:=ober;rfs:=/n/ober/misc/win/tftpboot \ + rhost:=lol;rfs:=/n/lol/import/tftpboot +@end example + +To help understand this example, I list a few of the file entries that +are created inside @file{/tftpboot}: + +@example +$ ls -la /tftpboot +dr-xr-xr-x 2 root 512 Aug 30 23:11 .amd +drwxrwsr-x 12 root 512 Aug 30 08:00 import +lrwxrwxrwx 1 root 33 Feb 27 1997 adminpr.cfg -> ./.amd/tp/hplj/adminpr.cfg +lrwxrwxrwx 1 root 22 Dec 5 1996 tekxp -> ./.amd/tp/xterms/tekxp +lrwxrwxrwx 1 root 1 Dec 5 1996 tftpboot -> . +@end example + +Here is an explanation of each of the entries listed above: + +@table @code + +@item .amd +This is the @i{Amd} mount point. Note that you do not need to run a +separate @i{Amd} process for the TFTP service. The @b{chroot}(2) system +call only protects against file access, but the same process can still +serve files and directories inside and outside the chroot-ed +environment, because @i{Amd} itself was not run in chroot-ed mode. + +@item import +This is the mount point where @i{Amd} will mount the directories +containing the boot files. The map is designed so that remote +directories will be NFS mounted (even if they are already mounted +elsewhere), and local directories are loopback mounted (since they are +not accessible outside the chroot-ed @file{/tftpboot} directory). + +@item adminpr.cfg +@itemx tekxp +Two manually created symbolic links to directories @emph{inside} the +@i{Amd}-managed directory. The crossing of the component @file{tp} will +cause @i{Amd} to automount one of the remote replicas. Once crossed, +access to files inside proceeds as usual. The @samp{adminpr.cfg} is a +configuration file for an HP Laser-Jet 4si printer, and the @samp{tekxp} +is a directory for Tektronix X-Terminal boot files. + +@item tftpboot +This innocent looking symlink is important. Usually, when devices boot +via the TFTP service, they perform the @samp{get file} command to +retrieve @var{file}. However, some devices assume that @samp{tftpd} +does not run in a chroot-ed environment, but rather ``unprotected'', and +thus use a full pathname for files to retrieve, as in @samp{get +/tftpboot/file}. This symlink effectively strips out the leading +@file{/tftpboot/}. + +@end table + +@c ################################################################ +@node Internals, Acknowledgments & Trademarks, Examples, Top +@comment node-name, next, previous, up +@chapter Internals + +Note that there are more error and logging messages possible than are +listed here. Most of them are self-explanatory. Refer to the program +sources for more details on the rest. + +@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{$@{@i{var}@}}, indicate that the value of the appropriate variable is +output. + +Log messages are either sent directly to a file, +or logged via the @b{syslog}(3) mechanism. @xref{log_file Parameter} +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 @t + +@item 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 error ``should +never happen''. + +@item 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 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 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 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 @code{-v} option. + +@item No work to do - quitting +No automount points were given on the command line and so there is no +work to do. + +@item Out of memory +While attempting to malloc some memory, the memory space available to +@i{Amd} was exhausted. This is an unrecoverable error. + +@item 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 cannot create rpc/udp service +Either the NFS or AMQ endpoint could not be created. + +@item gethostname: @i{description} +The @b{gethostname}(2) system call failed during startup. + +@item 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 ifs_match called! +An internal error occurred while restarting a pre-mounted filesystem. +This error ``should never happen''. + +@item mount_afs: @i{description} +An error occurred while @i{Amd} was mounting itself. + +@item run_rpc failed +Somehow the main NFS server loop failed. This error ``should never +happen''. + +@item unable to free rpc arguments in amqprog_1 +The incoming arguments to the AMQ server could not be free'ed. + +@item unable to free rpc arguments in nfs_program_1 +The incoming arguments to the NFS server could not be free'ed. + +@item 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 unable to register (NFS_PROGRAM, NFS_VERSION, 0) +The NFS server could not be registered with the internal RPC dispatcher. + +@end table + +XXX: This section needs to be updated + +@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 @t + +@item "@t{$@{@i{path}@}}" forcibly timed out +An automount point has been timed out by the @i{Amq} command. + +@item "@t{$@{@i{path}@}}" has timed out +No access to the automount point has been made within the timeout +period. + +@item Filehandle denied for "$@{@i{rhost}@}:$@{@i{rfs}@}" +The mount daemon refused to return a file handle for the requested filesystem. + +@item Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}": @i{description} +The mount daemon gave some other error for the requested filesystem. + +@item Finishing with status @i{exit-status} +@i{Amd} is about to exit with the given exit status. + +@item Re-synchronizing cache for map @t{$@{@i{map}@}} +The named map has been modified and the internal cache is being re-synchronized. + +@item 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 file server @t{$@{@i{rhost}@}} type nfs is down +An NFS file server that was previously up is now down. + +@item file server @t{$@{@i{rhost}@}} type nfs is up +An NFS file server that was previously down is now up. + +@item file server @t{$@{@i{rhost}@}} type nfs starts down +A new NFS file server has been referenced and is known to be down. + +@item file server @t{$@{@i{rhost}@}} type nfs starts up +A new NFS file server has been referenced and is known to be up. + +@item 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 @i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} +A new file system has been mounted. + +@item @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 @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} +A file system has been unmounted. + +@item @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. + +@item restarting @i{mount-info} on @t{$@{@i{fs}@}} +A pre-mounted file system has been noted. + +@end table + +XXX: This section needs to be updated + +@c ################################################################ +@node Acknowledgments & Trademarks, Index, Internals, Top +@comment node-name, next, previous, up +@unnumbered Acknowledgments & Trademarks + +Many thanks to the @email{amd-dev@@majordomo.cs.columbia.edu,Amd +Developers} mailing list through the months developing am-utils. These +members have contributed to the discussions, ideas, code and +documentation, and subjected their systems to alpha quality code. +Special thanks go to those +@uref{http://www.cs.columbia.edu/~ezk/am-utils/AUTHORS.txt,authors} who +have submitted patches. + +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. + +Thanks to the @email{amd-workers@@majordomo.glue.umd.edu,Amd Workers} +mailing list members for many suggestions and bug reports to @i{Amd}. + +@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 in the USA and other countries, +exclusively licensed through X/Open Company, Ltd. +@item +All other registered trademarks are owned by their respective owners. +@end itemize + +@c ################################################################ +@node Index, , Acknowledgments & Trademarks, Top +@comment node-name, next, previous, up +@unnumbered Index + +@printindex cp + +@contents +@bye + +@c ==================================================================== +@c ISPELL LOCAL WORDS: +@c LocalWords: setfilename amdref overfullrule settitle titlepage titlefont nz +@c LocalWords: authorfont vskip ifinfo iftex cindex unnumberedsec dfn xref vol +@c LocalWords: locationN pxref jpo nott concentrix Sjoerd sjoerd cwi Eitan vuw +@c LocalWords: Mizrotsky eitan shumuji dgux fpx scp hcx metcalf masala hlh OTS +@c LocalWords: Presnell srp cgl Trost trost ogi pyrOSx OSx tubsibr riscix iX +@c LocalWords: Piete pb Lindblad cjl ai umax utek xinu Mitchum D'Souza dsouza +@c LocalWords: mrc apu alliant aviion AViiON fps macII multimax tahoe vax emph +@c LocalWords: mapdefault valA valB valC YPTSDIR ETCDIR substr MAKEDBM YPDBDIR +@c LocalWords: NOPUSH njw dylan dk dylan njw anydir domN achilles mjh pref sel +@c LocalWords: gdef loc loc loc ldots autodir remopts rwho rwho styx styx yoyo +@c LocalWords: noindent gould rvdmount rvdunmount fserver mtmp unioned logfile +@c LocalWords: dmn esac phjk toytown toytown toytown toytown phjk RdDir RdLnk +@c LocalWords: volname attrs netif dougal inaddr hwaddr ec mountmaps passno xy +@c LocalWords: freq dumpset hfs brian florence localinfo fstabs automaps defn +@c LocalWords: localname fsck'd opr gummo sjv ganymede sjv fserv fserv fserv +@c LocalWords: vaxA vaxB wp thpfs nbsd asis ifs amqprog free'ed printindex gov +@c LocalWords: LocalWords syncodeindex Distrib bsdnet lanl AutoMounter acis ic +@c LocalWords: ac uk aix bsd Mullender nl il DG lcs hpux irix ucsf NeXT cse cl +@c LocalWords: mt FX hp ibm mips utils def def Domainname eg hostd getwd tmp +@c LocalWords: subsubsection rw grpid intr noconn nocto nodevs nosuid retrans +@c LocalWords: rsize tcp timeo nounmount utimeout DDEBUG nodaemon fd hostnames +@c LocalWords: pid Amd's pendry vangogh nfsx backoff stats nomap nostats CRIT +@c LocalWords: noinfo clustername RVD dsk dsk amq hostports osver statfs str +@c LocalWords: ou counter's amdmaps proj src tftpboot sh mv cd sbin ypcat inet +@c LocalWords: Getattr getattr localhost fhandles netmask fstype noquota addr +@c LocalWords: exportfs Dumpsets dumpsets pindex ldif fixmount fixrmtab euid +@c LocalWords: lostaltmail realloc netnumber itemx primnetnum primnetname ARG +@c LocalWords: subsnetname subsnetnum netgrp netgroup multitable Shlib dec osf +@c LocalWords: hppa pc bsdi freebsd netbsd openbsd ncr sysv rs acdirmax fsid +@c LocalWords: acdirmin acregmax acregmin actimeo dumbtimr nfsv noac noauto sd +@c LocalWords: nocache nodev noint nosub pgthresh posix rdonly suid symttl mfs +@c LocalWords: AMFS umapfs myftpdir unionfs es mapname mapfile mapfile slocal +@c LocalWords: mailspool saturn saturn notknown lol ober dr xr xr drwxrwsr cfg +@c LocalWords: lrwxrwxrwx adminpr hplj adminpr cfg tekxp xterms tekxp Dupuy tp +@c LocalWords: linkname hlfsddump dirname rmtab pluto rlogin direntry pg vr dn +@c LocalWords: maxmem hlfsdir xmailbox showmount cn amdmap amdmapName resvport +@c LocalWords: objectClass amdmapKey amdmapValue ln powerpc amdmapTimestamp ez +@c LocalWords: moisil FSinfo Libtool Unmounting sublink fileservers NullProc +@c LocalWords: gethostname mount's unmounts linkx remounts unmounting UAs SA's +@c LocalWords: mountpoint mountpoints unescaped UIDs util's overlayed uref EFS +@c LocalWords: serv maxgroups nfsl cachedir copt cfsadmin efs addopts fg +@c LocalWords: nointr |
