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