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