am-utils.texi revision 310490
1\input texinfo @c -*-texinfo-*- 2@c 3@c Copyright (c) 1997-2014 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. Neither the name of the University nor the names of its contributors 21@c may be used to endorse or promote products derived from this software 22@c without specific prior written permission. 23@c 24@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34@c 35@c 36@c File: am-utils/doc/am-utils.texi 37@c 38@setfilename am-utils.info 39 40@include version.texi 41 42@c info directory entry 43@dircategory Administration 44@direntry 45* Am-utils: (am-utils). The Amd automounter suite of utilities 46@end direntry 47 48@settitle Am-utils (4.4BSD Automounter Utilities) 49@setchapternewpage odd 50 51@titlepage 52@title Am-utils (4.4BSD Automounter Utilities) 53@subtitle For version @value{VERSION}, @value{UPDATED} 54 55@author Erez Zadok 56(Originally by Jan-Simon Pendry and Nick Williams) 57 58@page 59Copyright @copyright{} 1997-2014 Erez Zadok 60@* 61Copyright @copyright{} 1989 Jan-Simon Pendry 62@* 63Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 64@* 65Copyright @copyright{} 1989 The Regents of the University of California. 66@sp 1 67All Rights Reserved. 68@vskip 1ex 69Permission to copy this document, or any portion of it, as 70necessary for use of this software is granted provided this 71copyright notice and statement of permission are included. 72@end titlepage 73@page 74 75@c Define a new index for options. 76@syncodeindex pg cp 77@syncodeindex vr cp 78 79@ifinfo 80 81@c ################################################################ 82@node Top, License, , (DIR) 83 84@b{Am-utils (4.4BSD Automounter Utilities) User Manual} 85@* 86For version @value{VERSION}, @value{UPDATED} 87 88@b{Erez Zadok} 89@* 90(Originally by Jan-Simon Pendry and Nick Williams) 91 92Copyright @copyright{} 1997-2014 Erez Zadok 93@* 94Copyright @copyright{} 1989 Jan-Simon Pendry 95@* 96Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 97@* 98Copyright @copyright{} 1989 The Regents of the University of California. 99@* 100All Rights Reserved. 101 102Permission to copy this document, or any portion of it, as 103necessary for use of this software is granted provided this 104copyright notice and statement of permission are included. 105 106Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd 107automounter, the Amq query and control program, the Hlfsd daemon, and 108other tools. This Info file describes how to use and understand the 109tools within Am-utils. 110@end ifinfo 111 112@menu 113* License:: Explains the terms and conditions for using 114 and distributing Am-utils. 115* Distrib:: How to get the latest Am-utils distribution. 116* AddInfo:: How to get additional information. 117* Intro:: An introduction to Automounting concepts. 118* History:: History of am-utils' development. 119* Overview:: An overview of Amd. 120* Supported Platforms:: Machines and Systems supported by Amd. 121* Mount Maps:: Details of mount maps. 122* Amd Command Line Options:: All the Amd command line options explained. 123* Filesystem Types:: The different mount types supported by Amd. 124* Amd Configuration File:: The amd.conf file syntax and meaning. 125* Run-time Administration:: How to start, stop and control Amd. 126* FSinfo:: The FSinfo filesystem management tool. 127* Hlfsd:: The Home-Link Filesystem server. 128* Assorted Tools:: Other tools which come with am-utils. 129* Examples:: Some examples showing how Amd might be used. 130* Internals:: Implementation details. 131* Acknowledgments & Trademarks:: Legal Notes. 132 133Indexes 134* Index:: An item for each concept. 135@end menu 136 137@iftex 138@unnumbered Preface 139 140This manual documents the use of the 4.4BSD automounter tool suite, 141which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is 142primarily a reference manual. While no tutorial exists, there are 143examples available. @xref{Examples}. 144 145This manual comes in two forms: the published form and the Info form. 146The Info form is for on-line perusal with the INFO program which is 147distributed along with GNU texinfo package (a version of which is 148available for GNU Emacs).@footnote{GNU packages can be found in 149@url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially 150the same text and are generated from a common source file, which is 151distributed with the @i{Am-utils} source. 152@end iftex 153 154@c ################################################################ 155@node License, Distrib, Top, Top 156@unnumbered License 157@cindex License Information 158 159@i{Am-utils} is not in the public domain; it is copyrighted and there are 160restrictions on its distribution. 161 162Redistribution and use in source and binary forms, with or without 163modification, are permitted provided that the following conditions are 164met: 165 166@enumerate 167 168@item 169Redistributions of source code must retain the above copyright notice, 170this list of conditions and the following disclaimer. 171 172@item 173Redistributions in binary form must reproduce the above copyright 174notice, this list of conditions and the following disclaimer in the 175documentation and/or other materials provided with the distribution. 176 177@item 178Neither the name of the University nor the names of its contributors may 179be used to endorse or promote products derived from this software 180without specific prior written permission. 181 182@end enumerate 183 184THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 185ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 186IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 187PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 188BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 189CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 190SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 191INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 192CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 193ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 194THE POSSIBILITY OF SUCH DAMAGE. 195 196@c ################################################################ 197@node Distrib, AddInfo, License, Top 198@unnumbered Source Distribution 199@cindex Source code distribution 200@cindex Obtaining the source code 201 202The @i{Am-utils} home page is located in 203@example 204@url{http://www.am-utils.org/} 205@end example 206 207You can get the latest distribution version of @i{Am-utils} from 208@example 209@url{ftp://ftp.am-utils.org/pub/am-utils/am-utils.tar.gz} 210@end example 211 212Additional alpha, beta, and release distributions are available in 213@example 214@url{ftp://ftp.am-utils.org/pub/am-utils/}. 215@end example 216 217Revision 5.2 was part of the 4.3BSD Reno distribution. 218 219Revision 5.3bsdnet, a late alpha version of 5.3, was part 220of the BSD network version 2 distribution 221 222Revision 6.0 was made independently by 223Erez Zadok at the Computer Science 224Department of @uref{http://www.cs.columbia.edu/,Columbia University}, 225as part of his 226@uref{http://www.fsl.cs.sunysb.edu/docs/zadok-thesis-proposal/,PhD 227thesis work}. Am-utils (especially version 6.1) continues to be 228developed and maintained at the 229@uref{http://www.cs.sunysb.edu/,Computer Science Department} of 230@uref{http://www.stonybrook.edu/,Stony Brook University}, as a service 231to the user community. 232 233 234@xref{History}, for more details. 235 236@c ################################################################ 237@node AddInfo, Intro, Distrib, Top 238@unnumbered Getting Additional Information 239@cindex Getting Additional Information 240 241@unnumberedsec Bug Reports 242@cindex Bug reports 243 244Before reporting a bug, see if it is a known one in the 245@uref{http://www.am-utils.org/docs/am-utils/BUGS.txt,bugs} file. 246 247If you find a problem and hopefully you can reproduce it, please 248describe it in detail and 249@uref{https://bugzilla.filesystems.org/,submit a bug report} via 250@uref{http://www.bugzilla.org/,Bugzilla}. Alternatively, you can send 251your bug report to the ``am-utils'' list (see 252@url{http://www.am-utils.org/} under ``Mailing Lists'') quoting the details 253of the release and your configuration. These details can be obtained 254by running the command @samp{amd -v}. It would greatly help if you 255could provide a reproducible procedure for detecting the bug you are 256reporting. 257 258Providing working patches is highly encouraged. Every patch 259incorporated, however small, will get its author an honorable mention in 260the @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors 261file}. 262 263@unnumberedsec Mailing Lists 264@cindex Mailing lists 265 266There are several mailing lists for people interested in keeping up-to-date 267with developments. 268 269@c ############### 270 271@enumerate 272 273@item 274The users mailing list, @samp{am-utils} is for 275 276@itemize @minus 277@item 278announcements of alpha and beta releases of am-utils 279@item 280reporting of bugs and patches 281@item 282discussions of new features for am-utils 283@item 284implementation and porting issues 285@end itemize 286 287To subscribe, visit @url{http://www.am-utils.org/} under ``Mailing 288Lists.'' After subscribing, you can post a message to this list. To 289avoid as much spam as possible, only subscribers to this list may post 290to it. 291 292Subscribers of @samp{am-utils} are most helpful if they have the time 293and resources to test new and development versions of amd, on as many 294different platforms as possible. They should also be prepared to 295learn and use the GNU Autoconf, Automake, and Libtool packages, as 296needed; and of course, become familiar with the complex code in the 297am-utils package. In other words, subscribers on this list should 298hopefully be able to contribute meaningfully to the development of 299amd. 300 301Note that this @samp{am-utils} list used to be called @samp{amd-dev} 302before January 1st, 2004. Please use the new name, @samp{am-utils}. 303 304@item 305The announcements mailing list, @samp{am-utils-announce} is for 306announcements only (mostly new releases). To subscribe, visit 307@url{http://www.am-utils.org/} under ``Mailing Lists.'' 308This list is read-only: only am-utils developers may post to it. 309 310@item 311We distribute nightly CVS snapshots in 312@url{ftp://ftp.am-utils.org/pub/am-utils/snapshots/daily/}. If you 313like to get email notices of commits to the am-utils CVS repository, 314subscribe to the CVS logs mailing list, @samp{am-utils-cvs} at 315@url{http://www.am-utils.org/} under ``Mailing Lists.'' 316 317@item 318The older list which was used to user discussions, @samp{amd-workers}, 319is defunct as of January 2004. (Its last address was 320@email{amd-workers AT majordomo.glue.umd.edu}.) Don't use 321@samp{amd-workers}: use the newer, more active @samp{am-utils} list. 322 323@item 324For completeness, there's a developers-only closed list called 325@samp{am-utils-developers} (see @url{http://www.am-utils.org/} under 326``Mailing Lists''). 327 328@end enumerate 329 330@unnumberedsec Am-utils Book 331@cindex Am-utils book 332@cindex Amd book 333@cindex Automounter book 334@cindex book 335 336@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} wrote a 337@uref{http://www.fsl.cs.sunysb.edu/docs/amd-book/,book}, titled @i{Linux NFS and 338Automounter Administration}, ISBN 0-7821-2739-8, (Sybex, 2001). The 339book is full of details and examples that go beyond what this manual 340has. The book also covers NFS in great detail. Although the book is 341geared toward Linux users, it is general enough for any Unix 342administrator and contains specific sections for non-Linux systems. 343 344@c ################################################################ 345@node Intro, History, AddInfo, Top 346@unnumbered Introduction 347@cindex Introduction 348 349An @dfn{automounter} maintains a cache of mounted filesystems. 350Filesystems are mounted on demand when they are first referenced, 351and unmounted after a period of inactivity. 352 353@i{Amd} may be used as a replacement for Sun's automounter. The choice 354of which filesystem to mount can be controlled dynamically with 355@dfn{selectors}. Selectors allow decisions of the form ``hostname is 356@var{this},'' or ``architecture is not @var{that}.'' Selectors may be 357combined arbitrarily. @i{Amd} also supports a variety of filesystem 358types, including NFS, UFS and the novel @dfn{program} filesystem. The 359combination of selectors and multiple filesystem types allows identical 360configuration files to be used on all machines thus reducing the 361administrative overhead. 362 363@i{Amd} ensures that it will not hang if a remote server goes down. 364Moreover, @i{Amd} can determine when a remote server has become 365inaccessible and then mount replacement filesystems as and when they 366become available. 367 368@i{Amd} contains no proprietary source code and has been ported to 369numerous flavors of Unix. 370 371@c ################################################################ 372@node History, Overview, Intro, Top 373@unnumbered History 374@cindex History 375 376The @i{Amd} package has been without an official maintainer since 1992. 377Several people have stepped in to maintain it unofficially. Most 378notable were the `upl' (Unofficial Patch Level) releases of @i{Amd}, 379created by me (@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok}), and available from 380@url{ftp://ftp.am-utils.org/pub/amd/}. The last such unofficial 381release was `upl102'. 382 383Through the process of patching and aging, it was becoming more and more 384apparent that @i{Amd} was in much need of revitalizing. Maintaining 385@i{Amd} had become a difficult task. I took it upon myself to cleanup 386the code, so that it would be easier to port to new platforms, add new 387features, keep up with the many new feature requests, and deal with the 388never ending stream of bug reports. 389 390I have been working on such a release of @i{Amd} on and off since 391January of 1996. The new suite of tools is currently named "am-utils" 392(AutoMounter Utilities), in line with GNU naming conventions, befitting 393the contents of the package. In October of 1996 I had received enough 394offers to help me with this task that I decided to make a mailing list 395for this group of people. Around the same time, @i{Amd} had become a 396necessary part of my PhD thesis work, resulting in more work performed 397on am-utils. 398 399Am-utils version 6.0 was numbered with a major new release number to 400distinguish it from the last official release of @i{Amd} (5.x). Many 401new features have been added such as a GNU @code{configure} system, NFS 402Version 3, a run-time configuration file (`amd.conf'), many new ports, 403more scripts and programs, as well as numerous bug fixes. Another 404reason for the new major release number was to alert users of am-utils 405that user-visible interfaces may have changed. In order to make @i{Amd} 406work well for the next 10 years, and be easier to maintain, it was 407necessary to remove old or unused features, change various syntax files, 408etc. However, great care was taken to ensure the maximum possible 409backwards compatibility. 410 411Am-utils version 6.1 has autofs support for Linux and Solaris 2.5+ as 412@i{the} major new feature, in addition to several other minor new 413features. The autofs support is completely transparent to the 414end-user, aside from the fact that @code{/bin/pwd} now always returns 415the correct amd-ified path. The administrator can easily switch 416between NFS and autofs mounts by changing one parameter in 417@code{amd.conf}. Autofs support and maintenance was developed in 418conjunction with @email{ionut AT badula.org,Ion Badulescu}. 419 420@c ################################################################ 421@node Overview, Supported Platforms, History, Top 422@chapter Overview 423 424@i{Amd} maintains a cache of mounted filesystems. Filesystems are 425@dfn{demand-mounted} when they are first referenced, and unmounted after 426a period of inactivity. @i{Amd} may be used as a replacement for Sun's 427@b{automount}(8) program. It contains no proprietary source code and 428has been ported to numerous flavors of Unix. @xref{Supported 429Platforms}.@refill 430 431@i{Amd} was designed as the basis for experimenting with filesystem 432layout and management. Although @i{Amd} has many direct applications it 433is loaded with additional features which have little practical use. At 434some point the infrequently used components may be removed to streamline 435the production system. 436 437@i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating 438each member of a list of possible filesystem locations one by one. 439@i{Amd} checks that each cached mapping remains valid. Should a mapping be 440lost -- such as happens when a fileserver goes down -- @i{Amd} automatically 441selects a replacement should one be available. 442 443@menu 444* Fundamentals:: 445* Filesystems and Volumes:: 446* Volume Naming:: 447* Volume Binding:: 448* Operational Principles:: 449* Mounting a Volume:: 450* Automatic Unmounting:: 451* Keep-alives:: 452* Non-blocking Operation:: 453@end menu 454 455@node Fundamentals, Filesystems and Volumes, Overview, Overview 456@comment node-name, next, previous, up 457@section Fundamentals 458@cindex Automounter fundamentals 459 460The fundamental concept behind @i{Amd} is the ability to separate the 461name used to refer to a file from the name used to refer to its physical 462storage location. This allows the same files to be accessed with the 463same name regardless of where in the network the name is used. This is 464very different from placing @file{/n/hostname} in front of the pathname 465since that includes location dependent information which may change if 466files are moved to another machine. 467 468By placing the required mappings in a centrally administered database, 469filesystems can be re-organized without requiring changes to 470configuration files, shell scripts and so on. 471 472@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview 473@comment node-name, next, previous, up 474@section Filesystems and Volumes 475@cindex Filesystem 476@cindex Volume 477@cindex Fileserver 478@cindex sublink 479 480@i{Amd} views the world as a set of fileservers, each containing one or 481more filesystems where each filesystem contains one or more 482@dfn{volumes}. Here the term @dfn{volume} is used to refer to a 483coherent set of files such as a user's home directory or a @TeX{} 484distribution.@refill 485 486In order to access the contents of a volume, @i{Amd} must be told in 487which filesystem the volume resides and which host owns the filesystem. 488By default the host is assumed to be local and the volume is assumed to 489be the entire filesystem. If a filesystem contains more than one 490volume, then a @dfn{sublink} is used to refer to the sub-directory 491within the filesystem where the volume can be found. 492 493@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview 494@comment node-name, next, previous, up 495@section Volume Naming 496@cindex Volume names 497@cindex Network-wide naming 498@cindex Replicated volumes 499@cindex Duplicated volumes 500@cindex Replacement volumes 501 502Volume names are defined to be unique across the entire network. A 503volume name is the pathname to the volume's root as known by the users 504of that volume. Since this name uniquely identifies the volume 505contents, all volumes can be named and accessed from each host, subject 506to administrative controls. 507 508Volumes may be replicated or duplicated. Replicated volumes contain 509identical copies of the same data and reside at two or more locations in 510the network. Each of the replicated volumes can be used 511interchangeably. Duplicated volumes each have the same name but contain 512different, though functionally identical, data. For example, 513@samp{/vol/tex} might be the name of a @TeX{} distribution which varied 514for each machine architecture.@refill 515 516@i{Amd} provides facilities to take advantage of both replicated and 517duplicated volumes. Configuration options allow a single set of 518configuration data to be shared across an entire network by taking 519advantage of replicated and duplicated volumes. 520 521@i{Amd} can take advantage of replacement volumes by mounting them as 522required should an active fileserver become unavailable. 523 524@node Volume Binding, Operational Principles, Volume Naming, Overview 525@comment node-name, next, previous, up 526@section Volume Binding 527@cindex Volume binding 528@cindex Unix namespace 529@cindex Namespace 530@cindex Binding names to filesystems 531 532Unix implements a namespace of hierarchically mounted filesystems. Two 533forms of binding between names and files are provided. A @dfn{hard 534link} completes the binding when the name is added to the filesystem. A 535@dfn{soft link} delays the binding until the name is accessed. An 536@dfn{automounter} adds a further form in which the binding of name to 537filesystem is delayed until the name is accessed.@refill 538 539The target volume, in its general form, is a tuple (host, filesystem, 540sublink) which can be used to name the physical location of any volume 541in the network. 542 543When a target is referenced, @i{Amd} ignores the sublink element and 544determines whether the required filesystem is already mounted. This is 545done by computing the local mount point for the filesystem and checking 546for an existing filesystem mounted at the same place. If such a 547filesystem already exists then it is assumed to be functionally 548identical to the target filesystem. By default there is a one-to-one 549mapping between the pair (host, filesystem) and the local mount point so 550this assumption is valid. 551 552@node Operational Principles, Mounting a Volume, Volume Binding, Overview 553@comment node-name, next, previous, up 554@section Operational Principles 555@cindex Operational principles 556 557@i{Amd} operates by introducing new mount points into the namespace. 558These are called @dfn{automount} points. The kernel sees these 559automount points as NFS filesystems being served by @i{Amd}. Having 560attached itself to the namespace, @i{Amd} is now able to control the 561view the rest of the system has of those mount points. RPC calls are 562received from the kernel one at a time. 563 564When a @dfn{lookup} call is received @i{Amd} checks whether the name is 565already known. If it is not, the required volume is mounted. A 566symbolic link pointing to the volume root is then returned. Once the 567symbolic link is returned, the kernel will send all other requests 568direct to the mounted filesystem. 569 570If a volume is not yet mounted, @i{Amd} consults a configuration 571@dfn{mount-map} corresponding to the automount point. @i{Amd} then 572makes a runtime decision on what and where to mount a filesystem based 573on the information obtained from the map. 574 575@i{Amd} does not implement all the NFS requests; only those relevant 576to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. 577Some other calls are also implemented but most simply return an error 578code; for example @dfn{mkdir} always returns ``read-only filesystem''. 579 580@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview 581@comment node-name, next, previous, up 582@section Mounting a Volume 583@cindex Mounting a volume 584@cindex Location lists 585@cindex Alternate locations 586@cindex Mount retries 587@cindex Background mounts 588 589Each automount point has a corresponding mount map. The mount map 590contains a list of key--value pairs. The key is the name of the volume 591to be mounted. The value is a list of locations describing where the 592filesystem is stored in the network. In the source for the map the 593value would look like 594 595@display 596location1 location2 @dots{} locationN 597@end display 598 599@i{Amd} examines each location in turn. Each location may contain 600@dfn{selectors} which control whether @i{Amd} can use that location. 601For example, the location may be restricted to use by certain hosts. 602Those locations which cannot be used are ignored. 603 604@i{Amd} attempts to mount the filesystem described by each remaining 605location until a mount succeeds or @i{Amd} can no longer proceed. The 606latter can occur in three ways: 607 608@itemize @bullet 609@item 610If none of the locations could be used, or if all of the locations 611caused an error, then the last error is returned. 612 613@item 614If a location could be used but was being mounted in the background then 615@i{Amd} marks that mount as being ``in progress'' and continues with 616the next request; no reply is sent to the kernel. 617 618@item 619Lastly, one or more of the mounts may have been @dfn{deferred}. A mount 620is deferred if extra information is required before the mount can 621proceed. When the information becomes available the mount will take 622place, but in the mean time no reply is sent to the kernel. If the 623mount is deferred, @i{Amd} continues to try any remaining locations. 624@end itemize 625 626Once a volume has been mounted, @i{Amd} establishes a @dfn{volume 627mapping} which is used to satisfy subsequent requests.@refill 628 629@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview 630@comment node-name, next, previous, up 631@section Automatic Unmounting 632 633To avoid an ever increasing number of filesystem mounts, @i{Amd} removes 634volume mappings which have not been used recently. A time-to-live 635interval is associated with each mapping and when that expires the 636mapping is removed. When the last reference to a filesystem is removed, 637that filesystem is unmounted. If the unmount fails, for example the 638filesystem is still busy, the mapping is re-instated and its 639time-to-live interval is extended. The global default for this grace 640period is controlled by the @code{-w} command-line option (@pxref{-w 641Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval} 642(@pxref{dismount_interval Parameter}). It is also possible to set this 643value on a per-mount basis (@pxref{opts Option, opts, opts}). 644 645Filesystems can be forcefully timed out using the @i{Amq} command. 646@xref{Run-time Administration}. Note that on new enough systems that 647support forced unmounts, such as Linux, @i{Amd} can try to use the 648@b{umount2}(2) system call to force the unmount, if the regular 649@b{umount}(2) system call failed in a way that indicates that the 650mount point is hung or stale. @xref{forced_unmounts Parameter}. 651 652@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview 653@comment node-name, next, previous, up 654@section Keep-alives 655@cindex Keep-alives 656@cindex Server crashes 657@cindex NFS ping 658 659Use of some filesystem types requires the presence of a server on 660another machine. If a machine crashes then it is of no concern to 661processes on that machine that the filesystem is unavailable. However, 662to processes on a remote host using that machine as a fileserver this 663event is important. This situation is most widely recognized when an 664NFS server crashes and the behavior observed on client machines is that 665more and more processes hang. In order to provide the possibility of 666recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some 667filesystem types. Currently only NFS makes use of this service. 668 669The basis of the NFS keep-alive implementation is the observation that 670most sites maintain replicated copies of common system data such as 671manual pages, most or all programs, system source code and so on. If 672one of those servers goes down it would be reasonable to mount one of 673the others as a replacement. 674 675The first part of the process is to keep track of which fileservers are 676up and which are down. @i{Amd} does this by sending RPC requests to the 677servers' NFS @code{NullProc} and checking whether a reply is returned. 678While the server state is uncertain the requests are re-transmitted at 679three second intervals and if no reply is received after four attempts 680the server is marked down. If a reply is received the fileserver is 681marked up and stays in that state for 30 seconds at which time another 682NFS ping is sent. This interval is configurable and can even be 683turned off using the @i{ping} option. @xref{opts Option}. 684 685Once a fileserver is marked down, requests continue to be sent every 30 686seconds in order to determine when the fileserver comes back up. During 687this time any reference through @i{Amd} to the filesystems on that 688server fail with the error ``Operation would block''. If a replacement 689volume is available then it will be mounted, otherwise the error is 690returned to the user. 691 692@c @i{Amd} keeps track of which servers are up and which are down. 693@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and 694@c checking whether a reply is returned. If no replies are received after a 695@c short period, @i{Amd} marks the fileserver @dfn{down}. 696@c RPC requests continue to be sent so that it will notice when a fileserver 697@c comes back up. 698@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability 699@c of the NFS service that is important, not the existence of a base kernel. 700@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate 701@c filesystem is mounted if one is available. 702@c 703Although this action does not protect user files, which are unique on 704the network, or processes which do not access files via @i{Amd} or 705already have open files on the hung filesystem, it can prevent most new 706processes from hanging. 707@c 708@c With a suitable combination of filesystem management and mount-maps, 709@c machines can be protected against most server downtime. This can be 710@c enhanced by allocating boot-servers dynamically which allows a diskless 711@c workstation to be quickly restarted if necessary. Once the root filesystem 712@c is mounted, @i{Amd} can be started and allowed to mount the remainder of 713@c the filesystem from whichever fileservers are available. 714 715@node Non-blocking Operation, , Keep-alives, Overview 716@comment node-name, next, previous, up 717@section Non-blocking Operation 718@cindex Non-blocking operation 719@cindex Multiple-threaded server 720@cindex RPC retries 721 722Since there is only one instance of @i{Amd} for each automount point, 723and usually only one instance on each machine, it is important that it 724is always available to service kernel calls. @i{Amd} goes to great 725lengths to ensure that it does not block in a system call. As a last 726resort @i{Amd} will fork before it attempts a system call that may block 727indefinitely, such as mounting an NFS filesystem. Other tasks such as 728obtaining filehandle information for an NFS filesystem, are done using a 729purpose built non-blocking RPC library which is integrated with 730@i{Amd}'s task scheduler. This library is also used to implement NFS 731keep-alives (@pxref{Keep-alives}). 732 733Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it 734to complete before replying to the kernel. However, this would cause 735@i{Amd} to block waiting for a reply to be constructed. Rather than do 736this, @i{Amd} simply @dfn{drops} the call under the assumption that the 737kernel RPC mechanism will automatically retry the request. 738 739@c ################################################################ 740@node Supported Platforms, Mount Maps, Overview, Top 741@comment node-name, next, previous, up 742@chapter Supported Platforms 743@cindex Supported Platforms 744@cindex shared libraries 745@cindex NFS V.3 support 746 747@i{Am-utils} has been ported to a wide variety of machines and operating 748systems. @i{Am-utils}'s code works for little-endian and big-endian 749machines, as well as 32 bit and 64 bit architectures. Furthermore, when 750@i{Am-utils} ports to an Operating System on one architecture, it is generally 751readily portable to the same Operating System on all platforms on which 752it is available. 753 754See the @file{INSTALL} in the distribution for more specific details on 755building and/or configuring for some systems. 756 757@c ################################################################ 758@node Mount Maps, Amd Command Line Options, Supported Platforms, Top 759@comment node-name, next, previous, up 760@chapter Mount Maps 761@cindex Mount maps 762@cindex Automounter configuration maps 763@cindex Mount information 764 765@i{Amd} has no built-in knowledge of machines or filesystems. 766External @dfn{mount-maps} are used to provide the required information. 767Specifically, @i{Amd} needs to know when and under what conditions it 768should mount filesystems. 769 770The map entry corresponding to the requested name contains a list of 771possible locations from which to resolve the request. Each location 772specifies filesystem type, information required by that filesystem (for 773example the block special device in the case of UFS), and some 774information describing where to mount the filesystem (@pxref{fs Option}). A 775location may also contain @dfn{selectors} (@pxref{Selectors}).@refill 776 777@menu 778* Map Types:: 779* Key Lookup:: 780* Location Format:: 781@end menu 782 783@node Map Types, Key Lookup, Mount Maps, Mount Maps 784@comment node-name, next, previous, up 785@section Map Types 786@cindex Mount map types 787@cindex Map types 788@cindex Configuration map types 789@cindex Types of mount map 790@cindex Types of configuration map 791@cindex Determining the map type 792 793A mount-map provides the run-time configuration information to @i{Amd}. 794Maps can be implemented in many ways. Some of the forms supported by 795@i{Amd} are regular files, ndbm databases, NIS maps, the @dfn{Hesiod} 796name server, and even the password file. 797 798A mount-map @dfn{name} is a sequence of characters. When an automount 799point is created a handle on the mount-map is obtained. For each map 800type configured, @i{Amd} attempts to reference the map of the 801appropriate type. If a map is found, @i{Amd} notes the type for future 802use and deletes the reference, for example closing any open file 803descriptors. The available maps are configured when @i{Amd} is built 804and can be displayed by running the command @samp{amd -v}. 805 806When using an @i{Amd} configuration file (@pxref{Amd Configuration File}) 807and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may 808force the map used to any type. 809 810By default, @i{Amd} caches data in a mode dependent on the type of map. 811This is the same as specifying @samp{cache:=mapdefault} and selects a 812suitable default cache mode depending on the map type. The individual 813defaults are described below. The @var{cache} option can be specified 814on automount points to alter the caching behavior (@pxref{Automount 815Filesystem}).@refill 816 817The following map types have been implemented, though some are not 818available on all machines. Run the command @samp{amd -v} to obtain a 819list of map types configured on your machine. 820 821@menu 822* File maps:: 823* ndbm maps:: 824* NIS maps:: 825* NIS+ maps:: 826* Hesiod maps:: 827* Password maps:: 828* Union maps:: 829* LDAP maps:: 830* Executable maps:: 831@end menu 832 833@c ---------------------------------------------------------------- 834@node File maps, ndbm maps, Map Types, Map Types 835@comment node-name, next, previous, up 836@subsection File maps 837@cindex File maps 838@cindex Flat file maps 839@cindex File map syntactic conventions 840 841When @i{Amd} searches a file for a map entry it does a simple scan of 842the file and supports both comments and continuation lines. 843 844Continuation lines are indicated by a backslash character (@samp{\}) as 845the last character of a line in the file. The backslash, newline character 846@emph{and any leading white space on the following line} are discarded. A maximum 847line length of 2047 characters is enforced after continuation lines are read 848but before comments are stripped. Each line must end with 849a newline character; that is newlines are terminators, not separators. 850The following examples illustrate this: 851 852@example 853key valA valB; \ 854 valC 855@end example 856 857specifies @emph{three} locations, and is identical to 858 859@example 860key valA valB; valC 861@end example 862 863However, 864 865@example 866key valA valB;\ 867 valC 868@end example 869 870specifies only @emph{two} locations, and is identical to 871 872@example 873key valA valB;valC 874@end example 875 876After a complete line has been read from the file, including 877continuations, @i{Amd} determines whether there is a comment on the 878line. A comment begins with a hash (``@samp{#}'') character and 879continues to the end of the line. There is no way to escape or change 880the comment lead-in character. 881 882Note that continuation lines and comment support @dfn{only} apply to 883file maps, or ndbm maps built with the @code{mk-amd-map} program. 884 885When caching is enabled, file maps have a default cache mode of 886@code{all} (@pxref{Automount Filesystem}). 887 888@c ---------------------------------------------------------------- 889@node ndbm maps, NIS maps, File maps, Map Types 890@comment node-name, next, previous, up 891@subsection ndbm maps 892@cindex ndbm maps 893 894An ndbm map may be used as a fast access form of a file map. The program, 895@code{mk-amd-map}, converts a normal map file into an ndbm database. 896This program supports the same continuation and comment conventions that 897are provided for file maps. Note that ndbm format files may @emph{not} 898be sharable across machine architectures. The notion of speed generally 899only applies to large maps; a small map, less than a single disk block, 900is almost certainly better implemented as a file map. 901 902ndbm maps have a default cache mode of @samp{all} 903(@pxref{Automount Filesystem}). 904 905@c ---------------------------------------------------------------- 906@node NIS maps, NIS+ maps, ndbm maps, Map Types 907@comment node-name, next, previous, up 908@subsection NIS maps 909@cindex NIS (YP) maps 910 911When using NIS (formerly YP), an @i{Amd} map is implemented directly 912by the underlying NIS map. Comments and continuation lines are 913@emph{not} supported in the automounter and must be stripped when 914constructing the NIS server's database. 915 916NIS maps have a default cache mode of @code{all} (@pxref{Automount 917Filesystem}). 918 919The following rule illustrates what could be added to your NIS @file{Makefile}, 920in this case causing the @file{amd.home} map to be rebuilt: 921@example 922$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home 923 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ 924 awk '@{ \ 925 for (i = 1; i <= NF; i++) \ 926 if (i == NF) @{ \ 927 if (substr($$i, length($$i), 1) == "\\") \ 928 printf("%s", substr($$i, 1, length($$i) - 1)); \ 929 else \ 930 printf("%s\n", $$i); \ 931 @} \ 932 else \ 933 printf("%s ", $$i); \ 934 @}' | \ 935 $(MAKEDBM) - $(YPDBDIR)/amd.home; \ 936 touch $(YPTSDIR)/amd.home.time; \ 937 echo "updated amd.home"; \ 938 if [ ! $(NOPUSH) ]; then \ 939 $(YPPUSH) amd.home; \ 940 echo "pushed amd.home"; \ 941 else \ 942 : ; \ 943 fi 944@end example 945 946Here @code{$(YPTSDIR)} contains the time stamp files, and 947@code{$(YPDBDIR)} contains the dbm format NIS files. 948 949@c ---------------------------------------------------------------- 950@node NIS+ maps, Hesiod maps, NIS maps, Map Types 951@comment node-name, next, previous, up 952@subsection NIS+ maps 953@cindex NIS+ maps 954 955NIS+ maps do not support cache mode @samp{all} and, when caching is 956enabled, have a default cache mode of @samp{inc}. 957 958XXX: FILL IN WITH AN EXAMPLE. 959 960@c ---------------------------------------------------------------- 961@node Hesiod maps, Password maps, NIS+ maps, Map Types 962@comment node-name, next, previous, up 963@subsection Hesiod maps 964@cindex Hesiod maps 965 966When the map name begins with the string @samp{hesiod.} lookups are made 967using the @dfn{Hesiod} name server. The string following the dot is 968used as a name qualifier and is prepended with the key being located. 969The entire string is then resolved in the @code{automount} context, or 970the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base 971Parameter}). For example, if the key is @samp{jsp} and map name is 972@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve 973@samp{jsp.homes.automount}. 974 975Hesiod maps do not support cache mode @samp{all} and, when caching is 976enabled, have a default cache mode of @samp{inc} (@pxref{Automount 977Filesystem}). 978 979The following is an example of a @dfn{Hesiod} map entry: 980 981@example 982jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" 983njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" 984@end example 985 986@c ---------------------------------------------------------------- 987@node Password maps, Union maps, Hesiod maps, Map Types 988@comment node-name, next, previous, up 989@subsection Password maps 990@cindex Password file maps 991@cindex /etc/passwd maps 992@cindex User maps, automatic generation 993@cindex Automatic generation of user maps 994@cindex Using the password file as a map 995 996The password map support is unlike the four previous map types. When 997the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user 998name in the password file and re-arrange the home directory field to 999produce a usable map entry. 1000 1001@i{Amd} assumes the home directory has the format 1002`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. 1003@c @footnote{This interpretation is not necessarily exactly what you want.} 1004It breaks this string into a map entry where @code{$@{rfs@}} has the 1005value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value 1006`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the 1007value @i{login}.@refill 1008 1009Thus if the password file entry was 1010 1011@example 1012/home/achilles/jsp 1013@end example 1014 1015the map entry used by @i{Amd} would be 1016 1017@example 1018rfs:=/home/achilles;rhost:=achilles;sublink:=jsp 1019@end example 1020 1021Similarly, if the password file entry was 1022 1023@example 1024/home/cc/sugar/mjh 1025@end example 1026 1027the map entry used by @i{Amd} would be 1028 1029@example 1030rfs:=/home/sugar;rhost:=sugar.cc;sublink:=mhj 1031@end example 1032 1033@c ---------------------------------------------------------------- 1034@node Union maps, LDAP maps, Password maps, Map Types 1035@comment node-name, next, previous, up 1036@subsection Union maps 1037@cindex Union file maps 1038 1039The union map support is provided specifically for use with the union 1040filesystem, @pxref{Union Filesystem}. 1041 1042It is identified by the string @samp{union:} which is followed by a 1043colon separated list of directories. The directories are read in order, 1044and the names of all entries are recorded in the map cache. Later 1045directories take precedence over earlier ones. The union filesystem 1046type then uses the map cache to determine the union of the names in all 1047the directories. 1048 1049@c ---------------------------------------------------------------- 1050@node LDAP maps, Executable maps, Union maps, Map Types 1051@comment node-name, next, previous, up 1052@subsection LDAP maps 1053@cindex LDAP maps 1054@cindex Lightweight Directory Access Protocol 1055 1056LDAP (Lightweight Directory Access Protocol) maps do not support cache 1057mode @samp{all} and, when caching is enabled, have a default cache mode 1058of @samp{inc}. 1059 1060For example, an @i{Amd} map @samp{amd.home} that looks as follows: 1061 1062@example 1063/defaults opts:=rw,intr;type:=link 1064 1065zing -rhost:=shekel \ 1066 host==shekel \ 1067 host!=shekel;type:=nfs 1068@end example 1069@noindent 1070when converted to LDAP (@pxref{amd2ldif}), will result in the following 1071LDAP database: 1072@example 1073$ amd2ldif amd.home CUCS < amd.home 1074dn: cn=amdmap timestamp, CUCS 1075cn : amdmap timestamp 1076objectClass : amdmapTimestamp 1077amdmapTimestamp: 873071363 1078 1079dn: cn=amdmap amd.home[/defaults], CUCS 1080cn : amdmap amd.home[/defaults] 1081objectClass : amdmap 1082amdmapName : amd.home 1083amdmapKey : /defaults 1084amdmapValue : opts:=rw,intr;type:=link 1085 1086dn: cn=amdmap amd.home[], CUCS 1087cn : amdmap amd.home[] 1088objectClass : amdmap 1089amdmapName : amd.home 1090amdmapKey : 1091amdmapValue : 1092 1093dn: cn=amdmap amd.home[zing], CUCS 1094cn : amdmap amd.home[zing] 1095objectClass : amdmap 1096amdmapName : amd.home 1097amdmapKey : zing 1098amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs 1099@end example 1100 1101@c ---------------------------------------------------------------- 1102@node Executable maps, , LDAP maps, Map Types 1103@comment node-name, next, previous, up 1104@subsection Executable maps 1105@cindex Executable maps 1106 1107An executable map is a dynamic map in which the keys and values for 1108the maps are generated on the fly by a program or script. The program 1109is expected to take a single parameter argument which is the key to 1110lookup. If the key is found, the program should print on stdout the 1111key-value pair that were found; if the key was not found, nothing 1112should be printed out. Below is an sample of such a map script: 1113 1114@example 1115#!/bin/sh 1116# executable map example 1117case "$1" in 1118 "/defaults" ) 1119 echo "/defaults type:=nfs;rfs:=filer" 1120 ;; 1121 "a" ) 1122 echo "a type:=nfs;fs:=/tmp" 1123 ;; 1124 "b" ) 1125 echo "b type:=link;fs:=/usr/local" 1126 ;; 1127 * ) # no match, echo nothing 1128 ;; 1129esac 1130@end example 1131 1132@xref{exec_map_timeout Parameter}. 1133 1134@c ---------------------------------------------------------------- 1135@c subsection Gdbm 1136@c ---------------------------------------------------------------- 1137@node Key Lookup, Location Format, Map Types, Mount Maps 1138@comment node-name, next, previous, up 1139@section How keys are looked up 1140@cindex Key lookup 1141@cindex Map lookup 1142@cindex Looking up keys 1143@cindex How keys are looked up 1144@cindex Wildcards in maps 1145 1146The key is located in the map whose type was determined when the 1147automount point was first created. In general the key is a pathname 1148component. In some circumstances this may be modified by variable 1149expansion (@pxref{Variable Expansion}) and prefixing. If the automount 1150point has a prefix, specified by the @var{pref} option, then that is 1151prepended to the search key before the map is searched. 1152 1153If the map cache is a @samp{regexp} cache then the key is treated as an 1154egrep-style regular expression, otherwise a normal string comparison is 1155made. 1156 1157If the key cannot be found then a @dfn{wildcard} match is attempted. 1158@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and 1159attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. 1160 1161For example, the following sequence would be checked if @file{home/dylan/dk2} was 1162being located: 1163 1164@example 1165 home/dylan/dk2 1166 home/dylan/* 1167 home/* 1168 * 1169@end example 1170 1171At any point when a wildcard is found, @i{Amd} proceeds as if an exact 1172match had been found and the value field is then used to resolve the 1173mount request, otherwise an error code is propagated back to the kernel. 1174(@pxref{Filesystem Types}).@refill 1175 1176@node Location Format, , Key Lookup, Mount Maps 1177@comment node-name, next, previous, up 1178@section Location Format 1179@cindex Location format 1180@cindex Map entry format 1181@cindex How locations are parsed 1182 1183The value field from the lookup provides the information required to 1184mount a filesystem. The information is parsed according to the syntax 1185shown below. 1186 1187@display 1188@i{location-list}: 1189 @i{location-selection} 1190 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} 1191@i{location-selection}: 1192 @i{location} 1193 @i{location-selection} @i{white-space} @i{location} 1194@i{location}: 1195 @i{location-info} 1196 @t{-}@i{location-info} 1197 @t{-} 1198@i{location-info}: 1199 @i{sel-or-opt} 1200 @i{location-info}@t{;}@i{sel-or-opt} 1201 @t{;} 1202@i{sel-or-opt}: 1203 @i{selection} 1204 @i{opt-ass} 1205@i{selection}: 1206 selector@t{==}@i{value} 1207 selector@t{!=}@i{value} 1208@i{opt-ass}: 1209 option@t{:=}@i{value} 1210@i{white-space}: 1211 space 1212 tab 1213@end display 1214 1215Note that unquoted whitespace is not allowed in a location description. 1216White space is only allowed, and is mandatory, where shown with non-terminal 1217@i{white-space}. 1218 1219A @dfn{location-selection} is a list of possible volumes with which to 1220satisfy the request. Each @dfn{location-selection} is tried 1221sequentially, until either one succeeds or all fail. This, by the 1222way, is different from the historically documented behavior, which 1223claimed (falsely, at least for last 3 years) that @i{Amd} would 1224attempt to mount all @dfn{location-selection}s in parallel and the 1225first one to succeed would be used. 1226 1227@dfn{location-selection}s are optionally separated by the @samp{||} 1228operator. The effect of this operator is to prevent use of 1229location-selections to its right if any of the location-selections on 1230its left were selected, whether or not any of them were successfully 1231mounted (@pxref{Selectors}).@refill 1232 1233The location-selection, and singleton @dfn{location-list}, 1234@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS 1235filesystem from the block special device @file{/dev/xd1g}. 1236 1237The @dfn{sel-or-opt} component is either the name of an option required 1238by a specific filesystem, or it is the name of a built-in, predefined 1239selector such as the architecture type. The value may be quoted with 1240double quotes @samp{"}, for example 1241@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the 1242value is parsed and there is no way to get a double quote into a value 1243field. Double quotes are used to get white space into a value field, 1244which is needed for the program filesystem (@pxref{Program Filesystem}).@refill 1245 1246@menu 1247* Map Defaults:: 1248* Variable Expansion:: 1249* Selectors:: 1250* Map Options:: 1251@end menu 1252 1253@node Map Defaults, Variable Expansion, Location Format, Location Format 1254@comment node-name, next, previous, up 1255@subsection Map Defaults 1256@cindex Map defaults 1257@cindex How to set default map parameters 1258@cindex Setting default map parameters 1259 1260A location beginning with a dash @samp{-} is used to specify default 1261values for subsequent locations. Any previously specified defaults in 1262the location-list are discarded. The default string can be empty in 1263which case no defaults apply. 1264 1265The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point 1266to @file{/mnt} and cause mounts to be read-only by default. Defaults 1267specified this way are appended to, and so override, any global map 1268defaults given with @samp{/defaults}). 1269 1270@c 1271@c A @samp{/defaults} value @dfn{gdef} and a location list 1272@c \begin{quote} 1273@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$ 1274@c \end{quote} 1275@c is equivalent to 1276@c \begin{quote} 1277@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$ 1278@c \end{quote} 1279@c which is equivalent to 1280@c \begin{quote} 1281@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$ 1282@c \end{quote} 1283 1284@node Variable Expansion, Selectors, Map Defaults, Location Format 1285@comment node-name, next, previous, up 1286@subsection Variable Expansion 1287@cindex Variable expansion 1288@cindex How variables are expanded 1289@cindex Pathname operators 1290@cindex Domain stripping 1291@cindex Domainname operators 1292@cindex Stripping the local domain name 1293@cindex Environment variables 1294@cindex How to access environment variables in maps 1295 1296To allow generic location specifications @i{Amd} does variable expansion 1297on each location and also on some of the option strings. Any option or 1298selector appearing in the form @code{$@dfn{var}} is replaced by the 1299current value of that option or selector. For example, if the value of 1300@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and 1301@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then 1302after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. 1303Any environment variable can be accessed in a similar way.@refill 1304 1305Two pathname operators are available when expanding a variable. If the 1306variable name begins with @samp{/} then only the last component of the 1307pathname is substituted. For example, if @code{$@{path@}} was 1308@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. 1309Similarly, if the variable name ends with @samp{/} then all but the last 1310component of the pathname is substituted. In the previous example, 1311@code{$@{path/@}} would be expanded to @samp{/foo}.@refill 1312 1313Two domain name operators are also provided. If the variable name 1314begins with @samp{.} then only the domain part of the name is 1315substituted. For example, if @code{$@{rhost@}} was 1316@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to 1317@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} 1318then only the host component is substituted. In the previous example, 1319@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill 1320 1321Variable expansion is a two phase process. Before a location is parsed, 1322all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The 1323location is then parsed, selections are evaluated and option assignments 1324recorded. If there were no selections or they all succeeded the 1325location is used and the values of the following options are expanded in 1326the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, 1327@var{remopts}, @var{mount} and @var{unmount}. 1328 1329Note that expansion of option values is done after @dfn{all} assignments 1330have been completed and not in a purely left to right order as is done 1331by the shell. This generally has the desired effect but care must be 1332taken if one of the options references another, in which case the 1333ordering can become significant. 1334 1335There are two special cases concerning variable expansion: 1336 1337@enumerate 1338@item 1339before a map is consulted, any selectors in the name received 1340from the kernel are expanded. For example, if the request from the 1341kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture 1342was @samp{vax}, the value given to @code{$@{key@}} would be 1343@samp{vax.bin}.@refill 1344 1345@item 1346the value of @code{$@{rhost@}} is expanded and normalized before the 1347other options are expanded. The normalization process strips any local 1348sub-domain components. For example, if @code{$@{domain@}} was 1349@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially 1350@samp{snow.Berkeley.EDU}, after the normalization it would simply be 1351@samp{snow}. Hostname normalization is currently done in a 1352@emph{case-dependent} manner.@refill 1353@end enumerate 1354 1355@c====================================================================== 1356@node Selectors, Map Options, Variable Expansion, Location Format 1357@comment node-name, next, previous, up 1358@subsection Selectors 1359@cindex Selectors 1360 1361Selectors are used to control the use of a location. It is possible to 1362share a mount map between many machines in such a way that filesystem 1363location, architecture and operating system differences are hidden from 1364the users. A selector of the form @samp{arch==sun3;os==sunos4} would only 1365apply on Sun-3s running SunOS 4.x. 1366 1367Selectors can be negated by using @samp{!=} instead of @samp{==}. For 1368example to select a location on all non-Vax machines the selector 1369@samp{arch!=vax} would be used. 1370 1371Selectors are evaluated left to right. If a selector fails then that 1372location is ignored. Thus the selectors form a conjunction and the 1373locations form a disjunction. If all the locations are ignored or 1374otherwise fail then @i{Amd} uses the @dfn{error} filesystem 1375(@pxref{Error Filesystem}). This is equivalent to having a location 1376@samp{type:=error} at the end of each mount-map entry.@refill 1377 1378The default value of many of the selectors listed here can be overridden 1379by an @i{Amd} command line switch or in an @i{Amd} configuration file. 1380@xref{Amd Configuration File}. 1381 1382The following selectors are currently implemented. 1383 1384@menu 1385* arch Selector Variable:: 1386* autodir Selector Variable:: 1387* byte Selector Variable:: 1388* cluster Selector Variable:: 1389* domain Selector Variable:: 1390* dollar Selector Variable:: 1391* host Selector Variable:: 1392* hostd Selector Variable:: 1393* karch Selector Variable:: 1394* os Selector Variable:: 1395* osver Selector Variable:: 1396* full_os Selector Variable:: 1397* vendor Selector Variable:: 1398 1399* key Selector Variable:: 1400* map Selector Variable:: 1401* netnumber Selector Variable:: 1402* network Selector Variable:: 1403* path Selector Variable:: 1404* wire Selector Variable:: 1405* uid Selector Variable:: 1406* gid Selector Variable:: 1407 1408* exists Selector Function:: 1409* false Selector Function:: 1410* netgrp Selector Function:: 1411* netgrpd Selector Function:: 1412* in_network Selector Function:: 1413* true Selector Function:: 1414* xhost Selector Function:: 1415@end menu 1416 1417@c ---------------------------------------------------------------- 1418@node arch Selector Variable, autodir Selector Variable, Selectors, Selectors 1419@comment node-name, next, previous, up 1420@subsubsection arch Selector Variable 1421@cindex arch Selector Variable 1422@cindex arch, mount selector 1423@cindex Mount selector; arch 1424@cindex Selector; arch 1425 1426The machine architecture which was automatically determined at compile 1427time. The architecture type can be displayed by running the command 1428@samp{amd -v}. You can override this value also using the @code{-A} 1429command line option. @xref{Supported Platforms}.@refill 1430 1431@c ---------------------------------------------------------------- 1432@node autodir Selector Variable, byte Selector Variable, arch Selector Variable, Selectors 1433@comment node-name, next, previous, up 1434@subsubsection autodir Selector Variable 1435@cindex autodir Selector Variable 1436@cindex autodir, mount selector 1437@cindex Mount selector; autodir 1438@cindex Selector; autodir 1439 1440The default directory under which to mount filesystems. This may be 1441changed by the @code{-a} command line option. @xref{fs Option}. 1442 1443@c ---------------------------------------------------------------- 1444@node byte Selector Variable, cluster Selector Variable, autodir Selector Variable, Selectors 1445@comment node-name, next, previous, up 1446@subsubsection byte Selector Variable 1447@cindex byte Selector Variable 1448@cindex byte, mount selector 1449@cindex Mount selector; byte 1450@cindex Selector; byte 1451 1452The machine's byte ordering. This is either @samp{little}, indicating 1453little-endian, or @samp{big}, indicating big-endian. One possible use 1454is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to 1455share ndbm databases, however this use can be considered a courageous 1456juggling act. 1457 1458@c ---------------------------------------------------------------- 1459@node cluster Selector Variable, domain Selector Variable, byte Selector Variable, Selectors 1460@comment node-name, next, previous, up 1461@subsubsection cluster Selector Variable 1462@cindex cluster Selector Variable 1463@cindex cluster, mount selector 1464@cindex Mount selector; cluster 1465@cindex Selector; cluster 1466 1467This is provided as a hook for the name of the local cluster. This can 1468be used to decide which servers to use for copies of replicated 1469filesystems. @code{$@{cluster@}} defaults to the value of 1470@code{$@{domain@}} unless a different value is set with the @code{-C} 1471command line option. 1472 1473@c ---------------------------------------------------------------- 1474@node domain Selector Variable, dollar Selector Variable, cluster Selector Variable, Selectors 1475@comment node-name, next, previous, up 1476@subsubsection domain Selector Variable 1477@cindex domain Selector Variable 1478@cindex domain, mount selector 1479@cindex Mount selector; domain 1480@cindex Selector; domain 1481 1482The local domain name as specified by the @code{-d} command line option. 1483@xref{host Selector Variable}. 1484 1485@c ---------------------------------------------------------------- 1486@node dollar Selector Variable, host Selector Variable, domain Selector Variable, Selectors 1487@comment node-name, next, previous, up 1488@subsubsection dollar Selector Variable 1489@cindex dollar Selector Variable 1490 1491This is a special variable, whose sole purpose is to produce a literal 1492dollar sign in the value of another variable. For example, if you have 1493a remote file system whose name is @samp{/disk$s}, you can mount it by 1494setting the remote file system variable as follows: 1495 1496@example 1497rfs:=/disk$@{dollar@}s 1498@end example 1499 1500@c ---------------------------------------------------------------- 1501@node host Selector Variable, hostd Selector Variable, dollar Selector Variable, Selectors 1502@comment node-name, next, previous, up 1503@subsubsection host Selector Variable 1504@cindex host Selector Variable 1505@cindex host, mount selector 1506@cindex Mount selector; host 1507@cindex Selector; host 1508 1509The local hostname as determined by @b{gethostname}(2). If no domain 1510name was specified on the command line and the hostname contains a 1511period @samp{.} then the string before the period is used as the host 1512name, and the string after the period is assigned to @code{$@{domain@}}. 1513For example, if the hostname is @samp{styx.doc.ic.ac.uk} then 1514@code{host} would be @samp{styx} and @code{domain} would be 1515@samp{doc.ic.ac.uk}. @code{hostd} would be 1516@samp{styx.doc.ic.ac.uk}.@refill 1517 1518@c ---------------------------------------------------------------- 1519@node hostd Selector Variable, karch Selector Variable, host Selector Variable, Selectors 1520@comment node-name, next, previous, up 1521@subsubsection hostd Selector Variable 1522@cindex hostd Selector Variable 1523@cindex hostd, mount selector 1524@cindex Mount selector; hostd 1525@cindex Selector; hostd 1526 1527This resolves to the @code{$@{host@}} and @code{$@{domain@}} 1528concatenated with a @samp{.} inserted between them if required. If 1529@code{$@{domain@}} is an empty string then @code{$@{host@}} and 1530@code{$@{hostd@}} will be identical. 1531 1532@c ---------------------------------------------------------------- 1533@node karch Selector Variable, os Selector Variable, hostd Selector Variable, Selectors 1534@comment node-name, next, previous, up 1535@subsubsection karch Selector Variable 1536@cindex karch Selector Variable 1537@cindex karch, mount selector 1538@cindex Mount selector; karch 1539@cindex Selector; karch 1540 1541This is provided as a hook for the kernel architecture. This is used on 1542SunOS 4 and SunOS 5, for example, to distinguish between different 1543@samp{/usr/kvm} volumes. @code{$@{karch@}} defaults to the ``machine'' 1544value gotten from @b{uname}(2). If the @b{uname}(2) system call is not 1545available, the value of @code{$@{karch@}} defaults to that of 1546@code{$@{arch@}}. Finally, a different value can be set with the @code{-k} 1547command line option. 1548 1549@c ---------------------------------------------------------------- 1550@node os Selector Variable, osver Selector Variable, karch Selector Variable, Selectors 1551@comment node-name, next, previous, up 1552@subsubsection os Selector Variable 1553@cindex os Selector Variable 1554@cindex os, mount selector 1555@cindex Mount selector; os 1556@cindex Selector; os 1557 1558The operating system. Like the machine architecture, this is 1559automatically determined at compile time. The operating system name can 1560be displayed by running the command @samp{amd -v}. @xref{Supported 1561Platforms}.@refill 1562 1563@c ---------------------------------------------------------------- 1564@node osver Selector Variable, full_os Selector Variable, os Selector Variable, Selectors 1565@comment node-name, next, previous, up 1566@subsubsection osver Selector Variable 1567@cindex osver Selector Variable 1568@cindex osver, mount selector 1569@cindex Mount selector; osver 1570@cindex Selector; osver 1571 1572The operating system version. Like the machine architecture, this is 1573automatically determined at compile time. The operating system name can 1574be displayed by running the command @samp{amd -v}. @xref{Supported 1575Platforms}.@refill 1576 1577@c ---------------------------------------------------------------- 1578@node full_os Selector Variable, vendor Selector Variable, osver Selector Variable, Selectors 1579@comment node-name, next, previous, up 1580@subsubsection full_os Selector Variable 1581@cindex full_os Selector Variable 1582@cindex full_os, mount selector 1583@cindex Mount selector; full_os 1584@cindex Selector; full_os 1585 1586The full name of the operating system, including its version. This 1587value is automatically determined at compile time. The full operating 1588system name and version can be displayed by running the command 1589@samp{amd -v}. @xref{Supported Platforms}.@refill 1590 1591@c ---------------------------------------------------------------- 1592@node vendor Selector Variable, key Selector Variable, full_os Selector Variable, Selectors 1593@comment node-name, next, previous, up 1594@subsubsection vendor Selector Variable 1595@cindex vendor Selector Variable 1596@cindex vendor, mount selector 1597@cindex Mount selector; vendor 1598@cindex Selector; vendor 1599 1600The name of the vendor of the operating system. This value is 1601automatically determined at compile time. The name of the vendor can be 1602displayed by running the command @samp{amd -v}. @xref{Supported 1603Platforms}.@refill 1604 1605 1606@c ---------------------------------------------------------------- 1607@ifhtml 1608<HR> 1609@end ifhtml 1610@sp 3 1611The following selectors are also provided. Unlike the other selectors, 1612they vary for each lookup. Note that when the name from the kernel is 1613expanded prior to a map lookup, these selectors are all defined as empty 1614strings. 1615 1616@c ---------------------------------------------------------------- 1617@node key Selector Variable, map Selector Variable, vendor Selector Variable, Selectors 1618@comment node-name, next, previous, up 1619@subsubsection key Selector Variable 1620@cindex key Selector Variable 1621@cindex key, mount selector 1622@cindex Mount selector; key 1623@cindex Selector; key 1624 1625The name being resolved. For example, if @file{/home} is an automount 1626point, then accessing @file{/home/foo} would set @code{$@{key@}} to the 1627string @samp{foo}. The key is prefixed by the @var{pref} option set in 1628the parent mount point. The default prefix is an empty string. If the 1629prefix was @file{blah/} then @code{$@{key@}} would be set to 1630@file{blah/foo}.@refill 1631 1632@c ---------------------------------------------------------------- 1633@node map Selector Variable, netnumber Selector Variable, key Selector Variable, Selectors 1634@comment node-name, next, previous, up 1635@subsubsection map Selector Variable 1636@cindex map Selector Variable 1637@cindex map, mount selector 1638@cindex Mount selector; map 1639@cindex Selector; map 1640 1641The name of the mount map being used. 1642 1643@c ---------------------------------------------------------------- 1644@node netnumber Selector Variable, network Selector Variable, map Selector Variable, Selectors 1645@comment node-name, next, previous, up 1646@subsubsection netnumber Selector Variable 1647@cindex netnumber Selector Variable 1648@cindex netnumber, mount selector 1649@cindex Mount selector; netnumber 1650@cindex Selector; netnumber 1651 1652This selector is identical to the @samp{in_network} selector function, 1653see @ref{in_network Selector Function}. It will match either the name 1654or number of @i{any} network interface on which this host is connected 1655to. The names and numbers of all attached interfaces are available from 1656the output of @samp{amd -v}. 1657 1658@c ---------------------------------------------------------------- 1659@node network Selector Variable, path Selector Variable, netnumber Selector Variable, Selectors 1660@comment node-name, next, previous, up 1661@subsubsection network Selector Variable 1662@cindex network Selector Variable 1663@cindex network, mount selector 1664@cindex Mount selector; network 1665@cindex Selector; network 1666 1667This selector is identical to the @samp{in_network} selector function, 1668see @ref{in_network Selector Function}. It will match either the name 1669or number of @i{any} network interface on which this host is connected 1670to. The names and numbers of all attached interfaces are available from 1671the output of @samp{amd -v}. 1672 1673@c ---------------------------------------------------------------- 1674@node path Selector Variable, wire Selector Variable, network Selector Variable, Selectors 1675@comment node-name, next, previous, up 1676@subsubsection path Selector Variable 1677@cindex path Selector Variable 1678@cindex path, mount selector 1679@cindex Mount selector; path 1680@cindex Selector; path 1681 1682The full pathname of the name being resolved. For example 1683@file{/home/foo} in the example above. 1684 1685@c ---------------------------------------------------------------- 1686@node wire Selector Variable, uid Selector Variable, path Selector Variable, Selectors 1687@comment node-name, next, previous, up 1688@subsubsection wire Selector Variable 1689@cindex wire Selector Variable 1690@cindex wire, mount selector 1691@cindex Mount selector; wire 1692@cindex Selector; wire 1693 1694This selector is identical to the @samp{in_network} selector function, 1695see @ref{in_network Selector Function}. It will match either the name 1696or number of @i{any} network interface on which this host is connected 1697to. The names and numbers of all attached interfaces are available from 1698the output of @samp{amd -v}. 1699 1700@c ---------------------------------------------------------------- 1701@node uid Selector Variable, gid Selector Variable, wire Selector Variable, Selectors 1702@comment node-name, next, previous, up 1703@subsubsection uid Selector Variable 1704@cindex uid Selector Variable 1705@cindex uid, mount selector 1706@cindex Mount selector; uid 1707@cindex Selector; uid 1708 1709This selector provides the numeric effective user ID (UID) of the user 1710which last accessed an automounted path name. This simple example shows 1711how floppy mounting can be assigned only to machine owners: 1712 1713@example 1714floppy -type:=pcfs \ 1715 uid==2301;host==shekel;dev:=/dev/floppy \ 1716 uid==6712;host==titan;dev=/dev/fd0 \ 1717 uid==0;dev:=/dev/fd0c \ 1718 type:=error 1719@end example 1720 1721The example allows two machine owners to mount floppies on their 1722designated workstations, allows the root user to mount on any host, and 1723otherwise forces an error. 1724 1725@c ---------------------------------------------------------------- 1726@node gid Selector Variable, exists Selector Function, uid Selector Variable, Selectors 1727@comment node-name, next, previous, up 1728@subsubsection gid Selector Variable 1729@cindex gid Selector Variable 1730@cindex gid, mount selector 1731@cindex Mount selector; gid 1732@cindex Selector; gid 1733 1734This selector provides the numeric effective group ID (GID) of the user 1735which last accessed an automounted path name. 1736 1737@c ---------------------------------------------------------------- 1738@ifhtml 1739<HR> 1740@end ifhtml 1741@sp 2 1742The following boolean functions are selectors which take an argument 1743@i{ARG}. They return a value of true or false, and thus do not need to 1744be compared with a value. Each of these may be negated by prepending 1745@samp{!} to their name. 1746 1747@c ---------------------------------------------------------------- 1748@node exists Selector Function, false Selector Function, gid Selector Variable, Selectors 1749@comment node-name, next, previous, up 1750@subsubsection exists Selector Function 1751@cindex exists Selector Function 1752@cindex exists, boolean mount selector 1753@cindex !exists, boolean mount selector 1754@cindex Mount selector; exists 1755@cindex Selector; exists 1756 1757If the file listed by @i{ARG} exists (via @b{lstat}(2)), this function 1758evaluates to true. Otherwise it evaluates to false. 1759 1760@c ---------------------------------------------------------------- 1761@node false Selector Function, netgrp Selector Function, exists Selector Function, Selectors 1762@comment node-name, next, previous, up 1763@subsubsection false Selector Function 1764@cindex false Selector Function 1765@cindex false, boolean mount selector 1766@cindex !false, boolean mount selector 1767@cindex Mount selector; false 1768@cindex Selector; false 1769 1770Always evaluates to false. @i{ARG} is ignored. 1771 1772@c ---------------------------------------------------------------- 1773@node netgrp Selector Function, netgrpd Selector Function, false Selector Function, Selectors 1774@comment node-name, next, previous, up 1775@subsubsection netgrp Selector Function 1776@cindex netgrp Selector Function 1777@cindex netgrp, boolean mount selector 1778@cindex !netgrp, boolean mount selector 1779@cindex Mount selector; netgrp 1780@cindex Selector; netgrp 1781 1782The argument @i{ARG} of this selector is a netgroup name followed 1783optionally by a comma and a host name. If the host name is not 1784specified, it defaults to @code{$@{host@}}. If the host name (short 1785name) is a member of the netgroup, this selector evaluates to true. 1786Otherwise it evaluates to false. 1787 1788For example, suppose you have a netgroup @samp{ppp-hosts}, and for 1789reasons of performance, these have a local @file{/home} partition, 1790while all other clients on the faster network can access a shared home 1791directory. A common map to use for both might look like the 1792following: 1793 1794@example 1795home/* netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \ 1796 !netgrp(ppp-hosts);type:=nfs;rhost:=serv1;rfs:=/remote/$@{key@} 1797@end example 1798 1799A more complex example that takes advantage of the two argument netgrp 1800mount selector is given in the following scenario. Suppose one wants 1801to mount the local scratch space from a each host under 1802@file{scratch/<hostname>} and some hosts have their scratch space in a 1803different path than others. Hosts in the netgroup @samp{apple-hosts} 1804have their scratch space in the @file{/apple} path, where hosts in the 1805netgroup @samp{cherry-hosts} have their scratch space in the 1806@file{/cherry} path. For hosts that are neither in the 1807@samp{apple-hosts} or @samp{cherry-hosts} netgroups we want to make a 1808symlink pointing to nowhere but provide a descriptive error message in 1809the link destination: 1810 1811@example 1812scratch/* netgrp(apple-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1813 rfs:="/apple" \ 1814 netgrp(cherry-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1815 rfs:="/cherry" \ 1816 type:=link;rfs:="no local partition for $@{/key@}" 1817@end example 1818 1819@c ---------------------------------------------------------------- 1820@node netgrpd Selector Function, in_network Selector Function, netgrp Selector Function, Selectors 1821@comment node-name, next, previous, up 1822@subsubsection netgrpd Selector Function 1823@cindex netgrpd Selector Function 1824@cindex netgrpd, boolean mount selector 1825@cindex !netgrpd, boolean mount selector 1826@cindex Mount selector; netgrpd 1827@cindex Selector; netgrpd 1828 1829The argument @i{ARG} of this selector is a netgroup name followed 1830optionally by a comma and a host name. If the host name is not 1831specified, it defaults to @code{$@{hostd@}}. If the host name 1832(fully-qualified name) is a member of the netgroup, this selector 1833evaluates to true. Otherwise it evaluates to false. 1834 1835The @samp{netgrpd} function uses fully-qualified host names to match 1836netgroup names, while the @samp{netgrp} function (@pxref{netgrp 1837Selector Function}) uses short host names. 1838 1839@c ---------------------------------------------------------------- 1840@node in_network Selector Function, true Selector Function, netgrpd Selector Function, Selectors 1841@comment node-name, next, previous, up 1842@subsubsection in_network Selector Function 1843@cindex in_network Selector Function 1844@cindex in_network, boolean mount selector 1845@cindex !in_network, boolean mount selector 1846@cindex Mount selector; in_network 1847@cindex Selector; in_network 1848 1849This selector matches against any network name or number with an 1850optional netmask. First, if the current host has any network interface that is 1851locally attached to the network specified in @i{ARG} (either via name or 1852number), this selector evaluates to true. 1853 1854Second, @samp{in_network} supports a network/netmask syntax such as 1855@samp{128.59.16.0/255.255.255.0}, @samp{128.59.16.0/24}, 1856@samp{128.59.16.0/0xffffff00}, or @samp{128.59.16.0/}. Using the last 1857form, @i{Amd} will match the specified network number against the 1858default netmasks of each of the locally attached interfaces. 1859 1860If the selector does not match, it evaluates to false. 1861 1862For example, suppose you have two servers that have an exportable 1863@file{/opt} that smaller clients can NFS mount. The two servers are 1864say, @samp{serv1} on network @samp{foo-net.site.com} and @samp{serv2} on 1865network @samp{123.4.5.0}. You can write a map to be used by all clients 1866that will attempt to mount the closest one as follows: 1867 1868@example 1869opt in_network(foo-net.site.com);rhost:=serv1;rfs:=/opt \ 1870 in_network(123.4.5.0);rhost:=serv2;rfs:=/opt \ 1871 rhost:=fallback-server 1872@end example 1873 1874@c ---------------------------------------------------------------- 1875@node true Selector Function, xhost Selector Function, in_network Selector Function, Selectors 1876@comment node-name, next, previous, up 1877@subsubsection true Selector Function 1878@cindex true Selector Function 1879@cindex true, boolean mount selector 1880@cindex !true, boolean mount selector 1881@cindex Mount selector; true 1882@cindex Selector; true 1883 1884Always evaluates to true. @i{ARG} is ignored. 1885 1886@c ---------------------------------------------------------------- 1887@node xhost Selector Function, , true Selector Function, Selectors 1888@comment node-name, next, previous, up 1889@subsubsection xhost Selector Function 1890@cindex xhost Selector Function 1891@cindex xhost, boolean mount selector 1892@cindex !xhost, boolean mount selector 1893@cindex Mount selector; xhost 1894@cindex Selector; xhost 1895@cindex CNAMEs 1896 1897This function compares @i{ARG} against the current hostname, similarly 1898to the @ref{host Selector Variable}. However, this function will 1899also match if @i{ARG} is a CNAME (DNS Canonical Name, or alias) for 1900the current host's name. 1901 1902@c ================================================================ 1903@node Map Options, , Selectors, Location Format 1904@comment node-name, next, previous, up 1905@subsection Map Options 1906@cindex Map options 1907@cindex Setting map options 1908 1909Options are parsed concurrently with selectors. The difference is that 1910when an option is seen the string following the @samp{:=} is 1911recorded for later use. As a minimum the @var{type} option must be 1912specified. Each filesystem type has other options which must also be 1913specified. @xref{Filesystem Types}, for details on the filesystem 1914specific options.@refill 1915 1916Superfluous option specifications are ignored and are not reported 1917as errors. 1918 1919The following options apply to more than one filesystem type. 1920 1921@menu 1922* addopts Option:: 1923* delay Option:: 1924* fs Option:: 1925* opts Option:: 1926* remopts Option:: 1927* sublink Option:: 1928* type Option:: 1929@end menu 1930 1931@node addopts Option, delay Option, Map Options, Map Options 1932@comment node-name, next, previous, up 1933@subsubsection addopts Option 1934@cindex Setting additional options on a mount location 1935@cindex Overriding or adding options to a mount 1936@cindex addopts, mount option 1937@cindex Mount option; addopts 1938 1939This option adds additional options to default options normally 1940specified in the @samp{/defaults} entry or the defaults of the key entry 1941being processed (@pxref{opts Option}). Normally when you specify 1942@samp{opts} in both the @samp{/defaults} and the map entry, the latter 1943overrides the former completely. But with @samp{addopts} it will append 1944the options and override any conflicting ones. 1945 1946@samp{addopts} also overrides the value of the @samp{remopts} option 1947(@pxref{remopts Option}), which unless specified defaults to the value 1948of @samp{opts}. 1949 1950Options which start with @samp{no} will override those with the same 1951name that do not start with @samp{no} and vice verse. Special handling 1952is given to inverted options such as @samp{soft} and @samp{hard}, 1953@samp{bg} and @samp{fg}, @samp{ro} and @samp{rw}, etc. 1954 1955For example, if the default options specified were 1956@example 1957opts:=rw,nosuid,intr,rsize=1024,wsize=1024,quota,posix 1958@end example 1959 1960and the ones specified in a map entry were 1961 1962@example 1963addopts:=grpid,suid,ro,rsize=2048,quota,nointr 1964@end example 1965 1966then the actual options used would be 1967 1968@example 1969wsize=1024,posix,grpid,suid,ro,rsize=2048,quota,nointr 1970@end example 1971 1972@node delay Option, fs Option, addopts Option, Map Options 1973@comment node-name, next, previous, up 1974@subsubsection delay Option 1975@cindex Setting a delay on a mount location 1976@cindex Delaying mounts from specific locations 1977@cindex Primary server 1978@cindex Secondary server 1979@cindex delay, mount option 1980@cindex Mount option; delay 1981 1982The delay, in seconds, before an attempt will be made to mount from the 1983current location. Auxiliary data, such as network address, file handles 1984and so on are computed regardless of this value. 1985 1986A delay can be used to implement the notion of primary and secondary 1987file servers. The secondary servers would have a delay of a few 1988seconds, thus giving the primary servers a chance to respond first. 1989 1990@node fs Option, opts Option, delay Option, Map Options 1991@comment node-name, next, previous, up 1992@subsubsection fs Option 1993@cindex Setting the local mount point 1994@cindex Overriding the default mount point 1995@cindex fs, mount option 1996@cindex Mount option; fs 1997 1998The local mount point. The semantics of this option vary between 1999filesystems. 2000 2001For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the 2002local mount point. For other filesystem types it has other meanings 2003which are described in the section describing the respective filesystem 2004type. It is important that this string uniquely identifies the 2005filesystem being mounted. To satisfy this requirement, it should 2006contain the name of the host on which the filesystem is resident and the 2007pathname of the filesystem on the local or remote host. 2008 2009The reason for requiring the hostname is clear if replicated filesystems 2010are considered. If a fileserver goes down and a replacement filesystem 2011is mounted then the @dfn{local} mount point @dfn{must} be different from 2012that of the filesystem which is hung. Some encoding of the filesystem 2013name is required if more than one filesystem is to be mounted from any 2014given host. 2015 2016If the hostname is first in the path then all mounts from a particular 2017host will be gathered below a single directory. If that server goes 2018down then the hung mount points are less likely to be accidentally 2019referenced, for example when @b{getcwd}(3) traverses the namespace to 2020find the pathname of the current directory. 2021 2022The @samp{fs} option defaults to 2023@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, 2024@samp{rhost} defaults to the local host name (@code{$@{host@}}) and 2025@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full 2026path of the requested file; @samp{/home/foo} in the example above 2027(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may 2028be changed with the @code{-a} command line option. Sun's automounter 2029defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between 2030the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins 2031with a @samp{/}.@refill 2032 2033@node opts Option, remopts Option, fs Option, Map Options 2034@comment node-name, next, previous, up 2035@subsubsection opts Option 2036@cindex Setting system mount options 2037@cindex Passing parameters to the mount system call 2038@cindex mount system call 2039@cindex mount system call flags 2040@cindex The mount system call 2041@cindex opts, mount option 2042@cindex Mount option; opts 2043 2044The options to pass to the mount system call. A leading @samp{-} is 2045silently ignored. The mount options supported generally correspond to 2046those used by @b{mount}(8) and are listed below. Some additional 2047pseudo-options are interpreted by @i{Amd} and are also listed. 2048 2049Unless specifically overridden, each of the system default mount options 2050applies. Any options not recognized are ignored. If no options list is 2051supplied the string @samp{rw,defaults} is used and all the system 2052default mount options apply. Options which are not applicable for a 2053particular operating system are silently ignored. For example, only 4.4BSD 2054is known to implement the @code{compress} and @code{spongy} options. 2055 2056@table @code 2057 2058@item acdirmax=@var{n} 2059@cindex Mount flags; acdirmax 2060Set the maximum directory attribute cache timeout to @var{n}. 2061 2062@item acdirmin=@var{n} 2063@cindex Mount flags; acdirmin 2064Set the minimum directory attribute cache timeout to @var{n}. 2065 2066@item acregmax=@var{n} 2067@cindex Mount flags; acregmax 2068Set the maximum file attribute cache timeout to @var{n}. 2069 2070@item acregmin=@var{n} 2071@cindex Mount flags; acregmin 2072Set the minimum file attribute cache timeout to @var{n}. 2073 2074@item actimeo=@var{n} 2075@cindex Mount flags; actimeo 2076Set the overall attribute cache timeout to @var{n}. 2077 2078@item auto 2079@cindex Mount flags; auto 2080@itemx ignore 2081@cindex Mount flags; ignore 2082Ignore this mount by @b{df}(1). 2083 2084@item cache 2085@cindex Mount flags; cache 2086Allow data to be cached from a remote server for this mount. 2087 2088@item closesession 2089@cindex Mount flags; closesession 2090For UDF mounts, close the session when unmounting. 2091 2092@item compress 2093@cindex Mount flags; compress 2094Use NFS compression protocol. 2095 2096@item defperm 2097@cindex Mount flags; defperm 2098Ignore the permission mode bits, and default file permissions to 0555, 2099UID 0, and GID 0. Useful for CD-ROMs formatted as ISO-9660. 2100 2101@item dev 2102@cindex Mount flags; dev 2103Allow local special devices on this filesystem. 2104 2105@item dirmask=@var{n} 2106@cindex Mount flags; dirmask 2107For PCFS mounts, specify the maximum file permissions for directories 2108in the file system. See the @samp{mask} option's description for more 2109details. The mask value of @var{n} can be specified in decimal, 2110octal, or hexadecimal. 2111 2112@item dumbtimr 2113@cindex Mount flags; dumbtimr 2114Turn off the dynamic retransmit timeout estimator. This may be useful 2115for UDP mounts that exhibit high retry rates, since it is possible that 2116the dynamically estimated timeout interval is too short. 2117 2118@item extatt 2119@cindex Mount flags; extatt 2120Enable extended attributes in ISO-9660 file systems. 2121 2122@item fsid 2123@cindex Mount flags; fsid 2124Set ID of filesystem. 2125 2126@item gens 2127@cindex Mount flags; gens 2128Enable generations in ISO-9660 file systems. Generations allow you to 2129see all versions of a given file. 2130 2131@item gmtoff=@var{n} 2132@cindex Mount flags; gmtoff 2133For UDF mounts, set the time zone offset from UTC to @var{n} seconds, 2134with positive values indicating east of the Prime Meridian. If not 2135set, the user's current time zone will be used. 2136 2137@item group=@var{n} 2138@cindex Mount flags; group 2139For PCFS and UDF mounts, set the group of the files in the file system 2140to @var{n} (which can either be a group name or a GID number). The 2141default group is the group of the directory on which the file system 2142is being mounted. 2143 2144@item grpid 2145@cindex Mount flags; grpid 2146Use BSD directory group-id semantics. 2147 2148@item int 2149@cindex Mount flags; int 2150@itemx intr 2151@cindex Mount flags; intr 2152Allow keyboard interrupts on hard mounts. 2153 2154@item lock 2155@cindex Mount flags; lock 2156Use the NFS locking protocol (default) 2157 2158@item longname 2159@cindex Mount Flags; longname 2160For PCFS mounts, force Win95 long names. 2161 2162@item mask=@var{n} 2163@cindex Mount flags; mask 2164For PCFS mounts, specify the maximum file permissions for files in the 2165file system. For example, a mask of 755 specifies that, by default, 2166the owner should have read, write, and execute permissions for files, 2167but others should only have read and execute permissions. Only the 2168nine low-order bits of mask are used. The default mask is taken from 2169the directory on which the file system is being mounted. The mask 2170value of @var{n} can be specified in decimal, octal, or hexadecimal. 2171 2172@item multi 2173@cindex Mount flags; multi 2174Perform multi-component lookup on files. 2175 2176@item maxgroups 2177@cindex Mount flags; maxgroups 2178Set the maximum number of groups to allow for this mount. 2179 2180@item nfsv3 2181@cindex Mount flags; nfsv3 2182Use NFS Version 3 for this mount. 2183 2184@item noac 2185@cindex Mount flags; noac 2186Turn off the attribute cache. 2187 2188@item noauto 2189@cindex Mount flags; noauto 2190This option is used by the mount command in @samp{/etc/fstab} or 2191@samp{/etc/vfstab} and means not to mount this file system when mount -a 2192is used. 2193 2194@item nocache 2195@cindex Mount flags; nocache 2196Do not allow data to be cached from a remote server for this 2197mount. 2198 2199@item nocasetrans 2200@cindex Mount flags; nocasetrans 2201Don't do case translation. Useful for CD-ROMS formatted as 2202ISO-9660. 2203 2204@item noconn 2205@cindex Mount flags; noconn 2206Don't make a connection on datagram transports. 2207 2208@item nocto 2209@cindex Mount flags; nocto 2210No close-to-open consistency. 2211 2212@item nodefperm 2213@cindex Mount flags; nodefperm 2214Do not ignore the permission mode bits. Useful for CD-ROMS formatted as 2215ISO-9660. 2216 2217@item nodev 2218@cindex Mount flags; nodev 2219@itemx nodevs 2220@cindex Mount flags; nodevs 2221Don't allow local special devices on this filesystem. 2222 2223@item noexec 2224@cindex Mount flags; noexec 2225Don't allow program execution. 2226 2227@item noint 2228@cindex Mount flags; noint 2229Do not allow keyboard interrupts for this mount 2230 2231@item nojoliet 2232@cindex Mount flags; nojoliet 2233Turn off the Joliet extensions. Useful for CD-ROMS formatted as ISO-9660. 2234 2235@item nolock 2236@cindex Mount flags; nolock 2237Do not use the NFS locking protocol 2238 2239@item nomnttab 2240@cindex Mount flags; nomnttab 2241This option is used internally to tell Amd that a Solaris 8 system using 2242mntfs is in use. 2243 2244@item norrip 2245@cindex Mount flags; norrip 2246Turn off using of the Rock Ridge Interchange Protocol (RRIP) extensions 2247to ISO-9660. 2248 2249@item nosub 2250@cindex Mount flags; nosub 2251Disallow mounts beneath this mount. 2252 2253@item nosuid 2254@cindex Mount flags; nosuid 2255Don't allow set-uid or set-gid executables on this filesystem. 2256 2257@item noversion 2258@cindex Mount flags; noversion 2259Strip the extension @samp{;#} from the version string of files recorded 2260on an ISO-9660 CD-ROM. 2261 2262@item nowin95 2263@cindex Mount Flags; nowin95 2264For PCFS mounts, completely ignore Win95 entries. 2265 2266@item optionstr 2267@cindex Mount flags; optionstr 2268Under Solaris 8, provide the kernel a string of options to parse and 2269show as part of the special in-kernel mount file system. 2270 2271@item overlay 2272@cindex Mount flags; overlay 2273Overlay this mount on top of an existing mount, if any. 2274 2275@item pgthresh=@var{n} 2276@cindex Mount flags; pgthresh 2277Set the paging threshold to @var{n} kilobytes. 2278 2279@item port=@var{n} 2280@cindex Mount flags; port 2281Set the NFS port to @var{n}. 2282 2283@item posix 2284@cindex Mount flags; posix 2285Turn on POSIX static pathconf for mounts. 2286 2287@item private 2288@cindex Mount flags; private 2289Use local locking instead of the NLM protocol, useful for IRIX 6 only. 2290 2291@item proplist 2292@cindex Mount flags; proplist 2293Support property lists (ACLs) for this mount, useful primarily for Tru64 2294UNIX. 2295 2296@item proto=@var{s} 2297@cindex Mount flags; proto 2298Use transport protocol @var{s} for NFS (can be @code{"tcp"} or @code{"udp"}). 2299 2300@item quota 2301@cindex Mount flags; quota 2302Enable quota checking on this mount. 2303 2304@item rdonly 2305@cindex Mount flags; rdonly 2306@itemx ro 2307@cindex Mount flags; ro 2308Mount this filesystem readonly. 2309 2310@item resvport 2311@cindex Mount flags; resvport 2312Use a reserved port (smaller than 1024) for remote NFS mounts. Most 2313systems assume that, but some allow for mounts to occur on non-reserved 2314ports. This causes problems when such a system tries to NFS mount one 2315that requires reserved ports. It is recommended that this option always 2316be on. 2317 2318@item retrans=@i{n} 2319@cindex Mount flags; retrans 2320The number of NFS retransmits made before a user error is generated by a 2321@samp{soft} mounted filesystem, and before a @samp{hard} mounted 2322filesystem reports @samp{NFS server @dfn{yoyo} not responding still 2323trying}. 2324 2325@item retry 2326@cindex Mount flags; retry 2327Set the NFS retry counter. 2328 2329@item rrcaseins 2330@cindex Mount flags; rrcaseins 2331Enable the Rock Ridge Interchange Protocol (RRIP) case insensitive extensions. 2332Useful for CD-ROMS formatted as ISO-9660. 2333 2334@item rrip 2335@cindex Mount flags; rrip 2336Uses the Rock Ridge Interchange Protocol (RRIP) extensions to ISO-9660. 2337 2338@item rsize=@var{n} 2339@cindex Mount flags; rsize 2340The NFS read packet size. You may need to set this if you are using 2341NFS/UDP through a gateway or a slow link. 2342 2343@item rw 2344@cindex Mount flags; rw 2345Allow reads and writes on this filesystem. 2346 2347@item sessionnr=@var{n} 2348@cindex Mount Flags; sessionnr 2349For multisession UDF mounts, use session number @var{n} when mounting. 2350 2351@item shortname 2352@cindex Mount Flags; longname 2353For PCFS mounts, force old DOS short names only. 2354 2355@item soft 2356@cindex Mount flags; soft 2357Give up after @dfn{retrans} retransmissions. 2358 2359@item spongy 2360@cindex Mount flags; spongy 2361Like @samp{soft} for status requests, and @samp{hard} for data transfers. 2362 2363@item suid 2364@cindex Mount flags; suid 2365Allow set-uid programs on this mount. 2366 2367@item symttl 2368@cindex Mount flags; symttl 2369Turn off the symbolic link cache time-to-live. 2370 2371@item sync 2372@cindex Mount flags; sync 2373Perform synchronous filesystem operations on this mount. 2374 2375@item tcp 2376@cindex Mount flags; tcp 2377Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not 2378support TCP/IP mounts. 2379 2380@item timeo=@var{n} 2381@cindex Mount flags; timeo 2382The NFS timeout, in tenth-seconds, before a request is retransmitted. 2383 2384@item user=@var{n} 2385@cindex Mount flags; user 2386For PCFS and UDF mounts, set the owner of the files in the file system 2387to @var{n} (which can either be a user name or a UID number). The 2388default owner is the owner of the directory on which the file system 2389is being mounted. 2390 2391@item vers=@var{n} 2392@cindex Mount flags; vers 2393Use NFS protocol version number @var{n} (can be 2 or 3). 2394 2395@item wsize=@var{n} 2396@cindex Mount flags; wsize 2397The NFS write packet size. You may need to set this if you are using 2398NFS/UDP through a gateway or a slow link. 2399 2400@end table 2401 2402The following options are implemented by @i{Amd}, rather than being 2403passed to the kernel. 2404 2405@table @code 2406 2407@item nounmount 2408@cindex Mount flags; nounmount 2409Configures the mount so that its time-to-live will never expire. This 2410is the default for non-network based filesystem types (such as 2411mounting local disks, floppies, and CD-ROMs). See also the related 2412@i{unmount} option. 2413@c 2414@c Implementation broken: 2415 2416@item ping=@var{n} 2417@cindex Mount flags; ping 2418The interval, in seconds, between keep-alive pings. When four 2419consecutive pings have failed the mount point is marked as hung. This 2420interval defaults to 30 seconds; if the ping interval is set to zero, 2421@i{Amd} will use the default 30-second interval. If the interval is 2422set to -1 (or any other negative value), no pings are sent and the 2423host is assumed to be always up, which can cause unmounts to hang See 2424the @i{softlookup} option for a better alternative. Turning pings off 2425can be useful in NFS-HA (High-Availability) sites where the NFS 2426service rarely goes down. Setting the ping value to a large value can 2427reduce the amount of NFS_NULL chatter on your network considerably, 2428especially in large sites. 2429 2430Note that if you have multiple @i{Amd} entries using the same file 2431server, and each entry sets a different value of N, then each time Amd 2432mounts a new entry, the ping value will be re-evaluated (and updated, 2433turned off, or turned back on as needed). Finally, note that NFS_NULL 2434pings are sent for both UDP and TCP mounts, because even a hung TCP 2435mount can cause user processes to hang. 2436 2437@item public 2438@cindex Mount flags; public 2439Use WebNFS multi-component lookup on the public file handle instead of 2440the mount protocol to obtain NFS file handles, as documented in the 2441WebNFS Client Specification, RFC 2054. This means that @i{Amd} will not 2442attempt to contact the remote portmapper or remote mountd daemon, and 2443will only connect to the well-known NFS port 2049 or the port specified 2444with the @i{port} mount option, thus making it easier to use NFS through 2445a firewall. 2446 2447@item retry=@var{n} 2448@cindex Mount flags; retry=@var{n} 2449The number of times to retry the mount system call. 2450 2451@item softlookup 2452@cindex Mount flags; softlookup 2453Configures @i{Amd}'s behavior with respect to already-mounted shares from 2454NFS fileservers that are unreachable. If softlookup is specified, 2455trying to access such a share will result in an error (EIO, which is 2456changed from the ENOENT 6.0 used to return). If it is not specified, a 2457regular symlink is provided and the access will probably hang 2458in the NFS filesystem. 2459 2460The default behavior depends on whether the mount is 'soft' or 'hard'; 2461softlookup can be used to change this default. This is changed from 6.0 2462which always behaved as if softlookup was specified. 2463 2464@item unmount 2465@cindex Mount flags; unmount 2466Configures the mount so that its time-to-live will indeed expire (and 2467thus may be automatically unmounted). This is also the default for 2468network-based filesystem types (e.g., NFS). This option is useful for 2469removable local media such as CD-ROMs, USB drives, etc. so they can 2470expire when not in use, and get unmounted (such drives can get work 2471out when they keep spinning). See also the related @i{nounmount} 2472option. 2473 2474@item utimeout=@var{n} 2475@cindex Mount flags; utimeout=@var{n} 2476The interval, in seconds, that looked up and mounted map entries are 2477cached. After that period of time, @i{Amd} will attempt to unmount 2478the entries. If, however, the unmount fails (with EBUSY), then 2479@i{Amd} will extend the mount's time-to-live by the @i{utimeout} value 2480before the next unmount attempt is made. In fact the interval is 2481extended before the unmount is attempted, to avoid thrashing. The 2482default value is 120 seconds (two minutes) or as set by the @code{-w} 2483command line option. 2484 2485@item xlatecookie 2486@cindex Mount flags; xlatecookie 2487Translate directory cookies between 32-long and 64-long lengths. 2488 2489@end table 2490 2491@node remopts Option, sublink Option, opts Option, Map Options 2492@comment node-name, next, previous, up 2493@subsubsection remopts Option 2494@cindex Setting system mount options for non-local networks 2495@cindex remopts, mount option 2496@cindex Mount option; remopts 2497 2498This option has the same use as @code{$@{opts@}} but applies only when 2499the remote host is on a non-local network. For example, when using NFS 2500across a gateway it is often necessary to use smaller values for the 2501data read and write sizes. This can simply be done by specifying the 2502small values in @var{remopts}. When a non-local host is accessed, the 2503smaller sizes will automatically be used. 2504 2505@i{Amd} determines whether a host is local by examining the network 2506interface configuration at startup. Any interface changes made after 2507@i{Amd} has been started will not be noticed. The likely effect will 2508be that a host may incorrectly be declared non-local. 2509 2510Unless otherwise set, the value of @code{$@{remopts@}} is the same as 2511the value of @code{$@{opts@}}. 2512 2513@node sublink Option, type Option, remopts Option, Map Options 2514@comment node-name, next, previous, up 2515@subsubsection sublink Option 2516@cindex Setting the sublink option 2517@cindex sublink, mount option 2518@cindex Mount option; sublink 2519 2520The subdirectory within the mounted filesystem to which the reference 2521should point. This can be used to prevent duplicate mounts in cases 2522where multiple directories in the same mounted filesystem are used. 2523 2524@node type Option, , sublink Option, Map Options 2525@comment node-name, next, previous, up 2526@subsubsection type Option 2527@cindex Setting the filesystem type option 2528@cindex type, mount option 2529@cindex Mount option; type 2530 2531The filesystem type to be used. @xref{Filesystem Types}, for a full 2532description of each type.@refill 2533 2534@c ################################################################ 2535@node Amd Command Line Options, Filesystem Types, Mount Maps, Top 2536@comment node-name, next, previous, up 2537@chapter @i{Amd} Command Line Options 2538@cindex Command line options, Amd 2539@cindex Amd command line options 2540@cindex Overriding defaults on the command line 2541 2542Many of @i{Amd}'s parameters can be set from the command line. The 2543command line is also used to specify automount points and maps. 2544 2545The general format of a command line is 2546 2547@example 2548amd [@i{options}] [@{ @i{directory} @i{map-name} [-@i{map-options}] @} ...] 2549@end example 2550 2551For each directory and map-name given or specified in the 2552@file{amd.conf} file, @i{Amd} establishes an automount point. The 2553@dfn{map-options} may be any sequence of options or 2554selectors---@pxref{Location Format}. The @dfn{map-options} apply only 2555to @i{Amd}'s mount point. 2556 2557@samp{type:=toplvl;cache:=mapdefault;fs:=$@{map@}} is the default value for the 2558map options. Default options for a map are read from a special entry in 2559the map whose key is the string @samp{/defaults}. When default options 2560are given they are prepended to any options specified in the mount-map 2561locations as explained in @ref{Map Defaults}. 2562 2563The @dfn{options} are any combination of those listed below. 2564 2565Once the command line has been parsed, the automount points are mounted. 2566The mount points are created if they do not already exist, in which case they 2567will be removed when @i{Amd} exits. 2568Finally, @i{Amd} disassociates itself from its controlling terminal and 2569forks into the background. 2570 2571Note: Even if @i{Amd} has been built with @samp{-DDEBUG} (via 2572@code{configure --enable-debug}), it will still background itself and 2573disassociate itself from the controlling terminal. To use a debugger it 2574is necessary to specify @samp{-D daemon} on the command line. 2575However, even with all of this, mounts and unmounts are performed in the 2576background, and @i{Amd} will always fork before doing them. Therefore, 2577debugging what happens closely during un/mounts is more challenging. 2578 2579@emph{All} of @i{Amd}'s command options (save @code{-F} and @code{-T}) 2580can be specified in the @file{amd.conf} file. @xref{Amd Configuration 2581File}. If @i{Amd} is invoked without any command line options, it will 2582default to using the configuration file @file{/etc/amd.conf}, if one 2583exists. 2584 2585@menu 2586* -a Option:: Automount directory. 2587* -c Option:: Cache timeout interval. 2588* -d Option:: Domain name. 2589* -k Option:: Kernel architecture. 2590* -l Option:: Log file. 2591* -n Option:: Hostname normalization. 2592* -o Option:: Operating system version. 2593* -p Option:: Output process id. 2594* -r Option:: Restart existing mounts. 2595* -t Option:: Kernel RPC timeout. 2596* -v Option:: Version information. 2597* -w Option:: Wait interval after failed unmount. 2598* -x Option:: Log options. 2599* -y Option:: NIS domain. 2600* -A Option:: Operating system Architecture. 2601* -C Option:: Cluster name. 2602* -D Option:: Debug flags. 2603* -F Option:: Amd configuration file. 2604* -H Option:: Show brief help. 2605* -O Option:: Operating system name. 2606* -S Option:: Lock executable pages in memory. 2607* -T Option:: Set tag for configuration file. 2608@end menu 2609 2610@c ---------------------------------------------------------------- 2611@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options 2612@comment node-name, next, previous, up 2613@section @code{-a} @var{directory} 2614@cindex Automount directory 2615@cindex Setting the default mount directory 2616 2617Specifies the default mount directory. This option changes the variable 2618@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, 2619some sites prefer @file{/amd} or @file{/n}. 2620 2621@example 2622amd -a /amd ... 2623@end example 2624 2625@c ---------------------------------------------------------------- 2626@node -c Option, -d Option, -a Option, Amd Command Line Options 2627@comment node-name, next, previous, up 2628@section @code{-c} @var{cache-interval} 2629@cindex Cache interval 2630@cindex Interval before a filesystem times out 2631@cindex Setting the interval before a filesystem times out 2632@cindex Changing the interval before a filesystem times out 2633 2634Selects the period, in seconds, for which a name is cached by @i{Amd}. 2635If no reference is made to the volume in this period, @i{Amd} discards 2636the volume name to filesystem mapping. 2637 2638Once the last reference to a filesystem has been removed, @i{Amd} 2639attempts to unmount the filesystem. If the unmount fails the interval 2640is extended by a further period as specified by the @samp{-w} command 2641line option or by the @samp{utimeout} mount option. 2642 2643The default @dfn{cache-interval} is 300 seconds (five minutes). 2644 2645@c ---------------------------------------------------------------- 2646@node -d Option, -k Option, -c Option, Amd Command Line Options 2647@comment node-name, next, previous, up 2648@section @code{-d} @var{domain} 2649@cindex Domain name 2650@cindex Setting the local domain name 2651@cindex Overriding the local domain name 2652 2653Specifies the host's domain. This sets the internal variable 2654@code{$@{domain@}} and affects the @code{$@{hostd@}} variable. 2655 2656If this option is not specified and the hostname already contains the 2657local domain then that is used, otherwise the default value of 2658@code{$@{domain@}} is @samp{unknown.domain}. 2659 2660For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could 2661be started as follows: 2662 2663@example 2664amd -d doc.ic.ac.uk ... 2665@end example 2666 2667@c ---------------------------------------------------------------- 2668@node -k Option, -l Option, -d Option, Amd Command Line Options 2669@comment node-name, next, previous, up 2670@section @code{-k} @var{kernel-architecture} 2671@cindex Setting the Kernel architecture 2672 2673Specifies the kernel architecture of the system. This is usually the 2674output of @samp{uname -m} (the ``machine'' value gotten from 2675@b{uname}(2)). If the @b{uname}(2) system call is not available, the 2676value of @code{$@{karch@}} defaults to that of @code{$@{arch@}}. 2677 2678The only effect of this option is to set the variable @code{$@{karch@}}. 2679 2680This option would be used as follows: 2681 2682@example 2683amd -k `arch -k` ... 2684@end example 2685 2686@c ---------------------------------------------------------------- 2687@node -l Option, -n Option, -k Option, Amd Command Line Options 2688@comment node-name, next, previous, up 2689@section @code{-l} @var{log-option} 2690@cindex Log filename 2691@cindex Setting the log file 2692@cindex Using syslog to log errors 2693@cindex syslog 2694 2695Selects the form of logging to be made. Several special @dfn{log-options} 2696are recognized. 2697 2698@enumerate 2699@item 2700If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the 2701@b{syslog}(3) mechanism. If your system supports syslog facilities, then 2702the default facility used is @samp{LOG_DAEMON}. 2703 2704@item 2705@cindex syslog facility; specifying an alternate 2706When using syslog, if you wish to change the facility, append its name 2707to the log option name, delimited by a single colon. For example, if 2708@dfn{log-options} is the string @samp{syslog:local7} then @b{Amd} will 2709log messages via @b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If 2710the facility name specified is not recognized, @i{Amd} will default to 2711@samp{LOG_DAEMON}. Note: while you can use any syslog facility 2712available on your system, it is generally a bad idea to use those 2713reserved for other services such as @samp{kern}, @samp{lpr}, 2714@samp{cron}, etc. 2715 2716@item 2717If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use 2718standard error, which is also the default target for log messages. To 2719implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} 2720driver. 2721@end enumerate 2722 2723Any other string is taken as a filename to use for logging. Log 2724messages are appended to the file if it already exists, otherwise a new 2725file is created. The file is opened once and then held open, rather 2726than being re-opened for each message. 2727 2728Normally, when long-running daemons hold an open file descriptor on a 2729log file, it is impossible to ``rotate'' the log file and compress older 2730logs on a daily basis. The daemon needs to be told to discard (via 2731@b{close}(2)) its file handle, and re-open the log file. This is done 2732using @code{amq -l} @i{log-option}. @xref{Amq -l option}. 2733 2734If the @samp{syslog} option is specified but the system does not support 2735syslog or if the named file cannot be opened or created, @i{Amd} will 2736use standard error. Error messages generated before @i{Amd} has 2737finished parsing the command line are printed on standard error. 2738 2739Since @i{Amd} tends to generate a lot of logging information (especially 2740if debugging was turned on), and due to it being an important program 2741running on the system, it is usually best to log to a separate disk 2742file. In that case @i{Amd} would be started as follows: 2743 2744@example 2745amd -l /var/log/amd ... 2746@end example 2747 2748@c ---------------------------------------------------------------- 2749@node -n Option, -o Option, -l Option, Amd Command Line Options 2750@comment node-name, next, previous, up 2751@section @code{-n} 2752@cindex Hostname normalization 2753@cindex Aliased hostnames 2754@cindex Resolving aliased hostnames 2755@cindex Normalizing hostnames 2756 2757Normalizes the remote hostname before using it. Normalization is done 2758by replacing the value of @code{$@{rhost@}} with the (generally fully 2759qualified) primary name returned by a hostname lookup. 2760 2761This option should be used if several names are used to refer to a 2762single host in a mount map. 2763 2764@c ---------------------------------------------------------------- 2765@node -o Option, -p Option, -n Option, Amd Command Line Options 2766@comment node-name, next, previous, up 2767@section @code{-o} @var{op-sys-ver} 2768@cindex Operating System version 2769@cindex Setting the Operating System version 2770 2771Overrides the compiled-in version number of the operating system, with 2772@var{op-sys-ver}. Useful when the built-in version is not desired for 2773backward compatibility reasons. For example, if the built-in version is 2774@samp{2.5.1}, you can override it to @samp{5.5.1}, and use older maps 2775that were written with the latter in mind. 2776 2777@c ---------------------------------------------------------------- 2778@node -p Option, -r Option, -o Option, Amd Command Line Options 2779@comment node-name, next, previous, up 2780@section @code{-p} 2781@cindex Process id 2782@cindex Displaying the process id 2783@cindex process id of Amd daemon 2784@cindex pid file, creating with -p option 2785@cindex Creating a pid file 2786 2787Causes @i{Amd}'s process id to be printed on standard output. 2788This can be redirected to a suitable file for use with kill: 2789 2790@example 2791amd -p > /var/run/amd.pid ... 2792@end example 2793 2794This option only has an affect if @i{Amd} is running in daemon mode. 2795If @i{Amd} is started with the @code{-D daemon} debug flag, this 2796option is ignored. 2797 2798@c ---------------------------------------------------------------- 2799@node -r Option, -t Option, -p Option, Amd Command Line Options 2800@comment node-name, next, previous, up 2801@section @code{-r} 2802@cindex Restarting existing mounts 2803@cindex Picking up existing mounts 2804 2805Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). 2806@c @dfn{This option will be made the default in the next release.} 2807 2808@c ---------------------------------------------------------------- 2809@node -t Option, -v Option, -r Option, Amd Command Line Options 2810@comment node-name, next, previous, up 2811@section @code{-t} @var{timeout.retransmit} 2812@cindex Setting Amd's RPC parameters 2813 2814Specifies the RPC @dfn{timeout} interval and the @dfn{retransmit} 2815counter used by the kernel to communicate to @i{Amd}. These are used to 2816set the @samp{timeo} and @samp{retrans} mount options, respectively. 2817The default timeout is 0.8 seconds, and the default number of 2818retransmissions is 11. 2819 2820@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 2821retries. The values of these parameters change the overall retry 2822interval. Too long an interval gives poor interactive response; too 2823short an interval causes excessive retries. 2824 2825@c ---------------------------------------------------------------- 2826@node -v Option, -w Option, -t Option, Amd Command Line Options 2827@comment node-name, next, previous, up 2828@section @code{-v} 2829@cindex Version information 2830@cindex Discovering version information 2831@cindex How to discover your version of Amd 2832 2833Print version information on standard error and then exit. The output 2834is of the form: 2835 2836@example 2837Copyright (c) 1997-1999 Erez Zadok 2838Copyright (c) 1990 Jan-Simon Pendry 2839Copyright (c) 1990 Imperial College of Science, Technology & Medicine 2840Copyright (c) 1990 The Regents of the University of California. 2841am-utils version 6.0a15 (build 61). 2842Built by ezk@@example.com on date Wed Oct 22 15:21:03 EDT 1997. 2843cpu=sparc (big-endian), arch=sun4, karch=sun4u. 2844full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun. 2845Map support for: root, passwd, union, nisplus, nis, ndbm, file, error. 2846AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit, 2847 ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error. 2848FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, udf, ufs. 2849Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13). 2850Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14). 2851Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16). 2852@end example 2853 2854The information includes the version number, number of times @i{Amd} was 2855compiled on the local system, release date and name of the release. 2856Following come the cpu type, byte ordering, and the architecture and 2857kernel architecture as @code{$@{arch@}} and @code{$@{karch@}}, 2858respectively. The next line lists the operating system full name, short 2859name, version, and vendor. These four values correspond to the 2860variables @code{$@{full_os@}}, @code{$@{os@}}, @code{$@{osver@}}, and 2861@code{$@{vendor@}}, respectively. @xref{Supported Platforms}. 2862 2863Then come a list of map types supported, filesystems internally 2864supported by @i{Amd} (AMFS), and generic filesystems available (FS). 2865Finally all known networks (if any) of this host are listed by name 2866and number. They are available via the variables 2867@code{$@{wire@}} or @code{$@{network@}}, and 2868@code{$@{netnumber@}} (@pxref{Selectors}) or the @samp{in_network} 2869selector function (@pxref{in_network Selector Function}). 2870 2871@c ---------------------------------------------------------------- 2872@node -w Option, -x Option, -v Option, Amd Command Line Options 2873@comment node-name, next, previous, up 2874@section @code{-w} @var{wait-timeout} 2875@cindex Setting the interval between unmount attempts 2876@cindex unmount attempt backoff interval 2877 2878Selects the interval in seconds between unmount attempts after the 2879initial time-to-live has expired. 2880 2881This defaults to 120 seconds (two minutes). 2882 2883@c ---------------------------------------------------------------- 2884@node -x Option, -y Option, -w Option, Amd Command Line Options 2885@comment node-name, next, previous, up 2886@section @code{-x} @var{opts} 2887@cindex Log message selection 2888@cindex Selecting specific log messages 2889@cindex How to select log messages 2890@cindex syslog priorities 2891 2892Specifies the type and verbosity of log messages. @dfn{opts} is 2893a comma separated list selected from the following options: 2894 2895@table @code 2896@item fatal 2897Fatal errors (cannot be turned off) 2898@item error 2899Non-fatal errors (cannot be turned off) 2900@item user 2901Non-fatal user errors 2902@item warn 2903Recoverable errors 2904@item warning 2905Alias for @code{warn} 2906@item info 2907Information messages 2908@item map 2909Mount map usage 2910@item stats 2911Additional statistics 2912@item all 2913All of the above 2914@item defaults 2915An alias for "fatal,error,user,warning,info". 2916@end table 2917 2918Initially a set of default logging flags is enabled. This is as if 2919@samp{-x defaults} 2920or 2921@samp{-x fatal,error,user,warning,info} 2922had been selected. The command line is 2923parsed and logging is controlled by the @code{-x} option. The very first 2924set of logging flags is saved and can not be subsequently disabled using 2925@i{Amq}. This default set of options is useful for general production 2926use.@refill 2927 2928The @samp{info} messages include details of what is mounted and 2929unmounted and when filesystems have timed out. If you want to have the 2930default set of messages without the @samp{info} messages then you simply 2931need @samp{-x noinfo}. The messages given by @samp{user} relate to 2932errors in the mount maps, so these are useful when new maps are 2933installed. The following table lists the syslog priorities used for each 2934of the message types.@refill 2935 2936@table @code 2937@item fatal 2938@samp{LOG_CRIT} 2939@item error 2940@samp{LOG_ERR} 2941@item user 2942@samp{LOG_WARNING} 2943@item warning 2944@samp{LOG_WARNING} 2945@item info 2946@samp{LOG_INFO} 2947@item debug 2948@samp{LOG_DEBUG} 2949@item map 2950@samp{LOG_DEBUG} 2951@item stats 2952@samp{LOG_INFO} 2953@end table 2954 2955The options can be prefixed by the string @samp{no} to indicate 2956that this option should be turned off. For example, to obtain all 2957but @samp{info} messages the option @samp{-x all,noinfo} would be used. 2958 2959If @i{Amd} was built with debugging enabled the @code{debug} option is 2960automatically enabled regardless of the command line options. 2961 2962@c ---------------------------------------------------------------- 2963@node -y Option, -A Option, -x Option, Amd Command Line Options 2964@comment node-name, next, previous, up 2965@section @code{-y} @var{NIS-domain} 2966@cindex NIS (YP) domain name 2967@cindex Overriding the NIS (YP) domain name 2968@cindex Setting the NIS (YP) domain name 2969@cindex YP domain name 2970 2971Selects an alternate NIS domain. This is useful for debugging and 2972cross-domain shared mounting. If this flag is specified, @i{Amd} 2973immediately attempts to bind to a server for this domain. 2974@c @i{Amd} refers to NIS maps when it starts, unless the @code{-m} option 2975@c is specified, and whenever required in a mount map. 2976 2977@c ---------------------------------------------------------------- 2978@node -A Option, -C Option, -y Option, Amd Command Line Options 2979@comment node-name, next, previous, up 2980@section @code{-A} @var{architecture} 2981@cindex Setting the operating system architecture 2982 2983Specifies the OS architecture of the system. 2984The only effect of this option is to set the variable @code{$@{arch@}}. 2985 2986This option would be used as follows: 2987 2988@example 2989amd -A i386 ... 2990@end example 2991 2992@c ---------------------------------------------------------------- 2993@node -C Option, -D Option, -A Option, Amd Command Line Options 2994@comment node-name, next, previous, up 2995@section @code{-C} @var{cluster-name} 2996@cindex Cluster names 2997@cindex Setting the cluster name 2998 2999Specifies the name of the cluster of which the local machine is a member. 3000The only effect is to set the variable @code{$@{cluster@}}. 3001The @dfn{cluster-name} is will usually obtained by running another command which uses 3002a database to map the local hostname into a cluster name. 3003@code{$@{cluster@}} can then be used as a selector to restrict mounting of 3004replicated data. 3005If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. 3006This would be used as follows: 3007 3008@example 3009amd -C `clustername` ... 3010@end example 3011 3012@c ---------------------------------------------------------------- 3013@node -D Option, -F Option, -C Option, Amd Command Line Options 3014@comment node-name, next, previous, up 3015@section @code{-D} @var{opts} 3016@cindex Debug options 3017@cindex Setting debug flags 3018 3019Controls the verbosity and coverage of the debugging trace; @dfn{opts} 3020is a comma separated list of debugging options. The @code{-D} option is 3021only available if @i{Amd} was compiled with @samp{-DDEBUG}, or 3022configured with @code{configure --enable-debug}. The memory debugging 3023facilities (@samp{mem}) are only available if @i{Amd} was compiled with 3024@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}), or configured with 3025@code{configure --enable-debug=mem}. 3026 3027The most common options to use are @samp{-D trace} and @samp{-D test} 3028(which turns on all the useful debug options). As usual, every option 3029can be prefixed with @samp{no} to turn it off. 3030 3031@table @code 3032@item all 3033all options (excluding hrtime and mtab) 3034@item defaults 3035``sensible'' default options (all--excluding hrtime, mtab, and xdrtrace) 3036@item test 3037full debug options plus mtab,nodaemon,nofork,noamq 3038@item amq 3039register @i{Amd} with the RPC portmapper, for @i{Amq} 3040@item daemon 3041enter daemon mode 3042@item fork 3043fork child worker (hlfsd only) 3044@item full 3045program trace 3046@item hrtime 3047print high resolution time stamps (only if @b{syslog}(3) is not used) 3048@item info 3049@cindex debugging hesiod resolver service 3050@cindex Hesiod; turning on RES_DEBUG 3051info service specific debugging (hesiod, nis, etc.) In the case of 3052hesiod maps, turns on the hesiod RES_DEBUG internal debugging option. 3053@item mem 3054trace memory allocations. Needs to be explicitly enabled at compile 3055time with --enable-debug=mem. 3056@item mtab 3057use local mount-table file (defaults to @file{/tmp/mtab}, @pxref{debug_mtab_file Parameter}) 3058@item readdir 3059show readdir progress 3060@item str 3061debug string munging 3062@item trace 3063trace RPC protocol and NFS mount arguments 3064@item xdrtrace 3065trace XDR routines 3066@end table 3067 3068You may also refer to the program source for a more detailed explanation 3069of the available options. 3070 3071@c ---------------------------------------------------------------- 3072@node -F Option, -H Option, -D Option, Amd Command Line Options 3073@comment node-name, next, previous, up 3074@section @code{-F} @var{conf-file} 3075@cindex Amd configuration file; specifying name 3076@cindex Amd configuration file 3077@cindex amd.conf file 3078 3079Specify an @i{Amd} configuration file @var{conf-file} to use. For a 3080description of the format and syntax, @pxref{Amd Configuration File}. 3081This configuration file is used to specify any options in lieu of typing 3082many of them on the command line. The @file{amd.conf} file includes 3083directives for every command line option @i{Amd} has, and many more that 3084are only available via the configuration file facility. The 3085configuration file specified by this option is processed after all other 3086options had been processed, regardless of the actual location of this 3087option on the command line. 3088 3089@c ---------------------------------------------------------------- 3090@node -H Option, -O Option, -F Option, Amd Command Line Options 3091@comment node-name, next, previous, up 3092@section @code{-H} 3093@cindex Displaying brief help 3094@cindex Help; showing from Amd 3095 3096Print a brief help and usage string. 3097 3098@c ---------------------------------------------------------------- 3099@node -O Option, -S Option, -H Option, Amd Command Line Options 3100@comment node-name, next, previous, up 3101@section @code{-O} @var{op-sys-name} 3102@cindex Operating System name 3103@cindex Setting the Operating System name 3104 3105Overrides the compiled-in name of the operating system, with 3106@var{op-sys-name}. Useful when the built-in name is not desired for 3107backward compatibility reasons. For example, if the build in name is 3108@samp{sunos5}, you can override it to the old name @samp{sos5}, and use 3109older maps which were written with the latter in mind. 3110 3111@c ---------------------------------------------------------------- 3112@node -S Option, -T Option, -O Option, Amd Command Line Options 3113@comment node-name, next, previous, up 3114@section @code{-S} 3115@cindex plock; using 3116@cindex mlockall; using 3117@cindex locking executable pages in memory 3118 3119Do @emph{not} lock the running executable pages of @i{Amd} into memory. 3120To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 3121or @b{mlockall}(2) 3122call lock the @i{Amd} process into memory. This way there is less 3123chance the operating system will schedule, page out, and swap the 3124@i{Amd} process as needed. This tends to improve @i{Amd}'s performance, 3125at the cost of reserving the memory used by the @i{Amd} process (making 3126it unavailable for other processes). If this behavior is not desired, 3127use the @code{-S} option. 3128 3129@c ---------------------------------------------------------------- 3130@node -T Option, , -S Option, Amd Command Line Options 3131@comment node-name, next, previous, up 3132@section @code{-T} @var{tag} 3133@cindex Tags for Amd configuration file 3134@cindex Configuration file; tags 3135 3136Specify a tag to use with @file{amd.conf}. All map entries tagged with 3137@var{tag} will be processed. Map entries that are not tagged are always 3138processed. Map entries that are tagged with a tag other than @var{tag} 3139will not be processed. 3140 3141@c ################################################################ 3142@node Filesystem Types, Amd Configuration File, Amd Command Line Options, Top 3143@comment node-name, next, previous, up 3144@chapter Filesystem Types 3145@cindex Filesystem types 3146@cindex Mount types 3147@cindex Types of filesystem 3148 3149To mount a volume, @i{Amd} must be told the type of filesystem to be 3150used. Each filesystem type typically requires additional information 3151such as the fileserver name for NFS. 3152 3153From the point of view of @i{Amd}, a @dfn{filesystem} is anything that 3154can resolve an incoming name lookup. An important feature is support 3155for multiple filesystem types. Some of these filesystems are 3156implemented in the local kernel and some on remote fileservers, whilst 3157the others are implemented internally by @i{Amd}.@refill 3158 3159The two common filesystem types are UFS and NFS. Four other user 3160accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and 3161@samp{direct}) are also implemented internally by @i{Amd} and these are 3162described below. There are two additional filesystem types internal to 3163@i{Amd} which are not directly accessible to the user (@samp{inherit} 3164and @samp{error}). Their use is described since they may still have an 3165effect visible to the user.@refill 3166 3167@menu 3168* Network Filesystem:: A single NFS filesystem. 3169* Network Host Filesystem:: NFS mount a host's entire export tree. 3170* Network Filesystem Group:: An atomic group of NFS filesystems. 3171* Unix Filesystem:: Native disk filesystem. 3172* Caching Filesystem:: Caching from remote server filesystem. 3173* CD-ROM Filesystem:: ISO9660 CD ROM. 3174* UDF Filesystem:: Universal Disk Format filesystem. 3175* Loopback Filesystem:: Local loopback-mount filesystem. 3176* Memory/RAM Filesystem:: A memory or RAM-based filesystem. 3177* Null Filesystem:: 4.4BSD's loopback-mount filesystem. 3178* Floppy Filesystem:: MS-DOS Floppy filesystem. 3179* Translucent Filesystem:: The directory merging filesystem. 3180* Shared Memory+Swap Filesystem:: Sun's tmpfs filesystem. 3181* User ID Mapping Filesystem:: 4.4BSD's umapfs filesystem. 3182* Program Filesystem:: Generic Program mounts. 3183* Symbolic Link Filesystem:: Local link. 3184* Symbolic Link Filesystem II:: Local link referencing existing filesystem. 3185* NFS-Link Filesystem:: Link if path exists, NFS otherwise. 3186* Automount Filesystem:: 3187* Direct Automount Filesystem:: 3188* Union Filesystem:: 3189* Error Filesystem:: 3190* Top-level Filesystem:: 3191* Root Filesystem:: 3192* Inheritance Filesystem:: 3193@end menu 3194 3195@c ---------------------------------------------------------------- 3196@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types 3197@comment node-name, next, previous, up 3198@section Network Filesystem (@samp{nfs}) 3199@cindex NFS 3200@cindex Mounting an NFS filesystem 3201@cindex How to mount and NFS filesystem 3202@cindex nfs, filesystem type 3203@cindex Filesystem type; nfs 3204 3205The @dfn{nfs} (@samp{type:=nfs}) filesystem type provides access to Sun's NFS. 3206 3207@noindent 3208The following options must be specified: 3209 3210@table @code 3211@cindex rhost, mount option 3212@cindex Mount option; rhost 3213@item rhost 3214the remote fileserver. This must be an entry in the hosts database. IP 3215addresses are not accepted. The default value is taken 3216from the local host name (@code{$@{host@}}) if no other value is 3217specified. 3218 3219@cindex rfs, mount option 3220@cindex Mount option; rfs 3221@item rfs 3222the remote filesystem. 3223If no value is specified for this option, an internal default of 3224@code{$@{path@}} is used. 3225@end table 3226 3227NFS mounts require a two stage process. First, the @dfn{file handle} of 3228the remote file system must be obtained from the server. Then a mount 3229system call must be done on the local system. @i{Amd} keeps a cache 3230of file handles for remote file systems. The cache entries have a 3231lifetime of a few minutes. 3232 3233If a required file handle is not in the cache, @i{Amd} sends a request 3234to the remote server to obtain it. 3235@c @i{Amd} @dfn{does not} wait for 3236@c a response; it notes that one of the locations needs retrying, but 3237@c continues with any remaining locations. When the file handle becomes 3238@c available, and assuming none of the other locations was successfully 3239@c mounted, @i{Amd} will retry the mount. This mechanism allows several 3240@c NFS filesystems to be mounted in parallel. 3241@c @footnote{The mechanism 3242@c is general, however NFS is the only filesystem 3243@c for which the required hooks have been written.} 3244@c The first one which responds with a valid file handle will be used. 3245 3246Historically, this documentation has maintained that @i{Amd} will try 3247all the locations in parallel and use the first one which responds 3248with a valid file handle. This has not been the case for quite some 3249time, however. Instead, @i{Amd} will go through each location, one by 3250one, and will only skip to the next one if the previous one either 3251fails or times out. 3252 3253@noindent 3254An NFS entry might be: 3255 3256@example 3257jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp 3258@end example 3259 3260The mount system call and any unmount attempts are always done 3261in a new task to avoid the possibility of blocking @i{Amd}. 3262 3263@c ---------------------------------------------------------------- 3264@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types 3265@comment node-name, next, previous, up 3266@section Network Host Filesystem (@samp{host}) 3267@cindex Network host filesystem 3268@cindex Mounting entire export trees 3269@cindex How to mount all NFS exported filesystems 3270@cindex host, filesystem type 3271@cindex Filesystem type; host 3272 3273@c NOTE: the current implementation of the @dfn{host} filesystem type 3274@c sometimes fails to maintain a consistent view of the remote mount tree. 3275@c This happens when the mount times out and only some of the remote mounts 3276@c are successfully unmounted. To prevent this from occurring, use the 3277@c @samp{nounmount} mount option. 3278 3279The @dfn{host} (@samp{type:=host}) filesystem allows access to the entire export tree of an 3280NFS server. The implementation is layered above the @samp{nfs} 3281implementation so keep-alives work in the same way. The only option 3282which needs to be specified is @samp{rhost} which is the name of the 3283fileserver to mount. 3284 3285The @samp{host} filesystem type works by querying the mount daemon on 3286the given fileserver to obtain its export list. @i{Amd} then obtains 3287filehandles for each of the exported filesystems. Any errors at this 3288stage cause that particular filesystem to be ignored. Finally each 3289filesystem is mounted. Again, errors are logged but ignored. One 3290common reason for mounts to fail is that the mount point does not exist. 3291Although @i{Amd} attempts to automatically create the mount point, it 3292may be on a remote filesystem to which @i{Amd} does not have write 3293permission. 3294 3295When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} 3296remounts any filesystems which had successfully been unmounted. To do 3297this @i{Amd} queries the mount daemon again and obtains a fresh copy of 3298the export list. @i{Amd} then tries to mount any exported filesystems 3299which are not currently mounted. 3300 3301Sun's automounter provides a special @samp{-hosts} map. To achieve the 3302same effect with @i{Amd} requires two steps. First a mount map must 3303be created as follows: 3304 3305@example 3306* type:=host;rhost:=$@{key@};fs:=$@{autodir@}/$@{rhost@}/root 3307@end example 3308 3309@noindent 3310and then start @i{Amd} with the following command 3311 3312@example 3313amd /net net.map 3314@end example 3315 3316@noindent 3317where @samp{net.map} is the name of map described above. Note that the 3318value of @code{$@{fs@}} is overridden in the map. This is done to avoid 3319a clash between the mount tree and any other filesystem already mounted 3320from the same fileserver. 3321 3322If different mount options are needed for different hosts then 3323additional entries can be added to the map, for example 3324 3325@example 3326host2 opts:=ro,nosuid,soft 3327@end example 3328 3329@noindent 3330would soft mount @samp{host2} read-only. 3331 3332@c ---------------------------------------------------------------- 3333@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types 3334@comment node-name, next, previous, up 3335@section Network Filesystem Group (@samp{nfsx}) 3336@cindex Network filesystem group 3337@cindex Atomic NFS mounts 3338@cindex Mounting an atomic group of NFS filesystems 3339@cindex How to mount an atomic group of NFS filesystems 3340@cindex nfsx, filesystem type 3341@cindex Filesystem type; nfsx 3342 3343The @dfn{nfsx} (@samp{type:=nfsx}) filesystem allows a group of filesystems to be mounted 3344from a single NFS server. The implementation is layered above the 3345@samp{nfs} implementation so keep-alives work in the same way. 3346 3347@emph{WARNING}: @samp{nfsx} is meant to be a ``last resort'' kind of 3348solution. It is racy and poorly supported. The authors @emph{highly} 3349recommend that other solutions be considered before relying on it. 3350 3351The options are the same as for the @samp{nfs} filesystem with one 3352difference for @samp{rfs}, as explained below. 3353 3354@noindent 3355The following options should be specified: 3356 3357@table @code 3358@item rhost 3359the remote fileserver. The default value is taken from the local 3360host name (@code{$@{host@}}) if no other value is specified. 3361 3362@item rfs 3363is a list of filesystems to mount, and must be specified. 3364The list is in the form of a comma separated strings. 3365@end table 3366 3367@noindent 3368For example: 3369 3370@example 3371pub type:=nfsx;rhost:=gould;\ 3372 rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root 3373@end example 3374 3375The first string defines the root of the tree, and is applied as a 3376prefix to the remaining members of the list which define the individual 3377filesystems. The first string is @emph{not} used as a filesystem name. 3378A serial operation is used to determine the local mount points to 3379ensure a consistent layout of a tree of mounts. 3380 3381Here, the @emph{three} filesystems, @samp{/public}, 3382@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill 3383 3384A local mount point, @code{$@{fs@}}, @emph{must} be specified. The 3385default local mount point will not work correctly in the general case. 3386A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill 3387 3388@c ---------------------------------------------------------------- 3389@node Unix Filesystem, Caching Filesystem, Network Filesystem Group, Filesystem Types 3390@comment node-name, next, previous, up 3391@section Unix Filesystem (@samp{ufs}, @samp{xfs}, or @samp{efs}) 3392@cindex Unix filesystem 3393@cindex UFS 3394@cindex XFS 3395@cindex EFS 3396@cindex Mounting a UFS filesystem 3397@cindex Mounting a local disk 3398@cindex How to mount a UFS filesystems 3399@cindex How to mount a local disk 3400@cindex Disk filesystems 3401@cindex ufs, filesystem type 3402@cindex Filesystem type; ufs 3403@cindex xfs, filesystem type 3404@cindex Filesystem type; xfs 3405@cindex efs, filesystem type 3406@cindex Filesystem type; efs 3407 3408The @dfn{ufs} (@samp{type:=ufs}) filesystem type provides access to the system's standard 3409disk filesystem---usually a derivative of the Berkeley Fast Filesystem. 3410 3411@noindent 3412The following option must be specified: 3413 3414@table @code 3415@cindex dev, mount option 3416@cindex Mount option; dev 3417@item dev 3418the block special device to be mounted. 3419@end table 3420 3421A UFS entry might be: 3422 3423@example 3424jsp host==charm;type:=ufs;dev:=/dev/sd0d;sublink:=jsp 3425@end example 3426 3427UFS is the default Unix disk-based file system, which Am-utils picks up 3428during the autoconfiguration phase. Some systems have more than one 3429type, such as IRIX, that comes with EFS (Extent File System) and XFS 3430(Extended File System). In those cases, you may explicitly set the file 3431system type, by using entries such: 3432 3433@example 3434ez1 type:=efs;dev:=/dev/xd0a 3435ez2 type:=xfs;dev:=/dev/sd3c 3436@end example 3437 3438The UFS/XFS/EFS filesystems are never timed out by default, i.e. they 3439will never be unmounted by @i{Amd}. If automatic unmounting is 3440desired, the ``unmount'' option should be added to the mount options 3441for the entry. 3442 3443@c ---------------------------------------------------------------- 3444@node Caching Filesystem, CD-ROM Filesystem, Unix Filesystem, Filesystem Types 3445@comment node-name, next, previous, up 3446@section Caching Filesystem (@samp{cachefs}) 3447@cindex Caching Filesystem 3448@cindex cachefs, filesystem type 3449@cindex Filesystem type; cachefs 3450 3451The @dfn{cachefs} (@samp{type:=cachefs}) filesystem caches files from 3452one location onto another, presumably providing faster access. It is 3453particularly useful to cache from a larger and remote (slower) NFS 3454partition to a smaller and local (faster) UFS directory. 3455 3456@noindent 3457The following options must be specified: 3458 3459@table @code 3460@cindex cachedir, mount option 3461@cindex Mount option; cachedir 3462@item cachedir 3463the directory where the cache is stored. 3464@item rfs 3465the path name to the ``back file system'' to be cached from. 3466@item fs 3467the ``front file system'' mount point to the cached files, where @i{Amd} 3468will set a symbolic link pointing to. 3469@end table 3470 3471A CacheFS entry for, say, the @file{/import} @i{Amd} mount point, might 3472be: 3473 3474@example 3475copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt 3476@end example 3477 3478Access to the pathname @file{/import/copt} will follow a symbolic link 3479to @file{/n/import/copt}. The latter is the mount point for a caching 3480file system, that caches from @file{/import/opt} to @file{/cache}. 3481 3482The cachefs filesystem is never timed out by default, i.e. it will 3483never be unmounted by @i{Amd}. If automatic unmounting is desired, the 3484``unmount'' option should be added to the mount options for the entry. 3485 3486@b{Caveats}: 3487@enumerate 3488@item This file system is currently only implemented for Solaris 2.x! 3489@item Before being used for the first time, the cache directory @i{must} be 3490initialized with @samp{cfsadmin -c @var{cachedir}}. See the manual page for 3491@b{cfsadmin}(1M) for more information. 3492@item The ``back file system'' mounted must be a complete file system, not 3493a subdirectory thereof; otherwise you will get an error ``Invalid Argument''. 3494@item If @i{Amd} aborts abnormally, the state of the cache may be 3495inconsistent, requiring running the command @file{fsck -F cachefs 3496@var{cachedir}}. Otherwise you will get the error ``No Space Left on Device''. 3497@end enumerate 3498 3499@c ---------------------------------------------------------------- 3500@node CD-ROM Filesystem, UDF Filesystem, Caching Filesystem, Filesystem Types 3501@comment node-name, next, previous, up 3502@section CD-ROM Filesystem (@samp{cdfs}) 3503@cindex CD-ROM Filesystem 3504@cindex cdfs, filesystem type 3505@cindex Filesystem type; cdfs 3506 3507The @dfn{cdfs} (@samp{type:=cdfs}) filesystem mounts a CD-ROM with an 3508ISO9660 format filesystem on it. 3509 3510@noindent 3511The following option must be specified: 3512 3513@table @code 3514@cindex dev, mount option 3515@cindex Mount option; dev 3516@item dev 3517the block special device to be mounted. 3518@end table 3519 3520Some operating systems will fail to mount read-only CDs unless the 3521@samp{ro} option is specified. A cdfs entry might be: 3522 3523@example 3524cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ 3525 os==sunos5;addopts:=ro;type:=cdfs;dev:=/dev/dsk/c0t6d0s2 3526@end example 3527 3528@c ---------------------------------------------------------------- 3529@node UDF Filesystem, Loopback Filesystem, CD-ROM Filesystem, Filesystem Types 3530@comment node-name, next, previous, up 3531@section CD-ROM Filesystem (@samp{udf}) 3532@cindex CD-ROM Filesystem 3533@cindex udf, filesystem type 3534@cindex Filesystem type; udf 3535 3536The @dfn{udf} (@samp{type:=udf}) filesystem mounts media with a 3537Universal Disk Format (UDF) filesystem on it, e.g., a video DVD. 3538 3539@noindent 3540The following option must be specified: 3541 3542@table @code 3543@cindex dev, mount option 3544@cindex Mount option; dev 3545@item dev 3546the block special device to be mounted. 3547@end table 3548 3549Some operating systems will fail to mount read-only media unless the 3550@samp{ro} option is specified. A udf entry might be: 3551 3552@example 3553udf os==sunos4;type:=udf;dev:=/dev/sr0 \ 3554 os==sunos5;addopts:=ro;type:=udf;dev:=/dev/dsk/c0t6d0s2 3555@end example 3556 3557@c ---------------------------------------------------------------- 3558@node Loopback Filesystem, Memory/RAM Filesystem, UDF Filesystem, Filesystem Types 3559@comment node-name, next, previous, up 3560@section Loopback Filesystem (@samp{lofs}) 3561@cindex Loopback Filesystem 3562@cindex lofs, filesystem type 3563@cindex Filesystem type; lofs 3564 3565The @dfn{lofs} (@samp{type:=lofs}) filesystem is also called the 3566loopback filesystem. It mounts a local directory on another, thus 3567providing mount-time binding to another location (unlike symbolic 3568links). 3569 3570The loopback filesystem is particularly useful within the context of a 3571chroot-ed directory (via @b{chroot}(2)), to provide access to 3572directories otherwise inaccessible. 3573 3574@noindent 3575The following option must be specified: 3576 3577@table @code 3578@cindex rfs, mount option 3579@cindex Mount option; rfs 3580@item rfs 3581the pathname to be mounted on top of @code{$@{fs@}}. 3582@end table 3583 3584Usually, the FTP server runs in a chroot-ed environment, for security 3585reasons. In this example, lofs is used to provide a subdirectory within 3586a user's home directory, also available for public ftp. 3587 3588@example 3589lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk 3590@end example 3591 3592@c ---------------------------------------------------------------- 3593@node Memory/RAM Filesystem, Null Filesystem, Loopback Filesystem, Filesystem Types 3594@comment node-name, next, previous, up 3595@section Memory/RAM Filesystem (@samp{mfs}) 3596@cindex Memory/RAM Filesystem 3597@cindex mfs, filesystem type 3598@cindex Filesystem type; mfs 3599 3600The @dfn{mfs} (@samp{type:=mfs}) filesystem is available in 4.4BSD, 3601Linux, and other systems. It creates a filesystem in a portion of the 3602system's memory, thus providing very fast file (volatile) access. 3603 3604XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3605 3606@c ---------------------------------------------------------------- 3607@node Null Filesystem, Floppy Filesystem, Memory/RAM Filesystem, Filesystem Types 3608@comment node-name, next, previous, up 3609@section Null Filesystem (@samp{nullfs}) 3610@cindex Null Filesystem 3611@cindex nullfs, filesystem type 3612@cindex Filesystem type; nullfs 3613 3614The @dfn{nullfs} (@samp{type:=nullfs}) filesystem is available from 4.4BSD, 3615and is very similar to the loopback filesystem, @dfn{lofs}. 3616 3617XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3618 3619@c ---------------------------------------------------------------- 3620@node Floppy Filesystem, Translucent Filesystem, Null Filesystem, Filesystem Types 3621@comment node-name, next, previous, up 3622@section Floppy Filesystem (@samp{pcfs}) 3623@cindex Floppy Filesystem 3624@cindex pcfs, filesystem type 3625@cindex Filesystem type; pcfs 3626 3627The @dfn{pcfs} (@samp{type:=pcfs}) filesystem mounts a floppy previously 3628formatted for the MS-DOS format. 3629 3630@noindent 3631The following option must be specified: 3632 3633@table @code 3634@cindex dev, mount option 3635@cindex Mount option; dev 3636@item dev 3637the block special device to be mounted. 3638@end table 3639 3640A pcfs entry might be: 3641 3642@example 3643pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ 3644 os==sunos5;type:=pcfs;dev:=/dev/diskette 3645@end example 3646 3647@c ---------------------------------------------------------------- 3648@node Translucent Filesystem, Shared Memory+Swap Filesystem, Floppy Filesystem, Filesystem Types 3649@comment node-name, next, previous, up 3650@section Translucent Filesystem (@samp{tfs}) 3651@cindex Translucent Filesystem 3652@cindex tfs, filesystem type 3653@cindex Filesystem type; tfs 3654 3655The @dfn{tfs} (@samp{type:=tfs}) filesystem is an older version of the 36564.4BSD @dfn{unionfs}. 3657 3658XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3659 3660@c ---------------------------------------------------------------- 3661@node Shared Memory+Swap Filesystem, User ID Mapping Filesystem, Translucent Filesystem, Filesystem Types 3662@comment node-name, next, previous, up 3663@section Shared Memory+Swap Filesystem (@samp{tmpfs}) 3664@cindex Shared Memory and Swap Filesystem 3665@cindex tmpfs, filesystem type 3666@cindex Filesystem type; tmpfs 3667 3668The @dfn{tmpfs} (@samp{type:=tmpfs}) filesystem shares memory between a 3669the swap device and the rest of the system. It is generally used to 3670provide a fast access @file{/tmp} directory, one that uses memory that 3671is otherwise unused. This filesystem is available in SunOS 4.x and 5.x. 3672 3673XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3674 3675@c ---------------------------------------------------------------- 3676@node User ID Mapping Filesystem, Program Filesystem, Shared Memory+Swap Filesystem, Filesystem Types 3677@comment node-name, next, previous, up 3678@section User ID Mapping Filesystem (@samp{umapfs}) 3679@cindex User ID Mapping Filesystem 3680@cindex umapfs, filesystem type 3681@cindex Filesystem type; umapfs 3682 3683The @dfn{umapfs} (@samp{type:=umapfs}) filesystem maps User IDs of file 3684ownership, and is available from 4.4BSD. 3685 3686XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3687 3688@c ---------------------------------------------------------------- 3689@node Program Filesystem, Symbolic Link Filesystem, User ID Mapping Filesystem, Filesystem Types 3690@comment node-name, next, previous, up 3691@section Program Filesystem (@samp{program}) 3692@cindex Program filesystem 3693@cindex Mount a filesystem under program control 3694@cindex program, filesystem type 3695@cindex Filesystem type; program 3696 3697The @dfn{program} (@samp{type:=program}) filesystem type allows a 3698program to be run whenever a mount or unmount is required. This allows 3699easy addition of support for other filesystem types, such as MIT's 3700Remote Virtual Disk (RVD) which has a programmatic interface via the 3701commands @samp{rvdmount} and @samp{rvdunmount}. 3702 3703@noindent 3704Both of the following options must be specified: 3705 3706@table @code 3707@cindex mount, mount option 3708@cindex Mount option; mount 3709@item mount 3710the program which will perform the mount. 3711 3712@cindex unmount, mount option 3713@cindex umount, mount option 3714@cindex Mount option; unmount 3715@cindex Mount option; umount 3716@item unmount 3717@item umount 3718the program which will perform the unmount. For convenience, you may 3719use either @samp{unmount} or @samp{umount} but not both. If neither 3720is defined, @i{Amd} will default to @samp{umount $@{fs@}} (the actual 3721unmount program pathname will be automatically determined at the time 3722GNU @code{configure} runs.) 3723@end table 3724 3725The exit code from these two programs is interpreted as a Unix error 3726code. As usual, exit code zero indicates success. To execute the 3727program, @i{Amd} splits the string on whitespace to create an array of 3728substrings. Single quotes @samp{'} can be used to quote whitespace 3729if that is required in an argument. There is no way to escape or change 3730the single quote character. 3731 3732To run e.g. the program @samp{rvdmount} with a host name and filesystem as 3733arguments, it would be specified by 3734@samp{fs:=$@{autodir@}$@{path@};type:=program;mount:="/etc/rvdmount 3735rvdmount fserver $@{fs@}";unmount:="/etc/rdvumount rvdumount $@{fs@}"}. 3736 3737The first element in the array is taken as the pathname of the program 3738to execute. The other members of the array form the argument vector 3739to be passed to the program, @dfn{including argument zero}. The array 3740is exactly the same as the array passed to the execv() system call 3741(man execv for details). The split string must have at least two 3742elements. The programs are directly executed by @i{Amd}, not via a 3743shell. Therefore, if a script is to be used as a mount/umount 3744program, it @dfn{must} begin with a @code{#!} interpreter specification. 3745 3746Often, this program mount type is used for Samba mounts, where you 3747need a double slash in pathnames. However, @i{Amd} normalizes 3748sequences of slashes into one slash. Therefore, you must use an 3749escaped slash, preceded by an escaped backslash. So to get a double 3750slash in the mount command, you need the eight character sequence 3751@samp{\\\/\\\/} in your map. For example: 3752 3753@samp{mount="/sbin/mount mount -r -t smbfs -o-N,-Ihostname \\\/\\\/guest@@venus/mp3"} 3754 3755If a filesystem type is to be heavily used, it may be worthwhile adding 3756a new filesystem type into @i{Amd}, but for most uses the program 3757filesystem should suffice. 3758 3759When the program is run, standard input and standard error are inherited 3760from the current values used by @i{Amd}. Standard output is a 3761duplicate of standard error. The value specified with the @code{-l} 3762command line option has no effect on standard error. 3763 3764@i{Amd} guarantees that the mountpoint will be created before calling 3765the mount program, and that it will be removed after the umount 3766program returns success. 3767 3768@c ---------------------------------------------------------------- 3769@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types 3770@comment node-name, next, previous, up 3771@section Symbolic Link Filesystem (@samp{link}) 3772@cindex Symbolic link filesystem 3773@cindex Referencing part of the local name space 3774@cindex Mounting part of the local name space 3775@cindex How to reference part of the local name space 3776@cindex link, filesystem type 3777@cindex symlink, link filesystem type 3778@cindex Filesystem type; link 3779 3780Each filesystem type creates a symbolic link to point from the volume 3781name to the physical mount point. The @samp{link} filesystem does the 3782same without any other side effects. This allows any part of the 3783machines name space to be accessed via @i{Amd}. 3784 3785One common use for the symlink filesystem is @file{/homes} which can be 3786made to contain an entry for each user which points to their 3787(auto-mounted) home directory. Although this may seem rather expensive, 3788it provides a great deal of administrative flexibility. 3789 3790@noindent 3791The following option must be defined: 3792 3793@table @code 3794@item fs 3795The value of @var{fs} option specifies the destination of the link, as 3796modified by the @var{sublink} option. If @var{sublink} is non-null, it 3797is appended to @code{$@{fs@}}@code{/} and the resulting string is used 3798as the target. 3799@end table 3800 3801The @samp{link} filesystem can be thought of as identical to the 3802@samp{ufs} filesystem but without actually mounting anything. 3803 3804An example entry might be: 3805 3806@example 3807jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp 3808@end example 3809which would return a symbolic link pointing to @file{/home/charm/jsp}. 3810 3811@c ---------------------------------------------------------------- 3812@node Symbolic Link Filesystem II, NFS-Link Filesystem, Symbolic Link Filesystem, Filesystem Types 3813@comment node-name, next, previous, up 3814@section Symbolic Link Filesystem II (@samp{linkx}) 3815@cindex Symbolic link filesystem II 3816@cindex Referencing an existing part of the local name space 3817@cindex Mounting an existing part of the local name space 3818@cindex How to reference an existing part of the local name space 3819@cindex linkx, filesystem type 3820@cindex symlink, linkx filesystem type 3821@cindex Filesystem type; linkx 3822 3823The @dfn{linkx} (@samp{type:=linkx}) filesystem type is identical to @samp{link} with the 3824exception that the target of the link must exist. Existence is checked 3825with the @b{lstat}(2) system call. 3826 3827The @samp{linkx} filesystem type is particularly useful for wildcard map 3828entries. In this case, a list of possible targets can be given and 3829@i{Amd} will choose the first one which exists on the local machine. 3830 3831@c ---------------------------------------------------------------- 3832@node NFS-Link Filesystem, Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types 3833@comment node-name, next, previous, up 3834@section NFS-Link Filesystem (@samp{nfsl}) 3835@cindex NFS-Link filesystem II 3836@cindex Referencing an existing part of the name space if target exists 3837@cindex Mounting a remote part of the name space if target is missing 3838@cindex Symlink if target exists, NFS otherwise 3839@cindex nfsl, filesystem type 3840@cindex symlink, nfsl filesystem type 3841@cindex Filesystem type; nfsl 3842 3843The @dfn{nfsl} (@samp{type:=nfsl}) filesystem type is a combination of two others: 3844@samp{link} and @samp{nfs}. If the local host name is equal to the 3845value of @code{$@{rhost@}} @emph{and} the target pathname listed in 3846@code{$@{fs@}} exists, @samp{nfsl} will behave exactly as 3847@samp{type:=link}, and refer to the target as a symbolic link. If the 3848local host name is not equal to the value of @code{$@{rhost@}}, or if 3849the target of the link does not exist, @i{Amd} will treat it as 3850@samp{type:=nfs}, and will mount a remote pathname for it. 3851 3852The @samp{nfsl} filesystem type is particularly useful as a shorthand 3853for the more cumbersome and yet one of the most popular @i{Amd} 3854entries. For example, you can simplify all map entries that look like: 3855 3856@example 3857zing -fs:=/n/shekel/u/zing \ 3858 host!=shekel;type:=nfs;rhost:=shekel;rfs:=$@{fs@} \ 3859 host==shekel;type:=link 3860@end example 3861 3862or 3863 3864@example 3865zing -fs:=/n/shekel/u/zing \ 3866 exists($@{fs@});type:=link \ 3867 !exists($@{fs@});type:=nfs;rhost:=shekel;rfs:=$@{fs@} 3868@end example 3869 3870into a shorter form 3871 3872@example 3873zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=$@{fs@} 3874@end example 3875 3876Not just does it make the maps smaller and simpler, but it avoids 3877possible mistakes that often happen when forgetting to set up the two 3878entries (one for @samp{type:=nfs} and the other for @samp{type:=link}) 3879necessary to perform transparent mounts of existing or remote mounts. 3880 3881@c ---------------------------------------------------------------- 3882@node Automount Filesystem, Direct Automount Filesystem, NFS-Link Filesystem, Filesystem Types 3883@comment node-name, next, previous, up 3884@section Automount Filesystem (@samp{auto}) 3885@cindex Automount filesystem 3886@cindex Map cache types 3887@cindex Setting map cache parameters 3888@cindex How to set map cache parameters 3889@cindex How to start an indirect automount point 3890@cindex auto, filesystem type 3891@cindex Filesystem type; auto 3892@cindex SIGHUP signal 3893@cindex Map cache synchronizing 3894@cindex Synchronizing the map cache 3895@cindex Map cache options 3896@cindex Regular expressions in maps 3897 3898The @dfn{auto} (@samp{type:=auto}) filesystem type creates a new automount point below an 3899existing automount point. Top-level automount points appear as system 3900mount points. An automount mount point can also appear as a 3901sub-directory of an existing automount point. This allows some 3902additional structure to be added, for example to mimic the mount tree of 3903another machine. 3904 3905The following options may be specified: 3906 3907@table @code 3908@cindex cache, mount map option 3909@cindex Mount map option; cache 3910@item cache 3911specifies whether the data in this mount-map should be 3912cached. The default value is @samp{none}, in which case 3913no caching is done in order to conserve memory. 3914 3915However, better performance and reliability can be obtained by caching 3916some or all of a mount-map. 3917 3918If the cache option specifies @samp{all}, 3919the entire map is enumerated when the mount point is created. 3920 3921If the cache option specifies @samp{inc}, caching is done incrementally 3922as and when data is required. 3923Some map types do not support cache mode @samp{all}, in which case @samp{inc} 3924is used whenever @samp{all} is requested. 3925 3926Caching can be entirely disabled by using cache mode @samp{none}. 3927 3928If the cache option specifies @samp{regexp} then the entire map will be 3929enumerated and each key will be treated as an egrep-style regular 3930expression. The order in which a cached map is searched does not 3931correspond to the ordering in the source map so the regular expressions 3932should be mutually exclusive to avoid confusion. 3933 3934Each mount map type has a default cache type, usually @samp{inc}, which 3935can be selected by specifying @samp{mapdefault}. 3936 3937The cache mode for a mount map can only be selected on the command line. 3938Starting @i{Amd} with the command: 3939 3940@example 3941amd /homes hesiod.homes -cache:=inc 3942@end example 3943 3944will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name 3945server with local incremental caching of all successfully resolved names. 3946 3947All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} 3948signal and, if cache @samp{all} mode was selected, the cache will be 3949reloaded. This can be used to inform @i{Amd} that a map has been 3950updated. In addition, whenever a cache lookup fails and @i{Amd} needs 3951to examine a map, the map's modify time is examined. If the cache is 3952out of date with respect to the map then it is flushed as if a 3953@samp{SIGHUP} had been received. 3954 3955An additional option (@samp{sync}) may be specified to force @i{Amd} to 3956check the map's modify time whenever a cached entry is being used. For 3957example, an incremental, synchronized cache would be created by the 3958following command: 3959 3960@example 3961amd /homes hesiod.homes -cache:=inc,sync 3962@end example 3963 3964@item fs 3965specifies the name of the mount map to use for the new mount point. 3966 3967Arguably this should have been specified with the @code{$@{rfs@}} option but 3968we are now stuck with it due to historical accident. 3969 3970@c %If the string @samp{.} is used then the same map is used; 3971@c %in addition the lookup prefix is set to the name of the mount point followed 3972@c %by a slash @samp{/}. 3973@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. 3974@c 3975 3976@item pref 3977alters the name that is looked up in the mount map. If 3978@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended 3979to the name requested by the kernel @dfn{before} the map is 3980searched. The default prefix is the prefix of the parent map (if any) 3981with name of the auto node appended to it. That means if you want no 3982prefix you must say so in the map: @samp{pref:=null}. 3983 3984@item opts 3985Normally, @samp{auto} style maps are not browsable even if you turn on 3986directory browsability (@pxref{browsable_dirs Parameter}). To enable 3987browsing entries in @samp{auto} maps, specify @samp{opts:=browsable} 3988or @samp{opts:=fullybrowsable} in 3989the description of this map. 3990 3991@end table 3992 3993The server @samp{dylan.doc.ic.ac.uk} has two user disks: 3994@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as 3995@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since 3996@samp{/home} is already an automount point, this naming is achieved with 3997the following map entries:@refill 3998 3999@example 4000dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4001dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 4002dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 4003@end example 4004 4005@c ---------------------------------------------------------------- 4006@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types 4007@comment node-name, next, previous, up 4008@section Direct Automount Filesystem (@samp{direct}) 4009@cindex Direct automount filesystem 4010@cindex How to start a direct automount point 4011@cindex direct, filesystem type 4012@cindex Filesystem type; direct 4013 4014The @dfn{direct} (@samp{type:=direct}) filesystem is almost identical to 4015the automount filesystem. Instead of appearing to be a directory of 4016mount points, it appears as a symbolic link to a mounted filesystem. 4017The mount is done at the time the link is accessed. @xref{Automount 4018Filesystem}, for a list of required options. 4019 4020Direct automount points are created by specifying the @samp{direct} 4021filesystem type on the command line: 4022 4023@example 4024amd ... /usr/man auto.direct -type:=direct 4025@end example 4026 4027where @samp{auto.direct} would contain an entry such as: 4028 4029@example 4030usr/man -type:=nfs;rfs:=/usr/man \ 4031 rhost:=man-server1 rhost:=man-server2 4032@end example 4033 4034In this example, @samp{man-server1} and @samp{man-server2} are file 4035servers which export copies of the manual pages. Note that the key 4036which is looked up is the name of the automount point without the 4037leading @samp{/}. 4038 4039Note that the implementation of the traditional @dfn{direct} filesystem is 4040essentially a hack (pretending that the root of an NFS filesystem is a 4041symlink) and many modern operating systems get very unhappy about 4042it. For example, Linux kernel 2.4+ completely disallows it, and Solaris 40432.8 fails to unmount it when @i{Amd} shuts down. Therefore, the use of 4044the traditional @dfn{direct} filesystem is strongly discouraged; it is 4045only semi-supported, at best. 4046 4047The autofs implementations that permit direct mounts are fully 4048supported, however. That currently includes all versions of 4049Solaris. Linux autofs does NOT support direct mounts at all. 4050 4051@c ---------------------------------------------------------------- 4052@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types 4053@comment node-name, next, previous, up 4054@section Union Filesystem (@samp{union}) 4055@cindex Union filesystem 4056@cindex union, filesystem type 4057@cindex Filesystem type; union 4058 4059The @dfn{union} (@samp{type:=union}) filesystem type allows the contents of several 4060directories to be merged and made visible in a single directory. This 4061can be used to overcome one of the major limitations of the Unix mount 4062mechanism which only allows complete directories to be mounted. 4063 4064For example, supposing @file{/tmp} and @file{/var/tmp} were to be merged 4065into a new directory called @file{/mtmp}, with files in @file{/var/tmp} 4066taking precedence. The following command could be used to achieve this 4067effect: 4068 4069@example 4070amd ... /mtmp union:/tmp:/var/tmp -type:=union 4071@end example 4072 4073Currently, the unioned directories must @emph{not} be automounted. That 4074would cause a deadlock. This seriously limits the current usefulness of 4075this filesystem type and the problem will be addressed in a future 4076release of @i{Amd}. 4077 4078Files created in the union directory are actually created in the last 4079named directory. This is done by creating a wildcard entry which points 4080to the correct directory. The wildcard entry is visible if the union 4081directory is listed, so allowing you to see which directory has 4082priority. 4083 4084The files visible in the union directory are computed at the time 4085@i{Amd} is started, and are not kept up-to-date with respect to the 4086underlying directories. Similarly, if a link is removed, for example 4087with the @samp{rm} command, it will be lost forever. 4088 4089@c ---------------------------------------------------------------- 4090@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types 4091@comment node-name, next, previous, up 4092@section Error Filesystem (@samp{error}) 4093@cindex Error filesystem 4094@cindex error, filesystem type 4095@cindex Filesystem type; error 4096 4097The @dfn{error} (@samp{type:=error}) filesystem type is used internally as a catch-all in the 4098case where none of the other filesystems was selected, or some other 4099error occurred. Lookups and mounts always fail with ``No such file or 4100directory''. All other operations trivially succeed. 4101 4102The error filesystem is not directly accessible. 4103 4104@c ---------------------------------------------------------------- 4105@node Top-level Filesystem, Root Filesystem, Error Filesystem, Filesystem Types 4106@comment node-name, next, previous, up 4107@section Top-level Filesystem (@samp{toplvl}) 4108@cindex Top level filesystem 4109@cindex toplvl, filesystem type 4110@cindex Filesystem type; toplvl 4111 4112The @dfn{toplvl} (@samp{type:=toplvl}) filesystems is derived from the @samp{auto} filesystem 4113and is used to mount the top-level automount nodes. Requests of this 4114type are automatically generated from the command line arguments. 4115 4116@c ---------------------------------------------------------------- 4117@node Root Filesystem, Inheritance Filesystem, Top-level Filesystem, Filesystem Types 4118@comment node-name, next, previous, up 4119@section Root Filesystem (@samp{root}) 4120@cindex Root filesystem 4121@cindex root, filesystem type 4122@cindex Filesystem type; root 4123 4124The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal 4125placeholder onto which @i{Amd} can pin @samp{toplvl} mounts. Only one 4126node of this type need ever exist and one is created automatically 4127during startup. The effect of having more than one root node is 4128undefined. 4129 4130The root filesystem is not directly accessible. 4131 4132@c ---------------------------------------------------------------- 4133@node Inheritance Filesystem, , Root Filesystem, Filesystem Types 4134@comment node-name, next, previous, up 4135@section Inheritance Filesystem (@samp{inherit}) 4136@cindex Inheritance filesystem 4137@cindex Nodes generated on a restart 4138@cindex inherit, filesystem type 4139@cindex Filesystem type; inherit 4140 4141The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly 4142accessible. Instead, internal mount nodes of this type are 4143automatically generated when @i{Amd} is started with the @code{-r} option. 4144At this time the system mount table is scanned to locate any filesystems 4145which are already mounted. If any reference to these filesystems is 4146made through @i{Amd} then instead of attempting to mount it, @i{Amd} 4147simulates the mount and @dfn{inherits} the filesystem. This allows a 4148new version of @i{Amd} to be installed on a live system simply by 4149killing the old daemon with @samp{SIGTERM} and starting the new one.@refill 4150 4151This filesystem type is not generally visible externally, but it is 4152possible that the output from @samp{amq -m} may list @samp{inherit} as 4153the filesystem type. This happens when an inherit operation cannot 4154be completed for some reason, usually because a fileserver is down. 4155 4156@c ################################################################ 4157@node Amd Configuration File, Run-time Administration, Filesystem Types, Top 4158@comment node-name, next, previous, up 4159@chapter Amd Configuration File 4160@cindex Amd Configuration File 4161@cindex amd.conf 4162 4163The @samp{amd.conf} file is the configuration file for @i{Amd}, as part 4164of the am-utils suite. This file contains runtime configuration 4165information for the @i{Amd} automounter program. 4166 4167@menu 4168* File Format:: 4169* The Global Section:: 4170* Regular Map Sections:: 4171* Common Parameters:: 4172* Global Parameters:: 4173* Regular Map Parameters:: 4174* amd.conf Examples:: 4175@end menu 4176 4177@c ================================================================ 4178@node File Format, The Global Section, Amd Configuration File, Amd Configuration File 4179@comment node-name, next, previous, up 4180@section File Format 4181@cindex amd.conf file format 4182 4183The @samp{amd.conf} file consists of sections and parameters. A section 4184begins with the name of the section in square brackets @samp{[]} and 4185continues until the next section begins or the end of the file is reached. 4186Sections contain parameters of the form @samp{name = value}. 4187 4188The file is line-based --- that is, each newline-terminated line 4189represents either a comment, a section name or a parameter. No 4190line-continuation syntax is available. 4191 4192Section names, parameter names and their values are case sensitive. 4193 4194Only the first equals sign in a parameter is significant. Whitespace 4195before or after the first equals sign is discarded. Leading, trailing 4196and internal whitespace in section and parameter names is irrelevant. 4197Leading and trailing whitespace in a parameter value is discarded. 4198Internal whitespace within a parameter value is not allowed, unless the 4199whole parameter value is quoted with double quotes as in @samp{name = 4200"some value"}. 4201 4202Any line beginning with a pound sign @samp{#} is ignored, as are lines 4203containing only whitespace. 4204 4205The values following the equals sign in parameters are all either a 4206string (no quotes needed if string does not include spaces) or a 4207boolean, which may be given as @samp{yes}/@samp{no}. Case is significant in all 4208values. Some items such as cache timeouts are numeric. 4209 4210@c ================================================================ 4211@node The Global Section, Regular Map Sections, File Format, Amd Configuration File 4212@comment node-name, next, previous, up 4213@section The Global Section 4214@cindex amd.conf global section 4215 4216The global section must be specified as @samp{[global]}. Parameters in 4217this section either apply to @i{Amd} as a whole, or to all other regular map 4218sections which follow. There should be only one global section defined 4219in one configuration file. 4220 4221It is highly recommended that this section be specified first in the 4222configuration file. If it is not, then regular map sections which 4223precede it will not use global values defined later. 4224 4225@c ================================================================ 4226@node Regular Map Sections, Common Parameters, The Global Section, Amd Configuration File 4227@comment node-name, next, previous, up 4228@section Regular Map Sections 4229@cindex amd.conf regular map sections 4230 4231Parameters in regular (non-global) sections apply to a single map entry. 4232For example, if the map section @samp{[/homes]} is defined, then all 4233parameters following it will be applied to the @file{/homes} 4234@i{Amd}-managed mount point. 4235 4236@c ================================================================ 4237@node Common Parameters, Global Parameters, Regular Map Sections, Amd Configuration File 4238@comment node-name, next, previous, up 4239@section Common Parameters 4240@cindex amd.conf common parameters 4241 4242These parameters can be specified either in the global or a map-specific 4243section. Entries specified in a map-specific section override the default 4244value or one defined in the global section. If such a common parameter is 4245specified only in the global section, it is applicable to all regular map 4246sections that follow. 4247 4248@menu 4249* autofs_use_lofs Parameter:: 4250* browsable_dirs Parameter:: 4251* map_defaults Parameter:: 4252* map_options Parameter:: 4253* map_type Parameter:: 4254* mount_type Parameter:: 4255* search_path Parameter:: 4256* selectors_in_defaults Parameter:: 4257* sun_map_syntax Parameter:: 4258@end menu 4259 4260@c ---------------------------------------------------------------- 4261@node autofs_use_lofs Parameter, browsable_dirs Parameter, Common Parameters, Common Parameters 4262@comment node-name, next, previous, up 4263@subsection @t{autofs_use_lofs} Parameter 4264@cindex autofs_use_lofs Parameter 4265 4266(type=string, default=@samp{yes}). 4267When set to @samp{yes}, @i{Amd}'s autofs code will use lofs-type 4268(loopback) mounts for @code{type:=link} mounts, as well as several 4269other cases that require local references. This has the advantage 4270that @i{Amd} does not use a secondary mount point and users do not see 4271external pathnames (the infamous @code{/bin/pwd} problem, where it 4272reports a different path than the user chdir'ed into). One of the 4273disadvantages of using this option is that the autofs code is 4274relatively new and the in-place mounts have not been throughly tested. 4275 4276If this option is set to @samp{no}, then @i{Amd}'s autofs code will 4277use symlinks instead of lofs-type mounts for local references. This 4278has the advantage of using simpler (more stable) code, but at the 4279expense of negating one of autofs's big advantages: the hiding of 4280@i{Amd}'s internal paths. Note that symlinks are not supported in all 4281autofs implementations, especially those derived from Solaris Autofs 4282v1. Also, on Solaris 2.6 and newer, autofs symlinks are not cached, 4283resulting in repeated up-call requests to @i{Amd}. 4284 4285@c ---------------------------------------------------------------- 4286@node browsable_dirs Parameter, map_defaults Parameter, autofs_use_lofs Parameter, Common Parameters 4287@comment node-name, next, previous, up 4288@subsection @t{browsable_dirs} Parameter 4289@cindex browsable_dirs Parameter 4290 4291(type=string, default=@samp{no}). If @samp{yes}, then @i{Amd}'s top-level 4292mount points will be browsable to @b{readdir}(3) calls. This means you 4293could run for example @b{ls}(1) and see what keys are available to mount 4294in that directory. Not all entries are made visible to @b{readdir}(3): 4295the @samp{/defaults} entry, wildcard entries, and those with a @file{/} 4296in them are not included. If you specify @samp{full} to this option, 4297all but the @samp{/defaults} entry will be visible. Note that if you run 4298a command which will attempt to @b{stat}(2) the entries, such as often 4299done by @samp{ls -l} or @samp{ls -F}, @i{Amd} will attempt to mount 4300@i{every} entry in that map. This is often called a ``mount storm''. 4301 4302Note that mount storms are mostly avoided by using autofs mounts 4303(@samp{mount_type = autofs}). 4304 4305@c ---------------------------------------------------------------- 4306@node map_defaults Parameter, map_options Parameter, browsable_dirs Parameter, Common Parameters 4307@comment node-name, next, previous, up 4308@subsection @t{map_defaults} Parameter 4309@cindex map_defaults Parameter 4310 4311(type=string, default to empty). This option sets a string to be used 4312as the map's @code{/defaults} entry, overriding any @code{/defaults} 4313specified in the map. This allows local users to override a given 4314map's defaults without modifying maps globally (which is impossible in 4315sites where the maps are managed by a different administrative group). 4316 4317@c ---------------------------------------------------------------- 4318@node map_options Parameter, map_type Parameter, map_defaults Parameter, Common Parameters 4319@comment node-name, next, previous, up 4320@subsection @t{map_options} Parameter 4321@cindex map_options Parameter 4322 4323(type=string, default no options). This option is the same as 4324specifying map options on the command line to @i{Amd}, such as 4325@samp{cache:=all}. 4326 4327@c ---------------------------------------------------------------- 4328@node map_type Parameter, mount_type Parameter, map_options Parameter, Common Parameters 4329@comment node-name, next, previous, up 4330@subsection @t{map_type} Parameter 4331@cindex map_type Parameter 4332 4333(type=string, default search all map types). If specified, @i{Amd} will 4334initialize the map only for the type given. This is useful to avoid the 4335default map search type used by @i{Amd} which takes longer and can have 4336undesired side-effects such as initializing NIS even if not used. 4337Possible values are 4338 4339@table @samp 4340@item file 4341plain files 4342@item hesiod 4343Hesiod name service from MIT 4344@item ldap 4345Lightweight Directory Access Protocol 4346@item ndbm 4347(New) dbm style hash files 4348@item nis 4349Network Information Services (version 2) 4350@item nisplus 4351Network Information Services Plus (version 3) 4352@item passwd 4353local password files 4354@item union 4355union maps 4356@end table 4357 4358@c ---------------------------------------------------------------- 4359@node mount_type Parameter, search_path Parameter, map_type Parameter, Common Parameters 4360@comment node-name, next, previous, up 4361@subsection @t{mount_type} Parameter 4362@cindex mount_type Parameter 4363 4364(type=string, default=@samp{nfs}). All @i{Amd} mount types default to NFS. 4365That is, @i{Amd} is an NFS server on the map mount points, for the local 4366host it is running on. If @samp{autofs} is specified, @i{Amd} will be 4367an autofs server for those mount points. 4368 4369@c ---------------------------------------------------------------- 4370@node search_path Parameter, selectors_in_defaults Parameter, mount_type Parameter, Common Parameters 4371@comment node-name, next, previous, up 4372@subsection @t{search_path} Parameter 4373@cindex search_path Parameter 4374 4375(type=string, default no search path). This provides a 4376(colon-delimited) search path for file maps. Using a search path, 4377sites can allow for local map customizations and overrides, and can 4378distributed maps in several locations as needed. 4379 4380@c ---------------------------------------------------------------- 4381@node selectors_in_defaults Parameter, sun_map_syntax Parameter, search_path Parameter, Common Parameters 4382@comment node-name, next, previous, up 4383@subsection @t{selectors_in_defaults} Parameter 4384@cindex selectors_in_defaults Parameter 4385 4386(type=boolean, default=@samp{no}). If @samp{yes}, then the 4387@samp{/defaults} entry of maps will search for and process any 4388selectors before setting defaults for all other keys in that map. 4389Useful when you want to set different options for a complete map based 4390on some parameters. For example, you may want to better the NFS 4391performance over slow slip-based networks as follows: 4392 4393@example 4394/defaults \ 4395 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \ 4396 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192 4397@end example 4398 4399Deprecated form: selectors_on_default. 4400 4401@c ---------------------------------------------------------------- 4402@node sun_map_syntax Parameter, , selectors_in_defaults Parameter, Common Parameters 4403@comment node-name, next, previous, up 4404@subsection @t{sun_map_syntax} Parameter 4405@cindex sun_map_syntax Parameter 4406 4407(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will 4408parse the map according to the Sun Automount syntax. 4409 4410 4411@c ================================================================ 4412@node Global Parameters, Regular Map Parameters, Common Parameters, Amd Configuration File 4413@comment node-name, next, previous, up 4414@section Global Parameters 4415@cindex amd.conf global parameters 4416 4417The following parameters are applicable to the @samp{[global]} section only. 4418 4419@menu 4420* arch Parameter:: 4421* auto_attrcache Parameter:: 4422* auto_dir Parameter:: 4423* cache_duration Parameter:: 4424* cluster Parameter:: 4425* debug_mtab_file Parameter:: 4426* debug_options Parameter:: 4427* dismount_interval Parameter:: 4428* domain_strip Parameter:: 4429* exec_map_timeout Parameter:: 4430* forced_unmounts Parameter:: 4431* full_os Parameter:: 4432* fully_qualified_hosts Parameter:: 4433* hesiod_base Parameter:: 4434* karch Parameter:: 4435* ldap_base Parameter:: 4436* ldap_cache_maxmem Parameter:: 4437* ldap_cache_seconds Parameter:: 4438* ldap_hostports Parameter:: 4439* ldap_proto_version Parameter:: 4440* local_domain Parameter:: 4441* localhost_address Parameter:: 4442* log_file Parameter:: 4443* log_options Parameter:: 4444* map_reload_interval Parameter:: 4445* nfs_allow_any_interface Parameter:: 4446* nfs_allow_insecure_port Parameter:: 4447* nfs_proto Parameter:: 4448* nfs_retransmit_counter Parameter:: 4449* nfs_retransmit_counter_udp Parameter:: 4450* nfs_retransmit_counter_tcp Parameter:: 4451* nfs_retransmit_counter_toplvl Parameter:: 4452* nfs_retry_interval Parameter:: 4453* nfs_retry_interval_udp Parameter:: 4454* nfs_retry_interval_tcp Parameter:: 4455* nfs_retry_interval_toplvl Parameter:: 4456* nfs_vers Parameter:: 4457* nis_domain Parameter:: 4458* normalize_hostnames Parameter:: 4459* normalize_slashes Parameter:: 4460* os Parameter:: 4461* osver Parameter:: 4462* pid_file Parameter:: 4463* plock Parameter:: 4464* portmap_program Parameter:: 4465* preferred_amq_port Parameter:: 4466* print_pid Parameter:: 4467* print_version Parameter:: 4468* restart_mounts Parameter:: 4469* show_statfs_entries Parameter:: 4470* truncate_log Parameter:: 4471* unmount_on_exit Parameter:: 4472* use_tcpwrappers Parameter:: 4473* vendor Parameter:: 4474@end menu 4475 4476@c ---------------------------------------------------------------- 4477@node arch Parameter, auto_attrcache Parameter, Global Parameters, Global Parameters 4478@comment node-name, next, previous, up 4479@subsection @t{arch} Parameter 4480@cindex arch Parameter 4481 4482(type=string, default to compiled in value). Same as the @code{-A} 4483option to @i{Amd}. Allows you to override the value of the @i{arch} 4484@i{Amd} variable. 4485 4486@c ---------------------------------------------------------------- 4487@node auto_attrcache Parameter, auto_dir Parameter, arch Parameter, Global Parameters 4488@comment node-name, next, previous, up 4489@subsection @t{auto_attrcache} Parameter 4490@cindex auto_attrcache Parameter 4491 4492(type=numeric, default=0). Specify in seconds (or units of 0.1 4493seconds, depending on the OS), what is the (kernel-side) NFS attribute 4494cache timeout for @i{Amd}'s own automount points. A value of 0 is 4495supposed to turn off attribute caching, meaning that @i{Amd} will be 4496consulted via a kernel-RPC each time someone stat()'s the mount point 4497(which could be abused as a denial-of-service attack). 4498 4499@emph{WARNING}: @i{Amd} depends on being able to turn off the NFS 4500attribute cache of the client OS. If it cannot be turned off, then 4501users may get ESTALE errors or symlinks that point to the wrong 4502places. This is more likely under heavy use of @i{Amd}, for example 4503if your system is experiencing frequent map changes or frequent 4504mounts/unmounts. Therefore, under normal circumstances, this 4505parameter should remain set to 0, to ensure that the attribute cache 4506is indeed off. 4507 4508Unfortunately, some kernels (e.g., certain BSDs) don't have a way to 4509turn off the NFS attribute cache. Setting this parameter to 0 is 4510supposed to turn off attribute caching entirely, but unfortunately it 4511does not; instead, the attribute cache is set to some internal 4512hard-coded default (usually anywhere from 5-30 seconds). If you 4513suspect that your OS doesn't have a reliable way of turning off the 4514attribute cache, then it is better to set this parameter to the 4515smallest possible non-zero value (set @samp{auto_attrcache=1} in your 4516@code{amd.conf}). This will not eliminate the problem, but reduce the 4517risk window somewhat. The best solutions are (1) to use @i{Amd} in 4518Autofs mode, if it's supported in your OS, and (2) talk to your OS 4519vendor to support a true @samp{noac} flag. See the 4520@uref{http://www.am-utils.org/docs/am-utils/attrcache.txt,README.attrcache} 4521document for more details. 4522 4523If you are able to turn off the attribute cache on your OS, alas, 4524@i{Amd}'s performance may degrade (when not using Autofs) because 4525every traversal of an automounter-controlled pathname will result in a 4526lookup request from the kernel to @i{Amd}. Under heavy loads, for 4527example when using recursive tools like @samp{find}, @samp{rdist}, or 4528@samp{rsync}, this performance degradation can be noticeable. There 4529are two possible solutions that some administrators have chosen to 4530improve performance: 4531 4532@enumerate 4533 4534@item 4535First, you can turn off unmounting using the @samp{nounmount} mount 4536option. This will ensure that no @i{Amd} symlink could ever change, 4537thereby the kernel's attribute cache and @i{Amd} will always be in 4538sync. However, this method will cause the number of mounts to keep 4539growing, even if some are no longer in use; this has the disadvantage 4540that your system could be more susceptible to hangs if even one of 4541those accumulating mounts hangs due to a downed server. 4542 4543@item 4544Second, you can turn on attribute caching carefully by setting a small 4545automounter attribute cache value (say, one second), and a relatively 4546large dismount interval (say, one hour). (@xref{dismount_interval 4547Parameter}.) For example, you can set this in your @code{amd.conf}: 4548 4549@example 4550[global] 4551auto_attrcache = 1 4552dismount_interval = 3600 4553@end example 4554 4555This has the benefit of using the kernel's attribute cache and thus 4556improving performance. The disadvantage with this option is that the 4557window of vulnerability is not eliminated entirely: it is only made 4558smaller. 4559 4560@end enumerate 4561 4562@c ---------------------------------------------------------------- 4563@node auto_dir Parameter, cache_duration Parameter, auto_attrcache Parameter, Global Parameters 4564@comment node-name, next, previous, up 4565@subsection @t{auto_dir} Parameter 4566@cindex auto_dir Parameter 4567 4568(type=string, default=@samp{/a}). Same as the @code{-a} option to @i{Amd}. 4569This sets the private directory where @i{Amd} will create 4570sub-directories for its real mount points. 4571 4572@c ---------------------------------------------------------------- 4573@node cache_duration Parameter, cluster Parameter, auto_dir Parameter, Global Parameters 4574@comment node-name, next, previous, up 4575@subsection @t{cache_duration} Parameter 4576@cindex cache_duration Parameter 4577 4578(type=numeric, default=300). Same as the @code{-c} option to @i{Amd}. 4579Sets the duration in seconds that looked-up or mounted map entries 4580remain in the cache. 4581 4582@c ---------------------------------------------------------------- 4583@node cluster Parameter, debug_mtab_file Parameter, cache_duration Parameter, Global Parameters 4584@comment node-name, next, previous, up 4585@subsection @t{cluster} Parameter 4586@cindex cluster Parameter 4587 4588(type=string, default no cluster). Same as the @code{-C} option to 4589@i{Amd}. Specifies the alternate HP-UX cluster to use. 4590 4591@c ---------------------------------------------------------------- 4592@node debug_mtab_file Parameter, debug_options Parameter, cluster Parameter, Global Parameters 4593@comment node-name, next, previous, up 4594@subsection @t{debug_mtab_file} Parameter 4595@cindex debug_mtab_file Parameter 4596 4597(type=string, default="/tmp/mtab"). Path to mtab file that is used 4598by @i{Amd} to store a list of mounted file systems during debug-mtab mode. 4599This option only applies to systems that store mtab information on disk. 4600 4601@c ---------------------------------------------------------------- 4602@node debug_options Parameter, dismount_interval Parameter, debug_mtab_file Parameter, Global Parameters 4603@comment node-name, next, previous, up 4604@subsection @t{debug_options} Parameter 4605@cindex debug_options Parameter 4606 4607(type=string, default no debug options). Same as the @code{-D} option 4608to @i{Amd}. Specify any debugging options for @i{Amd}. Works only if 4609am-utils was configured for debugging using the @code{--enable-debug} 4610option. The additional @samp{mem} option can be turned on via 4611@code{--enable-debug=mem}. Otherwise debugging options are ignored. 4612Options are comma delimited, and can be preceded by the string 4613@samp{no} to negate their meaning. You can get the list of supported 4614debugging and logging options by running @code{amd -H}. Possible 4615values those listed for the -D option. @xref{-D Option}. 4616 4617@c ---------------------------------------------------------------- 4618@node dismount_interval Parameter, domain_strip Parameter, debug_options Parameter, Global Parameters 4619@comment node-name, next, previous, up 4620@subsection @t{dismount_interval} Parameter 4621@cindex dismount_interval Parameter 4622 4623(type=numeric, default=120). Same as the @code{-w} option to 4624@i{Amd}. Specify in seconds, the time between attempts to dismount file 4625systems that have exceeded their cached times. 4626 4627@c ---------------------------------------------------------------- 4628@node domain_strip Parameter, exec_map_timeout Parameter, dismount_interval Parameter, Global Parameters 4629@comment node-name, next, previous, up 4630@subsection @t{domain_strip} Parameter 4631@cindex domain_strip Parameter 4632 4633(type=boolean, default=@samp{yes}). If @samp{yes}, then the domain 4634name part referred to by @code{$@{rhost@}} is stripped off. This is 4635useful to keep logs and smaller. If @samp{no}, then the domain name 4636part is left changed. This is useful when using multiple domains with 4637the same maps (as you may have hosts whose domain-stripped name is 4638identical). 4639 4640@c ---------------------------------------------------------------- 4641@node exec_map_timeout Parameter, forced_unmounts Parameter, domain_strip Parameter, Global Parameters 4642@comment node-name, next, previous, up 4643@subsection @t{exec_map_timeout} Parameter 4644@cindex exec_map_timeout Parameter 4645 4646(type=numeric, default=10). The timeout in seconds that @i{Amd} will 4647wait for an executable map program before an answer is returned from 4648that program (or script). This value should be set to as small as 4649possible while still allowing normal replies to be returned before the 4650timer expires, because during the time that the executable map program 4651is queried, @i{Amd} is essentially waiting and is thus not responding 4652to any other queries. @xref{Executable maps}. 4653 4654@c ---------------------------------------------------------------- 4655@node forced_unmounts Parameter, full_os Parameter, exec_map_timeout Parameter, Global Parameters 4656@comment node-name, next, previous, up 4657@subsection @t{forced_unmounts} Parameter 4658@cindex forced_unmounts Parameter 4659 4660(type=boolean, default=@samp{no}). 4661Sometimes, mount points are hung due to unrecoverable conditions, such 4662as when NFS servers migrate, change their IP address, are down 4663permanently, or due to hardware failures, and more. In this case, 4664attempting to unmount an existing mount point, or even just to 4665@b{stat}(2) it, results in one of three fatal errors: EIO, ESTALE, or 4666EBUSY. At that point, @i{Amd} can do little to recover that hung 4667point (in fact, the OS cannot automatically recover either). For that 4668reason, some OSs support special kinds of forced unmounts, which must 4669be used very carefully: they will force an unmount immediately (or 4670lazily on Linux), which could result in application data loss. 4671However, that may be the only way to recover the entire host (without 4672rebooting). Once a hung mount point is forced out, @i{Amd} can then 4673re-mount a replacement one (if available), bringing a mostly-hung 4674system back to operation and avoiding a potentially costly reboot. 4675 4676If the @samp{forced_unmounts} option is set to @samp{yes}, and the 4677client OS supports forced or lazy unmounts, then @i{Amd} will attempt 4678to use them if it gets any of the three serious error conditions 4679listed above. Note that @i{Amd} will force the unmount of mount 4680points that returned EBUSY only for @samp{type:=toplvl} mounts 4681(@pxref{Top-level Filesystem}): that is, @i{Amd}'s own mount points. 4682This is useful to recover from a previously hung @i{Amd}, and to 4683ensure that an existing @i{Amd} can shutdown cleanly even if some 4684processes are keeping its mount points busy (i.e., when a user's shell 4685process uses @code{cd} to set its CWD to @i{Amd}'s own mount point). 4686 4687If this option is set to @samp{no} (the default), then @i{Amd} will 4688not attempt this special recovery procedure. 4689 4690@c ---------------------------------------------------------------- 4691@node full_os Parameter, fully_qualified_hosts Parameter, forced_unmounts Parameter, Global Parameters 4692@comment node-name, next, previous, up 4693@subsection @t{full_os} Parameter 4694@cindex full_os Parameter 4695 4696(type=string, default to compiled in value). The full name of the 4697operating system, along with its version. Allows you to override the 4698compiled-in full name and version of the operating system. Useful when 4699the compiled-in name is not desired. For example, the full operating 4700system name on linux comes up as @samp{linux}, but you can override it 4701to @samp{linux-2.2.5}. 4702 4703@c ---------------------------------------------------------------- 4704@node fully_qualified_hosts Parameter, hesiod_base Parameter, full_os Parameter, Global Parameters 4705@comment node-name, next, previous, up 4706@subsection @t{fully_qualified_hosts} Parameter 4707@cindex fully_qualified_hosts Parameter 4708 4709(type=string, default=@samp{no}). If @samp{yes}, @i{Amd} will perform RPC 4710authentication using fully-qualified host names. This is necessary for 4711some systems, and especially when performing cross-domain mounting. For 4712this function to work, the @i{Amd} variable @samp{$@{hostd@}} is used, 4713requiring that @samp{$@{domain@}} not be null. 4714 4715@c ---------------------------------------------------------------- 4716@node hesiod_base Parameter, karch Parameter, fully_qualified_hosts Parameter, Global Parameters 4717@comment node-name, next, previous, up 4718@subsection @t{hesiod_base} Parameter 4719@cindex hesiod_base Parameter 4720 4721(type=string, default=@samp{automount}). Specify the base name for 4722hesiod maps. 4723 4724@c ---------------------------------------------------------------- 4725@node karch Parameter, ldap_base Parameter, hesiod_base Parameter, Global Parameters 4726@comment node-name, next, previous, up 4727@subsection @t{karch} Parameter 4728@cindex karch Parameter 4729 4730(type=string, default to karch of the system). Same as the @code{-k} 4731option to @i{Amd}. Allows you to override the kernel-architecture of 4732your system. Useful for example on Sun (Sparc) machines, where you can 4733build one @i{Amd} binary, and run it on multiple machines, yet you want 4734each one to get the correct @i{karch} variable set (for example, sun4c, 4735sun4m, sun4u, etc.) Note that if not specified, @i{Amd} will use 4736@b{uname}(2) to figure out the kernel architecture of the machine. 4737 4738@c ---------------------------------------------------------------- 4739@node ldap_base Parameter, ldap_cache_maxmem Parameter, karch Parameter, Global Parameters 4740@comment node-name, next, previous, up 4741@subsection @t{ldap_base} Parameter 4742@cindex ldap_base Parameter 4743 4744(type=string, default not set). 4745Specify the base name for LDAP. This often includes LDAP-specific 4746values such as country and organization. 4747 4748@c ---------------------------------------------------------------- 4749@node ldap_cache_maxmem Parameter, ldap_cache_seconds Parameter, ldap_base Parameter, Global Parameters 4750@comment node-name, next, previous, up 4751@subsection @t{ldap_cache_maxmem} Parameter 4752@cindex ldap_cache_maxmem Parameter 4753 4754(type=numeric, default=131072). Specify the maximum memory @i{Amd} 4755should use to cache LDAP entries. 4756 4757@c ---------------------------------------------------------------- 4758@node ldap_cache_seconds Parameter, ldap_hostports Parameter, ldap_cache_maxmem Parameter, Global Parameters 4759@comment node-name, next, previous, up 4760@subsection @t{ldap_cache_seconds} Parameter 4761@cindex ldap_cache_seconds Parameter 4762 4763(type=numeric, default=0). Specify the number of seconds to keep 4764entries in the cache. 4765 4766@c ---------------------------------------------------------------- 4767@node ldap_hostports Parameter, ldap_proto_version Parameter, ldap_cache_seconds Parameter, Global Parameters 4768@comment node-name, next, previous, up 4769@subsection @t{ldap_hostports} Parameter 4770@cindex ldap_hostports Parameter 4771 4772(type=string, default not set). 4773Specify the LDAP host and port values. 4774 4775@c ---------------------------------------------------------------- 4776@node ldap_proto_version Parameter, local_domain Parameter, ldap_hostports Parameter, Global Parameters 4777@comment node-name, next, previous, up 4778@subsection @t{ldap_proto_version} Parameter 4779@cindex ldap_proto_version Parameter 4780 4781(type=numeric, default=2). Specify the LDAP protocol version to use. 4782With a value of 3 will use LDAPv3 protocol. 4783 4784@c ---------------------------------------------------------------- 4785@node local_domain Parameter, localhost_address Parameter, ldap_proto_version Parameter, Global Parameters 4786@comment node-name, next, previous, up 4787@subsection @t{local_domain} Parameter 4788@cindex local_domain Parameter 4789 4790(type=string, default no sub-domain). Same as the @code{-d} option 4791to @i{Amd}. Specify the local domain name. If this option is not given 4792the domain name is determined from the hostname, by removing the first 4793component of the fully-qualified host name. 4794 4795@c ---------------------------------------------------------------- 4796@node localhost_address Parameter, log_file Parameter, local_domain Parameter, Global Parameters 4797@comment node-name, next, previous, up 4798@subsection @t{localhost_address} Parameter 4799@cindex localhost_address Parameter 4800 4801(type=string, default to localhost or 127.0.0.1). Specify the name or 4802IP address for @i{Amd} to use when connecting the sockets for the 4803local NFS server and the RPC server. This defaults to 127.0.0.1 or 4804whatever the host reports as its local address. This parameter is 4805useful on hosts with multiple addresses where you want to force 4806@i{Amd} to connect to a specific address. 4807 4808@c ---------------------------------------------------------------- 4809@node log_file Parameter, log_options Parameter, localhost_address Parameter, Global Parameters 4810@comment node-name, next, previous, up 4811@subsection @t{log_file} Parameter 4812@cindex log_file Parameter 4813 4814(type=string, default=@samp{stderr}). Same as the @code{-l} option to 4815@i{Amd}. Specify a file name to log @i{Amd} events to. 4816If the string @samp{/dev/stderr} is specified, 4817@i{Amd} will send its events to the standard error file descriptor. 4818 4819If the string @samp{syslog} is given, @i{Amd} will record its events 4820with the system logger @b{syslogd}(8). If your system supports syslog 4821facilities, then the default facility used is @samp{LOG_DAEMON}. 4822 4823When using syslog, if you wish to change the facility, append its name 4824to the option name, delimited by a single colon. For example, if it is 4825the string @samp{syslog:local7} then @i{Amd} will log messages via 4826@b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If the facility 4827name specified is not recognized, @i{Amd} will default to @samp{LOG_DAEMON}. 4828Note: while you can use any syslog facility available on your system, it 4829is generally a bad idea to use those reserved for other services such as 4830@samp{kern}, @samp{lpr}, @samp{cron}, etc. 4831 4832@c ---------------------------------------------------------------- 4833@node log_options Parameter, map_reload_interval Parameter, log_file Parameter, Global Parameters 4834@comment node-name, next, previous, up 4835@subsection @t{log_options} Parameter 4836@cindex log_options Parameter 4837 4838(type=string, default=``defaults''). Same as the @code{-x} 4839option to @i{Amd}. Specify any logging options for @i{Amd}. Options 4840are comma delimited, and can be preceded by the string @samp{no} to 4841negate their meaning. The @samp{debug} logging option is only available 4842if am-utils was configured with @code{--enable-debug}. You can get the 4843list of supported debugging options by running @code{amd -H}. Possible 4844values are: 4845 4846@table @samp 4847@item all 4848all messages 4849@item defaults 4850an alias for "fatal,error,user,warning,info" 4851@item debug 4852debug messages 4853@item error 4854non-fatal system errors (cannot be turned off) 4855@item fatal 4856fatal errors (cannot be turned off) 4857@item info 4858information 4859@item map 4860map errors 4861@item stats 4862additional statistical information 4863@item user 4864non-fatal user errors 4865@item warn 4866warnings 4867@item warning 4868warnings 4869@end table 4870 4871@c ---------------------------------------------------------------- 4872@node map_reload_interval Parameter, nfs_allow_any_interface Parameter, log_options Parameter, Global Parameters 4873@comment node-name, next, previous, up 4874@subsection @t{map_reload_interval} Parameter 4875@cindex map_reload_interval Parameter 4876 4877(type=numeric, default=3600). The number of seconds that @i{Amd} will 4878wait before it checks to see if any maps have changed at their source 4879(NIS servers, LDAP servers, files, etc.). @i{Amd} will reload only 4880those maps that have changed. 4881 4882@c ---------------------------------------------------------------- 4883@node nfs_allow_any_interface Parameter, nfs_allow_insecure_port Parameter, map_reload_interval Parameter, Global Parameters 4884@comment node-name, next, previous, up 4885@subsection @t{nfs_allow_any_interface} Parameter 4886@cindex nfs_allow_any_interface Parameter 4887 4888(type=string, default=@samp{no}). Normally @i{Amd} accepts local NFS 4889packets only from 127.0.0.1. If this parameter is set to @samp{yes}, 4890then @i{amd} will accept local NFS packets from any local interface; 4891this is useful on hosts that may have multiple interfaces where the 4892system is forced to send all outgoing packets (even those bound to the 4893same host) via an address other than 127.0.0.1. 4894 4895@c ---------------------------------------------------------------- 4896@node nfs_allow_insecure_port Parameter, nfs_proto Parameter, nfs_allow_any_interface Parameter, Global Parameters 4897@comment node-name, next, previous, up 4898@subsection @t{nfs_allow_insecure_port} Parameter 4899@cindex nfs_allow_insecure_port Parameter 4900 4901(type=string, default=@samp{no}). Normally @i{Amd} will refuse requests 4902coming from unprivileged ports (i.e., ports >= 1024 on Unix systems), 4903so that only privileged users and the kernel can send NFS requests to 4904it. However, some kernels (certain versions of Darwin, MacOS X, and 4905Linux) have bugs that cause them to use unprivileged ports in certain 4906situations, which causes @i{Amd} to stop dead in its tracks. This 4907parameter allows @i{Amd} to operate normally even on such systems, at the 4908expense of a slight decrease in the security of its operations. If 4909you see messages like ``ignoring request from foo:1234, port not 4910reserved'' in your @i{Amd} log, try enabling this parameter and give it 4911another go. 4912 4913@c ---------------------------------------------------------------- 4914@node nfs_proto Parameter, nfs_retransmit_counter Parameter, nfs_allow_insecure_port Parameter, Global Parameters 4915@comment node-name, next, previous, up 4916@subsection @t{nfs_proto} Parameter 4917@cindex nfs_proto Parameter 4918 4919(type=string, default to trying version tcp then udp). By default, 4920@i{Amd} tries @code{tcp} and then @code{udp}. This option forces the 4921overall NFS protocol used to TCP or UDP. It overrides what is in the 4922@i{Amd} maps, and is useful when @i{Amd} is compiled with TCP support 4923in NFSv2/NFSv3 that may not be stable. With this option you can turn 4924off the complete usage of TCP for NFS dynamically (without having to 4925recompile @i{Amd}), and use UDP only, until such time as TCP support 4926is desired again. 4927 4928@c ---------------------------------------------------------------- 4929@node nfs_retransmit_counter Parameter, nfs_retransmit_counter_udp Parameter, nfs_proto Parameter, Global Parameters 4930@comment node-name, next, previous, up 4931@subsection @t{nfs_retransmit_counter} Parameter 4932@cindex nfs_retransmit_counter Parameter 4933 4934(type=numeric, default=11). Same as the @i{retransmit} part of the 4935@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the 4936number of NFS retransmissions that the kernel will use to communicate 4937with @i{Amd} using either UDP or TCP mounts. @xref{-t Option}. 4938 4939@c ---------------------------------------------------------------- 4940@node nfs_retransmit_counter_udp Parameter, nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter Parameter, Global Parameters 4941@comment node-name, next, previous, up 4942@subsection @t{nfs_retransmit_counter_udp} Parameter 4943@cindex nfs_retransmit_counter_udp Parameter 4944@cindex nfs_retransmit_counter Parameter 4945@cindex UDP 4946 4947(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4948parameter, but applied globally only to UDP mounts. 4949@xref{nfs_retransmit_counter Parameter}. 4950 4951@c ---------------------------------------------------------------- 4952@node nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter_toplvl Parameter, nfs_retransmit_counter_udp Parameter, Global Parameters 4953@comment node-name, next, previous, up 4954@subsection @t{nfs_retransmit_counter_tcp} Parameter 4955@cindex nfs_retransmit_counter_tcp Parameter 4956@cindex nfs_retransmit_counter Parameter 4957@cindex TCP 4958 4959(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4960parameter, but applied globally only to TCP mounts. 4961@xref{nfs_retransmit_counter Parameter}. 4962 4963@c ---------------------------------------------------------------- 4964@node nfs_retransmit_counter_toplvl Parameter, nfs_retry_interval Parameter, nfs_retransmit_counter_tcp Parameter, Global Parameters 4965@comment node-name, next, previous, up 4966@subsection @t{nfs_retransmit_counter_toplvl} Parameter 4967@cindex nfs_retransmit_counter_toplvl Parameter 4968@cindex nfs_retransmit_counter Parameter 4969@cindex UDP 4970 4971(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4972parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 4973systems it is useful to set this differently than the OS default, so 4974as to better tune @i{Amd}'s responsiveness under heavy scheduler 4975loads. @xref{nfs_retransmit_counter Parameter}. 4976 4977@c ---------------------------------------------------------------- 4978@node nfs_retry_interval Parameter, nfs_retry_interval_udp Parameter, nfs_retransmit_counter_toplvl Parameter, Global Parameters 4979@comment node-name, next, previous, up 4980@subsection @t{nfs_retry_interval} Parameter 4981@cindex nfs_retry_interval Parameter 4982 4983(type=numeric, default=8). Same as the @i{timeout} part of the 4984@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the NFS 4985timeout interval, in @emph{tenths} of seconds, between NFS/RPC retries 4986(for UDP or TCP). This is the value that the kernel will use to 4987communicate with @i{Amd}. @xref{-t Option}. 4988 4989@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 4990retries. The values of the @i{nfs_retransmit_counter} and the 4991@i{nfs_retry_interval} parameters change the overall retry interval. 4992Too long an interval gives poor interactive response; too short an 4993interval causes excessive retries. 4994 4995@c ---------------------------------------------------------------- 4996@node nfs_retry_interval_udp Parameter, nfs_retry_interval_tcp Parameter, nfs_retry_interval Parameter, Global Parameters 4997@comment node-name, next, previous, up 4998@subsection @t{nfs_retry_interval_udp} Parameter 4999@cindex nfs_retry_interval_udp Parameter 5000@cindex nfs_retry_interval Parameter 5001@cindex UDP 5002 5003(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5004parameter, but applied globally only to UDP mounts. 5005@xref{nfs_retry_interval Parameter}. 5006 5007@c ---------------------------------------------------------------- 5008@node nfs_retry_interval_tcp Parameter, nfs_retry_interval_toplvl Parameter, nfs_retry_interval_udp Parameter, Global Parameters 5009@comment node-name, next, previous, up 5010@subsection @t{nfs_retry_interval_tcp} Parameter 5011@cindex nfs_retry_interval_tcp Parameter 5012@cindex nfs_retry_interval Parameter 5013@cindex TCP 5014 5015(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5016parameter, but applied globally only to TCP mounts. 5017@xref{nfs_retry_interval Parameter}. 5018 5019@c ---------------------------------------------------------------- 5020@node nfs_retry_interval_toplvl Parameter, nfs_vers Parameter, nfs_retry_interval_tcp Parameter, Global Parameters 5021@comment node-name, next, previous, up 5022@subsection @t{nfs_retry_interval_toplvl} Parameter 5023@cindex nfs_retry_interval_toplvl Parameter 5024@cindex nfs_retry_interval Parameter 5025@cindex UDP 5026 5027(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5028parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 5029systems it is useful to set this differently than the OS default, so 5030as to better tune @i{Amd}'s responsiveness under heavy scheduler 5031loads. @xref{nfs_retry_interval Parameter}. 5032 5033@c ---------------------------------------------------------------- 5034@node nfs_vers Parameter, nis_domain Parameter, nfs_retry_interval_toplvl Parameter, Global Parameters 5035@comment node-name, next, previous, up 5036@subsection @t{nfs_vers} Parameter 5037@cindex nfs_vers Parameter 5038 5039(type=numeric, default to trying version 3 then 2). By default, 5040@i{Amd} tries version 3 and then version 2. This option forces the 5041overall NFS protocol used to version 3 or 2. It overrides what is in 5042the @i{Amd} maps, and is useful when @i{Amd} is compiled with NFSv3 5043support that may not be stable. With this option you can turn off the 5044complete usage of NFSv3 dynamically (without having to recompile 5045@i{Amd}), and use NFSv2 only, until such time as NFSv3 support is 5046desired again. 5047 5048@c ---------------------------------------------------------------- 5049@node nis_domain Parameter, normalize_hostnames Parameter, nfs_vers Parameter, Global Parameters 5050@comment node-name, next, previous, up 5051@subsection @t{nis_domain} Parameter 5052@cindex nis_domain Parameter 5053 5054(type=string, default to local NIS domain name). Same as the 5055@code{-y} option to @i{Amd}. Specify an alternative NIS domain from 5056which to fetch the NIS maps. The default is the system domain name. 5057This option is ignored if NIS support is not available. 5058 5059@c ---------------------------------------------------------------- 5060@node normalize_hostnames Parameter, normalize_slashes Parameter, nis_domain Parameter, Global Parameters 5061@comment node-name, next, previous, up 5062@subsection @t{normalize_hostnames} Parameter 5063@cindex normalize_hostnames Parameter 5064 5065(type=boolean, default=@samp{no}). Same as the @code{-n} option to @i{Amd}. 5066If @samp{yes}, then the name referred to by @code{$@{rhost@}} is normalized 5067relative to the host database before being used. The effect is to 5068translate aliases into ``official'' names. 5069 5070@c ---------------------------------------------------------------- 5071@node normalize_slashes Parameter, os Parameter, normalize_hostnames Parameter, Global Parameters 5072@comment node-name, next, previous, up 5073@subsection @t{normalize_slashes} Parameter 5074@cindex normalize_slashes Parameter 5075 5076(type=boolean, default=@samp{yes}). If @samp{yes} then amd will 5077condense all multiple @code{/} (slash) characters into one and remove 5078all trailing slashes. If @samp{no}, then amd will not touch strings 5079that may contain repeated or trailing slashes. The latter is 5080sometimes useful with SMB mounts, which often require multiple slash 5081characters in pathnames. 5082 5083@c ---------------------------------------------------------------- 5084@node os Parameter, osver Parameter, normalize_slashes Parameter, Global Parameters 5085@comment node-name, next, previous, up 5086@subsection @t{os} Parameter 5087@cindex os Parameter 5088 5089(type=string, default to compiled in value). Same as the @code{-O} 5090option to @i{Amd}. Allows you to override the compiled-in name of the 5091operating system. Useful when the built-in name is not desired for 5092backward compatibility reasons. For example, if the built-in name is 5093@samp{sunos5}, you can override it to @samp{sos5}, and use older maps 5094which were written with the latter in mind. 5095 5096 5097@c ---------------------------------------------------------------- 5098@node osver Parameter, pid_file Parameter, os Parameter, Global Parameters 5099@comment node-name, next, previous, up 5100@subsection @t{osver} Parameter 5101@cindex osver Parameter 5102 5103(type=string, default to compiled in value). Same as the @code{-o} 5104option to @i{Amd}. Allows you to override the compiled-in version 5105number of the operating system. Useful when the built-in version is not 5106desired for backward compatibility reasons. For example, if the build 5107in version is @samp{2.5.1}, you can override it to @samp{5.5.1}, and use 5108older maps that were written with the latter in mind. 5109 5110@c ---------------------------------------------------------------- 5111@node pid_file Parameter, plock Parameter, osver Parameter, Global Parameters 5112@comment node-name, next, previous, up 5113@subsection @t{pid_file} Parameter 5114@cindex pid_file Parameter 5115 5116(type=string, default=@samp{/dev/stdout}). Specify a file to store the process 5117ID of the running daemon into. If not specified, @i{Amd} will print its 5118process id onto the standard output. Useful for killing @i{Amd} after 5119it had run. Note that the PID of a running @i{Amd} can also be 5120retrieved via @i{Amq} (@pxref{Amq -p option}). 5121 5122This file is used only if the @samp{print_pid} option is on 5123(@pxref{print_pid Parameter}). 5124 5125@c ---------------------------------------------------------------- 5126@node plock Parameter, portmap_program Parameter, pid_file Parameter, Global Parameters 5127@comment node-name, next, previous, up 5128@subsection @t{plock} Parameter 5129@cindex plock Parameter 5130 5131(type=boolean, default=@samp{yes}). Same as the @code{-S} option to @i{Amd}. 5132If @samp{yes}, lock the running executable pages of @i{Amd} into memory. 5133To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 5134or @b{mlockall}(2) 5135call can lock the @i{Amd} process into memory. This way there is less 5136chance the operating system will schedule, page out, and swap the 5137@i{Amd} process as needed. This improves @i{Amd}'s performance, at the 5138cost of reserving the memory used by the @i{Amd} process (making it 5139unavailable for other processes). 5140 5141@c ---------------------------------------------------------------- 5142@node portmap_program Parameter, preferred_amq_port Parameter, plock Parameter, Global Parameters 5143@comment node-name, next, previous, up 5144@subsection @t{portmap_program} Parameter 5145@cindex portmap_program Parameter 5146 5147(type=numeric, default=300019). Specify an alternate Port-mapper RPC 5148program number, other than the official number. This is useful when 5149running multiple @i{Amd} processes. For example, you can run another 5150@i{Amd} in ``test'' mode, without affecting the primary @i{Amd} process 5151in any way. For safety reasons, the alternate program numbers that can 5152be specified must be in the range 300019-300029, inclusive. @i{Amq} has 5153an option @code{-P} which can be used to specify an alternate program 5154number of an @i{Amd} to contact. In this way, amq can fully control any 5155number of @i{Amd} processes running on the same host. 5156 5157@c ---------------------------------------------------------------- 5158@node preferred_amq_port Parameter, print_pid Parameter, portmap_program Parameter, Global Parameters 5159@comment node-name, next, previous, up 5160@subsection @t{preferred_amq_port} Parameter 5161@cindex preferred_amq_port Parameter 5162 5163(type=numeric, default=0). Specify an alternate Port-mapper RPC port 5164number for @i{Amd}'s @i{Amq} service. This is used for both UDP and 5165TCP. Setting this value to 0 (or not defining it) will cause @i{Amd} 5166to select an arbitrary port number. Setting the @i{Amq} RPC service 5167port to a specific number is useful in firewalled or NAT'ed 5168environments, where you need to know which port @i{Amd} will listen 5169on. 5170 5171@c ---------------------------------------------------------------- 5172@node print_pid Parameter, print_version Parameter, preferred_amq_port Parameter, Global Parameters 5173@comment node-name, next, previous, up 5174@subsection @t{print_pid} Parameter 5175@cindex print_pid Parameter 5176 5177(type=boolean, default=@samp{no}). Same as the @code{-p} option to @i{Amd}. 5178If @samp{yes}, @i{Amd} will print its process ID upon starting. 5179 5180@c ---------------------------------------------------------------- 5181@node print_version Parameter, restart_mounts Parameter, print_pid Parameter, Global Parameters 5182@comment node-name, next, previous, up 5183@subsection @t{print_version} Parameter 5184@cindex print_version Parameter 5185 5186(type=boolean, default=@samp{no}). Same as the @code{-v} option to @i{Amd}, 5187but the version prints and @i{Amd} continues to run. If @samp{yes}, @i{Amd} 5188will print its version information string, which includes some 5189configuration and compilation values. 5190 5191@c ---------------------------------------------------------------- 5192@node restart_mounts Parameter, show_statfs_entries Parameter, print_version Parameter, Global Parameters 5193@comment node-name, next, previous, up 5194@subsection @t{restart_mounts} Parameter 5195@cindex restart_mounts Parameter 5196 5197(type=boolean, default=@samp{no}). Same as the @code{-r} option to @i{Amd}. 5198If @samp{yes} @i{Amd} will scan the mount table to determine which file 5199systems are currently mounted. Whenever one of these would have been 5200auto-mounted, @i{Amd} inherits it. 5201 5202@c ---------------------------------------------------------------- 5203@node show_statfs_entries Parameter, truncate_log Parameter, restart_mounts Parameter, Global Parameters 5204@comment node-name, next, previous, up 5205@subsection @t{show_statfs_entries} Parameter 5206@cindex show_statfs_entries Parameter 5207 5208(type=boolean), default=@samp{no}). If @samp{yes}, then all maps which are 5209browsable will also show the number of entries (keys) they have when 5210@b{df}(1) runs. (This is accomplished by returning non-zero values to 5211the @b{statfs}(2) system call). 5212 5213@c ---------------------------------------------------------------- 5214@node truncate_log Parameter, unmount_on_exit Parameter, show_statfs_entries Parameter, Global Parameters 5215@comment node-name, next, previous, up 5216@subsection @t{truncate_log} Parameter 5217@cindex truncate_log Parameter 5218 5219(type=boolean), default=@samp{no}). If @samp{yes}, then @i{Amd} will 5220truncate the log file (if it's a regular file) on startup. This could 5221be useful when conducting extensive testing on @i{Amd} maps (or 5222@i{Amd} itself) and you don't want to see log data from a previous run 5223in the same file. 5224 5225@c ---------------------------------------------------------------- 5226@node unmount_on_exit Parameter, use_tcpwrappers Parameter, truncate_log Parameter, Global Parameters 5227@comment node-name, next, previous, up 5228@subsection @t{unmount_on_exit} Parameter 5229@cindex unmount_on_exit Parameter 5230 5231(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will attempt 5232to unmount all file systems which it knows about. Normally it leaves 5233all (esp. NFS) mounted file systems intact. Note that @i{Amd} does not 5234know about file systems mounted before it starts up, unless the 5235@samp{restart_mounts} option is used (@pxref{restart_mounts Parameter}). 5236 5237@c ---------------------------------------------------------------- 5238@node use_tcpwrappers Parameter, vendor Parameter, unmount_on_exit Parameter, Global Parameters 5239@comment node-name, next, previous, up 5240@subsection @t{use_tcpwrappers} Parameter 5241@cindex use_tcpwrappers Parameter 5242 5243(type=boolean), default=@samp{yes}). If @samp{yes}, then amd will use 5244the tcpwrappers (tcpd/librwap) library (if available) to control 5245access to @i{Amd} via the @code{/etc/hosts.allow} and 5246@code{/etc/hosts.deny} files. @i{Amd} will verify that the host 5247running @i{Amq} is authorized to connect. The @code{amd} service name 5248must used in the @code{/etc/hosts.allow} and @code{/etc/hosts.deny} 5249files. For example, to allow only localhost to connect to @i{Amd}, 5250add this line to @code{/etc/hosts.allow}: 5251 5252@example 5253amd: localhost 5254@end example 5255 5256and this line to @code{/etc/hosts.deny}: 5257 5258@example 5259amd: ALL 5260@end example 5261 5262Consult the man pages for @b{hosts_access}(5) for more information on using 5263the tcpwrappers access-control library. 5264 5265Note that in particular, you should not configure your @code{hosts.allow} 5266file to spawn a command for @i{Amd}: that will cause @i{Amd} to not be able 5267to @code{waitpid} on the child process ID of any background un/mount that 5268@i{Amd} issued, resulting in a confused @i{Amd} that does not know what 5269happened to those background un/mount requests. 5270 5271@c ---------------------------------------------------------------- 5272@node vendor Parameter, , use_tcpwrappers Parameter, Global Parameters 5273@comment node-name, next, previous, up 5274@subsection @t{vendor} Parameter 5275@cindex vendor Parameter 5276 5277(type=string, default to compiled in value). The name of the vendor of 5278the operating system. Overrides the compiled-in vendor name. Useful 5279when the compiled-in name is not desired. For example, most Intel based 5280systems set the vendor name to @samp{unknown}, but you can set it to 5281@samp{redhat}. 5282 5283@c ================================================================ 5284@node Regular Map Parameters, amd.conf Examples, Global Parameters, Amd Configuration File 5285@comment node-name, next, previous, up 5286@section Regular Map Parameters 5287@cindex amd.conf regular map parameters 5288 5289The following parameters are applicable only to regular map sections. 5290 5291@menu 5292* map_name Parameter:: 5293* tag Parameter:: 5294@end menu 5295 5296@c ---------------------------------------------------------------- 5297@node map_name Parameter, tag Parameter, Regular Map Parameters, Regular Map Parameters 5298@comment node-name, next, previous, up 5299@subsection map_name Parameter 5300@cindex map_name Parameter 5301 5302(type=string, must be specified). Name of the map where the keys are 5303located. 5304 5305@c ---------------------------------------------------------------- 5306@node tag Parameter, , map_name Parameter, Regular Map Parameters 5307@comment node-name, next, previous, up 5308@subsection tag Parameter 5309@cindex tag Parameter 5310 5311(type=string, default no tag). Each map entry in the configuration file 5312can be tagged. If no tag is specified, that map section will always be 5313processed by @i{Amd}. If it is specified, then @i{Amd} will process the map 5314if the @code{-T} option was given to @i{Amd}, and the value given to that 5315command-line option matches that in the map section. 5316 5317@c ================================================================ 5318@node amd.conf Examples, , Regular Map Parameters, Amd Configuration File 5319@comment node-name, next, previous, up 5320@section amd.conf Examples 5321@cindex amd.conf examples 5322 5323The following is the actual @code{amd.conf} file I used at the 5324Computer Science Department of Columbia University. 5325 5326@example 5327# GLOBAL OPTIONS SECTION 5328[ global ] 5329normalize_hostnames = no 5330print_pid = no 5331#pid_file = /var/run/amd.pid 5332restart_mounts = yes 5333#unmount_on_exit = yes 5334auto_dir = /n 5335log_file = /var/log/amd 5336log_options = all 5337#debug_options = defaults 5338plock = no 5339selectors_in_defaults = yes 5340# config.guess picks up "sunos5" and I don't want to edit my maps yet 5341os = sos5 5342# if you print_version after setting up "os", it will show it. 5343print_version = no 5344map_type = file 5345search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib 5346browsable_dirs = yes 5347fully_qualified_hosts = no 5348 5349# DEFINE AN AMD MOUNT POINT 5350[ /u ] 5351map_name = amd.u 5352 5353[ /proj ] 5354map_name = amd.proj 5355 5356[ /src ] 5357map_name = amd.src 5358 5359[ /misc ] 5360map_name = amd.misc 5361 5362[ /import ] 5363map_name = amd.import 5364 5365[ /tftpboot/.amd ] 5366tag = tftpboot 5367map_name = amd.tftpboot 5368@end example 5369 5370@c ################################################################ 5371@node Run-time Administration, FSinfo, Amd Configuration File, Top 5372@comment node-name, next, previous, up 5373@chapter Run-time Administration 5374@cindex Run-time administration 5375@cindex Amq command 5376 5377@menu 5378* Starting Amd:: 5379* Stopping Amd:: 5380* Restarting Amd:: 5381* Controlling Amd:: 5382@end menu 5383 5384@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration 5385@comment node-name, next, previous, up 5386@section Starting @i{Amd} 5387@cindex Starting Amd 5388@cindex Additions to /etc/rc.local 5389@cindex /etc/rc.local additions 5390@cindex ctl-amd 5391 5392@i{Amd} is best started from @samp{/etc/rc.local} on BSD systems, or 5393from the appropriate start-level script in @samp{/etc/init.d} on System V 5394systems. 5395 5396@example 5397if [ -f /usr/local/sbin/ctl-amd ]; then 5398 /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console 5399fi 5400@end example 5401 5402@noindent 5403The shell script, @samp{ctl-amd} is used to start, stop, or restart 5404@i{Amd}. It is a relatively generic script. All options you want to 5405set should not be made in this script, but rather updated in the 5406@file{amd.conf} file. @xref{Amd Configuration File}. 5407 5408If you do not wish to use an @i{Amd} configuration file, you may start 5409@i{Amd} manually. For example, getting the map entries via NIS: 5410 5411@example 5412amd -r -l /var/log/amd `ypcat -k auto.master` 5413@end example 5414 5415@node Stopping Amd, Restarting Amd, Starting Amd, Run-time Administration 5416@comment node-name, next, previous, up 5417@section Stopping @i{Amd} 5418@cindex Stopping Amd 5419@cindex SIGTERM signal 5420@cindex SIGINT signal 5421 5422@i{Amd} stops in response to two signals. 5423 5424@table @samp 5425@item SIGTERM 5426causes the top-level automount points to be unmounted and then @i{Amd} 5427to exit. Any automounted filesystems are left mounted. They can be 5428recovered by restarting @i{Amd} with the @code{-r} command line option.@refill 5429 5430@item SIGINT 5431causes @i{Amd} to attempt to unmount any filesystems which it has 5432automounted, in addition to the actions of @samp{SIGTERM}. This signal 5433is primarily used for debugging.@refill 5434@end table 5435 5436Actions taken for other signals are undefined. 5437 5438The easiest and safest way to stop @i{Amd}, without having to find its 5439process ID by hand, is to use the @file{ctl-amd} script, as with: 5440 5441@example 5442ctl-amd stop 5443@end example 5444 5445@node Restarting Amd, Controlling Amd, Stopping Amd, Run-time Administration 5446@comment node-name, next, previous, up 5447@section Restarting @i{Amd} 5448@cindex Restarting Amd 5449@cindex Killing and starting Amd 5450 5451Before @i{Amd} can be started, it is vital to ensure that no other 5452@i{Amd} processes are managing any of the mount points, and that the 5453previous process(es) have terminated cleanly. When a terminating signal 5454is set to @i{Amd}, the automounter does @emph{not} terminate right then. 5455Rather, it starts by unmounting all of its managed mount mounts in the 5456background, and then terminates. It usually takes a few seconds for 5457this process to happen, but it can take an arbitrarily longer time. If 5458two or more @i{Amd} processes attempt to manage the same mount point, it 5459usually will result in a system lockup. 5460 5461The easiest and safest way to restart @i{Amd}, without having to find 5462its process ID by hand, sending it the @samp{SIGTERM} signal, waiting for @i{Amd} 5463to die cleanly, and verifying so, is to use the @file{ctl-amd} script, 5464as with: 5465 5466@example 5467ctl-amd restart 5468@end example 5469 5470The script will locate the process ID of @i{Amd}, kill it, and wait for 5471it to die cleanly before starting a new instance of the automounter. 5472@file{ctl-amd} will wait for a total of 30 seconds for @i{Amd} to die, 5473and will check once every 5 seconds if it had. 5474 5475@node Controlling Amd, , Restarting Amd, Run-time Administration 5476@comment node-name, next, previous, up 5477@section Controlling @i{Amd} 5478@cindex Controlling Amd 5479@cindex Discovering what is going on at run-time 5480@cindex Listing currently mounted filesystems 5481 5482It is sometimes desirable or necessary to exercise external control 5483over some of @i{Amd}'s internal state. To support this requirement, 5484@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. 5485A variety of information is available. 5486 5487@i{Amq} generally applies an operation, specified by a single letter option, 5488to a list of mount points. The default operation is to obtain statistics 5489about each mount point. This is similar to the output shown above 5490but includes information about the number and type of accesses to each 5491mount point. 5492 5493@menu 5494* Amq default:: Default command behavior. 5495* Amq -f option:: Flushing the map cache. 5496* Amq -h option:: Controlling a non-local host. 5497* Amq -H option:: Print help message. 5498* Amq -l option:: Controlling the log file. 5499* Amq -m option:: Obtaining mount statistics. 5500* Amq -p option:: Getting Amd's process ID. 5501* Amq -P option:: Contacting alternate Amd processes. 5502* Amq -q option:: Suppress synchronous unmounting errors. 5503* Amq -s option:: Obtaining global statistics. 5504* Amq -T option:: Use TCP transport. 5505* Amq -U option:: Use UDP transport. 5506* Amq -u option:: Forcing volumes to time out. 5507* Amq -v option:: Version information. 5508* Amq -w option:: Print Amd current working directory. 5509* Other Amq options:: Three other special options. 5510@end menu 5511 5512@c ---------------------------------------------------------------- 5513@node Amq default, Amq -f option, Controlling Amd, Controlling Amd 5514@comment node-name, next, previous, up 5515@subsection @i{Amq} default information 5516 5517With no arguments, @dfn{Amq} obtains a brief list of all existing 5518mounts created by @i{Amd}. This is different from the list displayed by 5519@b{df}(1) since the latter only includes system mount points. 5520 5521@noindent 5522The output from this option includes the following information: 5523 5524@itemize @bullet 5525@item 5526the automount point, 5527@item 5528the filesystem type, 5529@item 5530the mount map or mount information, 5531@item 5532the internal, or system mount point. 5533@end itemize 5534 5535@noindent 5536For example: 5537 5538@example 5539/ root "root" sky:(pid75) 5540/homes toplvl /usr/local/etc/amd.homes /homes 5541/home toplvl /usr/local/etc/amd.home /home 5542/homes/jsp nfs charm:/home/charm /a/charm/home/charm/jsp 5543/homes/phjk nfs toytown:/home/toytown /a/toytown/home/toytown/ai/phjk 5544@end example 5545 5546@noindent 5547If an argument is given then statistics for that volume name will 5548be output. For example: 5549 5550@example 5551What Uid Getattr Lookup RdDir RdLnk Statfs Mounted@@ 5552/homes 0 1196 512 22 0 30 90/09/14 12:32:55 5553/homes/jsp 0 0 0 0 1180 0 90/10/13 12:56:58 5554@end example 5555 5556@table @code 5557@item What 5558the volume name. 5559 5560@item Uid 5561ignored. 5562 5563@item Getattr 5564the count of NFS @dfn{getattr} requests on this node. This should only be 5565non-zero for directory nodes. 5566 5567@item Lookup 5568the count of NFS @dfn{lookup} requests on this node. This should only be 5569non-zero for directory nodes. 5570 5571@item RdDir 5572the count of NFS @dfn{readdir} requests on this node. This should only 5573be non-zero for directory nodes. 5574 5575@item RdLnk 5576the count of NFS @dfn{readlink} requests on this node. This should be 5577zero for directory nodes. 5578 5579@item Statfs 5580the count of NFS @dfn{statfs} requests on this node. This should only 5581be non-zero for top-level automount points. 5582 5583@item Mounted@@ 5584the date and time the volume name was first referenced. 5585@end table 5586 5587@c ---------------------------------------------------------------- 5588@node Amq -f option, Amq -h option, Amq default, Controlling Amd 5589@comment node-name, next, previous, up 5590@subsection @i{Amq} @code{-f} option 5591@cindex Flushing the map cache 5592@cindex Map cache, flushing 5593 5594The @code{-f} option causes @i{Amd} to flush the internal mount map cache. 5595This is useful for example in Hesiod maps since @i{Amd} will not 5596automatically notice when they have been updated. The map cache can 5597also be synchronized with the map source by using the @samp{sync} option 5598(@pxref{Automount Filesystem}).@refill 5599 5600@c ---------------------------------------------------------------- 5601@node Amq -h option, Amq -H option, Amq -f option, Controlling Amd 5602@comment node-name, next, previous, up 5603@subsection @i{Amq} @code{-h} option 5604@cindex Querying an alternate host 5605 5606By default the local host is used. In an HP-UX cluster the root server 5607is used since that is the only place in the cluster where @i{Amd} will 5608be running. To query @i{Amd} on another host the @code{-h} option should 5609be used. 5610 5611@c ---------------------------------------------------------------- 5612@node Amq -H option, Amq -l option, Amq -h option, Controlling Amd 5613@comment node-name, next, previous, up 5614@subsection @i{Amq} @code{-H} option 5615@cindex Displaying brief help 5616@cindex Help; showing from Amq 5617 5618Print a brief help and usage string. 5619 5620@c ---------------------------------------------------------------- 5621@node Amq -l option, Amq -m option, Amq -H option, Controlling Amd 5622@comment node-name, next, previous, up 5623@subsection @i{Amq} @code{-l} option 5624@cindex Resetting the Amd log file 5625@cindex Setting the Amd log file via Amq 5626@cindex Log file, resetting 5627 5628Tell @i{Amd} to use @i{log_file} as the log file name. For security 5629reasons, this @emph{must} be the same log file which @i{Amd} used when 5630started. This option is therefore only useful to refresh @i{Amd}'s open 5631file handle on the log file, so that it can be rotated and compressed 5632via daily cron jobs. 5633 5634@c ---------------------------------------------------------------- 5635@node Amq -m option, Amq -p option, Amq -l option, Controlling Amd 5636@comment node-name, next, previous, up 5637@subsection @i{Amq} @code{-m} option 5638 5639The @code{-m} option displays similar information about mounted 5640filesystems, rather than automount points. The output includes the 5641following information: 5642 5643@itemize @bullet 5644@item 5645the mount information, 5646@item 5647the mount point, 5648@item 5649the filesystem type, 5650@item 5651the number of references to this filesystem, 5652@item 5653the server hostname, 5654@item 5655the state of the file server, 5656@item 5657any error which has occurred. 5658@end itemize 5659 5660For example: 5661 5662@example 5663"root" truth:(pid602) root 1 localhost is up 5664hesiod.home /home toplvl 1 localhost is up 5665hesiod.vol /vol toplvl 1 localhost is up 5666hesiod.homes /homes toplvl 1 localhost is up 5667amy:/home/amy /a/amy/home/amy nfs 5 amy is up 5668swan:/home/swan /a/swan/home/swan nfs 0 swan is up (Permission denied) 5669ex:/home/ex /a/ex/home/ex nfs 0 ex is down 5670@end example 5671 5672When the reference count is zero the filesystem is not mounted but 5673the mount point and server information is still being maintained 5674by @i{Amd}. 5675 5676@c ---------------------------------------------------------------- 5677@ignore 5678@comment Retained for future consideration: from the description of the 5679@comment amq -M option removed in amd 6.0.5. 5680 5681A future release of @i{Amd} will include code to allow the @b{mount}(8) 5682command to mount automount points: 5683 5684@example 5685mount -t amd /vol hesiod.vol 5686@end example 5687 5688This will then allow @i{Amd} to be controlled from the standard system 5689filesystem mount list. 5690 5691@end ignore 5692 5693@c ---------------------------------------------------------------- 5694@node Amq -p option, Amq -P option, Amq -m option, Controlling Amd 5695@comment node-name, next, previous, up 5696@subsection @i{Amq} @code{-p} option 5697@cindex Process ID; Amd 5698@cindex Amd's process ID 5699@cindex Amd's PID 5700@cindex PID; Amd 5701 5702Return the process ID of the remote or locally running @i{Amd}. Useful 5703when you need to send a signal to the local @i{Amd} process, and would 5704rather not have to search through the process table. This option is 5705used in the @file{ctl-amd} script. 5706 5707@c ---------------------------------------------------------------- 5708@node Amq -P option, Amq -q option, Amq -p option, Controlling Amd 5709@comment node-name, next, previous, up 5710@subsection @i{Amq} @code{-P} option 5711@cindex Multiple Amd processes 5712@cindex Running multiple Amd 5713@cindex Debugging a new Amd configuration 5714@cindex RPC Program numbers; Amd 5715 5716Contact an alternate running @i{Amd} that had registered itself on a 5717different RPC @var{program_number} and apply all other operations to 5718that instance of the automounter. This is useful when you run multiple 5719copies of @i{Amd}, and need to manage each one separately. If not 5720specified, @i{Amq} will use the default program number for @i{Amd}, 300019. 5721For security reasons, the only alternate program numbers @i{Amd} can use 5722range from 300019 to 300029, inclusive. 5723 5724For example, to kill an alternate running @i{Amd}: 5725 5726@example 5727kill `amq -p -P 300020` 5728@end example 5729 5730@c ---------------------------------------------------------------- 5731@node Amq -q option, Amq -s option, Amq -P option, Controlling Amd 5732@comment node-name, next, previous, up 5733@subsection @i{Amq} @code{-q} option 5734@cindex Unmounting a filesystem 5735 5736Suppress any error messages produced when a synchronous unmount fails. 5737See @ref{Amq -u option}. 5738 5739@c ---------------------------------------------------------------- 5740@node Amq -s option, Amq -T option, Amq -q option, Controlling Amd 5741@comment node-name, next, previous, up 5742@subsection @i{Amq} @code{-s} option 5743@cindex Global statistics 5744@cindex Statistics 5745 5746The @code{-s} option displays global statistics. If any other options are specified 5747or any filesystems named then this option is ignored. For example: 5748 5749@example 5750requests stale mount mount unmount 5751deferred fhandles ok failed failed 57521054 1 487 290 7017 5753@end example 5754 5755@table @samp 5756@item Deferred requests 5757are those for which an immediate reply could not be constructed. For 5758example, this would happen if a background mount was required. 5759 5760@item Stale filehandles 5761counts the number of times the kernel passes a stale filehandle to @i{Amd}. 5762Large numbers indicate problems. 5763 5764@item Mount ok 5765counts the number of automounts which were successful. 5766 5767@item Mount failed 5768counts the number of automounts which failed. 5769 5770@item Unmount failed 5771counts the number of times a filesystem could not be unmounted. Very 5772large numbers here indicate that the time between unmount attempts 5773should be increased. 5774@end table 5775 5776@c ---------------------------------------------------------------- 5777@node Amq -T option, Amq -U option, Amq -s option, Controlling Amd 5778@comment node-name, next, previous, up 5779@subsection @i{Amq} @code{-T} option 5780@cindex Forcing Amq to use a TCP transport 5781@cindex TCP; using with Amq 5782 5783The @code{-T} option causes the @i{Amq} to contact @i{Amd} using the TCP 5784transport only (connection oriented). Normally, @i{Amq} will use TCP 5785first, and if that failed, will try UDP. 5786 5787@c ---------------------------------------------------------------- 5788@node Amq -U option, Amq -u option, Amq -T option, Controlling Amd 5789@comment node-name, next, previous, up 5790@subsection @i{Amq} @code{-U} option 5791@cindex Forcing Amq to use a UDP transport 5792@cindex UDP; using with Amq 5793 5794The @code{-U} option causes the @i{Amq} to contact @i{Amd} using the UDP 5795transport only (connectionless). Normally, @i{Amq} will use TCP first, 5796and if that failed, will try UDP. 5797 5798@c ---------------------------------------------------------------- 5799@node Amq -u option, Amq -v option, Amq -U option, Controlling Amd 5800@comment node-name, next, previous, up 5801@subsection @i{Amq} @code{-u} option 5802@cindex Forcing filesystem to time out 5803@cindex Unmounting a filesystem 5804 5805The @code{-u} option causes the time-to-live interval of the named 5806mount points to be expired, thus causing an unmount attempt. This is 5807the only safe way to unmount an automounted filesystem. If @code{-u} 5808is repeated, then @i{Amd} will attempt to unmount the filesystem 5809synchronously. This makes things like 5810 5811@example 5812amq -uu /t/cd0d && eject cd0 5813@end example 5814 5815@noindent 5816work as expected. Any error messages this might produce can be 5817suppressed with the @code{-q} option. See @ref{Amq -q option}. 5818 5819@c The @code{-H} option informs @i{Amd} that the specified mount point 5820@c has hung - as if its keepalive timer had expired. 5821 5822@c ---------------------------------------------------------------- 5823@node Amq -v option, Amq -w option, Amq -u option, Controlling Amd 5824@comment node-name, next, previous, up 5825@subsection @i{Amq} @code{-v} option 5826@cindex Version information at run-time 5827 5828The @code{-v} option displays the version of @i{Amd} in a similar way to 5829@i{Amd}'s @code{-v} option. 5830 5831@c ---------------------------------------------------------------- 5832@node Amq -w option, Other Amq options, Amq -v option, Controlling Amd 5833@comment node-name, next, previous, up 5834@subsection @i{Amq} @code{-w} option 5835@cindex Getting real working directory 5836 5837The @code{-w} option translates a full pathname as returned by 5838@b{getpwd}(3) into a short @i{Amd} pathname that goes through its mount 5839points. This option requires that @i{Amd} is running. 5840 5841@c ---------------------------------------------------------------- 5842@node Other Amq options, , Amq -w option, Controlling Amd 5843@comment node-name, next, previous, up 5844@subsection Other @i{Amq} options 5845@cindex Logging options via Amq 5846@cindex Debugging options via Amq 5847 5848Two other operations are implemented. These modify the state of @i{Amd} 5849as a whole, rather than any particular filesystem. The @code{-x} and 5850@code{-D} options have exactly the same effect as @i{Amd}'s corresponding 5851command line options. 5852 5853When @i{Amd} receives the @code{-x} flag, it disallows turning off the 5854@samp{fatal} or @samp{error} flags. Both are on by default. They are 5855mandatory so that @i{Amd} could report important errors, including 5856errors relating to turning flags on/off. 5857 5858@c ################################################################ 5859@node FSinfo, Hlfsd, Run-time Administration, Top 5860@comment node-name, next, previous, up 5861@chapter FSinfo 5862@cindex FSinfo 5863@cindex Filesystem info package 5864 5865XXX: this chapter should be reviewed by someone knowledgeable with 5866fsinfo. 5867 5868@menu 5869* FSinfo Overview:: Introduction to FSinfo. 5870* Using FSinfo:: Basic concepts. 5871* FSinfo Grammar:: Language syntax, semantics and examples. 5872* FSinfo host definitions:: Defining a new host. 5873* FSinfo host attributes:: Definable host attributes. 5874* FSinfo filesystems:: Defining locally attached filesystems. 5875* FSinfo static mounts:: Defining additional static mounts. 5876* FSinfo automount definitions:: 5877* FSinfo Command Line Options:: 5878* FSinfo errors:: 5879@end menu 5880 5881@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo 5882@comment node-name, next, previous, up 5883@section @i{FSinfo} overview 5884@cindex FSinfo overview 5885 5886@i{FSinfo} is a filesystem management tool. It has been designed to 5887work with @i{Amd} to help system administrators keep track of the ever 5888increasing filesystem namespace under their control. 5889 5890The purpose of @i{FSinfo} is to generate all the important standard 5891filesystem data files from a single set of input data. Starting with a 5892single data source guarantees that all the generated files are 5893self-consistent. One of the possible output data formats is a set of 5894@i{Amd} maps which can be used among the set of hosts described in the 5895input data. 5896 5897@i{FSinfo} implements a declarative language. This language is 5898specifically designed for describing filesystem namespace and physical 5899layouts. The basic declaration defines a mounted filesystem including 5900its device name, mount point, and all the volumes and access 5901permissions. @i{FSinfo} reads this information and builds an internal 5902map of the entire network of hosts. Using this map, many different data 5903formats can be produced including @file{/etc/fstab}, 5904@file{/etc/exports}, @i{Amd} mount maps and 5905@file{/etc/bootparams}.@refill 5906 5907@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo 5908@comment node-name, next, previous, up 5909@section Using @i{FSinfo} 5910@cindex Using FSinfo 5911 5912The basic strategy when using @i{FSinfo} is to gather all the 5913information about all disks on all machines into one set of 5914declarations. For each machine being managed, the following data is 5915required: 5916 5917@itemize @bullet 5918@item 5919Hostname 5920@item 5921List of all filesystems and, optionally, their mount points. 5922@item 5923Names of volumes stored on each filesystem. 5924@item 5925NFS export information for each volume. 5926@item 5927The list of static filesystem mounts. 5928@end itemize 5929 5930The following information can also be entered into the same 5931configuration files so that all data can be kept in one place. 5932 5933@itemize @bullet 5934@item 5935List of network interfaces 5936@item 5937IP address of each interface 5938@item 5939Hardware address of each interface 5940@item 5941Dumpset to which each filesystem belongs 5942@item 5943and more @dots{} 5944@end itemize 5945 5946To generate @i{Amd} mount maps, the automount tree must also be defined 5947(@pxref{FSinfo automount definitions}). This will have been designed at 5948the time the volume names were allocated. Some volume names will not be 5949automounted, so @i{FSinfo} needs an explicit list of which volumes 5950should be automounted.@refill 5951 5952Hostnames are required at several places in the @i{FSinfo} language. It 5953is important to stick to either fully qualified names or unqualified 5954names. Using a mixture of the two will inevitably result in confusion. 5955 5956Sometimes volumes need to be referenced which are not defined in the set 5957of hosts being managed with @i{FSinfo}. The required action is to add a 5958dummy set of definitions for the host and volume names required. Since 5959the files generated for those particular hosts will not be used on them, 5960the exact values used is not critical. 5961 5962@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo 5963@comment node-name, next, previous, up 5964@section @i{FSinfo} grammar 5965@cindex FSinfo grammar 5966@cindex Grammar, FSinfo 5967 5968@i{FSinfo} has a relatively simple grammar. Distinct syntactic 5969constructs exist for each of the different types of data, though they 5970share a common flavor. Several conventions are used in the grammar 5971fragments below. 5972 5973The notation, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more 5974@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one 5975@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input 5976tokens. Items in angle brackets, @i{eg} @var{<hostname>}, represent 5977strings in the input. Strings need not be in double quotes, except to 5978differentiate them from reserved words. Quoted strings may include the 5979usual set of C ``@t{\}'' escape sequences with one exception: a 5980backslash-newline-whitespace sequence is squashed into a single space 5981character. To defeat this feature, put a further backslash at the start 5982of the second line. 5983 5984At the outermost level of the grammar, the input consists of a 5985sequence of host and automount declarations. These declarations are 5986all parsed before they are analyzed. This means they can appear in 5987any order and cyclic host references are possible. 5988 5989@example 5990fsinfo : @i{list(}fsinfo_attr@i{)} ; 5991 5992fsinfo_attr : host | automount ; 5993@end example 5994 5995@menu 5996* FSinfo host definitions:: 5997* FSinfo automount definitions:: 5998@end menu 5999 6000@node FSinfo host definitions, FSinfo host attributes, FSinfo Grammar, FSinfo 6001@comment node-name, next, previous, up 6002@section @i{FSinfo} host definitions 6003@cindex FSinfo host definitions 6004@cindex Defining a host, FSinfo 6005 6006A host declaration consists of three parts: a set of machine attribute 6007data, a list of filesystems physically attached to the machine, and a 6008list of additional statically mounted filesystems. 6009 6010@example 6011host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; 6012@end example 6013 6014Each host must be declared in this way exactly once. Such things as the 6015hardware address, the architecture and operating system types and the 6016cluster name are all specified within the @dfn{host data}. 6017 6018All the disks the machine has should then be described in the @dfn{list 6019of filesystems}. When describing disks, you can specify what 6020@dfn{volname} the disk/partition should have and all such entries are 6021built up into a dictionary which can then be used for building the 6022automounter maps. 6023 6024The @dfn{list of mounts} specifies all the filesystems that should be 6025statically mounted on the machine. 6026 6027@menu 6028* FSinfo host attributes:: 6029* FSinfo filesystems:: 6030* FSinfo static mounts:: 6031@end menu 6032 6033@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions 6034@comment node-name, next, previous, up 6035@section @i{FSinfo} host attributes 6036@cindex FSinfo host attributes 6037@cindex Defining host attributes, FSinfo 6038 6039The host data, @dfn{host_data}, always includes the @dfn{hostname}. In 6040addition, several other host attributes can be given. 6041 6042@example 6043host_data : @var{<hostname>} 6044 | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} 6045 ; 6046 6047host_attrs : host_attr "=" @var{<string>} 6048 | netif 6049 ; 6050 6051host_attr : "config" 6052 | "arch" 6053 | "os" 6054 | "cluster" 6055 ; 6056@end example 6057 6058The @dfn{hostname} is, typically, the fully qualified hostname of the 6059machine. 6060 6061Examples: 6062 6063@example 6064host dylan.doc.ic.ac.uk 6065 6066host @{ 6067 os = hpux 6068 arch = hp300 6069@} dougal.doc.ic.ac.uk 6070@end example 6071 6072The options that can be given as host attributes are shown below. 6073 6074@menu 6075* FSinfo netif Option:: FSinfo host netif. 6076* FSinfo config Option:: FSinfo host config. 6077* FSinfo arch Option:: FSinfo host arch. 6078* FSinfo os Option:: FSinfo host os. 6079* FSinfo cluster Option:: FSinfo host cluster. 6080@end menu 6081 6082@node FSinfo netif Option, FSinfo config Option, , FSinfo host attributes 6083@comment node-name, next, previous, up 6084@subsection netif Option 6085 6086This defines the set of network interfaces configured on the machine. 6087The interface attributes collected by @i{FSinfo} are the IP address, 6088subnet mask and hardware address. Multiple interfaces may be defined 6089for hosts with several interfaces by an entry for each interface. The 6090values given are sanity checked, but are currently unused for anything 6091else. 6092 6093@example 6094netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; 6095 6096netif_attrs : netif_attr "=" @var{<string>} ; 6097 6098netif_attr : "inaddr" | "netmask" | "hwaddr" ; 6099@end example 6100 6101Examples: 6102 6103@example 6104netif ie0 @{ 6105 inaddr = 129.31.81.37 6106 netmask = 0xfffffe00 6107 hwaddr = "08:00:20:01:a6:a5" 6108@} 6109 6110netif ec0 @{ @} 6111@end example 6112 6113@node FSinfo config Option, FSinfo arch Option, FSinfo netif Option, FSinfo host attributes 6114@comment node-name, next, previous, up 6115@subsection config Option 6116@cindex FSinfo config host attribute 6117@cindex config, FSinfo host attribute 6118 6119This option allows you to specify configuration variables for the 6120startup scripts (@file{rc} scripts). A simple string should immediately 6121follow the keyword. 6122 6123Example: 6124 6125@example 6126config "NFS_SERVER=true" 6127config "ZEPHYR=true" 6128@end example 6129 6130This option is currently unsupported. 6131 6132@node FSinfo arch Option, FSinfo os Option, FSinfo config Option, FSinfo host attributes 6133@comment node-name, next, previous, up 6134@subsection arch Option 6135@cindex FSinfo arch host attribute 6136@cindex arch, FSinfo host attribute 6137 6138This defines the architecture of the machine. For example: 6139 6140@example 6141arch = hp300 6142@end example 6143 6144This is intended to be of use when building architecture specific 6145mountmaps, however, the option is currently unsupported. 6146 6147@node FSinfo os Option, FSinfo cluster Option, FSinfo arch Option, FSinfo host attributes 6148@comment node-name, next, previous, up 6149@subsection os Option 6150@cindex FSinfo os host attribute 6151@cindex os, FSinfo host attribute 6152 6153This defines the operating system type of the host. For example: 6154 6155@example 6156os = hpux 6157@end example 6158 6159This information is used when creating the @file{fstab} files, for 6160example in choosing which format to use for the @file{fstab} entries 6161within the file. 6162 6163@node FSinfo cluster Option, , FSinfo os Option, FSinfo host attributes 6164@comment node-name, next, previous, up 6165@subsection cluster Option 6166@cindex FSinfo cluster host attribute 6167@cindex cluster, FSinfo host attribute 6168 6169This is used for specifying in which cluster the machine belongs. For 6170example: 6171 6172@example 6173cluster = "theory" 6174@end example 6175 6176The cluster is intended to be used when generating the automount maps, 6177although it is currently unsupported. 6178 6179@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions 6180@comment node-name, next, previous, up 6181@section @i{FSinfo} filesystems 6182@cindex FSinfo filesystems 6183 6184The list of physically attached filesystems follows the machine 6185attributes. These should define all the filesystems available from this 6186machine, whether exported or not. In addition to the device name, 6187filesystems have several attributes, such as filesystem type, mount 6188options, and @samp{fsck} pass number which are needed to generate 6189@file{fstab} entries. 6190 6191@example 6192filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; 6193 6194fs_data : fs_data_attr "=" @var{<string>} 6195 | mount 6196 ; 6197 6198fs_data_attr 6199 : "fstype" | "opts" | "passno" 6200 | "freq" | "dumpset" | "log" 6201 ; 6202@end example 6203 6204Here, @var{<device>} is the device name of the disk (for example, 6205@file{/dev/dsk/2s0}). The device name is used for building the mount 6206maps and for the @file{fstab} file. The attributes that can be 6207specified are shown in the following section. 6208 6209The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. 6210 6211@example 6212host dylan.doc.ic.ac.uk 6213 6214fs /dev/dsk/0s0 @{ 6215 fstype = swap 6216@} 6217 6218fs /dev/dsk/0s0 @{ 6219 fstype = hfs 6220 opts = rw,noquota,grpid 6221 passno = 0; 6222 freq = 1; 6223 mount / @{ @} 6224@} 6225 6226fs /dev/dsk/1s0 @{ 6227 fstype = hfs 6228 opts = defaults 6229 passno = 1; 6230 freq = 1; 6231 mount /usr @{ 6232 local @{ 6233 exportfs "dougal eden dylan zebedee brian" 6234 volname /nfs/hp300/local 6235 @} 6236 @} 6237@} 6238 6239fs /dev/dsk/2s0 @{ 6240 fstype = hfs 6241 opts = defaults 6242 passno = 1; 6243 freq = 1; 6244 mount default @{ 6245 exportfs "toytown_clients hangers_on" 6246 volname /home/dylan/dk2 6247 @} 6248@} 6249 6250fs /dev/dsk/3s0 @{ 6251 fstype = hfs 6252 opts = defaults 6253 passno = 1; 6254 freq = 1; 6255 mount default @{ 6256 exportfs "toytown_clients hangers_on" 6257 volname /home/dylan/dk3 6258 @} 6259@} 6260 6261fs /dev/dsk/5s0 @{ 6262 fstype = hfs 6263 opts = defaults 6264 passno = 1; 6265 freq = 1; 6266 mount default @{ 6267 exportfs "toytown_clients hangers_on" 6268 volname /home/dylan/dk5 6269 @} 6270@} 6271@end example 6272 6273@menu 6274* FSinfo fstype Option:: FSinfo filesystems fstype. 6275* FSinfo opts Option:: FSinfo filesystems opts. 6276* FSinfo passno Option:: FSinfo filesystems passno. 6277* FSinfo freq Option:: FSinfo filesystems freq. 6278* FSinfo mount Option:: FSinfo filesystems mount. 6279* FSinfo dumpset Option:: FSinfo filesystems dumpset. 6280* FSinfo log Option:: FSinfo filesystems log. 6281@end menu 6282 6283@node FSinfo fstype Option, FSinfo opts Option, , FSinfo filesystems 6284@comment node-name, next, previous, up 6285@subsection fstype Option 6286@cindex FSinfo fstype filesystems option 6287@cindex fstype, FSinfo filesystems option 6288@cindex export, FSinfo special fstype 6289 6290This specifies the type of filesystem being declared and will be placed 6291into the @file{fstab} file as is. The value of this option will be 6292handed to @code{mount} as the filesystem type---it should have such 6293values as @code{4.2}, @code{nfs} or @code{swap}. The value is not 6294examined for correctness. 6295 6296There is one special case. If the filesystem type is specified as 6297@samp{export} then the filesystem information will not be added to the 6298host's @file{fstab} information, but it will still be visible on the 6299network. This is useful for defining hosts which contain referenced 6300volumes but which are not under full control of @i{FSinfo}. 6301 6302Example: 6303 6304@example 6305fstype = swap 6306@end example 6307 6308@node FSinfo opts Option, FSinfo passno Option, FSinfo fstype Option, FSinfo filesystems 6309@comment node-name, next, previous, up 6310@subsection opts Option 6311@cindex FSinfo opts filesystems option 6312@cindex opts, FSinfo filesystems option 6313 6314This defines any options that should be given to @b{mount}(8) in the 6315@file{fstab} file. For example: 6316 6317@example 6318opts = rw,nosuid,grpid 6319@end example 6320 6321@node FSinfo passno Option, FSinfo freq Option, FSinfo opts Option, FSinfo filesystems 6322@comment node-name, next, previous, up 6323@subsection passno Option 6324@cindex FSinfo passno filesystems option 6325@cindex passno, FSinfo filesystems option 6326 6327This defines the @b{fsck}(8) pass number in which to check the 6328filesystem. This value will be placed into the @file{fstab} file. 6329 6330Example: 6331 6332@example 6333passno = 1 6334@end example 6335 6336@node FSinfo freq Option, FSinfo mount Option, FSinfo passno Option, FSinfo filesystems 6337@comment node-name, next, previous, up 6338@subsection freq Option 6339@cindex FSinfo freq filesystems option 6340@cindex freq, FSinfo filesystems option 6341 6342This defines the interval (in days) between dumps. The value is placed 6343as is into the @file{fstab} file. 6344 6345Example: 6346 6347@example 6348freq = 3 6349@end example 6350 6351@node FSinfo mount Option, FSinfo dumpset Option, FSinfo freq Option, FSinfo filesystems 6352@comment node-name, next, previous, up 6353@subsection mount Option 6354@cindex FSinfo mount filesystems option 6355@cindex mount, FSinfo filesystems option 6356@cindex exportfs, FSinfo mount option 6357@cindex volname, FSinfo mount option 6358@cindex sel, FSinfo mount option 6359 6360This defines the mountpoint at which to place the filesystem. If the 6361mountpoint of the filesystem is specified as @code{default}, then the 6362filesystem will be mounted in the automounter's tree under its volume 6363name and the mount will automatically be inherited by the automounter. 6364 6365Following the mountpoint, namespace information for the filesystem may 6366be described. The options that can be given here are @code{exportfs}, 6367@code{volname} and @code{sel}. 6368 6369The format is: 6370 6371@example 6372mount : "mount" vol_tree ; 6373 6374vol_tree : @i{list(}vol_tree_attr@i{)} ; 6375 6376vol_tree_attr 6377 : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; 6378 6379vol_tree_info 6380 : "exportfs" @var{<export-data>} 6381 | "volname" @var{<volname>} 6382 | "sel" @var{<selector-list>} 6383 ; 6384@end example 6385 6386Example: 6387 6388@example 6389mount default @{ 6390 exportfs "dylan dougal florence zebedee" 6391 volname /vol/andrew 6392@} 6393@end example 6394 6395In the above example, the filesystem currently being declared will have 6396an entry placed into the @file{exports} file allowing the filesystem to 6397be exported to the machines @code{dylan}, @code{dougal}, @code{florence} 6398and @code{zebedee}. The volume name by which the filesystem will be 6399referred to remotely, is @file{/vol/andrew}. By declaring the 6400mountpoint to be @code{default}, the filesystem will be mounted on the 6401local machine in the automounter tree, where @i{Amd} will automatically 6402inherit the mount as @file{/vol/andrew}.@refill 6403 6404@table @samp 6405@item exportfs 6406a string defining which machines the filesystem may be exported to. 6407This is copied, as is, into the @file{exports} file---no sanity checking 6408is performed on this string.@refill 6409 6410@item volname 6411a string which declares the remote name by which to reference the 6412filesystem. The string is entered into a dictionary and allows you to 6413refer to this filesystem in other places by this volume name.@refill 6414 6415@item sel 6416a string which is placed into the automounter maps as a selector for the 6417filesystem.@refill 6418 6419@end table 6420 6421@node FSinfo dumpset Option, FSinfo log Option, FSinfo mount Option, FSinfo filesystems 6422@comment node-name, next, previous, up 6423@subsection dumpset Option 6424@cindex FSinfo dumpset filesystems option 6425@cindex dumpset, FSinfo filesystems option 6426 6427This provides support for Imperial College's local file backup tools and 6428is not documented further here. 6429 6430@node FSinfo log Option, , FSinfo dumpset Option, FSinfo filesystems 6431@comment node-name, next, previous, up 6432@subsection log Option 6433@cindex FSinfo log filesystems option 6434@cindex log, FSinfo filesystems option 6435 6436Specifies the log device for the current filesystem. This is ignored if 6437not required by the particular filesystem type. 6438 6439@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions 6440@comment node-name, next, previous, up 6441@section @i{FSinfo} static mounts 6442@cindex FSinfo static mounts 6443@cindex Statically mounts filesystems, FSinfo 6444 6445Each host may also have a number of statically mounted filesystems. For 6446example, the host may be a diskless workstation in which case it will 6447have no @code{fs} declarations. In this case the @code{mount} 6448declaration is used to determine from where its filesystems will be 6449mounted. In addition to being added to the @file{fstab} file, this 6450information can also be used to generate a suitable @file{bootparams} 6451file.@refill 6452 6453@example 6454mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; 6455 6456localinfo : localinfo_attr @var{<string>} ; 6457 6458localinfo_attr 6459 : "as" 6460 | "from" 6461 | "fstype" 6462 | "opts" 6463 ; 6464@end example 6465 6466The filesystem specified to be mounted will be searched for in the 6467dictionary of volume names built when scanning the list of hosts' 6468definitions. 6469 6470The attributes have the following semantics: 6471@table @samp 6472@item from @var{machine} 6473mount the filesystem from the machine with the hostname of 6474@dfn{machine}.@refill 6475 6476@item as @var{mountpoint} 6477mount the filesystem locally as the name given, in case this is 6478different from the advertised volume name of the filesystem. 6479 6480@item opts @var{options} 6481native @b{mount}(8) options. 6482 6483@item fstype @var{type} 6484type of filesystem to be mounted. 6485@end table 6486 6487An example: 6488 6489@example 6490mount /export/exec/hp300/local as /usr/local 6491@end example 6492 6493If the mountpoint specified is either @file{/} or @file{swap}, the 6494machine will be considered to be booting off the net and this will be 6495noted for use in generating a @file{bootparams} file for the host which 6496owns the filesystems. 6497 6498@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo 6499@comment node-name, next, previous, up 6500@section Defining an @i{Amd} Mount Map in @i{FSinfo} 6501@cindex FSinfo automount definitions 6502@cindex Defining an Amd mount map, FSinfo 6503 6504The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining 6505all the automount trees. @i{FSinfo} takes all the definitions found and 6506builds one map for each top level tree. 6507 6508The automount tree is usually defined last. A single automount 6509configuration will usually apply to an entire management domain. One 6510@code{automount} declaration is needed for each @i{Amd} automount point. 6511@i{FSinfo} determines whether the automount point is @dfn{direct} 6512(@pxref{Direct Automount Filesystem}) or @dfn{indirect} 6513(@pxref{Top-level Filesystem}). Direct automount points are 6514distinguished by the fact that there is no underlying 6515@dfn{automount_tree}.@refill 6516 6517@example 6518automount : "automount" @i{opt(}auto_opts@i{)} automount_tree ; 6519 6520auto_opts : "opts" @var{<mount-options>} ; 6521 6522automount_tree 6523 : @i{list(}automount_attr@i{)} 6524 ; 6525 6526automount_attr 6527 : @var{<string>} "=" @var{<volname>} 6528 | @var{<string>} "->" @var{<symlink>} 6529 | @var{<string>} "@{" automount_tree "@}" 6530 ; 6531@end example 6532 6533If @var{<mount-options>} is given, then it is the string to be placed in 6534the maps for @i{Amd} for the @code{opts} option. 6535 6536A @dfn{map} is typically a tree of filesystems, for example @file{home} 6537normally contains a tree of filesystems representing other machines in 6538the network. 6539 6540A map can either be given as a name representing an already defined 6541volume name, or it can be a tree. A tree is represented by placing 6542braces after the name. For example, to define a tree @file{/vol}, the 6543following map would be defined: 6544 6545@example 6546automount /vol @{ @} 6547@end example 6548 6549Within a tree, the only items that can appear are more maps. 6550For example: 6551 6552@example 6553automount /vol @{ 6554 andrew @{ @} 6555 X11 @{ @} 6556@} 6557@end example 6558 6559In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} 6560and @file{/vol/X11} and a map entry will be generated for each. If the 6561volumes are defined more than once, then @i{FSinfo} will generate 6562a series of alternate entries for them in the maps.@refill 6563 6564Instead of a tree, either a link (@var{name} @code{->} 6565@var{destination}) or a reference can be specified (@var{name} @code{=} 6566@var{destination}). A link creates a symbolic link to the string 6567specified, without further processing the entry. A reference will 6568examine the destination filesystem and optimize the reference. For 6569example, to create an entry for @code{njw} in the @file{/homes} map, 6570either of the two forms can be used:@refill 6571 6572@example 6573automount /homes @{ 6574 njw -> /home/dylan/njw 6575@} 6576@end example 6577 6578or 6579 6580@example 6581automount /homes @{ 6582 njw = /home/dylan/njw 6583@} 6584@end example 6585 6586In the first example, when @file{/homes/njw} is referenced from @i{Amd}, 6587a link will be created leading to @file{/home/dylan/njw} and the 6588automounter will be referenced a second time to resolve this filename. 6589The map entry would be: 6590 6591@example 6592njw type:=link;fs:=/home/dylan/njw 6593@end example 6594 6595In the second example, the destination directory is analyzed and found 6596to be in the filesystem @file{/home/dylan} which has previously been 6597defined in the maps. Hence the map entry will look like: 6598 6599@example 6600njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw 6601@end example 6602 6603Creating only one symbolic link, and one access to @i{Amd}. 6604 6605@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo 6606@comment node-name, next, previous, up 6607@section @i{FSinfo} Command Line Options 6608@cindex FSinfo command line options 6609@cindex Command line options, FSinfo 6610 6611@i{FSinfo} is started from the command line by using the command: 6612 6613@example 6614fsinfo [@i{options}] @i{files} ... 6615@end example 6616 6617The input to @i{FSinfo} is a single set of definitions of machines and 6618automount maps. If multiple files are given on the command-line, then 6619the files are concatenated together to form the input source. The files 6620are passed individually through the C pre-processor before being parsed. 6621 6622Several options define a prefix for the name of an output file. If the 6623prefix is not specified no output of that type is produced. The suffix 6624used will correspond either to the hostname to which a file belongs, or 6625to the type of output if only one file is produced. Dumpsets and the 6626@file{bootparams} file are in the latter class. To put the output into 6627a subdirectory simply put a @file{/} at the end of the prefix, making 6628sure that the directory has already been made before running 6629@i{Fsinfo}. 6630 6631@menu 6632* -a FSinfo Option:: Amd automount directory: 6633* -b FSinfo Option:: Prefix for bootparams files. 6634* -d FSinfo Option:: Prefix for dumpset data files. 6635* -e FSinfo Option:: Prefix for exports files. 6636* -f FSinfo Option:: Prefix for fstab files. 6637* -h FSinfo Option:: Local hostname. 6638* -m FSinfo Option:: Prefix for automount maps. 6639* -q FSinfo Option:: Ultra quiet mode. 6640* -v FSinfo Option:: Verbose mode. 6641* -I FSinfo Option:: Define new #include directory. 6642* -D-FSinfo Option:: Define macro. 6643* -U FSinfo Option:: Undefine macro. 6644@end menu 6645 6646@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options 6647@comment node-name, next, previous, up 6648@subsection @code{-a} @var{autodir} 6649 6650Specifies the directory name in which to place the automounter's 6651mountpoints. This defaults to @file{/a}. Some sites have the autodir set 6652to be @file{/amd}, and this would be achieved by: 6653 6654@example 6655fsinfo -a /amd ... 6656@end example 6657 6658@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options 6659@comment node-name, next, previous, up 6660@subsection @code{-b} @var{bootparams} 6661@cindex bootparams, FSinfo prefix 6662 6663This specifies the prefix for the @file{bootparams} filename. If it is 6664not given, then the file will not be generated. The @file{bootparams} 6665file will be constructed for the destination machine and will be placed 6666into a file named @file{bootparams} and prefixed by this string. The 6667file generated contains a list of entries describing each diskless 6668client that can boot from the destination machine. 6669 6670As an example, to create a @file{bootparams} file in the directory 6671@file{generic}, the following would be used: 6672 6673@example 6674fsinfo -b generic/ ... 6675@end example 6676 6677@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options 6678@comment node-name, next, previous, up 6679@subsection @code{-d} @var{dumpsets} 6680@cindex dumpset, FSinfo prefix 6681 6682This specifies the prefix for the @file{dumpsets} file. If it is not 6683specified, then the file will not be generated. The file will be for 6684the destination machine and will be placed into a filename 6685@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is 6686for use by Imperial College's local backup system. 6687 6688For example, to create a @file{dumpsets} file in the directory @file{generic}, 6689then you would use the following: 6690 6691@example 6692fsinfo -d generic/ ... 6693@end example 6694 6695@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options 6696@comment node-name, next, previous, up 6697@subsection @code{-e} @var{exportfs} 6698@cindex exports, FSinfo prefix 6699 6700Defines the prefix for the @file{exports} files. If it is not given, 6701then the file will not be generated. For each machine defined in the 6702configuration files as having disks, an @file{exports} file is 6703constructed and given a filename determined by the name of the machine, 6704prefixed with this string. If a machine is defined as diskless, then no 6705@file{exports} file will be created for it. The files contain entries 6706for directories on the machine that may be exported to clients. 6707 6708Example: To create the @file{exports} files for each diskfull machine 6709and place them into the directory @file{exports}: 6710 6711@example 6712fsinfo -e exports/ ... 6713@end example 6714 6715@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options 6716@comment node-name, next, previous, up 6717@subsection @code{-f} @var{fstab} 6718@cindex fstab, FSinfo prefix 6719 6720This defines the prefix for the @file{fstab} files. The files will only 6721be created if this prefix is defined. For each machine defined in the 6722configuration files, a @file{fstab} file is created with the filename 6723determined by prefixing this string with the name of the machine. These 6724files contain entries for filesystems and partitions to mount at boot 6725time. 6726 6727Example, to create the files in the directory @file{fstabs}: 6728 6729@example 6730fsinfo -f fstabs/ ... 6731@end example 6732 6733@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options 6734@comment node-name, next, previous, up 6735@subsection @code{-h} @var{hostname} 6736@cindex hostname, FSinfo command line option 6737 6738Defines the hostname of the destination machine to process for. If this 6739is not specified, it defaults to the local machine name, as returned by 6740@b{gethostname}(2). 6741 6742Example: 6743 6744@example 6745fsinfo -h dylan.doc.ic.ac.uk ... 6746@end example 6747 6748@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options 6749@comment node-name, next, previous, up 6750@subsection @code{-m} @var{mount-maps} 6751@cindex maps, FSinfo command line option 6752 6753Defines the prefix for the automounter files. The maps will only be 6754produced if this prefix is defined. The mount maps suitable for the 6755network defined by the configuration files will be placed into files 6756with names calculated by prefixing this string to the name of each map. 6757 6758For example, to create the automounter maps and place them in the 6759directory @file{automaps}: 6760 6761@example 6762fsinfo -m automaps/ ... 6763@end example 6764 6765@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options 6766@comment node-name, next, previous, up 6767@subsection @code{-q} 6768@cindex quiet, FSinfo command line option 6769 6770Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and 6771only outputs any error messages which are generated. 6772 6773@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options 6774@comment node-name, next, previous, up 6775@subsection @code{-v} 6776@cindex verbose, FSinfo command line option 6777 6778Selects verbose mode. When this is activated, the program will display 6779more messages, and display all the information discovered when 6780performing the semantic analysis phase. Each verbose message is output 6781to @file{stdout} on a line starting with a @samp{#} character. 6782 6783@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options 6784@comment node-name, next, previous, up 6785@subsection @code{-D} @var{name}@i{[=defn]} 6786 6787Defines a symbol @dfn{name} for the preprocessor when reading the 6788configuration files. Equivalent to @code{#define} directive. 6789 6790@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options 6791@comment node-name, next, previous, up 6792@subsection @code{-I} @var{directory} 6793 6794This option is passed into the preprocessor for the configuration files. 6795It specifies directories in which to find include files 6796 6797@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options 6798@comment node-name, next, previous, up 6799@subsection @code{-U} @var{name} 6800 6801Removes any initial definition of the symbol @dfn{name}. Inverse of the 6802@code{-D} option. 6803 6804@node FSinfo errors, , FSinfo Command Line Options, FSinfo 6805@comment node-name, next, previous, up 6806@section Errors produced by @i{FSinfo} 6807@cindex FSinfo error messages 6808 6809The following table documents the errors and warnings which @i{FSinfo} may produce. 6810 6811@table @t 6812 6813@item " expected 6814Occurs if an unescaped newline is found in a quoted string. 6815 6816@item ambiguous mount: @var{volume} is a replicated filesystem 6817If several filesystems are declared as having the same volume name, they 6818will be considered replicated filesystems. To mount a replicated 6819filesystem statically, a specific host will need to be named, to say 6820which particular copy to try and mount, else this error will 6821result. 6822 6823@item can't open @var{filename} for writing 6824Occurs if any errors are encountered when opening an output file. 6825 6826@item cannot determine localname since volname @var{volume} is not uniquely defined 6827If a volume is replicated and an attempt is made to mount the filesystem 6828statically without specifying a local mountpoint, @i{FSinfo} cannot 6829calculate a mountpoint, as the desired pathname would be 6830ambiguous. 6831 6832@item @var{device} has duplicate exportfs data 6833Produced if the @samp{exportfs} option is used multiple times within the 6834same branch of a filesystem definition. For example, if you attempt to 6835set the @samp{exportfs} data at different levels of the mountpoint 6836directory tree. 6837 6838@item dump frequency for @var{host}:@var{device} is non-zero 6839Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6840or @samp{export} and the @samp{dump} option is set to a value greater 6841than zero. Swap devices should not be dumped. 6842 6843@item duplicate host @var{hostname}! 6844If a host has more than one definition. 6845 6846@item end of file within comment 6847A comment was unterminated before the end of one of the configuration 6848files. 6849 6850@item @var{filename}: cannot open for reading 6851If a file specified on the command line as containing configuration data 6852could not be opened. 6853 6854@item @var{filesystem} has a volname but no exportfs data 6855Occurs when a volume name is declared for a file system, but the string 6856specifying what machines the filesystem can be exported to is 6857missing. 6858 6859@item fs field "@var{field-name}" already set 6860Occurs when multiple definitions are given for one of the attributes of a 6861host's filesystem. 6862 6863@item host field "@var{field-name}" already set 6864If duplicate definitions are given for any of the fields with a host 6865definition. 6866 6867@item @var{host}:@var{device} has more than one mount point 6868Occurs if the mount option for a host's filesystem specifies multiple 6869trees at which to place the mountpoint. 6870 6871@item @var{host}:@var{device} has no mount point 6872Occurs if the @samp{mount} option is not specified for a host's 6873filesystem. 6874 6875@item @var{host}:@var{device} needs field "@var{field-name}" 6876Occurs when a filesystem is missing a required field. @var{field-name} could 6877be one of @samp{fstype}, @samp{opts}, @samp{passno} or 6878@samp{mount}. 6879 6880@item @var{host}:mount field specified for swap partition 6881Occurs if a mountpoint is given for a filesystem whose type is declared 6882to be @samp{swap}. 6883 6884@item malformed IP dotted quad: @var{address} 6885If the Internet address of an interface is incorrectly specified. An 6886Internet address definition is handled to @b{inet_addr}(3N) to see if it 6887can cope. If not, then this message will be displayed. 6888 6889@item malformed netmask: @var{netmask} 6890If the netmask cannot be decoded as though it were a hexadecimal number, 6891then this message will be displayed. It will typically be caused by 6892incorrect characters in the @var{netmask} value. 6893 6894@item mount field "@var{field-name}" already set 6895Occurs when a static mount has multiple definitions of the same field. 6896 6897@item mount tree field "@var{field-name}" already set 6898Occurs when the @var{field-name} is defined more than once during the 6899definition of a filesystems mountpoint. 6900 6901@item netif field @var{field-name} already set 6902Occurs if you attempt to define an attribute of an interface more than 6903once. 6904 6905@item network booting requires both root and swap areas 6906Occurs if a machine has mount declarations for either the root partition 6907or the swap area, but not both. You cannot define a machine to only 6908partially boot via the network. 6909 6910@item no disk mounts on @var{hostname} 6911If there are no static mounts, nor local disk mounts specified for a 6912machine, this message will be displayed. 6913 6914@item no volname given for @var{host}:@var{device} 6915Occurs when a filesystem is defined to be mounted on @file{default}, but 6916no volume name is given for the file system, then the mountpoint cannot 6917be determined. 6918 6919@item not allowed '/' in a directory name 6920Occurs when a pathname with multiple directory elements is specified as 6921the name for an automounter tree. A tree should only have one name at 6922each level. 6923 6924@item pass number for @var{host}:@var{device} is non-zero 6925Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6926or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices 6927should not be fsck'd. @xref{FSinfo fstype Option}. 6928 6929@item sub-directory @var{directory} of @var{directory-tree} starts with '/' 6930Within the filesystem specification for a host, if an element 6931@var{directory} of the mountpoint begins with a @samp{/} and it is not 6932the start of the tree. 6933 6934@item sub-directory of @var{directory-tree} is named "default" 6935@samp{default} is a keyword used to specify if a mountpoint should be 6936automatically calculated by @i{FSinfo}. If you attempt to specify a 6937directory name as this, it will use the filename of @file{default} but 6938will produce this warning. 6939 6940@item unknown \ sequence 6941Occurs if an unknown escape sequence is found inside a string. Within a 6942string, you can give the standard C escape sequences for strings, such 6943as newlines and tab characters. 6944 6945@item unknown directory attribute 6946If an unknown keyword is found while reading the definition of a host's 6947filesystem mount option. 6948 6949@item unknown filesystem attribute 6950Occurs if an unrecognized keyword is used when defining a host's 6951filesystems. 6952 6953@item unknown host attribute 6954Occurs if an unrecognized keyword is used when defining a host. 6955 6956@item unknown mount attribute 6957Occurs if an unrecognized keyword is found while parsing the list of 6958static mounts. 6959 6960@item unknown volname @var{volume} automounted @i{[} on @i{name} @i{]} 6961Occurs if @var{volume} is used in a definition of an automount map but the volume 6962name has not been declared during the host filesystem definitions. 6963 6964@item volname @var{volume} is unknown 6965Occurs if an attempt is made to mount or reference a volume name which 6966has not been declared during the host filesystem definitions. 6967 6968@item volname @var{volume} not exported from @var{machine} 6969Occurs if you attempt to mount the volume @var{volume} from a machine 6970which has not declared itself to have such a filesystem 6971available. 6972 6973@end table 6974 6975@c ################################################################ 6976@node Hlfsd, Assorted Tools, FSinfo, Top 6977@comment node-name, next, previous, up 6978@chapter Hlfsd 6979@pindex Hlfsd 6980@cindex Home-Link Filesystem 6981 6982@i{Hlfsd} is a daemon which implements a filesystem containing a 6983symbolic link to subdirectory within a user's home directory, depending 6984on the user which accessed that link. It was primarily designed to 6985redirect incoming mail to users' home directories, so that it can be read 6986from anywhere. It was designed and implemented by 6987@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} and 6988@email{dupuy AT cs.columbia.edu,Alexander Dupuy}, at the 6989@uref{http://www.cs.columbia.edu/,Computer Science Department} of 6990@uref{http://www.columbia.edu/,Columbia University}. A 6991@uref{http://www.fsl.cs.sunysb.edu/docs/hlfsd/hlfsd.html,paper} 6992on @i{Hlfsd} was presented at the Usenix LISA VII conference in 1993. 6993 6994@i{Hlfsd} operates by mounting itself as an NFS server for the directory 6995containing @i{linkname}, which defaults to @file{/hlfs/home}. Lookups 6996within that directory are handled by @i{Hlfsd}, which uses the 6997password map to determine how to resolve the lookup. The directory will 6998be created if it doesn't already exist. The symbolic link will be to 6999the accessing user's home directory, with @i{subdir} appended to it. If 7000not specified, @i{subdir} defaults to @file{.hlfsdir}. This directory 7001will also be created if it does not already exist. 7002 7003A @samp{SIGTERM} sent to @i{Hlfsd} will cause it to shutdown. A 7004@samp{SIGHUP} will flush the internal caches, and reload the password 7005map. It will also close and reopen the log file, to enable the original 7006log file to be removed or rotated. A @samp{SIGUSR1} will cause it to 7007dump its internal table of user IDs and home directories to the file 7008@file{/tmp/hlfsddump}. 7009 7010@menu 7011* Introduction to Hlfsd:: 7012* Background to Mail Delivery:: 7013* Using Hlfsd:: 7014@end menu 7015 7016@c ================================================================ 7017@node Introduction to Hlfsd, Background to Mail Delivery, Hlfsd, Hlfsd 7018@comment node-name, next, previous, up 7019@section Introduction to Hlfsd 7020@cindex Introduction to Hlfsd 7021@cindex Hlfsd; introduction 7022 7023Electronic mail has become one of the major applications for many 7024computer networks, and use of this service is expected to increase over 7025time, as networks proliferate and become faster. Providing a convenient 7026environment for users to read, compose, and send electronic mail has 7027become a requirement for systems administrators (SAs). 7028 7029Widely used methods for handling mail usually require users to be logged 7030into a designated ``home'' machine, where their mailbox files reside. 7031Only on that one machine can they read newly arrived mail. Since users 7032have to be logged into that system to read their mail, they often find 7033it convenient to run all of their other processes on that system as 7034well, including memory and CPU-intensive jobs. For example, in our 7035department, we have allocated and configured several multi-processor 7036servers to handle such demanding CPU/memory applications, but these were 7037underutilized, in large part due to the inconvenience of not being able 7038to read mail on those machines. (No home directories were located on 7039these designated CPU-servers, since we did not want NFS service for 7040users' home directories to have to compete with CPU-intensive jobs. At the 7041same time, we discouraged users from running demanding applications on 7042their home machines.) 7043 7044Many different solutions have been proposed to allow users to read their 7045mail on any host. However, all of these solutions fail in one or more 7046of several ways: 7047 7048@itemize @bullet 7049 7050@item 7051they introduce new single points of failure 7052 7053@item 7054they require using different mail transfer agents (MTAs) or user agents 7055(UAs) 7056 7057@item 7058they do not solve the problem for all cases, i.e. the solution is only 7059partially successful for a particular environment. 7060 7061@end itemize 7062 7063We have designed a simple filesystem, called the @dfn{Home-Link File 7064System}, to provide the ability to deliver mail to users' home 7065directories, without modification to mail-related applications. We have 7066endeavored to make it as stable as possible. Of great importance to us 7067was to make sure the HLFS daemon, @file{hlfsd} , would not hang under 7068any circumstances, and would take the next-best action when faced with 7069problems. Compared to alternative methods, @i{Hlfsd} is a stable, more 7070general solution, and easier to install/use. In fact, in some ways, we 7071have even managed to improve the reliability and security of mail 7072service. 7073 7074Our server implements a small filesystem containing a symbolic link 7075to a subdirectory of the invoking user's home directory, and named symbolic 7076links to users' mailbox files. 7077 7078The @i{Hlfsd} server finds out the @var{uid} of the process that is 7079accessing its mount point, and resolves the pathname component @samp{home} as a 7080symbolic link to a subdirectory within the home directory given by the 7081@var{uid}'s entry in the password file. If the @var{gid} of the process 7082that attempts to access a mailbox file is a special one (called 7083HLFS_GID), then the server maps the name of the @emph{next} pathname 7084component directly to the user's mailbox. This is necessary so that 7085access to a mailbox file by users other than the owner can succeed. The 7086server has safety features in case of failures such as hung filesystems 7087or home directory filesystems that are inaccessible or full. 7088 7089On most of our machines, mail gets delivered to the directory 7090@file{/var/spool/mail}. Many programs, including UAs, depend on that 7091path. @i{Hlfsd} creates a directory @file{/mail}, and mounts itself on 7092top of that directory. @i{Hlfsd} implements the path name component 7093called @samp{home}, pointing to a subdirectory of the user's home directory. 7094We have made @file{/var/spool/mail} a symbolic link to 7095@file{/mail/home}, so that accessing @file{/var/spool/mail} actually 7096causes access to a subdirectory within a user's home directory. 7097 7098The following table shows an example of how resolving the pathname 7099@file{/var/mail/@i{NAME}} to @file{/users/ezk/.mailspool/@i{NAME}} proceeds. 7100 7101@multitable {Resolving Component} {Pathname left to resolve} {Value if symbolic link} 7102 7103@item @b{Resolving Component} 7104@tab @b{Pathname left to resolve} 7105@tab @b{Value if symbolic link} 7106 7107@item @t{/} 7108@tab @t{var/mail/}@i{NAME} 7109 7110@item @t{var/} 7111@tab @t{mail/}@i{NAME} 7112 7113@item @t{mail}@@ 7114@tab @t{/mail/home/}@i{NAME} 7115@tab @t{mail}@@ -> @t{/mail/home} 7116 7117@item @t{/} 7118@tab @t{mail/home/}@i{NAME} 7119 7120@item @t{mail/} 7121@tab @t{home/}@i{NAME} 7122 7123@item @t{home}@@ 7124@tab @i{NAME} 7125@tab @t{home}@@ -> @t{/users/ezk/.mailspool} 7126 7127@item @t{/} 7128@tab @t{users/ezk/.mailspool/}@i{NAME} 7129 7130@item @t{users/} 7131@tab @t{ezk/.mailspool/}@i{NAME} 7132 7133@item @t{ezk/} 7134@tab @t{.mailspool/}@i{NAME} 7135 7136@item @t{.mailspool/} 7137@tab @i{NAME} 7138 7139@item @i{NAME} 7140 7141@end multitable 7142 7143@c ================================================================ 7144@node Background to Mail Delivery, Using Hlfsd, Introduction to Hlfsd, Hlfsd 7145@comment node-name, next, previous, up 7146@section Background to Mail Delivery 7147@cindex Background to Mail Delivery 7148@cindex Hlfsd; background 7149 7150This section provides an in-depth discussion of why available methods 7151for delivering mail to home directories are not as good as the one used 7152by @i{Hlfsd}. 7153 7154@menu 7155* Single-Host Mail Spool Directory:: 7156* Centralized Mail Spool Directory:: 7157* Distributed Mail Spool Service:: 7158* Why Deliver Into the Home Directory?:: 7159@end menu 7160 7161@c ---------------------------------------------------------------- 7162@node Single-Host Mail Spool Directory, Centralized Mail Spool Directory, Background to Mail Delivery, Background to Mail Delivery 7163@comment node-name, next, previous, up 7164@subsection Single-Host Mail Spool Directory 7165@cindex Single-Host Mail Spool Directory 7166 7167The most common method for mail delivery is for mail to be appended to a 7168mailbox file in a standard spool directory on the designated ``mail 7169home'' machine of the user. The greatest advantage of this method is 7170that it is the default method most vendors provide with their systems, 7171thus very little (if any) configuration is required on the SA's part. 7172All they need to set up are mail aliases directing mail to the host on 7173which the user's mailbox file is assigned. (Otherwise, mail is 7174delivered locally, and users find mailboxes on many machines.) 7175 7176As users become more sophisticated, and aided by windowing systems, they 7177find themselves logging in on multiple hosts at once, performing several 7178tasks concurrently. They ask to be able to read their mail on any host 7179on the network, not just the one designated as their ``mail home''. 7180 7181@c ---------------------------------------------------------------- 7182@node Centralized Mail Spool Directory, Distributed Mail Spool Service, Single-Host Mail Spool Directory, Background to Mail Delivery 7183@comment node-name, next, previous, up 7184@subsection Centralized Mail Spool Directory 7185@cindex Centralized Mail Spool Directory 7186 7187A popular method for providing mail readability from any host is to have 7188all mail delivered to a mail spool directory on a designated 7189``mail-server'' which is exported via NFS to all of the hosts on the 7190network. Configuring such a system is relatively easy. On most 7191systems, the bulk of the work is a one-time addition to one or two 7192configuration files in @file{/etc}. The file-server's spool directory 7193is then hard-mounted across every machine on the local network. In 7194small environments with only a handful of hosts this can be an 7195acceptable solution. In our department, with a couple of hundred active 7196hosts and thousands of mail messages processed daily, this was deemed 7197completely unacceptable, as it introduced several types of problems: 7198 7199@table @b 7200 7201@item Scalability and Performance 7202 7203As more and more machines get added to the network, more mail traffic 7204has to go over NFS to and from the mail-server. Users like to run 7205mail-watchers, and read their mail often. The stress on the shared 7206infrastructure increases with every user and host added; loads on the 7207mail server would most certainly be high since all mail delivery goes 7208through that one machine.@footnote{ Delivery via NFS-mounted filesystems 7209may require usage of @samp{rpc.lockd} and @samp{rpc.statd} to provide 7210distributed file-locking, both of which are widely regarded as unstable 7211and unreliable. Furthermore, this will degrade performance, as local 7212processes as well as remote @samp{nfsd} processes are kept busy.} This 7213leads to lower reliability and performance. To reduce the number of 7214concurrent connections between clients and the server host, some SAs 7215have resorted to automounting the mail-spool directory. But this 7216solution only makes things worse: since users often run mail watchers, 7217and many popular applications such as @samp{trn}, @samp{emacs}, 7218@samp{csh} or @samp{ksh} check periodically for new mail, the 7219automounted directory would be effectively permanently mounted. If it 7220gets unmounted automatically by the automounter program, it is most 7221likely to get mounted shortly afterwards, consuming more I/O resources 7222by the constant cycle of mount and umount calls. 7223 7224@item Reliability 7225 7226The mail-server host and its network connectivity must be very reliable. 7227Worse, since the spool directory has to be hard-mounted,@footnote{No SA 7228in their right minds would soft-mount read/write partitions --- the 7229chances for data loss are too great.} many processes which access the 7230spool directory (various shells, @samp{login}, @samp{emacs}, etc.) 7231would be hung as long as connectivity to the mail-server is severed. To 7232improve reliability, SAs may choose to backup the mail-server's spool 7233partition several times a day. This may make things worse since reading 7234or delivering mail while backups are in progress may cause backups to be 7235inconsistent; more backups consume more backup-media resources, and 7236increase the load on the mail-server host. 7237 7238@end table 7239 7240@c ---------------------------------------------------------------- 7241@node Distributed Mail Spool Service, Why Deliver Into the Home Directory?, Centralized Mail Spool Directory, Background to Mail Delivery 7242@comment node-name, next, previous, up 7243@subsection Distributed Mail Spool Service 7244@cindex Distributed Mail Spool Service 7245 7246Despite the existence of a few systems that support delivery to users' 7247home directories, mail delivery to home directories hasn't caught on. 7248We believe the main reason is that there are too many programs that 7249``know'' where mailbox files reside. Besides the obvious (the delivery 7250program @file{/bin/mail} and mail readers like @file{/usr/ucb/Mail}, 7251@samp{mush}, @samp{mm}, etc.), other programs that know mailbox location 7252are login, from, almost every shell, @samp{xbiff}, @samp{xmailbox}, and 7253even some programs not directly related to mail, such as @samp{emacs} 7254and @samp{trn}. Although some of these programs can be configured to 7255look in different directories with the use of environment variables and 7256other resources, many of them cannot. The overall porting work is 7257significant. 7258 7259Other methods that have yet to catch on require the use of a special 7260mail-reading server, such as IMAP or POP. The main disadvantage of 7261these systems is that UAs need to be modified to use these services --- 7262a long and involved task. That is why they are not popular at this 7263time. 7264 7265Several other ideas have been proposed and even used in various 7266environments. None of them is robust. They are mostly very 7267specialized, inflexible, and do not extend to the general case. Some of 7268the ideas are plain bad, potentially leading to lost or corrupt mail: 7269 7270@table @b 7271 7272@item automounters 7273 7274Using an automounter such as @i{Amd} to provide a set of symbolic links 7275from the normal spool directory to user home directories is not 7276sufficient. UAs rename, unlink, and recreate the mailbox as a regular 7277file, therefore it must be a real file, not a symbolic link. 7278Furthermore, it must reside in a real directory which is writable by the 7279UAs and MTAs. This method may also require populating 7280@file{/var/spool/mail} with symbolic links and making sure they are 7281updated. Making @i{Amd} manage that directory directly fails, since 7282many various lock files need to be managed as well. Also, @i{Amd} does 7283not provide all of the NFS operations which are required to write mail 7284such as write, create, remove, and unlink. 7285 7286@item @code{$MAIL} 7287 7288Setting this variable to an automounted directory pointing to the user's 7289mail spool host only solves the problem for those programs which know 7290and use @code{$MAIL}. Many programs don't, therefore this solution is partial 7291and of limited flexibility. Also, it requires the SAs or the users to 7292set it themselves --- an added level of inconvenience and possible 7293failures. 7294 7295@item @t{/bin/mail} 7296 7297Using a different mail delivery agent could be the solution. One such 7298example is @samp{hdmail}. However, @samp{hdmail} still requires 7299modifying all UAs, the MTA's configuration, installing new daemons, and 7300changing login scripts. This makes the system less upgradable or 7301compatible with others, and adds one more complicated system for SAs to 7302deal with. It is not a complete solution because it still requires each 7303user have their @code{$MAIL} variable setup correctly, and that every program 7304use this variable. 7305 7306@end table 7307 7308@c ---------------------------------------------------------------- 7309@node Why Deliver Into the Home Directory?, , Distributed Mail Spool Service, Background to Mail Delivery 7310@comment node-name, next, previous, up 7311@subsection Why Deliver Into the Home Directory? 7312@cindex Why Deliver Into the Home Directory? 7313@cindex Hlfsd; Why Deliver Into the Home Directory? 7314 7315There are several major reasons why SAs might want to deliver mail 7316directly into the users' home directories: 7317 7318@table @b 7319 7320@item Location 7321 7322Many mail readers need to move mail from the spool directory to the 7323user's home directory. It speeds up this operation if the two are on 7324the same filesystem. If for some reason the user's home directory is 7325inaccessible, it isn't that useful to be able to read mail, since there 7326is no place to move it to. In some cases, trying to move mail to a 7327non-existent or hung filesystem may result in mail loss. 7328 7329@item Distribution 7330 7331Having all mail spool directories spread among the many more filesystems 7332minimizes the chances that complete environments will grind to a halt 7333when a single server is down. It does increase the chance that there 7334will be someone who is not able to read their mail when a machine is 7335down, but that is usually preferred to having no one be able to read 7336their mail because a centralized mail server is down. The problem of 7337losing some mail due to the (presumably) higher chances that a user's 7338machine is down is minimized in HLFS. 7339 7340@item Security 7341 7342Delivering mail to users' home directories has another advantage --- 7343enhanced security and privacy. Since a shared system mail spool 7344directory has to be world-readable and searchable, any user can see 7345whether other users have mail, when they last received new mail, or when 7346they last read their mail. Programs such as @samp{finger} display this 7347information, which some consider an infringement of privacy. While it 7348is possible to disable this feature of @samp{finger} so that remote 7349users cannot see a mailbox file's status, this doesn't prevent local 7350users from getting the information. Furthermore, there are more 7351programs which make use of this information. In shared environments, 7352disabling such programs has to be done on a system-wide basis, but with 7353mail delivered to users' home directories, users less concerned with 7354privacy who do want to let others know when they last received or read 7355mail can easily do so using file protection bits. 7356 7357@c Lastly, on systems that do not export their NFS filesystem with 7358@c @t{anon=0}, superusers are less likely to snoop around others' mail, as 7359@c they become ``nobodies'' across NFS. 7360 7361@end table 7362 7363In summary, delivering mail to home directories provides users the 7364functionality sought, and also avoids most of the problems just 7365discussed. 7366 7367@c ================================================================ 7368@node Using Hlfsd, , Background to Mail Delivery, Hlfsd 7369@comment node-name, next, previous, up 7370@section Using Hlfsd 7371@cindex Using Hlfsd 7372@cindex Hlfsd; using 7373 7374@menu 7375* Controlling Hlfsd:: 7376* Hlfsd Options:: 7377* Hlfsd Files:: 7378@end menu 7379 7380@c ---------------------------------------------------------------- 7381@node Controlling Hlfsd, Hlfsd Options, Using Hlfsd, Using Hlfsd 7382@comment node-name, next, previous, up 7383@subsection Controlling Hlfsd 7384@cindex Controlling Hlfsd 7385@cindex Hlfsd; controlling 7386@pindex ctl-hlfsd 7387 7388Much the same way @i{Amd} is controlled by @file{ctl-amd}, so does 7389@i{Hlfsd} get controlled by the @file{ctl-hlfsd} script: 7390 7391@table @t 7392 7393@item ctl-hlfsd start 7394Start a new @i{Hlfsd}. 7395 7396@item ctl-hlfsd stop 7397Stop a running @i{Hlfsd}. 7398 7399@item ctl-hlfsd restart 7400Stop a running @i{Hlfsd}, wait for 10 seconds, and then start a new 7401one. It is hoped that within 10 seconds, the previously running 7402@i{Hlfsd} terminate properly; otherwise, starting a second one could 7403cause system lockup. 7404 7405@end table 7406 7407For example, on our systems, we start @i{Hlfsd} within @file{ctl-hlfsd} 7408as follows on Solaris 2 systems: 7409 7410@example 7411hlfsd -a /var/alt_mail -x all -l /var/log/hlfsd /mail/home .mailspool 7412@end example 7413 7414The directory @file{/var/alt_mail} is a directory in the root partition 7415where alternate mail will be delivered into, when it cannot be delivered 7416into the user's home directory. 7417 7418Normal mail gets delivered into @file{/var/mail}, but on our systems, 7419that is a symbolic link to @file{/mail/home}. @file{/mail} is managed 7420by @i{Hlfsd}, which creates a dynamic symlink named @samp{home}, 7421pointing to the subdirectory @file{.mailspool} @emph{within} the 7422accessing user's home directory. This results in mail which normally 7423should go to @file{/var/mail/@code{$USER}}, to go to 7424@file{@code{$HOME}/.mailspool/@code{$USER}}. 7425 7426@i{Hlfsd} does not create the @file{/var/mail} symlink. This needs to 7427be created (manually) once on each host, by the system administrators, 7428as follows: 7429 7430@example 7431mv /var/mail /var/alt_mail 7432ln -s /mail/home /var/mail 7433@end example 7434 7435@i{Hlfsd} also responds to the following signals: 7436 7437A @samp{SIGHUP} signal sent to @i{Hlfsd} will force it to reload the 7438password map immediately. 7439 7440A @samp{SIGUSR1} signal sent to @i{Hlfsd} will cause it to dump its 7441internal password map to the file @file{/usr/tmp/hlfsd.dump.XXXXXX}, 7442where @samp{XXXXXX} will be replaced by a random string generated by 7443@b{mktemp}(3) or (the more secure) @b{mkstemp}(3). 7444 7445@c ---------------------------------------------------------------- 7446@node Hlfsd Options, Hlfsd Files, Controlling Hlfsd, Using Hlfsd 7447@comment node-name, next, previous, up 7448@subsection Hlfsd Options 7449@cindex Hlfsd Options 7450@cindex Hlfsd; Options 7451 7452@table @t 7453 7454@item -a @var{alt_dir} 7455Alternate directory. The name of the directory to which the symbolic 7456link returned by @i{Hlfsd} will point, if it cannot access the home 7457directory of the user. This defaults to @file{/var/hlfs}. This 7458directory will be created if it doesn't exist. It is expected that 7459either users will read these files, or the system administrators will 7460run a script to resend this ``lost mail'' to its owner. 7461 7462@item -c @var{cache-interval} 7463Caching interval. @i{Hlfsd} will cache the validity of home directories 7464for this interval, in seconds. Entries which have been verified within 7465the last @var{cache-interval} seconds will not be verified again, since 7466the operation could be expensive, and the entries are most likely still 7467valid. After the interval has expired, @i{Hlfsd} will re-verify the 7468validity of the user's home directory, and reset the cache time-counter. 7469The default value for @var{cache-interval} is 300 seconds (5 minutes). 7470 7471@item -f 7472Force fast startup. This option tells @i{Hlfsd} to skip startup-time 7473consistency checks such as existence of mount directory, alternate spool 7474directory, symlink to be hidden under the mount directory, their 7475permissions and validity. 7476 7477@item -g @var{group} 7478Set the special group HLFS_GID to @var{group}. Programs such as 7479@file{/usr/ucb/from} or @file{/usr/sbin/in.comsat}, which access the 7480mailboxes of other users, must be setgid @samp{HLFS_GID} to work properly. The 7481default group is @samp{hlfs}. If no group is provided, and there is no 7482group @samp{hlfs}, this feature is disabled. 7483 7484@item -h 7485Help. Print a brief help message, and exit. 7486 7487@item -i @var{reload-interval} 7488Map-reloading interval. Each @var{reload-interval} seconds, @i{Hlfsd} 7489will reload the password map. @i{Hlfsd} needs the password map for the 7490UIDs and home directory pathnames. @i{Hlfsd} schedules a @samp{SIGALRM} to 7491reload the password maps. A @samp{SIGHUP} sent to @i{Hlfsd} will force it to 7492reload the maps immediately. The default value for 7493@var{reload-interval} is 900 seconds (15 minutes.) 7494 7495@item -l @var{logfile} 7496Specify a log file to which @i{Hlfsd} will record events. If 7497@var{logfile} is the string @samp{syslog} then the log messages will be 7498sent to the system log daemon by @b{syslog}(3), using the @samp{LOG_DAEMON} 7499facility. This is also the default. 7500 7501@item -n 7502No verify. @i{Hlfsd} will not verify the validity of the symbolic link 7503it will be returning, or that the user's home directory contains 7504sufficient disk-space for spooling. This can speed up @i{Hlfsd} at the 7505cost of possibly returning symbolic links to home directories which are 7506not currently accessible or are full. By default, @i{Hlfsd} validates 7507the symbolic-link in the background. The @code{-n} option overrides the 7508meaning of the @code{-c} option, since no caching is necessary. 7509 7510@item -o @var{mount-options} 7511Mount options which @i{Hlfsd} will use to mount itself on top of 7512@var{dirname}. By default, @var{mount-options} is set to @samp{ro}. If 7513the system supports symbolic-link caching, default options are set 7514to @samp{ro,nocache}. 7515 7516@item -p 7517Print PID. Outputs the process-id of @i{Hlfsd} to standard output where 7518it can be saved into a file. 7519 7520@item -v 7521Version. Displays version information to standard error. 7522 7523@item -x @var{log-options} 7524Specify run-time logging options. The options are a comma separated 7525list chosen from: @samp{fatal}, @samp{error}, @samp{user}, @samp{warn}, @samp{info}, @samp{map}, @samp{stats}, @samp{all}. 7526 7527@item -C 7528Force @i{Hlfsd} to run on systems that cannot turn off the NFS 7529attribute-cache. Use of this option on those systems is discouraged, as 7530it may result in loss or misdelivery of mail. The option is ignored on 7531systems that can turn off the attribute-cache. 7532 7533@item -D @var{log-options} 7534Select from a variety of debugging options. Prefixing an option with 7535the string @samp{no} reverses the effect of that option. Options are 7536cumulative. The most useful option is @samp{all}. Since this option is 7537only used for debugging other options are not documented here. A fuller 7538description is available in the program source. 7539 7540@item -P @var{password-file} 7541Read the user-name, user-id, and home directory information from the 7542file @var{password-file}. Normally, @i{Hlfsd} will use @b{getpwent}(3) 7543to read the password database. This option allows you to override the 7544default database, and is useful if you want to map users' mail files to 7545a directory other than their home directory. Only the username, uid, 7546and home-directory fields of the file @var{password-file} are read and 7547checked. All other fields are ignored. The file @var{password-file} 7548must otherwise be compliant with Unix Version 7 colon-delimited format 7549@b{passwd}(4). 7550 7551@end table 7552 7553@c ---------------------------------------------------------------- 7554@node Hlfsd Files, , Hlfsd Options, Using Hlfsd 7555@comment node-name, next, previous, up 7556@subsection Hlfsd Files 7557@cindex Hlfsd Files 7558@cindex Hlfsd; Files 7559 7560The following files are used by @i{Hlfsd}: 7561 7562@table @file 7563 7564@item /hlfs 7565directory under which @i{Hlfsd} mounts itself and manages the symbolic 7566link @file{home}. 7567 7568@item .hlfsdir 7569default sub-directory in the user's home directory, to which the 7570@file{home} symbolic link returned by @i{Hlfsd} points. 7571 7572@item /var/hlfs 7573directory to which @file{home} symbolic link returned by @i{Hlfsd} 7574points if it is unable to verify the that user's home directory is 7575accessible. 7576 7577@item /usr/tmp/hlfsd.dump.XXXXXX 7578file to which @i{Hlfsd} will dump its internal password map when it 7579receives the @samp{SIGUSR1} signal. @samp{XXXXXX} will be replaced by 7580a random string generated by @b{mktemp}(3) or (the more secure) 7581@b{mkstemp}(3). 7582 7583@end table 7584 7585For discussion on other files used by @i{Hlfsd}, see @xref{lostaltmail}, and 7586@ref{lostaltmail.conf-sample}. 7587 7588@c ################################################################ 7589@node Assorted Tools, Examples, Hlfsd, Top 7590@comment node-name, next, previous, up 7591@chapter Assorted Tools 7592@cindex Assorted Tools 7593 7594The following are additional utilities and scripts included with 7595am-utils, and get installed. 7596 7597@menu 7598* am-eject:: 7599* amd.conf-sample:: 7600* amd2ldif:: 7601* amd2sun:: 7602* automount2amd:: 7603* ctl-amd:: 7604* ctl-hlfsd:: 7605* fix-amd-map:: 7606* fixmount:: 7607* fixrmtab:: 7608* lostaltmail:: 7609* lostaltmail.conf-sample:: 7610* mk-amd-map:: 7611* pawd:: 7612* redhat-ctl-amd:: 7613* wait4amd:: 7614* wait4amd2die:: 7615* wire-test:: 7616@end menu 7617 7618@c ---------------------------------------------------------------- 7619@node am-eject, amd.conf-sample, Assorted Tools, Assorted Tools 7620@comment node-name, next, previous, up 7621@section am-eject 7622@pindex am-eject 7623 7624A shell script unmounts a floppy or CD-ROM that is automounted, and 7625then attempts to eject the removable device. 7626 7627@c ---------------------------------------------------------------- 7628@node amd.conf-sample, amd2ldif, am-eject, Assorted Tools 7629@comment node-name, next, previous, up 7630@section amd.conf-sample 7631@pindex amd.conf-sample 7632 7633A sample @i{Amd} configuration file. @xref{Amd Configuration File}. 7634 7635@c ---------------------------------------------------------------- 7636@node amd2ldif, amd2sun, amd.conf-sample, Assorted Tools 7637@comment node-name, next, previous, up 7638@section amd2ldif 7639@pindex amd2ldif 7640 7641A script to convert @i{Amd} maps to LDAP input files. Use it as follows: 7642 7643@example 7644amd2ldif @i{mapname} @i{base} < @i{amd.mapfile} > @i{mapfile.ldif} 7645@end example 7646 7647@c ---------------------------------------------------------------- 7648@node amd2sun, automount2amd, amd2ldif, Assorted Tools 7649@comment node-name, next, previous, up 7650@section amd2sun 7651@pindex amd2sun 7652 7653A script to convert @i{Amd} maps to Sun Automounter maps. Use it as 7654follows 7655 7656@example 7657amd2sun < @i{amd.mapfile} > @i{auto_mapfile} 7658@end example 7659 7660@c ---------------------------------------------------------------- 7661@node automount2amd, ctl-amd, amd2sun, Assorted Tools 7662@comment node-name, next, previous, up 7663@section automount2amd 7664@pindex automount2amd 7665 7666A script to convert old Sun Automounter maps to @i{Amd} maps. 7667 7668Say you have the Sun automount file @i{auto.foo}, with these two lines: 7669@example 7670home earth:/home 7671moon -ro,intr server:/proj/images 7672@end example 7673Running 7674@example 7675automount2amd auto.foo > amd.foo 7676@end example 7677 7678will produce the @i{Amd} map @i{amd.foo} with this content: 7679 7680@example 7681# generated by automount2amd on Sat Aug 14 17:59:32 US/Eastern 1999 7682 7683/defaults \\ 7684 type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7685 7686home \ 7687 host==earth;type:=link;fs:=/home \\ 7688 rhost:=earth;rfs:=/home 7689 7690moon \ 7691 -addopts:=ro,intr \\ 7692 host==server;type:=link;fs:=/proj/images \\ 7693 rhost:=server;rfs:=/proj/images 7694@end example 7695 7696This perl script will use the following @i{/default} entry 7697@example 7698type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7699@end example 7700If you wish to override that, define the @b{$DEFAULTS} environment 7701variable, or modify the script. 7702 7703If you wish to generate Amd maps using the @i{hostd} (@pxref{hostd 7704Selector Variable}) @i{Amd} map syntax, then define the environment 7705variable @b{$DOMAIN} or modify the script. 7706 7707Note that automount2amd does not understand the syntax in newer Sun 7708Automount maps, those used with autofs. 7709 7710@c ---------------------------------------------------------------- 7711@node ctl-amd, ctl-hlfsd, automount2amd, Assorted Tools 7712@comment node-name, next, previous, up 7713@section ctl-amd 7714@pindex ctl-amd 7715 7716A script to start, stop, or restart @i{Amd}. Use it as follows: 7717 7718@table @t 7719@item ctl-amd start 7720Start a new @i{Amd} process. 7721@item ctl-amd stop 7722Stop the running @i{Amd}. 7723@item ctl-amd restart 7724Stop the running @i{Amd} (if any), safely wait for it to terminate, and 7725then start a new process --- only if the previous one died cleanly. 7726@end table 7727 7728@xref{Run-time Administration}, for more details. 7729 7730@c ---------------------------------------------------------------- 7731@node ctl-hlfsd, fix-amd-map, ctl-amd, Assorted Tools 7732@comment node-name, next, previous, up 7733@section ctl-hlfsd 7734@pindex ctl-hlfsd 7735 7736A script for controlling @i{Hlfsd}, much the same way @file{ctl-amd} 7737controls @i{Amd}. Use it as follows: 7738 7739@table @t 7740@item ctl-hlfsd start 7741Start a new @i{Hlfsd} process. 7742@item ctl-hlfsd stop 7743Stop the running @i{Hlfsd}. 7744@item ctl-hlfsd restart 7745Stop the running @i{Hlfsd} (if any), wait for 10 seconds for it to 7746terminate, and then start a new process --- only if the previous one 7747died cleanly. 7748@end table 7749 7750@xref{Hlfsd}, for more details. 7751 7752@c ---------------------------------------------------------------- 7753@node fix-amd-map, fixmount, ctl-hlfsd, Assorted Tools 7754@comment node-name, next, previous, up 7755@section fix-amd-map 7756@pindex fix-amd-map 7757 7758Am-utils changed some of the syntax and default values of some 7759variables. For example, the default value for @samp{$@{os@}} for 7760Solaris 2.x (aka SunOS 5.x) systems used to be @samp{sos5}, it is now 7761more automatically generated from @file{config.guess} and its value is 7762@samp{sunos5}. 7763 7764This script converts older @i{Amd} maps to new ones. Use it as follows: 7765 7766@example 7767fix-amd-map < @i{old.map} > @i{new.map} 7768@end example 7769 7770@c ---------------------------------------------------------------- 7771@node fixmount, fixrmtab, fix-amd-map, Assorted Tools 7772@comment node-name, next, previous, up 7773@section fixmount 7774@pindex fixmount 7775 7776@samp{fixmount} is a variant of @b{showmount}(8) that can delete bogus 7777mount entries in remote @b{mountd}(8) daemons. This is useful to 7778cleanup otherwise ever-accumulating ``junk''. Use it for example: 7779 7780@example 7781fixmount -r @i{host} 7782@end example 7783 7784See the online manual page for @samp{fixmount} for more details of its 7785usage. 7786 7787@c ---------------------------------------------------------------- 7788@node fixrmtab, lostaltmail, fixmount, Assorted Tools 7789@comment node-name, next, previous, up 7790@section fixrmtab 7791@pindex fixrmtab 7792 7793A script to invalidate @file{/etc/rmtab} entries for hosts named. Also 7794restart mountd for changes to take effect. Use it for example: 7795 7796@example 7797fixrmtab @i{host1} @i{host2} @i{...} 7798@end example 7799 7800@c ---------------------------------------------------------------- 7801@node lostaltmail, lostaltmail.conf-sample, fixrmtab, Assorted Tools 7802@comment node-name, next, previous, up 7803@section lostaltmail 7804@pindex lostaltmail 7805 7806A script used with @i{Hlfsd} to resend any ``lost'' mail. @i{Hlfsd} 7807redirects mail which cannot be written into the user's home directory to 7808an alternate directory. This is useful to continue delivering mail, 7809even if the user's file system was unavailable, full, or over quota. 7810But, the mail which gets delivered to the alternate directory needs to 7811be resent to its respective users. This is what the @samp{lostaltmail} 7812script does. 7813 7814Use it as follows: 7815 7816@example 7817lostaltmail 7818@end example 7819 7820This script needs a configuration file @samp{lostaltmail.conf} set up 7821with the right parameters to properly work. @xref{Hlfsd}, for more 7822details. 7823 7824@c ---------------------------------------------------------------- 7825@node lostaltmail.conf-sample, mk-amd-map, lostaltmail, Assorted Tools 7826@comment node-name, next, previous, up 7827@section lostaltmail.conf-sample 7828@pindex lostaltmail.conf-sample 7829@cindex lostaltmail; configuration file 7830 7831This is a text file with configuration parameters needed for the 7832@samp{lostaltmail} script. The script includes comments explaining each 7833of the configuration variables. See it for more information. Also 7834@pxref{Hlfsd} for general information. 7835 7836@c ---------------------------------------------------------------- 7837@node mk-amd-map, pawd, lostaltmail.conf-sample, Assorted Tools 7838@comment node-name, next, previous, up 7839@section mk-amd-map 7840@pindex mk-amd-map 7841 7842This program converts a normal @i{Amd} map file into an ndbm database 7843with the same prefix as the named file. Use it as follows: 7844 7845@example 7846mk-amd-map @i{mapname} 7847@end example 7848 7849@c ---------------------------------------------------------------- 7850@node pawd, redhat-ctl-amd, mk-amd-map, Assorted Tools 7851@comment node-name, next, previous, up 7852@section pawd 7853@pindex pawd 7854 7855@i{Pawd} is used to print the current working directory, adjusted to 7856reflect proper paths that can be reused to go through the automounter 7857for the shortest possible path. In particular, the path printed back 7858does not include any of @i{Amd}'s local mount points. Using them is 7859unsafe, because @i{Amd} may unmount managed file systems from the mount 7860points, and thus including them in paths may not always find the files 7861within. 7862 7863Without any arguments, @i{Pawd} will print the automounter adjusted 7864current working directory. With any number of arguments, it will print 7865the adjusted path of each one of the arguments. 7866 7867@c ---------------------------------------------------------------- 7868@node redhat-ctl-amd, wait4amd, pawd, Assorted Tools 7869@comment node-name, next, previous, up 7870@section redhat-ctl-amd 7871@pindex redhat-ctl-amd 7872 7873This script is similar to @i{ctl-amd} (@pxref{ctl-amd}) but is intended 7874for Red Hat Linux systems. You can safely copy @i{redhat-ctl-amd} onto 7875@file{/etc/rc.d/init.d/amd}. The script supplied by @i{Am-utils} is 7876usually better than the one provided by Red Hat, because the Red Hat 7877script does not correctly kill @i{Amd} processes: it is too quick to 7878kill the wrong processes, leaving stale or hung mount points behind. 7879 7880@c ---------------------------------------------------------------- 7881@node wait4amd, wait4amd2die, redhat-ctl-amd, Assorted Tools 7882@comment node-name, next, previous, up 7883@section wait4amd 7884@pindex wait4amd 7885 7886A script to wait for @i{Amd} to start on a particular host before 7887performing an arbitrary command. The command is executed repeatedly, 7888with 1 second intervals in between. You may interrupt the script using 7889@samp{^C} (or whatever keyboard sequence your terminal's @samp{intr} function 7890is bound to). 7891 7892Examples: 7893 7894@table @t 7895@item wait4amd saturn amq -p -h saturn 7896When @i{Amd} is up on host @samp{saturn}, get the process ID of that 7897running @i{Amd}. 7898@item wait4amd pluto rlogin pluto 7899Remote login to host @samp{pluto} when @i{Amd} is up on that host. It 7900is generally necessary to wait for @i{Amd} to properly start and 7901initialize on a remote host before logging in to it, because otherwise 7902user home directories may not be accessible across the network. 7903@item wait4amd pluto 7904A short-hand version of the previous command, since the most useful 7905reason for this script is to login to a remote host. I use it very 7906often when testing out new versions of @i{Amd}, and need to reboot hung 7907hosts. 7908@end table 7909 7910@c ---------------------------------------------------------------- 7911@node wait4amd2die, wire-test, wait4amd, Assorted Tools 7912@comment node-name, next, previous, up 7913@section wait4amd2die 7914@pindex wait4amd2die 7915 7916This script is used internally by @samp{ctl-amd} when used to restart 7917@i{Amd}. It waits for @i{Amd} to terminate. If it detected that 7918@i{Amd} terminated cleanly, this script will return an exist status of 7919zero. Otherwise, it will return a non-zero exit status. 7920 7921The script tests for @i{Amd}'s existence once every 5 seconds, six 7922times, for a total of 30 seconds. It will return a zero exist status as 7923soon as it detects that @i{Amd} dies. 7924 7925@c ---------------------------------------------------------------- 7926@node wire-test, , wait4amd2die, Assorted Tools 7927@comment node-name, next, previous, up 7928@section wire-test 7929@pindex wire-test 7930 7931A simple program to test if some of the most basic networking functions 7932in am-util's library @file{libamu} work. It also tests the combination 7933of NFS protocol and version number that are supported from the current 7934host, to a remote one. 7935 7936For example, in this test a machine which only supports NFS Version 2 is 7937contacting a remote host that can support the same version, but using 7938both UDP and TCP. If no host name is specified, @samp{wire-test} will 7939try @file{localhost}. 7940 7941@example 7942$ wire-test moisil 7943Network name is "mcl-lab-net.cs.columbia.edu" 7944Network number is "128.59.13" 7945Network name is "old-net.cs.columbia.edu" 7946Network number is "128.59.16" 7947My IP address is 0x7f000001. 7948NFS Version and protocol tests to host "moisil"... 7949 testing vers=2, proto="udp" -> found version 2. 7950 testing vers=3, proto="udp" -> failed! 7951 testing vers=2, proto="tcp" -> found version 2. 7952 testing vers=3, proto="tcp" -> failed! 7953@end example 7954 7955@c ################################################################ 7956@node Examples, Internals, Assorted Tools, Top 7957@comment node-name, next, previous, up 7958@chapter Examples 7959 7960@menu 7961* User Filesystems:: 7962* Home Directories:: 7963* Architecture Sharing:: 7964* Wildcard Names:: 7965* rwho servers:: 7966* /vol:: 7967* /defaults with selectors:: 7968* /tftpboot in a chroot-ed environment:: 7969 7970@end menu 7971 7972@node User Filesystems, Home Directories, Examples, Examples 7973@comment node-name, next, previous, up 7974@section User Filesystems 7975@cindex User filesystems 7976@cindex Mounting user filesystems 7977 7978With more than one fileserver, the directories most frequently 7979cross-mounted are those containing user home directories. A common 7980convention used at Imperial College is to mount the user disks under 7981@t{/home/}@i{machine}. 7982 7983Typically, the @samp{/etc/fstab} file contained a long list of entries 7984such as: 7985 7986@example 7987@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... 7988@end example 7989 7990for each fileserver on the network. 7991 7992There are numerous problems with this system. The mount list can become 7993quite large and some of the machines may be down when a system is 7994booted. When a new fileserver is installed, @samp{/etc/fstab} must be 7995updated on every machine, the mount directory created and the filesystem 7996mounted. 7997 7998In many environments most people use the same few workstations, but 7999it is convenient to go to a colleague's machine and access your own 8000files. When a server goes down, it can cause a process on a client 8001machine to hang. By minimizing the mounted filesystems to only include 8002those actively being used, there is less chance that a filesystem will 8003be mounted when a server goes down. 8004 8005The following is a short extract from a map taken from a research fileserver 8006at Imperial College. 8007 8008Note the entry for @samp{localhost} which is used for users such as 8009the operator (@samp{opr}) who have a home directory on most machine as 8010@samp{/home/localhost/opr}. 8011 8012@example 8013/defaults opts:=rw,intr,grpid,nosuid 8014charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8015 host==$@{key@};type:=ufs;dev:=/dev/xd0g 8016# 8017... 8018 8019# 8020localhost type:=link;fs:=$@{host@} 8021... 8022# 8023# dylan has two user disks so have a 8024# top directory in which to mount them. 8025# 8026dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8027# 8028dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8029 host==dylan;type:=ufs;dev:=/dev/dsk/2s0 8030# 8031dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8032 host==dylan;type:=ufs;dev:=/dev/dsk/5s0 8033... 8034# 8035toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8036 host==$@{key@};type:=ufs;dev:=/dev/xy1g 8037... 8038# 8039zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8040 host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 8041# 8042# Just for access... 8043# 8044gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8045gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} 8046# 8047gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} 8048... 8049@end example 8050 8051This map is shared by most of the machines listed so on those 8052systems any of the user disks is accessible via a consistent name. 8053@i{Amd} is started with the following command 8054 8055@example 8056amd /home amd.home 8057@end example 8058 8059Note that when mounting a remote filesystem, the @dfn{automounted} 8060mount point is referenced, so that the filesystem will be mounted if 8061it is not yet (at the time the remote @samp{mountd} obtains the file handle). 8062 8063@node Home Directories, Architecture Sharing, User Filesystems, Examples 8064@comment node-name, next, previous, up 8065@section Home Directories 8066@cindex Home directories 8067@cindex Example of mounting home directories 8068@cindex Mount home directories 8069 8070One convention for home directories is to locate them in @samp{/homes} 8071so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more 8072than a single fileserver it is convenient to spread user files across 8073several machines. All that is required is a mount-map which converts 8074login names to an automounted directory. 8075 8076Such a map might be started by the command: 8077 8078@example 8079amd /homes amd.homes 8080@end example 8081 8082where the map @samp{amd.homes} contained the entries: 8083 8084@example 8085/defaults type:=link # All the entries are of type:=link 8086jsp fs:=/home/charm/jsp 8087njw fs:=/home/dylan/dk5/njw 8088... 8089phjk fs:=/home/toytown/ai/phjk 8090sjv fs:=/home/ganymede/sjv 8091@end example 8092 8093Whenever a login name is accessed in @samp{/homes} a symbolic link 8094appears pointing to the real location of that user's home directory. In 8095this example, @samp{/homes/jsp} would appear to be a symbolic link 8096pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also 8097be an automount point. 8098 8099This system causes an extra level of symbolic links to be used. 8100Although that turns out to be relatively inexpensive, an alternative is 8101to directly mount the required filesystems in the @samp{/homes} 8102map. The required map is simple, but long, and its creation is best automated. 8103The entry for @samp{jsp} could be: 8104 8105@example 8106jsp -sublink:=$@{key@};rfs:=/home/charm \ 8107 host==charm;type:=ufs;dev:=/dev/xd0g \ 8108 host!=charm;type:=nfs;rhost:=charm 8109@end example 8110 8111This map can become quite big if it contains a large number of entries. 8112By combining two other features of @i{Amd} it can be greatly simplified. 8113 8114First the UFS partitions should be mounted under the control of 8115@samp{/etc/fstab}, taking care that they are mounted in the same place 8116that @i{Amd} would have automounted them. In most cases this would be 8117something like @samp{/a/@dfn{host}/home/@dfn{host}} and 8118@samp{/etc/fstab} on host @samp{charm} would have a line:@refill 8119 8120@example 8121/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 8122@end example 8123 8124The map can then be changed to: 8125 8126@example 8127/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid 8128jsp rhost:=charm;rfs:=/home/charm 8129njw rhost:=dylan;rfs:=/home/dylan/dk5 8130... 8131phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} 8132sjv rhost:=ganymede;rfs:=/home/ganymede 8133@end example 8134 8135This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} 8136not equal to @code{$@{rhost@}}). On the machine where the filesystem is 8137stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} 8138will construct a local filesystem mount point which corresponds to the 8139name of the locally mounted UFS partition. If @i{Amd} is started with 8140the @code{-r} option then instead of attempting an NFS mount, @i{Amd} will 8141simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If 8142@code{-r} is not used then a loopback NFS mount will be made. This type of 8143mount is known to cause a deadlock on many systems. 8144 8145@node Architecture Sharing, Wildcard Names, Home Directories, Examples 8146@comment node-name, next, previous, up 8147@section Architecture Sharing 8148@cindex Architecture sharing 8149@cindex Sharing a fileserver between architectures 8150@cindex Architecture dependent volumes 8151 8152@c %At the moment some of the research machines have sets of software 8153@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, 8154@c %system sources, local sources, prolog libraries and so on. 8155Often a filesystem will be shared by machines of different architectures. 8156Separate trees can be maintained for the executable images for each 8157architecture, but it may be more convenient to have a shared tree, 8158with distinct subdirectories. 8159 8160A shared tree might have the following structure on the fileserver (called 8161@samp{fserver} in the example): 8162 8163@example 8164local/tex 8165local/tex/fonts 8166local/tex/lib 8167local/tex/bin 8168local/tex/bin/sun3 8169local/tex/bin/sun4 8170local/tex/bin/hp9000 8171... 8172@end example 8173 8174In this example, the subdirectories of @samp{local/tex/bin} should be 8175hidden when accessed via the automount point (conventionally @samp{/vol}). 8176A mount-map for @samp{/vol} to achieve this would look like: 8177 8178@example 8179/defaults sublink:=$@{/key@};rhost:=fserver;type:=link 8180tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8181tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ 8182 host==fserver;fs:=/usr/local/tex 8183tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ 8184 host==fserver;fs:=/usr/local/tex 8185tex/bin -sublink:=$@{/key@}/$@{arch@} \ 8186 host!=fserver;type:=nfs;rfs:=/vol/tex \ 8187 host:=fserver;fs:=/usr/local/tex 8188@end example 8189 8190When @samp{/vol/tex/bin} is referenced, the current machine architecture 8191is automatically appended to the path by the @code{$@{sublink@}} 8192variable. This means that users can have @samp{/vol/tex/bin} in their 8193@samp{PATH} without concern for architecture dependencies. 8194 8195@node Wildcard Names, rwho servers, Architecture Sharing, Examples 8196@comment node-name, next, previous, up 8197@section Wildcard Names & Replicated Servers 8198 8199By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing 8200directory with additional entries. 8201The system files are usually mounted under @samp{/usr}. If instead, 8202@i{Amd} is mounted on @samp{/usr}, additional 8203names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. 8204A map to do this would have the form: 8205 8206@example 8207local type:=auto;fs:=local-map 8208share type:=auto;fs:=share-map 8209* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ 8210 rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 8211@end example 8212 8213Note that the assignment to @code{$@{sublink@}} is surrounded by double 8214quotes to prevent the incoming key from causing the map to be 8215misinterpreted. This map has the effect of directing any access to 8216@samp{/usr/local} or @samp{/usr/share} to another automount point. 8217 8218In this example, it is assumed that the @samp{/usr} files are replicated 8219on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. 8220For any references other than to @samp{local} and @samp{share} one of 8221the servers is used and a symbolic link to 8222@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is 8223returned once an appropriate filesystem has been mounted.@refill 8224 8225@node rwho servers, /vol, Wildcard Names, Examples 8226@comment node-name, next, previous, up 8227@section @samp{rwho} servers 8228@cindex rwho servers 8229@cindex Architecture specific mounts 8230@cindex Example of architecture specific mounts 8231 8232The @samp{/usr/spool/rwho} directory is a good candidate for automounting. 8233For efficiency reasons it is best to capture the rwho data on a small 8234number of machines and then mount that information onto a large number 8235of clients. The data written into the rwho files is byte order dependent 8236so only servers with the correct byte ordering can be used by a client: 8237 8238@example 8239/defaults type:=nfs 8240usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ 8241 rhost:=vaxA rhost:=vaxB \ 8242 || -rfs:=/usr/spool/rwho \ 8243 rhost:=sun4 rhost:=hp300 8244@end example 8245 8246@node /vol, /defaults with selectors, rwho servers, Examples 8247@comment node-name, next, previous, up 8248@section @samp{/vol} 8249@cindex /vol 8250@cindex Catch-all mount point 8251@cindex Generic volume name 8252 8253@samp{/vol} is used as a catch-all for volumes which do not have other 8254conventional names. 8255 8256Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. 8257The @samp{r+d} tree is used for new or experimental software that needs 8258to be available everywhere without installing it on all the fileservers. 8259Users wishing to try out the new software then simply include 8260@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill 8261 8262The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has 8263different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} 8264sub-directories for each machine architecture. For example, 8265@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory 8266@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed 8267a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be 8268returned.@refill 8269 8270@example 8271/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft 8272wp -opts:=rw,grpid,nosuid;rhost:=charm \ 8273 host==charm;type:=link;fs:=/usr/local/wp \ 8274 host!=charm;type:=nfs;rfs:=/vol/wp 8275... 8276# 8277src -opts:=rw,grpid,nosuid;rhost:=charm \ 8278 host==charm;type:=link;fs:=/usr/src \ 8279 host!=charm;type:=nfs;rfs:=/vol/src 8280# 8281r+d type:=auto;fs:=$@{map@};pref:=r+d/ 8282# per architecture bin,etc,lib&ucb... 8283r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8284r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8285r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8286r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8287r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8288r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8289r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8290# hades pictures 8291pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8292 host==thpfs;type:=link;fs:=/nbsd/pictures \ 8293 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures 8294# hades tools 8295hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8296 host==thpfs;type:=link;fs:=/nbsd/hades \ 8297 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades 8298# bsd tools for hp. 8299bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ 8300 host==thpfs;type:=link;fs:=/nbsd/bsd \ 8301 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd 8302@end example 8303 8304@node /defaults with selectors, /tftpboot in a chroot-ed environment, /vol, Examples 8305@comment node-name, next, previous, up 8306@section @samp{/defaults} with selectors 8307@cindex /defaults with selectors 8308@cindex selectors on default 8309 8310It is sometimes useful to have different defaults for a given map. To 8311achieve this, the @samp{/defaults} entry must be able to process normal 8312selectors. This feature is turned on by setting 8313@samp{selectors_in_defaults = yes} in the @file{amd.conf} file. 8314@xref{selectors_in_defaults Parameter}. 8315 8316In this example, I set different default NFS mount options for hosts 8317which are running over a slower network link. By setting a smaller size 8318for the NFS read and write buffer sizes, you can greatly improve remote 8319file service performance. 8320 8321@example 8322/defaults \ 8323 wire==slip-net;opts:=rw,intr,rsize=1024,wsize=1024,timeo=20,retrans=10 \ 8324 wire!=slip-net;opts:=rw,intr 8325@end example 8326 8327@node /tftpboot in a chroot-ed environment, , /defaults with selectors, Examples 8328@comment node-name, next, previous, up 8329@section @samp{/tftpboot} in a chroot-ed environment 8330@cindex /tftpboot in a chroot-ed environment 8331@cindex chroot; /tftpboot example 8332 8333In this complex example, we attempt to run an @i{Amd} process 8334@emph{inside} a chroot-ed environment. @samp{tftpd} (Trivial FTP) is 8335used to trivially retrieve files used to boot X-Terminals, Network 8336Printers, Network routers, diskless workstations, and other such 8337devices. For security reasons, @samp{tftpd} (and also @samp{ftpd}) 8338processes are run using the @b{chroot}(2) system call. This provides an 8339environment for these processes, where access to any files outside the 8340directory where the chroot-ed process runs is denied. 8341 8342For example, if you start @samp{tftpd} on your system with 8343 8344@example 8345chroot /tftpboot /usr/sbin/tftpd 8346@end example 8347 8348@noindent 8349then the @samp{tftpd} process will not be able to access any files 8350outside @file{/tftpboot}. This ensures that no one can retrieve files 8351such as @file{/etc/passwd} and run password crackers on it. 8352 8353Since the TFTP service works by broadcast, it is necessary to have at 8354least one TFTP server running on each subnet. If you have lots of files 8355that you need to make available for @samp{tftp}, and many subnets, it 8356could take significant amounts of disk space on each host serving them. 8357 8358A solution we implemented at Columbia University was to have every host 8359run @samp{tftpd}, but have those servers retrieve the boot files from 8360two replicated servers. Those replicated servers have special 8361partitions dedicated to the many network boot files. 8362 8363We start @i{Amd} as follows: 8364 8365@example 8366amd /tftpboot/.amd amd.tftpboot 8367@end example 8368 8369That is, @i{Amd} is serving the directory @file{/tftpboot/.amd}. The 8370@samp{tftp} server runs inside @file{/tftpboot} and is chroot-ed in that 8371directory too. The @file{amd.tftpboot} map looks like: 8372 8373@example 8374# 8375# Amd /tftpboot directory -> host map 8376# 8377 8378/defaults opts:=nosuid,ro,intr,soft;fs:=/tftpboot/import;type:=nfs 8379 8380tp host==lol;rfs:=/n/lol/import/tftpboot;type:=lofs \ 8381 host==ober;rfs:=/n/ober/misc/win/tftpboot;type:=lofs \ 8382 rhost:=ober;rfs:=/n/ober/misc/win/tftpboot \ 8383 rhost:=lol;rfs:=/n/lol/import/tftpboot 8384@end example 8385 8386To help understand this example, I list a few of the file entries that 8387are created inside @file{/tftpboot}: 8388 8389@example 8390$ ls -la /tftpboot 8391dr-xr-xr-x 2 root 512 Aug 30 23:11 .amd 8392drwxrwsr-x 12 root 512 Aug 30 08:00 import 8393lrwxrwxrwx 1 root 33 Feb 27 1997 adminpr.cfg -> ./.amd/tp/hplj/adminpr.cfg 8394lrwxrwxrwx 1 root 22 Dec 5 1996 tekxp -> ./.amd/tp/xterms/tekxp 8395lrwxrwxrwx 1 root 1 Dec 5 1996 tftpboot -> . 8396@end example 8397 8398Here is an explanation of each of the entries listed above: 8399 8400@table @code 8401 8402@item .amd 8403This is the @i{Amd} mount point. Note that you do not need to run a 8404separate @i{Amd} process for the TFTP service. The @b{chroot}(2) system 8405call only protects against file access, but the same process can still 8406serve files and directories inside and outside the chroot-ed 8407environment, because @i{Amd} itself was not run in chroot-ed mode. 8408 8409@item import 8410This is the mount point where @i{Amd} will mount the directories 8411containing the boot files. The map is designed so that remote 8412directories will be NFS mounted (even if they are already mounted 8413elsewhere), and local directories are loopback mounted (since they are 8414not accessible outside the chroot-ed @file{/tftpboot} directory). 8415 8416@item adminpr.cfg 8417@itemx tekxp 8418Two manually created symbolic links to directories @emph{inside} the 8419@i{Amd}-managed directory. The crossing of the component @file{tp} will 8420cause @i{Amd} to automount one of the remote replicas. Once crossed, 8421access to files inside proceeds as usual. The @samp{adminpr.cfg} is a 8422configuration file for an HP Laser-Jet 4si printer, and the @samp{tekxp} 8423is a directory for Tektronix X-Terminal boot files. 8424 8425@item tftpboot 8426This innocent looking symlink is important. Usually, when devices boot 8427via the TFTP service, they perform the @samp{get file} command to 8428retrieve @var{file}. However, some devices assume that @samp{tftpd} 8429does not run in a chroot-ed environment, but rather ``unprotected'', and 8430thus use a full pathname for files to retrieve, as in @samp{get 8431/tftpboot/file}. This symlink effectively strips out the leading 8432@file{/tftpboot/}. 8433 8434@end table 8435 8436@c ################################################################ 8437@node Internals, Acknowledgments & Trademarks, Examples, Top 8438@comment node-name, next, previous, up 8439@chapter Internals 8440 8441Note that there are more error and logging messages possible than are 8442listed here. Most of them are self-explanatory. Refer to the program 8443sources for more details on the rest. 8444 8445@menu 8446* Log Messages:: 8447@end menu 8448 8449@node Log Messages, , Internals, Internals 8450@comment node-name, next, previous, up 8451@section Log Messages 8452 8453In the following sections a brief explanation is given of some of the 8454log messages made by @i{Amd}. Where the message is in @samp{typewriter} 8455font, it corresponds exactly to the message produced by @i{Amd}. Words 8456in @dfn{italic} are replaced by an appropriate string. Variables, 8457@code{$@{@i{var}@}}, indicate that the value of the appropriate variable is 8458output. 8459 8460Log messages are either sent directly to a file, 8461or logged via the @b{syslog}(3) mechanism. @xref{log_file Parameter}. 8462In either case, entries in the file are of the form: 8463@example 8464@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} 8465@end example 8466 8467@menu 8468* Fatal errors:: 8469* Info messages:: 8470@end menu 8471 8472@node Fatal errors, Info messages, Log Messages, Log Messages 8473@comment node-name, next, previous, up 8474@subsection Fatal errors 8475 8476@i{Amd} attempts to deal with unusual events. Whenever it is not 8477possible to deal with such an error, @i{Amd} will log an appropriate 8478message and, if it cannot possibly continue, will either exit or abort. 8479These messages are selected by @samp{-x fatal} on the command line. 8480When @b{syslog}(3) is being used, they are logged with level 8481@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to 8482remain in a precarious state and should be restarted at the earliest 8483opportunity. 8484 8485@table @t 8486 8487@item Attempting to inherit not-a-filesystem 8488The prototype mount point created during a filesystem restart did not 8489contain a reference to the restarted filesystem. This error ``should 8490never happen''. 8491 8492@item Can't bind to domain "@i{NIS-domain}" 8493A specific NIS domain was requested on the command line, but no server 8494for that domain is available on the local net. 8495 8496@item Can't determine IP address of this host (@i{hostname}) 8497When @i{Amd} starts it determines its own IP address. If this lookup 8498fails then @i{Amd} cannot continue. The hostname it looks up is that 8499obtained returned by @b{gethostname}(2) system call. 8500 8501@item Can't find root file handle for @i{automount point} 8502@i{Amd} creates its own file handles for the automount points. When it 8503mounts itself as a server, it must pass these file handles to the local 8504kernel. If the filehandle is not obtainable the mount point is ignored. 8505This error ``should never happen''. 8506 8507@item Must be root to mount filesystems (euid = @i{euid}) 8508To prevent embarrassment, @i{Amd} makes sure it has appropriate system 8509privileges. This amounts to having an euid of 0. The check is made 8510after argument processing complete to give non-root users a chance to 8511access the @code{-v} option. 8512 8513@item No work to do - quitting 8514No automount points were given on the command line and so there is no 8515work to do. 8516 8517@item Out of memory 8518While attempting to malloc some memory, the memory space available to 8519@i{Amd} was exhausted. This is an unrecoverable error. 8520 8521@item Out of memory in realloc 8522While attempting to realloc some memory, the memory space available to 8523@i{Amd} was exhausted. This is an unrecoverable error. 8524 8525@item cannot create rpc/udp service 8526Either the NFS or AMQ endpoint could not be created. 8527 8528@item gethostname: @i{description} 8529The @b{gethostname}(2) system call failed during startup. 8530 8531@item host name is not set 8532The @b{gethostname}(2) system call returned a zero length host name. 8533This can happen if @i{Amd} is started in single user mode just after 8534booting the system. 8535 8536@item ifs_match called! 8537An internal error occurred while restarting a pre-mounted filesystem. 8538This error ``should never happen''. 8539 8540@item mount_afs: @i{description} 8541An error occurred while @i{Amd} was mounting itself. 8542 8543@item run_rpc failed 8544Somehow the main NFS server loop failed. This error ``should never 8545happen''. 8546 8547@item unable to free rpc arguments in amqprog_1 8548The incoming arguments to the AMQ server could not be free'ed. 8549 8550@item unable to free rpc arguments in nfs_program_1 8551The incoming arguments to the NFS server could not be free'ed. 8552 8553@item unable to register (AMQ_PROGRAM, AMQ_VERSION, udp) 8554The AMQ server could not be registered with the local portmapper or the 8555internal RPC dispatcher. 8556 8557@item unable to register (NFS_PROGRAM, NFS_VERSION, 0) 8558The NFS server could not be registered with the internal RPC dispatcher. 8559 8560@end table 8561 8562XXX: This section needs to be updated 8563 8564@node Info messages, , Fatal errors, Log Messages 8565@comment node-name, next, previous, up 8566@subsection Info messages 8567 8568@i{Amd} generates information messages to record state changes. These 8569messages are selected by @samp{-x info} on the command line. When 8570@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. 8571 8572The messages listed below can be generated and are in a format suitable 8573for simple statistical analysis. @dfn{mount-info} is the string 8574that is displayed by @dfn{Amq} in its mount information column and 8575placed in the system mount table. 8576 8577@table @t 8578 8579@item "@t{$@{@i{path}@}}" forcibly timed out 8580An automount point has been timed out by the @i{Amq} command. 8581 8582@item "@t{$@{@i{path}@}}" has timed out 8583No access to the automount point has been made within the timeout 8584period. 8585 8586@item Filehandle denied for "$@{@i{rhost}@}:$@{@i{rfs}@}" 8587The mount daemon refused to return a file handle for the requested filesystem. 8588 8589@item Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}": @i{description} 8590The mount daemon gave some other error for the requested filesystem. 8591 8592@item Finishing with status @i{exit-status} 8593@i{Amd} is about to exit with the given exit status. 8594 8595@item Re-synchronizing cache for map @t{$@{@i{map}@}} 8596The named map has been modified and the internal cache is being re-synchronized. 8597 8598@item file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored 8599An automount point has timed out, but the corresponding file server is 8600known to be down. This message is only produced once for each mount 8601point for which the server is down. 8602 8603@item file server @t{$@{@i{rhost}@}} type nfs is down 8604An NFS file server that was previously up is now down. 8605 8606@item file server @t{$@{@i{rhost}@}} type nfs is up 8607An NFS file server that was previously down is now up. 8608 8609@item file server @t{$@{@i{rhost}@}} type nfs starts down 8610A new NFS file server has been referenced and is known to be down. 8611 8612@item file server @t{$@{@i{rhost}@}} type nfs starts up 8613A new NFS file server has been referenced and is known to be up. 8614 8615@item mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out 8616Attempts to mount a filesystem for the given automount point have failed 8617to complete within 30 seconds. 8618 8619@item @i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8620A new file system has been mounted. 8621 8622@item @i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8623@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. 8624 8625@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} 8626A file system has been unmounted. 8627 8628@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}} 8629A file system of which only a sub-directory was in use has been unmounted. 8630 8631@item restarting @i{mount-info} on @t{$@{@i{fs}@}} 8632A pre-mounted file system has been noted. 8633 8634@end table 8635 8636XXX: This section needs to be updated 8637 8638@c ################################################################ 8639@node Acknowledgments & Trademarks, Index, Internals, Top 8640@comment node-name, next, previous, up 8641@unnumbered Acknowledgments & Trademarks 8642 8643Many thanks to the Am-Utils Users 8644mailing list through the months developing am-utils. These members 8645have contributed to the discussions, ideas, code and documentation, 8646and subjected their systems to alpha quality code. Special thanks go 8647to those @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors} who have 8648submitted patches, and especially to the maintainers: 8649 8650@itemize @bullet 8651@item @uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} 8652@item @email{ionut AT badula.org,Ion Badulescu} 8653@item @email{ro AT techfak.uni-bielefeld.de,Rainer Orth} 8654@item @email{nick.williams AT morganstanley.com,Nick Williams} 8655@end itemize 8656 8657Thanks to the Formal Methods Group at Imperial College for suffering 8658patiently while @i{Amd} was being developed on their machines. 8659 8660Thanks to the many people who have helped with the development of 8661@i{Amd}, especially Piete Brooks at the Cambridge University Computing 8662Lab for many hours of testing, experimentation and discussion. 8663 8664Thanks to the older @email{amd-workers AT majordomo.glue.umd.edu,Amd 8665Workers} mailing list (now defunct) members for many suggestions and 8666bug reports to @i{Amd}. 8667 8668@itemize @bullet 8669@item 8670@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital 8671Equipment Corporation. 8672@item 8673@b{AIX} and @b{IBM} are registered trademarks of International Business 8674Machines Corporation. 8675@item 8676@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun 8677Microsystems, Inc. 8678@item 8679@b{UNIX} is a registered trademark in the USA and other countries, 8680exclusively licensed through X/Open Company, Ltd. 8681@item 8682All other registered trademarks are owned by their respective owners. 8683@end itemize 8684 8685@c ################################################################ 8686@node Index, , Acknowledgments & Trademarks, Top 8687@comment node-name, next, previous, up 8688@unnumbered Index 8689 8690@printindex cp 8691 8692@contents 8693@bye 8694 8695@c ==================================================================== 8696@c ISPELL LOCAL WORDS: 8697@c LocalWords: setfilename amdref overfullrule settitle titlepage titlefont nz 8698@c LocalWords: authorfont vskip ifinfo iftex cindex unnumberedsec dfn xref vol 8699@c LocalWords: locationN pxref jpo nott concentrix Sjoerd sjoerd cwi Eitan vuw 8700@c LocalWords: Mizrotsky eitan shumuji dgux fpx scp hcx metcalf masala hlh OTS 8701@c LocalWords: Presnell srp cgl Trost trost ogi pyrOSx OSx tubsibr riscix iX 8702@c LocalWords: Piete pb Lindblad cjl ai umax utek xinu Mitchum D'Souza dsouza 8703@c LocalWords: mrc apu alliant aviion AViiON fps macII multimax tahoe vax emph 8704@c LocalWords: mapdefault valA valB valC YPTSDIR ETCDIR substr MAKEDBM YPDBDIR 8705@c LocalWords: NOPUSH njw dylan dk dylan njw anydir domN achilles mjh pref sel 8706@c LocalWords: gdef loc loc loc ldots autodir remopts rwho rwho styx styx yoyo 8707@c LocalWords: noindent gould rvdmount rvdunmount fserver mtmp unioned logfile 8708@c LocalWords: dmn esac phjk toytown toytown toytown toytown phjk RdDir RdLnk 8709@c LocalWords: volname attrs netif dougal inaddr hwaddr ec mountmaps passno xy 8710@c LocalWords: freq dumpset hfs brian florence localinfo fstabs automaps defn 8711@c LocalWords: localname fsck'd opr gummo sjv ganymede sjv fserv fserv fserv 8712@c LocalWords: vaxA vaxB wp thpfs nbsd asis ifs amqprog free'ed printindex gov 8713@c LocalWords: LocalWords syncodeindex Distrib bsdnet lanl AutoMounter acis ic 8714@c LocalWords: ac uk aix bsd Mullender nl il DG lcs hpux irix ucsf NeXT cse cl 8715@c LocalWords: mt FX hp ibm mips utils def def Domainname eg hostd getwd tmp 8716@c LocalWords: subsubsection rw grpid intr noconn nocto nodevs nosuid retrans 8717@c LocalWords: rsize tcp timeo nounmount utimeout DDEBUG nodaemon fd hostnames 8718@c LocalWords: pid Amd's pendry vangogh nfsx backoff stats nomap nostats CRIT 8719@c LocalWords: noinfo clustername RVD dsk dsk amq hostports osver statfs str 8720@c LocalWords: ou counter's amdmaps proj src tftpboot sh mv cd sbin ypcat inet 8721@c LocalWords: Getattr getattr localhost fhandles netmask fstype noquota addr 8722@c LocalWords: exportfs Dumpsets dumpsets pindex ldif fixmount fixrmtab euid 8723@c LocalWords: lostaltmail realloc netnumber itemx primnetnum primnetname ARG 8724@c LocalWords: subsnetname subsnetnum netgrp netgroup multitable Shlib dec osf 8725@c LocalWords: hppa pc bsdi freebsd netbsd openbsd ncr sysv rs acdirmax fsid 8726@c LocalWords: acdirmin acregmax acregmin actimeo dumbtimr nfsv noac noauto sd 8727@c LocalWords: nocache nodev noint nosub pgthresh posix rdonly suid symttl mfs 8728@c LocalWords: AMFS umapfs myftpdir unionfs es mapname mapfile mapfile slocal 8729@c LocalWords: mailspool saturn saturn notknown lol ober dr xr xr drwxrwsr cfg 8730@c LocalWords: lrwxrwxrwx adminpr hplj adminpr cfg tekxp xterms tekxp Dupuy tp 8731@c LocalWords: linkname hlfsddump dirname rmtab pluto rlogin direntry pg vr dn 8732@c LocalWords: maxmem hlfsdir xmailbox showmount cn amdmap amdmapName resvport 8733@c LocalWords: objectClass amdmapKey amdmapValue ln powerpc amdmapTimestamp ez 8734@c LocalWords: moisil FSinfo Libtool Unmounting sublink fileservers NullProc 8735@c LocalWords: gethostname mount's unmounts linkx remounts unmounting UAs SA's 8736@c LocalWords: mountpoint mountpoints unescaped UIDs util's overlayed uref EFS 8737@c LocalWords: serv maxgroups nfsl cachedir copt cfsadmin efs addopts fg ROMs 8738@c LocalWords: nointr extatt setchapternewpage columnfractions alphaev gnulibc 8739@c LocalWords: freebsdelf gnuoldld ifhtml defperm nodefperm norrip RRIP rrip 8740@c LocalWords: noversion attr XXXXXX netgrpd rh mkstemp uid gid noexec mntfs 8741@c LocalWords: nomnttab optionstr hrtime xdrtrace getpwd proplist redhat ctl 8742@c LocalWords: texinfo texi ib sp cartouche ified xlatecookie dircategory sc 8743@c LocalWords: AddInfo suse Novell softlookup ENOENT USB fullybrowsable LDAPv 8744@c LocalWords: amy ie xfffffe zebedee andrew diskfull hdmail searchable si 8745@c LocalWords: Orth ESTALE 8746