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