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