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