am-utils.texi revision 51591
1\input texinfo @c -*-texinfo-*- 2@c 3@c Copyright (c) 1997-1999 Erez Zadok 4@c Copyright (c) 1989 Jan-Simon Pendry 5@c Copyright (c) 1989 Imperial College of Science, Technology & Medicine 6@c Copyright (c) 1989 The Regents of the University of California. 7@c All rights reserved. 8@c 9@c This code is derived from software contributed to Berkeley by 10@c Jan-Simon Pendry at Imperial College, London. 11@c 12@c Redistribution and use in source and binary forms, with or without 13@c modification, are permitted provided that the following conditions 14@c are met: 15@c 1. Redistributions of source code must retain the above copyright 16@c notice, this list of conditions and the following disclaimer. 17@c 2. Redistributions in binary form must reproduce the above copyright 18@c notice, this list of conditions and the following disclaimer in the 19@c documentation and/or other materials provided with the distribution. 20@c 3. All advertising materials mentioning features or use of this software 21@c must display the following acknowledgment: 22@c This product includes software developed by the University of 23@c California, Berkeley and its contributors. 24@c 4. Neither the name of the University nor the names of its contributors 25@c may be used to endorse or promote products derived from this software 26@c without specific prior written permission. 27@c 28@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 29@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 30@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 31@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 32@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 33@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 34@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 35@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 36@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 37@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 38@c 39@c %W% (Berkeley) %G% 40@c 41@c $Id: am-utils.texi,v 1.10 1999/09/08 23:36:49 ezk Exp $ 42@c 43@setfilename am-utils.info 44 45@include version.texi 46 47@c info directory entry 48@direntry 49* Am-utils: (am-utils). The Amd automounter suite of utilities 50@end direntry 51 52@settitle 53@setchapternewpage odd 54 55@titlepage 56@title Am-utils (4.4BSD Automounter Utilities) 57@subtitle For version @value{VERSION}, @value{UPDATED} 58 59@author Erez Zadok 60(Originally by Jan-Simon Pendry and Nick Williams) 61 62@page 63Copyright @copyright{} 1997-1999 Erez Zadok 64@* 65Copyright @copyright{} 1989 Jan-Simon Pendry 66@* 67Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 68@* 69Copyright @copyright{} 1989 The Regents of the University of California. 70@sp 71All Rights Reserved. 72@vskip 1ex 73Permission to copy this document, or any portion of it, as 74necessary for use of this software is granted provided this 75copyright notice and statement of permission are included. 76@end titlepage 77@page 78 79@c Define a new index for options. 80@syncodeindex pg cp 81@syncodeindex vr cp 82 83@ifinfo 84 85@c ################################################################ 86@node Top, License, , (DIR) 87Am-utils - The 4.4BSD Automounter Tool Suite 88********************************************* 89 90Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd 91automounter, the Amq query and control program, the Hlfsd daemon, and 92other tools. This Info file describes how to use and understand the 93tools within Am-utils. 94@end ifinfo 95 96@menu 97* License:: Explains the terms and conditions for using 98 and distributing Am-utils. 99* Distrib:: How to get the latest Am-utils distribution. 100* Intro:: An introduction to Automounting concepts. 101* History:: History of am-utils' development. 102* Overview:: An overview of Amd. 103* Supported Platforms:: Machines and Systems supported by Amd. 104* Mount Maps:: Details of mount maps 105* Amd Command Line Options:: All the Amd command line options explained. 106* Filesystem Types:: The different mount types supported by Amd. 107* Amd Configuration File:: The amd.conf file syntax and meaning. 108* Run-time Administration:: How to start, stop and control Amd. 109* FSinfo:: The FSinfo filesystem management tool. 110* Hlfsd:: The Home-Link Filesystem server. 111* Assorted Tools:: Other tools which come with am-utils. 112* Examples:: Some examples showing how Amd might be used. 113* Internals:: Implementation details. 114* Acknowledgments & Trademarks:: Legal Notes 115 116Indexes 117* Index:: An item for each concept. 118@end menu 119 120@iftex 121@unnumbered Preface 122 123This manual documents the use of the 4.4BSD automounter tool suite, 124which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is 125primarily a reference manual. While no tutorial exists, there are 126examples available. @xref{Examples}. 127 128This manual comes in two forms: the published form and the Info form. 129The Info form is for on-line perusal with the INFO program which is 130distributed along with GNU texinfo package (a version of which is 131available for GNU Emacs).@footnote{GNU packages can be found in 132@url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially 133the same text and are generated from a common source file, which is 134distributed with the @i{Am-utils} source. 135@end iftex 136 137@c ################################################################ 138@node License, Distrib, Top, Top 139@unnumbered License 140@cindex License Information 141 142@i{Am-utils} is not in the public domain; it is copyrighted and there are 143restrictions on its distribution. 144 145Redistribution and use in source and binary forms, with or without 146modification, are permitted provided that the following conditions are 147met: 148 149@enumerate 150 151@item 152Redistributions of source code must retain the above copyright notice, 153this list of conditions and the following disclaimer. 154 155@item 156Redistributions in binary form must reproduce the above copyright 157notice, this list of conditions and the following disclaimer in the 158documentation and/or other materials provided with the distribution. 159 160@item 161All advertising materials mentioning features or use of this software 162must display the following acknowledgment: 163 164@cartouche 165``This product includes software developed by the University of 166California, Berkeley and its contributors, as well as the Trustees of 167Columbia University.'' 168@end cartouche 169 170@item 171Neither the name of the University nor the names of its contributors may 172be used to endorse or promote products derived from this software 173without specific prior written permission. 174 175@end enumerate 176 177THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 178ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 179IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 180PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 181BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 182CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 183SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 184INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 185CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 186ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 187THE POSSIBILITY OF SUCH DAMAGE. 188 189@c ################################################################ 190@node Distrib, Intro, License, Top 191@unnumbered Source Distribution 192@cindex Source code distribution 193@cindex Obtaining the source code 194 195The @i{Am-utils} home page is located in 196@example 197@url{http://www.cs.columbia.edu/~ezk/am-utils/} 198@end example 199 200You can get the latest distribution version of @i{Am-utils} from 201@example 202@url{ftp://shekel.mcl.cs.columbia.edu/pub/am-utils/am-utils.tar.gz} 203@end example 204 205Alpha and beta distributions are available in 206@example 207@url{ftp://shekel.mcl.cs.columbia.edu/pub/am-utils/}. 208@end example 209 210Revision 5.2 was part of the 4.3BSD Reno distribution. 211 212Revision 5.3bsdnet, a late alpha version of 5.3, was part 213of the BSD network version 2 distribution 214 215Revision 6.0 was made independently by @email{ezk@@cs.columbia.edu,Erez 216Zadok} at the @uref{http://www.cs.columbia.edu/,Computer Science 217Department} of @uref{http://www.columbia.edu/,Columbia University}, as 218part of his @uref{http://www.cs.columbia.edu/~ezk/research/tp/thesis_proposal.html,PhD thesis work}. @xref{History}, for more details. 219 220@unnumberedsec Bug Reports 221@cindex Bug reports 222 223Before reporting a bug, see if it is a known one in the 224@uref{http://www.cs.columbia.edu/~ezk/am-utils/BUGS.txt,bugs} file. 225Send all bug reports to @email{amd-dev@@majordomo.cs.columbia.edu} 226quoting the details of the release and your configuration. These can be 227obtained by running the command @samp{amd -v}. It would greatly help if 228you could provide a reproducible procedure for detecting the bug you are 229reporting. 230 231Providing working patches is highly encouraged. Every patch 232incorporated, however small, will get its author an honorable mention in 233the @uref{http://www.cs.columbia.edu/~ezk/am-utils/AUTHORS.txt,authors 234file}. 235 236@unnumberedsec Mailing List 237@cindex Mailing list 238 239There are two mailing lists for people interested in keeping up-to-date 240with developments. 241 242@c ############### 243 244@enumerate 245 246@item 247The older list, @samp{amd-workers} is for general "how to" questions and 248announcements. To subscribe, send a note to 249@email{amd-workers-request@@majordomo.glue.umd.edu}.@footnote{Note that 250the older address, @email{amd-workers-request@@acl.lanl.gov}, is 251defunct.} To post a message to this list, send mail to 252@email{amd-workers@@majordomo.glue.umd.edu}. 253 254@item 255The developers only list, @samp{amd-dev} is for 256 257@itemize @minus 258@item 259announcements of alpha and beta releases of am-utils 260@item 261reporting of bugs and patches 262@item 263discussions of new features for am-utils 264@item 265implementation and porting issues 266@end itemize 267 268To subscribe, send a note to @email{majordomo@@majordomo.cs.columbia.edu} 269with the single body text line @samp{subscribe amd-dev}. To post a 270message to this list, send mail to 271@email{amd-dev@@majordomo.cs.columbia.edu}. To avoid as much spam as 272possible, only subscribers to this list may post to it. 273 274Subscribers of @samp{amd-dev} are most suitable if they have the time 275and resources to test new and buggy versions of amd, on as many 276different platforms as possible. They should also be prepared to learn 277and use the GNU Autoconf, Automake, and Libtool packages, and of course, 278be very familiar with the complex code in the am-utils package. In 279other words, subscribers on this list should be able to contribute 280meaningfully to the development of amd. 281 282@end enumerate 283 284@c ################################################################ 285@node Intro, History, Distrib, Top 286@unnumbered Introduction 287@cindex Introduction 288 289An @dfn{automounter} maintains a cache of mounted filesystems. 290Filesystems are mounted on demand when they are first referenced, 291and unmounted after a period of inactivity. 292 293@i{Amd} may be used as a replacement for Sun's automounter. The choice 294of which filesystem to mount can be controlled dynamically with 295@dfn{selectors}. Selectors allow decisions of the form ``hostname is 296@var{this},'' or ``architecture is not @var{that}.'' Selectors may be 297combined arbitrarily. @i{Amd} also supports a variety of filesystem 298types, including NFS, UFS and the novel @dfn{program} filesystem. The 299combination of selectors and multiple filesystem types allows identical 300configuration files to be used on all machines thus reducing the 301administrative overhead. 302 303@i{Amd} ensures that it will not hang if a remote server goes down. 304Moreover, @i{Amd} can determine when a remote server has become 305inaccessible and then mount replacement filesystems as and when they 306become available. 307 308@i{Amd} contains no proprietary source code and has been ported to 309numerous flavors of Unix. 310 311@c ################################################################ 312@node History, Overview, Intro, Top 313@unnumbered History 314@cindex History 315 316The @i{Amd} package has been without an official maintainer since 1992. 317Several people have stepped in to maintain it unofficially. Most 318notable were the `upl' (Unofficial Patch Level) releases of @i{Amd}, 319created by me (@email{ezk@@cs.columbia.edu,Erez Zadok}), and available from 320@url{ftp://ftp.cs.columbia.edu/pub/amd/}. The last such unofficial 321release was `upl102'. 322 323Through the process of patching and aging, it was becoming more and more 324apparent that @i{Amd} was in much need of revitalizing. Maintaining 325@i{Amd} had become a difficult task. I took it upon myself to cleanup 326the code, so that it would be easier to port to new platforms, add new 327features, keep up with the many new feature requests, and deal with the 328never ending stream of bug reports. 329 330I have been working on such a release of @i{Amd} on and off since 331January of 1996. The new suite of tools is currently named "am-utils" 332(AutoMounter Utilities), in line with GNU naming conventions, befitting 333the contents of the package. In October of 1996 I had received enough 334offers to help me with this task that I decided to make a mailing list 335for this group of people. Around the same time, @i{Amd} had become a 336necessary part of my PhD thesis work, resulting in more work performed 337on am-utils. 338 339Am-utils version 6.0 was numbered with a major new release number to 340distinguish it from the last official release of @i{Amd} (5.x). Many 341new features have been added such as a GNU @code{configure} system, NFS 342Version 3, Autofs support, a run-time configuration file (`amd.conf'), 343many new ports, more scripts and programs, as well as numerous bug 344fixes. Another reason for the new major release number was to alert 345users of am-utils that user-visible interfaces may have changed. In 346order to make @i{Amd} work well for the next 10 years, and be easier to 347maintain, it was necessary to remove old or unused features, change 348various syntax files, etc. However, great care was taken to ensure the 349maximum possible backwards compatibility. 350 351@c ################################################################ 352@node Overview, Supported Platforms, History, Top 353@chapter Overview 354 355@i{Amd} maintains a cache of mounted filesystems. Filesystems are 356@dfn{demand-mounted} when they are first referenced, and unmounted after 357a period of inactivity. @i{Amd} may be used as a replacement for Sun's 358@b{automount}(8) program. It contains no proprietary source code and 359has been ported to numerous flavors of Unix. @xref{Supported 360Platforms}.@refill 361 362@i{Amd} was designed as the basis for experimenting with filesystem 363layout and management. Although @i{Amd} has many direct applications it 364is loaded with additional features which have little practical use. At 365some point the infrequently used components may be removed to streamline 366the production system. 367 368@c @i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating 369@c each member of a list of possible filesystem locations in parallel. 370@c @i{Amd} checks that each cached mapping remains valid. Should a mapping be 371@c lost -- such as happens when a fileserver goes down -- @i{Amd} automatically 372@c selects a replacement should one be available. 373@c 374@menu 375* Fundamentals:: 376* Filesystems and Volumes:: 377* Volume Naming:: 378* Volume Binding:: 379* Operational Principles:: 380* Mounting a Volume:: 381* Automatic Unmounting:: 382* Keep-alives:: 383* Non-blocking Operation:: 384@end menu 385 386@node Fundamentals, Filesystems and Volumes, Overview, Overview 387@comment node-name, next, previous, up 388@section Fundamentals 389@cindex Automounter fundamentals 390 391The fundamental concept behind @i{Amd} is the ability to separate the 392name used to refer to a file from the name used to refer to its physical 393storage location. This allows the same files to be accessed with the 394same name regardless of where in the network the name is used. This is 395very different from placing @file{/n/hostname} in front of the pathname 396since that includes location dependent information which may change if 397files are moved to another machine. 398 399By placing the required mappings in a centrally administered database, 400filesystems can be re-organized without requiring changes to 401configuration files, shell scripts and so on. 402 403@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview 404@comment node-name, next, previous, up 405@section Filesystems and Volumes 406@cindex Filesystem 407@cindex Volume 408@cindex Fileserver 409@cindex sublink 410 411@i{Amd} views the world as a set of fileservers, each containing one or 412more filesystems where each filesystem contains one or more 413@dfn{volumes}. Here the term @dfn{volume} is used to refer to a 414coherent set of files such as a user's home directory or a @TeX{} 415distribution.@refill 416 417In order to access the contents of a volume, @i{Amd} must be told in 418which filesystem the volume resides and which host owns the filesystem. 419By default the host is assumed to be local and the volume is assumed to 420be the entire filesystem. If a filesystem contains more than one 421volume, then a @dfn{sublink} is used to refer to the sub-directory 422within the filesystem where the volume can be found. 423 424@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview 425@comment node-name, next, previous, up 426@section Volume Naming 427@cindex Volume names 428@cindex Network-wide naming 429@cindex Replicated volumes 430@cindex Duplicated volumes 431@cindex Replacement volumes 432 433Volume names are defined to be unique across the entire network. A 434volume name is the pathname to the volume's root as known by the users 435of that volume. Since this name uniquely identifies the volume 436contents, all volumes can be named and accessed from each host, subject 437to administrative controls. 438 439Volumes may be replicated or duplicated. Replicated volumes contain 440identical copies of the same data and reside at two or more locations in 441the network. Each of the replicated volumes can be used 442interchangeably. Duplicated volumes each have the same name but contain 443different, though functionally identical, data. For example, 444@samp{/vol/tex} might be the name of a @TeX{} distribution which varied 445for each machine architecture.@refill 446 447@i{Amd} provides facilities to take advantage of both replicated and 448duplicated volumes. Configuration options allow a single set of 449configuration data to be shared across an entire network by taking 450advantage of replicated and duplicated volumes. 451 452@i{Amd} can take advantage of replacement volumes by mounting them as 453required should an active fileserver become unavailable. 454 455@node Volume Binding, Operational Principles, Volume Naming, Overview 456@comment node-name, next, previous, up 457@section Volume Binding 458@cindex Volume binding 459@cindex Unix namespace 460@cindex Namespace 461@cindex Binding names to filesystems 462 463Unix implements a namespace of hierarchically mounted filesystems. Two 464forms of binding between names and files are provided. A @dfn{hard 465link} completes the binding when the name is added to the filesystem. A 466@dfn{soft link} delays the binding until the name is accessed. An 467@dfn{automounter} adds a further form in which the binding of name to 468filesystem is delayed until the name is accessed.@refill 469 470The target volume, in its general form, is a tuple (host, filesystem, 471sublink) which can be used to name the physical location of any volume 472in the network. 473 474When a target is referenced, @i{Amd} ignores the sublink element and 475determines whether the required filesystem is already mounted. This is 476done by computing the local mount point for the filesystem and checking 477for an existing filesystem mounted at the same place. If such a 478filesystem already exists then it is assumed to be functionally 479identical to the target filesystem. By default there is a one-to-one 480mapping between the pair (host, filesystem) and the local mount point so 481this assumption is valid. 482 483@node Operational Principles, Mounting a Volume, Volume Binding, Overview 484@comment node-name, next, previous, up 485@section Operational Principles 486@cindex Operational principles 487 488@i{Amd} operates by introducing new mount points into the namespace. 489These are called @dfn{automount} points. The kernel sees these 490automount points as NFS filesystems being served by @i{Amd}. Having 491attached itself to the namespace, @i{Amd} is now able to control the 492view the rest of the system has of those mount points. RPC calls are 493received from the kernel one at a time. 494 495When a @dfn{lookup} call is received @i{Amd} checks whether the name is 496already known. If it is not, the required volume is mounted. A 497symbolic link pointing to the volume root is then returned. Once the 498symbolic link is returned, the kernel will send all other requests 499direct to the mounted filesystem. 500 501If a volume is not yet mounted, @i{Amd} consults a configuration 502@dfn{mount-map} corresponding to the automount point. @i{Amd} then 503makes a runtime decision on what and where to mount a filesystem based 504on the information obtained from the map. 505 506@i{Amd} does not implement all the NFS requests; only those relevant 507to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. 508Some other calls are also implemented but most simply return an error 509code; for example @dfn{mkdir} always returns ``read-only filesystem''. 510 511@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview 512@comment node-name, next, previous, up 513@section Mounting a Volume 514@cindex Mounting a volume 515@cindex Location lists 516@cindex Alternate locations 517@cindex Mount retries 518@cindex Background mounts 519 520Each automount point has a corresponding mount map. The mount map 521contains a list of key--value pairs. The key is the name of the volume 522to be mounted. The value is a list of locations describing where the 523filesystem is stored in the network. In the source for the map the 524value would look like 525 526@display 527location1 location2 @dots{} locationN 528@end display 529 530@i{Amd} examines each location in turn. Each location may contain 531@dfn{selectors} which control whether @i{Amd} can use that location. 532For example, the location may be restricted to use by certain hosts. 533Those locations which cannot be used are ignored. 534 535@i{Amd} attempts to mount the filesystem described by each remaining 536location until a mount succeeds or @i{Amd} can no longer proceed. The 537latter can occur in three ways: 538 539@itemize @bullet 540@item 541If none of the locations could be used, or if all of the locations 542caused an error, then the last error is returned. 543 544@item 545If a location could be used but was being mounted in the background then 546@i{Amd} marks that mount as being ``in progress'' and continues with 547the next request; no reply is sent to the kernel. 548 549@item 550Lastly, one or more of the mounts may have been @dfn{deferred}. A mount 551is deferred if extra information is required before the mount can 552proceed. When the information becomes available the mount will take 553place, but in the mean time no reply is sent to the kernel. If the 554mount is deferred, @i{Amd} continues to try any remaining locations. 555@end itemize 556 557Once a volume has been mounted, @i{Amd} establishes a @dfn{volume 558mapping} which is used to satisfy subsequent requests.@refill 559 560@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview 561@comment node-name, next, previous, up 562@section Automatic Unmounting 563 564To avoid an ever increasing number of filesystem mounts, @i{Amd} removes 565volume mappings which have not been used recently. A time-to-live 566interval is associated with each mapping and when that expires the 567mapping is removed. When the last reference to a filesystem is removed, 568that filesystem is unmounted. If the unmount fails, for example the 569filesystem is still busy, the mapping is re-instated and its 570time-to-live interval is extended. The global default for this grace 571period is controlled by the @code{-w} command-line option (@pxref{-w 572Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval} 573(@pxref{dismount_interval Parameter}). It is also possible to set this 574value on a per-mount basis (@pxref{opts Option, opts, opts}). 575 576Filesystems can be forcefully timed out using the @i{Amq} command. 577@xref{Run-time Administration}. 578 579@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview 580@comment node-name, next, previous, up 581@section Keep-alives 582@cindex Keep-alives 583@cindex Server crashes 584@cindex NFS ping 585 586Use of some filesystem types requires the presence of a server on 587another machine. If a machine crashes then it is of no concern to 588processes on that machine that the filesystem is unavailable. However, 589to processes on a remote host using that machine as a fileserver this 590event is important. This situation is most widely recognized when an 591NFS server crashes and the behavior observed on client machines is that 592more and more processes hang. In order to provide the possibility of 593recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some 594filesystem types. Currently only NFS makes use of this service. 595 596The basis of the NFS keep-alive implementation is the observation that 597most sites maintain replicated copies of common system data such as 598manual pages, most or all programs, system source code and so on. If 599one of those servers goes down it would be reasonable to mount one of 600the others as a replacement. 601 602The first part of the process is to keep track of which fileservers are 603up and which are down. @i{Amd} does this by sending RPC requests to the 604servers' NFS @code{NullProc} and checking whether a reply is returned. 605While the server state is uncertain the requests are re-transmitted at 606three second intervals and if no reply is received after four attempts 607the server is marked down. If a reply is received the fileserver is 608marked up and stays in that state for 30 seconds at which time another 609NFS ping is sent. 610 611Once a fileserver is marked down, requests continue to be sent every 30 612seconds in order to determine when the fileserver comes back up. During 613this time any reference through @i{Amd} to the filesystems on that 614server fail with the error ``Operation would block''. If a replacement 615volume is available then it will be mounted, otherwise the error is 616returned to the user. 617 618@c @i{Amd} keeps track of which servers are up and which are down. 619@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and 620@c checking whether a reply is returned. If no replies are received after a 621@c short period, @i{Amd} marks the fileserver @dfn{down}. 622@c RPC requests continue to be sent so that it will notice when a fileserver 623@c comes back up. 624@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability 625@c of the NFS service that is important, not the existence of a base kernel. 626@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate 627@c filesystem is mounted if one is available. 628@c 629Although this action does not protect user files, which are unique on 630the network, or processes which do not access files via @i{Amd} or 631already have open files on the hung filesystem, it can prevent most new 632processes from hanging. 633 634By default, fileserver state is not maintained for NFS/TCP mounts. The 635remote fileserver is always assumed to be up. 636@c 637@c With a suitable combination of filesystem management and mount-maps, 638@c machines can be protected against most server downtime. This can be 639@c enhanced by allocating boot-servers dynamically which allows a diskless 640@c workstation to be quickly restarted if necessary. Once the root filesystem 641@c is mounted, @i{Amd} can be started and allowed to mount the remainder of 642@c the filesystem from whichever fileservers are available. 643 644@node Non-blocking Operation, , Keep-alives, Overview 645@comment node-name, next, previous, up 646@section Non-blocking Operation 647@cindex Non-blocking operation 648@cindex Multiple-threaded server 649@cindex RPC retries 650 651Since there is only one instance of @i{Amd} for each automount point, 652and usually only one instance on each machine, it is important that it 653is always available to service kernel calls. @i{Amd} goes to great 654lengths to ensure that it does not block in a system call. As a last 655resort @i{Amd} will fork before it attempts a system call that may block 656indefinitely, such as mounting an NFS filesystem. Other tasks such as 657obtaining filehandle information for an NFS filesystem, are done using a 658purpose built non-blocking RPC library which is integrated with 659@i{Amd}'s task scheduler. This library is also used to implement NFS 660keep-alives (@pxref{Keep-alives}). 661 662Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it 663to complete before replying to the kernel. However, this would cause 664@i{Amd} to block waiting for a reply to be constructed. Rather than do 665this, @i{Amd} simply @dfn{drops} the call under the assumption that the 666kernel RPC mechanism will automatically retry the request. 667 668@c ################################################################ 669@node Supported Platforms, Mount Maps, Overview, Top 670@comment node-name, next, previous, up 671@chapter Supported Platforms 672@cindex Supported Platforms 673@cindex shared libraries 674@cindex NFS V.3 support 675 676@i{Am-utils} has been ported to a wide variety of machines and operating 677systems. @i{Am-utils}'s code works for little-endian and big-endian 678machines, as well as 32 bit and 64 bit architectures. Furthermore, when 679@i{Am-utils} ports to an Operating System on one architecture, it is generally 680readily portable to the same Operating System on all platforms on which 681it is available. 682 683The table below lists those platforms supported by the latest release. 684The listing is based on the standard output from GNU's 685@code{config.guess} script. Since significant changes have been made to 686am-utils, not all systems listed here have been verified working for all 687features. 688 689@multitable {Auto-Configured System Name} {Config} {Compile} {Amd} {NFS3} {Shlib} {Hlfsd} 690@c @multitable @columnfractions .5 .1 .1 .1 .1 .1 691 692@item @b{Auto-Configured System Name} 693@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 694@tab @b{Config} @tab @b{Compile} @tab @b{Amd} @tab @b{NFS3} @tab @b{Shlib} @tab @b{Hlfsd} 695 696@item @b{alpha-dec-osf2.1} 697@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 698@tab yes @tab yes @tab yes @tab ? @tab no @tab ? 699 700@item @b{alpha-dec-osf4.0} 701@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 702@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 703 704@item @b{alphaev5-unknown-linux-gnu} 705@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 706@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 707 708@item @b{alphaev5-unknown-linux-gnu-rh5.2} 709@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 710@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 711 712@item @b{hppa1.0-hp-hpux11.00} 713@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 714@tab yes @tab yes @tab yes @tab no @tab yes @tab ? 715 716@item @b{hppa1.1-hp-hpux10.10} 717@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 718@tab yes @tab yes @tab yes @tab n/a @tab no @tab ? 719 720@item @b{hppa1.1-hp-hpux10.20} 721@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 722@tab yes @tab yes @tab yes @tab no @tab no @tab ? 723 724@item @b{hppa1.1-hp-hpux9.01} 725@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 726@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 727 728@item @b{hppa1.1-hp-hpux9.05} 729@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 730@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 731 732@item @b{hppa1.1-hp-hpux9.07} 733@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 734@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 735 736@item @b{hppa2.0w-hp-hpux11.00} 737@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 738@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 739 740@item @b{i386-pc-bsdi2.1} 741@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 742@tab yes @tab yes @tab yes @tab n/a @tab no @tab ? 743 744@item @b{i386-pc-bsdi3.0} 745@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 746@tab yes @tab yes @tab yes @tab yes @tab no @tab ? 747 748@item @b{i386-pc-bsdi3.1} 749@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 750@tab yes @tab yes @tab yes @tab yes @tab no @tab ? 751 752@item @b{i386-pc-bsdi4.0} 753@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 754@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 755 756@item @b{i386-pc-bsdi4.0.1} 757@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 758@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 759 760@item @b{i386-pc-solaris2.5.1} 761@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 762@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 763 764@item @b{i386-pc-solaris2.6} 765@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 766@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 767 768@item @b{i386-pc-solaris2.7} 769@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 770@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 771 772@item @b{i386-unknown-freebsd2.1.0} 773@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 774@tab yes @tab yes @tab yes @tab n/a @tab ? @tab ? 775 776@item @b{i386-unknown-freebsd2.2.1} 777@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 778@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 779 780@item @b{i386-unknown-freebsd2.2.6} 781@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 782@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 783 784@item @b{i386-unknown-freebsd2.2.7} 785@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 786@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 787 788@item @b{i386-unknown-freebsd2.2.8} 789@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 790@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 791 792@item @b{i386-unknown-freebsd3.0} 793@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 794@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 795 796@item @b{i386-unknown-freebsdelf3.0} 797@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 798@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 799 800@item @b{i386-unknown-freebsdelf3.1} 801@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 802@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 803 804@item @b{i386-unknown-freebsdelf3.2} 805@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 806@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 807 808@item @b{i386-unknown-freebsdelf3.3} 809@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 810@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 811 812@item @b{i386-unknown-freebsdelf4.0} 813@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 814@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 815 816@item @b{i386-unknown-netbsd1.2.1} 817@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 818@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 819 820@item @b{i386-unknown-netbsd1.3} 821@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 822@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 823 824@item @b{i386-unknown-netbsd1.3.1} 825@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 826@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 827 828@item @b{i386-unknown-netbsd1.3.2} 829@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 830@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 831 832@item @b{i386-unknown-netbsd1.3.3} 833@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 834@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 835 836@item @b{i386-unknown-netbsd1.4} 837@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 838@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 839 840@item @b{i386-unknown-openbsd2.1} 841@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 842@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 843 844@item @b{i386-unknown-openbsd2.2} 845@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 846@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 847 848@item @b{i386-unknown-openbsd2.3} 849@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 850@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 851 852@item @b{i386-unknown-openbsd2.4} 853@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 854@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 855 856@item @b{i386-unknown-openbsd2.5} 857@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 858@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 859 860@item @b{i486-ncr-sysv4.3.03} 861@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 862@tab yes @tab yes @tab ? @tab yes @tab yes @tab ? 863 864@item @b{i486-pc-linux-gnu-rh6.0} 865@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 866@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 867 868@item @b{i486-pc-linux-gnulibc1} 869@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 870@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 871 872@item @b{i486-pc-linux-gnulibc1-rh4.2} 873@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 874@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 875 876@item @b{i486-pc-linux-gnuoldld} 877@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 878@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 879 880@item @b{i586-pc-linux-gnu} 881@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 882@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 883 884@item @b{i586-pc-linux-gnu-rh5.2} 885@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 886@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 887 888@item @b{i586-pc-linux-gnu-rh6.0} 889@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 890@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 891 892@item @b{i586-pc-linux-gnulibc1} 893@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 894@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 895 896@item @b{i586-pc-linux-gnulibc1-rh4.2} 897@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 898@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 899 900 901@item @b{i686-pc-linux-gnu} 902@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 903@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 904 905@item @b{i686-pc-linux-gnu-rh5.2} 906@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 907@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 908 909@item @b{i686-pc-linux-gnu-rh6.0} 910@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 911@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 912 913@item @b{i686-pc-linux-gnulibc} 914@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 915@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 916 917@item @b{i686-pc-linux-gnulibc1} 918@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 919@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 920 921@item @b{m68k-hp-hpux9.00} 922@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 923@tab yes @tab yes @tab yes @tab n/a @tab ? @tab ? 924 925@item @b{m68k-sun-sunos4.1.1} 926@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 927@tab yes @tab yes @tab yes @tab n/a @tab no @tab ? 928 929@item @b{m68k-next-nextstep3} 930@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 931@tab yes @tab yes @tab yes @tab n/a @tab no @tab ? 932 933@item @b{mips-dec-ultrix4.3} 934@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 935@tab yes @tab yes @tab yes @tab n/a @tab ? @tab ? 936 937@item @b{mips-sgi-irix5.2} 938@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 939@tab ? @tab ? @tab ? @tab ? @tab ? @tab ? 940 941@item @b{mips-sgi-irix5.3} 942@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 943@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 944 945@item @b{mips-sgi-irix6.2} 946@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 947@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 948 949@item @b{mips-sgi-irix6.4} 950@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 951@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 952 953@item @b{mips-sgi-irix6.5} 954@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 955@tab yes @tab yes @tab ? @tab yes @tab yes @tab ? 956 957@item @b{powerpc-ibm-aix4.1.5.0} 958@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 959@tab yes @tab yes @tab yes @tab n/a @tab no/broken @tab ? 960 961@item @b{powerpc-ibm-aix4.2.1.0} 962@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 963@tab yes @tab yes @tab yes @tab yes @tab no/broken @tab ? 964 965@item @b{powerpc-ibm-aix4.3.1.0} 966@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 967@tab yes @tab yes @tab ? @tab yes @tab ? @tab ? 968 969@item @b{powerpc-unknown-linux-gnu} 970@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 971@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 972 973@item @b{rs6000-ibm-aix3.2} 974@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 975@tab yes @tab yes @tab yes @tab n/a @tab ? @tab ? 976 977@item @b{rs6000-ibm-aix3.2.5} 978@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 979@tab yes @tab yes @tab yes @tab n/a @tab ? @tab ? 980 981@item @b{rs6000-ibm-aix4.1.4.0} 982@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 983@tab yes @tab yes @tab yes @tab n/a @tab no/broken @tab ? 984 985@item @b{rs6000-ibm-aix4.1.5.0} 986@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 987@tab yes @tab yes @tab yes @tab n/a @tab no/broken @tab ? 988 989@item @b{sparc-sun-solaris2.3} 990@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 991@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 992 993@item @b{sparc-sun-solaris2.4} 994@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 995@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 996 997@item @b{sparc-sun-solaris2.5} 998@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 999@tab yes @tab yes @tab yes @tab yes @tab yes @tab ? 1000 1001@item @b{sparc-sun-solaris2.5.1} 1002@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1003@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 1004 1005@item @b{sparc-sun-solaris2.6} 1006@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1007@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 1008 1009@item @b{sparc-sun-solaris2.7} 1010@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1011@tab yes @tab yes @tab yes @tab yes @tab yes @tab yes 1012 1013@item @b{sparc-sun-sunos4.1.1} 1014@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1015@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1016 1017@item @b{sparc-sun-sunos4.1.3} 1018@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1019@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1020 1021@item @b{sparc-sun-sunos4.1.3C} 1022@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1023@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1024 1025@item @b{sparc-sun-sunos4.1.3_U1} 1026@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1027@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1028 1029@item @b{sparc-sun-sunos4.1.4} 1030@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1031@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1032 1033@item @b{sparc-unknown-linux-gnulibc1} 1034@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1035@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1036 1037@item @b{sparc-unknown-netbsd1.2E} 1038@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1039@tab yes @tab yes @tab yes @tab ? @tab ? @tab ? 1040 1041@item @b{sparc-unknown-netbsd1.2G} 1042@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1043@tab yes @tab yes @tab yes @tab ? @tab ? @tab ? 1044 1045@item @b{sparc64-unknown-linux-gnu} 1046@c {Config} {Compile} {Amd} {NFS V.3} {Shlib} {Hlfsd} 1047@tab yes @tab yes @tab yes @tab n/a @tab yes @tab ? 1048 1049@end multitable 1050 1051See the @file{INSTALL} in the distribution for more specific details on 1052building and/or configuring for some systems. 1053 1054@c ################################################################ 1055@node Mount Maps, Amd Command Line Options, Supported Platforms, Top 1056@comment node-name, next, previous, up 1057@chapter Mount Maps 1058@cindex Mount maps 1059@cindex Automounter configuration maps 1060@cindex Mount information 1061 1062@i{Amd} has no built-in knowledge of machines or filesystems. 1063External @dfn{mount-maps} are used to provide the required information. 1064Specifically, @i{Amd} needs to know when and under what conditions it 1065should mount filesystems. 1066 1067The map entry corresponding to the requested name contains a list of 1068possible locations from which to resolve the request. Each location 1069specifies filesystem type, information required by that filesystem (for 1070example the block special device in the case of UFS), and some 1071information describing where to mount the filesystem (@pxref{fs Option}). A 1072location may also contain @dfn{selectors} (@pxref{Selectors}).@refill 1073 1074@menu 1075* Map Types:: 1076* Key Lookup:: 1077* Location Format:: 1078@end menu 1079 1080@node Map Types, Key Lookup, Mount Maps, Mount Maps 1081@comment node-name, next, previous, up 1082@section Map Types 1083@cindex Mount map types 1084@cindex Map types 1085@cindex Configuration map types 1086@cindex Types of mount map 1087@cindex Types of configuration map 1088@cindex Determining the map type 1089 1090A mount-map provides the run-time configuration information to @i{Amd}. 1091Maps can be implemented in many ways. Some of the forms supported by 1092@i{Amd} are regular files, ndbm databases, NIS maps, the @dfn{Hesiod} 1093name server, and even the password file. 1094 1095A mount-map @dfn{name} is a sequence of characters. When an automount 1096point is created a handle on the mount-map is obtained. For each map 1097type configured, @i{Amd} attempts to reference the map of the 1098appropriate type. If a map is found, @i{Amd} notes the type for future 1099use and deletes the reference, for example closing any open file 1100descriptors. The available maps are configured when @i{Amd} is built 1101and can be displayed by running the command @samp{amd -v}. 1102 1103When using an @i{Amd} configuration file (@pxref{Amd Configuration File}) 1104and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may 1105force the map used to any type. 1106 1107By default, @i{Amd} caches data in a mode dependent on the type of map. 1108This is the same as specifying @samp{cache:=mapdefault} and selects a 1109suitable default cache mode depending on the map type. The individual 1110defaults are described below. The @var{cache} option can be specified 1111on automount points to alter the caching behavior (@pxref{Automount 1112Filesystem}).@refill 1113 1114The following map types have been implemented, though some are not 1115available on all machines. Run the command @samp{amd -v} to obtain a 1116list of map types configured on your machine. 1117 1118@menu 1119* File maps:: 1120* ndbm maps:: 1121* NIS maps:: 1122* NIS+ maps:: 1123* Hesiod maps:: 1124* Password maps:: 1125* Union maps:: 1126* LDAP maps:: 1127@end menu 1128 1129@node File maps, ndbm maps, Map Types, Map Types 1130@comment node-name, next, previous, up 1131@subsection File maps 1132@cindex File maps 1133@cindex Flat file maps 1134@cindex File map syntactic conventions 1135 1136When @i{Amd} searches a file for a map entry it does a simple scan of 1137the file and supports both comments and continuation lines. 1138 1139Continuation lines are indicated by a backslash character (@samp{\}) as 1140the last character of a line in the file. The backslash, newline character 1141@emph{and any leading white space on the following line} are discarded. A maximum 1142line length of 2047 characters is enforced after continuation lines are read 1143but before comments are stripped. Each line must end with 1144a newline character; that is newlines are terminators, not separators. 1145The following examples illustrate this: 1146 1147@example 1148key valA valB; \ 1149 valC 1150@end example 1151 1152specifies @emph{three} locations, and is identical to 1153 1154@example 1155key valA valB; valC 1156@end example 1157 1158However, 1159 1160@example 1161key valA valB;\ 1162 valC 1163@end example 1164 1165specifies only @emph{two} locations, and is identical to 1166 1167@example 1168key valA valB;valC 1169@end example 1170 1171After a complete line has been read from the file, including 1172continuations, @i{Amd} determines whether there is a comment on the 1173line. A comment begins with a hash (``@samp{#}'') character and 1174continues to the end of the line. There is no way to escape or change 1175the comment lead-in character. 1176 1177Note that continuation lines and comment support @dfn{only} apply to 1178file maps, or ndbm maps built with the @code{mk-amd-map} program. 1179 1180When caching is enabled, file maps have a default cache mode of 1181@code{all} (@pxref{Automount Filesystem}). 1182 1183@node ndbm maps, NIS maps, File maps, Map Types 1184@comment node-name, next, previous, up 1185@subsection ndbm maps 1186@cindex ndbm maps 1187 1188An ndbm map may be used as a fast access form of a file map. The program, 1189@code{mk-amd-map}, converts a normal map file into an ndbm database. 1190This program supports the same continuation and comment conventions that 1191are provided for file maps. Note that ndbm format files may @emph{not} 1192be sharable across machine architectures. The notion of speed generally 1193only applies to large maps; a small map, less than a single disk block, 1194is almost certainly better implemented as a file map. 1195 1196ndbm maps have a default cache mode of @samp{all} (@pxref{Automount Filesystem}). 1197 1198@node NIS maps, NIS+ maps, ndbm maps, Map Types 1199@comment node-name, next, previous, up 1200@subsection NIS maps 1201@cindex NIS (YP) maps 1202 1203When using NIS (formerly YP), an @i{Amd} map is implemented directly 1204by the underlying NIS map. Comments and continuation lines are 1205@emph{not} supported in the automounter and must be stripped when 1206constructing the NIS server's database. 1207 1208NIS maps have a default cache mode of @code{all} (@pxref{Automount 1209Filesystem}). 1210 1211The following rule illustrates what could be added to your NIS @file{Makefile}, 1212in this case causing the @file{amd.home} map to be rebuilt: 1213@example 1214$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home 1215 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ 1216 awk '@{ \ 1217 for (i = 1; i <= NF; i++) \ 1218 if (i == NF) @{ \ 1219 if (substr($$i, length($$i), 1) == "\\") \ 1220 printf("%s", substr($$i, 1, length($$i) - 1)); \ 1221 else \ 1222 printf("%s\n", $$i); \ 1223 @} \ 1224 else \ 1225 printf("%s ", $$i); \ 1226 @}' | \ 1227 $(MAKEDBM) - $(YPDBDIR)/amd.home; \ 1228 touch $(YPTSDIR)/amd.home.time; \ 1229 echo "updated amd.home"; \ 1230 if [ ! $(NOPUSH) ]; then \ 1231 $(YPPUSH) amd.home; \ 1232 echo "pushed amd.home"; \ 1233 else \ 1234 : ; \ 1235 fi 1236@end example 1237 1238Here @code{$(YPTSDIR)} contains the time stamp files, and @code{$(YPDBDIR)} contains 1239the dbm format NIS files. 1240 1241@node NIS+ maps, Hesiod maps, NIS maps, Map Types 1242@comment node-name, next, previous, up 1243@subsection NIS+ maps 1244@cindex NIS+ maps 1245 1246NIS+ maps do not support cache mode @samp{all} and, when caching is 1247enabled, have a default cache mode of @samp{inc}. 1248 1249XXX: FILL IN WITH AN EXAMPLE. 1250 1251@node Hesiod maps, Password maps, NIS+ maps, Map Types 1252@comment node-name, next, previous, up 1253@subsection Hesiod maps 1254@cindex Hesiod maps 1255 1256When the map name begins with the string @samp{hesiod.} lookups are made 1257using the @dfn{Hesiod} name server. The string following the dot is 1258used as a name qualifier and is prepended with the key being located. 1259The entire string is then resolved in the @code{automount} context, or 1260the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base 1261Parameter}). For example, if the the key is @samp{jsp} and map name is 1262@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve 1263@samp{jsp.homes.automount}. 1264 1265Hesiod maps do not support cache mode @samp{all} and, when caching is 1266enabled, have a default cache mode of @samp{inc} (@pxref{Automount 1267Filesystem}). 1268 1269The following is an example of a @dfn{Hesiod} map entry: 1270 1271@example 1272jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" 1273njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" 1274@end example 1275 1276@node Password maps, Union maps, Hesiod maps, Map Types 1277@comment node-name, next, previous, up 1278@subsection Password maps 1279@cindex Password file maps 1280@cindex /etc/passwd maps 1281@cindex User maps, automatic generation 1282@cindex Automatic generation of user maps 1283@cindex Using the password file as a map 1284 1285The password map support is unlike the four previous map types. When 1286the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user 1287name in the password file and re-arrange the home directory field to 1288produce a usable map entry. 1289 1290@i{Amd} assumes the home directory has the format 1291`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. 1292@c @footnote{This interpretation is not necessarily exactly what you want.} 1293It breaks this string into a map entry where @code{$@{rfs@}} has the 1294value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value 1295`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the 1296value @i{login}.@refill 1297 1298Thus if the password file entry was 1299 1300@example 1301/home/achilles/jsp 1302@end example 1303 1304the map entry used by @i{Amd} would be 1305 1306@example 1307rfs:=/home/achilles;rhost:=achilles;sublink:=jsp 1308@end example 1309 1310Similarly, if the password file entry was 1311 1312@example 1313/home/cc/sugar/mjh 1314@end example 1315 1316the map entry used by @i{Amd} would be 1317 1318@example 1319rfs:=/home/sugar;rhost:=sugar.cc;sublink:=jsp 1320@end example 1321 1322@node Union maps, LDAP maps , Password maps, Map Types 1323@comment node-name, next, previous, up 1324@subsection Union maps 1325@cindex Union file maps 1326 1327The union map support is provided specifically for use with the union 1328filesystem, @pxref{Union Filesystem}. 1329 1330It is identified by the string @samp{union:} which is followed by a 1331colon separated list of directories. The directories are read in order, 1332and the names of all entries are recorded in the map cache. Later 1333directories take precedence over earlier ones. The union filesystem 1334type then uses the map cache to determine the union of the names in all 1335the directories. 1336 1337@node LDAP maps, , Union maps, Map Types 1338@comment node-name, next, previous, up 1339@subsection LDAP maps 1340@cindex LDAP maps 1341@cindex Lightweight Directory Access Protocol 1342 1343LDAP (Lightweight Directory Access Protocol) maps do not support cache 1344mode @samp{all} and, when caching is enabled, have a default cache mode 1345of @samp{inc}. 1346 1347For example, an @i{Amd} map @samp{amd.home} that looks as follows: 1348 1349@example 1350/defaults opts:=rw,intr;type:=link 1351 1352zing -rhost:=shekel \ 1353 host==shekel \ 1354 host!=shekel;type:=nfs 1355@end example 1356@noindent 1357when converted to LDAP (@pxref{amd2ldif}), will result in the following 1358LDAP database: 1359@example 1360$ amd2ldif amd.home CUCS < amd.home 1361dn: cn=amdmap timestamp, CUCS 1362cn : amdmap timestamp 1363objectClass : amdmapTimestamp 1364amdmapTimestamp: 873071363 1365 1366dn: cn=amdmap amd.home[/defaults], CUCS 1367cn : amdmap amd.home[/defaults] 1368objectClass : amdmap 1369amdmapName : amd.home 1370amdmapKey : /defaults 1371amdmapValue : opts:=rw,intr;type:=link 1372 1373dn: cn=amdmap amd.home[], CUCS 1374cn : amdmap amd.home[] 1375objectClass : amdmap 1376amdmapName : amd.home 1377amdmapKey : 1378amdmapValue : 1379 1380dn: cn=amdmap amd.home[zing], CUCS 1381cn : amdmap amd.home[zing] 1382objectClass : amdmap 1383amdmapName : amd.home 1384amdmapKey : zing 1385amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs 1386@end example 1387 1388@c subsection Gdbm 1389 1390@node Key Lookup, Location Format, Map Types, Mount Maps 1391@comment node-name, next, previous, up 1392@section How keys are looked up 1393@cindex Key lookup 1394@cindex Map lookup 1395@cindex Looking up keys 1396@cindex How keys are looked up 1397@cindex Wildcards in maps 1398 1399The key is located in the map whose type was determined when the 1400automount point was first created. In general the key is a pathname 1401component. In some circumstances this may be modified by variable 1402expansion (@pxref{Variable Expansion}) and prefixing. If the automount 1403point has a prefix, specified by the @var{pref} option, then that is 1404prepended to the search key before the map is searched. 1405 1406If the map cache is a @samp{regexp} cache then the key is treated as an 1407egrep-style regular expression, otherwise a normal string comparison is 1408made. 1409 1410If the key cannot be found then a @dfn{wildcard} match is attempted. 1411@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and 1412attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. 1413 1414For example, the following sequence would be checked if @file{home/dylan/dk2} was 1415being located: 1416 1417@example 1418 home/dylan/dk2 1419 home/dylan/* 1420 home/* 1421 * 1422@end example 1423 1424At any point when a wildcard is found, @i{Amd} proceeds as if an exact 1425match had been found and the value field is then used to resolve the 1426mount request, otherwise an error code is propagated back to the kernel. 1427(@pxref{Filesystem Types}).@refill 1428 1429@node Location Format, , Key Lookup, Mount Maps 1430@comment node-name, next, previous, up 1431@section Location Format 1432@cindex Location format 1433@cindex Map entry format 1434@cindex How locations are parsed 1435 1436The value field from the lookup provides the information required to 1437mount a filesystem. The information is parsed according to the syntax 1438shown below. 1439 1440@display 1441@i{location-list}: 1442 @i{location-selection} 1443 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} 1444@i{location-selection}: 1445 @i{location} 1446 @i{location-selection} @i{white-space} @i{location} 1447@i{location}: 1448 @i{location-info} 1449 @t{-}@i{location-info} 1450 @t{-} 1451@i{location-info}: 1452 @i{sel-or-opt} 1453 @i{location-info}@t{;}@i{sel-or-opt} 1454 @t{;} 1455@i{sel-or-opt}: 1456 @i{selection} 1457 @i{opt-ass} 1458@i{selection}: 1459 selector@t{==}@i{value} 1460 selector@t{!=}@i{value} 1461@i{opt-ass}: 1462 option@t{:=}@i{value} 1463@i{white-space}: 1464 space 1465 tab 1466@end display 1467 1468Note that unquoted whitespace is not allowed in a location description. 1469White space is only allowed, and is mandatory, where shown with non-terminal 1470@i{white-space}. 1471 1472A @dfn{location-selection} is a list of possible volumes with which to 1473satisfy the request. @dfn{location-selection}s are separated by the 1474@samp{||} operator. The effect of this operator is to prevent use of 1475location-selections to its right if any of the location-selections on 1476its left were selected whether or not any of them were successfully 1477mounted (@pxref{Selectors}).@refill 1478 1479The location-selection, and singleton @dfn{location-list}, 1480@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS 1481filesystem from the block special device @file{/dev/xd1g}. 1482 1483The @dfn{sel-or-opt} component is either the name of an option required 1484by a specific filesystem, or it is the name of a built-in, predefined 1485selector such as the architecture type. The value may be quoted with 1486double quotes @samp{"}, for example 1487@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the 1488value is parsed and there is no way to get a double quote into a value 1489field. Double quotes are used to get white space into a value field, 1490which is needed for the program filesystem (@pxref{Program Filesystem}).@refill 1491 1492@menu 1493* Map Defaults:: 1494* Variable Expansion:: 1495* Selectors:: 1496* Map Options:: 1497@end menu 1498 1499@node Map Defaults, Variable Expansion, Location Format, Location Format 1500@comment node-name, next, previous, up 1501@subsection Map Defaults 1502@cindex Map defaults 1503@cindex How to set default map parameters 1504@cindex Setting default map parameters 1505 1506A location beginning with a dash @samp{-} is used to specify default 1507values for subsequent locations. Any previously specified defaults in 1508the location-list are discarded. The default string can be empty in 1509which case no defaults apply. 1510 1511The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point 1512to @file{/mnt} and cause mounts to be read-only by default. Defaults 1513specified this way are appended to, and so override, any global map 1514defaults given with @samp{/defaults}). 1515 1516@c 1517@c A @samp{/defaults} value @dfn{gdef} and a location list 1518@c \begin{quote} 1519@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$ 1520@c \end{quote} 1521@c is equivalent to 1522@c \begin{quote} 1523@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$ 1524@c \end{quote} 1525@c which is equivalent to 1526@c \begin{quote} 1527@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$ 1528@c \end{quote} 1529 1530@node Variable Expansion, Selectors, Map Defaults, Location Format 1531@comment node-name, next, previous, up 1532@subsection Variable Expansion 1533@cindex Variable expansion 1534@cindex How variables are expanded 1535@cindex Pathname operators 1536@cindex Domain stripping 1537@cindex Domainname operators 1538@cindex Stripping the local domain name 1539@cindex Environment variables 1540@cindex How to access environment variables in maps 1541 1542To allow generic location specifications @i{Amd} does variable expansion 1543on each location and also on some of the option strings. Any option or 1544selector appearing in the form @code{$@dfn{var}} is replaced by the 1545current value of that option or selector. For example, if the value of 1546@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and 1547@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then 1548after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. 1549Any environment variable can be accessed in a similar way.@refill 1550 1551Two pathname operators are available when expanding a variable. If the 1552variable name begins with @samp{/} then only the last component of the 1553pathname is substituted. For example, if @code{$@{path@}} was 1554@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. 1555Similarly, if the variable name ends with @samp{/} then all but the last 1556component of the pathname is substituted. In the previous example, 1557@code{$@{path/@}} would be expanded to @samp{/foo}.@refill 1558 1559Two domain name operators are also provided. If the variable name 1560begins with @samp{.} then only the domain part of the name is 1561substituted. For example, if @code{$@{rhost@}} was 1562@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to 1563@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} 1564then only the host component is substituted. In the previous example, 1565@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill 1566 1567Variable expansion is a two phase process. Before a location is parsed, 1568all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The 1569location is then parsed, selections are evaluated and option assignments 1570recorded. If there were no selections or they all succeeded the 1571location is used and the values of the following options are expanded in 1572the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, 1573@var{remopts}, @var{mount} and @var{unmount}. 1574 1575Note that expansion of option values is done after @dfn{all} assignments 1576have been completed and not in a purely left to right order as is done 1577by the shell. This generally has the desired effect but care must be 1578taken if one of the options references another, in which case the 1579ordering can become significant. 1580 1581There are two special cases concerning variable expansion: 1582 1583@enumerate 1584@item 1585before a map is consulted, any selectors in the name received 1586from the kernel are expanded. For example, if the request from the 1587kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture 1588was @samp{vax}, the value given to @code{$@{key@}} would be 1589@samp{vax.bin}.@refill 1590 1591@item 1592the value of @code{$@{rhost@}} is expanded and normalized before the 1593other options are expanded. The normalization process strips any local 1594sub-domain components. For example, if @code{$@{domain@}} was 1595@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially 1596@samp{snow.Berkeley.EDU}, after the normalization it would simply be 1597@samp{snow}. Hostname normalization is currently done in a 1598@emph{case-dependent} manner.@refill 1599@end enumerate 1600 1601@c====================================================================== 1602@node Selectors, Map Options, Variable Expansion, Location Format 1603@comment node-name, next, previous, up 1604@subsection Selectors 1605@cindex Selectors 1606 1607Selectors are used to control the use of a location. It is possible to 1608share a mount map between many machines in such a way that filesystem 1609location, architecture and operating system differences are hidden from 1610the users. A selector of the form @samp{arch==sun3;os==sunos4} would only 1611apply on Sun-3s running SunOS 4.x. 1612 1613Selectors can be negated by using @samp{!=} instead of @samp{==}. For 1614example to select a location on all non-Vax machines the selector 1615@samp{arch!=vax} would be used. 1616 1617Selectors are evaluated left to right. If a selector fails then that 1618location is ignored. Thus the selectors form a conjunction and the 1619locations form a disjunction. If all the locations are ignored or 1620otherwise fail then @i{Amd} uses the @dfn{error} filesystem 1621(@pxref{Error Filesystem}). This is equivalent to having a location 1622@samp{type:=error} at the end of each mount-map entry.@refill 1623 1624The default value of many of the selectors listed here can be overridden 1625by an @i{Amd} command line switch or in an @i{Amd} configuration file. 1626@xref{Amd Configuration File}. 1627 1628These are the selectors currently implemented. 1629 1630@menu 1631* arch Selector Variable:: 1632* autodir Selector Variable:: 1633* byte Selector Variable:: 1634* cluster Selector Variable:: 1635* domain Selector Variable:: 1636* host Selector Variable:: 1637* hostd Selector Variable:: 1638* karch Selector Variable:: 1639* os Selector Variable:: 1640* osver Selector Variable:: 1641 1642* key Selector Variable:: 1643* map Selector Variable:: 1644* netnumber Selector Variable:: 1645* network Selector Variable:: 1646* path Selector Variable:: 1647* wire Selector Variable:: 1648 1649* exists Selector Function:: 1650* false Selector Function:: 1651* netgrp Selector Function:: 1652* netgrpd Selector Function:: 1653* in_network Selector Function:: 1654* true Selector Function:: 1655@end menu 1656 1657@c ---------------------------------------------------------------- 1658@node arch Selector Variable, autodir Selector Variable, Selectors, Selectors 1659@comment node-name, next, previous, up 1660@subsubsection arch Selector Variable 1661@cindex arch Selector Variable 1662@cindex arch, mount selector 1663@cindex Mount selector; arch 1664@cindex Selector; arch 1665 1666The machine architecture which was automatically determined at compile 1667time. The architecture type can be displayed by running the command 1668@samp{amd -v}. @xref{Supported Platforms}.@refill 1669 1670@c ---------------------------------------------------------------- 1671@node autodir Selector Variable, byte Selector Variable, arch Selector Variable, Selectors 1672@comment node-name, next, previous, up 1673@subsubsection autodir Selector Variable 1674@cindex autodir Selector Variable 1675@cindex autodir, mount selector 1676@cindex Mount selector; autodir 1677@cindex Selector; autodir 1678 1679The default directory under which to mount filesystems. This may be 1680changed by the @code{-a} command line option. @xref{fs Option}. 1681 1682@c ---------------------------------------------------------------- 1683@node byte Selector Variable, cluster Selector Variable, autodir Selector Variable, Selectors 1684@comment node-name, next, previous, up 1685@subsubsection byte Selector Variable 1686@cindex byte Selector Variable 1687@cindex byte, mount selector 1688@cindex Mount selector; byte 1689@cindex Selector; byte 1690 1691The machine's byte ordering. This is either @samp{little}, indicating 1692little-endian, or @samp{big}, indicating big-endian. One possible use 1693is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to 1694share ndbm databases, however this use can be considered a courageous 1695juggling act. 1696 1697@c ---------------------------------------------------------------- 1698@node cluster Selector Variable, domain Selector Variable, byte Selector Variable, Selectors 1699@comment node-name, next, previous, up 1700@subsubsection cluster Selector Variable 1701@cindex cluster Selector Variable 1702@cindex cluster, mount selector 1703@cindex Mount selector; cluster 1704@cindex Selector; cluster 1705 1706This is provided as a hook for the name of the local cluster. This can 1707be used to decide which servers to use for copies of replicated 1708filesystems. @code{$@{cluster@}} defaults to the value of 1709@code{$@{domain@}} unless a different value is set with the @code{-C} 1710command line option. 1711 1712@c ---------------------------------------------------------------- 1713@node domain Selector Variable, host Selector Variable, cluster Selector Variable, Selectors 1714@comment node-name, next, previous, up 1715@subsubsection domain Selector Variable 1716@cindex domain Selector Variable 1717@cindex domain, mount selector 1718@cindex Mount selector; domain 1719@cindex Selector; domain 1720 1721The local domain name as specified by the @code{-d} command line option. 1722@xref{host Selector Variable}. 1723 1724@c ---------------------------------------------------------------- 1725@node host Selector Variable, hostd Selector Variable, domain Selector Variable, Selectors 1726@comment node-name, next, previous, up 1727@subsubsection host Selector Variable 1728@cindex host Selector Variable 1729@cindex host, mount selector 1730@cindex Mount selector; host 1731@cindex Selector; host 1732 1733The local hostname as determined by @b{gethostname}(2). If no domain 1734name was specified on the command line and the hostname contains a 1735period @samp{.} then the string before the period is used as the host 1736name, and the string after the period is assigned to @code{$@{domain@}}. 1737For example, if the hostname is @samp{styx.doc.ic.ac.uk} then 1738@code{host} would be @samp{styx} and @code{domain} would be 1739@samp{doc.ic.ac.uk}. @code{hostd} would be 1740@samp{styx.doc.ic.ac.uk}.@refill 1741 1742@c ---------------------------------------------------------------- 1743@node hostd Selector Variable, karch Selector Variable, host Selector Variable, Selectors 1744@comment node-name, next, previous, up 1745@subsubsection hostd Selector Variable 1746@cindex hostd Selector Variable 1747@cindex hostd, mount selector 1748@cindex Mount selector; hostd 1749@cindex Selector; hostd 1750 1751This resolves to the @code{$@{host@}} and @code{$@{domain@}} 1752concatenated with a @samp{.} inserted between them if required. If 1753@code{$@{domain@}} is an empty string then @code{$@{host@}} and 1754@code{$@{hostd@}} will be identical. 1755 1756@c ---------------------------------------------------------------- 1757@node karch Selector Variable, os Selector Variable, hostd Selector Variable, Selectors 1758@comment node-name, next, previous, up 1759@subsubsection karch Selector Variable 1760@cindex karch Selector Variable 1761@cindex karch, mount selector 1762@cindex Mount selector; karch 1763@cindex Selector; karch 1764 1765This is provided as a hook for the kernel architecture. This is used on 1766SunOS 4 and SunOS 5, for example, to distinguish between different 1767@samp{/usr/kvm} volumes. @code{$@{karch@}} defaults to the ``machine'' 1768value gotten from @b{uname}(2). If the @b{uname}(2) system call is not 1769available, the value of @code{$@{karch@}} defaults to that of 1770@code{$@{arch@}}. Finally, a different value can be set with the @code{-k} 1771command line option. 1772 1773@c ---------------------------------------------------------------- 1774@node os Selector Variable, osver Selector Variable, karch Selector Variable, Selectors 1775@comment node-name, next, previous, up 1776@subsubsection os Selector Variable 1777@cindex os Selector Variable 1778@cindex os, mount selector 1779@cindex Mount selector; os 1780@cindex Selector; os 1781 1782The operating system. Like the machine architecture, this is 1783automatically determined at compile time. The operating system name can 1784be displayed by running the command @samp{amd -v}. @xref{Supported 1785Platforms}.@refill 1786 1787@c ---------------------------------------------------------------- 1788@node osver Selector Variable, key Selector Variable, os Selector Variable, Selectors 1789@comment node-name, next, previous, up 1790@subsubsection osver Selector Variable 1791@cindex osver Selector Variable 1792@cindex osver, mount selector 1793@cindex Mount selector; osver 1794@cindex Selector; osver 1795 1796The operating system version. Like the machine architecture, this is 1797automatically determined at compile time. The operating system name can 1798be displayed by running the command @samp{amd -v}. @xref{Supported 1799Platforms}.@refill 1800 1801@c ---------------------------------------------------------------- 1802@ifhtml 1803<HR> 1804@end ifhtml 1805@sp 3 1806The following selectors are also provided. Unlike the other selectors, 1807they vary for each lookup. Note that when the name from the kernel is 1808expanded prior to a map lookup, these selectors are all defined as empty 1809strings. 1810 1811@c ---------------------------------------------------------------- 1812@node key Selector Variable, map Selector Variable, osver Selector Variable, Selectors 1813@comment node-name, next, previous, up 1814@subsubsection key Selector Variable 1815@cindex key Selector Variable 1816@cindex key, mount selector 1817@cindex Mount selector; key 1818@cindex Selector; key 1819 1820The name being resolved. For example, if @file{/home} is an automount 1821point, then accessing @file{/home/foo} would set @code{$@{key@}} to the 1822string @samp{foo}. The key is prefixed by the @var{pref} option set in 1823the parent mount point. The default prefix is an empty string. If the 1824prefix was @file{blah/} then @code{$@{key@}} would be set to 1825@file{blah/foo}.@refill 1826 1827@c ---------------------------------------------------------------- 1828@node map Selector Variable, netnumber Selector Variable, key Selector Variable, Selectors 1829@comment node-name, next, previous, up 1830@subsubsection map Selector Variable 1831@cindex map Selector Variable 1832@cindex map, mount selector 1833@cindex Mount selector; map 1834@cindex Selector; map 1835 1836The name of the mount map being used. 1837 1838@c ---------------------------------------------------------------- 1839@node netnumber Selector Variable, network Selector Variable, map Selector Variable, Selectors 1840@comment node-name, next, previous, up 1841@subsubsection netnumber Selector Variable 1842@cindex netnumber Selector Variable 1843@cindex netnumber, mount selector 1844@cindex Mount selector; netnumber 1845@cindex Selector; netnumber 1846 1847This selector is identical to the @samp{in_network} selector function, 1848see @ref{in_network Selector Function}. It will match either the name 1849or number of @i{any} network interface on which this host is connected 1850to. The names and numbers of all attached interfaces are available from 1851the output of @samp{amd -v}. 1852 1853@c ---------------------------------------------------------------- 1854@node network Selector Variable, path Selector Variable, netnumber Selector Variable, Selectors 1855@comment node-name, next, previous, up 1856@subsubsection network Selector Variable 1857@cindex network Selector Variable 1858@cindex network, mount selector 1859@cindex Mount selector; network 1860@cindex Selector; network 1861 1862This selector is identical to the @samp{in_network} selector function, 1863see @ref{in_network Selector Function}. It will match either the name 1864or number of @i{any} network interface on which this host is connected 1865to. The names and numbers of all attached interfaces are available from 1866the output of @samp{amd -v}. 1867 1868@c ---------------------------------------------------------------- 1869@node path Selector Variable, wire Selector Variable, network Selector Variable, Selectors 1870@comment node-name, next, previous, up 1871@subsubsection path Selector Variable 1872@cindex path Selector Variable 1873@cindex path, mount selector 1874@cindex Mount selector; path 1875@cindex Selector; path 1876 1877The full pathname of the name being resolved. For example 1878@file{/home/foo} in the example above. 1879 1880@c ---------------------------------------------------------------- 1881@node wire Selector Variable, exists Selector Function, path Selector Variable, Selectors 1882@comment node-name, next, previous, up 1883@subsubsection wire Selector Variable 1884@cindex wire Selector Variable 1885@cindex wire, mount selector 1886@cindex Mount selector; wire 1887@cindex Selector; wire 1888 1889This selector is identical to the @samp{in_network} selector function, 1890see @ref{in_network Selector Function}. It will match either the name 1891or number of @i{any} network interface on which this host is connected 1892to. The names and numbers of all attached interfaces are available from 1893the output of @samp{amd -v}. 1894 1895@c ---------------------------------------------------------------- 1896@ifhtml 1897<HR> 1898@end ifhtml 1899@sp 2 1900The following boolean functions are selectors which take an argument 1901@i{ARG}. They return a value of true or false, and thus do not need to 1902be compared with a value. Each of these may be negated by prepending 1903@samp{!} to their name. 1904 1905@c ---------------------------------------------------------------- 1906@node exists Selector Function, false Selector Function, wire Selector Variable, Selectors 1907@comment node-name, next, previous, up 1908@subsubsection exists Selector Function 1909@cindex exists Selector Function 1910@cindex exists, boolean mount selector 1911@cindex !exists, boolean mount selector 1912@cindex Mount selector; exists 1913@cindex Selector; exists 1914 1915If the file listed by @i{ARG} exists (via @b{lstat}(2)), this function 1916evaluates to true. Otherwise it evaluates to false. 1917 1918@c ---------------------------------------------------------------- 1919@node false Selector Function, netgrp Selector Function, exists Selector Function, Selectors 1920@comment node-name, next, previous, up 1921@subsubsection false Selector Function 1922@cindex false Selector Function 1923@cindex false, boolean mount selector 1924@cindex !false, boolean mount selector 1925@cindex Mount selector; false 1926@cindex Selector; false 1927 1928Always evaluates to false. @i{ARG} is ignored. 1929 1930@c ---------------------------------------------------------------- 1931@node netgrp Selector Function, netgrpd Selector Function, false Selector Function, Selectors 1932@comment node-name, next, previous, up 1933@subsubsection netgrp Selector Function 1934@cindex netgrp Selector Function 1935@cindex netgrp, boolean mount selector 1936@cindex !netgrp, boolean mount selector 1937@cindex Mount selector; netgrp 1938@cindex Selector; netgrp 1939 1940If the current host as determined by the value of @code{$@{host@}} 1941(e.g., short host name) is a member of the netgroup @i{ARG}, this 1942selector evaluates to true. Otherwise it evaluates to false. 1943 1944For example, suppose you have a netgroup @samp{ppp-hosts}, and for 1945reasons of performance, these have a local @file{/home} partition, while 1946all other clients on the faster network can access a shared home 1947directory. A common map to use for both might look like the following: 1948 1949@example 1950home/* netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \ 1951 !netgrp(ppp-hosts);type:=nfs;rhost=serv1;rfs:=/remote/$@{key@} 1952@end example 1953 1954@c ---------------------------------------------------------------- 1955@node netgrpd Selector Function, in_network Selector Function, netgrp Selector Function, Selectors 1956@comment node-name, next, previous, up 1957@subsubsection netgrpd Selector Function 1958@cindex netgrpd Selector Function 1959@cindex netgrpd, boolean mount selector 1960@cindex !netgrpd, boolean mount selector 1961@cindex Mount selector; netgrpd 1962@cindex Selector; netgrpd 1963 1964If the current host as determined by the value of @code{$@{hostd@}} is a 1965member of the netgroup @i{ARG}, this selector evaluates to true. 1966Otherwise it evaluates to false. 1967 1968The @samp{netgrpd} function uses fully-qualified host names 1969(@code{$@{hostd@}}) to match netgroup names, while the @samp{netgrp} 1970function (@pxref{netgrp Selector Function}) uses short host names 1971(@code{$@{host@}}). 1972 1973@c ---------------------------------------------------------------- 1974@node in_network Selector Function, true Selector Function, netgrpd Selector Function, Selectors 1975@comment node-name, next, previous, up 1976@subsubsection in_network Selector Function 1977@cindex in_network Selector Function 1978@cindex in_network, boolean mount selector 1979@cindex !in_network, boolean mount selector 1980@cindex Mount selector; in_network 1981@cindex Selector; in_network 1982 1983If the current host has any network interface that is locally attached 1984to the network specified in @i{ARG} (either via name or number), this 1985selector evaluates to true. Otherwise it evaluates to false. 1986 1987For example, suppose you have two servers that have an exportable 1988@file{/opt} that smaller clients can NFS mount. The two servers are 1989say, @samp{serv1} on network @samp{foo-net.site.com} and @samp{serv2} on 1990network @samp{123.4.5.0}. You can write a map to be used by all clients 1991that will attempt to mount the closest one as follows: 1992 1993@example 1994opt in_network(foo-net.site.com);rhost:=serv1;rfs:=/opt \ 1995 in_network(123.4.5.0);rhost:=serv2;rfs:=/opt \ 1996 rhost:=fallback-server 1997@end example 1998 1999@c ---------------------------------------------------------------- 2000@node true Selector Function, , in_network Selector Function, Selectors 2001@comment node-name, next, previous, up 2002@subsubsection true Selector Function 2003@cindex true Selector Function 2004@cindex true, boolean mount selector 2005@cindex !true, boolean mount selector 2006@cindex Mount selector; true 2007@cindex Selector; true 2008 2009Always evaluates to true. @i{ARG} is ignored. 2010 2011@c ================================================================ 2012@node Map Options, , Selectors, Location Format 2013@comment node-name, next, previous, up 2014@subsection Map Options 2015@cindex Map options 2016@cindex Setting map options 2017 2018Options are parsed concurrently with selectors. The difference is that 2019when an option is seen the string following the @samp{:=} is 2020recorded for later use. As a minimum the @var{type} option must be 2021specified. Each filesystem type has other options which must also be 2022specified. @xref{Filesystem Types}, for details on the filesystem 2023specific options.@refill 2024 2025Superfluous option specifications are ignored and are not reported 2026as errors. 2027 2028The following options apply to more than one filesystem type. 2029 2030@menu 2031* addopts Option:: 2032* delay Option:: 2033* fs Option:: 2034* opts Option:: 2035* remopts Option:: 2036* sublink Option:: 2037* type Option:: 2038@end menu 2039 2040@node addopts Option, delay Option, Map Options, Map Options 2041@comment node-name, next, previous, up 2042@subsubsection addopts Option 2043@cindex Setting additional options on a mount location 2044@cindex Overriding or adding options to a mount 2045@cindex addopts, mount option 2046@cindex Mount option; addopts 2047 2048This option adds additional options to default options normally 2049specified in the @samp{/defaults} entry or the defaults of the key entry 2050being processed (@pxref{opts Option}). Normally when you specify 2051@samp{opts} in both the @samp{/defaults} and the map entry, the latter 2052overrides the former completely. But with @samp{addopts} it will append 2053the options and override any conflicting ones. 2054 2055@samp{addopts} also overrides the value of the @samp{remopts} option 2056(@pxref{remopts Option}), which unless specified defaults to the value 2057of @samp{opts}. 2058 2059Options which start with @samp{no} will override those with the same 2060name that do not start with @samp{no} and vice verse. Special handling 2061is given to inverted options such as @samp{soft} and @samp{hard}, 2062@samp{bg} and @samp{fg}, @samp{ro} and @samp{rw}, etc. 2063 2064For example, if the default options specified were 2065@example 2066opts:=rw,nosuid,intr,rsize=1024,wsize=1024,quota,posix 2067@end example 2068 2069and the ones specified in a map entry were 2070 2071@example 2072addopts:=grpid,suid,ro,rsize=2048,quota,nointr 2073@end example 2074 2075then the actual options used would be 2076 2077@example 2078wsize=1024,posix,grpid,suid,ro,rsize=2048,quota,nointr 2079@end example 2080 2081@node delay Option, fs Option, addopts Option, Map Options 2082@comment node-name, next, previous, up 2083@subsubsection delay Option 2084@cindex Setting a delay on a mount location 2085@cindex Delaying mounts from specific locations 2086@cindex Primary server 2087@cindex Secondary server 2088@cindex delay, mount option 2089@cindex Mount option; delay 2090 2091The delay, in seconds, before an attempt will be made to mount from the 2092current location. Auxiliary data, such as network address, file handles 2093and so on are computed regardless of this value. 2094 2095A delay can be used to implement the notion of primary and secondary 2096file servers. The secondary servers would have a delay of a few 2097seconds, thus giving the primary servers a chance to respond first. 2098 2099@node fs Option, opts Option, delay Option, Map Options 2100@comment node-name, next, previous, up 2101@subsubsection fs Option 2102@cindex Setting the local mount point 2103@cindex Overriding the default mount point 2104@cindex fs, mount option 2105@cindex Mount option; fs 2106 2107The local mount point. The semantics of this option vary between 2108filesystems. 2109 2110For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the 2111local mount point. For other filesystem types it has other meanings 2112which are described in the section describing the respective filesystem 2113type. It is important that this string uniquely identifies the 2114filesystem being mounted. To satisfy this requirement, it should 2115contain the name of the host on which the filesystem is resident and the 2116pathname of the filesystem on the local or remote host. 2117 2118The reason for requiring the hostname is clear if replicated filesystems 2119are considered. If a fileserver goes down and a replacement filesystem 2120is mounted then the @dfn{local} mount point @dfn{must} be different from 2121that of the filesystem which is hung. Some encoding of the filesystem 2122name is required if more than one filesystem is to be mounted from any 2123given host. 2124 2125If the hostname is first in the path then all mounts from a particular 2126host will be gathered below a single directory. If that server goes 2127down then the hung mount points are less likely to be accidentally 2128referenced, for example when @b{getcwd}(3) traverses the namespace to 2129find the pathname of the current directory. 2130 2131The @samp{fs} option defaults to 2132@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, 2133@samp{rhost} defaults to the local host name (@code{$@{host@}}) and 2134@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full 2135path of the requested file; @samp{/home/foo} in the example above 2136(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may 2137be changed with the @code{-a} command line option. Sun's automounter 2138defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between 2139the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins 2140with a @samp{/}.@refill 2141 2142@node opts Option, remopts Option, fs Option, Map Options 2143@comment node-name, next, previous, up 2144@subsubsection opts Option 2145@cindex Setting system mount options 2146@cindex Passing parameters to the mount system call 2147@cindex mount system call 2148@cindex mount system call flags 2149@cindex The mount system call 2150@cindex opts, mount option 2151@cindex Mount option; opts 2152 2153The options to pass to the mount system call. A leading @samp{-} is 2154silently ignored. The mount options supported generally correspond to 2155those used by @b{mount}(8) and are listed below. Some additional 2156pseudo-options are interpreted by @i{Amd} and are also listed. 2157 2158Unless specifically overridden, each of the system default mount options 2159applies. Any options not recognized are ignored. If no options list is 2160supplied the string @samp{rw,defaults} is used and all the system 2161default mount options apply. Options which are not applicable for a 2162particular operating system are silently ignored. For example, only 4.4BSD 2163is known to implement the @code{compress} and @code{spongy} options. 2164 2165@table @code 2166 2167@item acdirmax=@var{n} 2168@cindex Mount flags; acdirmax 2169Set the maximum directory attribute cache timeout to @var{n}. 2170 2171@item acdirmin=@var{n} 2172@cindex Mount flags; acdirmin 2173Set the minimum directory attribute cache timeout to @var{n}. 2174 2175@item acregmax=@var{n} 2176@cindex Mount flags; acregmax 2177Set the maximum file attribute cache timeout to @var{n}. 2178 2179@item acregmin=@var{n} 2180@cindex Mount flags; acregmin 2181Set the minimum file attribute cache timeout to @var{n}. 2182 2183@item actimeo=@var{n} 2184@cindex Mount flags; actimeo 2185Set the overall attribute cache timeout to @var{n}. 2186 2187@item auto 2188@cindex Mount flags; auto 2189@itemx ignore 2190@cindex Mount flags; ignore 2191Ignore this mount by @b{df}(1). 2192 2193@item cache 2194@cindex Mount flags; cache 2195Allow data to be cached from a remote server for this mount. 2196 2197@item compress 2198@cindex Mount flags; compress 2199Use NFS compression protocol. 2200 2201@item defperm 2202@cindex Mount flags; defperm 2203Ignore the permission mode bits, and default file permissions to 0555, 2204UID 0, and GID 0. Useful for CD-ROMs formatted as ISO-9660. 2205 2206@item dev 2207@cindex Mount flags; dev 2208Allow local special devices on this filesystem. 2209 2210@item dumbtimr 2211@cindex Mount flags; dumbtimr 2212Turn off the dynamic retransmit timeout estimator. This may be useful 2213for UDP mounts that exhibit high retry rates, since it is possible that 2214the dynamically estimated timeout interval is too short. 2215 2216@item extatt 2217@cindex Mount flags; extatt 2218Enable extended attributes in ISO-9660 file systems. 2219 2220@item fsid 2221@cindex Mount flags; fsid 2222Set ID of filesystem. 2223 2224@item gens 2225@cindex Mount flags; gens 2226Enable generations in ISO-9660 file systems. Generations allow you to 2227see all versions of a given file. 2228 2229@item grpid 2230@cindex Mount flags; grpid 2231Use BSD directory group-id semantics. 2232 2233@item int 2234@cindex Mount flags; int 2235@itemx intr 2236@cindex Mount flags; intr 2237Allow keyboard interrupts on hard mounts. 2238 2239@item multi 2240@cindex Mount flags; multi 2241Perform multi-component lookup on files. 2242 2243@item maxgroups 2244@cindex Mount flags; maxgroups 2245Set the maximum number of groups to allow for this mount. 2246 2247@item nfsv3 2248@cindex Mount flags; nfsv3 2249Use NFS Version 3 for this mount. 2250 2251@item noac 2252@cindex Mount flags; noac 2253Turn off the attribute cache. 2254 2255@item noauto 2256@cindex Mount flags; noauto 2257This option is used by the mount command in @samp{/etc/fstab} or 2258@samp{/etc/vfstab} and means not to mount this file system when mount -a 2259is used. 2260 2261@item nocache 2262@cindex Mount flags; nocache 2263Do not allow data to be cached from a remote server for this 2264mount. 2265 2266@item noconn 2267@cindex Mount flags; noconn 2268Don't make a connection on datagram transports. 2269 2270@item nocto 2271@cindex Mount flags; nocto 2272No close-to-open consistency. 2273 2274@item nodefperm 2275@cindex Mount flags; nodefperm 2276Do not ignore the permission mode bits. Useful for CD-ROMS formatted as 2277ISO-9660. 2278 2279@item nodev 2280@cindex Mount flags; nodev 2281@itemx nodevs 2282@cindex Mount flags; nodevs 2283Don't allow local special devices on this filesystem. 2284 2285@item noint 2286@cindex Mount flags; noint 2287Do not allow keyboard interrupts for this mount 2288 2289@item norrip 2290@cindex Mount flags; norrip 2291Turn off using of the Rock Ridge Interchange Protocol (RRIP) extensions 2292to ISO-9660. 2293 2294@item nosub 2295@cindex Mount flags; nosub 2296Disallow mounts beneath this mount. 2297 2298@item nosuid 2299@cindex Mount flags; nosuid 2300Don't allow set-uid or set-gid executables on this filesystem. 2301 2302@item noversion 2303@cindex Mount flags; noversion 2304Strip the extension @samp{;#} from the version string of files recorded 2305on an ISO-9660 CD-ROM. 2306 2307@item overlay 2308@cindex Mount flags; overlay 2309Overlay this mount on top of an existing mount, if any. 2310 2311@item pgthresh=@var{n} 2312@cindex Mount flags; pgthresh 2313Set the paging threshold to @var{n} kilobytes. 2314 2315@item port=@var{n} 2316@cindex Mount flags; port 2317Set the NFS port to @var{n}. 2318 2319@item posix 2320@cindex Mount flags; posix 2321Turn on POSIX static pathconf for mounts. 2322 2323@item proto=@var{s} 2324@cindex Mount flags; proto 2325Use transport protocol @var{s} for NFS (can be @code{"tcp"} or @code{"udp"}). 2326 2327@item quota 2328@cindex Mount flags; quota 2329Enable quota checking on this mount. 2330 2331@item rdonly 2332@cindex Mount flags; rdonly 2333@itemx ro 2334@cindex Mount flags; ro 2335Mount this filesystem readonly. 2336 2337@item resvport 2338@cindex Mount flags; resvport 2339Use a reserved port (smaller than 1024) for remote NFS mounts. Most 2340systems assume that, but some allow for mounts to occur on non-reserved 2341ports. This causes problems when such a system tries to NFS mount one 2342that requires reserved ports. It is recommended that this option always 2343be on. 2344 2345@item retrans=@i{n} 2346@cindex Mount flags; retrans 2347The number of NFS retransmits made before a user error is generated by a 2348@samp{soft} mounted filesystem, and before a @samp{hard} mounted 2349filesystem reports @samp{NFS server @dfn{yoyo} not responding still 2350trying}. 2351 2352@item retry 2353@cindex Mount flags; retry 2354Set the NFS retry counter. 2355 2356@item rrip 2357@cindex Mount flags; rrip 2358Uses the Rock Ridge Interchange Protocol (RRIP) extensions to ISO-9660. 2359 2360@item rsize=@var{n} 2361@cindex Mount flags; rsize 2362The NFS read packet size. You may need to set this if you are using 2363NFS/UDP through a gateway or a slow link. 2364 2365@item rw 2366@cindex Mount flags; rw 2367Allow reads and writes on this filesystem. 2368 2369@item soft 2370@cindex Mount flags; soft 2371Give up after @dfn{retrans} retransmissions. 2372 2373@item spongy 2374@cindex Mount flags; spongy 2375Like @samp{soft} for status requests, and @samp{hard} for data transfers. 2376 2377@item suid 2378@cindex Mount flags; suid 2379Allow set-uid programs on this mount. 2380 2381@item symttl 2382@cindex Mount flags; symttl 2383Turn of the symbolic link cache time-to-live. 2384 2385@item sync 2386@cindex Mount flags; sync 2387Perform synchronous filesystem operations on this mount. 2388 2389@item tcp 2390@cindex Mount flags; tcp 2391Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not 2392support TCP/IP mounts. 2393 2394@item timeo=@var{n} 2395@cindex Mount flags; timeo 2396The NFS timeout, in tenth-seconds, before a request is retransmitted. 2397 2398@item vers=@var{n} 2399@cindex Mount flags; vers 2400 Use NFS protocol version number @var{n} (can be 2 or 3). 2401 2402@item wsize=@var{n} 2403@cindex Mount flags; wsize 2404The NFS write packet size. You may need to set this if you are using 2405NFS/UDP through a gateway or a slow link. 2406 2407@end table 2408 2409The following options are implemented by @i{Amd}, rather than being 2410passed to the kernel. 2411 2412@table @code 2413 2414@item nounmount 2415@cindex Mount flags; nounmount 2416Configures the mount so that its time-to-live will 2417never expire. This is also the default for some filesystem types. 2418@c 2419@c Implementation broken: 2420 2421@item ping=@var{n} 2422@cindex Mount flags; ping 2423The interval, in seconds, between keep-alive pings. When four 2424consecutive pings have failed the mount point is marked as hung. This 2425interval defaults to 30 seconds. If the ping interval is less than zero, 2426no pings are sent and the host is assumed to be always 2427up. By default, pings are not sent for an NFS/TCP mount. 2428 2429@item retry=@var{n} 2430@cindex Mount flags; retry=@var{n} 2431The number of times to retry the mount system call. 2432 2433@item utimeout=@var{n} 2434@cindex Mount flags; utimeout=@var{n} 2435The interval, in seconds, by which the mount's 2436time-to-live is extended after an unmount attempt 2437has failed. In fact the interval is extended before the unmount is 2438attempted to avoid thrashing. The default value is 120 seconds (two 2439minutes) or as set by the @code{-w} command line option. 2440 2441@end table 2442 2443@node remopts Option, sublink Option, opts Option, Map Options 2444@comment node-name, next, previous, up 2445@subsubsection remopts Option 2446@cindex Setting system mount options for non-local networks 2447@cindex remopts, mount option 2448@cindex Mount option; remopts 2449 2450This option has the same use as @code{$@{opts@}} but applies only when 2451the remote host is on a non-local network. For example, when using NFS 2452across a gateway it is often necessary to use smaller values for the 2453data read and write sizes. This can simply be done by specifying the 2454small values in @var{remopts}. When a non-local host is accessed, the 2455smaller sizes will automatically be used. 2456 2457@i{Amd} determines whether a host is local by examining the network 2458interface configuration at startup. Any interface changes made after 2459@i{Amd} has been started will not be noticed. The likely effect will 2460be that a host may incorrectly be declared non-local. 2461 2462Unless otherwise set, the value of @code{$@{remopts@}} is the same as 2463the value of @code{$@{opts@}}. 2464 2465@node sublink Option, type Option, remopts Option, Map Options 2466@comment node-name, next, previous, up 2467@subsubsection sublink Option 2468@cindex Setting the sublink option 2469@cindex sublink, mount option 2470@cindex Mount option; sublink 2471 2472The subdirectory within the mounted filesystem to which the reference 2473should point. This can be used to prevent duplicate mounts in cases 2474where multiple directories in the same mounted filesystem are used. 2475 2476@node type Option, , sublink Option, Map Options 2477@comment node-name, next, previous, up 2478@subsubsection type Option 2479@cindex Setting the filesystem type option 2480@cindex type, mount option 2481@cindex Mount option; type 2482 2483The filesystem type to be used. @xref{Filesystem Types}, for a full 2484description of each type.@refill 2485 2486@c ################################################################ 2487@node Amd Command Line Options, Filesystem Types, Mount Maps, Top 2488@comment node-name, next, previous, up 2489@chapter @i{Amd} Command Line Options 2490@cindex Command line options, Amd 2491@cindex Amd command line options 2492@cindex Overriding defaults on the command line 2493 2494Many of @i{Amd}'s parameters can be set from the command line. The 2495command line is also used to specify automount points and maps. 2496 2497The general format of a command line is 2498 2499@example 2500amd [@i{options}] [@{ @i{directory} @i{map-name} [-@i{map-options}] @} ...] 2501@end example 2502 2503For each directory and map-name given or specified in the 2504@file{amd.conf} file, @i{Amd} establishes an automount point. The 2505@dfn{map-options} may be any sequence of options or 2506selectors---@pxref{Location Format}. The @dfn{map-options} apply only 2507to @i{Amd}'s mount point. 2508 2509@samp{type:=toplvl;cache:=mapdefault;fs:=$@{map@}} is the default value for the 2510map options. Default options for a map are read from a special entry in 2511the map whose key is the string @samp{/defaults}. When default options 2512are given they are prepended to any options specified in the mount-map 2513locations as explained in @ref{Map Defaults}. 2514 2515The @dfn{options} are any combination of those listed below. 2516 2517Once the command line has been parsed, the automount points are mounted. 2518The mount points are created if they do not already exist, in which case they 2519will be removed when @i{Amd} exits. 2520Finally, @i{Amd} disassociates itself from its controlling terminal and 2521forks into the background. 2522 2523Note: Even if @i{Amd} has been built with @samp{-DDEBUG} (via 2524@code{configure --enable-debug}), it will still background itself and 2525disassociate itself from the controlling terminal. To use a debugger it 2526is necessary to specify @samp{-D nodaemon} on the command line. 2527However, even with all of this, mounts and unmounts are performed in the 2528background, and @i{Amd} will always fork before doing them. Therefore, 2529debugging what happens closely during un/mounts is more challenging. 2530 2531@emph{All} of @i{Amd}'s command options (save @code{-F} and @code{-T}) 2532can be specified in the @file{amd.conf} file. @xref{Amd Configuration 2533File}. If @i{Amd} is invoked without any command line options, it will 2534default to using the configuration file @file{/etc/amd.conf}, if one 2535exists. 2536 2537@menu 2538* -a Option:: Automount directory. 2539* -c Option:: Cache timeout interval. 2540* -d Option:: Domain name. 2541* -k Option:: Kernel architecture. 2542* -l Option:: Log file. 2543* -n Option:: Hostname normalization. 2544* -o Option:: Operating system version. 2545* -p Option:: Output process id. 2546* -r Option:: Restart existing mounts. 2547* -t Option:: Kernel RPC timeout. 2548* -v Option:: Version information. 2549* -w Option:: Wait interval after failed unmount. 2550* -x Option:: Log options. 2551* -y Option:: NIS domain. 2552* -C-Option:: Cluster name. 2553* -D-Option:: Debug flags. 2554* -F Option:: Amd configuration file. 2555* -H Option:: Show brief help. 2556* -O-Option:: Operating system name. 2557* -S Option:: Lock executable pages in memory. 2558* -T-Option:: Set tag for configuration file. 2559@end menu 2560 2561@c ---------------------------------------------------------------- 2562@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options 2563@comment node-name, next, previous, up 2564@section @code{-a} @var{directory} 2565@cindex Automount directory 2566@cindex Setting the default mount directory 2567 2568Specifies the default mount directory. This option changes the variable 2569@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, 2570some sites prefer @file{/amd} or @file{/n}. 2571 2572@example 2573amd -a /amd ... 2574@end example 2575 2576@c ---------------------------------------------------------------- 2577@node -c Option, -d Option, -a Option, Amd Command Line Options 2578@comment node-name, next, previous, up 2579@section @code{-c} @var{cache-interval} 2580@cindex Cache interval 2581@cindex Interval before a filesystem times out 2582@cindex Setting the interval before a filesystem times out 2583@cindex Changing the interval before a filesystem times out 2584 2585Selects the period, in seconds, for which a name is cached by @i{Amd}. 2586If no reference is made to the volume in this period, @i{Amd} discards 2587the volume name to filesystem mapping. 2588 2589Once the last reference to a filesystem has been removed, @i{Amd} 2590attempts to unmount the filesystem. If the unmount fails the interval 2591is extended by a further period as specified by the @samp{-w} command 2592line option or by the @samp{utimeout} mount option. 2593 2594The default @dfn{cache-interval} is 300 seconds (five minutes). 2595 2596@c ---------------------------------------------------------------- 2597@node -d Option, -k Option, -c Option, Amd Command Line Options 2598@comment node-name, next, previous, up 2599@section @code{-d} @var{domain} 2600@cindex Domain name 2601@cindex Setting the local domain name 2602@cindex Overriding the local domain name 2603 2604Specifies the host's domain. This sets the internal variable 2605@code{$@{domain@}} and affects the @code{$@{hostd@}} variable. 2606 2607If this option is not specified and the hostname already contains the 2608local domain then that is used, otherwise the default value of 2609@code{$@{domain@}} is @samp{unknown.domain}. 2610 2611For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could 2612be started as follows: 2613 2614@example 2615amd -d doc.ic.ac.uk ... 2616@end example 2617 2618@c ---------------------------------------------------------------- 2619@node -k Option, -l Option, -d Option, Amd Command Line Options 2620@comment node-name, next, previous, up 2621@section @code{-k} @var{kernel-architecture} 2622@cindex Setting the Kernel architecture 2623 2624Specifies the kernel architecture of the system. This is usually the 2625output of @samp{uname -m} (the ``machine'' value gotten from 2626@b{uname}(2)). If the @b{uname}(2) system call is not available, the 2627value of @code{$@{karch@}} defaults to that of @code{$@{arch@}}. 2628 2629The only effect of this option is to set the variable @code{$@{karch@}}. 2630 2631This option would be used as follows: 2632 2633@example 2634amd -k `arch -k` ... 2635@end example 2636 2637@c ---------------------------------------------------------------- 2638@node -l Option, -n Option, -k Option, Amd Command Line Options 2639@comment node-name, next, previous, up 2640@section @code{-l} @var{log-option} 2641@cindex Log filename 2642@cindex Setting the log file 2643@cindex Using syslog to log errors 2644@cindex syslog 2645 2646Selects the form of logging to be made. Several special @dfn{log-options} 2647are recognized. 2648 2649@enumerate 2650@item 2651If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the 2652@b{syslog}(3) mechanism. If your system supports syslog facilities, then 2653the default facility used is @samp{LOG_DAEMON}. 2654 2655@item 2656@cindex syslog facility; specifying an alternate 2657When using syslog, if you wish to change the facility, append its name 2658to the log option name, delimited by a single colon. For example, if 2659@dfn{log-options} is the string @samp{syslog:local7} then @b{Amd} will 2660log messages via @b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If 2661the facility name specified is not recognized, @i{Amd} will default to 2662@samp{LOG_DAEMON}. Note: while you can use any syslog facility 2663available on your system, it is generally a bad idea to use those 2664reserved for other services such as @samp{kern}, @samp{lpr}, 2665@samp{cron}, etc. 2666 2667@item 2668If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use 2669standard error, which is also the default target for log messages. To 2670implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} 2671driver. 2672@end enumerate 2673 2674Any other string is taken as a filename to use for logging. Log 2675messages are appended to the file if it already exists, otherwise a new 2676file is created. The file is opened once and then held open, rather 2677than being re-opened for each message. 2678 2679Normally, when long-running daemons hold an open file descriptor on a 2680log file, it is impossible to ``rotate'' the log file and compress older 2681logs on a daily basis. The daemon needs to be told to discard (via 2682@b{close}(2)) its file handle, and re-open the log file. This is done 2683using @code{amq -l} @i{log-option}. @xref{Amq -l option}. 2684 2685If the @samp{syslog} option is specified but the system does not support 2686syslog or if the named file cannot be opened or created, @i{Amd} will 2687use standard error. Error messages generated before @i{Amd} has 2688finished parsing the command line are printed on standard error. 2689 2690Since @i{Amd} tends to generate a lot of logging information (especially 2691if debugging was turned on), and due to it being an important program 2692running on the system, it is usually best to log to a separate disk 2693file. In that case @i{Amd} would be started as follows: 2694 2695@example 2696amd -l /var/log/amd ... 2697@end example 2698 2699@c ---------------------------------------------------------------- 2700@node -n Option, -o Option, -l Option, Amd Command Line Options 2701@comment node-name, next, previous, up 2702@section @code{-n} 2703@cindex Hostname normalization 2704@cindex Aliased hostnames 2705@cindex Resolving aliased hostnames 2706@cindex Normalizing hostnames 2707 2708Normalizes the remote hostname before using it. Normalization is done 2709by replacing the value of @code{$@{rhost@}} with the (generally fully 2710qualified) primary name returned by a hostname lookup. 2711 2712This option should be used if several names are used to refer to a 2713single host in a mount map. 2714 2715@c ---------------------------------------------------------------- 2716@node -o Option, -p Option, -n Option, Amd Command Line Options 2717@comment node-name, next, previous, up 2718@section @code{-o} @var{op-sys-ver} 2719@cindex Operating System version 2720@cindex Setting the Operating System version 2721 2722Override the compiled-in version number of the operating system, with 2723@var{op-sys-ver}. Useful when the built-in version is not desired for 2724backward compatibility reasons. For example, if the built-in version is 2725@samp{2.5.1}, you can override it to @samp{5.5.1}, and use older maps 2726that were written with the latter in mind. 2727 2728@c ---------------------------------------------------------------- 2729@node -p Option, -r Option, -o Option, Amd Command Line Options 2730@comment node-name, next, previous, up 2731@section @code{-p} 2732@cindex Process id 2733@cindex Displaying the process id 2734@cindex process id of Amd daemon 2735@cindex pid file, creating with -p option 2736@cindex Creating a pid file 2737 2738Causes @i{Amd}'s process id to be printed on standard output. 2739This can be redirected to a suitable file for use with kill: 2740 2741@example 2742amd -p > /var/run/amd.pid ... 2743@end example 2744 2745This option only has an affect if @i{Amd} is running in daemon mode. 2746If @i{Amd} is started with the @code{-D nodaemon} debug flag, this 2747option is ignored. 2748 2749@c ---------------------------------------------------------------- 2750@node -r Option, -t Option, -p Option, Amd Command Line Options 2751@comment node-name, next, previous, up 2752@section @code{-r} 2753@cindex Restarting existing mounts 2754@cindex Picking up existing mounts 2755 2756Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). 2757@c @dfn{This option will be made the default in the next release.} 2758 2759@c ---------------------------------------------------------------- 2760@node -t Option, -v Option, -r Option, Amd Command Line Options 2761@comment node-name, next, previous, up 2762@section @code{-t} @var{timeout.retransmit} 2763@cindex Setting Amd's RPC parameters 2764 2765Specifies the RPC @dfn{timeout} and @dfn{retransmit} intervals used by 2766the kernel to communicate to @i{Amd}. These are used to set the 2767@samp{timeo} and @samp{retrans} mount options. 2768 2769@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 2770retries. The value of this parameter changes the retry interval. Too 2771long an interval gives poor interactive response, too short an interval 2772causes excessive retries. 2773 2774@c ---------------------------------------------------------------- 2775@node -v Option, -w Option, -t Option, Amd Command Line Options 2776@comment node-name, next, previous, up 2777@section @code{-v} 2778@cindex Version information 2779@cindex Discovering version information 2780@cindex How to discover your version of Amd 2781 2782Print version information on standard error and then exit. The output 2783is of the form: 2784 2785@example 2786Copyright (c) 1997-1999 Erez Zadok 2787Copyright (c) 1990 Jan-Simon Pendry 2788Copyright (c) 1990 Imperial College of Science, Technology & Medicine 2789Copyright (c) 1990 The Regents of the University of California. 2790am-utils version 6.0a15 (build 61). 2791Built by ezk@@cs.columbia.edu on date Wed Oct 22 15:21:03 EDT 1997. 2792cpu=sparc (big-endian), arch=sun4, karch=sun4u. 2793full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun. 2794Map support for: root, passwd, union, nisplus, nis, ndbm, file, error. 2795AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit, 2796 ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error. 2797FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, ufs. 2798Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13). 2799Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14). 2800Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16). 2801@end example 2802 2803The information includes the version number, number of times @i{Amd} was 2804compiled on the local system, release date and name of the release. 2805Following come the cpu type, byte ordering, and the architecture and 2806kernel architecture as @code{$@{arch@}} and @code{$@{karch@}}, 2807respectively. The next line lists the full name of the system, the 2808variables @code{$@{os@}} and @code{$@{osver@}}, and the vendor's 2809name. @xref{Supported Platforms}. 2810 2811Then come a list of map types supported, filesystems internally 2812supported by @i{Amd} (AMFS), and generic filesystems available (FS). 2813Finally all known networks (if any) of this host are listed by name 2814and number. They are available via the variables 2815@code{$@{wire@}} or @code{$@{network@}}, and 2816@code{$@{netnumber@}} (@pxref{Selectors}) or the @samp{in_network} 2817selector function (@pxref{in_network Selector Function}). 2818 2819@c ---------------------------------------------------------------- 2820@node -w Option, -x Option, -v Option, Amd Command Line Options 2821@comment node-name, next, previous, up 2822@section @code{-w} @var{wait-timeout} 2823@cindex Setting the interval between unmount attempts 2824@cindex unmount attempt backoff interval 2825 2826Selects the interval in seconds between unmount attempts after the 2827initial time-to-live has expired. 2828 2829This defaults to 120 seconds (two minutes). 2830 2831@c ---------------------------------------------------------------- 2832@node -x Option, -y Option, -w Option, Amd Command Line Options 2833@comment node-name, next, previous, up 2834@section @code{-x} @var{opts} 2835@cindex Log message selection 2836@cindex Selecting specific log messages 2837@cindex How to select log messages 2838@cindex syslog priorities 2839 2840Specifies the type and verbosity of log messages. @dfn{opts} is 2841a comma separated list selected from the following options: 2842 2843@table @code 2844@item fatal 2845Fatal errors 2846@item error 2847Non-fatal errors 2848@item user 2849Non-fatal user errors 2850@item warn 2851Recoverable errors 2852@item warning 2853Alias for @code{warn} 2854@item info 2855Information messages 2856@item map 2857Mount map usage 2858@item stats 2859Additional statistics 2860@item all 2861All of the above 2862@end table 2863 2864Initially a set of default logging flags is enabled. This is as if 2865@samp{-x all,nomap,nostats} had been selected. The command line is 2866parsed and logging is controlled by the @code{-x} option. The very first 2867set of logging flags is saved and can not be subsequently disabled using 2868@i{Amq}. This default set of options is useful for general production 2869use.@refill 2870 2871The @samp{info} messages include details of what is mounted and 2872unmounted and when filesystems have timed out. If you want to have the 2873default set of messages without the @samp{info} messages then you simply 2874need @samp{-x noinfo}. The messages given by @samp{user} relate to 2875errors in the mount maps, so these are useful when new maps are 2876installed. The following table lists the syslog priorities used for each 2877of the message types.@refill 2878 2879@table @code 2880@item fatal 2881@samp{LOG_CRIT} 2882@item error 2883@samp{LOG_ERR} 2884@item user 2885@samp{LOG_WARNING} 2886@item warning 2887@samp{LOG_WARNING} 2888@item info 2889@samp{LOG_INFO} 2890@item debug 2891@samp{LOG_DEBUG} 2892@item map 2893@samp{LOG_DEBUG} 2894@item stats 2895@samp{LOG_INFO} 2896@end table 2897 2898 2899The options can be prefixed by the string @samp{no} to indicate 2900that this option should be turned off. For example, to obtain all 2901but @samp{info} messages the option @samp{-x all,noinfo} would be used. 2902 2903If @i{Amd} was built with debugging enabled the @code{debug} option is 2904automatically enabled regardless of the command line options. 2905 2906@c ---------------------------------------------------------------- 2907@node -y Option, -C-Option, -x Option, Amd Command Line Options 2908@comment node-name, next, previous, up 2909@section @code{-y} @var{NIS-domain} 2910@cindex NIS (YP) domain name 2911@cindex Overriding the NIS (YP) domain name 2912@cindex Setting the NIS (YP) domain name 2913@cindex YP domain name 2914 2915Selects an alternate NIS domain. This is useful for debugging and 2916cross-domain shared mounting. If this flag is specified, @i{Amd} 2917immediately attempts to bind to a server for this domain. 2918@c @i{Amd} refers to NIS maps when it starts, unless the @code{-m} option 2919@c is specified, and whenever required in a mount map. 2920 2921@c ---------------------------------------------------------------- 2922@node -C-Option, -D-Option, -y Option, Amd Command Line Options 2923@comment node-name, next, previous, up 2924@section @code{-C} @var{cluster-name} 2925@cindex Cluster names 2926@cindex Setting the cluster name 2927 2928Specifies the name of the cluster of which the local machine is a member. 2929The only effect is to set the variable @code{$@{cluster@}}. 2930The @dfn{cluster-name} is will usually obtained by running another command which uses 2931a database to map the local hostname into a cluster name. 2932@code{$@{cluster@}} can then be used as a selector to restrict mounting of 2933replicated data. 2934If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. 2935This would be used as follows: 2936 2937@example 2938amd -C `clustername` ... 2939@end example 2940 2941@c ---------------------------------------------------------------- 2942@node -D-Option, -F Option, -C-Option, Amd Command Line Options 2943@comment node-name, next, previous, up 2944@section @code{-D} @var{opts} 2945@cindex Debug options 2946@cindex Setting debug flags 2947 2948Controls the verbosity and coverage of the debugging trace; @dfn{opts} 2949is a comma separated list of debugging options. The @code{-D} option is 2950only available if @i{Amd} was compiled with @samp{-DDEBUG}, or 2951configured with @code{configure --enable-debug}. The memory debugging 2952facilities (@samp{mem}) are only available if @i{Amd} was compiled with 2953@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}), or configured with 2954@code{configure --enable-debug=mem}. 2955 2956The most common options to use are @samp{-D trace} and @samp{-D test} 2957(which turns on all the useful debug options). As usual, every option 2958can be prefixed with @samp{no} to turn it off. 2959 2960@table @code 2961@item all 2962all options 2963@item amq 2964register for amq 2965@item daemon 2966enter daemon mode 2967@item fork 2968fork server 2969@item full 2970program trace 2971@item info 2972@cindex debugging hesiod resolver service 2973@cindex Hesiod: turning on RES_DEBUG 2974info service specific debugging (hesiod, nis, etc.) In the case of 2975hesiod maps, turns on the hesiod RES_DEBUG internal debugging option. 2976@item mem 2977trace memory allocations 2978@item mtab 2979use local @file{./mtab} file 2980@item str 2981debug string munging 2982@item test 2983full debug but no daemon 2984@item trace 2985protocol trace 2986@end table 2987 2988You may also refer to the program source for a more detailed explanation 2989of the available options. 2990 2991@c ---------------------------------------------------------------- 2992@node -F Option, -H Option, -D-Option, Amd Command Line Options 2993@comment node-name, next, previous, up 2994@section @code{-F} @var{conf-file} 2995@cindex Amd configuration file; specifying name 2996@cindex Amd configuration file 2997@cindex amd.conf file 2998 2999Specify an @i{Amd} configuration file @var{conf-file} to use. For a 3000description of the format and syntax, @pxref{Amd Configuration File}. 3001This configuration file is used to specify any options in lieu of typing 3002many of them on the command line. The @file{amd.conf} file includes 3003directives for every command line option @i{Amd} has, and many more that 3004are only available via the configuration file facility. The 3005configuration file specified by this option is processed after all other 3006options had been processed, regardless of the actual location of this 3007option on the command line. 3008 3009@c ---------------------------------------------------------------- 3010@node -H Option, -O-Option, -F Option, Amd Command Line Options 3011@comment node-name, next, previous, up 3012@section @code{-H} 3013@cindex Displaying brief help 3014@cindex Help; showing from Amd 3015 3016Print a brief help and usage string. 3017 3018@c ---------------------------------------------------------------- 3019@node -O-Option, -S Option, -H Option, Amd Command Line Options 3020@comment node-name, next, previous, up 3021@section @code{-O} @var{op-sys-name} 3022@cindex Operating System name 3023@cindex Setting the Operating System name 3024 3025Override the compiled-in name of the operating system, with 3026@var{op-sys-name}. Useful when the built-in name is not desired for 3027backward compatibility reasons. For example, if the build in name is 3028@samp{sunos5}, you can override it to the old name @samp{sos5}, and use 3029older maps which were written with the latter in mind. 3030 3031@c ---------------------------------------------------------------- 3032@node -S Option, -T-Option, -O-Option, Amd Command Line Options 3033@comment node-name, next, previous, up 3034@section @code{-S} 3035@cindex plock; using 3036@cindex locking executable pages in memory 3037 3038Do @emph{not} lock the running executable pages of @i{Amd} into memory. 3039To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 3040call lock the @i{Amd} process into memory. This way there is less 3041chance the operating system will schedule, page out, and swap the 3042@i{Amd} process as needed. This tends to improve @i{Amd}'s performance, 3043at the cost of reserving the memory used by the @i{Amd} process (making 3044it unavailable for other processes). If this behavior is not desired, 3045use the @code{-S} option. 3046 3047@c ---------------------------------------------------------------- 3048@node -T-Option, , -S Option, Amd Command Line Options 3049@comment node-name, next, previous, up 3050@section @code{-T} @var{tag} 3051@cindex Tags for Amd configuration file 3052@cindex Configuration file; tags 3053 3054Specify a tag to use with @file{amd.conf}. All map entries tagged with 3055@var{tag} will be processed. Map entries that are not tagged are always 3056processed. Map entries that are tagged with a tag other than @var{tag} 3057will not be processed. 3058 3059@c ################################################################ 3060@node Filesystem Types, Amd Configuration File, Amd Command Line Options, Top 3061@comment node-name, next, previous, up 3062@chapter Filesystem Types 3063@cindex Filesystem types 3064@cindex Mount types 3065@cindex Types of filesystem 3066 3067To mount a volume, @i{Amd} must be told the type of filesystem to be 3068used. Each filesystem type typically requires additional information 3069such as the fileserver name for NFS. 3070 3071From the point of view of @i{Amd}, a @dfn{filesystem} is anything that 3072can resolve an incoming name lookup. An important feature is support 3073for multiple filesystem types. Some of these filesystems are 3074implemented in the local kernel and some on remote fileservers, whilst 3075the others are implemented internally by @i{Amd}.@refill 3076 3077The two common filesystem types are UFS and NFS. Four other user 3078accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and 3079@samp{direct}) are also implemented internally by @i{Amd} and these are 3080described below. There are two additional filesystem types internal to 3081@i{Amd} which are not directly accessible to the user (@samp{inherit} 3082and @samp{error}). Their use is described since they may still have an 3083effect visible to the user.@refill 3084 3085@menu 3086* Network Filesystem:: A single NFS filesystem. 3087* Network Host Filesystem:: NFS mount a host's entire export tree. 3088* Network Filesystem Group:: An atomic group of NFS filesystems. 3089* Unix Filesystem:: Native disk filesystem. 3090* Caching Filesystem:: Caching from remote server filesystem. 3091* CD-ROM Filesystem:: ISO9660 CD ROM. 3092* Loopback Filesystem:: Local loopback-mount filesystem. 3093* Memory/RAM Filesystem:: A memory or RAM-based filesystem. 3094* Null Filesystem:: 4.4BSD's loopback-mount filesystem. 3095* Floppy Filesystem:: MS-DOS Floppy filesystem. 3096* Translucent Filesystem:: The directory merging filesystem. 3097* Shared Memory+Swap Filesystem:: Sun's tmpfs filesystem. 3098* User ID Mapping Filesystem:: 4.4BSD's umapfs filesystem. 3099* Program Filesystem:: Generic Program mounts. 3100* Symbolic Link Filesystem:: Local link. 3101* Symbolic Link Filesystem II:: Local link referencing existing filesystem. 3102* NFS-Link Filesystem:: Link if path exists, NFS otherwise. 3103* Automount Filesystem:: 3104* Direct Automount Filesystem:: 3105* Union Filesystem:: 3106* Error Filesystem:: 3107* Top-level Filesystem:: 3108* Autofs Filesystem:: Sun's kernel-based automounter filesystem. 3109* Root Filesystem:: 3110* Inheritance Filesystem:: 3111@end menu 3112 3113@c ---------------------------------------------------------------- 3114@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types 3115@comment node-name, next, previous, up 3116@section Network Filesystem (@samp{nfs}) 3117@cindex NFS 3118@cindex Mounting an NFS filesystem 3119@cindex How to mount and NFS filesystem 3120@cindex nfs, filesystem type 3121@cindex Filesystem type; nfs 3122 3123The @dfn{nfs} (@samp{type:=nfs}) filesystem type provides access to Sun's NFS. 3124 3125@noindent 3126The following options must be specified: 3127 3128@table @code 3129@cindex rhost, mount option 3130@cindex Mount option; rhost 3131@item rhost 3132the remote fileserver. This must be an entry in the hosts database. IP 3133addresses are not accepted. The default value is taken 3134from the local host name (@code{$@{host@}}) if no other value is 3135specified. 3136 3137@cindex rfs, mount option 3138@cindex Mount option; rfs 3139@item rfs 3140the remote filesystem. 3141If no value is specified for this option, an internal default of 3142@code{$@{path@}} is used. 3143@end table 3144 3145NFS mounts require a two stage process. First, the @dfn{file handle} of 3146the remote file system must be obtained from the server. Then a mount 3147system call must be done on the local system. @i{Amd} keeps a cache 3148of file handles for remote file systems. The cache entries have a 3149lifetime of a few minutes. 3150 3151If a required file handle is not in the cache, @i{Amd} sends a request 3152to the remote server to obtain it. @i{Amd} @dfn{does not} wait for 3153a response; it notes that one of the locations needs retrying, but 3154continues with any remaining locations. When the file handle becomes 3155available, and assuming none of the other locations was successfully 3156mounted, @i{Amd} will retry the mount. This mechanism allows several 3157NFS filesystems to be mounted in parallel. 3158@c @footnote{The mechanism 3159@c is general, however NFS is the only filesystem 3160@c for which the required hooks have been written.} 3161The first one which responds with a valid file handle will be used. 3162 3163@noindent 3164An NFS entry might be: 3165 3166@example 3167jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp 3168@end example 3169 3170The mount system call and any unmount attempts are always done 3171in a new task to avoid the possibility of blocking @i{Amd}. 3172 3173@c ---------------------------------------------------------------- 3174@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types 3175@comment node-name, next, previous, up 3176@section Network Host Filesystem (@samp{host}) 3177@cindex Network host filesystem 3178@cindex Mounting entire export trees 3179@cindex How to mount all NFS exported filesystems 3180@cindex host, filesystem type 3181@cindex Filesystem type; host 3182 3183@c NOTE: the current implementation of the @dfn{host} filesystem type 3184@c sometimes fails to maintain a consistent view of the remote mount tree. 3185@c This happens when the mount times out and only some of the remote mounts 3186@c are successfully unmounted. To prevent this from occurring, use the 3187@c @samp{nounmount} mount option. 3188 3189The @dfn{host} (@samp{type:=host}) filesystem allows access to the entire export tree of an 3190NFS server. The implementation is layered above the @samp{nfs} 3191implementation so keep-alives work in the same way. The only option 3192which needs to be specified is @samp{rhost} which is the name of the 3193fileserver to mount. 3194 3195The @samp{host} filesystem type works by querying the mount daemon on 3196the given fileserver to obtain its export list. @i{Amd} then obtains 3197filehandles for each of the exported filesystems. Any errors at this 3198stage cause that particular filesystem to be ignored. Finally each 3199filesystem is mounted. Again, errors are logged but ignored. One 3200common reason for mounts to fail is that the mount point does not exist. 3201Although @i{Amd} attempts to automatically create the mount point, it 3202may be on a remote filesystem to which @i{Amd} does not have write 3203permission. 3204 3205When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} 3206remounts any filesystems which had successfully been unmounted. To do 3207this @i{Amd} queries the mount daemon again and obtains a fresh copy of 3208the export list. @i{Amd} then tries to mount any exported filesystems 3209which are not currently mounted. 3210 3211Sun's automounter provides a special @samp{-hosts} map. To achieve the 3212same effect with @i{Amd} requires two steps. First a mount map must 3213be created as follows: 3214 3215@example 3216* type:=host;rhost:=$@{key@};fs:=$@{autodir@}/$@{rhost@}/root 3217@end example 3218 3219@noindent 3220and then start @i{Amd} with the following command 3221 3222@example 3223amd /net net.map 3224@end example 3225 3226@noindent 3227where @samp{net.map} is the name of map described above. Note that the 3228value of @code{$@{fs@}} is overridden in the map. This is done to avoid 3229a clash between the mount tree and any other filesystem already mounted 3230from the same fileserver. 3231 3232If different mount options are needed for different hosts then 3233additional entries can be added to the map, for example 3234 3235@example 3236host2 opts:=ro,nosuid,soft 3237@end example 3238 3239@noindent 3240would soft mount @samp{host2} read-only. 3241 3242@c ---------------------------------------------------------------- 3243@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types 3244@comment node-name, next, previous, up 3245@section Network Filesystem Group (@samp{nfsx}) 3246@cindex Network filesystem group 3247@cindex Atomic NFS mounts 3248@cindex Mounting an atomic group of NFS filesystems 3249@cindex How to mount an atomic group of NFS filesystems 3250@cindex nfsx, filesystem type 3251@cindex Filesystem type; nfsx 3252 3253The @dfn{nfsx} (@samp{type:=nfsx}) filesystem allows a group of filesystems to be mounted 3254from a single NFS server. The implementation is layered above the 3255@samp{nfs} implementation so keep-alives work in the same way. 3256 3257The options are the same as for the @samp{nfs} filesystem with one 3258difference. 3259 3260@noindent 3261The following options must be specified: 3262 3263@table @code 3264@item rhost 3265the remote fileserver. This must be an entry in the hosts database. IP 3266addresses are not accepted. The default value is taken from the local 3267host name (@code{$@{host@}}) if no other value is specified. 3268 3269@item rfs 3270as a list of filesystems to mount. The list is in the form of a comma 3271separated strings. 3272@end table 3273 3274@noindent 3275For example: 3276 3277@example 3278pub type:=nfsx;rhost:=gould;\ 3279 rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root 3280@end example 3281 3282The first string defines the root of the tree, and is applied as a 3283prefix to the remaining members of the list which define the individual 3284filesystems. The first string is @emph{not} used as a filesystem name. 3285A parallel operation is used to determine the local mount points to 3286ensure a consistent layout of a tree of mounts. 3287 3288Here, the @emph{three} filesystems, @samp{/public}, 3289@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill 3290 3291A local mount point, @code{$@{fs@}}, @emph{must} be specified. The 3292default local mount point will not work correctly in the general case. 3293A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill 3294 3295@c ---------------------------------------------------------------- 3296@node Unix Filesystem, Caching Filesystem, Network Filesystem Group, Filesystem Types 3297@comment node-name, next, previous, up 3298@section Unix Filesystem (@samp{ufs}, @samp{xfs}, or @samp{efs}) 3299@cindex Unix filesystem 3300@cindex UFS 3301@cindex XFS 3302@cindex EFS 3303@cindex Mounting a UFS filesystem 3304@cindex Mounting a local disk 3305@cindex How to mount a UFS filesystems 3306@cindex How to mount a local disk 3307@cindex Disk filesystems 3308@cindex ufs, filesystem type 3309@cindex Filesystem type; ufs 3310@cindex xfs, filesystem type 3311@cindex Filesystem type; xfs 3312@cindex efs, filesystem type 3313@cindex Filesystem type; efs 3314 3315The @dfn{ufs} (@samp{type:=ufs}) filesystem type provides access to the system's standard 3316disk filesystem---usually a derivative of the Berkeley Fast Filesystem. 3317 3318@noindent 3319The following option must be specified: 3320 3321@table @code 3322@cindex dev, mount option 3323@cindex Mount option; dev 3324@item dev 3325the block special device to be mounted. 3326@end table 3327 3328A UFS entry might be: 3329 3330@example 3331jsp host==charm;type:=ufs;dev:=/dev/sd0d;sublink:=jsp 3332@end example 3333 3334UFS is the default Unix disk-based file system, which Am-utils picks up 3335during the autoconfiguration phase. Some systems have more than one 3336type, such as IRIX, that comes with EFS (Extent File System) and XFS 3337(Extended File System). In those cases, you may explicitly set the file 3338system type, by using entries such: 3339 3340@example 3341ez1 type:=efs;dev:=/dev/xd0a 3342ez2 type:=xfs;dev:=/dev/sd3c 3343@end example 3344 3345@c ---------------------------------------------------------------- 3346@node Caching Filesystem, CD-ROM Filesystem, Unix Filesystem, Filesystem Types 3347@comment node-name, next, previous, up 3348@section Caching Filesystem (@samp{cachefs}) 3349@cindex Caching Filesystem 3350@cindex cachefs, filesystem type 3351@cindex Filesystem type; cachefs 3352 3353The @dfn{cachefs} (@samp{type:=cachefs}) filesystem caches files from 3354one location onto another, presumably providing faster access. It is 3355particularly useful to cache from a larger and remote (slower) NFS 3356partition to a smaller and local (faster) UFS directory. 3357 3358@noindent 3359The following options must be specified: 3360 3361@table @code 3362@cindex cachedir, mount option 3363@cindex Mount option; cachedir 3364@item cachedir 3365the directory where the cache is stored. 3366@item rfs 3367the path name to the ``back file system'' to be cached from. 3368@item fs 3369the ``front file system'' mount point to the cached files, where @i{Amd} 3370will set a symbolic link pointing to. 3371@end table 3372 3373A CacheFS entry for, say, the @file{/import} @i{Amd} mount point, might 3374be: 3375 3376@example 3377copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt 3378@end example 3379 3380Access to the pathname @file{/import/copt} will follow a symbolic link 3381to @file{/n/import/copt}. The latter is the mount point for a caching 3382file system, that caches from @file{/import/opt} to @file{/cache}. 3383 3384@b{Caveats}: 3385@enumerate 3386@item This file system is currently only implemented for Solaris 2.x! 3387@item Before being used for the first time, the cache directory @i{must} be 3388initialized with @samp{cfsadmin -c @var{cachedir}}. See the manual page for 3389@b{cfsadmin}(1M) for more information. 3390@item The ``back file system'' mounted must be a complete file system, not 3391a subdirectory thereof; otherwise you will get an error ``Invalid Argument''. 3392@item If @i{Amd} aborts abnormally, the state of the cache may be 3393inconsistent, requiring running the command @file{fsck -F cachefs 3394@var{cachedir}}. Otherwise you will get the error ``No Space Left on Device''. 3395@end enumerate 3396 3397@c ---------------------------------------------------------------- 3398@node CD-ROM Filesystem, Loopback Filesystem, Caching Filesystem, Filesystem Types 3399@comment node-name, next, previous, up 3400@section CD-ROM Filesystem (@samp{cdfs}) 3401@cindex CD-ROM Filesystem 3402@cindex cdfs, filesystem type 3403@cindex Filesystem type; cdfs 3404 3405The @dfn{cdfs} (@samp{type:=cdfs}) filesystem mounts a CD-ROM with an 3406ISO9660 format filesystem on it. 3407 3408@noindent 3409The following option must be specified: 3410 3411@table @code 3412@cindex dev, mount option 3413@cindex Mount option; dev 3414@item dev 3415the block special device to be mounted. 3416@end table 3417 3418Some operating systems will fail to mount read-only CDs unless the 3419@samp{ro} option is specified. A cdfs entry might be: 3420 3421@example 3422cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ 3423 os==sunos5;addopts:=ro;type:=cdfs;dev:=/dev/dsk/c0t6d0s2 3424@end example 3425 3426@c ---------------------------------------------------------------- 3427@node Loopback Filesystem, Memory/RAM Filesystem, CD-ROM Filesystem, Filesystem Types 3428@comment node-name, next, previous, up 3429@section Loopback Filesystem (@samp{lofs}) 3430@cindex Loopback Filesystem 3431@cindex lofs, filesystem type 3432@cindex Filesystem type; lofs 3433 3434The @dfn{lofs} (@samp{type:=lofs}) filesystem is also called the 3435loopback filesystem. It mounts a local directory on another, thus 3436providing mount-time binding to another location (unlike symbolic 3437links). 3438 3439The loopback filesystem is particularly useful within the context of a 3440chroot-ed directory (via @b{chroot}(2)), to provide access to 3441directories otherwise inaccessible. 3442 3443@noindent 3444The following option must be specified: 3445 3446@table @code 3447@cindex rfs, mount option 3448@cindex Mount option; rfs 3449@item rfs 3450the pathname to be mounted on top of @code{$@{fs@}}. 3451@end table 3452 3453Usually, the FTP server runs in a chroot-ed environment, for security 3454reasons. In this example, lofs is used to provide a subdirectory within 3455a user's home directory, also available for public ftp. 3456 3457@example 3458lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk 3459@end example 3460 3461@c ---------------------------------------------------------------- 3462@node Memory/RAM Filesystem, Null Filesystem, Loopback Filesystem, Filesystem Types 3463@comment node-name, next, previous, up 3464@section Memory/RAM Filesystem (@samp{mfs}) 3465@cindex Memory/RAM Filesystem 3466@cindex mfs, filesystem type 3467@cindex Filesystem type; mfs 3468 3469The @dfn{mfs} (@samp{type:=mfs}) filesystem is available in 4.4BSD, 3470Linux, and other systems. It creates a filesystem in a portion of the 3471system's memory, thus providing very fast file (volatile) access. 3472 3473XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3474 3475@c ---------------------------------------------------------------- 3476@node Null Filesystem, Floppy Filesystem, Memory/RAM Filesystem, Filesystem Types 3477@comment node-name, next, previous, up 3478@section Null Filesystem (@samp{nullfs}) 3479@cindex Null Filesystem 3480@cindex nullfs, filesystem type 3481@cindex Filesystem type; nullfs 3482 3483The @dfn{nullfs} (@samp{type:=nullfs}) filesystem is available from 4.4BSD, 3484and is very similar to the loopback filesystem, @dfn{lofs}. 3485 3486XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3487 3488@c ---------------------------------------------------------------- 3489@node Floppy Filesystem, Translucent Filesystem, Null Filesystem, Filesystem Types 3490@comment node-name, next, previous, up 3491@section Floppy Filesystem (@samp{pcfs}) 3492@cindex Floppy Filesystem 3493@cindex pcfs, filesystem type 3494@cindex Filesystem type; pcfs 3495 3496The @dfn{pcfs} (@samp{type:=pcfs}) filesystem mounts a floppy previously 3497formatted for the MS-DOS format. 3498 3499@noindent 3500The following option must be specified: 3501 3502@table @code 3503@cindex dev, mount option 3504@cindex Mount option; dev 3505@item dev 3506the block special device to be mounted. 3507@end table 3508 3509A pcfs entry might be: 3510 3511@example 3512pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ 3513 os==sunos5;type:=pcfs;dev:=/dev/diskette 3514@end example 3515 3516@c ---------------------------------------------------------------- 3517@node Translucent Filesystem, Shared Memory+Swap Filesystem, Floppy Filesystem, Filesystem Types 3518@comment node-name, next, previous, up 3519@section Translucent Filesystem (@samp{tfs}) 3520@cindex Translucent Filesystem 3521@cindex tfs, filesystem type 3522@cindex Filesystem type; tfs 3523 3524The @dfn{tfs} (@samp{type:=tfs}) filesystem is an older version of the 35254.4BSD @dfn{unionfs}. 3526 3527XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3528 3529@c ---------------------------------------------------------------- 3530@node Shared Memory+Swap Filesystem, User ID Mapping Filesystem, Translucent Filesystem, Filesystem Types 3531@comment node-name, next, previous, up 3532@section Shared Memory+Swap Filesystem (@samp{tmpfs}) 3533@cindex Shared Memory and Swap Filesystem 3534@cindex tmpfs, filesystem type 3535@cindex Filesystem type; tmpfs 3536 3537The @dfn{tmpfs} (@samp{type:=tmpfs}) filesystem shares memory between a 3538the swap device and the rest of the system. It is generally used to 3539provide a fast access @file{/tmp} directory, one that uses memory that 3540is otherwise unused. This filesystem is available in SunOS 4.x and 5.x. 3541 3542XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3543 3544@c ---------------------------------------------------------------- 3545@node User ID Mapping Filesystem, Program Filesystem, Shared Memory+Swap Filesystem, Filesystem Types 3546@comment node-name, next, previous, up 3547@section User ID Mapping Filesystem (@samp{umapfs}) 3548@cindex User ID Mapping Filesystem 3549@cindex umapfs, filesystem type 3550@cindex Filesystem type; umapfs 3551 3552The @dfn{umapfs} (@samp{type:=umapfs}) filesystem maps User IDs of file 3553ownership, and is available from 4.4BSD. 3554 3555XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3556 3557@c ---------------------------------------------------------------- 3558@node Program Filesystem, Symbolic Link Filesystem, User ID Mapping Filesystem, Filesystem Types 3559@comment node-name, next, previous, up 3560@section Program Filesystem (@samp{program}) 3561@cindex Program filesystem 3562@cindex Mount a filesystem under program control 3563@cindex program, filesystem type 3564@cindex Filesystem type; program 3565 3566The @dfn{program} (@samp{type:=program}) filesystem type allows a program to be run whenever a 3567mount or unmount is required. This allows easy addition of support for 3568other filesystem types, such as MIT's Remote Virtual Disk (RVD) 3569which has a programmatic interface via the commands 3570@samp{rvdmount} and @samp{rvdunmount}. 3571 3572@noindent 3573The following options must be specified: 3574 3575@table @code 3576@cindex mount, mount option 3577@cindex Mount option; mount 3578@item mount 3579the program which will perform the mount. 3580 3581@cindex unmount, mount option 3582@cindex Mount option; unmount 3583@item unmount 3584the program which will perform the unmount. 3585@end table 3586 3587The exit code from these two programs is interpreted as a Unix error 3588code. As usual, exit code zero indicates success. To execute the 3589program @i{Amd} splits the string on whitespace to create an array of 3590substrings. Single quotes @samp{'} can be used to quote whitespace 3591if that is required in an argument. There is no way to escape or change 3592the quote character. 3593 3594To run the program @samp{rvdmount} with a host name and filesystem as 3595arguments would be specified by 3596@samp{fs:=$@{autodir@}$@{path@};mount:="/etc/rvdmount rvdmount fserver 3597$@{fs@}"}. 3598 3599The first element in the array is taken as the pathname of the program 3600to execute. The other members of the array form the argument vector to 3601be passed to the program, @dfn{including argument zero}. This means 3602that the split string must have at least two elements. The program is 3603directly executed by @i{Amd}, not via a shell. This means that scripts 3604must begin with a @code{#!} interpreter specification. 3605 3606If a filesystem type is to be heavily used, it may be worthwhile adding 3607a new filesystem type into @i{Amd}, but for most uses the program 3608filesystem should suffice. 3609 3610When the program is run, standard input and standard error are inherited 3611from the current values used by @i{Amd}. Standard output is a 3612duplicate of standard error. The value specified with the @code{-l} 3613command line option has no effect on standard error. 3614 3615@c ---------------------------------------------------------------- 3616@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types 3617@comment node-name, next, previous, up 3618@section Symbolic Link Filesystem (@samp{link}) 3619@cindex Symbolic link filesystem 3620@cindex Referencing part of the local name space 3621@cindex Mounting part of the local name space 3622@cindex How to reference part of the local name space 3623@cindex link, filesystem type 3624@cindex symlink, link filesystem type 3625@cindex Filesystem type; link 3626 3627Each filesystem type creates a symbolic link to point from the volume 3628name to the physical mount point. The @samp{link} filesystem does the 3629same without any other side effects. This allows any part of the 3630machines name space to be accessed via @i{Amd}. 3631 3632One common use for the symlink filesystem is @file{/homes} which can be 3633made to contain an entry for each user which points to their 3634(auto-mounted) home directory. Although this may seem rather expensive, 3635it provides a great deal of administrative flexibility. 3636 3637@noindent 3638The following option must be defined: 3639 3640@table @code 3641@item fs 3642The value of @var{fs} option specifies the destination of the link, as 3643modified by the @var{sublink} option. If @var{sublink} is non-null, it 3644is appended to @code{$@{fs@}}@code{/} and the resulting string is used 3645as the target. 3646@end table 3647 3648The @samp{link} filesystem can be thought of as identical to the 3649@samp{ufs} filesystem but without actually mounting anything. 3650 3651An example entry might be: 3652 3653@example 3654jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp 3655@end example 3656which would return a symbolic link pointing to @file{/home/charm/jsp}. 3657 3658@c ---------------------------------------------------------------- 3659@node Symbolic Link Filesystem II, NFS-Link Filesystem, Symbolic Link Filesystem, Filesystem Types 3660@comment node-name, next, previous, up 3661@section Symbolic Link Filesystem II (@samp{linkx}) 3662@cindex Symbolic link filesystem II 3663@cindex Referencing an existing part of the local name space 3664@cindex Mounting an existing part of the local name space 3665@cindex How to reference an existing part of the local name space 3666@cindex linkx, filesystem type 3667@cindex symlink, linkx filesystem type 3668@cindex Filesystem type; linkx 3669 3670The @dfn{linkx} (@samp{type:=linkx}) filesystem type is identical to @samp{link} with the 3671exception that the target of the link must exist. Existence is checked 3672with the @b{lstat}(2) system call. 3673 3674The @samp{linkx} filesystem type is particularly useful for wildcard map 3675entries. In this case, a list of possible targets can be given and 3676@i{Amd} will choose the first one which exists on the local machine. 3677 3678@c ---------------------------------------------------------------- 3679@node NFS-Link Filesystem, Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types 3680@comment node-name, next, previous, up 3681@section NFS-Link Filesystem (@samp{nfsl}) 3682@cindex NFS-Link filesystem II 3683@cindex Referencing an existing part of the name space if target exists 3684@cindex Mounting a remote part of the name space if target is missing 3685@cindex Symlink if target exists, NFS otherwise 3686@cindex nfsl, filesystem type 3687@cindex symlink, nfsl filesystem type 3688@cindex Filesystem type; nfsl 3689 3690The @dfn{nfsl} (@samp{type:=nfsl}) filesystem type is a combination of two others: 3691@samp{link} and @samp{nfs}. If the local host name is equal to the 3692value of @code{$@{rhost@}}, or if the target pathname listed in 3693@code{$@{fs@}} exists, @samp{nfsl} will behave exactly as 3694@samp{type:=link}, and refer to the target as a symbolic link. If the 3695local host name is not equal to the value of @code{$@{rhost@}}, or if 3696the target of the link does not exist, @i{Amd} will treat it as 3697@samp{type:=nfs}, and will mount a remote pathname for it. 3698 3699The @samp{nfsl} filesystem type is particularly useful as a shorthand 3700for the more cumbersome and yet one of the most popular @i{Amd} 3701entries. For example, you can simplify all map entries that look like: 3702 3703@example 3704zing -fs:=/n/shekel/u/zing \ 3705 host!=shekel;type:=nfs;rhost:=shekel;rfs:=$@{fs@} \ 3706 host==shekel;type:=link 3707@end example 3708 3709or 3710 3711@example 3712zing -fs:=/n/shekel/u/zing \ 3713 exists($@{fs@});type:=link \ 3714 !exists($@{fs@});type:=nfs;rhost:=shekel;rfs:=$@{fs@} 3715@end example 3716 3717into a shorter form 3718 3719@example 3720zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=$@{fs@} 3721@end example 3722 3723Not just does it make the maps smaller and simpler, but it avoids 3724possible mistakes that often happen when forgetting to set up the two 3725entries (one for @samp{type:=nfs} and the other for @samp{type:=link}) 3726necessary to perform transparent mounts of existing or remote mounts. 3727 3728@c ---------------------------------------------------------------- 3729@node Automount Filesystem, Direct Automount Filesystem, NFS-Link Filesystem, Filesystem Types 3730@comment node-name, next, previous, up 3731@section Automount Filesystem (@samp{auto}) 3732@cindex Automount filesystem 3733@cindex Map cache types 3734@cindex Setting map cache parameters 3735@cindex How to set map cache parameters 3736@cindex How to start an indirect automount point 3737@cindex auto, filesystem type 3738@cindex Filesystem type; auto 3739@cindex SIGHUP signal 3740@cindex Map cache synchronizing 3741@cindex Synchronizing the map cache 3742@cindex Map cache options 3743@cindex Regular expressions in maps 3744 3745The @dfn{auto} (@samp{type:=auto}) filesystem type creates a new automount point below an 3746existing automount point. Top-level automount points appear as system 3747mount points. An automount mount point can also appear as a 3748sub-directory of an existing automount point. This allows some 3749additional structure to be added, for example to mimic the mount tree of 3750another machine. 3751 3752The following options may be specified: 3753 3754@table @code 3755@cindex cache, mount option 3756@cindex Mount option; cache 3757@item cache 3758specifies whether the data in this mount-map should be 3759cached. The default value is @samp{none}, in which case 3760no caching is done in order to conserve memory. 3761However, better performance and reliability can be obtained by caching 3762some or all of a mount-map. 3763 3764If the cache option specifies @samp{all}, 3765the entire map is enumerated when the mount point is created. 3766 3767If the cache option specifies @samp{inc}, caching is done incrementally 3768as and when data is required. 3769Some map types do not support cache mode @samp{all}, in which case @samp{inc} 3770is used whenever @samp{all} is requested. 3771 3772Caching can be entirely disabled by using cache mode @samp{none}. 3773 3774If the cache option specifies @samp{regexp} then the entire map will be 3775enumerated and each key will be treated as an egrep-style regular 3776expression. The order in which a cached map is searched does not 3777correspond to the ordering in the source map so the regular expressions 3778should be mutually exclusive to avoid confusion. 3779 3780Each mount map type has a default cache type, usually @samp{inc}, which 3781can be selected by specifying @samp{mapdefault}. 3782 3783The cache mode for a mount map can only be selected on the command line. 3784Starting @i{Amd} with the command: 3785 3786@example 3787amd /homes hesiod.homes -cache:=inc 3788@end example 3789 3790will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name 3791server with local incremental caching of all successfully resolved names. 3792 3793All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} 3794signal and, if cache @samp{all} mode was selected, the cache will be 3795reloaded. This can be used to inform @i{Amd} that a map has been 3796updated. In addition, whenever a cache lookup fails and @i{Amd} needs 3797to examine a map, the map's modify time is examined. If the cache is 3798out of date with respect to the map then it is flushed as if a 3799@samp{SIGHUP} had been received. 3800 3801An additional option (@samp{sync}) may be specified to force @i{Amd} to 3802check the map's modify time whenever a cached entry is being used. For 3803example, an incremental, synchronized cache would be created by the 3804following command: 3805 3806@example 3807amd /homes hesiod.homes -cache:=inc,sync 3808@end example 3809 3810@item fs 3811specifies the name of the mount map to use for the new mount point. 3812 3813Arguably this should have been specified with the @code{$@{rfs@}} option but 3814we are now stuck with it due to historical accident. 3815 3816@c %If the string @samp{.} is used then the same map is used; 3817@c %in addition the lookup prefix is set to the name of the mount point followed 3818@c %by a slash @samp{/}. 3819@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. 3820@c 3821 3822@item pref 3823alters the name that is looked up in the mount map. If 3824@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended to 3825the name requested by the kernel @dfn{before} the map is searched. 3826@end table 3827 3828The server @samp{dylan.doc.ic.ac.uk} has two user disks: 3829@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as 3830@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since 3831@samp{/home} is already an automount point, this naming is achieved with 3832the following map entries:@refill 3833 3834@example 3835dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 3836dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 3837dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 3838@end example 3839 3840@c ---------------------------------------------------------------- 3841@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types 3842@comment node-name, next, previous, up 3843@section Direct Automount Filesystem (@samp{direct}) 3844@cindex Direct automount filesystem 3845@cindex How to start a direct automount point 3846@cindex direct, filesystem type 3847@cindex Filesystem type; direct 3848 3849The @dfn{direct} (@samp{type:=direct}) filesystem is almost identical to the automount 3850filesystem. Instead of appearing to be a directory of mount points, it 3851appears as a symbolic link to a mounted filesystem. The mount is done 3852at the time the link is accessed. @xref{Automount Filesystem}, for a 3853list of required options. 3854 3855Direct automount points are created by specifying the @samp{direct} 3856filesystem type on the command line: 3857 3858@example 3859amd ... /usr/man auto.direct -type:=direct 3860@end example 3861 3862where @samp{auto.direct} would contain an entry such as: 3863 3864@example 3865usr/man -type:=nfs;rfs:=/usr/man \ 3866 rhost:=man-server1 rhost:=man-server2 3867@end example 3868 3869In this example, @samp{man-server1} and @samp{man-server2} are file 3870servers which export copies of the manual pages. Note that the key 3871which is looked up is the name of the automount point without the 3872leading @samp{/}. 3873 3874@c ---------------------------------------------------------------- 3875@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types 3876@comment node-name, next, previous, up 3877@section Union Filesystem (@samp{union}) 3878@cindex Union filesystem 3879@cindex union, filesystem type 3880@cindex Filesystem type; union 3881 3882The @dfn{union} (@samp{type:=union}) filesystem type allows the contents of several 3883directories to be merged and made visible in a single directory. This 3884can be used to overcome one of the major limitations of the Unix mount 3885mechanism which only allows complete directories to be mounted. 3886 3887For example, supposing @file{/tmp} and @file{/var/tmp} were to be merged 3888into a new directory called @file{/mtmp}, with files in @file{/var/tmp} 3889taking precedence. The following command could be used to achieve this 3890effect: 3891 3892@example 3893amd ... /mtmp union:/tmp:/var/tmp -type:=union 3894@end example 3895 3896Currently, the unioned directories must @emph{not} be automounted. That 3897would cause a deadlock. This seriously limits the current usefulness of 3898this filesystem type and the problem will be addressed in a future 3899release of @i{Amd}. 3900 3901Files created in the union directory are actually created in the last 3902named directory. This is done by creating a wildcard entry which points 3903to the correct directory. The wildcard entry is visible if the union 3904directory is listed, so allowing you to see which directory has 3905priority. 3906 3907The files visible in the union directory are computed at the time 3908@i{Amd} is started, and are not kept up-to-date with respect to the 3909underlying directories. Similarly, if a link is removed, for example 3910with the @samp{rm} command, it will be lost forever. 3911 3912@c ---------------------------------------------------------------- 3913@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types 3914@comment node-name, next, previous, up 3915@section Error Filesystem (@samp{error}) 3916@cindex Error filesystem 3917@cindex error, filesystem type 3918@cindex Filesystem type; error 3919 3920The @dfn{error} (@samp{type:=error}) filesystem type is used internally as a catch-all in the 3921case where none of the other filesystems was selected, or some other 3922error occurred. Lookups and mounts always fail with ``No such file or 3923directory''. All other operations trivially succeed. 3924 3925The error filesystem is not directly accessible. 3926 3927@c ---------------------------------------------------------------- 3928@node Top-level Filesystem, Autofs Filesystem, Error Filesystem, Filesystem Types 3929@comment node-name, next, previous, up 3930@section Top-level Filesystem (@samp{toplvl}) 3931@cindex Top level filesystem 3932@cindex toplvl, filesystem type 3933@cindex Filesystem type; toplvl 3934 3935The @dfn{toplvl} (@samp{type:=toplvl}) filesystems is derived from the @samp{auto} filesystem 3936and is used to mount the top-level automount nodes. Requests of this 3937type are automatically generated from the command line arguments and can 3938also be passed in by using the @code{-M} option of the @dfn{Amq} command. 3939That option is insecure, and is unavailable unless am-utils was 3940configured with @samp{--with-amq-mount}. 3941 3942@c ---------------------------------------------------------------- 3943@node Root Filesystem, Inheritance Filesystem, Autofs Filesystem, Filesystem Types 3944@comment node-name, next, previous, up 3945@section Root Filesystem (@samp{root}) 3946@cindex Root filesystem 3947@cindex root, filesystem type 3948@cindex Filesystem type; root 3949 3950The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal 3951placeholder onto which @i{Amd} can pin @samp{toplvl} mounts. Only one 3952node of this type need ever exist and one is created automatically 3953during startup. The effect of having more than one root node is 3954undefined. 3955 3956The root filesystem is not directly accessible. 3957 3958@c ---------------------------------------------------------------- 3959@node Autofs Filesystem, Root Filesystem, Top-level Filesystem, Filesystem Types 3960@comment node-name, next, previous, up 3961@section Autofs Filesystem (@samp{autofs}) 3962@cindex Autofs filesystem 3963@cindex autofs, filesystem type 3964@cindex Filesystem type; autofs 3965 3966The @dfn{autofs} (@samp{type:=autofs}) filesystem uses Sun's kernel-based automounter 3967supporting filesystem for @i{Amd}'s mount points. Hence it is another 3968type of top level filesystem. 3969 3970The autofs filesystem is not directly accessible from @i{Amd} maps, but 3971only from the @file{amd.conf} file (@pxref{mount_type Parameter}). 3972 3973Note that Autofs support is still very early. See the distribution file 3974@file{README.autofs} for detail of what works and what does not. 3975 3976@c ---------------------------------------------------------------- 3977@node Inheritance Filesystem, , Root Filesystem, Filesystem Types 3978@comment node-name, next, previous, up 3979@section Inheritance Filesystem (@samp{inherit}) 3980@cindex Inheritance filesystem 3981@cindex Nodes generated on a restart 3982@cindex inherit, filesystem type 3983@cindex Filesystem type; inherit 3984 3985The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly 3986accessible. Instead, internal mount nodes of this type are 3987automatically generated when @i{Amd} is started with the @code{-r} option. 3988At this time the system mount table is scanned to locate any filesystems 3989which are already mounted. If any reference to these filesystems is 3990made through @i{Amd} then instead of attempting to mount it, @i{Amd} 3991simulates the mount and @dfn{inherits} the filesystem. This allows a 3992new version of @i{Amd} to be installed on a live system simply by 3993killing the old daemon with @samp{SIGTERM} and starting the new one.@refill 3994 3995This filesystem type is not generally visible externally, but it is 3996possible that the output from @samp{amq -m} may list @samp{inherit} as 3997the filesystem type. This happens when an inherit operation cannot 3998be completed for some reason, usually because a fileserver is down. 3999 4000@c ################################################################ 4001@node Amd Configuration File, Run-time Administration, Filesystem Types, Top 4002@comment node-name, next, previous, up 4003@chapter Amd Configuration File 4004@cindex Amd Configuration File 4005@cindex amd.conf 4006 4007The @samp{amd.conf} file is the configuration file for @i{Amd}, as part 4008of the am-utils suite. This file contains runtime configuration 4009information for the @i{Amd} automounter program. 4010 4011@menu 4012* File Format:: 4013* The Global Section:: 4014* Regular Map Sections:: 4015* Common Parameters:: 4016* Global Parameters:: 4017* Regular Map Parameters:: 4018* amd.conf Examples:: 4019@end menu 4020 4021@c ================================================================ 4022@node File Format, The Global Section, Amd Configuration File, Amd Configuration File 4023@comment node-name, next, previous, up 4024@section File Format 4025@cindex amd.conf file format 4026 4027The @samp{amd.conf} file consists of sections and parameters. A section 4028begins with the name of the section in square brackets @samp{[]} and 4029continues until the next section begins or the end of the file is reached. 4030Sections contain parameters of the form @samp{name = value}. 4031 4032The file is line-based --- that is, each newline-terminated line 4033represents either a comment, a section name or a parameter. No 4034line-continuation syntax is available. 4035 4036Section names, parameter names and their values are case sensitive. 4037 4038Only the first equals sign in a parameter is significant. Whitespace 4039before or after the first equals sign is discarded. Leading, trailing 4040and internal whitespace in section and parameter names is irrelevant. 4041Leading and trailing whitespace in a parameter value is discarded. 4042Internal whitespace within a parameter value is not allowed, unless the 4043whole parameter value is quoted with double quotes as in @samp{name = 4044"some value"}. 4045 4046Any line beginning with a pound sign @samp{#} is ignored, as are lines 4047containing only whitespace. 4048 4049The values following the equals sign in parameters are all either a 4050string (no quotes needed if string does not include spaces) or a 4051boolean, which may be given as @samp{yes}/@samp{no}. Case is significant in all 4052values. Some items such as cache timeouts are numeric. 4053 4054@c ================================================================ 4055@node The Global Section, Regular Map Sections, File Format, Amd Configuration File 4056@comment node-name, next, previous, up 4057@section The Global Section 4058@cindex amd.conf global section 4059 4060The global section must be specified as @samp{[global]}. Parameters in 4061this section either apply to @i{Amd} as a whole, or to all other regular map 4062sections which follow. There should be only one global section defined 4063in one configuration file. 4064 4065It is highly recommended that this section be specified first in the 4066configuration file. If it is not, then regular map sections which 4067precede it will not use global values defined later. 4068 4069@c ================================================================ 4070@node Regular Map Sections, Common Parameters, The Global Section, Amd Configuration File 4071@comment node-name, next, previous, up 4072@section Regular Map Sections 4073@cindex amd.conf regular map sections 4074 4075Parameters in regular (non-global) sections apply to a single map entry. 4076For example, if the map section @samp{[/homes]} is defined, then all 4077parameters following it will be applied to the @file{/homes} 4078@i{Amd}-managed mount point. 4079 4080@c ================================================================ 4081@node Common Parameters, Global Parameters, Regular Map Sections, Amd Configuration File 4082@comment node-name, next, previous, up 4083@section Common Parameters 4084@cindex amd.conf common parameters 4085 4086These parameters can be specified either in the global or a map-specific 4087section. Entries specified in a map-specific section override the default 4088value or one defined in the global section. If such a common parameter is 4089specified only in the global section, it is applicable to all regular map 4090sections that follow. 4091 4092@menu 4093* browsable_dirs Parameter:: 4094* map_options Parameter:: 4095* map_type Parameter:: 4096* mount_type Parameter:: 4097* search_path Parameter:: 4098@end menu 4099 4100@c ---------------------------------------------------------------- 4101@node browsable_dirs Parameter, map_options Parameter, Common Parameters, Common Parameters 4102@comment node-name, next, previous, up 4103@subsection @t{browsable_dirs} Parameter 4104@cindex browsable_dirs Parameter 4105 4106(type=string, default=@samp{no}). If @samp{yes}, then @i{Amd}'s top-level 4107mount points will be browsable to @b{readdir}(3) calls. This means you 4108could run for example @b{ls}(1) and see what keys are available to mount 4109in that directory. Not all entries are made visible to @b{readdir}(3): 4110the @samp{/defaults} entry, wildcard entries, and those with a @file{/} 4111in them are not included. If you specify @samp{full} to this option, 4112all but the @samp{/defaults} entry will be visible. Note that if you run 4113a command which will attempt to @b{stat}(2) the entries, such as often 4114done by @samp{ls -l} or @samp{ls -F}, @i{Amd} will attempt to mount 4115@i{every} entry in that map. This is often called a ``mount storm''. 4116 4117@c ---------------------------------------------------------------- 4118@node map_options Parameter, map_type Parameter, browsable_dirs Parameter, Common Parameters 4119@comment node-name, next, previous, up 4120@subsection @t{map_options} Parameter 4121@cindex map_options Parameter 4122 4123(type=string, default no options). This option is the same as 4124specifying map options on the command line to @i{Amd}, such as 4125@samp{cache:=all}. 4126 4127@c ---------------------------------------------------------------- 4128@node map_type Parameter, mount_type Parameter, map_options Parameter, Common Parameters 4129@comment node-name, next, previous, up 4130@subsection @t{map_type} Parameter 4131@cindex map_type Parameter 4132 4133(type=string, default search all map types). If specified, @i{Amd} will 4134initialize the map only for the type given. This is useful to avoid the 4135default map search type used by @i{Amd} which takes longer and can have 4136undesired side-effects such as initializing NIS even if not used. 4137Possible values are 4138 4139@table @samp 4140@item file 4141plain files 4142@item hesiod 4143Hesiod name service from MIT 4144@item ldap 4145Lightweight Directory Access Protocol 4146@item ndbm 4147(New) dbm style hash files 4148@item nis 4149Network Information Services (version 2) 4150@item nisplus 4151Network Information Services Plus (version 3) 4152@item passwd 4153local password files 4154@item union 4155union maps 4156@end table 4157 4158@c ---------------------------------------------------------------- 4159@node mount_type Parameter, search_path Parameter, map_type Parameter, Common Parameters 4160@comment node-name, next, previous, up 4161@subsection @t{mount_type} Parameter 4162@cindex mount_type Parameter 4163 4164(type=string, default=@samp{nfs}). All @i{Amd} mount types default to NFS. 4165That is, @i{Amd} is an NFS server on the map mount points, for the local 4166host it is running on. If @samp{autofs} is specified, @i{Amd} will be 4167an autofs server for those mount points. 4168 4169@c ---------------------------------------------------------------- 4170@node search_path Parameter, , mount_type Parameter, Common Parameters 4171@comment node-name, next, previous, up 4172@subsection @t{search_path} Parameter 4173@cindex search_path Parameter 4174 4175(type=string, default no search path). This provides a 4176(colon-delimited) search path for file maps. Using a search path, 4177sites can allow for local map customizations and overrides, and can 4178distributed maps in several locations as needed. 4179 4180@c ================================================================ 4181@node Global Parameters, Regular Map Parameters, Common Parameters, Amd Configuration File 4182@comment node-name, next, previous, up 4183@section Global Parameters 4184@cindex amd.conf global parameters 4185 4186The following parameters are applicable to the @samp{[global]} section only. 4187 4188@menu 4189* arch Parameter:: 4190* auto_dir Parameter:: 4191* cache_duration Parameter:: 4192* cluster Parameter:: 4193* debug_options Parameter:: 4194* dismount_interval Parameter:: 4195* fully_qualified_hosts Parameter:: 4196* hesiod_base Parameter:: 4197* karch Parameter:: 4198* ldap_base Parameter:: 4199* ldap_cache_maxmem Parameter:: 4200* ldap_cache_seconds Parameter:: 4201* ldap_hostports Parameter:: 4202* local_domain Parameter:: 4203* log_file Parameter:: 4204* log_options Parameter:: 4205* nfs_retransmit_counter Parameter:: 4206* nfs_retry_interval Parameter:: 4207* nis_domain Parameter:: 4208* normalize_hostnames Parameter:: 4209* os Parameter:: 4210* osver Parameter:: 4211* pid_file Parameter:: 4212* plock Parameter:: 4213* portmap_program Parameter:: 4214* print_pid Parameter:: 4215* print_version Parameter:: 4216* restart_mounts Parameter:: 4217* selectors_on_default Parameter:: 4218* show_statfs_entries Parameter:: 4219* unmount_on_exit Parameter:: 4220@end menu 4221 4222@c ---------------------------------------------------------------- 4223@node arch Parameter, auto_dir Parameter, Global Parameters, Global Parameters 4224@comment node-name, next, previous, up 4225@subsection @t{arch} Parameter 4226@cindex arch Parameter 4227 4228(type=string, default to compiled in value). Allows you to override the 4229value of the @i{arch} @i{Amd} variable. 4230 4231@c ---------------------------------------------------------------- 4232@node auto_dir Parameter, cache_duration Parameter, arch Parameter, Global Parameters 4233@comment node-name, next, previous, up 4234@subsection @t{auto_dir} Parameter 4235@cindex auto_dir Parameter 4236 4237(type=string, default=@samp{/a}). Same as the @code{-a} option to @i{Amd}. 4238This sets the private directory where @i{Amd} will create 4239sub-directories for its real mount points. 4240 4241@c ---------------------------------------------------------------- 4242@node cache_duration Parameter, cluster Parameter, auto_dir Parameter, Global Parameters 4243@comment node-name, next, previous, up 4244@subsection @t{cache_duration} Parameter 4245@cindex cache_duration Parameter 4246 4247(type=numeric, default=300). Same as the @code{-c} option to 4248@i{Amd}. Sets the duration in seconds that looked up map entries remain 4249in the cache. 4250 4251@c ---------------------------------------------------------------- 4252@node cluster Parameter, debug_options Parameter, cache_duration Parameter, Global Parameters 4253@comment node-name, next, previous, up 4254@subsection @t{cluster} Parameter 4255@cindex cluster Parameter 4256 4257(type=string, default no cluster). Same as the @code{-C} option to 4258@i{Amd}. Specifies the alternate HP-UX cluster to use. 4259 4260@c ---------------------------------------------------------------- 4261@node debug_options Parameter, dismount_interval Parameter, cluster Parameter, Global Parameters 4262@comment node-name, next, previous, up 4263@subsection @t{debug_options} Parameter 4264@cindex debug_options Parameter 4265 4266(type=string, default no debug options). Same as the @code{-D} 4267option to @i{Amd}. Specify any debugging options for @i{Amd}. Works 4268only if am-utils was configured for debugging using the 4269@code{--enable-debug} option. The @samp{mem} option alone can be turned 4270on via @code{--enable-debug=mem}. Otherwise debugging options are 4271ignored. Options are comma delimited, and can be preceded by the string 4272@samp{no} to negate their meaning. You can get the list of supported 4273debugging options by running @code{amd -v}. Possible values are: 4274 4275@table @samp 4276@item all 4277all options 4278@item amq 4279register for amq 4280@item daemon 4281enter daemon mode 4282@item fork 4283fork server 4284@item full 4285program trace 4286@item mem 4287trace memory allocations 4288@item mtab 4289use local @file{./mtab} file 4290@item str 4291debug string munging 4292@item test 4293full debug but no daemon 4294@item trace 4295protocol trace 4296@end table 4297 4298@c ---------------------------------------------------------------- 4299@node dismount_interval Parameter, fully_qualified_hosts Parameter, debug_options Parameter, Global Parameters 4300@comment node-name, next, previous, up 4301@subsection @t{dismount_interval} Parameter 4302@cindex dismount_interval Parameter 4303 4304(type=numeric, default=120). Same as the @code{-w} option to 4305@i{Amd}. Specify in seconds, the time between attempts to dismount file 4306systems that have exceeded their cached times. 4307 4308@c ---------------------------------------------------------------- 4309@node fully_qualified_hosts Parameter, hesiod_base Parameter, dismount_interval Parameter, Global Parameters 4310@comment node-name, next, previous, up 4311@subsection @t{fully_qualified_hosts} Parameter 4312@cindex fully_qualified_hosts Parameter 4313 4314(type=string, default=@samp{no}). If @samp{yes}, @i{Amd} will perform RPC 4315authentication using fully-qualified host names. This is necessary for 4316some systems, and especially when performing cross-domain mounting. For 4317this function to work, the @i{Amd} variable @samp{$@{hostd@}} is used, 4318requiring that @samp{$@{domain@}} not be null. 4319 4320@c ---------------------------------------------------------------- 4321@node hesiod_base Parameter, karch Parameter, fully_qualified_hosts Parameter, Global Parameters 4322@comment node-name, next, previous, up 4323@subsection @t{hesiod_base} Parameter 4324@cindex hesiod_base Parameter 4325 4326(type=string, default=@samp{automount}). Specify the base name for 4327hesiod maps. 4328 4329@c ---------------------------------------------------------------- 4330@node karch Parameter, ldap_base Parameter, hesiod_base Parameter, Global Parameters 4331@comment node-name, next, previous, up 4332@subsection @t{karch} Parameter 4333@cindex karch Parameter 4334 4335(type=string, default to karch of the system). Same as the @code{-k} 4336option to @i{Amd}. Allows you to override the kernel-architecture of 4337your system. Useful for example on Sun (Sparc) machines, where you can 4338build one @i{Amd} binary, and run it on multiple machines, yet you want 4339each one to get the correct @i{karch} variable set (for example, sun4c, 4340sun4m, sun4u, etc.) Note that if not specified, @i{Amd} will use 4341@b{uname}(2) to figure out the kernel architecture of the machine. 4342 4343@c ---------------------------------------------------------------- 4344@node ldap_base Parameter, ldap_cache_maxmem Parameter, karch Parameter, Global Parameters 4345@comment node-name, next, previous, up 4346@subsection @t{ldap_base} Parameter 4347@cindex ldap_base Parameter 4348 4349(type=string, default not set). Specify the base name for 4350LDAP. 4351 4352@c ---------------------------------------------------------------- 4353@node ldap_cache_maxmem Parameter, ldap_cache_seconds Parameter, ldap_base Parameter, Global Parameters 4354@comment node-name, next, previous, up 4355@subsection @t{ldap_cache_maxmem} Parameter 4356@cindex ldap_cache_maxmem Parameter 4357 4358(type=numeric, default=131072). Specify the maximum memory @i{Amd} 4359should use to cache LDAP entries. 4360 4361@c ---------------------------------------------------------------- 4362@node ldap_cache_seconds Parameter, ldap_hostports Parameter, ldap_cache_maxmem Parameter, Global Parameters 4363@comment node-name, next, previous, up 4364@subsection @t{ldap_cache_seconds} Parameter 4365@cindex ldap_cache_seconds Parameter 4366 4367(type=numeric, default=0). Specify the number of seconds to keep 4368entries in the cache. 4369 4370@c ---------------------------------------------------------------- 4371@node ldap_hostports Parameter, local_domain Parameter, ldap_cache_seconds Parameter, Global Parameters 4372@comment node-name, next, previous, up 4373@subsection @t{ldap_hostports} Parameter 4374@cindex ldap_hostports Parameter 4375 4376(type=string, default not set). Specify 4377LDAP-specific values such as country and organization. 4378 4379@c ---------------------------------------------------------------- 4380@node local_domain Parameter, log_file Parameter, ldap_hostports Parameter, Global Parameters 4381@comment node-name, next, previous, up 4382@subsection @t{local_domain} Parameter 4383@cindex local_domain Parameter 4384 4385(type=string, default no sub-domain). Same as the @code{-d} option 4386to @i{Amd}. Specify the local domain name. If this option is not given 4387the domain name is determined from the hostname, by removing the first 4388component of the fully-qualified host name. 4389 4390@c ---------------------------------------------------------------- 4391@node log_file Parameter, log_options Parameter, local_domain Parameter, Global Parameters 4392@comment node-name, next, previous, up 4393@subsection @t{log_file} Parameter 4394@cindex log_file Parameter 4395 4396(type=string, default=@samp{stderr}). Same as the @code{-l} option to 4397@i{Amd}. Specify a file name to log @i{Amd} events to. 4398If the string @samp{/dev/stderr} is specified, 4399@i{Amd} will send its events to the standard error file descriptor. 4400 4401If the string @samp{syslog} is given, @i{Amd} will record its events 4402with the system logger @b{syslogd}(8). If your system supports syslog 4403facilities, then the default facility used is @samp{LOG_DAEMON}. 4404 4405When using syslog, if you wish to change the facility, append its name 4406to the option name, delimited by a single colon. For example, if it is 4407the string @samp{syslog:local7} then @i{Amd} will log messages via 4408@b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If the facility 4409name specified is not recognized, @i{Amd} will default to @samp{LOG_DAEMON}. 4410Note: while you can use any syslog facility available on your system, it 4411is generally a bad idea to use those reserved for other services such as 4412@samp{kern}, @samp{lpr}, @samp{cron}, etc. 4413 4414@c ---------------------------------------------------------------- 4415@node log_options Parameter, nfs_retransmit_counter Parameter, log_file Parameter, Global Parameters 4416@comment node-name, next, previous, up 4417@subsection @t{log_options} Parameter 4418@cindex log_options Parameter 4419 4420(type=string, default no logging options). Same as the @code{-x} 4421option to @i{Amd}. Specify any logging options for @i{Amd}. Options 4422are comma delimited, and can be preceded by the string @samp{no} to 4423negate their meaning. The @samp{debug} logging option is only available 4424if am-utils was configured with @code{--enable-debug}. You can get the 4425list of supported debugging options by running @code{amd -v}. Possible 4426values are: 4427 4428@table @samp 4429@item all 4430all messages 4431@item debug 4432debug messages 4433@item error 4434non-fatal system errors 4435@item fatal 4436fatal errors 4437@item info 4438information 4439@item map 4440map errors 4441@item stats 4442additional statistical information 4443@item user 4444non-fatal user errors 4445@item warn 4446warnings 4447@item warning 4448warnings 4449@end table 4450 4451@c ---------------------------------------------------------------- 4452@node nfs_retransmit_counter Parameter, nfs_retry_interval Parameter, log_options Parameter, Global Parameters 4453@comment node-name, next, previous, up 4454@subsection @t{nfs_retransmit_counter} Parameter 4455@cindex nfs_retransmit_counter Parameter 4456 4457(type=numeric, default=110). Same as the @i{counter} part of the 4458@code{-t} @i{interval.counter} option to @i{Amd}. Specifies the 4459retransmit counter's value in @emph{tenths} of seconds. 4460 4461@c ---------------------------------------------------------------- 4462@node nfs_retry_interval Parameter, nis_domain Parameter, nfs_retransmit_counter Parameter, Global Parameters 4463@comment node-name, next, previous, up 4464@subsection @t{nfs_retry_interval} Parameter 4465@cindex nfs_retry_interval Parameter 4466 4467(type=numeric, default=8). Same as the @i{interval} part of the 4468@code{-t} @i{interval.counter} option to @i{Amd}. Specifies the 4469interval in @emph{tenths} of seconds, between NFS/RPC/UDP retries. 4470 4471@c ---------------------------------------------------------------- 4472@node nis_domain Parameter, normalize_hostnames Parameter, nfs_retry_interval Parameter, Global Parameters 4473@comment node-name, next, previous, up 4474@subsection @t{nis_domain} Parameter 4475@cindex nis_domain Parameter 4476 4477(type=string, default to local NIS domain name). Same as the 4478@code{-y} option to @i{Amd}. Specify an alternative NIS domain from 4479which to fetch the NIS maps. The default is the system domain name. 4480This option is ignored if NIS support is not available. 4481 4482@c ---------------------------------------------------------------- 4483@node normalize_hostnames Parameter, os Parameter, nis_domain Parameter, Global Parameters 4484@comment node-name, next, previous, up 4485@subsection @t{normalize_hostnames} Parameter 4486@cindex normalize_hostnames Parameter 4487 4488(type=boolean, default=@samp{no}). Same as the @code{-n} option to @i{Amd}. 4489If @samp{yes}, then the name referred to by @code{$@{rhost@}} is normalized 4490relative to the host database before being used. The effect is to 4491translate aliases into ``official'' names. 4492 4493@c ---------------------------------------------------------------- 4494@node os Parameter, osver Parameter, normalize_hostnames Parameter, Global Parameters 4495@comment node-name, next, previous, up 4496@subsection @t{os} Parameter 4497@cindex os Parameter 4498 4499(type=string, default to compiled in value). Same as the @code{-O} 4500option to @i{Amd}. Allows you to override the compiled-in name of the 4501operating system. Useful when the built-in name is not desired for 4502backward compatibility reasons. For example, if the built-in name is 4503@samp{sunos5}, you can override it to @samp{sos5}, and use older maps 4504which were written with the latter in mind. 4505 4506@c ---------------------------------------------------------------- 4507@node osver Parameter, pid_file Parameter, os Parameter, Global Parameters 4508@comment node-name, next, previous, up 4509@subsection @t{osver} Parameter 4510@cindex osver Parameter 4511 4512(type=string, default to compiled in value). Same as the @code{-o} 4513option to @i{Amd}. Allows you to override the compiled-in version 4514number of the operating system. Useful when the built-in version is not 4515desired for backward compatibility reasons. For example, if the build 4516in version is @samp{2.5.1}, you can override it to @samp{5.5.1}, and use 4517older maps that were written with the latter in mind. 4518 4519@c ---------------------------------------------------------------- 4520@node pid_file Parameter, plock Parameter, osver Parameter, Global Parameters 4521@comment node-name, next, previous, up 4522@subsection @t{pid_file} Parameter 4523@cindex pid_file Parameter 4524 4525(type=string, default=@samp{/dev/stdout}). Specify a file to store the process 4526ID of the running daemon into. If not specified, @i{Amd} will print its 4527process id onto the standard output. Useful for killing @i{Amd} after 4528it had run. Note that the PID of a running @i{Amd} can also be 4529retrieved via @i{Amq} (@pxref{Amq -p option}). 4530 4531This file is used only if the @samp{print_pid} option is on 4532(@pxref{print_pid Parameter}). 4533 4534@c ---------------------------------------------------------------- 4535@node plock Parameter, portmap_program Parameter, pid_file Parameter, Global Parameters 4536@comment node-name, next, previous, up 4537@subsection @t{plock} Parameter 4538@cindex plock Parameter 4539 4540(type=boolean, default=@samp{yes}). Same as the @code{-S} option to @i{Amd}. 4541If @samp{yes}, lock the running executable pages of @i{Amd} into memory. 4542To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 4543call can lock the @i{Amd} process into memory. This way there is less 4544chance the operating system will schedule, page out, and swap the 4545@i{Amd} process as needed. This improves @i{Amd}'s performance, at the 4546cost of reserving the memory used by the @i{Amd} process (making it 4547unavailable for other processes). 4548 4549@c ---------------------------------------------------------------- 4550@node portmap_program Parameter, print_pid Parameter, plock Parameter, Global Parameters 4551@comment node-name, next, previous, up 4552@subsection @t{portmap_program} Parameter 4553@cindex portmap_program Parameter 4554 4555(type=numeric, default=300019). Specify an alternate Port-mapper RPC 4556program number, other than the official number. This is useful when 4557running multiple @i{Amd} processes. For example, you can run another 4558@i{Amd} in ``test'' mode, without affecting the primary @i{Amd} process 4559in any way. For safety reasons, the alternate program numbers that can 4560be specified must be in the range 300019-300029, inclusive. @i{Amq} has 4561an option @code{-P} which can be used to specify an alternate program 4562number of an @i{Amd} to contact. In this way, amq can fully control any 4563number of @i{Amd} processes running on the same host. 4564 4565@c ---------------------------------------------------------------- 4566@node print_pid Parameter, print_version Parameter, portmap_program Parameter, Global Parameters 4567@comment node-name, next, previous, up 4568@subsection @t{print_pid} Parameter 4569@cindex print_pid Parameter 4570 4571(type=boolean, default=@samp{no}). Same as the @code{-p} option to @i{Amd}. 4572If @samp{yes}, @i{Amd} will print its process ID upon starting. 4573 4574@c ---------------------------------------------------------------- 4575@node print_version Parameter, restart_mounts Parameter, print_pid Parameter, Global Parameters 4576@comment node-name, next, previous, up 4577@subsection @t{print_version} Parameter 4578@cindex print_version Parameter 4579 4580(type=boolean, default=@samp{no}). Same as the @code{-v} option to @i{Amd}, 4581but the version prints and @i{Amd} continues to run. If @samp{yes}, @i{Amd} 4582will print its version information string, which includes some 4583configuration and compilation values. 4584 4585@c ---------------------------------------------------------------- 4586@node restart_mounts Parameter, selectors_on_default Parameter, print_version Parameter, Global Parameters 4587@comment node-name, next, previous, up 4588@subsection @t{restart_mounts} Parameter 4589@cindex restart_mounts Parameter 4590 4591(type=boolean, default=@samp{no}). Same as the @code{-r} option to @i{Amd}. 4592If @samp{yes} @i{Amd} will scan the mount table to determine which file 4593systems are currently mounted. Whenever one of these would have been 4594auto-mounted, @i{Amd} inherits it. 4595 4596@c ---------------------------------------------------------------- 4597@node selectors_on_default Parameter, show_statfs_entries Parameter, restart_mounts Parameter, Global Parameters 4598@comment node-name, next, previous, up 4599@subsection @t{selectors_on_default} Parameter 4600@cindex selectors_on_default Parameter 4601 4602(type=boolean, default=@samp{no}). If @samp{yes}, then the @samp{/defaults} entry of 4603maps will be looked for and any selectors processed before setting defaults 4604for all other keys in that map. Useful when you want to set different 4605options for a complete map based on some parameters. For example, you 4606may want to better the NFS performance over slow slip-based networks as 4607follows: 4608 4609@example 4610/defaults \ 4611 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \ 4612 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192 4613@end example 4614 4615@c ---------------------------------------------------------------- 4616@node show_statfs_entries Parameter, unmount_on_exit Parameter , selectors_on_default Parameter, Global Parameters 4617@comment node-name, next, previous, up 4618@subsection @t{show_statfs_entries} Parameter 4619@cindex show_statfs_entries Parameter 4620 4621(type=boolean), default=@samp{no}). If @samp{yes}, then all maps which are 4622browsable will also show the number of entries (keys) they have when 4623@b{df}(1) runs. (This is accomplished by returning non-zero values to 4624the @b{statfs}(2) system call). 4625 4626@c ---------------------------------------------------------------- 4627@node unmount_on_exit Parameter, , show_statfs_entries Parameter, Global Parameters 4628@comment node-name, next, previous, up 4629@subsection @t{unmount_on_exit} Parameter 4630@cindex unmount_on_exit Parameter 4631 4632(type=boolean), default=@samp{no}). If @samp{yes}, then @i{Amd} will attempt 4633to unmount all file systems which it knows about. Normally it leaves 4634all (esp. NFS) mounted file systems intact. Note that @i{Amd} does not 4635know about file systems mounted before it starts up, unless the 4636@samp{restart_mounts} option is used (@pxref{restart_mounts Parameter}). 4637 4638@c ================================================================ 4639@node Regular Map Parameters, amd.conf Examples, Global Parameters, Amd Configuration File 4640@comment node-name, next, previous, up 4641@section Regular Map Parameters 4642@cindex amd.conf regular map parameters 4643 4644The following parameters are applicable only to regular map sections. 4645 4646@menu 4647* map_name Parameter:: 4648* tag Parameter:: 4649@end menu 4650 4651@c ---------------------------------------------------------------- 4652@node map_name Parameter, tag Parameter, Regular Map Parameters, Regular Map Parameters 4653@comment node-name, next, previous, up 4654@subsection map_name Parameter 4655@cindex map_name Parameter 4656 4657(type=string, must be specified). Name of the map where the keys are 4658located. 4659 4660@c ---------------------------------------------------------------- 4661@node tag Parameter, , map_name Parameter, Regular Map Parameters 4662@comment node-name, next, previous, up 4663@subsection tag Parameter 4664@cindex tag Parameter 4665 4666(type=string, default no tag). Each map entry in the configuration file 4667can be tagged. If no tag is specified, that map section will always be 4668processed by @i{Amd}. If it is specified, then @i{Amd} will process the map 4669if the @code{-T} option was given to @i{Amd}, and the value given to that 4670command-line option matches that in the map section. 4671 4672@c ================================================================ 4673@node amd.conf Examples, , Regular Map Parameters, Amd Configuration File 4674@comment node-name, next, previous, up 4675@section amd.conf Examples 4676@cindex amd.conf examples 4677 4678The following is the actual @code{amd.conf} file I use at the 4679Computer Science Department of Columbia University. 4680 4681@example 4682# GLOBAL OPTIONS SECTION 4683[ global ] 4684normalize_hostnames = no 4685print_pid = no 4686#pid_file = /var/run/amd.pid 4687restart_mounts = yes 4688#unmount_on_exit = yes 4689auto_dir = /n 4690log_file = /var/log/amd 4691log_options = all 4692#debug_options = all 4693plock = no 4694selectors_on_default = yes 4695# config.guess picks up "sunos5" and I don't want to edit my maps yet 4696os = sos5 4697# if you print_version after setting up "os", it will show it. 4698print_version = no 4699map_type = file 4700search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib 4701browsable_dirs = yes 4702fully_qualified_hosts = no 4703 4704# DEFINE AN AMD MOUNT POINT 4705[ /u ] 4706map_name = amd.u 4707 4708[ /proj ] 4709map_name = amd.proj 4710 4711[ /src ] 4712map_name = amd.src 4713 4714[ /misc ] 4715map_name = amd.misc 4716 4717[ /import ] 4718map_name = amd.import 4719 4720[ /tftpboot/.amd ] 4721tag = tftpboot 4722map_name = amd.tftpboot 4723@end example 4724 4725@c ################################################################ 4726@node Run-time Administration, FSinfo, Amd Configuration File, Top 4727@comment node-name, next, previous, up 4728@chapter Run-time Administration 4729@cindex Run-time administration 4730@cindex Amq command 4731 4732@menu 4733* Starting Amd:: 4734* Stopping Amd:: 4735* Restarting Amd:: 4736* Controlling Amd:: 4737@end menu 4738 4739@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration 4740@comment node-name, next, previous, up 4741@section Starting @i{Amd} 4742@cindex Starting Amd 4743@cindex Additions to /etc/rc.local 4744@cindex /etc/rc.local additions 4745@cindex ctl-amd 4746 4747@i{Amd} is best started from @samp{/etc/rc.local} on BSD systems, or 4748from the appropriate start-level script in @samp{/etc/init.d} on System V 4749systems. 4750 4751@example 4752if [ -f /usr/local/sbin/ctl-amd ]; then 4753 /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console 4754fi 4755@end example 4756 4757@noindent 4758The shell script, @samp{ctl-amd} is used to start, stop, or restart 4759@i{Amd}. It is a relatively generic script. All options you want to 4760set should not be made in this script, but rather updated in the 4761@file{amd.conf} file. @xref{Amd Configuration File}. 4762 4763If you do not wish to use an @i{Amd} configuration file, you may start 4764@i{Amd} manually. For example, getting the map entries via NIS: 4765 4766@example 4767amd -r -l /var/log/amd `ypcat -k auto.master` 4768@end example 4769 4770@node Stopping Amd, Restarting Amd, Starting Amd, Run-time Administration 4771@comment node-name, next, previous, up 4772@section Stopping @i{Amd} 4773@cindex Stopping Amd 4774@cindex SIGTERM signal 4775@cindex SIGINT signal 4776 4777@i{Amd} stops in response to two signals. 4778 4779@table @samp 4780@item SIGTERM 4781causes the top-level automount points to be unmounted and then @i{Amd} 4782to exit. Any automounted filesystems are left mounted. They can be 4783recovered by restarting @i{Amd} with the @code{-r} command line option.@refill 4784 4785@item SIGINT 4786causes @i{Amd} to attempt to unmount any filesystems which it has 4787automounted, in addition to the actions of @samp{SIGTERM}. This signal 4788is primarily used for debugging.@refill 4789@end table 4790 4791Actions taken for other signals are undefined. 4792 4793The easiest and safest way to stop @i{Amd}, without having to find its 4794process ID by hand, is to use the @file{ctl-amd} script, as with: 4795 4796@example 4797ctl-amd stop 4798@end example 4799 4800@node Restarting Amd, Controlling Amd, Stopping Amd, Run-time Administration 4801@comment node-name, next, previous, up 4802@section Restarting @i{Amd} 4803@cindex Restarting Amd 4804@cindex Killing and starting Amd 4805 4806Before @i{Amd} can be started, it is vital to ensure that no other 4807@i{Amd} processes are managing any of the mount points, and that the 4808previous process(es) have terminated cleanly. When a terminating signal 4809is set to @i{Amd}, the automounter does @emph{not} terminate right then. 4810Rather, it starts by unmounting all of its managed mount mounts in the 4811background, and then terminates. It usually takes a few seconds for 4812this process to happen, but it can take an arbitrarily longer time. If 4813two or more @i{Amd} processes attempt to manage the same mount point, it 4814usually will result in a system lockup. 4815 4816The easiest and safest way to restart @i{Amd}, without having to find 4817its process ID by hand, sending it the @samp{SIGTERM} signal, waiting for @i{Amd} 4818to die cleanly, and verifying so, is to use the @file{ctl-amd} script, 4819as with: 4820 4821@example 4822ctl-amd restart 4823@end example 4824 4825The script will locate the process ID of @i{Amd}, kill it, and wait for 4826it to die cleanly before starting a new instance of the automounter. 4827@file{ctl-amd} will wait for a total of 30 seconds for @i{Amd} to die, 4828and will check once every 5 seconds if it had. 4829 4830@node Controlling Amd, , Restarting Amd, Run-time Administration 4831@comment node-name, next, previous, up 4832@section Controlling @i{Amd} 4833@cindex Controlling Amd 4834@cindex Discovering what is going on at run-time 4835@cindex Listing currently mounted filesystems 4836 4837It is sometimes desirable or necessary to exercise external control 4838over some of @i{Amd}'s internal state. To support this requirement, 4839@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. 4840A variety of information is available. 4841 4842@i{Amq} generally applies an operation, specified by a single letter option, 4843to a list of mount points. The default operation is to obtain statistics 4844about each mount point. This is similar to the output shown above 4845but includes information about the number and type of accesses to each 4846mount point. 4847 4848@menu 4849* Amq default:: Default command behavior. 4850* Amq -f option:: Flushing the map cache. 4851* Amq -h option:: Controlling a non-local host. 4852* Amq -l option:: Controlling the log file. 4853* Amq -m option:: Obtaining mount statistics. 4854* Amq -M-option:: Mounting a volume. 4855* Amq -p option:: Getting Amd's process ID. 4856* Amq -P-option:: Contacting alternate Amd processes. 4857* Amq -s option:: Obtaining global statistics. 4858* Amq -T option:: Use TCP transport. 4859* Amq -U-option:: Use UDP transport. 4860* Amq -u option:: Forcing volumes to time out. 4861* Amq -v option:: Version information. 4862* Other Amq options:: Three other special options. 4863@end menu 4864 4865@c ---------------------------------------------------------------- 4866@node Amq default, Amq -f option, Controlling Amd, Controlling Amd 4867@comment node-name, next, previous, up 4868@subsection @i{Amq} default information 4869 4870With no arguments, @dfn{Amq} obtains a brief list of all existing 4871mounts created by @i{Amd}. This is different from the list displayed by 4872@b{df}(1) since the latter only includes system mount points. 4873 4874@noindent 4875The output from this option includes the following information: 4876 4877@itemize @bullet 4878@item 4879the automount point, 4880@item 4881the filesystem type, 4882@item 4883the mount map or mount information, 4884@item 4885the internal, or system mount point. 4886@end itemize 4887 4888@noindent 4889For example: 4890 4891@example 4892/ root "root" sky:(pid75) 4893/homes toplvl /usr/local/etc/amd.homes /homes 4894/home toplvl /usr/local/etc/amd.home /home 4895/homes/jsp nfs charm:/home/charm /a/charm/home/charm/jsp 4896/homes/phjk nfs toytown:/home/toytown /a/toytown/home/toytown/ai/phjk 4897@end example 4898 4899@noindent 4900If an argument is given then statistics for that volume name will 4901be output. For example: 4902 4903@example 4904What Uid Getattr Lookup RdDir RdLnk Statfs Mounted@@ 4905/homes 0 1196 512 22 0 30 90/09/14 12:32:55 4906/homes/jsp 0 0 0 0 1180 0 90/10/13 12:56:58 4907@end example 4908 4909@table @code 4910@item What 4911the volume name. 4912 4913@item Uid 4914ignored. 4915 4916@item Getattr 4917the count of NFS @dfn{getattr} requests on this node. This should only be 4918non-zero for directory nodes. 4919 4920@item Lookup 4921the count of NFS @dfn{lookup} requests on this node. This should only be 4922non-zero for directory nodes. 4923 4924@item RdDir 4925the count of NFS @dfn{readdir} requests on this node. This should only 4926be non-zero for directory nodes. 4927 4928@item RdLnk 4929the count of NFS @dfn{readlink} requests on this node. This should be 4930zero for directory nodes. 4931 4932@item Statfs 4933the count of NFS @dfn{statfs} requests on this node. This should only 4934be non-zero for top-level automount points. 4935 4936@item Mounted@@ 4937the date and time the volume name was first referenced. 4938@end table 4939 4940@c ---------------------------------------------------------------- 4941@node Amq -f option, Amq -h option, Amq default, Controlling Amd 4942@comment node-name, next, previous, up 4943@subsection @i{Amq} @code{-f} option 4944@cindex Flushing the map cache 4945@cindex Map cache, flushing 4946 4947The @code{-f} option causes @i{Amd} to flush the internal mount map cache. 4948This is useful for example in Hesiod maps since @i{Amd} will not 4949automatically notice when they have been updated. The map cache can 4950also be synchronized with the map source by using the @samp{sync} option 4951(@pxref{Automount Filesystem}).@refill 4952 4953@c ---------------------------------------------------------------- 4954@node Amq -l option, Amq -m option, Amq -h option, Controlling Amd 4955@comment node-name, next, previous, up 4956@subsection @i{Amq} @code{-l} option 4957@cindex Resetting the Amd log file 4958@cindex Setting the Amd log file via Amq 4959@cindex Log file, resetting 4960 4961Tell @i{Amd} to use @i{log_file} as the log file name. For security 4962reasons, this @emph{must} be the same log file which @i{Amd} used when 4963started. This option is therefore only useful to refresh @i{Amd}'s open 4964file handle on the log file, so that it can be rotated and compressed 4965via daily cron jobs. 4966 4967@c ---------------------------------------------------------------- 4968@node Amq -h option, Amq -l option, Amq -f option, Controlling Amd 4969@comment node-name, next, previous, up 4970@subsection @i{Amq} @code{-h} option 4971@cindex Querying an alternate host 4972 4973By default the local host is used. In an HP-UX cluster the root server 4974is used since that is the only place in the cluster where @i{Amd} will 4975be running. To query @i{Amd} on another host the @code{-h} option should 4976be used. 4977 4978@c ---------------------------------------------------------------- 4979@node Amq -m option, Amq -M-option, Amq -l option, Controlling Amd 4980@comment node-name, next, previous, up 4981@subsection @i{Amq} @code{-m} option 4982 4983The @code{-m} option displays similar information about mounted 4984filesystems, rather than automount points. The output includes the 4985following information: 4986 4987@itemize @bullet 4988@item 4989the mount information, 4990@item 4991the mount point, 4992@item 4993the filesystem type, 4994@item 4995the number of references to this filesystem, 4996@item 4997the server hostname, 4998@item 4999the state of the file server, 5000@item 5001any error which has occurred. 5002@end itemize 5003 5004For example: 5005 5006@example 5007"root" truth:(pid602) root 1 localhost is up 5008hesiod.home /home toplvl 1 localhost is up 5009hesiod.vol /vol toplvl 1 localhost is up 5010hesiod.homes /homes toplvl 1 localhost is up 5011amy:/home/amy /a/amy/home/amy nfs 5 amy is up 5012swan:/home/swan /a/swan/home/swan nfs 0 swan is up (Permission denied) 5013ex:/home/ex /a/ex/home/ex nfs 0 ex is down 5014@end example 5015 5016When the reference count is zero the filesystem is not mounted but 5017the mount point and server information is still being maintained 5018by @i{Amd}. 5019 5020@c ---------------------------------------------------------------- 5021@node Amq -M-option, Amq -p option, Amq -m option, Controlling Amd 5022@comment node-name, next, previous, up 5023@subsection @i{Amq} @code{-M} option 5024 5025The @code{-M} option passes a new map entry to @i{Amd} and waits for it to 5026be evaluated, possibly causing a mount. For example, the following 5027command would cause @samp{/home/toytown} on host @samp{toytown} to be 5028mounted locally on @samp{/mnt/toytown}. 5029 5030@example 5031amq -M '/mnt/toytown type:=nfs;rfs:=/home/toytown;rhost:=toytown;fs:=$@{key@}' 5032@end example 5033 5034@i{Amd} applies some simple security checks before allowing this 5035operation. The check tests whether the incoming request is from a 5036privileged UDP port on the local machine. ``Permission denied'' is 5037returned if the check fails. 5038 5039This option is very insecure as it is vulnerable to attacks such as IP 5040Spoofing. In other words, it is relatively easy for an attacker who 5041really wants to, to make your @i{Amd} process mount any filesystem from 5042the Internet! Therefore, the @emph{complete} code which supports the 5043@code{-M} option in @i{Amd} and @i{Amq} is turned off by default. To turn 5044it on, you have to reconfigure am-utils with @code{configure 5045--enable-amq-mount}. Think twice before doing so, and use this option 5046only if you absolutely need to. 5047 5048A future release of @i{Amd} will include code to allow the @b{mount}(8) 5049command to mount automount points: 5050 5051@example 5052mount -t amd /vol hesiod.vol 5053@end example 5054 5055This will then allow @i{Amd} to be controlled from the standard system 5056filesystem mount list. 5057 5058@c ---------------------------------------------------------------- 5059@node Amq -p option, Amq -P-option, Amq -M-option, Controlling Amd 5060@comment node-name, next, previous, up 5061@subsection @i{Amq} @code{-p} option 5062@cindex Process ID; Amd 5063@cindex Amd's process ID 5064@cindex Amd's PID 5065@cindex PID; Amd 5066 5067Return the process ID of the remote or locally running @i{Amd}. Useful 5068when you need to send a signal to the local @i{Amd} process, and would 5069rather not have to search through the process table. This option is 5070used in the @file{ctl-amd} script. 5071 5072@c ---------------------------------------------------------------- 5073@node Amq -P-option, Amq -s option, Amq -p option, Controlling Amd 5074@comment node-name, next, previous, up 5075@subsection @i{Amq} @code{-P} option 5076@cindex Multiple Amd processes 5077@cindex Running multiple Amd 5078@cindex Debugging a new Amd configuration 5079@cindex RPC Program numbers; Amd 5080 5081Contact an alternate running @i{Amd} that had registered itself on a 5082different RPC @var{program_number} and apply all other operations to 5083that instance of the automounter. This is useful when you run multiple 5084copies of @i{Amd}, and need to manage each one separately. If not 5085specified, @i{Amq} will use the default program number for @i{Amd}, 300019. 5086For security reasons, the only alternate program numbers @i{Amd} can use 5087range from 300019 to 300029, inclusive. 5088 5089For example, to kill an alternate running @i{Amd}: 5090 5091@example 5092kill `amq -p -P 300020` 5093@end example 5094 5095@c ---------------------------------------------------------------- 5096@node Amq -s option, Amq -T option, Amq -P-option, Controlling Amd 5097@comment node-name, next, previous, up 5098@subsection @i{Amq} @code{-s} option 5099@cindex Global statistics 5100@cindex Statistics 5101 5102The @code{-s} option displays global statistics. If any other options are specified 5103or any filesystems named then this option is ignored. For example: 5104 5105@example 5106requests stale mount mount unmount 5107deferred fhandles ok failed failed 51081054 1 487 290 7017 5109@end example 5110 5111@table @samp 5112@item Deferred requests 5113are those for which an immediate reply could not be constructed. For 5114example, this would happen if a background mount was required. 5115 5116@item Stale filehandles 5117counts the number of times the kernel passes a stale filehandle to @i{Amd}. 5118Large numbers indicate problems. 5119 5120@item Mount ok 5121counts the number of automounts which were successful. 5122 5123@item Mount failed 5124counts the number of automounts which failed. 5125 5126@item Unmount failed 5127counts the number of times a filesystem could not be unmounted. Very 5128large numbers here indicate that the time between unmount attempts 5129should be increased. 5130@end table 5131 5132@c ---------------------------------------------------------------- 5133@node Amq -T option, Amq -U-option, Amq -s option, Controlling Amd 5134@comment node-name, next, previous, up 5135@subsection @i{Amq} @code{-T} option 5136@cindex Forcing Amq to use a TCP transport 5137@cindex TCP; using with Amq 5138 5139The @code{-T} option causes the @i{Amq} to contact @i{Amd} using the TCP 5140transport only (connection oriented). Normally, @i{Amq} will use TCP 5141first, and if that failed, will try UDP. 5142 5143@c ---------------------------------------------------------------- 5144@node Amq -U-option, Amq -u option, Amq -T option, Controlling Amd 5145@comment node-name, next, previous, up 5146@subsection @i{Amq} @code{-U} option 5147@cindex Forcing Amq to use a UDP transport 5148@cindex UDP; using with Amq 5149 5150The @code{-U} option causes the @i{Amq} to contact @i{Amd} using the UDP 5151transport only (connectionless). Normally, @i{Amq} will use TCP first, 5152and if that failed, will try UDP. 5153 5154@c ---------------------------------------------------------------- 5155@node Amq -u option, Amq -v option, Amq -U-option, Controlling Amd 5156@comment node-name, next, previous, up 5157@subsection @i{Amq} @code{-u} option 5158@cindex Forcing filesystem to time out 5159@cindex Unmounting a filesystem 5160 5161The @code{-u} option causes the time-to-live interval of the named mount 5162points to be expired, thus causing an unmount attempt. This is the only 5163safe way to unmount an automounted filesystem. It is not possible to 5164unmount a filesystem which has been mounted with the @samp{nounmount} 5165flag. 5166 5167@c The @code{-H} option informs @i{Amd} that the specified mount point has hung - 5168@c as if its keepalive timer had expired. 5169 5170@c ---------------------------------------------------------------- 5171@node Amq -v option, Other Amq options, Amq -u option, Controlling Amd 5172@comment node-name, next, previous, up 5173@subsection @i{Amq} @code{-v} option 5174@cindex Version information at run-time 5175 5176The @code{-v} option displays the version of @i{Amd} in a similar way to 5177@i{Amd}'s @code{-v} option. 5178 5179@c ---------------------------------------------------------------- 5180@node Other Amq options, , Amq -v option, Controlling Amd 5181@comment node-name, next, previous, up 5182@subsection Other @i{Amq} options 5183@cindex Logging options via Amq 5184@cindex Debugging options via Amq 5185 5186Two other operations are implemented. These modify the state of @i{Amd} 5187as a whole, rather than any particular filesystem. The @code{-x} and 5188@code{-D} options have exactly the same effect as @i{Amd}'s corresponding 5189command line options. 5190 5191When @i{Amd} receives a @code{-x} flag it limits the log options being 5192modified to those which were not enabled at startup. This prevents a 5193user turning @emph{off} any logging option which was specified at 5194startup, though any which have been turned on since then can still be 5195turned off. The @code{-D} option has a similar behavior. 5196 5197@c ################################################################ 5198@node FSinfo, Hlfsd, Run-time Administration, Top 5199@comment node-name, next, previous, up 5200@chapter FSinfo 5201@cindex FSinfo 5202@cindex Filesystem info package 5203 5204XXX: this chapter should be reviewed by someone knowledgeable with 5205fsinfo. 5206 5207@menu 5208* FSinfo Overview:: Introduction to FSinfo. 5209* Using FSinfo:: Basic concepts. 5210* FSinfo Grammar:: Language syntax, semantics and examples. 5211* FSinfo host definitions:: Defining a new host. 5212* FSinfo host attributes:: Definable host attributes. 5213* FSinfo filesystems:: Defining locally attached filesystems. 5214* FSinfo static mounts:: Defining additional static mounts. 5215* FSinfo automount definitions:: 5216* FSinfo Command Line Options:: 5217* FSinfo errors:: 5218@end menu 5219 5220@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo 5221@comment node-name, next, previous, up 5222@section @i{FSinfo} overview 5223@cindex FSinfo overview 5224 5225@i{FSinfo} is a filesystem management tool. It has been designed to 5226work with @i{Amd} to help system administrators keep track of the ever 5227increasing filesystem namespace under their control. 5228 5229The purpose of @i{FSinfo} is to generate all the important standard 5230filesystem data files from a single set of input data. Starting with a 5231single data source guarantees that all the generated files are 5232self-consistent. One of the possible output data formats is a set of 5233@i{Amd} maps which can be used amongst the set of hosts described in the 5234input data. 5235 5236@i{FSinfo} implements a declarative language. This language is 5237specifically designed for describing filesystem namespace and physical 5238layouts. The basic declaration defines a mounted filesystem including 5239its device name, mount point, and all the volumes and access 5240permissions. @i{FSinfo} reads this information and builds an internal 5241map of the entire network of hosts. Using this map, many different data 5242formats can be produced including @file{/etc/fstab}, 5243@file{/etc/exports}, @i{Amd} mount maps and 5244@file{/etc/bootparams}.@refill 5245 5246@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo 5247@comment node-name, next, previous, up 5248@section Using @i{FSinfo} 5249@cindex Using FSinfo 5250 5251The basic strategy when using @i{FSinfo} is to gather all the 5252information about all disks on all machines into one set of 5253declarations. For each machine being managed, the following data is 5254required: 5255 5256@itemize @bullet 5257@item 5258Hostname 5259@item 5260List of all filesystems and, optionally, their mount points. 5261@item 5262Names of volumes stored on each filesystem. 5263@item 5264NFS export information for each volume. 5265@item 5266The list of static filesystem mounts. 5267@end itemize 5268 5269The following information can also be entered into the same 5270configuration files so that all data can be kept in one place. 5271 5272@itemize @bullet 5273@item 5274List of network interfaces 5275@item 5276IP address of each interface 5277@item 5278Hardware address of each interface 5279@item 5280Dumpset to which each filesystem belongs 5281@item 5282and more @dots{} 5283@end itemize 5284 5285To generate @i{Amd} mount maps, the automount tree must also be defined 5286(@pxref{FSinfo automount definitions}). This will have been designed at 5287the time the volume names were allocated. Some volume names will not be 5288automounted, so @i{FSinfo} needs an explicit list of which volumes 5289should be automounted.@refill 5290 5291Hostnames are required at several places in the @i{FSinfo} language. It 5292is important to stick to either fully qualified names or unqualified 5293names. Using a mixture of the two will inevitably result in confusion. 5294 5295Sometimes volumes need to be referenced which are not defined in the set 5296of hosts being managed with @i{FSinfo}. The required action is to add a 5297dummy set of definitions for the host and volume names required. Since 5298the files generated for those particular hosts will not be used on them, 5299the exact values used is not critical. 5300 5301@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo 5302@comment node-name, next, previous, up 5303@section @i{FSinfo} grammar 5304@cindex FSinfo grammar 5305@cindex Grammar, FSinfo 5306 5307@i{FSinfo} has a relatively simple grammar. Distinct syntactic 5308constructs exist for each of the different types of data, though they 5309share a common flavor. Several conventions are used in the grammar 5310fragments below. 5311 5312The notation, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more 5313@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one 5314@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input 5315tokens. Items in angle brackets, @i{eg} @var{<hostname>}, represent 5316strings in the input. Strings need not be in double quotes, except to 5317differentiate them from reserved words. Quoted strings may include the 5318usual set of C ``@t{\}'' escape sequences with one exception: a 5319backslash-newline-whitespace sequence is squashed into a single space 5320character. To defeat this feature, put a further backslash at the start 5321of the second line. 5322 5323At the outermost level of the grammar, the input consists of a 5324sequence of host and automount declarations. These declarations are 5325all parsed before they are analyzed. This means they can appear in 5326any order and cyclic host references are possible. 5327 5328@example 5329fsinfo : @i{list(}fsinfo_attr@i{)} ; 5330 5331fsinfo_attr : host | automount ; 5332@end example 5333 5334@menu 5335* FSinfo host definitions:: 5336* FSinfo automount definitions:: 5337@end menu 5338 5339@node FSinfo host definitions, FSinfo host attributes, FSinfo Grammar, FSinfo 5340@comment node-name, next, previous, up 5341@section @i{FSinfo} host definitions 5342@cindex FSinfo host definitions 5343@cindex Defining a host, FSinfo 5344 5345A host declaration consists of three parts: a set of machine attribute 5346data, a list of filesystems physically attached to the machine, and a 5347list of additional statically mounted filesystems. 5348 5349@example 5350host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; 5351@end example 5352 5353Each host must be declared in this way exactly once. Such things as the 5354hardware address, the architecture and operating system types and the 5355cluster name are all specified within the @dfn{host data}. 5356 5357All the disks the machine has should then be described in the @dfn{list 5358of filesystems}. When describing disks, you can specify what 5359@dfn{volname} the disk/partition should have and all such entries are 5360built up into a dictionary which can then be used for building the 5361automounter maps. 5362 5363The @dfn{list of mounts} specifies all the filesystems that should be 5364statically mounted on the machine. 5365 5366@menu 5367* FSinfo host attributes:: 5368* FSinfo filesystems:: 5369* FSinfo static mounts:: 5370@end menu 5371 5372@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions 5373@comment node-name, next, previous, up 5374@section @i{FSinfo} host attributes 5375@cindex FSinfo host attributes 5376@cindex Defining host attributes, FSinfo 5377 5378The host data, @dfn{host_data}, always includes the @dfn{hostname}. In 5379addition, several other host attributes can be given. 5380 5381@example 5382host_data : @var{<hostname>} 5383 | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} 5384 ; 5385 5386host_attrs : host_attr "=" @var{<string>} 5387 | netif 5388 ; 5389 5390host_attr : "config" 5391 | "arch" 5392 | "os" 5393 | "cluster" 5394 ; 5395@end example 5396 5397The @dfn{hostname} is, typically, the fully qualified hostname of the 5398machine. 5399 5400Examples: 5401 5402@example 5403host dylan.doc.ic.ac.uk 5404 5405host @{ 5406 os = hpux 5407 arch = hp300 5408@} dougal.doc.ic.ac.uk 5409@end example 5410 5411The options that can be given as host attributes are shown below. 5412 5413@menu 5414* netif Option: FSinfo host netif: 5415* config Option: FSinfo host config: 5416* arch Option: FSinfo host arch: 5417* os Option: FSinfo host os: 5418* cluster Option: FSinfo host cluster: 5419@end menu 5420 5421@node FSinfo host netif, FSinfo host config, , FSinfo host attributes 5422@comment node-name, next, previous, up 5423@subsection netif Option 5424 5425This defines the set of network interfaces configured on the machine. 5426The interface attributes collected by @i{FSinfo} are the IP address, 5427subnet mask and hardware address. Multiple interfaces may be defined 5428for hosts with several interfaces by an entry for each interface. The 5429values given are sanity checked, but are currently unused for anything 5430else. 5431 5432@example 5433netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; 5434 5435netif_attrs : netif_attr "=" @var{<string>} ; 5436 5437netif_attr : "inaddr" | "netmask" | "hwaddr" ; 5438@end example 5439 5440Examples: 5441 5442@example 5443netif ie0 @{ 5444 inaddr = 129.31.81.37 5445 netmask = 0xfffffe00 5446 hwaddr = "08:00:20:01:a6:a5" 5447@} 5448 5449netif ec0 @{ @} 5450@end example 5451 5452@node FSinfo host config, FSinfo host arch, FSinfo host netif, FSinfo host attributes 5453@comment node-name, next, previous, up 5454@subsection config Option 5455@cindex FSinfo config host attribute 5456@cindex config, FSinfo host attribute 5457 5458This option allows you to specify configuration variables for the 5459startup scripts (@file{rc} scripts). A simple string should immediately 5460follow the keyword. 5461 5462Example: 5463 5464@example 5465config "NFS_SERVER=true" 5466config "ZEPHYR=true" 5467@end example 5468 5469This option is currently unsupported. 5470 5471@node FSinfo host arch, FSinfo host os, FSinfo host config, FSinfo host attributes 5472@comment node-name, next, previous, up 5473@subsection arch Option 5474@cindex FSinfo arch host attribute 5475@cindex arch, FSinfo host attribute 5476 5477This defines the architecture of the machine. For example: 5478 5479@example 5480arch = hp300 5481@end example 5482 5483This is intended to be of use when building architecture specific 5484mountmaps, however, the option is currently unsupported. 5485 5486@node FSinfo host os, FSinfo host cluster, FSinfo host arch, FSinfo host attributes 5487@comment node-name, next, previous, up 5488@subsection os Option 5489@cindex FSinfo os host attribute 5490@cindex os, FSinfo host attribute 5491 5492This defines the operating system type of the host. For example: 5493 5494@example 5495os = hpux 5496@end example 5497 5498This information is used when creating the @file{fstab} files, for 5499example in choosing which format to use for the @file{fstab} entries 5500within the file. 5501 5502@node FSinfo host cluster, , FSinfo host os, FSinfo host attributes 5503@comment node-name, next, previous, up 5504@subsection cluster Option 5505@cindex FSinfo cluster host attribute 5506@cindex cluster, FSinfo host attribute 5507 5508This is used for specifying in which cluster the machine belongs. For 5509example: 5510 5511@example 5512cluster = "theory" 5513@end example 5514 5515The cluster is intended to be used when generating the automount maps, 5516although it is currently unsupported. 5517 5518@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions 5519@comment node-name, next, previous, up 5520@section @i{FSinfo} filesystems 5521@cindex FSinfo filesystems 5522 5523The list of physically attached filesystems follows the machine 5524attributes. These should define all the filesystems available from this 5525machine, whether exported or not. In addition to the device name, 5526filesystems have several attributes, such as filesystem type, mount 5527options, and @samp{fsck} pass number which are needed to generate 5528@file{fstab} entries. 5529 5530@example 5531filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; 5532 5533fs_data : fs_data_attr "=" @var{<string>} 5534 | mount 5535 ; 5536 5537fs_data_attr 5538 : "fstype" | "opts" | "passno" 5539 | "freq" | "dumpset" | "log" 5540 ; 5541@end example 5542 5543Here, @var{<device>} is the device name of the disk (for example, 5544@file{/dev/dsk/2s0}). The device name is used for building the mount 5545maps and for the @file{fstab} file. The attributes that can be 5546specified are shown in the following section. 5547 5548The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. 5549 5550@example 5551host dylan.doc.ic.ac.uk 5552 5553fs /dev/dsk/0s0 @{ 5554 fstype = swap 5555@} 5556 5557fs /dev/dsk/0s0 @{ 5558 fstype = hfs 5559 opts = rw,noquota,grpid 5560 passno = 0; 5561 freq = 1; 5562 mount / @{ @} 5563@} 5564 5565fs /dev/dsk/1s0 @{ 5566 fstype = hfs 5567 opts = defaults 5568 passno = 1; 5569 freq = 1; 5570 mount /usr @{ 5571 local @{ 5572 exportfs "dougal eden dylan zebedee brian" 5573 volname /nfs/hp300/local 5574 @} 5575 @} 5576@} 5577 5578fs /dev/dsk/2s0 @{ 5579 fstype = hfs 5580 opts = defaults 5581 passno = 1; 5582 freq = 1; 5583 mount default @{ 5584 exportfs "toytown_clients hangers_on" 5585 volname /home/dylan/dk2 5586 @} 5587@} 5588 5589fs /dev/dsk/3s0 @{ 5590 fstype = hfs 5591 opts = defaults 5592 passno = 1; 5593 freq = 1; 5594 mount default @{ 5595 exportfs "toytown_clients hangers_on" 5596 volname /home/dylan/dk3 5597 @} 5598@} 5599 5600fs /dev/dsk/5s0 @{ 5601 fstype = hfs 5602 opts = defaults 5603 passno = 1; 5604 freq = 1; 5605 mount default @{ 5606 exportfs "toytown_clients hangers_on" 5607 volname /home/dylan/dk5 5608 @} 5609@} 5610@end example 5611 5612@menu 5613* fstype Option: FSinfo filesystems fstype: 5614* opts Option: FSinfo filesystems opts: 5615* passno Option: FSinfo filesystems passno: 5616* freq Option: FSinfo filesystems freq: 5617* mount Option: FSinfo filesystems mount: 5618* dumpset Option: FSinfo filesystems dumpset: 5619* log Option: FSinfo filesystems log: 5620@end menu 5621 5622@node FSinfo filesystems fstype, FSinfo filesystems opts, , FSinfo filesystems 5623@comment node-name, next, previous, up 5624@subsection fstype Option 5625@cindex FSinfo fstype filesystems option 5626@cindex fstype, FSinfo filesystems option 5627@cindex export, FSinfo special fstype 5628 5629This specifies the type of filesystem being declared and will be placed 5630into the @file{fstab} file as is. The value of this option will be 5631handed to @code{mount} as the filesystem type---it should have such 5632values as @code{4.2}, @code{nfs} or @code{swap}. The value is not 5633examined for correctness. 5634 5635There is one special case. If the filesystem type is specified as 5636@samp{export} then the filesystem information will not be added to the 5637host's @file{fstab} information, but it will still be visible on the 5638network. This is useful for defining hosts which contain referenced 5639volumes but which are not under full control of @i{FSinfo}. 5640 5641Example: 5642 5643@example 5644fstype = swap 5645@end example 5646 5647@node FSinfo filesystems opts, FSinfo filesystems passno, FSinfo filesystems fstype, FSinfo filesystems 5648@comment node-name, next, previous, up 5649@subsection opts Option 5650@cindex FSinfo opts filesystems option 5651@cindex opts, FSinfo filesystems option 5652 5653This defines any options that should be given to @b{mount}(8) in the 5654@file{fstab} file. For example: 5655 5656@example 5657opts = rw,nosuid,grpid 5658@end example 5659 5660@node FSinfo filesystems passno, FSinfo filesystems freq, FSinfo filesystems opts, FSinfo filesystems 5661@comment node-name, next, previous, up 5662@subsection passno Option 5663@cindex FSinfo passno filesystems option 5664@cindex passno, FSinfo filesystems option 5665 5666This defines the @b{fsck}(8) pass number in which to check the 5667filesystem. This value will be placed into the @file{fstab} file. 5668 5669Example: 5670 5671@example 5672passno = 1 5673@end example 5674 5675@node FSinfo filesystems freq, FSinfo filesystems mount, FSinfo filesystems passno, FSinfo filesystems 5676@comment node-name, next, previous, up 5677@subsection freq Option 5678@cindex FSinfo freq filesystems option 5679@cindex freq, FSinfo filesystems option 5680 5681This defines the interval (in days) between dumps. The value is placed 5682as is into the @file{fstab} file. 5683 5684Example: 5685 5686@example 5687freq = 3 5688@end example 5689 5690@node FSinfo filesystems mount, FSinfo filesystems dumpset, FSinfo filesystems freq, FSinfo filesystems 5691@comment node-name, next, previous, up 5692@subsection mount Option 5693@cindex FSinfo mount filesystems option 5694@cindex mount, FSinfo filesystems option 5695@cindex exportfs, FSinfo mount option 5696@cindex volname, FSinfo mount option 5697@cindex sel, FSinfo mount option 5698 5699This defines the mountpoint at which to place the filesystem. If the 5700mountpoint of the filesystem is specified as @code{default}, then the 5701filesystem will be mounted in the automounter's tree under its volume 5702name and the mount will automatically be inherited by the automounter. 5703 5704Following the mountpoint, namespace information for the filesystem may 5705be described. The options that can be given here are @code{exportfs}, 5706@code{volname} and @code{sel}. 5707 5708The format is: 5709 5710@example 5711mount : "mount" vol_tree ; 5712 5713vol_tree : @i{list(}vol_tree_attr@i{)} ; 5714 5715vol_tree_attr 5716 : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; 5717 5718vol_tree_info 5719 : "exportfs" @var{<export-data>} 5720 | "volname" @var{<volname>} 5721 | "sel" @var{<selector-list>} 5722 ; 5723@end example 5724 5725Example: 5726 5727@example 5728mount default @{ 5729 exportfs "dylan dougal florence zebedee" 5730 volname /vol/andrew 5731@} 5732@end example 5733 5734In the above example, the filesystem currently being declared will have 5735an entry placed into the @file{exports} file allowing the filesystem to 5736be exported to the machines @code{dylan}, @code{dougal}, @code{florence} 5737and @code{zebedee}. The volume name by which the filesystem will be 5738referred to remotely, is @file{/vol/andrew}. By declaring the 5739mountpoint to be @code{default}, the filesystem will be mounted on the 5740local machine in the automounter tree, where @i{Amd} will automatically 5741inherit the mount as @file{/vol/andrew}.@refill 5742 5743@table @samp 5744@item exportfs 5745a string defining which machines the filesystem may be exported to. 5746This is copied, as is, into the @file{exports} file---no sanity checking 5747is performed on this string.@refill 5748 5749@item volname 5750a string which declares the remote name by which to reference the 5751filesystem. The string is entered into a dictionary and allows you to 5752refer to this filesystem in other places by this volume name.@refill 5753 5754@item sel 5755a string which is placed into the automounter maps as a selector for the 5756filesystem.@refill 5757 5758@end table 5759 5760@node FSinfo filesystems dumpset, FSinfo filesystems log, FSinfo filesystems mount, FSinfo filesystems 5761@comment node-name, next, previous, up 5762@subsection dumpset Option 5763@cindex FSinfo dumpset filesystems option 5764@cindex dumpset, FSinfo filesystems option 5765 5766This provides support for Imperial College's local file backup tools and 5767is not documented further here. 5768 5769@node FSinfo filesystems log, , FSinfo filesystems dumpset, FSinfo filesystems 5770@comment node-name, next, previous, up 5771@subsection log Option 5772@cindex FSinfo log filesystems option 5773@cindex log, FSinfo filesystems option 5774 5775Specifies the log device for the current filesystem. This is ignored if 5776not required by the particular filesystem type. 5777 5778@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions 5779@comment node-name, next, previous, up 5780@section @i{FSinfo} static mounts 5781@cindex FSinfo static mounts 5782@cindex Statically mounts filesystems, FSinfo 5783 5784Each host may also have a number of statically mounted filesystems. For 5785example, the host may be a diskless workstation in which case it will 5786have no @code{fs} declarations. In this case the @code{mount} 5787declaration is used to determine from where its filesystems will be 5788mounted. In addition to being added to the @file{fstab} file, this 5789information can also be used to generate a suitable @file{bootparams} 5790file.@refill 5791 5792@example 5793mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; 5794 5795localinfo : localinfo_attr @var{<string>} ; 5796 5797localinfo_attr 5798 : "as" 5799 | "from" 5800 | "fstype" 5801 | "opts" 5802 ; 5803@end example 5804 5805The filesystem specified to be mounted will be searched for in the 5806dictionary of volume names built when scanning the list of hosts' 5807definitions. 5808 5809The attributes have the following semantics: 5810@table @samp 5811@item from @var{machine} 5812mount the filesystem from the machine with the hostname of 5813@dfn{machine}.@refill 5814 5815@item as @var{mountpoint} 5816mount the filesystem locally as the name given, in case this is 5817different from the advertised volume name of the filesystem. 5818 5819@item opts @var{options} 5820native @b{mount}(8) options. 5821 5822@item fstype @var{type} 5823type of filesystem to be mounted. 5824@end table 5825 5826An example: 5827 5828@example 5829mount /export/exec/hp300/local as /usr/local 5830@end example 5831 5832If the mountpoint specified is either @file{/} or @file{swap}, the 5833machine will be considered to be booting off the net and this will be 5834noted for use in generating a @file{bootparams} file for the host which 5835owns the filesystems. 5836 5837@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo 5838@comment node-name, next, previous, up 5839@section Defining an @i{Amd} Mount Map in @i{FSinfo} 5840@cindex FSinfo automount definitions 5841@cindex Defining an Amd mount map, FSinfo 5842 5843The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining 5844all the automount trees. @i{FSinfo} takes all the definitions found and 5845builds one map for each top level tree. 5846 5847The automount tree is usually defined last. A single automount 5848configuration will usually apply to an entire management domain. One 5849@code{automount} declaration is needed for each @i{Amd} automount point. 5850@i{FSinfo} determines whether the automount point is @dfn{direct} 5851(@pxref{Direct Automount Filesystem}) or @dfn{indirect} 5852(@pxref{Top-level Filesystem}). Direct automount points are 5853distinguished by the fact that there is no underlying 5854@dfn{automount_tree}.@refill 5855 5856@example 5857automount : "automount" @i{opt(}auto_opts@i{)} automount_tree ; 5858 5859auto_opts : "opts" @var{<mount-options>} ; 5860 5861automount_tree 5862 : @i{list(}automount_attr@i{)} 5863 ; 5864 5865automount_attr 5866 : @var{<string>} "=" @var{<volname>} 5867 | @var{<string>} "->" @var{<symlink>} 5868 | @var{<string>} "@{" automount_tree "@}" 5869 ; 5870@end example 5871 5872If @var{<mount-options>} is given, then it is the string to be placed in 5873the maps for @i{Amd} for the @code{opts} option. 5874 5875A @dfn{map} is typically a tree of filesystems, for example @file{home} 5876normally contains a tree of filesystems representing other machines in 5877the network. 5878 5879A map can either be given as a name representing an already defined 5880volume name, or it can be a tree. A tree is represented by placing 5881braces after the name. For example, to define a tree @file{/vol}, the 5882following map would be defined: 5883 5884@example 5885automount /vol @{ @} 5886@end example 5887 5888Within a tree, the only items that can appear are more maps. 5889For example: 5890 5891@example 5892automount /vol @{ 5893 andrew @{ @} 5894 X11 @{ @} 5895@} 5896@end example 5897 5898In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} 5899and @file{/vol/X11} and a map entry will be generated for each. If the 5900volumes are defined more than once, then @i{FSinfo} will generate 5901a series of alternate entries for them in the maps.@refill 5902 5903Instead of a tree, either a link (@var{name} @code{->} 5904@var{destination}) or a reference can be specified (@var{name} @code{=} 5905@var{destination}). A link creates a symbolic link to the string 5906specified, without further processing the entry. A reference will 5907examine the destination filesystem and optimize the reference. For 5908example, to create an entry for @code{njw} in the @file{/homes} map, 5909either of the two forms can be used:@refill 5910 5911@example 5912automount /homes @{ 5913 njw -> /home/dylan/njw 5914@} 5915@end example 5916 5917or 5918 5919@example 5920automount /homes @{ 5921 njw = /home/dylan/njw 5922@} 5923@end example 5924 5925In the first example, when @file{/homes/njw} is referenced from @i{Amd}, 5926a link will be created leading to @file{/home/dylan/njw} and the 5927automounter will be referenced a second time to resolve this filename. 5928The map entry would be: 5929 5930@example 5931njw type:=link;fs:=/home/dylan/njw 5932@end example 5933 5934In the second example, the destination directory is analyzed and found 5935to be in the filesystem @file{/home/dylan} which has previously been 5936defined in the maps. Hence the map entry will look like: 5937 5938@example 5939njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw 5940@end example 5941 5942Creating only one symbolic link, and one access to @i{Amd}. 5943 5944@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo 5945@comment node-name, next, previous, up 5946@section @i{FSinfo} Command Line Options 5947@cindex FSinfo command line options 5948@cindex Command line options, FSinfo 5949 5950@i{FSinfo} is started from the command line by using the command: 5951 5952@example 5953fsinfo [@i{options}] @i{files} ... 5954@end example 5955 5956The input to @i{FSinfo} is a single set of definitions of machines and 5957automount maps. If multiple files are given on the command-line, then 5958the files are concatenated together to form the input source. The files 5959are passed individually through the C pre-processor before being parsed. 5960 5961Several options define a prefix for the name of an output file. If the 5962prefix is not specified no output of that type is produced. The suffix 5963used will correspond either to the hostname to which a file belongs, or 5964to the type of output if only one file is produced. Dumpsets and the 5965@file{bootparams} file are in the latter class. To put the output into 5966a subdirectory simply put a @file{/} at the end of the prefix, making 5967sure that the directory has already been made before running 5968@i{Fsinfo}. 5969 5970@menu 5971* -a FSinfo Option:: Amd automount directory: 5972* -b FSinfo Option:: Prefix for bootparams files. 5973* -d FSinfo Option:: Prefix for dumpset data files. 5974* -e FSinfo Option:: Prefix for exports files. 5975* -f FSinfo Option:: Prefix for fstab files. 5976* -h FSinfo Option:: Local hostname. 5977* -m FSinfo Option:: Prefix for automount maps. 5978* -q FSinfo Option:: Ultra quiet mode. 5979* -v FSinfo Option:: Verbose mode. 5980* -I FSinfo Option:: Define new #include directory. 5981* -D-FSinfo Option:: Define macro. 5982* -U FSinfo Option:: Undefine macro. 5983@end menu 5984 5985@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options 5986@comment node-name, next, previous, up 5987@subsection @code{-a} @var{autodir} 5988 5989Specifies the directory name in which to place the automounter's 5990mountpoints. This defaults to @file{/a}. Some sites have the autodir set 5991to be @file{/amd}, and this would be achieved by: 5992 5993@example 5994fsinfo -a /amd ... 5995@end example 5996 5997@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options 5998@comment node-name, next, previous, up 5999@subsection @code{-b} @var{bootparams} 6000@cindex bootparams, FSinfo prefix 6001 6002This specifies the prefix for the @file{bootparams} filename. If it is 6003not given, then the file will not be generated. The @file{bootparams} 6004file will be constructed for the destination machine and will be placed 6005into a file named @file{bootparams} and prefixed by this string. The 6006file generated contains a list of entries describing each diskless 6007client that can boot from the destination machine. 6008 6009As an example, to create a @file{bootparams} file in the directory 6010@file{generic}, the following would be used: 6011 6012@example 6013fsinfo -b generic/ ... 6014@end example 6015 6016@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options 6017@comment node-name, next, previous, up 6018@subsection @code{-d} @var{dumpsets} 6019@cindex dumpset, FSinfo prefix 6020 6021This specifies the prefix for the @file{dumpsets} file. If it is not 6022specified, then the file will not be generated. The file will be for 6023the destination machine and will be placed into a filename 6024@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is 6025for use by Imperial College's local backup system. 6026 6027For example, to create a @file{dumpsets} file in the directory @file{generic}, 6028then you would use the following: 6029 6030@example 6031fsinfo -d generic/ ... 6032@end example 6033 6034@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options 6035@comment node-name, next, previous, up 6036@subsection @code{-e} @var{exportfs} 6037@cindex exports, FSinfo prefix 6038 6039Defines the prefix for the @file{exports} files. If it is not given, 6040then the file will not be generated. For each machine defined in the 6041configuration files as having disks, an @file{exports} file is 6042constructed and given a filename determined by the name of the machine, 6043prefixed with this string. If a machine is defined as diskless, then no 6044@file{exports} file will be created for it. The files contain entries 6045for directories on the machine that may be exported to clients. 6046 6047Example: To create the @file{exports} files for each diskfull machine 6048and place them into the directory @file{exports}: 6049 6050@example 6051fsinfo -e exports/ ... 6052@end example 6053 6054@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options 6055@comment node-name, next, previous, up 6056@subsection @code{-f} @var{fstab} 6057@cindex fstab, FSinfo prefix 6058 6059This defines the prefix for the @file{fstab} files. The files will only 6060be created if this prefix is defined. For each machine defined in the 6061configuration files, a @file{fstab} file is created with the filename 6062determined by prefixing this string with the name of the machine. These 6063files contain entries for filesystems and partitions to mount at boot 6064time. 6065 6066Example, to create the files in the directory @file{fstabs}: 6067 6068@example 6069fsinfo -f fstabs/ ... 6070@end example 6071 6072@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options 6073@comment node-name, next, previous, up 6074@subsection @code{-h} @var{hostname} 6075@cindex hostname, FSinfo command line option 6076 6077Defines the hostname of the destination machine to process for. If this 6078is not specified, it defaults to the local machine name, as returned by 6079@b{gethostname}(2). 6080 6081Example: 6082 6083@example 6084fsinfo -h dylan.doc.ic.ac.uk ... 6085@end example 6086 6087@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options 6088@comment node-name, next, previous, up 6089@subsection @code{-m} @var{mount-maps} 6090@cindex maps, FSinfo command line option 6091 6092Defines the prefix for the automounter files. The maps will only be 6093produced if this prefix is defined. The mount maps suitable for the 6094network defined by the configuration files will be placed into files 6095with names calculated by prefixing this string to the name of each map. 6096 6097For example, to create the automounter maps and place them in the 6098directory @file{automaps}: 6099 6100@example 6101fsinfo -m automaps/ ... 6102@end example 6103 6104@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options 6105@comment node-name, next, previous, up 6106@subsection @code{-q} 6107@cindex quiet, FSinfo command line option 6108 6109Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and 6110only outputs any error messages which are generated. 6111 6112@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options 6113@comment node-name, next, previous, up 6114@subsection @code{-v} 6115@cindex verbose, FSinfo command line option 6116 6117Selects verbose mode. When this is activated, the program will display 6118more messages, and display all the information discovered when 6119performing the semantic analysis phase. Each verbose message is output 6120to @file{stdout} on a line starting with a @samp{#} character. 6121 6122@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options 6123@comment node-name, next, previous, up 6124@subsection @code{-D} @var{name[=defn]} 6125 6126Defines a symbol @dfn{name} for the preprocessor when reading the 6127configuration files. Equivalent to @code{#define} directive. 6128 6129@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options 6130@comment node-name, next, previous, up 6131@subsection @code{-I} @var{directory} 6132 6133This option is passed into the preprocessor for the configuration files. 6134It specifies directories in which to find include files 6135 6136@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options 6137@comment node-name, next, previous, up 6138@subsection @code{-U} @var{name} 6139 6140Removes any initial definition of the symbol @dfn{name}. Inverse of the 6141@code{-D} option. 6142 6143@node FSinfo errors, , FSinfo Command Line Options, FSinfo 6144@comment node-name, next, previous, up 6145@section Errors produced by @i{FSinfo} 6146@cindex FSinfo error messages 6147 6148The following table documents the errors and warnings which @i{FSinfo} may produce. 6149 6150@table @t 6151 6152@item " expected 6153Occurs if an unescaped newline is found in a quoted string. 6154 6155@item ambiguous mount: @var{volume} is a replicated filesystem 6156If several filesystems are declared as having the same volume name, they 6157will be considered replicated filesystems. To mount a replicated 6158filesystem statically, a specific host will need to be named, to say 6159which particular copy to try and mount, else this error will 6160result. 6161 6162@item can't open @var{filename} for writing 6163Occurs if any errors are encountered when opening an output file. 6164 6165@item cannot determine localname since volname @var{volume} is not uniquely defined 6166If a volume is replicated and an attempt is made to mount the filesystem 6167statically without specifying a local mountpoint, @i{FSinfo} cannot 6168calculate a mountpoint, as the desired pathname would be 6169ambiguous. 6170 6171@item @var{device} has duplicate exportfs data 6172Produced if the @samp{exportfs} option is used multiple times within the 6173same branch of a filesystem definition. For example, if you attempt to 6174set the @samp{exportfs} data at different levels of the mountpoint 6175directory tree. 6176 6177@item dump frequency for @var{host}:@var{device} is non-zero 6178Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6179or @samp{export} and the @samp{dump} option is set to a value greater 6180than zero. Swap devices should not be dumped. 6181 6182@item duplicate host @var{hostname}! 6183If a host has more than one definition. 6184 6185@item end of file within comment 6186A comment was unterminated before the end of one of the configuration 6187files. 6188 6189@item @var{filename}: cannot open for reading 6190If a file specified on the command line as containing configuration data 6191could not be opened. 6192 6193@item @var{filesystem} has a volname but no exportfs data 6194Occurs when a volume name is declared for a file system, but the string 6195specifying what machines the filesystem can be exported to is 6196missing. 6197 6198@item fs field "@var{field-name}" already set 6199Occurs when multiple definitions are given for one of the attributes of a 6200host's filesystem. 6201 6202@item host field "@var{field-name}" already set 6203If duplicate definitions are given for any of the fields with a host 6204definition. 6205 6206@item @var{host}:@var{device} has more than one mount point 6207Occurs if the mount option for a host's filesystem specifies multiple 6208trees at which to place the mountpoint. 6209 6210@item @var{host}:@var{device} has no mount point 6211Occurs if the @samp{mount} option is not specified for a host's 6212filesystem. 6213 6214@item @var{host}:@var{device} needs field "@var{field-name}" 6215Occurs when a filesystem is missing a required field. @var{field-name} could 6216be one of @samp{fstype}, @samp{opts}, @samp{passno} or 6217@samp{mount}. 6218 6219@item @var{host}:mount field specified for swap partition 6220Occurs if a mountpoint is given for a filesystem whose type is declared 6221to be @samp{swap}. 6222 6223@item malformed IP dotted quad: @var{address} 6224If the Internet address of an interface is incorrectly specified. An 6225Internet address definition is handled to @b{inet_addr}(3N) to see if it 6226can cope. If not, then this message will be displayed. 6227 6228@item malformed netmask: @var{netmask} 6229If the netmask cannot be decoded as though it were a hexadecimal number, 6230then this message will be displayed. It will typically be caused by 6231incorrect characters in the @var{netmask} value. 6232 6233@item mount field "@var{field-name}" already set 6234Occurs when a static mount has multiple definitions of the same field. 6235 6236@item mount tree field "@var{field-name}" already set 6237Occurs when the @var{field-name} is defined more than once during the 6238definition of a filesystems mountpoint. 6239 6240@item netif field @var{field-name} already set 6241Occurs if you attempt to define an attribute of an interface more than 6242once. 6243 6244@item network booting requires both root and swap areas 6245Occurs if a machine has mount declarations for either the root partition 6246or the swap area, but not both. You cannot define a machine to only 6247partially boot via the network. 6248 6249@item no disk mounts on @var{hostname} 6250If there are no static mounts, nor local disk mounts specified for a 6251machine, this message will be displayed. 6252 6253@item no volname given for @var{host}:@var{device} 6254Occurs when a filesystem is defined to be mounted on @file{default}, but 6255no volume name is given for the file system, then the mountpoint cannot 6256be determined. 6257 6258@item not allowed '/' in a directory name 6259Occurs when a pathname with multiple directory elements is specified as 6260the name for an automounter tree. A tree should only have one name at 6261each level. 6262 6263@item pass number for @var{host}:@var{device} is non-zero 6264Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6265or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices should not be 6266fsck'd. @xref{FSinfo filesystems fstype}. 6267 6268@item sub-directory @var{directory} of @var{directory-tree} starts with '/' 6269Within the filesystem specification for a host, if an element 6270@var{directory} of the mountpoint begins with a @samp{/} and it is not 6271the start of the tree. 6272 6273@item sub-directory of @var{directory-tree} is named "default" 6274@samp{default} is a keyword used to specify if a mountpoint should be 6275automatically calculated by @i{FSinfo}. If you attempt to specify a 6276directory name as this, it will use the filename of @file{default} but 6277will produce this warning. 6278 6279@item unknown \ sequence 6280Occurs if an unknown escape sequence is found inside a string. Within a 6281string, you can give the standard C escape sequences for strings, such 6282as newlines and tab characters. 6283 6284@item unknown directory attribute 6285If an unknown keyword is found while reading the definition of a host's 6286filesystem mount option. 6287 6288@item unknown filesystem attribute 6289Occurs if an unrecognized keyword is used when defining a host's 6290filesystems. 6291 6292@item unknown host attribute 6293Occurs if an unrecognized keyword is used when defining a host. 6294 6295@item unknown mount attribute 6296Occurs if an unrecognized keyword is found while parsing the list of 6297static mounts. 6298 6299@item unknown volname @var{volume} automounted @i{[} on @i{name} @i{]} 6300Occurs if @var{volume} is used in a definition of an automount map but the volume 6301name has not been declared during the host filesystem definitions. 6302 6303@item volname @var{volume} is unknown 6304Occurs if an attempt is made to mount or reference a volume name which 6305has not been declared during the host filesystem definitions. 6306 6307@item volname @var{volume} not exported from @var{machine} 6308Occurs if you attempt to mount the volume @var{volume} from a machine 6309which has not declared itself to have such a filesystem 6310available. 6311 6312@end table 6313 6314@c ################################################################ 6315@node Hlfsd, Assorted Tools, FSinfo, Top 6316@comment node-name, next, previous, up 6317@chapter Hlfsd 6318@pindex Hlfsd 6319@cindex Home-Link Filesystem 6320 6321@i{Hlfsd} is a daemon which implements a filesystem containing a 6322symbolic link to subdirectory within a user's home directory, depending 6323on the user which accessed that link. It was primarily designed to 6324redirect incoming mail to users' home directories, so that it can be read 6325from anywhere. It was designed and implemented by 6326@email{ezk@@cs.columbia.edu,Erez Zadok} and 6327@email{dupuy@@cs.columbia.edu,Alexander Dupuy}, at the 6328@uref{http://www.cs.columbia.edu/,Computer Science Department} of 6329@uref{http://www.columbia.edu/,Columbia University}. A 6330@uref{http://www.cs.columbia.edu/~ezk/research/hlfsd/hlfsd.html,paper} 6331on @i{Hlfsd} was presented at the Usenix LISA VII conference in 1993. 6332 6333@i{Hlfsd} operates by mounting itself as an NFS server for the directory 6334containing @i{linkname}, which defaults to @file{/hlfs/home}. Lookups 6335within that directory are handled by @i{Hlfsd}, which uses the 6336password map to determine how to resolve the lookup. The directory will 6337be created if it doesn't already exist. The symbolic link will be to 6338the accessing user's home directory, with @i{subdir} appended to it. If 6339not specified, @i{subdir} defaults to @file{.hlfsdir}. This directory 6340will also be created if it does not already exist. 6341 6342A @samp{SIGTERM} sent to @i{Hlfsd} will cause it to shutdown. A @samp{SIGHUP} will 6343flush the internal caches, and reload the password map. It will also 6344close and reopen the log file, to enable the original log file to be 6345removed or rotated. A @samp{SIGUSR1} will cause it to dump its internal table 6346of user IDs and home directories to the file @file{/tmp/hlfsddump}. 6347 6348@menu 6349* Introduction to Hlfsd:: 6350* Background to Mail Delivery:: 6351* Using Hlfsd:: 6352@end menu 6353 6354@c ================================================================ 6355@node Introduction to Hlfsd, Background to Mail Delivery, Hlfsd, Hlfsd 6356@comment node-name, next, previous, up 6357@section Introduction to Hlfsd 6358@cindex Introduction to Hlfsd 6359@cindex Hlfsd; introduction 6360 6361Electronic mail has become one of the major applications for many 6362computer networks, and use of this service is expected to increase over 6363time, as networks proliferate and become faster. Providing a convenient 6364environment for users to read, compose, and send electronic mail has 6365become a requirement for systems administrators (SAs). 6366 6367Widely used methods for handling mail usually require users to be logged 6368into a designated ``home'' machine, where their mailbox files reside. 6369Only on that one machine can they read newly arrived mail. Since users 6370have to be logged into that system to read their mail, they often find 6371it convenient to run all of their other processes on that system as 6372well, including memory and CPU-intensive jobs. For example, in our 6373department, we have allocated and configured several multi-processor 6374servers to handle such demanding CPU/memory applications, but these were 6375underutilized, in large part due to the inconvenience of not being able 6376to read mail on those machines. (No home directories were located on 6377these designated CPU-servers, since we did not want NFS service for 6378users' home directories to have to compete with CPU-intensive jobs. At the 6379same time, we discouraged users from running demanding applications on 6380their home machines.) 6381 6382Many different solutions have been proposed to allow users to read their 6383mail on any host. However, all of these solutions fail in one or more 6384of several ways: 6385 6386@itemize @bullet 6387 6388@item 6389they introduce new single points of failure 6390 6391@item 6392they require using different mail transfer agents (MTAs) or user agents 6393(UAs) 6394 6395@item 6396they do not solve the problem for all cases, i.e. the solution is only 6397partially successful for a particular environment. 6398 6399@end itemize 6400 6401We have designed a simple filesystem, called the @dfn{Home-Link File 6402System}, to provide the ability to deliver mail to users' home 6403directories, without modification to mail-related applications. We have 6404endeavored to make it as stable as possible. Of great importance to us 6405was to make sure the HLFS daemon, @file{hlfsd} , would not hang under 6406any circumstances, and would take the next-best action when faced with 6407problems. Compared to alternative methods, @i{Hlfsd} is a stable, more 6408general solution, and easier to install/use. In fact, in some ways, we 6409have even managed to improve the reliability and security of mail 6410service. 6411 6412Our server implements a small filesystem containing a symbolic link 6413to a subdirectory of the invoking user's home directory, and named symbolic 6414links to users' mailbox files. 6415 6416The @i{Hlfsd} server finds out the @var{uid} of the process that is 6417accessing its mount point, and resolves the pathname component @samp{home} as a 6418symbolic link to a subdirectory within the home directory given by the 6419@var{uid}'s entry in the password file. If the @var{gid} of the process 6420that attempts to access a mailbox file is a special one (called 6421HLFS_GID), then the server maps the name of the @emph{next} pathname 6422component directly to the user's mailbox. This is necessary so that 6423access to a mailbox file by users other than the owner can succeed. The 6424server has safety features in case of failures such as hung filesystems 6425or home directory filesystems that are inaccessible or full. 6426 6427On most of our machines, mail gets delivered to the directory 6428@file{/var/spool/mail}. Many programs, including UAs, depend on that 6429path. @i{Hlfsd} creates a directory @file{/mail}, and mounts itself on 6430top of that directory. @i{Hlfsd} implements the path name component 6431called @samp{home}, pointing to a subdirectory of the user's home directory. 6432We have made @file{/var/spool/mail} a symbolic link to 6433@file{/mail/home}, so that accessing @file{/var/spool/mail} actually 6434causes access to a subdirectory within a user's home directory. 6435 6436The following table shows an example of how resolving the pathname 6437@file{/var/mail/@i{NAME}} to @file{/users/ezk/.mailspool/@i{NAME}} proceeds. 6438 6439@multitable {Resolving Component} {Pathname left to resolve} {Value if symbolic link} 6440 6441@item @b{Resolving Component} 6442@tab @b{Pathname left to resolve} 6443@tab @b{Value if symbolic link} 6444 6445@item @t{/} 6446@tab @t{var/mail/}@i{NAME} 6447 6448@item @t{var/} 6449@tab @t{mail/}@i{NAME} 6450 6451@item @t{mail}@@ 6452@tab @t{/mail/home/}@i{NAME} 6453@tab @t{mail}@@ -> @t{/mail/home} 6454 6455@item @t{/} 6456@tab @t{mail/home/}@i{NAME} 6457 6458@item @t{mail/} 6459@tab @t{home/}@i{NAME} 6460 6461@item @t{home}@@ 6462@tab @i{NAME} 6463@tab @t{home}@@ -> @t{/users/ezk/.mailspool} 6464 6465@item @t{/} 6466@tab @t{users/ezk/.mailspool/}@i{NAME} 6467 6468@item @t{users/} 6469@tab @t{ezk/.mailspool/}@i{NAME} 6470 6471@item @t{ezk/} 6472@tab @t{.mailspool/}@i{NAME} 6473 6474@item @t{.mailspool/} 6475@tab @i{NAME} 6476 6477@item @i{NAME} 6478 6479@end multitable 6480 6481@c ================================================================ 6482@node Background to Mail Delivery, Using Hlfsd, Introduction to Hlfsd, Hlfsd 6483@comment node-name, next, previous, up 6484@section Background to Mail Delivery 6485@cindex Background to Mail Delivery 6486@cindex Hlfsd; background 6487 6488This section provides an in-depth discussion of why available methods 6489for delivering mail to home directories are not as good as the one used 6490by @i{Hlfsd}. 6491 6492@menu 6493* Single-Host Mail Spool Directory:: 6494* Centralized Mail Spool Directory:: 6495* Distributed Mail Spool Service:: 6496* Why Deliver Into the Home Directory?:: 6497@end menu 6498 6499@c ---------------------------------------------------------------- 6500@node Single-Host Mail Spool Directory, Centralized Mail Spool Directory, Background to Mail Delivery, Background to Mail Delivery 6501@comment node-name, next, previous, up 6502@subsection Single-Host Mail Spool Directory 6503@cindex Single-Host Mail Spool Directory 6504 6505The most common method for mail delivery is for mail to be appended to a 6506mailbox file in a standard spool directory on the designated ``mail 6507home'' machine of the user. The greatest advantage of this method is 6508that it is the default method most vendors provide with their systems, 6509thus very little (if any) configuration is required on the SA's part. 6510All they need to set up are mail aliases directing mail to the host on 6511which the user's mailbox file is assigned. (Otherwise, mail is 6512delivered locally, and users find mailboxes on many machines.) 6513 6514As users become more sophisticated, and aided by windowing systems, they 6515find themselves logging in on multiple hosts at once, performing several 6516tasks concurrently. They ask to be able to read their mail on any host 6517on the network, not just the one designated as their ``mail home''. 6518 6519@c ---------------------------------------------------------------- 6520@node Centralized Mail Spool Directory, Distributed Mail Spool Service, Single-Host Mail Spool Directory, Background to Mail Delivery 6521@comment node-name, next, previous, up 6522@subsection Centralized Mail Spool Directory 6523@cindex Centralized Mail Spool Directory 6524 6525A popular method for providing mail readability from any host is to have 6526all mail delivered to a mail spool directory on a designated 6527``mail-server'' which is exported via NFS to all of the hosts on the 6528network. Configuring such a system is relatively easy. On most 6529systems, the bulk of the work is a one-time addition to one or two 6530configuration files in @file{/etc}. The file-server's spool directory 6531is then hard-mounted across every machine on the local network. In 6532small environments with only a handful of hosts this can be an 6533acceptable solution. In our department, with a couple of hundred active 6534hosts and thousands of mail messages processed daily, this was deemed 6535completely unacceptable, as it introduced several types of problems: 6536 6537@table @b 6538 6539@item Scalability and Performance 6540 6541As more and more machines get added to the network, more mail traffic 6542has to go over NFS to and from the mail-server. Users like to run 6543mail-watchers, and read their mail often. The stress on the shared 6544infrastructure increases with every user and host added; loads on the 6545mail server would most certainly be high since all mail delivery goes 6546through that one machine.@footnote{ Delivery via NFS-mounted filesystems 6547may require usage of @samp{rpc.lockd} and @samp{rpc.statd} to provide 6548distributed file-locking, both of which are widely regarded as unstable 6549and unreliable. Furthermore, this will degrade performance, as local 6550processes as well as remote @samp{nfsd} processes are kept busy.} This 6551leads to lower reliability and performance. To reduce the number of 6552concurrent connections between clients and the server host, some SAs 6553have resorted to automounting the mail-spool directory. But this 6554solution only makes things worse: since users often run mail watchers, 6555and many popular applications such as @samp{trn}, @samp{emacs}, 6556@samp{csh} or @samp{ksh} check periodically for new mail, the 6557automounted directory would be effectively permanently mounted. If it 6558gets unmounted automatically by the automounter program, it is most 6559likely to get mounted shortly afterwards, consuming more I/O resources 6560by the constant cycle of mount and umount calls. 6561 6562@item Reliability 6563 6564The mail-server host and its network connectivity must be very reliable. 6565Worse, since the spool directory has to be hard-mounted,@footnote{No SA 6566in their right minds would soft-mount read/write partitions --- the 6567chances for data loss are too great.} many processes which access the 6568spool directory (various shells, @samp{login}, @samp{emacs}, etc.) 6569would be hung as long as connectivity to the mail-server is severed. To 6570improve reliability, SAs may choose to backup the mail-server's spool 6571partition several times a day. This may make things worse since reading 6572or delivering mail while backups are in progress may cause backups to be 6573inconsistent; more backups consume more backup-media resources, and 6574increase the load on the mail-server host. 6575 6576@end table 6577 6578@c ---------------------------------------------------------------- 6579@node Distributed Mail Spool Service, Why Deliver Into the Home Directory?, Centralized Mail Spool Directory, Background to Mail Delivery 6580@comment node-name, next, previous, up 6581@subsection Distributed Mail Spool Service 6582@cindex Distributed Mail Spool Service 6583 6584Despite the existence of a few systems that support delivery to users' 6585home directories, mail delivery to home directories hasn't caught on. 6586We believe the main reason is that there are too many programs that 6587``know'' where mailbox files reside. Besides the obvious (the delivery 6588program @file{/bin/mail} and mail readers like @file{/usr/ucb/Mail}, 6589@samp{mush}, @samp{mm}, etc.), other programs that know mailbox location 6590are login, from, almost every shell, @samp{xbiff}, @samp{xmailbox}, and 6591even some programs not directly related to mail, such as @samp{emacs} 6592and @samp{trn}. Although some of these programs can be configured to 6593look in different directories with the use of environment variables and 6594other resources, many of them cannot. The overall porting work is 6595significant. 6596 6597Other methods that have yet to catch on require the use of a special 6598mail-reading server, such as IMAP or POP. The main disadvantage of 6599these systems is that UAs need to be modified to use these services --- 6600a long and involved task. That is why they are not popular at this 6601time. 6602 6603Several other ideas have been proposed and even used in various 6604environments. None of them is robust. They are mostly very 6605specialized, inflexible, and do not extend to the general case. Some of 6606the ideas are plain bad, potentially leading to lost or corrupt mail: 6607 6608@table @b 6609 6610@item automounters 6611 6612Using an automounter such as @i{Amd} to provide a set of symbolic links 6613from the normal spool directory to user home directories is not 6614sufficient. UAs rename, unlink, and recreate the mailbox as a regular 6615file, therefore it must be a real file, not a symbolic link. 6616Furthermore, it must reside in a real directory which is writable by the 6617UAs and MTAs. This method may also require populating 6618@file{/var/spool/mail} with symbolic links and making sure they are 6619updated. Making @i{Amd} manage that directory directly fails, since 6620many various lock files need to be managed as well. Also, @i{Amd} does 6621not provide all of the NFS operations which are required to write mail 6622such as write, create, remove, and unlink. 6623 6624@item @code{$MAIL} 6625 6626Setting this variable to an automounted directory pointing to the user's 6627mail spool host only solves the problem for those programs which know 6628and use @code{$MAIL}. Many programs don't, therefore this solution is partial 6629and of limited flexibility. Also, it requires the SAs or the users to 6630set it themselves --- an added level of inconvenience and possible 6631failures. 6632 6633@item @t{/bin/mail} 6634 6635Using a different mail delivery agent could be the solution. One such 6636example is @samp{hdmail}. However, @samp{hdmail} still requires 6637modifying all UAs, the MTA's configuration, installing new daemons, and 6638changing login scripts. This makes the system less upgradable or 6639compatible with others, and adds one more complicated system for SAs to 6640deal with. It is not a complete solution because it still requires each 6641user have their @code{$MAIL} variable setup correctly, and that every program 6642use this variable. 6643 6644@end table 6645 6646@c ---------------------------------------------------------------- 6647@node Why Deliver Into the Home Directory?, , Distributed Mail Spool Service, Background to Mail Delivery 6648@comment node-name, next, previous, up 6649@subsection Why Deliver Into the Home Directory? 6650@cindex Why Deliver Into the Home Directory? 6651@cindex Hlfsd; Why Deliver Into the Home Directory? 6652 6653There are several major reasons why SAs might want to deliver mail 6654directly into the users' home directories: 6655 6656@table @b 6657 6658@item Location 6659 6660Many mail readers need to move mail from the spool directory to the 6661user's home directory. It speeds up this operation if the two are on 6662the same filesystem. If for some reason the user's home directory is 6663inaccessible, it isn't that useful to be able to read mail, since there 6664is no place to move it to. In some cases, trying to move mail to a 6665non-existent or hung filesystem may result in mail loss. 6666 6667@item Distribution 6668 6669Having all mail spool directories spread among the many more filesystems 6670minimizes the chances that complete environments will grind to a halt 6671when a single server is down. It does increase the chance that there 6672will be someone who is not able to read their mail when a machine is 6673down, but that is usually preferred to having no one be able to read 6674their mail because a centralized mail server is down. The problem of 6675losing some mail due to the (presumably) higher chances that a user's 6676machine is down is minimized in HLFS. 6677 6678@item Security 6679 6680Delivering mail to users' home directories has another advantage --- 6681enhanced security and privacy. Since a shared system mail spool 6682directory has to be world-readable and searchable, any user can see 6683whether other users have mail, when they last received new mail, or when 6684they last read their mail. Programs such as @samp{finger} display this 6685information, which some consider an infringement of privacy. While it 6686is possible to disable this feature of @samp{finger} so that remote 6687users cannot see a mailbox file's status, this doesn't prevent local 6688users from getting the information. Furthermore, there are more 6689programs which make use of this information. In shared environments, 6690disabling such programs has to be done on a system-wide basis, but with 6691mail delivered to users' home directories, users less concerned with 6692privacy who do want to let others know when they last received or read 6693mail can easily do so using file protection bits. 6694 6695@c Lastly, on systems that do not export their NFS filesystem with 6696@c @t{anon=0}, superusers are less likely to snoop around others' mail, as 6697@c they become ``nobodies'' across NFS. 6698 6699@end table 6700 6701In summary, delivering mail to home directories provides users the 6702functionality sought, and also avoids most of the problems just 6703discussed. 6704 6705@c ================================================================ 6706@node Using Hlfsd, , Background to Mail Delivery, Hlfsd 6707@comment node-name, next, previous, up 6708@section Using Hlfsd 6709@cindex Using Hlfsd 6710@cindex Hlfsd; using 6711 6712@menu 6713* Controlling Hlfsd:: 6714* Hlfsd Options:: 6715* Hlfsd Files:: 6716@end menu 6717 6718@c ---------------------------------------------------------------- 6719@node Controlling Hlfsd, Hlfsd Options, Using Hlfsd, Using Hlfsd 6720@comment node-name, next, previous, up 6721@subsection Controlling Hlfsd 6722@cindex Controlling Hlfsd 6723@cindex Hlfsd; controlling 6724@pindex ctl-hlfsd 6725 6726Much the same way @i{Amd} is controlled by @file{ctl-amd}, so does 6727@i{Hlfsd} get controlled by the @file{ctl-hlfsd} script: 6728 6729@table @t 6730 6731@item ctl-hlfsd start 6732Start a new @i{Hlfsd}. 6733 6734@item ctl-hlfsd stop 6735Stop a running @i{Hlfsd}. 6736 6737@item ctl-hlfsd restart 6738Stop a running @i{Hlfsd}, wait for 10 seconds, and then start a new 6739one. It is hoped that within 10 seconds, the previously running 6740@i{Hlfsd} terminate properly; otherwise, starting a second one could 6741cause system lockup. 6742 6743@end table 6744 6745For example, on our systems, we start @i{Hlfsd} within @file{ctl-hlfsd} 6746as follows on Solaris 2 systems: 6747 6748@example 6749hlfsd -a /var/alt_mail -x all -l /var/log/hlfsd /mail/home .mailspool 6750@end example 6751 6752The directory @file{/var/alt_mail} is a directory in the root partition 6753where alternate mail will be delivered into, when it cannot be delivered 6754into the user's home directory. 6755 6756Normal mail gets delivered into @file{/var/mail}, but on our systems, 6757that is a symbolic link to @file{/mail/home}. @file{/mail} is managed 6758by @i{Hlfsd}, which creates a dynamic symlink named @samp{home}, 6759pointing to the subdirectory @file{.mailspool} @emph{within} the 6760accessing user's home directory. This results in mail which normally 6761should go to @file{/var/mail/@code{$USER}}, to go to 6762@file{@code{$HOME}/.mailspool/@code{$USER}}. 6763 6764@i{Hlfsd} does not create the @file{/var/mail} symlink. This needs to 6765be created (manually) once on each host, by the system administrators, 6766as follows: 6767 6768@example 6769mv /var/mail /var/alt_mail 6770ln -s /mail/home /var/mail 6771@end example 6772 6773@c ---------------------------------------------------------------- 6774@node Hlfsd Options, Hlfsd Files, Controlling Hlfsd, Using Hlfsd 6775@comment node-name, next, previous, up 6776@subsection Hlfsd Options 6777@cindex Hlfsd Options 6778@cindex Hlfsd; Options 6779 6780@table @t 6781 6782@item -a @var{alt_dir} 6783Alternate directory. The name of the directory to which the symbolic 6784link returned by @i{Hlfsd} will point, if it cannot access the home 6785directory of the user. This defaults to @file{/var/hlfs}. This 6786directory will be created if it doesn't exist. It is expected that 6787either users will read these files, or the system administrators will 6788run a script to resend this ``lost mail'' to its owner. 6789 6790@item -c @var{cache-interval} 6791Caching interval. @i{Hlfsd} will cache the validity of home directories 6792for this interval, in seconds. Entries which have been verified within 6793the last @var{cache-interval} seconds will not be verified again, since 6794the operation could be expensive, and the entries are most likely still 6795valid. After the interval has expired, @i{Hlfsd} will re-verify the 6796validity of the user's home directory, and reset the cache time-counter. 6797The default value for @var{cache-interval} is 300 seconds (5 minutes). 6798 6799@item -f 6800Force fast startup. This option tells @i{Hlfsd} to skip startup-time 6801consistency checks such as existence of mount directory, alternate spool 6802directory, symlink to be hidden under the mount directory, their 6803permissions and validity. 6804 6805@item -g @var{group} 6806Set the special group HLFS_GID to @var{group}. Programs such as 6807@file{/usr/ucb/from} or @file{/usr/sbin/in.comsat}, which access the 6808mailboxes of other users, must be setgid @samp{HLFS_GID} to work properly. The 6809default group is @samp{hlfs}. If no group is provided, and there is no 6810group @samp{hlfs}, this feature is disabled. 6811 6812@item -h 6813Help. Print a brief help message, and exit. 6814 6815@item -i @var{reload-interval} 6816Map-reloading interval. Each @var{reload-interval} seconds, @i{Hlfsd} 6817will reload the password map. @i{Hlfsd} needs the password map for the 6818UIDs and home directory pathnames. @i{Hlfsd} schedules a @samp{SIGALRM} to 6819reload the password maps. A @samp{SIGHUP} sent to @i{Hlfsd} will force it to 6820reload the maps immediately. The default value for 6821@var{reload-interval} is 900 seconds (15 minutes.) 6822 6823@item -l @var{logfile} 6824Specify a log file to which @i{Hlfsd} will record events. If 6825@var{logfile} is the string @samp{syslog} then the log messages will be 6826sent to the system log daemon by @b{syslog}(3), using the @samp{LOG_DAEMON} 6827facility. This is also the default. 6828 6829@item -n 6830No verify. @i{Hlfsd} will not verify the validity of the symbolic link 6831it will be returning, or that the user's home directory contains 6832sufficient disk-space for spooling. This can speed up @i{Hlfsd} at the 6833cost of possibly returning symbolic links to home directories which are 6834not currently accessible or are full. By default, @i{Hlfsd} validates 6835the symbolic-link in the background. The @code{-n} option overrides the 6836meaning of the @code{-c} option, since no caching is necessary. 6837 6838@item -o @var{mount-options} 6839Mount options which @i{Hlfsd} will use to mount itself on top of 6840@var{dirname}. By default, @var{mount-options} is set to @samp{ro}. If 6841the system supports symbolic-link caching, default options are set 6842to @samp{ro,nocache}. 6843 6844@item -p 6845Print PID. Outputs the process-id of @i{Hlfsd} to standard output where 6846it can be saved into a file. 6847 6848@item -v 6849Version. Displays version information to standard error. 6850 6851@item -x @var{log-options} 6852Specify run-time logging options. The options are a comma separated 6853list chosen from: @samp{fatal}, @samp{error}, @samp{user}, @samp{warn}, @samp{info}, @samp{map}, @samp{stats}, @samp{all}. 6854 6855@item -C 6856Force @i{Hlfsd} to run on systems that cannot turn off the NFS 6857attribute-cache. Use of this option on those systems is discouraged, as 6858it may result in loss or misdelivery of mail. The option is ignored on 6859systems that can turn off the attribute-cache. 6860 6861@item -D @var{log-options} 6862Select from a variety of debugging options. Prefixing an option with 6863the string @samp{no} reverses the effect of that option. Options are 6864cumulative. The most useful option is @samp{all}. Since this option is 6865only used for debugging other options are not documented here. A fuller 6866description is available in the program source. A @samp{SIGUSR1} sent 6867to @i{Hlfsd} will cause it to dump its internal password map to the file 6868@file{/usr/tmp/hlfsd.dump.XXXXXX}, where @samp{XXXXXX} will be replaced 6869by a random string generated by @b{mktemp}(3) or (the more secure) 6870@b{mkstemp}(3). 6871 6872@item -P @var{password-file} 6873Read the user-name, user-id, and home directory information from the 6874file @var{password-file}. Normally, @i{Hlfsd} will use @b{getpwent}(3) 6875to read the password database. This option allows you to override the 6876default database, and is useful if you want to map users' mail files to 6877a directory other than their home directory. Only the username, uid, 6878and home-directory fields of the file @var{password-file} are read and 6879checked. All other fields are ignored. The file @var{password-file} 6880must otherwise be compliant with Unix Version 7 colon-delimited format 6881@b{passwd}(4). 6882 6883@end table 6884 6885@c ---------------------------------------------------------------- 6886@node Hlfsd Files, , Hlfsd Options, Using Hlfsd 6887@comment node-name, next, previous, up 6888@subsection Hlfsd Files 6889@cindex Hlfsd Files 6890@cindex Hlfsd; Files 6891 6892The following files are used by @i{Hlfsd}: 6893 6894@table @file 6895 6896@item /hlfs 6897directory under which @i{Hlfsd} mounts itself and manages the symbolic 6898link @file{home}. 6899 6900@item .hlfsdir 6901default sub-directory in the user's home directory, to which the 6902@file{home} symbolic link returned by @i{Hlfsd} points. 6903 6904@item /var/hlfs 6905directory to which @file{home} symbolic link returned by @i{Hlfsd} 6906points if it is unable to verify the that user's home directory is 6907accessible. 6908 6909@end table 6910 6911For discussion on other files used by @i{Hlfsd}, see @xref{lostaltmail}, and 6912@ref{lostaltmail.conf-sample}. 6913 6914@c ################################################################ 6915@node Assorted Tools, Examples, Hlfsd, Top 6916@comment node-name, next, previous, up 6917@chapter Assorted Tools 6918@cindex Assorted Tools 6919 6920The following are additional utilities and scripts included with 6921am-utils, and get installed. 6922 6923@menu 6924* am-eject:: 6925* amd.conf-sample:: 6926* amd2ldif:: 6927* amd2sun:: 6928* automount2amd:: 6929* ctl-amd:: 6930* ctl-hlfsd:: 6931* expn:: 6932* fix-amd-map:: 6933* fixmount:: 6934* fixrmtab:: 6935* lostaltmail:: 6936* lostaltmail.conf-sample:: 6937* mk-amd-map:: 6938* pawd:: 6939* wait4amd:: 6940* wait4amd2die:: 6941* wire-test:: 6942@end menu 6943 6944@c ---------------------------------------------------------------- 6945@node am-eject, amd.conf-sample, Assorted Tools, Assorted Tools 6946@comment node-name, next, previous, up 6947@section am-eject 6948@pindex am-eject 6949 6950A shell script unmounts a floppy or CD-ROM that is automounted, and 6951then attempts to eject the removable device. 6952 6953@c ---------------------------------------------------------------- 6954@node amd.conf-sample, amd2ldif, am-eject, Assorted Tools 6955@comment node-name, next, previous, up 6956@section amd.conf-sample 6957@pindex amd.conf-sample 6958 6959A sample @i{Amd} configuration file. @xref{Amd Configuration File}. 6960 6961@c ---------------------------------------------------------------- 6962@node amd2ldif, amd2sun, amd.conf-sample, Assorted Tools 6963@comment node-name, next, previous, up 6964@section amd2ldif 6965@pindex amd2ldif 6966 6967A script to convert @i{Amd} maps to LDAP input files. Use it as follows: 6968 6969@example 6970amd2ldif @i{mapname} @i{base} < @i{amd.mapfile} > @i{mapfile.ldif} 6971@end example 6972 6973@c ---------------------------------------------------------------- 6974@node amd2sun, automount2amd, amd2ldif, Assorted Tools 6975@comment node-name, next, previous, up 6976@section amd2sun 6977@pindex amd2sun 6978 6979A script to convert @i{Amd} maps to Sun Automounter maps. Use it as 6980follows 6981 6982@example 6983amd2sun < @i{amd.mapfile} > @i{auto_mapfile} 6984@end example 6985 6986@c ---------------------------------------------------------------- 6987@node automount2amd, ctl-amd, amd2sun, Assorted Tools 6988@comment node-name, next, previous, up 6989@section automount2amd 6990@pindex automount2amd 6991 6992A script to convert old Sun Automounter maps to @i{Amd} maps. 6993 6994Say you have the Sun automount file @i{auto.foo}, with these two lines: 6995@example 6996home earth:/home 6997moon -ro,intr server:/proj/images 6998@end example 6999Running 7000@example 7001automount2amd auto.foo > amd.foo 7002@end example 7003 7004will produce the @i{Amd} map @i{amd.foo} with this content: 7005 7006@example 7007# generated by automount2amd on Sat Aug 14 17:59:32 US/Eastern 1999 7008 7009/defaults \\ 7010 type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7011 7012home \ 7013 host==earth;type:=link;fs:=/home \\ 7014 rhost:=earth;rfs:=/home 7015 7016moon \ 7017 -addopts:=ro,intr \\ 7018 host==server;type:=link;fs:=/proj/images \\ 7019 rhost:=server;rfs:=/proj/images 7020@end example 7021 7022This perl script will use the following @i{/default} entry 7023@example 7024type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7025@end example 7026If you wish to override that, define the @b{$DEFAULTS} environment 7027variable, or modify the script. 7028 7029If you wish to generate Amd maps using the @i{hostd} (@pxref{hostd 7030Selector Variable}) @i{Amd} map syntax, then define the environment 7031variable @b{$DOMAIN} or modify the script. 7032 7033Note that automount2amd does not understand newer Sun Automount map 7034syntax, those used by autofs. 7035 7036@c ---------------------------------------------------------------- 7037@node ctl-amd, ctl-hlfsd, automount2amd, Assorted Tools 7038@comment node-name, next, previous, up 7039@section ctl-amd 7040@pindex ctl-amd 7041 7042A script to start, stop, or restart @i{Amd}. Use it as follows: 7043 7044@table @t 7045@item ctl-amd start 7046Start a new @i{Amd} process. 7047@item ctl-amd stop 7048Stop the running @i{Amd}. 7049@item ctl-amd restart 7050Stop the running @i{Amd} (if any), safely wait for it to terminate, and 7051then start a new process --- only if the previous one died cleanly. 7052@end table 7053 7054@xref{Run-time Administration}, for more details. 7055 7056@c ---------------------------------------------------------------- 7057@node ctl-hlfsd, expn, ctl-amd, Assorted Tools 7058@comment node-name, next, previous, up 7059@section ctl-hlfsd 7060@pindex ctl-hlfsd 7061 7062A script for controlling @i{Hlfsd}, much the same way @file{ctl-amd} 7063controls @i{Amd}. Use it as follows: 7064 7065@table @t 7066@item ctl-hlfsd start 7067Start a new @i{Hlfsd} process. 7068@item ctl-hlfsd stop 7069Stop the running @i{Hlfsd}. 7070@item ctl-hlfsd restart 7071Stop the running @i{Hlfsd} (if any), wait for 10 seconds for it to 7072terminate, and then start a new process --- only if the previous one 7073died cleanly. 7074@end table 7075 7076@xref{Hlfsd}, for more details. 7077 7078@c ---------------------------------------------------------------- 7079@node expn, fix-amd-map, ctl-hlfsd, Assorted Tools 7080@comment node-name, next, previous, up 7081@section expn 7082@pindex expn 7083 7084A script to expand email addresses into their full name. It is 7085generally useful when using with the @file{lostaltmail} script, but is a 7086useful tools otherwise. 7087 7088@example 7089$ expn -v ezk@@cs.columbia.edu 7090ezk@@cs.columbia.edu -> 7091 ezk@@shekel.mcl.cs.columbia.edu 7092ezk@@shekel.mcl.cs.columbia.edu -> 7093 Erez Zadok <"| /usr/local/mh/lib/slocal -user ezk || exit 75> 7094 Erez Zadok <\ezk> 7095 Erez Zadok </u/zing/ezk/.mailspool/backup> 7096@end example 7097 7098@c ---------------------------------------------------------------- 7099@node fix-amd-map, fixmount, expn, Assorted Tools 7100@comment node-name, next, previous, up 7101@section fix-amd-map 7102@pindex fix-amd-map 7103 7104Am-utils changed some of the syntax and default values of some 7105variables. For example, the default value for @samp{$@{os@}} for 7106Solaris 2.x (aka SunOS 5.x) systems used to be @samp{sos5}, it is now 7107more automatically generated from @file{config.guess} and its value is 7108@samp{sunos5}. 7109 7110This script converts older @i{Amd} maps to new ones. Use it as follows: 7111 7112@example 7113fix-amd-map < @i{old.map} > @i{new.map} 7114@end example 7115 7116@c ---------------------------------------------------------------- 7117@node fixmount, fixrmtab, fix-amd-map, Assorted Tools 7118@comment node-name, next, previous, up 7119@section fixmount 7120@pindex fixmount 7121 7122@samp{fixmount} is a variant of @b{showmount}(8) that can delete bogus 7123mount entries in remote @b{mountd}(8) daemons. This is useful to 7124cleanup otherwise ever-accumulating ``junk''. Use it for example: 7125 7126@example 7127fixmount -r @i{host} 7128@end example 7129 7130See the online manual page for @samp{fixmount} for more details of its 7131usage. 7132 7133@c ---------------------------------------------------------------- 7134@node fixrmtab, lostaltmail, fixmount, Assorted Tools 7135@comment node-name, next, previous, up 7136@section fixrmtab 7137@pindex fixrmtab 7138 7139A script to invalidate @file{/etc/rmtab} entries for hosts named. Also 7140restart mountd for changes to take effect. Use it for example: 7141 7142@example 7143fixrmtab @i{host1} @i{host2} @i{...} 7144@end example 7145 7146@c ---------------------------------------------------------------- 7147@node lostaltmail, lostaltmail.conf-sample, fixrmtab, Assorted Tools 7148@comment node-name, next, previous, up 7149@section lostaltmail 7150@pindex lostaltmail 7151 7152A script used with @i{Hlfsd} to resend any ``lost'' mail. @i{Hlfsd} 7153redirects mail which cannot be written into the user's home directory to 7154an alternate directory. This is useful to continue delivering mail, 7155even if the user's file system was unavailable, full, or over quota. 7156But, the mail which gets delivered to the alternate directory needs to 7157be resent to its respective users. This is what the @samp{lostaltmail} 7158script does. 7159 7160Use it as follows: 7161 7162@example 7163lostaltmail 7164@end example 7165 7166This script needs a configuration file @samp{lostaltmail.conf} set up 7167with the right parameters to properly work. @xref{Hlfsd}, for more 7168details. 7169 7170@c ---------------------------------------------------------------- 7171@node lostaltmail.conf-sample, mk-amd-map, lostaltmail, Assorted Tools 7172@comment node-name, next, previous, up 7173@section lostaltmail.conf-sample 7174@pindex lostaltmail.conf-sample 7175@cindex lostaltmail; configuration file 7176 7177This is a text file with configuration parameters needed for the 7178@samp{lostaltmail} script. The script includes comments explaining each 7179of the configuration variables. See it for more information. Also 7180@pxref{Hlfsd} for general information. 7181 7182@c ---------------------------------------------------------------- 7183@node mk-amd-map, pawd, lostaltmail.conf-sample, Assorted Tools 7184@comment node-name, next, previous, up 7185@section mk-amd-map 7186@pindex mk-amd-map 7187 7188This program converts a normal @i{Amd} map file into an ndbm database 7189with the same prefix as the named file. Use it as follows: 7190 7191@example 7192mk-amd-map @i{mapname} 7193@end example 7194 7195@c ---------------------------------------------------------------- 7196@node pawd, wait4amd, mk-amd-map, Assorted Tools 7197@comment node-name, next, previous, up 7198@section pawd 7199@pindex pawd 7200 7201@i{Pawd} is used to print the current working directory, adjusted to 7202reflect proper paths that can be reused to go through the automounter 7203for the shortest possible path. In particular, the path printed back 7204does not include any of @i{Amd}'s local mount points. Using them is 7205unsafe, because @i{Amd} may unmount managed file systems from the mount 7206points, and thus including them in paths may not always find the files 7207within. 7208 7209Without any arguments, @i{Pawd} will print the automounter adjusted 7210current working directory. With any number of arguments, it will print 7211the adjusted path of each one of the arguments. 7212 7213@c ---------------------------------------------------------------- 7214@node wait4amd, wait4amd2die, pawd, Assorted Tools 7215@comment node-name, next, previous, up 7216@section wait4amd 7217@pindex wait4amd 7218 7219A script to wait for @i{Amd} to start on a particular host before 7220performing an arbitrary command. The command is executed repeatedly, 7221with 1 second intervals in between. You may interrupt the script using 7222@samp{^C} (or whatever keyboard sequence your terminal's @samp{intr} function 7223is bound to). 7224 7225Examples: 7226 7227@table @t 7228@item wait4amd saturn amq -p -h saturn 7229When @i{Amd} is up on host @samp{saturn}, get the process ID of that 7230running @i{Amd}. 7231@item wait4amd pluto rlogin pluto 7232Remote login to host @samp{pluto} when @i{Amd} is up on that host. It 7233is generally necessary to wait for @i{Amd} to properly start and 7234initialize on a remote host before logging in to it, because otherwise 7235user home directories may not be accessible across the network. 7236@item wait4amd pluto 7237A short-hand version of the previous command, since the most useful 7238reason for this script is to login to a remote host. I use it very 7239often when testing out new versions of @i{Amd}, and need to reboot hung 7240hosts. 7241@end table 7242 7243@c ---------------------------------------------------------------- 7244@node wait4amd2die, wire-test, wait4amd, Assorted Tools 7245@comment node-name, next, previous, up 7246@section wait4amd2die 7247@pindex wait4amd2die 7248 7249This script is used internally by @samp{ctl-amd} when used to restart 7250@i{Amd}. It waits for @i{Amd} to terminate. If it detected that 7251@i{Amd} terminated cleanly, this script will return an exist status of 7252zero. Otherwise, it will return a non-zero exit status. 7253 7254The script tests for @i{Amd}'s existence once every 5 seconds, six 7255times, for a total of 30 seconds. It will return a zero exist status as 7256soon as it detects that @i{Amd} dies. 7257 7258@c ---------------------------------------------------------------- 7259@node wire-test, , wait4amd2die, Assorted Tools 7260@comment node-name, next, previous, up 7261@section wire-test 7262@pindex wire-test 7263 7264A simple program to test if some of the most basic networking functions 7265in am-util's library @file{libamu} work. It also tests the combination 7266of NFS protocol and version number that are supported from the current 7267host, to a remote one. 7268 7269For example, in this test a machine which only supports NFS Version 2 is 7270contacting a remote host that can support the same version, but using 7271both UDP and TCP. If no host name is specified, @samp{wire-test} will 7272try @file{localhost}. 7273 7274@example 7275$ wire-test moisil 7276Network name is "mcl-lab-net.cs.columbia.edu" 7277Network number is "128.59.13" 7278Network name is "old-net.cs.columbia.edu" 7279Network number is "128.59.16" 7280My IP address is 0x7f000001. 7281NFS Version and protocol tests to host "moisil"... 7282 testing vers=2, proto="udp" -> found version 2. 7283 testing vers=3, proto="udp" -> failed! 7284 testing vers=2, proto="tcp" -> found version 2. 7285 testing vers=3, proto="tcp" -> failed! 7286@end example 7287 7288@c ################################################################ 7289@node Examples, Internals, Assorted Tools, Top 7290@comment node-name, next, previous, up 7291@chapter Examples 7292 7293@menu 7294* User Filesystems:: 7295* Home Directories:: 7296* Architecture Sharing:: 7297* Wildcard Names:: 7298* rwho servers:: 7299* /vol:: 7300* /defaults with selectors:: 7301* /tftpboot in a chroot-ed environment:: 7302 7303@end menu 7304 7305@node User Filesystems, Home Directories, Examples, Examples 7306@comment node-name, next, previous, up 7307@section User Filesystems 7308@cindex User filesystems 7309@cindex Mounting user filesystems 7310 7311With more than one fileserver, the directories most frequently 7312cross-mounted are those containing user home directories. A common 7313convention used at Imperial College is to mount the user disks under 7314@t{/home/}@i{machine}. 7315 7316Typically, the @samp{/etc/fstab} file contained a long list of entries 7317such as: 7318 7319@example 7320@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... 7321@end example 7322 7323for each fileserver on the network. 7324 7325There are numerous problems with this system. The mount list can become 7326quite large and some of the machines may be down when a system is 7327booted. When a new fileserver is installed, @samp{/etc/fstab} must be 7328updated on every machine, the mount directory created and the filesystem 7329mounted. 7330 7331In many environments most people use the same few workstations, but 7332it is convenient to go to a colleague's machine and access your own 7333files. When a server goes down, it can cause a process on a client 7334machine to hang. By minimizing the mounted filesystems to only include 7335those actively being used, there is less chance that a filesystem will 7336be mounted when a server goes down. 7337 7338The following is a short extract from a map taken from a research fileserver 7339at Imperial College. 7340 7341Note the entry for @samp{localhost} which is used for users such as 7342the operator (@samp{opr}) who have a home directory on most machine as 7343@samp{/home/localhost/opr}. 7344 7345@example 7346/defaults opts:=rw,intr,grpid,nosuid 7347charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 7348 host==$@{key@};type:=ufs;dev:=/dev/xd0g 7349# 7350... 7351 7352# 7353localhost type:=link;fs:=$@{host@} 7354... 7355# 7356# dylan has two user disks so have a 7357# top directory in which to mount them. 7358# 7359dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 7360# 7361dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 7362 host==dylan;type:=ufs;dev:=/dev/dsk/2s0 7363# 7364dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 7365 host==dylan;type:=ufs;dev:=/dev/dsk/5s0 7366... 7367# 7368toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 7369 host==$@{key@};type:=ufs;dev:=/dev/xy1g 7370... 7371# 7372zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 7373 host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 7374# 7375# Just for access... 7376# 7377gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ 7378gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} 7379# 7380gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} 7381... 7382@end example 7383 7384This map is shared by most of the machines listed so on those 7385systems any of the user disks is accessible via a consistent name. 7386@i{Amd} is started with the following command 7387 7388@example 7389amd /home amd.home 7390@end example 7391 7392Note that when mounting a remote filesystem, the @dfn{automounted} 7393mount point is referenced, so that the filesystem will be mounted if 7394it is not yet (at the time the remote @samp{mountd} obtains the file handle). 7395 7396@node Home Directories, Architecture Sharing, User Filesystems, Examples 7397@comment node-name, next, previous, up 7398@section Home Directories 7399@cindex Home directories 7400@cindex Example of mounting home directories 7401@cindex Mount home directories 7402 7403One convention for home directories is to locate them in @samp{/homes} 7404so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more 7405than a single fileserver it is convenient to spread user files across 7406several machines. All that is required is a mount-map which converts 7407login names to an automounted directory. 7408 7409Such a map might be started by the command: 7410 7411@example 7412amd /homes amd.homes 7413@end example 7414 7415where the map @samp{amd.homes} contained the entries: 7416 7417@example 7418/defaults type:=link # All the entries are of type:=link 7419jsp fs:=/home/charm/jsp 7420njw fs:=/home/dylan/dk5/njw 7421... 7422phjk fs:=/home/toytown/ai/phjk 7423sjv fs:=/home/ganymede/sjv 7424@end example 7425 7426Whenever a login name is accessed in @samp{/homes} a symbolic link 7427appears pointing to the real location of that user's home directory. In 7428this example, @samp{/homes/jsp} would appear to be a symbolic link 7429pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also 7430be an automount point. 7431 7432This system causes an extra level of symbolic links to be used. 7433Although that turns out to be relatively inexpensive, an alternative is 7434to directly mount the required filesystems in the @samp{/homes} 7435map. The required map is simple, but long, and its creation is best automated. 7436The entry for @samp{jsp} could be: 7437 7438@example 7439jsp -sublink:=$@{key@};rfs:=/home/charm \ 7440 host==charm;type:=ufs;dev:=/dev/xd0g \ 7441 host!=charm;type:=nfs;rhost:=charm 7442@end example 7443 7444This map can become quite big if it contains a large number of entries. 7445By combining two other features of @i{Amd} it can be greatly simplified. 7446 7447First the UFS partitions should be mounted under the control of 7448@samp{/etc/fstab}, taking care that they are mounted in the same place 7449that @i{Amd} would have automounted them. In most cases this would be 7450something like @samp{/a/@dfn{host}/home/@dfn{host}} and 7451@samp{/etc/fstab} on host @samp{charm} would have a line:@refill 7452 7453@example 7454/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 7455@end example 7456 7457The map can then be changed to: 7458 7459@example 7460/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid 7461jsp rhost:=charm;rfs:=/home/charm 7462njw rhost:=dylan;rfs:=/home/dylan/dk5 7463... 7464phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} 7465sjv rhost:=ganymede;rfs:=/home/ganymede 7466@end example 7467 7468This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} 7469not equal to @code{$@{rhost@}}). On the machine where the filesystem is 7470stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} 7471will construct a local filesystem mount point which corresponds to the 7472name of the locally mounted UFS partition. If @i{Amd} is started with 7473the @code{-r} option then instead of attempting an NFS mount, @i{Amd} will 7474simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If 7475@code{-r} is not used then a loopback NFS mount will be made. This type of 7476mount is known to cause a deadlock on many systems. 7477 7478@node Architecture Sharing, Wildcard Names, Home Directories, Examples 7479@comment node-name, next, previous, up 7480@section Architecture Sharing 7481@cindex Architecture sharing 7482@cindex Sharing a fileserver between architectures 7483@cindex Architecture dependent volumes 7484 7485@c %At the moment some of the research machines have sets of software 7486@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, 7487@c %system sources, local sources, prolog libraries and so on. 7488Often a filesystem will be shared by machines of different architectures. 7489Separate trees can be maintained for the executable images for each 7490architecture, but it may be more convenient to have a shared tree, 7491with distinct subdirectories. 7492 7493A shared tree might have the following structure on the fileserver (called 7494@samp{fserver} in the example): 7495 7496@example 7497local/tex 7498local/tex/fonts 7499local/tex/lib 7500local/tex/bin 7501local/tex/bin/sun3 7502local/tex/bin/sun4 7503local/tex/bin/hp9000 7504... 7505@end example 7506 7507In this example, the subdirectories of @samp{local/tex/bin} should be 7508hidden when accessed via the automount point (conventionally @samp{/vol}). 7509A mount-map for @samp{/vol} to achieve this would look like: 7510 7511@example 7512/defaults sublink:=$@{/key@};rhost:=fserver;type:=link 7513tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ 7514tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ 7515 host==fserver;fs:=/usr/local/tex 7516tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ 7517 host==fserver;fs:=/usr/local/tex 7518tex/bin -sublink:=$@{/key@}/$@{arch@} \ 7519 host!=fserver;type:=nfs;rfs:=/vol/tex \ 7520 host:=fserver;fs:=/usr/local/tex 7521@end example 7522 7523When @samp{/vol/tex/bin} is referenced, the current machine architecture 7524is automatically appended to the path by the @code{$@{sublink@}} 7525variable. This means that users can have @samp{/vol/tex/bin} in their 7526@samp{PATH} without concern for architecture dependencies. 7527 7528@node Wildcard Names, rwho servers, Architecture Sharing, Examples 7529@comment node-name, next, previous, up 7530@section Wildcard Names & Replicated Servers 7531 7532By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing 7533directory with additional entries. 7534The system files are usually mounted under @samp{/usr}. If instead, 7535@i{Amd} is mounted on @samp{/usr}, additional 7536names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. 7537A map to do this would have the form: 7538 7539@example 7540local type:=auto;fs:=local-map 7541share type:=auto;fs:=share-map 7542* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ 7543 rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 7544@end example 7545 7546Note that the assignment to @code{$@{sublink@}} is surrounded by double 7547quotes to prevent the incoming key from causing the map to be 7548misinterpreted. This map has the effect of directing any access to 7549@samp{/usr/local} or @samp{/usr/share} to another automount point. 7550 7551In this example, it is assumed that the @samp{/usr} files are replicated 7552on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. 7553For any references other than to @samp{local} and @samp{share} one of 7554the servers is used and a symbolic link to 7555@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is 7556returned once an appropriate filesystem has been mounted.@refill 7557 7558@node rwho servers, /vol, Wildcard Names, Examples 7559@comment node-name, next, previous, up 7560@section @samp{rwho} servers 7561@cindex rwho servers 7562@cindex Architecture specific mounts 7563@cindex Example of architecture specific mounts 7564 7565The @samp{/usr/spool/rwho} directory is a good candidate for automounting. 7566For efficiency reasons it is best to capture the rwho data on a small 7567number of machines and then mount that information onto a large number 7568of clients. The data written into the rwho files is byte order dependent 7569so only servers with the correct byte ordering can be used by a client: 7570 7571@example 7572/defaults type:=nfs 7573usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ 7574 rhost:=vaxA rhost:=vaxB \ 7575 || -rfs:=/usr/spool/rwho \ 7576 rhost:=sun4 rhost:=hp300 7577@end example 7578 7579@node /vol, /defaults with selectors, rwho servers, Examples 7580@comment node-name, next, previous, up 7581@section @samp{/vol} 7582@cindex /vol 7583@cindex Catch-all mount point 7584@cindex Generic volume name 7585 7586@samp{/vol} is used as a catch-all for volumes which do not have other 7587conventional names. 7588 7589Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. 7590The @samp{r+d} tree is used for new or experimental software that needs 7591to be available everywhere without installing it on all the fileservers. 7592Users wishing to try out the new software then simply include 7593@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill 7594 7595The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has 7596different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} 7597sub-directories for each machine architecture. For example, 7598@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory 7599@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed 7600a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be 7601returned.@refill 7602 7603@example 7604/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft 7605wp -opts:=rw,grpid,nosuid;rhost:=charm \ 7606 host==charm;type:=link;fs:=/usr/local/wp \ 7607 host!=charm;type:=nfs;rfs:=/vol/wp 7608... 7609# 7610src -opts:=rw,grpid,nosuid;rhost:=charm \ 7611 host==charm;type:=link;fs:=/usr/src \ 7612 host!=charm;type:=nfs;rfs:=/vol/src 7613# 7614r+d type:=auto;fs:=$@{map@};pref:=r+d/ 7615# per architecture bin,etc,lib&ucb... 7616r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 7617r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 7618r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 7619r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 7620r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 7621r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 7622r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 7623# hades pictures 7624pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ 7625 host==thpfs;type:=link;fs:=/nbsd/pictures \ 7626 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures 7627# hades tools 7628hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ 7629 host==thpfs;type:=link;fs:=/nbsd/hades \ 7630 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades 7631# bsd tools for hp. 7632bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ 7633 host==thpfs;type:=link;fs:=/nbsd/bsd \ 7634 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd 7635@end example 7636 7637@node /defaults with selectors, /tftpboot in a chroot-ed environment, /vol, Examples 7638@comment node-name, next, previous, up 7639@section @samp{/defaults} with selectors 7640@cindex /defaults with selectors 7641@cindex selectors on default 7642 7643It is sometimes useful to have different defaults for a given map. To 7644achieve this, the @samp{/defaults} entry must be able to process normal 7645selectors. This feature is turned on by setting 7646@samp{selectors_on_default = yes} in the @file{amd.conf} file. 7647@xref{selectors_on_default Parameter}. 7648 7649In this example, I set different default NFS mount options for hosts 7650which are running over a slower network link. By setting a smaller size 7651for the NFS read and write buffer sizes, you can greatly improve remote 7652file service performance. 7653 7654@example 7655/defaults \ 7656 wire==slip-net;opts:=rw,intr,rsize=1024,wsize=1024,timeo=20,retrans=10 \ 7657 wire!=slip-net;opts:=rw,intr 7658@end example 7659 7660@node /tftpboot in a chroot-ed environment, , /defaults with selectors, Examples 7661@comment node-name, next, previous, up 7662@section @samp{/tftpboot} in a chroot-ed environment 7663@cindex /tftpboot in a chroot-ed environment 7664@cindex chroot: /tftpboot example 7665 7666In this complex example, we attempt to run an @i{Amd} process 7667@emph{inside} a chroot-ed environment. @samp{tftpd} (Trivial FTP) is 7668used to trivially retrieve files used to boot X-Terminals, Network 7669Printers, Network routers, diskless workstations, and other such 7670devices. For security reasons, @samp{tftpd} (and also @samp{ftpd}) 7671processes are run using the @b{chroot}(2) system call. This provides an 7672environment for these processes, where access to any files outside the 7673directory where the chroot-ed process runs is denied. 7674 7675For example, if you start @samp{tftpd} on your system with 7676 7677@example 7678chroot /tftpboot /usr/sbin/tftpd 7679@end example 7680 7681@noindent 7682then the @samp{tftpd} process will not be able to access any files 7683outside @file{/tftpboot}. This ensures that no one can retrieve files 7684such as @file{/etc/passwd} and run password crackers on it. 7685 7686Since the TFTP service works by broadcast, it is necessary to have at 7687least one TFTP server running on each subnet. If you have lots of files 7688that you need to make available for @samp{tftp}, and many subnets, it 7689could take significant amounts of disk space on each host serving them. 7690 7691A solution we implemented at Columbia University was to have every host 7692run @samp{tftpd}, but have those servers retrieve the boot files from 7693two replicated servers. Those replicated servers have special 7694partitions dedicated to the many network boot files. 7695 7696We start @i{Amd} as follows: 7697 7698@example 7699amd /tftpboot/.amd amd.tftpboot 7700@end example 7701 7702That is, @i{Amd} is serving the directory @file{/tftpboot/.amd}. The 7703@samp{tftp} server runs inside @file{/tftpboot} and is chroot-ed in that 7704directory too. The @file{amd.tftpboot} map looks like: 7705 7706@example 7707# 7708# Amd /tftpboot directory -> host map 7709# 7710 7711/defaults opts:=nosuid,ro,intr,soft;fs:=/tftpboot/import;type:=nfs 7712 7713tp host==lol;rfs:=/n/lol/import/tftpboot;type:=lofs \ 7714 host==ober;rfs:=/n/ober/misc/win/tftpboot;type:=lofs \ 7715 rhost:=ober;rfs:=/n/ober/misc/win/tftpboot \ 7716 rhost:=lol;rfs:=/n/lol/import/tftpboot 7717@end example 7718 7719To help understand this example, I list a few of the file entries that 7720are created inside @file{/tftpboot}: 7721 7722@example 7723$ ls -la /tftpboot 7724dr-xr-xr-x 2 root 512 Aug 30 23:11 .amd 7725drwxrwsr-x 12 root 512 Aug 30 08:00 import 7726lrwxrwxrwx 1 root 33 Feb 27 1997 adminpr.cfg -> ./.amd/tp/hplj/adminpr.cfg 7727lrwxrwxrwx 1 root 22 Dec 5 1996 tekxp -> ./.amd/tp/xterms/tekxp 7728lrwxrwxrwx 1 root 1 Dec 5 1996 tftpboot -> . 7729@end example 7730 7731Here is an explanation of each of the entries listed above: 7732 7733@table @code 7734 7735@item .amd 7736This is the @i{Amd} mount point. Note that you do not need to run a 7737separate @i{Amd} process for the TFTP service. The @b{chroot}(2) system 7738call only protects against file access, but the same process can still 7739serve files and directories inside and outside the chroot-ed 7740environment, because @i{Amd} itself was not run in chroot-ed mode. 7741 7742@item import 7743This is the mount point where @i{Amd} will mount the directories 7744containing the boot files. The map is designed so that remote 7745directories will be NFS mounted (even if they are already mounted 7746elsewhere), and local directories are loopback mounted (since they are 7747not accessible outside the chroot-ed @file{/tftpboot} directory). 7748 7749@item adminpr.cfg 7750@itemx tekxp 7751Two manually created symbolic links to directories @emph{inside} the 7752@i{Amd}-managed directory. The crossing of the component @file{tp} will 7753cause @i{Amd} to automount one of the remote replicas. Once crossed, 7754access to files inside proceeds as usual. The @samp{adminpr.cfg} is a 7755configuration file for an HP Laser-Jet 4si printer, and the @samp{tekxp} 7756is a directory for Tektronix X-Terminal boot files. 7757 7758@item tftpboot 7759This innocent looking symlink is important. Usually, when devices boot 7760via the TFTP service, they perform the @samp{get file} command to 7761retrieve @var{file}. However, some devices assume that @samp{tftpd} 7762does not run in a chroot-ed environment, but rather ``unprotected'', and 7763thus use a full pathname for files to retrieve, as in @samp{get 7764/tftpboot/file}. This symlink effectively strips out the leading 7765@file{/tftpboot/}. 7766 7767@end table 7768 7769@c ################################################################ 7770@node Internals, Acknowledgments & Trademarks, Examples, Top 7771@comment node-name, next, previous, up 7772@chapter Internals 7773 7774Note that there are more error and logging messages possible than are 7775listed here. Most of them are self-explanatory. Refer to the program 7776sources for more details on the rest. 7777 7778@menu 7779* Log Messages:: 7780@end menu 7781 7782@node Log Messages, , Internals, Internals 7783@comment node-name, next, previous, up 7784@section Log Messages 7785 7786In the following sections a brief explanation is given of some of the 7787log messages made by @i{Amd}. Where the message is in @samp{typewriter} 7788font, it corresponds exactly to the message produced by @i{Amd}. Words 7789in @dfn{italic} are replaced by an appropriate string. Variables, 7790@code{$@{@i{var}@}}, indicate that the value of the appropriate variable is 7791output. 7792 7793Log messages are either sent directly to a file, 7794or logged via the @b{syslog}(3) mechanism. @xref{log_file Parameter}. 7795In either case, entries in the file are of the form: 7796@example 7797@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} 7798@end example 7799 7800@menu 7801* Fatal errors:: 7802* Info messages:: 7803@end menu 7804 7805@node Fatal errors, Info messages, Log Messages, Log Messages 7806@comment node-name, next, previous, up 7807@subsection Fatal errors 7808 7809@i{Amd} attempts to deal with unusual events. Whenever it is not 7810possible to deal with such an error, @i{Amd} will log an appropriate 7811message and, if it cannot possibly continue, will either exit or abort. 7812These messages are selected by @samp{-x fatal} on the command line. 7813When @b{syslog}(3) is being used, they are logged with level 7814@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to 7815remain in a precarious state and should be restarted at the earliest 7816opportunity. 7817 7818@table @t 7819 7820@item Attempting to inherit not-a-filesystem 7821The prototype mount point created during a filesystem restart did not 7822contain a reference to the restarted filesystem. This error ``should 7823never happen''. 7824 7825@item Can't bind to domain "@i{NIS-domain}" 7826A specific NIS domain was requested on the command line, but no server 7827for that domain is available on the local net. 7828 7829@item Can't determine IP address of this host (@i{hostname}) 7830When @i{Amd} starts it determines its own IP address. If this lookup 7831fails then @i{Amd} cannot continue. The hostname it looks up is that 7832obtained returned by @b{gethostname}(2) system call. 7833 7834@item Can't find root file handle for @i{automount point} 7835@i{Amd} creates its own file handles for the automount points. When it 7836mounts itself as a server, it must pass these file handles to the local 7837kernel. If the filehandle is not obtainable the mount point is ignored. 7838This error ``should never happen''. 7839 7840@item Must be root to mount filesystems (euid = @i{euid}) 7841To prevent embarrassment, @i{Amd} makes sure it has appropriate system 7842privileges. This amounts to having an euid of 0. The check is made 7843after argument processing complete to give non-root users a chance to 7844access the @code{-v} option. 7845 7846@item No work to do - quitting 7847No automount points were given on the command line and so there is no 7848work to do. 7849 7850@item Out of memory 7851While attempting to malloc some memory, the memory space available to 7852@i{Amd} was exhausted. This is an unrecoverable error. 7853 7854@item Out of memory in realloc 7855While attempting to realloc some memory, the memory space available to 7856@i{Amd} was exhausted. This is an unrecoverable error. 7857 7858@item cannot create rpc/udp service 7859Either the NFS or AMQ endpoint could not be created. 7860 7861@item gethostname: @i{description} 7862The @b{gethostname}(2) system call failed during startup. 7863 7864@item host name is not set 7865The @b{gethostname}(2) system call returned a zero length host name. 7866This can happen if @i{Amd} is started in single user mode just after 7867booting the system. 7868 7869@item ifs_match called! 7870An internal error occurred while restarting a pre-mounted filesystem. 7871This error ``should never happen''. 7872 7873@item mount_afs: @i{description} 7874An error occurred while @i{Amd} was mounting itself. 7875 7876@item run_rpc failed 7877Somehow the main NFS server loop failed. This error ``should never 7878happen''. 7879 7880@item unable to free rpc arguments in amqprog_1 7881The incoming arguments to the AMQ server could not be free'ed. 7882 7883@item unable to free rpc arguments in nfs_program_1 7884The incoming arguments to the NFS server could not be free'ed. 7885 7886@item unable to register (AMQ_PROGRAM, AMQ_VERSION, udp) 7887The AMQ server could not be registered with the local portmapper or the 7888internal RPC dispatcher. 7889 7890@item unable to register (NFS_PROGRAM, NFS_VERSION, 0) 7891The NFS server could not be registered with the internal RPC dispatcher. 7892 7893@end table 7894 7895XXX: This section needs to be updated 7896 7897@node Info messages, , Fatal errors, Log Messages 7898@comment node-name, next, previous, up 7899@subsection Info messages 7900 7901@i{Amd} generates information messages to record state changes. These 7902messages are selected by @samp{-x info} on the command line. When 7903@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. 7904 7905The messages listed below can be generated and are in a format suitable 7906for simple statistical analysis. @dfn{mount-info} is the string 7907that is displayed by @dfn{Amq} in its mount information column and 7908placed in the system mount table. 7909 7910@table @t 7911 7912@item "@t{$@{@i{path}@}}" forcibly timed out 7913An automount point has been timed out by the @i{Amq} command. 7914 7915@item "@t{$@{@i{path}@}}" has timed out 7916No access to the automount point has been made within the timeout 7917period. 7918 7919@item Filehandle denied for "$@{@i{rhost}@}:$@{@i{rfs}@}" 7920The mount daemon refused to return a file handle for the requested filesystem. 7921 7922@item Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}": @i{description} 7923The mount daemon gave some other error for the requested filesystem. 7924 7925@item Finishing with status @i{exit-status} 7926@i{Amd} is about to exit with the given exit status. 7927 7928@item Re-synchronizing cache for map @t{$@{@i{map}@}} 7929The named map has been modified and the internal cache is being re-synchronized. 7930 7931@item file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored 7932An automount point has timed out, but the corresponding file server is 7933known to be down. This message is only produced once for each mount 7934point for which the server is down. 7935 7936@item file server @t{$@{@i{rhost}@}} type nfs is down 7937An NFS file server that was previously up is now down. 7938 7939@item file server @t{$@{@i{rhost}@}} type nfs is up 7940An NFS file server that was previously down is now up. 7941 7942@item file server @t{$@{@i{rhost}@}} type nfs starts down 7943A new NFS file server has been referenced and is known to be down. 7944 7945@item file server @t{$@{@i{rhost}@}} type nfs starts up 7946A new NFS file server has been referenced and is known to be up. 7947 7948@item mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out 7949Attempts to mount a filesystem for the given automount point have failed 7950to complete within 30 seconds. 7951 7952@item @i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 7953A new file system has been mounted. 7954 7955@item @i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 7956@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. 7957 7958@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} 7959A file system has been unmounted. 7960 7961@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}} 7962A file system of which only a sub-directory was in use has been unmounted. 7963 7964@item restarting @i{mount-info} on @t{$@{@i{fs}@}} 7965A pre-mounted file system has been noted. 7966 7967@end table 7968 7969XXX: This section needs to be updated 7970 7971@c ################################################################ 7972@node Acknowledgments & Trademarks, Index, Internals, Top 7973@comment node-name, next, previous, up 7974@unnumbered Acknowledgments & Trademarks 7975 7976Many thanks to the @email{amd-dev@@majordomo.cs.columbia.edu,Amd 7977Developers} mailing list through the months developing am-utils. These 7978members have contributed to the discussions, ideas, code and 7979documentation, and subjected their systems to alpha quality code. 7980Special thanks go to those 7981@uref{http://www.cs.columbia.edu/~ezk/am-utils/AUTHORS.txt,authors} who 7982have submitted patches. 7983 7984Thanks to the Formal Methods Group at Imperial College for suffering 7985patiently while @i{Amd} was being developed on their machines. 7986 7987Thanks to the many people who have helped with the development of 7988@i{Amd}, especially Piete Brooks at the Cambridge University Computing 7989Lab for many hours of testing, experimentation and discussion. 7990 7991Thanks to the @email{amd-workers@@majordomo.glue.umd.edu,Amd Workers} 7992mailing list members for many suggestions and bug reports to @i{Amd}. 7993 7994@itemize @bullet 7995@item 7996@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital 7997Equipment Corporation. 7998@item 7999@b{AIX} and @b{IBM} are registered trademarks of International Business 8000Machines Corporation. 8001@item 8002@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun 8003Microsystems, Inc. 8004@item 8005@b{UNIX} is a registered trademark in the USA and other countries, 8006exclusively licensed through X/Open Company, Ltd. 8007@item 8008All other registered trademarks are owned by their respective owners. 8009@end itemize 8010 8011@c ################################################################ 8012@node Index, , Acknowledgments & Trademarks, Top 8013@comment node-name, next, previous, up 8014@unnumbered Index 8015 8016@printindex cp 8017 8018@contents 8019@bye 8020 8021@c ==================================================================== 8022@c ISPELL LOCAL WORDS: 8023@c LocalWords: setfilename amdref overfullrule settitle titlepage titlefont nz 8024@c LocalWords: authorfont vskip ifinfo iftex cindex unnumberedsec dfn xref vol 8025@c LocalWords: locationN pxref jpo nott concentrix Sjoerd sjoerd cwi Eitan vuw 8026@c LocalWords: Mizrotsky eitan shumuji dgux fpx scp hcx metcalf masala hlh OTS 8027@c LocalWords: Presnell srp cgl Trost trost ogi pyrOSx OSx tubsibr riscix iX 8028@c LocalWords: Piete pb Lindblad cjl ai umax utek xinu Mitchum D'Souza dsouza 8029@c LocalWords: mrc apu alliant aviion AViiON fps macII multimax tahoe vax emph 8030@c LocalWords: mapdefault valA valB valC YPTSDIR ETCDIR substr MAKEDBM YPDBDIR 8031@c LocalWords: NOPUSH njw dylan dk dylan njw anydir domN achilles mjh pref sel 8032@c LocalWords: gdef loc loc loc ldots autodir remopts rwho rwho styx styx yoyo 8033@c LocalWords: noindent gould rvdmount rvdunmount fserver mtmp unioned logfile 8034@c LocalWords: dmn esac phjk toytown toytown toytown toytown phjk RdDir RdLnk 8035@c LocalWords: volname attrs netif dougal inaddr hwaddr ec mountmaps passno xy 8036@c LocalWords: freq dumpset hfs brian florence localinfo fstabs automaps defn 8037@c LocalWords: localname fsck'd opr gummo sjv ganymede sjv fserv fserv fserv 8038@c LocalWords: vaxA vaxB wp thpfs nbsd asis ifs amqprog free'ed printindex gov 8039@c LocalWords: LocalWords syncodeindex Distrib bsdnet lanl AutoMounter acis ic 8040@c LocalWords: ac uk aix bsd Mullender nl il DG lcs hpux irix ucsf NeXT cse cl 8041@c LocalWords: mt FX hp ibm mips utils def def Domainname eg hostd getwd tmp 8042@c LocalWords: subsubsection rw grpid intr noconn nocto nodevs nosuid retrans 8043@c LocalWords: rsize tcp timeo nounmount utimeout DDEBUG nodaemon fd hostnames 8044@c LocalWords: pid Amd's pendry vangogh nfsx backoff stats nomap nostats CRIT 8045@c LocalWords: noinfo clustername RVD dsk dsk amq hostports osver statfs str 8046@c LocalWords: ou counter's amdmaps proj src tftpboot sh mv cd sbin ypcat inet 8047@c LocalWords: Getattr getattr localhost fhandles netmask fstype noquota addr 8048@c LocalWords: exportfs Dumpsets dumpsets pindex ldif fixmount fixrmtab euid 8049@c LocalWords: lostaltmail realloc netnumber itemx primnetnum primnetname ARG 8050@c LocalWords: subsnetname subsnetnum netgrp netgroup multitable Shlib dec osf 8051@c LocalWords: hppa pc bsdi freebsd netbsd openbsd ncr sysv rs acdirmax fsid 8052@c LocalWords: acdirmin acregmax acregmin actimeo dumbtimr nfsv noac noauto sd 8053@c LocalWords: nocache nodev noint nosub pgthresh posix rdonly suid symttl mfs 8054@c LocalWords: AMFS umapfs myftpdir unionfs es mapname mapfile mapfile slocal 8055@c LocalWords: mailspool saturn saturn notknown lol ober dr xr xr drwxrwsr cfg 8056@c LocalWords: lrwxrwxrwx adminpr hplj adminpr cfg tekxp xterms tekxp Dupuy tp 8057@c LocalWords: linkname hlfsddump dirname rmtab pluto rlogin direntry pg vr dn 8058@c LocalWords: maxmem hlfsdir xmailbox showmount cn amdmap amdmapName resvport 8059@c LocalWords: objectClass amdmapKey amdmapValue ln powerpc amdmapTimestamp ez 8060@c LocalWords: moisil FSinfo Libtool Unmounting sublink fileservers NullProc 8061@c LocalWords: gethostname mount's unmounts linkx remounts unmounting UAs SA's 8062@c LocalWords: mountpoint mountpoints unescaped UIDs util's overlayed uref EFS 8063@c LocalWords: serv maxgroups nfsl cachedir copt cfsadmin efs addopts fg ROMs 8064@c LocalWords: nointr extatt setchapternewpage columnfractions alphaev gnulibc 8065@c LocalWords: freebsdelf gnuoldld ifhtml defperm nodefperm norrip RRIP rrip 8066@c LocalWords: noversion attr XXXXXX netgrpd 8067