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