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