am-utils.texi revision 1.3
1\input texinfo @c -*-texinfo-*- 2@c $NetBSD: am-utils.texi,v 1.3 2009/03/20 20:30:52 christos Exp $ 3@c 4@c Copyright (c) 1997-2009 Erez Zadok 5@c Copyright (c) 1989 Jan-Simon Pendry 6@c Copyright (c) 1989 Imperial College of Science, Technology & Medicine 7@c Copyright (c) 1989 The Regents of the University of California. 8@c All rights reserved. 9@c 10@c This code is derived from software contributed to Berkeley by 11@c Jan-Simon Pendry at Imperial College, London. 12@c 13@c Redistribution and use in source and binary forms, with or without 14@c modification, are permitted provided that the following conditions 15@c are met: 16@c 1. Redistributions of source code must retain the above copyright 17@c notice, this list of conditions and the following disclaimer. 18@c 2. Redistributions in binary form must reproduce the above copyright 19@c notice, this list of conditions and the following disclaimer in the 20@c documentation and/or other materials provided with the distribution. 21@c 3. All advertising materials mentioning features or use of this software 22@c must display the following acknowledgment: 23@c This product includes software developed by the University of 24@c California, Berkeley and its contributors. 25@c 4. Neither the name of the University nor the names of its contributors 26@c may be used to endorse or promote products derived from this software 27@c without specific prior written permission. 28@c 29@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 30@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 31@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 32@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 33@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 34@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 35@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 36@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 37@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 38@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 39@c 40@c 41@c File: am-utils/doc/am-utils.texi 42@c 43@setfilename am-utils.info 44 45@include version.texi 46 47@c info directory entry 48@dircategory Administration 49@direntry 50* Am-utils: (am-utils). The Amd automounter suite of utilities 51@end direntry 52 53@settitle Am-utils (4.4BSD Automounter Utilities) 54@setchapternewpage odd 55 56@titlepage 57@title Am-utils (4.4BSD Automounter Utilities) 58@subtitle For version @value{VERSION}, @value{UPDATED} 59 60@author Erez Zadok 61(Originally by Jan-Simon Pendry and Nick Williams) 62 63@page 64Copyright @copyright{} 1997-2009 Erez Zadok 65@* 66Copyright @copyright{} 1989 Jan-Simon Pendry 67@* 68Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 69@* 70Copyright @copyright{} 1989 The Regents of the University of California. 71@sp 72All Rights Reserved. 73@vskip 1ex 74Permission to copy this document, or any portion of it, as 75necessary for use of this software is granted provided this 76copyright notice and statement of permission are included. 77@end titlepage 78@page 79 80@c Define a new index for options. 81@syncodeindex pg cp 82@syncodeindex vr cp 83 84@ifinfo 85 86@c ################################################################ 87@node Top, License, , (DIR) 88 89@b{Am-utils (4.4BSD Automounter Utilities) User Manual} 90@* 91For version @value{VERSION}, @value{UPDATED} 92 93@b{Erez Zadok} 94@* 95(Originally by Jan-Simon Pendry and Nick Williams) 96 97Copyright @copyright{} 1997-2009 Erez Zadok 98@* 99Copyright @copyright{} 1989 Jan-Simon Pendry 100@* 101Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 102@* 103Copyright @copyright{} 1989 The Regents of the University of California. 104@* 105All Rights Reserved. 106 107Permission to copy this document, or any portion of it, as 108necessary for use of this software is granted provided this 109copyright notice and statement of permission are included. 110 111Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd 112automounter, the Amq query and control program, the Hlfsd daemon, and 113other tools. This Info file describes how to use and understand the 114tools within Am-utils. 115@end ifinfo 116 117@menu 118* License:: Explains the terms and conditions for using 119 and distributing Am-utils. 120* Distrib:: How to get the latest Am-utils distribution. 121* AddInfo:: How to get additional information. 122* Intro:: An introduction to Automounting concepts. 123* History:: History of am-utils' development. 124* Overview:: An overview of Amd. 125* Supported Platforms:: Machines and Systems supported by Amd. 126* Mount Maps:: Details of mount maps. 127* Amd Command Line Options:: All the Amd command line options explained. 128* Filesystem Types:: The different mount types supported by Amd. 129* Amd Configuration File:: The amd.conf file syntax and meaning. 130* Run-time Administration:: How to start, stop and control Amd. 131* FSinfo:: The FSinfo filesystem management tool. 132* Hlfsd:: The Home-Link Filesystem server. 133* Assorted Tools:: Other tools which come with am-utils. 134* Examples:: Some examples showing how Amd might be used. 135* Internals:: Implementation details. 136* Acknowledgments & Trademarks:: Legal Notes. 137 138Indexes 139* Index:: An item for each concept. 140@end menu 141 142@iftex 143@unnumbered Preface 144 145This manual documents the use of the 4.4BSD automounter tool suite, 146which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is 147primarily a reference manual. While no tutorial exists, there are 148examples available. @xref{Examples}. 149 150This manual comes in two forms: the published form and the Info form. 151The Info form is for on-line perusal with the INFO program which is 152distributed along with GNU texinfo package (a version of which is 153available for GNU Emacs).@footnote{GNU packages can be found in 154@url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially 155the same text and are generated from a common source file, which is 156distributed with the @i{Am-utils} source. 157@end iftex 158 159@c ################################################################ 160@node License, Distrib, Top, Top 161@unnumbered License 162@cindex License Information 163 164@i{Am-utils} is not in the public domain; it is copyrighted and there are 165restrictions on its distribution. 166 167Redistribution and use in source and binary forms, with or without 168modification, are permitted provided that the following conditions are 169met: 170 171@enumerate 172 173@item 174Redistributions of source code must retain the above copyright notice, 175this list of conditions and the following disclaimer. 176 177@item 178Redistributions in binary form must reproduce the above copyright 179notice, this list of conditions and the following disclaimer in the 180documentation and/or other materials provided with the distribution. 181 182@item 183All advertising materials mentioning features or use of this software 184must display the following acknowledgment: 185 186@cartouche 187``This product includes software developed by the University of 188California, Berkeley and its contributors, as well as the Trustees of 189Columbia University.'' 190@end cartouche 191 192@item 193Neither the name of the University nor the names of its contributors may 194be used to endorse or promote products derived from this software 195without specific prior written permission. 196 197@end enumerate 198 199THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 200ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 201IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 202PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 203BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 204CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 205SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 206INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 207CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 208ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 209THE POSSIBILITY OF SUCH DAMAGE. 210 211@c ################################################################ 212@node Distrib, AddInfo, License, Top 213@unnumbered Source Distribution 214@cindex Source code distribution 215@cindex Obtaining the source code 216 217The @i{Am-utils} home page is located in 218@example 219@url{http://www.am-utils.org/} 220@end example 221 222You can get the latest distribution version of @i{Am-utils} from 223@example 224@url{ftp://ftp.am-utils.org/pub/am-utils/am-utils.tar.gz} 225@end example 226 227Additional alpha, beta, and release distributions are available in 228@example 229@url{ftp://ftp.am-utils.org/pub/am-utils/}. 230@end example 231 232Revision 5.2 was part of the 4.3BSD Reno distribution. 233 234Revision 5.3bsdnet, a late alpha version of 5.3, was part 235of the BSD network version 2 distribution 236 237Revision 6.0 was made independently by 238Erez Zadok at the Computer Science 239Department of @uref{http://www.cs.columbia.edu/,Columbia University}, 240as part of his 241@uref{http://www.fsl.cs.sunysb.edu/docs/zadok-thesis-proposal/,PhD 242thesis work}. Am-utils (especially version 6.1) continues to be 243developed and maintained at the 244@uref{http://www.cs.sunysb.edu/,Computer Science Department} of 245@uref{http://www.stonybrook.edu/,Stony Brook University}, as a service 246to the user community. 247 248 249@xref{History}, for more details. 250 251@c ################################################################ 252@node AddInfo, Intro, Distrib, Top 253@unnumbered Getting Additional Information 254@cindex Getting Additional Information 255 256@unnumberedsec Bug Reports 257@cindex Bug reports 258 259Before reporting a bug, see if it is a known one in the 260@uref{http://www.am-utils.org/docs/am-utils/BUGS.txt,bugs} file. 261 262If you find a problem and hopefully you can reproduce it, please 263describe it in detail and 264@uref{https://bugzilla.filesystems.org/,submit a bug report} via 265@uref{http://www.bugzilla.org/,Bugzilla}. Alternatively, you can send 266your bug report to the ``am-utils'' list (see 267@url{http://www.am-utils.org/} under ``Mailing Lists'') quoting the details 268of the release and your configuration. These details can be obtained 269by running the command @samp{amd -v}. It would greatly help if you 270could provide a reproducible procedure for detecting the bug you are 271reporting. 272 273Providing working patches is highly encouraged. Every patch 274incorporated, however small, will get its author an honorable mention in 275the @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors 276file}. 277 278@unnumberedsec Mailing Lists 279@cindex Mailing lists 280 281There are several mailing lists for people interested in keeping up-to-date 282with developments. 283 284@c ############### 285 286@enumerate 287 288@item 289The users mailing list, @samp{am-utils} is for 290 291@itemize @minus 292@item 293announcements of alpha and beta releases of am-utils 294@item 295reporting of bugs and patches 296@item 297discussions of new features for am-utils 298@item 299implementation and porting issues 300@end itemize 301 302To subscribe, visit @url{http://www.am-utils.org/} under ``Mailing 303Lists.'' After subscribing, you can post a message to this list. To 304avoid as much spam as possible, only subscribers to this list may post 305to it. 306 307Subscribers of @samp{am-utils} are most helpful if they have the time 308and resources to test new and development versions of amd, on as many 309different platforms as possible. They should also be prepared to 310learn and use the GNU Autoconf, Automake, and Libtool packages, as 311needed; and of course, become familiar with the complex code in the 312am-utils package. In other words, subscribers on this list should 313hopefully be able to contribute meaningfully to the development of 314amd. 315 316Note that this @samp{am-utils} list used to be called @samp{amd-dev} 317before January 1st, 2004. Please use the new name, @samp{am-utils}. 318 319@item 320The announcements mailing list, @samp{am-utils-announce} is for 321announcements only (mostly new releases). To subscribe, visit 322@url{http://www.am-utils.org/} under ``Mailing Lists.'' 323This list is read-only: only am-utils developers may post to it. 324 325@item 326We distribute nightly CVS snapshots in 327@url{ftp://ftp.am-utils.org/pub/am-utils/snapshots/daily/}. If you 328like to get email notices of commits to the am-utils CVS repository, 329subscribe to the CVS logs mailing list, @samp{am-utils-cvs} at 330@url{http://www.am-utils.org/} under ``Mailing Lists.'' 331 332@item 333The older list which was used to user discussions, @samp{amd-workers}, 334is defunct as of January 2004. (Its last address was 335@email{amd-workers AT majordomo.glue.umd.edu}.) Don't use 336@samp{amd-workers}: use the newer, more active @samp{am-utils} list. 337 338@item 339For completeness, there's a developers-only closed list called 340@samp{am-utils-developers} (see @url{http://www.am-utils.org/} under 341``Mailing Lists''). 342 343@end enumerate 344 345@unnumberedsec Am-utils Book 346@cindex Am-utils book 347@cindex Amd book 348@cindex Automounter book 349@cindex book 350 351@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} wrote a 352@uref{http://www.fsl.cs.sunysb.edu/docs/amd-book/,book}, titled @i{Linux NFS and 353Automounter Administration}, ISBN 0-7821-2739-8, (Sybex, 2001). The 354book is full of details and examples that go beyond what this manual 355has. The book also covers NFS in great detail. Although the book is 356geared toward Linux users, it is general enough for any Unix 357administrator and contains specific sections for non-Linux systems. 358 359@c ################################################################ 360@node Intro, History, AddInfo, Top 361@unnumbered Introduction 362@cindex Introduction 363 364An @dfn{automounter} maintains a cache of mounted filesystems. 365Filesystems are mounted on demand when they are first referenced, 366and unmounted after a period of inactivity. 367 368@i{Amd} may be used as a replacement for Sun's automounter. The choice 369of which filesystem to mount can be controlled dynamically with 370@dfn{selectors}. Selectors allow decisions of the form ``hostname is 371@var{this},'' or ``architecture is not @var{that}.'' Selectors may be 372combined arbitrarily. @i{Amd} also supports a variety of filesystem 373types, including NFS, UFS and the novel @dfn{program} filesystem. The 374combination of selectors and multiple filesystem types allows identical 375configuration files to be used on all machines thus reducing the 376administrative overhead. 377 378@i{Amd} ensures that it will not hang if a remote server goes down. 379Moreover, @i{Amd} can determine when a remote server has become 380inaccessible and then mount replacement filesystems as and when they 381become available. 382 383@i{Amd} contains no proprietary source code and has been ported to 384numerous flavors of Unix. 385 386@c ################################################################ 387@node History, Overview, Intro, Top 388@unnumbered History 389@cindex History 390 391The @i{Amd} package has been without an official maintainer since 1992. 392Several people have stepped in to maintain it unofficially. Most 393notable were the `upl' (Unofficial Patch Level) releases of @i{Amd}, 394created by me (@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok}), and available from 395@url{ftp://ftp.am-utils.org/pub/amd/}. The last such unofficial 396release was `upl102'. 397 398Through the process of patching and aging, it was becoming more and more 399apparent that @i{Amd} was in much need of revitalizing. Maintaining 400@i{Amd} had become a difficult task. I took it upon myself to cleanup 401the code, so that it would be easier to port to new platforms, add new 402features, keep up with the many new feature requests, and deal with the 403never ending stream of bug reports. 404 405I have been working on such a release of @i{Amd} on and off since 406January of 1996. The new suite of tools is currently named "am-utils" 407(AutoMounter Utilities), in line with GNU naming conventions, befitting 408the contents of the package. In October of 1996 I had received enough 409offers to help me with this task that I decided to make a mailing list 410for this group of people. Around the same time, @i{Amd} had become a 411necessary part of my PhD thesis work, resulting in more work performed 412on am-utils. 413 414Am-utils version 6.0 was numbered with a major new release number to 415distinguish it from the last official release of @i{Amd} (5.x). Many 416new features have been added such as a GNU @code{configure} system, NFS 417Version 3, a run-time configuration file (`amd.conf'), many new ports, 418more scripts and programs, as well as numerous bug fixes. Another 419reason for the new major release number was to alert users of am-utils 420that user-visible interfaces may have changed. In order to make @i{Amd} 421work well for the next 10 years, and be easier to maintain, it was 422necessary to remove old or unused features, change various syntax files, 423etc. However, great care was taken to ensure the maximum possible 424backwards compatibility. 425 426Am-utils version 6.1 has autofs support for Linux and Solaris 2.5+ as 427@i{the} major new feature, in addition to several other minor new 428features. The autofs support is completely transparent to the 429end-user, aside from the fact that @code{/bin/pwd} now always returns 430the correct amd-ified path. The administrator can easily switch 431between NFS and autofs mounts by changing one parameter in 432@code{amd.conf}. Autofs support and maintenance was developed in 433conjunction with @email{ionut AT badula.org,Ion Badulescu}. 434 435@c ################################################################ 436@node Overview, Supported Platforms, History, Top 437@chapter Overview 438 439@i{Amd} maintains a cache of mounted filesystems. Filesystems are 440@dfn{demand-mounted} when they are first referenced, and unmounted after 441a period of inactivity. @i{Amd} may be used as a replacement for Sun's 442@b{automount}(8) program. It contains no proprietary source code and 443has been ported to numerous flavors of Unix. @xref{Supported 444Platforms}.@refill 445 446@i{Amd} was designed as the basis for experimenting with filesystem 447layout and management. Although @i{Amd} has many direct applications it 448is loaded with additional features which have little practical use. At 449some point the infrequently used components may be removed to streamline 450the production system. 451 452@i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating 453each member of a list of possible filesystem locations one by one. 454@i{Amd} checks that each cached mapping remains valid. Should a mapping be 455lost -- such as happens when a fileserver goes down -- @i{Amd} automatically 456selects a replacement should one be available. 457 458@menu 459* Fundamentals:: 460* Filesystems and Volumes:: 461* Volume Naming:: 462* Volume Binding:: 463* Operational Principles:: 464* Mounting a Volume:: 465* Automatic Unmounting:: 466* Keep-alives:: 467* Non-blocking Operation:: 468@end menu 469 470@node Fundamentals, Filesystems and Volumes, Overview, Overview 471@comment node-name, next, previous, up 472@section Fundamentals 473@cindex Automounter fundamentals 474 475The fundamental concept behind @i{Amd} is the ability to separate the 476name used to refer to a file from the name used to refer to its physical 477storage location. This allows the same files to be accessed with the 478same name regardless of where in the network the name is used. This is 479very different from placing @file{/n/hostname} in front of the pathname 480since that includes location dependent information which may change if 481files are moved to another machine. 482 483By placing the required mappings in a centrally administered database, 484filesystems can be re-organized without requiring changes to 485configuration files, shell scripts and so on. 486 487@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview 488@comment node-name, next, previous, up 489@section Filesystems and Volumes 490@cindex Filesystem 491@cindex Volume 492@cindex Fileserver 493@cindex sublink 494 495@i{Amd} views the world as a set of fileservers, each containing one or 496more filesystems where each filesystem contains one or more 497@dfn{volumes}. Here the term @dfn{volume} is used to refer to a 498coherent set of files such as a user's home directory or a @TeX{} 499distribution.@refill 500 501In order to access the contents of a volume, @i{Amd} must be told in 502which filesystem the volume resides and which host owns the filesystem. 503By default the host is assumed to be local and the volume is assumed to 504be the entire filesystem. If a filesystem contains more than one 505volume, then a @dfn{sublink} is used to refer to the sub-directory 506within the filesystem where the volume can be found. 507 508@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview 509@comment node-name, next, previous, up 510@section Volume Naming 511@cindex Volume names 512@cindex Network-wide naming 513@cindex Replicated volumes 514@cindex Duplicated volumes 515@cindex Replacement volumes 516 517Volume names are defined to be unique across the entire network. A 518volume name is the pathname to the volume's root as known by the users 519of that volume. Since this name uniquely identifies the volume 520contents, all volumes can be named and accessed from each host, subject 521to administrative controls. 522 523Volumes may be replicated or duplicated. Replicated volumes contain 524identical copies of the same data and reside at two or more locations in 525the network. Each of the replicated volumes can be used 526interchangeably. Duplicated volumes each have the same name but contain 527different, though functionally identical, data. For example, 528@samp{/vol/tex} might be the name of a @TeX{} distribution which varied 529for each machine architecture.@refill 530 531@i{Amd} provides facilities to take advantage of both replicated and 532duplicated volumes. Configuration options allow a single set of 533configuration data to be shared across an entire network by taking 534advantage of replicated and duplicated volumes. 535 536@i{Amd} can take advantage of replacement volumes by mounting them as 537required should an active fileserver become unavailable. 538 539@node Volume Binding, Operational Principles, Volume Naming, Overview 540@comment node-name, next, previous, up 541@section Volume Binding 542@cindex Volume binding 543@cindex Unix namespace 544@cindex Namespace 545@cindex Binding names to filesystems 546 547Unix implements a namespace of hierarchically mounted filesystems. Two 548forms of binding between names and files are provided. A @dfn{hard 549link} completes the binding when the name is added to the filesystem. A 550@dfn{soft link} delays the binding until the name is accessed. An 551@dfn{automounter} adds a further form in which the binding of name to 552filesystem is delayed until the name is accessed.@refill 553 554The target volume, in its general form, is a tuple (host, filesystem, 555sublink) which can be used to name the physical location of any volume 556in the network. 557 558When a target is referenced, @i{Amd} ignores the sublink element and 559determines whether the required filesystem is already mounted. This is 560done by computing the local mount point for the filesystem and checking 561for an existing filesystem mounted at the same place. If such a 562filesystem already exists then it is assumed to be functionally 563identical to the target filesystem. By default there is a one-to-one 564mapping between the pair (host, filesystem) and the local mount point so 565this assumption is valid. 566 567@node Operational Principles, Mounting a Volume, Volume Binding, Overview 568@comment node-name, next, previous, up 569@section Operational Principles 570@cindex Operational principles 571 572@i{Amd} operates by introducing new mount points into the namespace. 573These are called @dfn{automount} points. The kernel sees these 574automount points as NFS filesystems being served by @i{Amd}. Having 575attached itself to the namespace, @i{Amd} is now able to control the 576view the rest of the system has of those mount points. RPC calls are 577received from the kernel one at a time. 578 579When a @dfn{lookup} call is received @i{Amd} checks whether the name is 580already known. If it is not, the required volume is mounted. A 581symbolic link pointing to the volume root is then returned. Once the 582symbolic link is returned, the kernel will send all other requests 583direct to the mounted filesystem. 584 585If a volume is not yet mounted, @i{Amd} consults a configuration 586@dfn{mount-map} corresponding to the automount point. @i{Amd} then 587makes a runtime decision on what and where to mount a filesystem based 588on the information obtained from the map. 589 590@i{Amd} does not implement all the NFS requests; only those relevant 591to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. 592Some other calls are also implemented but most simply return an error 593code; for example @dfn{mkdir} always returns ``read-only filesystem''. 594 595@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview 596@comment node-name, next, previous, up 597@section Mounting a Volume 598@cindex Mounting a volume 599@cindex Location lists 600@cindex Alternate locations 601@cindex Mount retries 602@cindex Background mounts 603 604Each automount point has a corresponding mount map. The mount map 605contains a list of key--value pairs. The key is the name of the volume 606to be mounted. The value is a list of locations describing where the 607filesystem is stored in the network. In the source for the map the 608value would look like 609 610@display 611location1 location2 @dots{} locationN 612@end display 613 614@i{Amd} examines each location in turn. Each location may contain 615@dfn{selectors} which control whether @i{Amd} can use that location. 616For example, the location may be restricted to use by certain hosts. 617Those locations which cannot be used are ignored. 618 619@i{Amd} attempts to mount the filesystem described by each remaining 620location until a mount succeeds or @i{Amd} can no longer proceed. The 621latter can occur in three ways: 622 623@itemize @bullet 624@item 625If none of the locations could be used, or if all of the locations 626caused an error, then the last error is returned. 627 628@item 629If a location could be used but was being mounted in the background then 630@i{Amd} marks that mount as being ``in progress'' and continues with 631the next request; no reply is sent to the kernel. 632 633@item 634Lastly, one or more of the mounts may have been @dfn{deferred}. A mount 635is deferred if extra information is required before the mount can 636proceed. When the information becomes available the mount will take 637place, but in the mean time no reply is sent to the kernel. If the 638mount is deferred, @i{Amd} continues to try any remaining locations. 639@end itemize 640 641Once a volume has been mounted, @i{Amd} establishes a @dfn{volume 642mapping} which is used to satisfy subsequent requests.@refill 643 644@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview 645@comment node-name, next, previous, up 646@section Automatic Unmounting 647 648To avoid an ever increasing number of filesystem mounts, @i{Amd} removes 649volume mappings which have not been used recently. A time-to-live 650interval is associated with each mapping and when that expires the 651mapping is removed. When the last reference to a filesystem is removed, 652that filesystem is unmounted. If the unmount fails, for example the 653filesystem is still busy, the mapping is re-instated and its 654time-to-live interval is extended. The global default for this grace 655period is controlled by the @code{-w} command-line option (@pxref{-w 656Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval} 657(@pxref{dismount_interval Parameter}). It is also possible to set this 658value on a per-mount basis (@pxref{opts Option, opts, opts}). 659 660Filesystems can be forcefully timed out using the @i{Amq} command. 661@xref{Run-time Administration}. Note that on new enough systems that 662support forced unmounts, such as Linux, @i{Amd} can try to use the 663@b{umount2}(2) system call to force the unmount, if the regular 664@b{umount}(2) system call failed in a way that indicates that the 665mount point is hung or stale. @xref{forced_unmounts Parameter}. 666 667@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview 668@comment node-name, next, previous, up 669@section Keep-alives 670@cindex Keep-alives 671@cindex Server crashes 672@cindex NFS ping 673 674Use of some filesystem types requires the presence of a server on 675another machine. If a machine crashes then it is of no concern to 676processes on that machine that the filesystem is unavailable. However, 677to processes on a remote host using that machine as a fileserver this 678event is important. This situation is most widely recognized when an 679NFS server crashes and the behavior observed on client machines is that 680more and more processes hang. In order to provide the possibility of 681recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some 682filesystem types. Currently only NFS makes use of this service. 683 684The basis of the NFS keep-alive implementation is the observation that 685most sites maintain replicated copies of common system data such as 686manual pages, most or all programs, system source code and so on. If 687one of those servers goes down it would be reasonable to mount one of 688the others as a replacement. 689 690The first part of the process is to keep track of which fileservers are 691up and which are down. @i{Amd} does this by sending RPC requests to the 692servers' NFS @code{NullProc} and checking whether a reply is returned. 693While the server state is uncertain the requests are re-transmitted at 694three second intervals and if no reply is received after four attempts 695the server is marked down. If a reply is received the fileserver is 696marked up and stays in that state for 30 seconds at which time another 697NFS ping is sent. This interval is configurable and can even be 698turned off using the @i{ping} option. @xref{opts Option}. 699 700Once a fileserver is marked down, requests continue to be sent every 30 701seconds in order to determine when the fileserver comes back up. During 702this time any reference through @i{Amd} to the filesystems on that 703server fail with the error ``Operation would block''. If a replacement 704volume is available then it will be mounted, otherwise the error is 705returned to the user. 706 707@c @i{Amd} keeps track of which servers are up and which are down. 708@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and 709@c checking whether a reply is returned. If no replies are received after a 710@c short period, @i{Amd} marks the fileserver @dfn{down}. 711@c RPC requests continue to be sent so that it will notice when a fileserver 712@c comes back up. 713@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability 714@c of the NFS service that is important, not the existence of a base kernel. 715@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate 716@c filesystem is mounted if one is available. 717@c 718Although this action does not protect user files, which are unique on 719the network, or processes which do not access files via @i{Amd} or 720already have open files on the hung filesystem, it can prevent most new 721processes from hanging. 722@c 723@c With a suitable combination of filesystem management and mount-maps, 724@c machines can be protected against most server downtime. This can be 725@c enhanced by allocating boot-servers dynamically which allows a diskless 726@c workstation to be quickly restarted if necessary. Once the root filesystem 727@c is mounted, @i{Amd} can be started and allowed to mount the remainder of 728@c the filesystem from whichever fileservers are available. 729 730@node Non-blocking Operation, , Keep-alives, Overview 731@comment node-name, next, previous, up 732@section Non-blocking Operation 733@cindex Non-blocking operation 734@cindex Multiple-threaded server 735@cindex RPC retries 736 737Since there is only one instance of @i{Amd} for each automount point, 738and usually only one instance on each machine, it is important that it 739is always available to service kernel calls. @i{Amd} goes to great 740lengths to ensure that it does not block in a system call. As a last 741resort @i{Amd} will fork before it attempts a system call that may block 742indefinitely, such as mounting an NFS filesystem. Other tasks such as 743obtaining filehandle information for an NFS filesystem, are done using a 744purpose built non-blocking RPC library which is integrated with 745@i{Amd}'s task scheduler. This library is also used to implement NFS 746keep-alives (@pxref{Keep-alives}). 747 748Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it 749to complete before replying to the kernel. However, this would cause 750@i{Amd} to block waiting for a reply to be constructed. Rather than do 751this, @i{Amd} simply @dfn{drops} the call under the assumption that the 752kernel RPC mechanism will automatically retry the request. 753 754@c ################################################################ 755@node Supported Platforms, Mount Maps, Overview, Top 756@comment node-name, next, previous, up 757@chapter Supported Platforms 758@cindex Supported Platforms 759@cindex shared libraries 760@cindex NFS V.3 support 761 762@i{Am-utils} has been ported to a wide variety of machines and operating 763systems. @i{Am-utils}'s code works for little-endian and big-endian 764machines, as well as 32 bit and 64 bit architectures. Furthermore, when 765@i{Am-utils} ports to an Operating System on one architecture, it is generally 766readily portable to the same Operating System on all platforms on which 767it is available. 768 769See the @file{INSTALL} in the distribution for more specific details on 770building and/or configuring for some systems. 771 772@c ################################################################ 773@node Mount Maps, Amd Command Line Options, Supported Platforms, Top 774@comment node-name, next, previous, up 775@chapter Mount Maps 776@cindex Mount maps 777@cindex Automounter configuration maps 778@cindex Mount information 779 780@i{Amd} has no built-in knowledge of machines or filesystems. 781External @dfn{mount-maps} are used to provide the required information. 782Specifically, @i{Amd} needs to know when and under what conditions it 783should mount filesystems. 784 785The map entry corresponding to the requested name contains a list of 786possible locations from which to resolve the request. Each location 787specifies filesystem type, information required by that filesystem (for 788example the block special device in the case of UFS), and some 789information describing where to mount the filesystem (@pxref{fs Option}). A 790location may also contain @dfn{selectors} (@pxref{Selectors}).@refill 791 792@menu 793* Map Types:: 794* Key Lookup:: 795* Location Format:: 796@end menu 797 798@node Map Types, Key Lookup, Mount Maps, Mount Maps 799@comment node-name, next, previous, up 800@section Map Types 801@cindex Mount map types 802@cindex Map types 803@cindex Configuration map types 804@cindex Types of mount map 805@cindex Types of configuration map 806@cindex Determining the map type 807 808A mount-map provides the run-time configuration information to @i{Amd}. 809Maps can be implemented in many ways. Some of the forms supported by 810@i{Amd} are regular files, ndbm databases, NIS maps, the @dfn{Hesiod} 811name server, and even the password file. 812 813A mount-map @dfn{name} is a sequence of characters. When an automount 814point is created a handle on the mount-map is obtained. For each map 815type configured, @i{Amd} attempts to reference the map of the 816appropriate type. If a map is found, @i{Amd} notes the type for future 817use and deletes the reference, for example closing any open file 818descriptors. The available maps are configured when @i{Amd} is built 819and can be displayed by running the command @samp{amd -v}. 820 821When using an @i{Amd} configuration file (@pxref{Amd Configuration File}) 822and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may 823force the map used to any type. 824 825By default, @i{Amd} caches data in a mode dependent on the type of map. 826This is the same as specifying @samp{cache:=mapdefault} and selects a 827suitable default cache mode depending on the map type. The individual 828defaults are described below. The @var{cache} option can be specified 829on automount points to alter the caching behavior (@pxref{Automount 830Filesystem}).@refill 831 832The following map types have been implemented, though some are not 833available on all machines. Run the command @samp{amd -v} to obtain a 834list of map types configured on your machine. 835 836@menu 837* File maps:: 838* ndbm maps:: 839* NIS maps:: 840* NIS+ maps:: 841* Hesiod maps:: 842* Password maps:: 843* Union maps:: 844* LDAP maps:: 845* Executable maps:: 846@end menu 847 848@c ---------------------------------------------------------------- 849@node File maps, ndbm maps, Map Types, Map Types 850@comment node-name, next, previous, up 851@subsection File maps 852@cindex File maps 853@cindex Flat file maps 854@cindex File map syntactic conventions 855 856When @i{Amd} searches a file for a map entry it does a simple scan of 857the file and supports both comments and continuation lines. 858 859Continuation lines are indicated by a backslash character (@samp{\}) as 860the last character of a line in the file. The backslash, newline character 861@emph{and any leading white space on the following line} are discarded. A maximum 862line length of 2047 characters is enforced after continuation lines are read 863but before comments are stripped. Each line must end with 864a newline character; that is newlines are terminators, not separators. 865The following examples illustrate this: 866 867@example 868key valA valB; \ 869 valC 870@end example 871 872specifies @emph{three} locations, and is identical to 873 874@example 875key valA valB; valC 876@end example 877 878However, 879 880@example 881key valA valB;\ 882 valC 883@end example 884 885specifies only @emph{two} locations, and is identical to 886 887@example 888key valA valB;valC 889@end example 890 891After a complete line has been read from the file, including 892continuations, @i{Amd} determines whether there is a comment on the 893line. A comment begins with a hash (``@samp{#}'') character and 894continues to the end of the line. There is no way to escape or change 895the comment lead-in character. 896 897Note that continuation lines and comment support @dfn{only} apply to 898file maps, or ndbm maps built with the @code{mk-amd-map} program. 899 900When caching is enabled, file maps have a default cache mode of 901@code{all} (@pxref{Automount Filesystem}). 902 903@c ---------------------------------------------------------------- 904@node ndbm maps, NIS maps, File maps, Map Types 905@comment node-name, next, previous, up 906@subsection ndbm maps 907@cindex ndbm maps 908 909An ndbm map may be used as a fast access form of a file map. The program, 910@code{mk-amd-map}, converts a normal map file into an ndbm database. 911This program supports the same continuation and comment conventions that 912are provided for file maps. Note that ndbm format files may @emph{not} 913be sharable across machine architectures. The notion of speed generally 914only applies to large maps; a small map, less than a single disk block, 915is almost certainly better implemented as a file map. 916 917ndbm maps have a default cache mode of @samp{all} 918(@pxref{Automount Filesystem}). 919 920@c ---------------------------------------------------------------- 921@node NIS maps, NIS+ maps, ndbm maps, Map Types 922@comment node-name, next, previous, up 923@subsection NIS maps 924@cindex NIS (YP) maps 925 926When using NIS (formerly YP), an @i{Amd} map is implemented directly 927by the underlying NIS map. Comments and continuation lines are 928@emph{not} supported in the automounter and must be stripped when 929constructing the NIS server's database. 930 931NIS maps have a default cache mode of @code{all} (@pxref{Automount 932Filesystem}). 933 934The following rule illustrates what could be added to your NIS @file{Makefile}, 935in this case causing the @file{amd.home} map to be rebuilt: 936@example 937$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home 938 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ 939 awk '@{ \ 940 for (i = 1; i <= NF; i++) \ 941 if (i == NF) @{ \ 942 if (substr($$i, length($$i), 1) == "\\") \ 943 printf("%s", substr($$i, 1, length($$i) - 1)); \ 944 else \ 945 printf("%s\n", $$i); \ 946 @} \ 947 else \ 948 printf("%s ", $$i); \ 949 @}' | \ 950 $(MAKEDBM) - $(YPDBDIR)/amd.home; \ 951 touch $(YPTSDIR)/amd.home.time; \ 952 echo "updated amd.home"; \ 953 if [ ! $(NOPUSH) ]; then \ 954 $(YPPUSH) amd.home; \ 955 echo "pushed amd.home"; \ 956 else \ 957 : ; \ 958 fi 959@end example 960 961Here @code{$(YPTSDIR)} contains the time stamp files, and 962@code{$(YPDBDIR)} contains the dbm format NIS files. 963 964@c ---------------------------------------------------------------- 965@node NIS+ maps, Hesiod maps, NIS maps, Map Types 966@comment node-name, next, previous, up 967@subsection NIS+ maps 968@cindex NIS+ maps 969 970NIS+ maps do not support cache mode @samp{all} and, when caching is 971enabled, have a default cache mode of @samp{inc}. 972 973XXX: FILL IN WITH AN EXAMPLE. 974 975@c ---------------------------------------------------------------- 976@node Hesiod maps, Password maps, NIS+ maps, Map Types 977@comment node-name, next, previous, up 978@subsection Hesiod maps 979@cindex Hesiod maps 980 981When the map name begins with the string @samp{hesiod.} lookups are made 982using the @dfn{Hesiod} name server. The string following the dot is 983used as a name qualifier and is prepended with the key being located. 984The entire string is then resolved in the @code{automount} context, or 985the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base 986Parameter}). For example, if the key is @samp{jsp} and map name is 987@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve 988@samp{jsp.homes.automount}. 989 990Hesiod maps do not support cache mode @samp{all} and, when caching is 991enabled, have a default cache mode of @samp{inc} (@pxref{Automount 992Filesystem}). 993 994The following is an example of a @dfn{Hesiod} map entry: 995 996@example 997jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" 998njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" 999@end example 1000 1001@c ---------------------------------------------------------------- 1002@node Password maps, Union maps, Hesiod maps, Map Types 1003@comment node-name, next, previous, up 1004@subsection Password maps 1005@cindex Password file maps 1006@cindex /etc/passwd maps 1007@cindex User maps, automatic generation 1008@cindex Automatic generation of user maps 1009@cindex Using the password file as a map 1010 1011The password map support is unlike the four previous map types. When 1012the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user 1013name in the password file and re-arrange the home directory field to 1014produce a usable map entry. 1015 1016@i{Amd} assumes the home directory has the format 1017`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. 1018@c @footnote{This interpretation is not necessarily exactly what you want.} 1019It breaks this string into a map entry where @code{$@{rfs@}} has the 1020value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value 1021`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the 1022value @i{login}.@refill 1023 1024Thus if the password file entry was 1025 1026@example 1027/home/achilles/jsp 1028@end example 1029 1030the map entry used by @i{Amd} would be 1031 1032@example 1033rfs:=/home/achilles;rhost:=achilles;sublink:=jsp 1034@end example 1035 1036Similarly, if the password file entry was 1037 1038@example 1039/home/cc/sugar/mjh 1040@end example 1041 1042the map entry used by @i{Amd} would be 1043 1044@example 1045rfs:=/home/sugar;rhost:=sugar.cc;sublink:=mhj 1046@end example 1047 1048@c ---------------------------------------------------------------- 1049@node Union maps, LDAP maps, Password maps, Map Types 1050@comment node-name, next, previous, up 1051@subsection Union maps 1052@cindex Union file maps 1053 1054The union map support is provided specifically for use with the union 1055filesystem, @pxref{Union Filesystem}. 1056 1057It is identified by the string @samp{union:} which is followed by a 1058colon separated list of directories. The directories are read in order, 1059and the names of all entries are recorded in the map cache. Later 1060directories take precedence over earlier ones. The union filesystem 1061type then uses the map cache to determine the union of the names in all 1062the directories. 1063 1064@c ---------------------------------------------------------------- 1065@node LDAP maps, Executable maps, Union maps, Map Types 1066@comment node-name, next, previous, up 1067@subsection LDAP maps 1068@cindex LDAP maps 1069@cindex Lightweight Directory Access Protocol 1070 1071LDAP (Lightweight Directory Access Protocol) maps do not support cache 1072mode @samp{all} and, when caching is enabled, have a default cache mode 1073of @samp{inc}. 1074 1075For example, an @i{Amd} map @samp{amd.home} that looks as follows: 1076 1077@example 1078/defaults opts:=rw,intr;type:=link 1079 1080zing -rhost:=shekel \ 1081 host==shekel \ 1082 host!=shekel;type:=nfs 1083@end example 1084@noindent 1085when converted to LDAP (@pxref{amd2ldif}), will result in the following 1086LDAP database: 1087@example 1088$ amd2ldif amd.home CUCS < amd.home 1089dn: cn=amdmap timestamp, CUCS 1090cn : amdmap timestamp 1091objectClass : amdmapTimestamp 1092amdmapTimestamp: 873071363 1093 1094dn: cn=amdmap amd.home[/defaults], CUCS 1095cn : amdmap amd.home[/defaults] 1096objectClass : amdmap 1097amdmapName : amd.home 1098amdmapKey : /defaults 1099amdmapValue : opts:=rw,intr;type:=link 1100 1101dn: cn=amdmap amd.home[], CUCS 1102cn : amdmap amd.home[] 1103objectClass : amdmap 1104amdmapName : amd.home 1105amdmapKey : 1106amdmapValue : 1107 1108dn: cn=amdmap amd.home[zing], CUCS 1109cn : amdmap amd.home[zing] 1110objectClass : amdmap 1111amdmapName : amd.home 1112amdmapKey : zing 1113amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs 1114@end example 1115 1116@c ---------------------------------------------------------------- 1117@node Executable maps, , LDAP maps, Map Types 1118@comment node-name, next, previous, up 1119@subsection Executable maps 1120@cindex Executable maps 1121 1122An executable map is a dynamic map in which the keys and values for 1123the maps are generated on the fly by a program or script. The program 1124is expected to take a single parameter argument which is the key to 1125lookup. If the key is found, the program should print on stdout the 1126key-value pair that were found; if the key was not found, nothing 1127should be printed out. Below is an sample of such a map script: 1128 1129@example 1130#!/bin/sh 1131# executable map example 1132case "$1" in 1133 "/defaults" ) 1134 echo "/defaults type:=nfs;rfs:=filer" 1135 ;; 1136 "a" ) 1137 echo "a type:=nfs;fs:=/tmp" 1138 ;; 1139 "b" ) 1140 echo "b type:=link;fs:=/usr/local" 1141 ;; 1142 * ) # no match, echo nothing 1143 ;; 1144esac 1145@end example 1146 1147@xref{exec_map_timeout Parameter}. 1148 1149@c ---------------------------------------------------------------- 1150@c subsection Gdbm 1151@c ---------------------------------------------------------------- 1152@node Key Lookup, Location Format, Map Types, Mount Maps 1153@comment node-name, next, previous, up 1154@section How keys are looked up 1155@cindex Key lookup 1156@cindex Map lookup 1157@cindex Looking up keys 1158@cindex How keys are looked up 1159@cindex Wildcards in maps 1160 1161The key is located in the map whose type was determined when the 1162automount point was first created. In general the key is a pathname 1163component. In some circumstances this may be modified by variable 1164expansion (@pxref{Variable Expansion}) and prefixing. If the automount 1165point has a prefix, specified by the @var{pref} option, then that is 1166prepended to the search key before the map is searched. 1167 1168If the map cache is a @samp{regexp} cache then the key is treated as an 1169egrep-style regular expression, otherwise a normal string comparison is 1170made. 1171 1172If the key cannot be found then a @dfn{wildcard} match is attempted. 1173@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and 1174attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. 1175 1176For example, the following sequence would be checked if @file{home/dylan/dk2} was 1177being located: 1178 1179@example 1180 home/dylan/dk2 1181 home/dylan/* 1182 home/* 1183 * 1184@end example 1185 1186At any point when a wildcard is found, @i{Amd} proceeds as if an exact 1187match had been found and the value field is then used to resolve the 1188mount request, otherwise an error code is propagated back to the kernel. 1189(@pxref{Filesystem Types}).@refill 1190 1191@node Location Format, , Key Lookup, Mount Maps 1192@comment node-name, next, previous, up 1193@section Location Format 1194@cindex Location format 1195@cindex Map entry format 1196@cindex How locations are parsed 1197 1198The value field from the lookup provides the information required to 1199mount a filesystem. The information is parsed according to the syntax 1200shown below. 1201 1202@display 1203@i{location-list}: 1204 @i{location-selection} 1205 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} 1206@i{location-selection}: 1207 @i{location} 1208 @i{location-selection} @i{white-space} @i{location} 1209@i{location}: 1210 @i{location-info} 1211 @t{-}@i{location-info} 1212 @t{-} 1213@i{location-info}: 1214 @i{sel-or-opt} 1215 @i{location-info}@t{;}@i{sel-or-opt} 1216 @t{;} 1217@i{sel-or-opt}: 1218 @i{selection} 1219 @i{opt-ass} 1220@i{selection}: 1221 selector@t{==}@i{value} 1222 selector@t{!=}@i{value} 1223@i{opt-ass}: 1224 option@t{:=}@i{value} 1225@i{white-space}: 1226 space 1227 tab 1228@end display 1229 1230Note that unquoted whitespace is not allowed in a location description. 1231White space is only allowed, and is mandatory, where shown with non-terminal 1232@i{white-space}. 1233 1234A @dfn{location-selection} is a list of possible volumes with which to 1235satisfy the request. Each @dfn{location-selection} is tried 1236sequentially, until either one succeeds or all fail. This, by the 1237way, is different from the historically documented behavior, which 1238claimed (falsely, at least for last 3 years) that @i{Amd} would 1239attempt to mount all @dfn{location-selection}s in parallel and the 1240first one to succeed would be used. 1241 1242@dfn{location-selection}s are optionally separated by the @samp{||} 1243operator. The effect of this operator is to prevent use of 1244location-selections to its right if any of the location-selections on 1245its left were selected, whether or not any of them were successfully 1246mounted (@pxref{Selectors}).@refill 1247 1248The location-selection, and singleton @dfn{location-list}, 1249@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS 1250filesystem from the block special device @file{/dev/xd1g}. 1251 1252The @dfn{sel-or-opt} component is either the name of an option required 1253by a specific filesystem, or it is the name of a built-in, predefined 1254selector such as the architecture type. The value may be quoted with 1255double quotes @samp{"}, for example 1256@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the 1257value is parsed and there is no way to get a double quote into a value 1258field. Double quotes are used to get white space into a value field, 1259which is needed for the program filesystem (@pxref{Program Filesystem}).@refill 1260 1261@menu 1262* Map Defaults:: 1263* Variable Expansion:: 1264* Selectors:: 1265* Map Options:: 1266@end menu 1267 1268@node Map Defaults, Variable Expansion, Location Format, Location Format 1269@comment node-name, next, previous, up 1270@subsection Map Defaults 1271@cindex Map defaults 1272@cindex How to set default map parameters 1273@cindex Setting default map parameters 1274 1275A location beginning with a dash @samp{-} is used to specify default 1276values for subsequent locations. Any previously specified defaults in 1277the location-list are discarded. The default string can be empty in 1278which case no defaults apply. 1279 1280The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point 1281to @file{/mnt} and cause mounts to be read-only by default. Defaults 1282specified this way are appended to, and so override, any global map 1283defaults given with @samp{/defaults}). 1284 1285@c 1286@c A @samp{/defaults} value @dfn{gdef} and a location list 1287@c \begin{quote} 1288@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$ 1289@c \end{quote} 1290@c is equivalent to 1291@c \begin{quote} 1292@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$ 1293@c \end{quote} 1294@c which is equivalent to 1295@c \begin{quote} 1296@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$ 1297@c \end{quote} 1298 1299@node Variable Expansion, Selectors, Map Defaults, Location Format 1300@comment node-name, next, previous, up 1301@subsection Variable Expansion 1302@cindex Variable expansion 1303@cindex How variables are expanded 1304@cindex Pathname operators 1305@cindex Domain stripping 1306@cindex Domainname operators 1307@cindex Stripping the local domain name 1308@cindex Environment variables 1309@cindex How to access environment variables in maps 1310 1311To allow generic location specifications @i{Amd} does variable expansion 1312on each location and also on some of the option strings. Any option or 1313selector appearing in the form @code{$@dfn{var}} is replaced by the 1314current value of that option or selector. For example, if the value of 1315@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and 1316@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then 1317after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. 1318Any environment variable can be accessed in a similar way.@refill 1319 1320Two pathname operators are available when expanding a variable. If the 1321variable name begins with @samp{/} then only the last component of the 1322pathname is substituted. For example, if @code{$@{path@}} was 1323@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. 1324Similarly, if the variable name ends with @samp{/} then all but the last 1325component of the pathname is substituted. In the previous example, 1326@code{$@{path/@}} would be expanded to @samp{/foo}.@refill 1327 1328Two domain name operators are also provided. If the variable name 1329begins with @samp{.} then only the domain part of the name is 1330substituted. For example, if @code{$@{rhost@}} was 1331@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to 1332@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} 1333then only the host component is substituted. In the previous example, 1334@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill 1335 1336Variable expansion is a two phase process. Before a location is parsed, 1337all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The 1338location is then parsed, selections are evaluated and option assignments 1339recorded. If there were no selections or they all succeeded the 1340location is used and the values of the following options are expanded in 1341the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, 1342@var{remopts}, @var{mount} and @var{unmount}. 1343 1344Note that expansion of option values is done after @dfn{all} assignments 1345have been completed and not in a purely left to right order as is done 1346by the shell. This generally has the desired effect but care must be 1347taken if one of the options references another, in which case the 1348ordering can become significant. 1349 1350There are two special cases concerning variable expansion: 1351 1352@enumerate 1353@item 1354before a map is consulted, any selectors in the name received 1355from the kernel are expanded. For example, if the request from the 1356kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture 1357was @samp{vax}, the value given to @code{$@{key@}} would be 1358@samp{vax.bin}.@refill 1359 1360@item 1361the value of @code{$@{rhost@}} is expanded and normalized before the 1362other options are expanded. The normalization process strips any local 1363sub-domain components. For example, if @code{$@{domain@}} was 1364@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially 1365@samp{snow.Berkeley.EDU}, after the normalization it would simply be 1366@samp{snow}. Hostname normalization is currently done in a 1367@emph{case-dependent} manner.@refill 1368@end enumerate 1369 1370@c====================================================================== 1371@node Selectors, Map Options, Variable Expansion, Location Format 1372@comment node-name, next, previous, up 1373@subsection Selectors 1374@cindex Selectors 1375 1376Selectors are used to control the use of a location. It is possible to 1377share a mount map between many machines in such a way that filesystem 1378location, architecture and operating system differences are hidden from 1379the users. A selector of the form @samp{arch==sun3;os==sunos4} would only 1380apply on Sun-3s running SunOS 4.x. 1381 1382Selectors can be negated by using @samp{!=} instead of @samp{==}. For 1383example to select a location on all non-Vax machines the selector 1384@samp{arch!=vax} would be used. 1385 1386Selectors are evaluated left to right. If a selector fails then that 1387location is ignored. Thus the selectors form a conjunction and the 1388locations form a disjunction. If all the locations are ignored or 1389otherwise fail then @i{Amd} uses the @dfn{error} filesystem 1390(@pxref{Error Filesystem}). This is equivalent to having a location 1391@samp{type:=error} at the end of each mount-map entry.@refill 1392 1393The default value of many of the selectors listed here can be overridden 1394by an @i{Amd} command line switch or in an @i{Amd} configuration file. 1395@xref{Amd Configuration File}. 1396 1397The following selectors are currently implemented. 1398 1399@menu 1400* arch Selector Variable:: 1401* autodir Selector Variable:: 1402* byte Selector Variable:: 1403* cluster Selector Variable:: 1404* domain Selector Variable:: 1405* dollar Selector Variable:: 1406* host Selector Variable:: 1407* hostd Selector Variable:: 1408* karch Selector Variable:: 1409* os Selector Variable:: 1410* osver Selector Variable:: 1411* full_os Selector Variable:: 1412* vendor Selector Variable:: 1413 1414* key Selector Variable:: 1415* map Selector Variable:: 1416* netnumber Selector Variable:: 1417* network Selector Variable:: 1418* path Selector Variable:: 1419* wire Selector Variable:: 1420* uid Selector Variable:: 1421* gid Selector Variable:: 1422 1423* exists Selector Function:: 1424* false Selector Function:: 1425* netgrp Selector Function:: 1426* netgrpd Selector Function:: 1427* in_network Selector Function:: 1428* true Selector Function:: 1429* xhost Selector Function:: 1430@end menu 1431 1432@c ---------------------------------------------------------------- 1433@node arch Selector Variable, autodir Selector Variable, Selectors, Selectors 1434@comment node-name, next, previous, up 1435@subsubsection arch Selector Variable 1436@cindex arch Selector Variable 1437@cindex arch, mount selector 1438@cindex Mount selector; arch 1439@cindex Selector; arch 1440 1441The machine architecture which was automatically determined at compile 1442time. The architecture type can be displayed by running the command 1443@samp{amd -v}. You can override this value also using the @code{-A} 1444command line option. @xref{Supported Platforms}.@refill 1445 1446@c ---------------------------------------------------------------- 1447@node autodir Selector Variable, byte Selector Variable, arch Selector Variable, Selectors 1448@comment node-name, next, previous, up 1449@subsubsection autodir Selector Variable 1450@cindex autodir Selector Variable 1451@cindex autodir, mount selector 1452@cindex Mount selector; autodir 1453@cindex Selector; autodir 1454 1455The default directory under which to mount filesystems. This may be 1456changed by the @code{-a} command line option. @xref{fs Option}. 1457 1458@c ---------------------------------------------------------------- 1459@node byte Selector Variable, cluster Selector Variable, autodir Selector Variable, Selectors 1460@comment node-name, next, previous, up 1461@subsubsection byte Selector Variable 1462@cindex byte Selector Variable 1463@cindex byte, mount selector 1464@cindex Mount selector; byte 1465@cindex Selector; byte 1466 1467The machine's byte ordering. This is either @samp{little}, indicating 1468little-endian, or @samp{big}, indicating big-endian. One possible use 1469is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to 1470share ndbm databases, however this use can be considered a courageous 1471juggling act. 1472 1473@c ---------------------------------------------------------------- 1474@node cluster Selector Variable, domain Selector Variable, byte Selector Variable, Selectors 1475@comment node-name, next, previous, up 1476@subsubsection cluster Selector Variable 1477@cindex cluster Selector Variable 1478@cindex cluster, mount selector 1479@cindex Mount selector; cluster 1480@cindex Selector; cluster 1481 1482This is provided as a hook for the name of the local cluster. This can 1483be used to decide which servers to use for copies of replicated 1484filesystems. @code{$@{cluster@}} defaults to the value of 1485@code{$@{domain@}} unless a different value is set with the @code{-C} 1486command line option. 1487 1488@c ---------------------------------------------------------------- 1489@node domain Selector Variable, dollar Selector Variable, cluster Selector Variable, Selectors 1490@comment node-name, next, previous, up 1491@subsubsection domain Selector Variable 1492@cindex domain Selector Variable 1493@cindex domain, mount selector 1494@cindex Mount selector; domain 1495@cindex Selector; domain 1496 1497The local domain name as specified by the @code{-d} command line option. 1498@xref{host Selector Variable}. 1499 1500@c ---------------------------------------------------------------- 1501@node dollar Selector Variable, host Selector Variable, domain Selector Variable, Selectors 1502@comment node-name, next, previous, up 1503@subsubsection dollar Selector Variable 1504@cindex dollar Selector Variable 1505 1506This is a special variable, whose sole purpose is to produce a literal 1507dollar sign in the value of another variable. For example, if you have 1508a remote file system whose name is @samp{/disk$s}, you can mount it by 1509setting the remote file system variable as follows: 1510 1511@example 1512rfs:=/disk$@{dollar@}s 1513@end example 1514 1515@c ---------------------------------------------------------------- 1516@node host Selector Variable, hostd Selector Variable, dollar Selector Variable, Selectors 1517@comment node-name, next, previous, up 1518@subsubsection host Selector Variable 1519@cindex host Selector Variable 1520@cindex host, mount selector 1521@cindex Mount selector; host 1522@cindex Selector; host 1523 1524The local hostname as determined by @b{gethostname}(2). If no domain 1525name was specified on the command line and the hostname contains a 1526period @samp{.} then the string before the period is used as the host 1527name, and the string after the period is assigned to @code{$@{domain@}}. 1528For example, if the hostname is @samp{styx.doc.ic.ac.uk} then 1529@code{host} would be @samp{styx} and @code{domain} would be 1530@samp{doc.ic.ac.uk}. @code{hostd} would be 1531@samp{styx.doc.ic.ac.uk}.@refill 1532 1533@c ---------------------------------------------------------------- 1534@node hostd Selector Variable, karch Selector Variable, host Selector Variable, Selectors 1535@comment node-name, next, previous, up 1536@subsubsection hostd Selector Variable 1537@cindex hostd Selector Variable 1538@cindex hostd, mount selector 1539@cindex Mount selector; hostd 1540@cindex Selector; hostd 1541 1542This resolves to the @code{$@{host@}} and @code{$@{domain@}} 1543concatenated with a @samp{.} inserted between them if required. If 1544@code{$@{domain@}} is an empty string then @code{$@{host@}} and 1545@code{$@{hostd@}} will be identical. 1546 1547@c ---------------------------------------------------------------- 1548@node karch Selector Variable, os Selector Variable, hostd Selector Variable, Selectors 1549@comment node-name, next, previous, up 1550@subsubsection karch Selector Variable 1551@cindex karch Selector Variable 1552@cindex karch, mount selector 1553@cindex Mount selector; karch 1554@cindex Selector; karch 1555 1556This is provided as a hook for the kernel architecture. This is used on 1557SunOS 4 and SunOS 5, for example, to distinguish between different 1558@samp{/usr/kvm} volumes. @code{$@{karch@}} defaults to the ``machine'' 1559value gotten from @b{uname}(2). If the @b{uname}(2) system call is not 1560available, the value of @code{$@{karch@}} defaults to that of 1561@code{$@{arch@}}. Finally, a different value can be set with the @code{-k} 1562command line option. 1563 1564@c ---------------------------------------------------------------- 1565@node os Selector Variable, osver Selector Variable, karch Selector Variable, Selectors 1566@comment node-name, next, previous, up 1567@subsubsection os Selector Variable 1568@cindex os Selector Variable 1569@cindex os, mount selector 1570@cindex Mount selector; os 1571@cindex Selector; os 1572 1573The operating system. Like the machine architecture, this is 1574automatically determined at compile time. The operating system name can 1575be displayed by running the command @samp{amd -v}. @xref{Supported 1576Platforms}.@refill 1577 1578@c ---------------------------------------------------------------- 1579@node osver Selector Variable, full_os Selector Variable, os Selector Variable, Selectors 1580@comment node-name, next, previous, up 1581@subsubsection osver Selector Variable 1582@cindex osver Selector Variable 1583@cindex osver, mount selector 1584@cindex Mount selector; osver 1585@cindex Selector; osver 1586 1587The operating system version. Like the machine architecture, this is 1588automatically determined at compile time. The operating system name can 1589be displayed by running the command @samp{amd -v}. @xref{Supported 1590Platforms}.@refill 1591 1592@c ---------------------------------------------------------------- 1593@node full_os Selector Variable, vendor Selector Variable, osver Selector Variable, Selectors 1594@comment node-name, next, previous, up 1595@subsubsection full_os Selector Variable 1596@cindex full_os Selector Variable 1597@cindex full_os, mount selector 1598@cindex Mount selector; full_os 1599@cindex Selector; full_os 1600 1601The full name of the operating system, including its version. This 1602value is automatically determined at compile time. The full operating 1603system name and version can be displayed by running the command 1604@samp{amd -v}. @xref{Supported Platforms}.@refill 1605 1606@c ---------------------------------------------------------------- 1607@node vendor Selector Variable, key Selector Variable, full_os Selector Variable, Selectors 1608@comment node-name, next, previous, up 1609@subsubsection vendor Selector Variable 1610@cindex vendor Selector Variable 1611@cindex vendor, mount selector 1612@cindex Mount selector; vendor 1613@cindex Selector; vendor 1614 1615The name of the vendor of the operating system. This value is 1616automatically determined at compile time. The name of the vendor can be 1617displayed by running the command @samp{amd -v}. @xref{Supported 1618Platforms}.@refill 1619 1620 1621@c ---------------------------------------------------------------- 1622@ifhtml 1623<HR> 1624@end ifhtml 1625@sp 3 1626The following selectors are also provided. Unlike the other selectors, 1627they vary for each lookup. Note that when the name from the kernel is 1628expanded prior to a map lookup, these selectors are all defined as empty 1629strings. 1630 1631@c ---------------------------------------------------------------- 1632@node key Selector Variable, map Selector Variable, vendor Selector Variable, Selectors 1633@comment node-name, next, previous, up 1634@subsubsection key Selector Variable 1635@cindex key Selector Variable 1636@cindex key, mount selector 1637@cindex Mount selector; key 1638@cindex Selector; key 1639 1640The name being resolved. For example, if @file{/home} is an automount 1641point, then accessing @file{/home/foo} would set @code{$@{key@}} to the 1642string @samp{foo}. The key is prefixed by the @var{pref} option set in 1643the parent mount point. The default prefix is an empty string. If the 1644prefix was @file{blah/} then @code{$@{key@}} would be set to 1645@file{blah/foo}.@refill 1646 1647@c ---------------------------------------------------------------- 1648@node map Selector Variable, netnumber Selector Variable, key Selector Variable, Selectors 1649@comment node-name, next, previous, up 1650@subsubsection map Selector Variable 1651@cindex map Selector Variable 1652@cindex map, mount selector 1653@cindex Mount selector; map 1654@cindex Selector; map 1655 1656The name of the mount map being used. 1657 1658@c ---------------------------------------------------------------- 1659@node netnumber Selector Variable, network Selector Variable, map Selector Variable, Selectors 1660@comment node-name, next, previous, up 1661@subsubsection netnumber Selector Variable 1662@cindex netnumber Selector Variable 1663@cindex netnumber, mount selector 1664@cindex Mount selector; netnumber 1665@cindex Selector; netnumber 1666 1667This selector is identical to the @samp{in_network} selector function, 1668see @ref{in_network Selector Function}. It will match either the name 1669or number of @i{any} network interface on which this host is connected 1670to. The names and numbers of all attached interfaces are available from 1671the output of @samp{amd -v}. 1672 1673@c ---------------------------------------------------------------- 1674@node network Selector Variable, path Selector Variable, netnumber Selector Variable, Selectors 1675@comment node-name, next, previous, up 1676@subsubsection network Selector Variable 1677@cindex network Selector Variable 1678@cindex network, mount selector 1679@cindex Mount selector; network 1680@cindex Selector; network 1681 1682This selector is identical to the @samp{in_network} selector function, 1683see @ref{in_network Selector Function}. It will match either the name 1684or number of @i{any} network interface on which this host is connected 1685to. The names and numbers of all attached interfaces are available from 1686the output of @samp{amd -v}. 1687 1688@c ---------------------------------------------------------------- 1689@node path Selector Variable, wire Selector Variable, network Selector Variable, Selectors 1690@comment node-name, next, previous, up 1691@subsubsection path Selector Variable 1692@cindex path Selector Variable 1693@cindex path, mount selector 1694@cindex Mount selector; path 1695@cindex Selector; path 1696 1697The full pathname of the name being resolved. For example 1698@file{/home/foo} in the example above. 1699 1700@c ---------------------------------------------------------------- 1701@node wire Selector Variable, uid Selector Variable, path Selector Variable, Selectors 1702@comment node-name, next, previous, up 1703@subsubsection wire Selector Variable 1704@cindex wire Selector Variable 1705@cindex wire, mount selector 1706@cindex Mount selector; wire 1707@cindex Selector; wire 1708 1709This selector is identical to the @samp{in_network} selector function, 1710see @ref{in_network Selector Function}. It will match either the name 1711or number of @i{any} network interface on which this host is connected 1712to. The names and numbers of all attached interfaces are available from 1713the output of @samp{amd -v}. 1714 1715@c ---------------------------------------------------------------- 1716@node uid Selector Variable, gid Selector Variable, wire Selector Variable, Selectors 1717@comment node-name, next, previous, up 1718@subsubsection uid Selector Variable 1719@cindex uid Selector Variable 1720@cindex uid, mount selector 1721@cindex Mount selector; uid 1722@cindex Selector; uid 1723 1724This selector provides the numeric effective user ID (UID) of the user 1725which last accessed an automounted path name. This simple example shows 1726how floppy mounting can be assigned only to machine owners: 1727 1728@example 1729floppy -type:=pcfs \ 1730 uid==2301;host==shekel;dev:=/dev/floppy \ 1731 uid==6712;host==titan;dev=/dev/fd0 \ 1732 uid==0;dev:=/dev/fd0c \ 1733 type:=error 1734@end example 1735 1736The example allows two machine owners to mount floppies on their 1737designated workstations, allows the root user to mount on any host, and 1738otherwise forces an error. 1739 1740@c ---------------------------------------------------------------- 1741@node gid Selector Variable, exists Selector Function, uid Selector Variable, Selectors 1742@comment node-name, next, previous, up 1743@subsubsection gid Selector Variable 1744@cindex gid Selector Variable 1745@cindex gid, mount selector 1746@cindex Mount selector; gid 1747@cindex Selector; gid 1748 1749This selector provides the numeric effective group ID (GID) of the user 1750which last accessed an automounted path name. 1751 1752@c ---------------------------------------------------------------- 1753@ifhtml 1754<HR> 1755@end ifhtml 1756@sp 2 1757The following boolean functions are selectors which take an argument 1758@i{ARG}. They return a value of true or false, and thus do not need to 1759be compared with a value. Each of these may be negated by prepending 1760@samp{!} to their name. 1761 1762@c ---------------------------------------------------------------- 1763@node exists Selector Function, false Selector Function, gid Selector Variable, Selectors 1764@comment node-name, next, previous, up 1765@subsubsection exists Selector Function 1766@cindex exists Selector Function 1767@cindex exists, boolean mount selector 1768@cindex !exists, boolean mount selector 1769@cindex Mount selector; exists 1770@cindex Selector; exists 1771 1772If the file listed by @i{ARG} exists (via @b{lstat}(2)), this function 1773evaluates to true. Otherwise it evaluates to false. 1774 1775@c ---------------------------------------------------------------- 1776@node false Selector Function, netgrp Selector Function, exists Selector Function, Selectors 1777@comment node-name, next, previous, up 1778@subsubsection false Selector Function 1779@cindex false Selector Function 1780@cindex false, boolean mount selector 1781@cindex !false, boolean mount selector 1782@cindex Mount selector; false 1783@cindex Selector; false 1784 1785Always evaluates to false. @i{ARG} is ignored. 1786 1787@c ---------------------------------------------------------------- 1788@node netgrp Selector Function, netgrpd Selector Function, false Selector Function, Selectors 1789@comment node-name, next, previous, up 1790@subsubsection netgrp Selector Function 1791@cindex netgrp Selector Function 1792@cindex netgrp, boolean mount selector 1793@cindex !netgrp, boolean mount selector 1794@cindex Mount selector; netgrp 1795@cindex Selector; netgrp 1796 1797The argument @i{ARG} of this selector is a netgroup name followed 1798optionally by a comma and a host name. If the host name is not 1799specified, it defaults to @code{$@{host@}}. If the host name (short 1800name) is a member of the netgroup, this selector evaluates to true. 1801Otherwise it evaluates to false. 1802 1803For example, suppose you have a netgroup @samp{ppp-hosts}, and for 1804reasons of performance, these have a local @file{/home} partition, 1805while all other clients on the faster network can access a shared home 1806directory. A common map to use for both might look like the 1807following: 1808 1809@example 1810home/* netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \ 1811 !netgrp(ppp-hosts);type:=nfs;rhost:=serv1;rfs:=/remote/$@{key@} 1812@end example 1813 1814A more complex example that takes advantage of the two argument netgrp 1815mount selector is given in the following scenario. Suppose one wants 1816to mount the local scratch space from a each host under 1817@file{scratch/<hostname>} and some hosts have their scratch space in a 1818different path than others. Hosts in the netgroup @samp{apple-hosts} 1819have their scratch space in the @file{/apple} path, where hosts in the 1820netgroup @samp{cherry-hosts} have their scratch space in the 1821@file{/cherry} path. For hosts that are neither in the 1822@samp{apple-hosts} or @samp{cherry-hosts} netgroups we want to make a 1823symlink pointing to nowhere but provide a descriptive error message in 1824the link destination: 1825 1826@example 1827scratch/* netgrp(apple-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1828 rfs:="/apple" \ 1829 netgrp(cherry-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1830 rfs:="/cherry" \ 1831 type:=link;rfs:="no local partition for $@{/key@}" 1832@end example 1833 1834@c ---------------------------------------------------------------- 1835@node netgrpd Selector Function, in_network Selector Function, netgrp Selector Function, Selectors 1836@comment node-name, next, previous, up 1837@subsubsection netgrpd Selector Function 1838@cindex netgrpd Selector Function 1839@cindex netgrpd, boolean mount selector 1840@cindex !netgrpd, boolean mount selector 1841@cindex Mount selector; netgrpd 1842@cindex Selector; netgrpd 1843 1844The argument @i{ARG} of this selector is a netgroup name followed 1845optionally by a comma and a host name. If the host name is not 1846specified, it defaults to @code{$@{hostd@}}. If the host name 1847(fully-qualified name) is a member of the netgroup, this selector 1848evaluates to true. Otherwise it evaluates to false. 1849 1850The @samp{netgrpd} function uses fully-qualified host names to match 1851netgroup names, while the @samp{netgrp} function (@pxref{netgrp 1852Selector Function}) uses short host names. 1853 1854@c ---------------------------------------------------------------- 1855@node in_network Selector Function, true Selector Function, netgrpd Selector Function, Selectors 1856@comment node-name, next, previous, up 1857@subsubsection in_network Selector Function 1858@cindex in_network Selector Function 1859@cindex in_network, boolean mount selector 1860@cindex !in_network, boolean mount selector 1861@cindex Mount selector; in_network 1862@cindex Selector; in_network 1863 1864This selector matches against any network name or number with an 1865optional netmask. First, if the current host has any network interface that is 1866locally attached to the network specified in @i{ARG} (either via name or 1867number), this selector evaluates to true. 1868 1869Second, @samp{in_network} supports a network/netmask syntax such as 1870@samp{128.59.16.0/255.255.255.0}, @samp{128.59.16.0/24}, 1871@samp{128.59.16.0/0xffffff00}, or @samp{128.59.16.0/}. Using the last 1872form, @i{Amd} will match the specified network number against the 1873default netmasks of each of the locally attached interfaces. 1874 1875If the selector does not match, it evaluates to false. 1876 1877For example, suppose you have two servers that have an exportable 1878@file{/opt} that smaller clients can NFS mount. The two servers are 1879say, @samp{serv1} on network @samp{foo-net.site.com} and @samp{serv2} on 1880network @samp{123.4.5.0}. You can write a map to be used by all clients 1881that will attempt to mount the closest one as follows: 1882 1883@example 1884opt in_network(foo-net.site.com);rhost:=serv1;rfs:=/opt \ 1885 in_network(123.4.5.0);rhost:=serv2;rfs:=/opt \ 1886 rhost:=fallback-server 1887@end example 1888 1889@c ---------------------------------------------------------------- 1890@node true Selector Function, xhost Selector Function, in_network Selector Function, Selectors 1891@comment node-name, next, previous, up 1892@subsubsection true Selector Function 1893@cindex true Selector Function 1894@cindex true, boolean mount selector 1895@cindex !true, boolean mount selector 1896@cindex Mount selector; true 1897@cindex Selector; true 1898 1899Always evaluates to true. @i{ARG} is ignored. 1900 1901@c ---------------------------------------------------------------- 1902@node xhost Selector Function, , true Selector Function, Selectors 1903@comment node-name, next, previous, up 1904@subsubsection xhost Selector Function 1905@cindex xhost Selector Function 1906@cindex xhost, boolean mount selector 1907@cindex !xhost, boolean mount selector 1908@cindex Mount selector; xhost 1909@cindex Selector; xhost 1910@cindex CNAMEs 1911 1912This function compares @i{ARG} against the current hostname, similarly 1913to the @ref{host Selector Variable}. However, this function will 1914also match if @i{ARG} is a CNAME (DNS Canonical Name, or alias) for 1915the current host's name. 1916 1917@c ================================================================ 1918@node Map Options, , Selectors, Location Format 1919@comment node-name, next, previous, up 1920@subsection Map Options 1921@cindex Map options 1922@cindex Setting map options 1923 1924Options are parsed concurrently with selectors. The difference is that 1925when an option is seen the string following the @samp{:=} is 1926recorded for later use. As a minimum the @var{type} option must be 1927specified. Each filesystem type has other options which must also be 1928specified. @xref{Filesystem Types}, for details on the filesystem 1929specific options.@refill 1930 1931Superfluous option specifications are ignored and are not reported 1932as errors. 1933 1934The following options apply to more than one filesystem type. 1935 1936@menu 1937* addopts Option:: 1938* delay Option:: 1939* fs Option:: 1940* opts Option:: 1941* remopts Option:: 1942* sublink Option:: 1943* type Option:: 1944@end menu 1945 1946@node addopts Option, delay Option, Map Options, Map Options 1947@comment node-name, next, previous, up 1948@subsubsection addopts Option 1949@cindex Setting additional options on a mount location 1950@cindex Overriding or adding options to a mount 1951@cindex addopts, mount option 1952@cindex Mount option; addopts 1953 1954This option adds additional options to default options normally 1955specified in the @samp{/defaults} entry or the defaults of the key entry 1956being processed (@pxref{opts Option}). Normally when you specify 1957@samp{opts} in both the @samp{/defaults} and the map entry, the latter 1958overrides the former completely. But with @samp{addopts} it will append 1959the options and override any conflicting ones. 1960 1961@samp{addopts} also overrides the value of the @samp{remopts} option 1962(@pxref{remopts Option}), which unless specified defaults to the value 1963of @samp{opts}. 1964 1965Options which start with @samp{no} will override those with the same 1966name that do not start with @samp{no} and vice verse. Special handling 1967is given to inverted options such as @samp{soft} and @samp{hard}, 1968@samp{bg} and @samp{fg}, @samp{ro} and @samp{rw}, etc. 1969 1970For example, if the default options specified were 1971@example 1972opts:=rw,nosuid,intr,rsize=1024,wsize=1024,quota,posix 1973@end example 1974 1975and the ones specified in a map entry were 1976 1977@example 1978addopts:=grpid,suid,ro,rsize=2048,quota,nointr 1979@end example 1980 1981then the actual options used would be 1982 1983@example 1984wsize=1024,posix,grpid,suid,ro,rsize=2048,quota,nointr 1985@end example 1986 1987@node delay Option, fs Option, addopts Option, Map Options 1988@comment node-name, next, previous, up 1989@subsubsection delay Option 1990@cindex Setting a delay on a mount location 1991@cindex Delaying mounts from specific locations 1992@cindex Primary server 1993@cindex Secondary server 1994@cindex delay, mount option 1995@cindex Mount option; delay 1996 1997The delay, in seconds, before an attempt will be made to mount from the 1998current location. Auxiliary data, such as network address, file handles 1999and so on are computed regardless of this value. 2000 2001A delay can be used to implement the notion of primary and secondary 2002file servers. The secondary servers would have a delay of a few 2003seconds, thus giving the primary servers a chance to respond first. 2004 2005@node fs Option, opts Option, delay Option, Map Options 2006@comment node-name, next, previous, up 2007@subsubsection fs Option 2008@cindex Setting the local mount point 2009@cindex Overriding the default mount point 2010@cindex fs, mount option 2011@cindex Mount option; fs 2012 2013The local mount point. The semantics of this option vary between 2014filesystems. 2015 2016For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the 2017local mount point. For other filesystem types it has other meanings 2018which are described in the section describing the respective filesystem 2019type. It is important that this string uniquely identifies the 2020filesystem being mounted. To satisfy this requirement, it should 2021contain the name of the host on which the filesystem is resident and the 2022pathname of the filesystem on the local or remote host. 2023 2024The reason for requiring the hostname is clear if replicated filesystems 2025are considered. If a fileserver goes down and a replacement filesystem 2026is mounted then the @dfn{local} mount point @dfn{must} be different from 2027that of the filesystem which is hung. Some encoding of the filesystem 2028name is required if more than one filesystem is to be mounted from any 2029given host. 2030 2031If the hostname is first in the path then all mounts from a particular 2032host will be gathered below a single directory. If that server goes 2033down then the hung mount points are less likely to be accidentally 2034referenced, for example when @b{getcwd}(3) traverses the namespace to 2035find the pathname of the current directory. 2036 2037The @samp{fs} option defaults to 2038@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, 2039@samp{rhost} defaults to the local host name (@code{$@{host@}}) and 2040@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full 2041path of the requested file; @samp{/home/foo} in the example above 2042(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may 2043be changed with the @code{-a} command line option. Sun's automounter 2044defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between 2045the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins 2046with a @samp{/}.@refill 2047 2048@node opts Option, remopts Option, fs Option, Map Options 2049@comment node-name, next, previous, up 2050@subsubsection opts Option 2051@cindex Setting system mount options 2052@cindex Passing parameters to the mount system call 2053@cindex mount system call 2054@cindex mount system call flags 2055@cindex The mount system call 2056@cindex opts, mount option 2057@cindex Mount option; opts 2058 2059The options to pass to the mount system call. A leading @samp{-} is 2060silently ignored. The mount options supported generally correspond to 2061those used by @b{mount}(8) and are listed below. Some additional 2062pseudo-options are interpreted by @i{Amd} and are also listed. 2063 2064Unless specifically overridden, each of the system default mount options 2065applies. Any options not recognized are ignored. If no options list is 2066supplied the string @samp{rw,defaults} is used and all the system 2067default mount options apply. Options which are not applicable for a 2068particular operating system are silently ignored. For example, only 4.4BSD 2069is known to implement the @code{compress} and @code{spongy} options. 2070 2071@table @code 2072 2073@item acdirmax=@var{n} 2074@cindex Mount flags; acdirmax 2075Set the maximum directory attribute cache timeout to @var{n}. 2076 2077@item acdirmin=@var{n} 2078@cindex Mount flags; acdirmin 2079Set the minimum directory attribute cache timeout to @var{n}. 2080 2081@item acregmax=@var{n} 2082@cindex Mount flags; acregmax 2083Set the maximum file attribute cache timeout to @var{n}. 2084 2085@item acregmin=@var{n} 2086@cindex Mount flags; acregmin 2087Set the minimum file attribute cache timeout to @var{n}. 2088 2089@item actimeo=@var{n} 2090@cindex Mount flags; actimeo 2091Set the overall attribute cache timeout to @var{n}. 2092 2093@item auto 2094@cindex Mount flags; auto 2095@itemx ignore 2096@cindex Mount flags; ignore 2097Ignore this mount by @b{df}(1). 2098 2099@item cache 2100@cindex Mount flags; cache 2101Allow data to be cached from a remote server for this mount. 2102 2103@item closesession 2104@cindex Mount flags; closesession 2105For UDF mounts, close the session when unmounting. 2106 2107@item compress 2108@cindex Mount flags; compress 2109Use NFS compression protocol. 2110 2111@item defperm 2112@cindex Mount flags; defperm 2113Ignore the permission mode bits, and default file permissions to 0555, 2114UID 0, and GID 0. Useful for CD-ROMs formatted as ISO-9660. 2115 2116@item dev 2117@cindex Mount flags; dev 2118Allow local special devices on this filesystem. 2119 2120@item dirmask=@var{n} 2121@cindex Mount flags; dirmask 2122For PCFS mounts, specify the maximum file permissions for directories 2123in the file system. See the @samp{mask} option's description for more 2124details. The mask value of @var{n} can be specified in decimal, 2125octal, or hexadecimal. 2126 2127@item dumbtimr 2128@cindex Mount flags; dumbtimr 2129Turn off the dynamic retransmit timeout estimator. This may be useful 2130for UDP mounts that exhibit high retry rates, since it is possible that 2131the dynamically estimated timeout interval is too short. 2132 2133@item extatt 2134@cindex Mount flags; extatt 2135Enable extended attributes in ISO-9660 file systems. 2136 2137@item fsid 2138@cindex Mount flags; fsid 2139Set ID of filesystem. 2140 2141@item gens 2142@cindex Mount flags; gens 2143Enable generations in ISO-9660 file systems. Generations allow you to 2144see all versions of a given file. 2145 2146@item gmtoff=@var{n} 2147@cindex Mount flags; gmtoff 2148For UDF mounts, set the time zone offset from UTC to @var{n} seconds, 2149with positive values indicating east of the Prime Meridian. If not 2150set, the user's current time zone will be used. 2151 2152@item group=@var{n} 2153@cindex Mount flags; group 2154For PCFS and UDF mounts, set the group of the files in the file system 2155to @var{n} (which can either be a group name or a GID number). The 2156default group is the group of the directory on which the file system 2157is being mounted. 2158 2159@item grpid 2160@cindex Mount flags; grpid 2161Use BSD directory group-id semantics. 2162 2163@item int 2164@cindex Mount flags; int 2165@itemx intr 2166@cindex Mount flags; intr 2167Allow keyboard interrupts on hard mounts. 2168 2169@item lock 2170@cindex Mount flags; lock 2171Use the NFS locking protocol (default) 2172 2173@item longname 2174@cindex Mount Flags; longname 2175For PCFS mounts, force Win95 long names. 2176 2177@item mask=@var{n} 2178@cindex Mount flags; mask 2179For PCFS mounts, specify the maximum file permissions for files in the 2180file system. For example, a mask of 755 specifies that, by default, 2181the owner should have read, write, and execute permissions for files, 2182but others should only have read and execute permissions. Only the 2183nine low-order bits of mask are used. The default mask is taken from 2184the directory on which the file system is being mounted. The mask 2185value of @var{n} can be specified in decimal, octal, or hexadecimal. 2186 2187@item multi 2188@cindex Mount flags; multi 2189Perform multi-component lookup on files. 2190 2191@item maxgroups 2192@cindex Mount flags; maxgroups 2193Set the maximum number of groups to allow for this mount. 2194 2195@item nfsv3 2196@cindex Mount flags; nfsv3 2197Use NFS Version 3 for this mount. 2198 2199@item noac 2200@cindex Mount flags; noac 2201Turn off the attribute cache. 2202 2203@item noauto 2204@cindex Mount flags; noauto 2205This option is used by the mount command in @samp{/etc/fstab} or 2206@samp{/etc/vfstab} and means not to mount this file system when mount -a 2207is used. 2208 2209@item nocache 2210@cindex Mount flags; nocache 2211Do not allow data to be cached from a remote server for this 2212mount. 2213 2214@item nocasetrans 2215@cindex Mount flags; nocasetrans 2216Don't do case translation. Useful for CD-ROMS formatted as 2217ISO-9660. 2218 2219@item noconn 2220@cindex Mount flags; noconn 2221Don't make a connection on datagram transports. 2222 2223@item nocto 2224@cindex Mount flags; nocto 2225No close-to-open consistency. 2226 2227@item nodefperm 2228@cindex Mount flags; nodefperm 2229Do not ignore the permission mode bits. Useful for CD-ROMS formatted as 2230ISO-9660. 2231 2232@item nodev 2233@cindex Mount flags; nodev 2234@itemx nodevs 2235@cindex Mount flags; nodevs 2236Don't allow local special devices on this filesystem. 2237 2238@item noexec 2239@cindex Mount flags; noexec 2240Don't allow program execution. 2241 2242@item noint 2243@cindex Mount flags; noint 2244Do not allow keyboard interrupts for this mount 2245 2246@item nojoliet 2247@cindex Mount flags; nojoliet 2248Turn off the Joliet extensions. Useful for CD-ROMS formatted as ISO-9660. 2249 2250@item nolock 2251@cindex Mount flags; nolock 2252Do not use the NFS locking protocol 2253 2254@item nomnttab 2255@cindex Mount flags; nomnttab 2256This option is used internally to tell Amd that a Solaris 8 system using 2257mntfs is in use. 2258 2259@item norrip 2260@cindex Mount flags; norrip 2261Turn off using of the Rock Ridge Interchange Protocol (RRIP) extensions 2262to ISO-9660. 2263 2264@item nosub 2265@cindex Mount flags; nosub 2266Disallow mounts beneath this mount. 2267 2268@item nosuid 2269@cindex Mount flags; nosuid 2270Don't allow set-uid or set-gid executables on this filesystem. 2271 2272@item noversion 2273@cindex Mount flags; noversion 2274Strip the extension @samp{;#} from the version string of files recorded 2275on an ISO-9660 CD-ROM. 2276 2277@item nowin95 2278@cindex Mount Flags; nowin95 2279For PCFS mounts, completely ignore Win95 entries. 2280 2281@item optionstr 2282@cindex Mount flags; optionstr 2283Under Solaris 8, provide the kernel a string of options to parse and 2284show as part of the special in-kernel mount file system. 2285 2286@item overlay 2287@cindex Mount flags; overlay 2288Overlay this mount on top of an existing mount, if any. 2289 2290@item pgthresh=@var{n} 2291@cindex Mount flags; pgthresh 2292Set the paging threshold to @var{n} kilobytes. 2293 2294@item port=@var{n} 2295@cindex Mount flags; port 2296Set the NFS port to @var{n}. 2297 2298@item posix 2299@cindex Mount flags; posix 2300Turn on POSIX static pathconf for mounts. 2301 2302@item private 2303@cindex Mount flags; private 2304Use local locking instead of the NLM protocol, useful for IRIX 6 only. 2305 2306@item proplist 2307@cindex Mount flags; proplist 2308Support property lists (ACLs) for this mount, useful primarily for Tru64 2309UNIX. 2310 2311@item proto=@var{s} 2312@cindex Mount flags; proto 2313Use transport protocol @var{s} for NFS (can be @code{"tcp"} or @code{"udp"}). 2314 2315@item quota 2316@cindex Mount flags; quota 2317Enable quota checking on this mount. 2318 2319@item rdonly 2320@cindex Mount flags; rdonly 2321@itemx ro 2322@cindex Mount flags; ro 2323Mount this filesystem readonly. 2324 2325@item resvport 2326@cindex Mount flags; resvport 2327Use a reserved port (smaller than 1024) for remote NFS mounts. Most 2328systems assume that, but some allow for mounts to occur on non-reserved 2329ports. This causes problems when such a system tries to NFS mount one 2330that requires reserved ports. It is recommended that this option always 2331be on. 2332 2333@item retrans=@i{n} 2334@cindex Mount flags; retrans 2335The number of NFS retransmits made before a user error is generated by a 2336@samp{soft} mounted filesystem, and before a @samp{hard} mounted 2337filesystem reports @samp{NFS server @dfn{yoyo} not responding still 2338trying}. 2339 2340@item retry 2341@cindex Mount flags; retry 2342Set the NFS retry counter. 2343 2344@item rrcaseins 2345@cindex Mount flags; rrcaseins 2346Enable the Rock Ridge Interchange Protocol (RRIP) case insensitive extensions. 2347Useful for CD-ROMS formatted as ISO-9660. 2348 2349@item rrip 2350@cindex Mount flags; rrip 2351Uses the Rock Ridge Interchange Protocol (RRIP) extensions to ISO-9660. 2352 2353@item rsize=@var{n} 2354@cindex Mount flags; rsize 2355The NFS read packet size. You may need to set this if you are using 2356NFS/UDP through a gateway or a slow link. 2357 2358@item rw 2359@cindex Mount flags; rw 2360Allow reads and writes on this filesystem. 2361 2362@item sessionnr=@var{n} 2363@cindex Mount Flags; sessionnr 2364For multisession UDF mounts, use session number @var{n} when mounting. 2365 2366@item shortname 2367@cindex Mount Flags; longname 2368For PCFS mounts, force old DOS short names only. 2369 2370@item soft 2371@cindex Mount flags; soft 2372Give up after @dfn{retrans} retransmissions. 2373 2374@item spongy 2375@cindex Mount flags; spongy 2376Like @samp{soft} for status requests, and @samp{hard} for data transfers. 2377 2378@item suid 2379@cindex Mount flags; suid 2380Allow set-uid programs on this mount. 2381 2382@item symttl 2383@cindex Mount flags; symttl 2384Turn off the symbolic link cache time-to-live. 2385 2386@item sync 2387@cindex Mount flags; sync 2388Perform synchronous filesystem operations on this mount. 2389 2390@item tcp 2391@cindex Mount flags; tcp 2392Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not 2393support TCP/IP mounts. 2394 2395@item timeo=@var{n} 2396@cindex Mount flags; timeo 2397The NFS timeout, in tenth-seconds, before a request is retransmitted. 2398 2399@item user=@var{n} 2400@cindex Mount flags; user 2401For PCFS and UDF mounts, set the owner of the files in the file system 2402to @var{n} (which can either be a user name or a UID number). The 2403default owner is the owner of the directory on which the file system 2404is being mounted. 2405 2406@item vers=@var{n} 2407@cindex Mount flags; vers 2408Use NFS protocol version number @var{n} (can be 2 or 3). 2409 2410@item wsize=@var{n} 2411@cindex Mount flags; wsize 2412The NFS write packet size. You may need to set this if you are using 2413NFS/UDP through a gateway or a slow link. 2414 2415@end table 2416 2417The following options are implemented by @i{Amd}, rather than being 2418passed to the kernel. 2419 2420@table @code 2421 2422@item nounmount 2423@cindex Mount flags; nounmount 2424Configures the mount so that its time-to-live will never expire. This 2425is the default for non-network based filesystem types (such as 2426mounting local disks, floppies, and CD-ROMs). See also the related 2427@i{unmount} option. 2428@c 2429@c Implementation broken: 2430 2431@item ping=@var{n} 2432@cindex Mount flags; ping 2433The interval, in seconds, between keep-alive pings. When four 2434consecutive pings have failed the mount point is marked as hung. This 2435interval defaults to 30 seconds; if the ping interval is set to zero, 2436@i{Amd} will use the default 30-second interval. If the interval is 2437set to -1 (or any other negative value), no pings are sent and the 2438host is assumed to be always up, which can cause unmounts to hang See 2439the @i{softlookup} option for a better alternative. Turning pings off 2440can be useful in NFS-HA (High-Availability) sites where the NFS 2441service rarely goes down. Setting the ping value to a large value can 2442reduce the amount of NFS_NULL chatter on your network considerably, 2443especially in large sites. 2444 2445Note that if you have multiple @i{Amd} entries using the same file 2446server, and each entry sets a different value of N, then each time Amd 2447mounts a new entry, the ping value will be re-evaluated (and updated, 2448turned off, or turned back on as needed). Finally, note that NFS_NULL 2449pings are sent for both UDP and TCP mounts, because even a hung TCP 2450mount can cause user processes to hang. 2451 2452@item public 2453@cindex Mount flags; public 2454Use WebNFS multi-component lookup on the public file handle instead of 2455the mount protocol to obtain NFS file handles, as documented in the 2456WebNFS Client Specification, RFC 2054. This means that @i{Amd} will not 2457attempt to contact the remote portmapper or remote mountd daemon, and 2458will only connect to the well-known NFS port 2049 or the port specified 2459with the @i{port} mount option, thus making it easier to use NFS through 2460a firewall. 2461 2462@item retry=@var{n} 2463@cindex Mount flags; retry=@var{n} 2464The number of times to retry the mount system call. 2465 2466@item softlookup 2467@cindex Mount flags; softlookup 2468Configures @i{Amd}'s behavior with respect to already-mounted shares from 2469NFS fileservers that are unreachable. If softlookup is specified, 2470trying to access such a share will result in an error (EIO, which is 2471changed from the ENOENT 6.0 used to return). If it is not specified, a 2472regular symlink is provided and the access will probably hang 2473in the NFS filesystem. 2474 2475The default behavior depends on whether the mount is 'soft' or 'hard'; 2476softlookup can be used to change this default. This is changed from 6.0 2477which always behaved as if softlookup was specified. 2478 2479@item unmount 2480@cindex Mount flags; unmount 2481Configures the mount so that its time-to-live will indeed expire (and 2482thus may be automatically unmounted). This is also the default for 2483network-based filesystem types (e.g., NFS). This option is useful for 2484removable local media such as CD-ROMs, USB drives, etc. so they can 2485expire when not in use, and get unmounted (such drives can get work 2486out when they keep spinning). See also the related @i{nounmount} 2487option. 2488 2489@item utimeout=@var{n} 2490@cindex Mount flags; utimeout=@var{n} 2491The interval, in seconds, that looked up and mounted map entries are 2492cached. After that period of time, @i{Amd} will attempt to unmount 2493the entries. If, however, the unmount fails (with EBUSY), then 2494@i{Amd} will extend the mount's time-to-live by the @i{utimeout} value 2495before the next unmount attempt is made. In fact the interval is 2496extended before the unmount is attempted, to avoid thrashing. The 2497default value is 120 seconds (two minutes) or as set by the @code{-w} 2498command line option. 2499 2500@item xlatecookie 2501@cindex Mount flags; xlatecookie 2502Translate directory cookies between 32-long and 64-long lengths. 2503 2504@end table 2505 2506@node remopts Option, sublink Option, opts Option, Map Options 2507@comment node-name, next, previous, up 2508@subsubsection remopts Option 2509@cindex Setting system mount options for non-local networks 2510@cindex remopts, mount option 2511@cindex Mount option; remopts 2512 2513This option has the same use as @code{$@{opts@}} but applies only when 2514the remote host is on a non-local network. For example, when using NFS 2515across a gateway it is often necessary to use smaller values for the 2516data read and write sizes. This can simply be done by specifying the 2517small values in @var{remopts}. When a non-local host is accessed, the 2518smaller sizes will automatically be used. 2519 2520@i{Amd} determines whether a host is local by examining the network 2521interface configuration at startup. Any interface changes made after 2522@i{Amd} has been started will not be noticed. The likely effect will 2523be that a host may incorrectly be declared non-local. 2524 2525Unless otherwise set, the value of @code{$@{remopts@}} is the same as 2526the value of @code{$@{opts@}}. 2527 2528@node sublink Option, type Option, remopts Option, Map Options 2529@comment node-name, next, previous, up 2530@subsubsection sublink Option 2531@cindex Setting the sublink option 2532@cindex sublink, mount option 2533@cindex Mount option; sublink 2534 2535The subdirectory within the mounted filesystem to which the reference 2536should point. This can be used to prevent duplicate mounts in cases 2537where multiple directories in the same mounted filesystem are used. 2538 2539@node type Option, , sublink Option, Map Options 2540@comment node-name, next, previous, up 2541@subsubsection type Option 2542@cindex Setting the filesystem type option 2543@cindex type, mount option 2544@cindex Mount option; type 2545 2546The filesystem type to be used. @xref{Filesystem Types}, for a full 2547description of each type.@refill 2548 2549@c ################################################################ 2550@node Amd Command Line Options, Filesystem Types, Mount Maps, Top 2551@comment node-name, next, previous, up 2552@chapter @i{Amd} Command Line Options 2553@cindex Command line options, Amd 2554@cindex Amd command line options 2555@cindex Overriding defaults on the command line 2556 2557Many of @i{Amd}'s parameters can be set from the command line. The 2558command line is also used to specify automount points and maps. 2559 2560The general format of a command line is 2561 2562@example 2563amd [@i{options}] [@{ @i{directory} @i{map-name} [-@i{map-options}] @} ...] 2564@end example 2565 2566For each directory and map-name given or specified in the 2567@file{amd.conf} file, @i{Amd} establishes an automount point. The 2568@dfn{map-options} may be any sequence of options or 2569selectors---@pxref{Location Format}. The @dfn{map-options} apply only 2570to @i{Amd}'s mount point. 2571 2572@samp{type:=toplvl;cache:=mapdefault;fs:=$@{map@}} is the default value for the 2573map options. Default options for a map are read from a special entry in 2574the map whose key is the string @samp{/defaults}. When default options 2575are given they are prepended to any options specified in the mount-map 2576locations as explained in @ref{Map Defaults}. 2577 2578The @dfn{options} are any combination of those listed below. 2579 2580Once the command line has been parsed, the automount points are mounted. 2581The mount points are created if they do not already exist, in which case they 2582will be removed when @i{Amd} exits. 2583Finally, @i{Amd} disassociates itself from its controlling terminal and 2584forks into the background. 2585 2586Note: Even if @i{Amd} has been built with @samp{-DDEBUG} (via 2587@code{configure --enable-debug}), it will still background itself and 2588disassociate itself from the controlling terminal. To use a debugger it 2589is necessary to specify @samp{-D daemon} on the command line. 2590However, even with all of this, mounts and unmounts are performed in the 2591background, and @i{Amd} will always fork before doing them. Therefore, 2592debugging what happens closely during un/mounts is more challenging. 2593 2594@emph{All} of @i{Amd}'s command options (save @code{-F} and @code{-T}) 2595can be specified in the @file{amd.conf} file. @xref{Amd Configuration 2596File}. If @i{Amd} is invoked without any command line options, it will 2597default to using the configuration file @file{/etc/amd.conf}, if one 2598exists. 2599 2600@menu 2601* -a Option:: Automount directory. 2602* -c Option:: Cache timeout interval. 2603* -d Option:: Domain name. 2604* -k Option:: Kernel architecture. 2605* -l Option:: Log file. 2606* -n Option:: Hostname normalization. 2607* -o Option:: Operating system version. 2608* -p Option:: Output process id. 2609* -r Option:: Restart existing mounts. 2610* -t Option:: Kernel RPC timeout. 2611* -v Option:: Version information. 2612* -w Option:: Wait interval after failed unmount. 2613* -x Option:: Log options. 2614* -y Option:: NIS domain. 2615* -A Option:: Operating system Architecture. 2616* -C Option:: Cluster name. 2617* -D Option:: Debug flags. 2618* -F Option:: Amd configuration file. 2619* -H Option:: Show brief help. 2620* -O Option:: Operating system name. 2621* -S Option:: Lock executable pages in memory. 2622* -T Option:: Set tag for configuration file. 2623@end menu 2624 2625@c ---------------------------------------------------------------- 2626@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options 2627@comment node-name, next, previous, up 2628@section @code{-a} @var{directory} 2629@cindex Automount directory 2630@cindex Setting the default mount directory 2631 2632Specifies the default mount directory. This option changes the variable 2633@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, 2634some sites prefer @file{/amd} or @file{/n}. 2635 2636@example 2637amd -a /amd ... 2638@end example 2639 2640@c ---------------------------------------------------------------- 2641@node -c Option, -d Option, -a Option, Amd Command Line Options 2642@comment node-name, next, previous, up 2643@section @code{-c} @var{cache-interval} 2644@cindex Cache interval 2645@cindex Interval before a filesystem times out 2646@cindex Setting the interval before a filesystem times out 2647@cindex Changing the interval before a filesystem times out 2648 2649Selects the period, in seconds, for which a name is cached by @i{Amd}. 2650If no reference is made to the volume in this period, @i{Amd} discards 2651the volume name to filesystem mapping. 2652 2653Once the last reference to a filesystem has been removed, @i{Amd} 2654attempts to unmount the filesystem. If the unmount fails the interval 2655is extended by a further period as specified by the @samp{-w} command 2656line option or by the @samp{utimeout} mount option. 2657 2658The default @dfn{cache-interval} is 300 seconds (five minutes). 2659 2660@c ---------------------------------------------------------------- 2661@node -d Option, -k Option, -c Option, Amd Command Line Options 2662@comment node-name, next, previous, up 2663@section @code{-d} @var{domain} 2664@cindex Domain name 2665@cindex Setting the local domain name 2666@cindex Overriding the local domain name 2667 2668Specifies the host's domain. This sets the internal variable 2669@code{$@{domain@}} and affects the @code{$@{hostd@}} variable. 2670 2671If this option is not specified and the hostname already contains the 2672local domain then that is used, otherwise the default value of 2673@code{$@{domain@}} is @samp{unknown.domain}. 2674 2675For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could 2676be started as follows: 2677 2678@example 2679amd -d doc.ic.ac.uk ... 2680@end example 2681 2682@c ---------------------------------------------------------------- 2683@node -k Option, -l Option, -d Option, Amd Command Line Options 2684@comment node-name, next, previous, up 2685@section @code{-k} @var{kernel-architecture} 2686@cindex Setting the Kernel architecture 2687 2688Specifies the kernel architecture of the system. This is usually the 2689output of @samp{uname -m} (the ``machine'' value gotten from 2690@b{uname}(2)). If the @b{uname}(2) system call is not available, the 2691value of @code{$@{karch@}} defaults to that of @code{$@{arch@}}. 2692 2693The only effect of this option is to set the variable @code{$@{karch@}}. 2694 2695This option would be used as follows: 2696 2697@example 2698amd -k `arch -k` ... 2699@end example 2700 2701@c ---------------------------------------------------------------- 2702@node -l Option, -n Option, -k Option, Amd Command Line Options 2703@comment node-name, next, previous, up 2704@section @code{-l} @var{log-option} 2705@cindex Log filename 2706@cindex Setting the log file 2707@cindex Using syslog to log errors 2708@cindex syslog 2709 2710Selects the form of logging to be made. Several special @dfn{log-options} 2711are recognized. 2712 2713@enumerate 2714@item 2715If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the 2716@b{syslog}(3) mechanism. If your system supports syslog facilities, then 2717the default facility used is @samp{LOG_DAEMON}. 2718 2719@item 2720@cindex syslog facility; specifying an alternate 2721When using syslog, if you wish to change the facility, append its name 2722to the log option name, delimited by a single colon. For example, if 2723@dfn{log-options} is the string @samp{syslog:local7} then @b{Amd} will 2724log messages via @b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If 2725the facility name specified is not recognized, @i{Amd} will default to 2726@samp{LOG_DAEMON}. Note: while you can use any syslog facility 2727available on your system, it is generally a bad idea to use those 2728reserved for other services such as @samp{kern}, @samp{lpr}, 2729@samp{cron}, etc. 2730 2731@item 2732If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use 2733standard error, which is also the default target for log messages. To 2734implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} 2735driver. 2736@end enumerate 2737 2738Any other string is taken as a filename to use for logging. Log 2739messages are appended to the file if it already exists, otherwise a new 2740file is created. The file is opened once and then held open, rather 2741than being re-opened for each message. 2742 2743Normally, when long-running daemons hold an open file descriptor on a 2744log file, it is impossible to ``rotate'' the log file and compress older 2745logs on a daily basis. The daemon needs to be told to discard (via 2746@b{close}(2)) its file handle, and re-open the log file. This is done 2747using @code{amq -l} @i{log-option}. @xref{Amq -l option}. 2748 2749If the @samp{syslog} option is specified but the system does not support 2750syslog or if the named file cannot be opened or created, @i{Amd} will 2751use standard error. Error messages generated before @i{Amd} has 2752finished parsing the command line are printed on standard error. 2753 2754Since @i{Amd} tends to generate a lot of logging information (especially 2755if debugging was turned on), and due to it being an important program 2756running on the system, it is usually best to log to a separate disk 2757file. In that case @i{Amd} would be started as follows: 2758 2759@example 2760amd -l /var/log/amd ... 2761@end example 2762 2763@c ---------------------------------------------------------------- 2764@node -n Option, -o Option, -l Option, Amd Command Line Options 2765@comment node-name, next, previous, up 2766@section @code{-n} 2767@cindex Hostname normalization 2768@cindex Aliased hostnames 2769@cindex Resolving aliased hostnames 2770@cindex Normalizing hostnames 2771 2772Normalizes the remote hostname before using it. Normalization is done 2773by replacing the value of @code{$@{rhost@}} with the (generally fully 2774qualified) primary name returned by a hostname lookup. 2775 2776This option should be used if several names are used to refer to a 2777single host in a mount map. 2778 2779@c ---------------------------------------------------------------- 2780@node -o Option, -p Option, -n Option, Amd Command Line Options 2781@comment node-name, next, previous, up 2782@section @code{-o} @var{op-sys-ver} 2783@cindex Operating System version 2784@cindex Setting the Operating System version 2785 2786Overrides the compiled-in version number of the operating system, with 2787@var{op-sys-ver}. Useful when the built-in version is not desired for 2788backward compatibility reasons. For example, if the built-in version is 2789@samp{2.5.1}, you can override it to @samp{5.5.1}, and use older maps 2790that were written with the latter in mind. 2791 2792@c ---------------------------------------------------------------- 2793@node -p Option, -r Option, -o Option, Amd Command Line Options 2794@comment node-name, next, previous, up 2795@section @code{-p} 2796@cindex Process id 2797@cindex Displaying the process id 2798@cindex process id of Amd daemon 2799@cindex pid file, creating with -p option 2800@cindex Creating a pid file 2801 2802Causes @i{Amd}'s process id to be printed on standard output. 2803This can be redirected to a suitable file for use with kill: 2804 2805@example 2806amd -p > /var/run/amd.pid ... 2807@end example 2808 2809This option only has an affect if @i{Amd} is running in daemon mode. 2810If @i{Amd} is started with the @code{-D daemon} debug flag, this 2811option is ignored. 2812 2813@c ---------------------------------------------------------------- 2814@node -r Option, -t Option, -p Option, Amd Command Line Options 2815@comment node-name, next, previous, up 2816@section @code{-r} 2817@cindex Restarting existing mounts 2818@cindex Picking up existing mounts 2819 2820Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). 2821@c @dfn{This option will be made the default in the next release.} 2822 2823@c ---------------------------------------------------------------- 2824@node -t Option, -v Option, -r Option, Amd Command Line Options 2825@comment node-name, next, previous, up 2826@section @code{-t} @var{timeout.retransmit} 2827@cindex Setting Amd's RPC parameters 2828 2829Specifies the RPC @dfn{timeout} interval and the @dfn{retransmit} 2830counter used by the kernel to communicate to @i{Amd}. These are used to 2831set the @samp{timeo} and @samp{retrans} mount options, respectively. 2832The default timeout is 0.8 seconds, and the default number of 2833retransmissions is 11. 2834 2835@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 2836retries. The values of these parameters change the overall retry 2837interval. Too long an interval gives poor interactive response; too 2838short an interval causes excessive retries. 2839 2840@c ---------------------------------------------------------------- 2841@node -v Option, -w Option, -t Option, Amd Command Line Options 2842@comment node-name, next, previous, up 2843@section @code{-v} 2844@cindex Version information 2845@cindex Discovering version information 2846@cindex How to discover your version of Amd 2847 2848Print version information on standard error and then exit. The output 2849is of the form: 2850 2851@example 2852Copyright (c) 1997-1999 Erez Zadok 2853Copyright (c) 1990 Jan-Simon Pendry 2854Copyright (c) 1990 Imperial College of Science, Technology & Medicine 2855Copyright (c) 1990 The Regents of the University of California. 2856am-utils version 6.0a15 (build 61). 2857Built by ezk@@example.com on date Wed Oct 22 15:21:03 EDT 1997. 2858cpu=sparc (big-endian), arch=sun4, karch=sun4u. 2859full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun. 2860Map support for: root, passwd, union, nisplus, nis, ndbm, file, error. 2861AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit, 2862 ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error. 2863FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, udf, ufs. 2864Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13). 2865Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14). 2866Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16). 2867@end example 2868 2869The information includes the version number, number of times @i{Amd} was 2870compiled on the local system, release date and name of the release. 2871Following come the cpu type, byte ordering, and the architecture and 2872kernel architecture as @code{$@{arch@}} and @code{$@{karch@}}, 2873respectively. The next line lists the operating system full name, short 2874name, version, and vendor. These four values correspond to the 2875variables @code{$@{full_os@}}, @code{$@{os@}}, @code{$@{osver@}}, and 2876@code{$@{vendor@}}, respectively. @xref{Supported Platforms}. 2877 2878Then come a list of map types supported, filesystems internally 2879supported by @i{Amd} (AMFS), and generic filesystems available (FS). 2880Finally all known networks (if any) of this host are listed by name 2881and number. They are available via the variables 2882@code{$@{wire@}} or @code{$@{network@}}, and 2883@code{$@{netnumber@}} (@pxref{Selectors}) or the @samp{in_network} 2884selector function (@pxref{in_network Selector Function}). 2885 2886@c ---------------------------------------------------------------- 2887@node -w Option, -x Option, -v Option, Amd Command Line Options 2888@comment node-name, next, previous, up 2889@section @code{-w} @var{wait-timeout} 2890@cindex Setting the interval between unmount attempts 2891@cindex unmount attempt backoff interval 2892 2893Selects the interval in seconds between unmount attempts after the 2894initial time-to-live has expired. 2895 2896This defaults to 120 seconds (two minutes). 2897 2898@c ---------------------------------------------------------------- 2899@node -x Option, -y Option, -w Option, Amd Command Line Options 2900@comment node-name, next, previous, up 2901@section @code{-x} @var{opts} 2902@cindex Log message selection 2903@cindex Selecting specific log messages 2904@cindex How to select log messages 2905@cindex syslog priorities 2906 2907Specifies the type and verbosity of log messages. @dfn{opts} is 2908a comma separated list selected from the following options: 2909 2910@table @code 2911@item fatal 2912Fatal errors (cannot be turned off) 2913@item error 2914Non-fatal errors (cannot be turned off) 2915@item user 2916Non-fatal user errors 2917@item warn 2918Recoverable errors 2919@item warning 2920Alias for @code{warn} 2921@item info 2922Information messages 2923@item map 2924Mount map usage 2925@item stats 2926Additional statistics 2927@item all 2928All of the above 2929@item defaults 2930An alias for "fatal,error,user,warning,info". 2931@end table 2932 2933Initially a set of default logging flags is enabled. This is as if 2934@samp{-x defaults} 2935or 2936@samp{-x fatal,error,user,warning,info} 2937had been selected. The command line is 2938parsed and logging is controlled by the @code{-x} option. The very first 2939set of logging flags is saved and can not be subsequently disabled using 2940@i{Amq}. This default set of options is useful for general production 2941use.@refill 2942 2943The @samp{info} messages include details of what is mounted and 2944unmounted and when filesystems have timed out. If you want to have the 2945default set of messages without the @samp{info} messages then you simply 2946need @samp{-x noinfo}. The messages given by @samp{user} relate to 2947errors in the mount maps, so these are useful when new maps are 2948installed. The following table lists the syslog priorities used for each 2949of the message types.@refill 2950 2951@table @code 2952@item fatal 2953@samp{LOG_CRIT} 2954@item error 2955@samp{LOG_ERR} 2956@item user 2957@samp{LOG_WARNING} 2958@item warning 2959@samp{LOG_WARNING} 2960@item info 2961@samp{LOG_INFO} 2962@item debug 2963@samp{LOG_DEBUG} 2964@item map 2965@samp{LOG_DEBUG} 2966@item stats 2967@samp{LOG_INFO} 2968@end table 2969 2970The options can be prefixed by the string @samp{no} to indicate 2971that this option should be turned off. For example, to obtain all 2972but @samp{info} messages the option @samp{-x all,noinfo} would be used. 2973 2974If @i{Amd} was built with debugging enabled the @code{debug} option is 2975automatically enabled regardless of the command line options. 2976 2977@c ---------------------------------------------------------------- 2978@node -y Option, -A Option, -x Option, Amd Command Line Options 2979@comment node-name, next, previous, up 2980@section @code{-y} @var{NIS-domain} 2981@cindex NIS (YP) domain name 2982@cindex Overriding the NIS (YP) domain name 2983@cindex Setting the NIS (YP) domain name 2984@cindex YP domain name 2985 2986Selects an alternate NIS domain. This is useful for debugging and 2987cross-domain shared mounting. If this flag is specified, @i{Amd} 2988immediately attempts to bind to a server for this domain. 2989@c @i{Amd} refers to NIS maps when it starts, unless the @code{-m} option 2990@c is specified, and whenever required in a mount map. 2991 2992@c ---------------------------------------------------------------- 2993@node -A Option, -C Option, -y Option, Amd Command Line Options 2994@comment node-name, next, previous, up 2995@section @code{-A} @var{architecture} 2996@cindex Setting the operating system architecture 2997 2998Specifies the OS architecture of the system. 2999The only effect of this option is to set the variable @code{$@{arch@}}. 3000 3001This option would be used as follows: 3002 3003@example 3004amd -A i386 ... 3005@end example 3006 3007@c ---------------------------------------------------------------- 3008@node -C Option, -D Option, -A Option, Amd Command Line Options 3009@comment node-name, next, previous, up 3010@section @code{-C} @var{cluster-name} 3011@cindex Cluster names 3012@cindex Setting the cluster name 3013 3014Specifies the name of the cluster of which the local machine is a member. 3015The only effect is to set the variable @code{$@{cluster@}}. 3016The @dfn{cluster-name} is will usually obtained by running another command which uses 3017a database to map the local hostname into a cluster name. 3018@code{$@{cluster@}} can then be used as a selector to restrict mounting of 3019replicated data. 3020If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. 3021This would be used as follows: 3022 3023@example 3024amd -C `clustername` ... 3025@end example 3026 3027@c ---------------------------------------------------------------- 3028@node -D Option, -F Option, -C Option, Amd Command Line Options 3029@comment node-name, next, previous, up 3030@section @code{-D} @var{opts} 3031@cindex Debug options 3032@cindex Setting debug flags 3033 3034Controls the verbosity and coverage of the debugging trace; @dfn{opts} 3035is a comma separated list of debugging options. The @code{-D} option is 3036only available if @i{Amd} was compiled with @samp{-DDEBUG}, or 3037configured with @code{configure --enable-debug}. The memory debugging 3038facilities (@samp{mem}) are only available if @i{Amd} was compiled with 3039@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}), or configured with 3040@code{configure --enable-debug=mem}. 3041 3042The most common options to use are @samp{-D trace} and @samp{-D test} 3043(which turns on all the useful debug options). As usual, every option 3044can be prefixed with @samp{no} to turn it off. 3045 3046@table @code 3047@item all 3048all options (excluding hrtime and mtab) 3049@item defaults 3050``sensible'' default options (all--excluding hrtime, mtab, and xdrtrace) 3051@item test 3052full debug options plus mtab,nodaemon,nofork,noamq 3053@item amq 3054register @i{Amd} with the RPC portmapper, for @i{Amq} 3055@item daemon 3056enter daemon mode 3057@item fork 3058fork child worker (hlfsd only) 3059@item full 3060program trace 3061@item hrtime 3062print high resolution time stamps (only if @b{syslog}(3) is not used) 3063@item info 3064@cindex debugging hesiod resolver service 3065@cindex Hesiod; turning on RES_DEBUG 3066info service specific debugging (hesiod, nis, etc.) In the case of 3067hesiod maps, turns on the hesiod RES_DEBUG internal debugging option. 3068@item mem 3069trace memory allocations. Needs to be explicitly enabled at compile 3070time with --enable-debug=mem. 3071@item mtab 3072use local mount-table file (defaults to @file{/tmp/mtab}, @pxref{debug_mtab_file Parameter}) 3073@item readdir 3074show readdir progress 3075@item str 3076debug string munging 3077@item trace 3078trace RPC protocol and NFS mount arguments 3079@item xdrtrace 3080trace XDR routines 3081@end table 3082 3083You may also refer to the program source for a more detailed explanation 3084of the available options. 3085 3086@c ---------------------------------------------------------------- 3087@node -F Option, -H Option, -D Option, Amd Command Line Options 3088@comment node-name, next, previous, up 3089@section @code{-F} @var{conf-file} 3090@cindex Amd configuration file; specifying name 3091@cindex Amd configuration file 3092@cindex amd.conf file 3093 3094Specify an @i{Amd} configuration file @var{conf-file} to use. For a 3095description of the format and syntax, @pxref{Amd Configuration File}. 3096This configuration file is used to specify any options in lieu of typing 3097many of them on the command line. The @file{amd.conf} file includes 3098directives for every command line option @i{Amd} has, and many more that 3099are only available via the configuration file facility. The 3100configuration file specified by this option is processed after all other 3101options had been processed, regardless of the actual location of this 3102option on the command line. 3103 3104@c ---------------------------------------------------------------- 3105@node -H Option, -O Option, -F Option, Amd Command Line Options 3106@comment node-name, next, previous, up 3107@section @code{-H} 3108@cindex Displaying brief help 3109@cindex Help; showing from Amd 3110 3111Print a brief help and usage string. 3112 3113@c ---------------------------------------------------------------- 3114@node -O Option, -S Option, -H Option, Amd Command Line Options 3115@comment node-name, next, previous, up 3116@section @code{-O} @var{op-sys-name} 3117@cindex Operating System name 3118@cindex Setting the Operating System name 3119 3120Overrides the compiled-in name of the operating system, with 3121@var{op-sys-name}. Useful when the built-in name is not desired for 3122backward compatibility reasons. For example, if the build in name is 3123@samp{sunos5}, you can override it to the old name @samp{sos5}, and use 3124older maps which were written with the latter in mind. 3125 3126@c ---------------------------------------------------------------- 3127@node -S Option, -T Option, -O Option, Amd Command Line Options 3128@comment node-name, next, previous, up 3129@section @code{-S} 3130@cindex plock; using 3131@cindex mlockall; using 3132@cindex locking executable pages in memory 3133 3134Do @emph{not} lock the running executable pages of @i{Amd} into memory. 3135To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 3136or @b{mlockall}(2) 3137call lock the @i{Amd} process into memory. This way there is less 3138chance the operating system will schedule, page out, and swap the 3139@i{Amd} process as needed. This tends to improve @i{Amd}'s performance, 3140at the cost of reserving the memory used by the @i{Amd} process (making 3141it unavailable for other processes). If this behavior is not desired, 3142use the @code{-S} option. 3143 3144@c ---------------------------------------------------------------- 3145@node -T Option, , -S Option, Amd Command Line Options 3146@comment node-name, next, previous, up 3147@section @code{-T} @var{tag} 3148@cindex Tags for Amd configuration file 3149@cindex Configuration file; tags 3150 3151Specify a tag to use with @file{amd.conf}. All map entries tagged with 3152@var{tag} will be processed. Map entries that are not tagged are always 3153processed. Map entries that are tagged with a tag other than @var{tag} 3154will not be processed. 3155 3156@c ################################################################ 3157@node Filesystem Types, Amd Configuration File, Amd Command Line Options, Top 3158@comment node-name, next, previous, up 3159@chapter Filesystem Types 3160@cindex Filesystem types 3161@cindex Mount types 3162@cindex Types of filesystem 3163 3164To mount a volume, @i{Amd} must be told the type of filesystem to be 3165used. Each filesystem type typically requires additional information 3166such as the fileserver name for NFS. 3167 3168From the point of view of @i{Amd}, a @dfn{filesystem} is anything that 3169can resolve an incoming name lookup. An important feature is support 3170for multiple filesystem types. Some of these filesystems are 3171implemented in the local kernel and some on remote fileservers, whilst 3172the others are implemented internally by @i{Amd}.@refill 3173 3174The two common filesystem types are UFS and NFS. Four other user 3175accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and 3176@samp{direct}) are also implemented internally by @i{Amd} and these are 3177described below. There are two additional filesystem types internal to 3178@i{Amd} which are not directly accessible to the user (@samp{inherit} 3179and @samp{error}). Their use is described since they may still have an 3180effect visible to the user.@refill 3181 3182@menu 3183* Network Filesystem:: A single NFS filesystem. 3184* Network Host Filesystem:: NFS mount a host's entire export tree. 3185* Network Filesystem Group:: An atomic group of NFS filesystems. 3186* Unix Filesystem:: Native disk filesystem. 3187* Caching Filesystem:: Caching from remote server filesystem. 3188* CD-ROM Filesystem:: ISO9660 CD ROM. 3189* UDF Filesystem:: Universal Disk Format filesystem. 3190* Loopback Filesystem:: Local loopback-mount filesystem. 3191* Memory/RAM Filesystem:: A memory or RAM-based filesystem. 3192* Null Filesystem:: 4.4BSD's loopback-mount filesystem. 3193* Floppy Filesystem:: MS-DOS Floppy filesystem. 3194* Translucent Filesystem:: The directory merging filesystem. 3195* Shared Memory+Swap Filesystem:: Sun's tmpfs filesystem. 3196* User ID Mapping Filesystem:: 4.4BSD's umapfs filesystem. 3197* Program Filesystem:: Generic Program mounts. 3198* Symbolic Link Filesystem:: Local link. 3199* Symbolic Link Filesystem II:: Local link referencing existing filesystem. 3200* NFS-Link Filesystem:: Link if path exists, NFS otherwise. 3201* Automount Filesystem:: 3202* Direct Automount Filesystem:: 3203* Union Filesystem:: 3204* Error Filesystem:: 3205* Top-level Filesystem:: 3206* Root Filesystem:: 3207* Inheritance Filesystem:: 3208@end menu 3209 3210@c ---------------------------------------------------------------- 3211@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types 3212@comment node-name, next, previous, up 3213@section Network Filesystem (@samp{nfs}) 3214@cindex NFS 3215@cindex Mounting an NFS filesystem 3216@cindex How to mount and NFS filesystem 3217@cindex nfs, filesystem type 3218@cindex Filesystem type; nfs 3219 3220The @dfn{nfs} (@samp{type:=nfs}) filesystem type provides access to Sun's NFS. 3221 3222@noindent 3223The following options must be specified: 3224 3225@table @code 3226@cindex rhost, mount option 3227@cindex Mount option; rhost 3228@item rhost 3229the remote fileserver. This must be an entry in the hosts database. IP 3230addresses are not accepted. The default value is taken 3231from the local host name (@code{$@{host@}}) if no other value is 3232specified. 3233 3234@cindex rfs, mount option 3235@cindex Mount option; rfs 3236@item rfs 3237the remote filesystem. 3238If no value is specified for this option, an internal default of 3239@code{$@{path@}} is used. 3240@end table 3241 3242NFS mounts require a two stage process. First, the @dfn{file handle} of 3243the remote file system must be obtained from the server. Then a mount 3244system call must be done on the local system. @i{Amd} keeps a cache 3245of file handles for remote file systems. The cache entries have a 3246lifetime of a few minutes. 3247 3248If a required file handle is not in the cache, @i{Amd} sends a request 3249to the remote server to obtain it. 3250@c @i{Amd} @dfn{does not} wait for 3251@c a response; it notes that one of the locations needs retrying, but 3252@c continues with any remaining locations. When the file handle becomes 3253@c available, and assuming none of the other locations was successfully 3254@c mounted, @i{Amd} will retry the mount. This mechanism allows several 3255@c NFS filesystems to be mounted in parallel. 3256@c @footnote{The mechanism 3257@c is general, however NFS is the only filesystem 3258@c for which the required hooks have been written.} 3259@c The first one which responds with a valid file handle will be used. 3260 3261Historically, this documentation has maintained that @i{Amd} will try 3262all the locations in parallel and use the first one which responds 3263with a valid file handle. This has not been the case for quite some 3264time, however. Instead, @i{Amd} will go through each location, one by 3265one, and will only skip to the next one if the previous one either 3266fails or times out. 3267 3268@noindent 3269An NFS entry might be: 3270 3271@example 3272jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp 3273@end example 3274 3275The mount system call and any unmount attempts are always done 3276in a new task to avoid the possibility of blocking @i{Amd}. 3277 3278@c ---------------------------------------------------------------- 3279@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types 3280@comment node-name, next, previous, up 3281@section Network Host Filesystem (@samp{host}) 3282@cindex Network host filesystem 3283@cindex Mounting entire export trees 3284@cindex How to mount all NFS exported filesystems 3285@cindex host, filesystem type 3286@cindex Filesystem type; host 3287 3288@c NOTE: the current implementation of the @dfn{host} filesystem type 3289@c sometimes fails to maintain a consistent view of the remote mount tree. 3290@c This happens when the mount times out and only some of the remote mounts 3291@c are successfully unmounted. To prevent this from occurring, use the 3292@c @samp{nounmount} mount option. 3293 3294The @dfn{host} (@samp{type:=host}) filesystem allows access to the entire export tree of an 3295NFS server. The implementation is layered above the @samp{nfs} 3296implementation so keep-alives work in the same way. The only option 3297which needs to be specified is @samp{rhost} which is the name of the 3298fileserver to mount. 3299 3300The @samp{host} filesystem type works by querying the mount daemon on 3301the given fileserver to obtain its export list. @i{Amd} then obtains 3302filehandles for each of the exported filesystems. Any errors at this 3303stage cause that particular filesystem to be ignored. Finally each 3304filesystem is mounted. Again, errors are logged but ignored. One 3305common reason for mounts to fail is that the mount point does not exist. 3306Although @i{Amd} attempts to automatically create the mount point, it 3307may be on a remote filesystem to which @i{Amd} does not have write 3308permission. 3309 3310When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} 3311remounts any filesystems which had successfully been unmounted. To do 3312this @i{Amd} queries the mount daemon again and obtains a fresh copy of 3313the export list. @i{Amd} then tries to mount any exported filesystems 3314which are not currently mounted. 3315 3316Sun's automounter provides a special @samp{-hosts} map. To achieve the 3317same effect with @i{Amd} requires two steps. First a mount map must 3318be created as follows: 3319 3320@example 3321* type:=host;rhost:=$@{key@};fs:=$@{autodir@}/$@{rhost@}/root 3322@end example 3323 3324@noindent 3325and then start @i{Amd} with the following command 3326 3327@example 3328amd /net net.map 3329@end example 3330 3331@noindent 3332where @samp{net.map} is the name of map described above. Note that the 3333value of @code{$@{fs@}} is overridden in the map. This is done to avoid 3334a clash between the mount tree and any other filesystem already mounted 3335from the same fileserver. 3336 3337If different mount options are needed for different hosts then 3338additional entries can be added to the map, for example 3339 3340@example 3341host2 opts:=ro,nosuid,soft 3342@end example 3343 3344@noindent 3345would soft mount @samp{host2} read-only. 3346 3347@c ---------------------------------------------------------------- 3348@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types 3349@comment node-name, next, previous, up 3350@section Network Filesystem Group (@samp{nfsx}) 3351@cindex Network filesystem group 3352@cindex Atomic NFS mounts 3353@cindex Mounting an atomic group of NFS filesystems 3354@cindex How to mount an atomic group of NFS filesystems 3355@cindex nfsx, filesystem type 3356@cindex Filesystem type; nfsx 3357 3358The @dfn{nfsx} (@samp{type:=nfsx}) filesystem allows a group of filesystems to be mounted 3359from a single NFS server. The implementation is layered above the 3360@samp{nfs} implementation so keep-alives work in the same way. 3361 3362@emph{WARNING}: @samp{nfsx} is meant to be a ``last resort'' kind of 3363solution. It is racy and poorly supported. The authors @emph{highly} 3364recommend that other solutions be considered before relying on it. 3365 3366The options are the same as for the @samp{nfs} filesystem with one 3367difference for @samp{rfs}, as explained below. 3368 3369@noindent 3370The following options should be specified: 3371 3372@table @code 3373@item rhost 3374the remote fileserver. The default value is taken from the local 3375host name (@code{$@{host@}}) if no other value is specified. 3376 3377@item rfs 3378is a list of filesystems to mount, and must be specified. 3379The list is in the form of a comma separated strings. 3380@end table 3381 3382@noindent 3383For example: 3384 3385@example 3386pub type:=nfsx;rhost:=gould;\ 3387 rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root 3388@end example 3389 3390The first string defines the root of the tree, and is applied as a 3391prefix to the remaining members of the list which define the individual 3392filesystems. The first string is @emph{not} used as a filesystem name. 3393A serial operation is used to determine the local mount points to 3394ensure a consistent layout of a tree of mounts. 3395 3396Here, the @emph{three} filesystems, @samp{/public}, 3397@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill 3398 3399A local mount point, @code{$@{fs@}}, @emph{must} be specified. The 3400default local mount point will not work correctly in the general case. 3401A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill 3402 3403@c ---------------------------------------------------------------- 3404@node Unix Filesystem, Caching Filesystem, Network Filesystem Group, Filesystem Types 3405@comment node-name, next, previous, up 3406@section Unix Filesystem (@samp{ufs}, @samp{xfs}, or @samp{efs}) 3407@cindex Unix filesystem 3408@cindex UFS 3409@cindex XFS 3410@cindex EFS 3411@cindex Mounting a UFS filesystem 3412@cindex Mounting a local disk 3413@cindex How to mount a UFS filesystems 3414@cindex How to mount a local disk 3415@cindex Disk filesystems 3416@cindex ufs, filesystem type 3417@cindex Filesystem type; ufs 3418@cindex xfs, filesystem type 3419@cindex Filesystem type; xfs 3420@cindex efs, filesystem type 3421@cindex Filesystem type; efs 3422 3423The @dfn{ufs} (@samp{type:=ufs}) filesystem type provides access to the system's standard 3424disk filesystem---usually a derivative of the Berkeley Fast Filesystem. 3425 3426@noindent 3427The following option must be specified: 3428 3429@table @code 3430@cindex dev, mount option 3431@cindex Mount option; dev 3432@item dev 3433the block special device to be mounted. 3434@end table 3435 3436A UFS entry might be: 3437 3438@example 3439jsp host==charm;type:=ufs;dev:=/dev/sd0d;sublink:=jsp 3440@end example 3441 3442UFS is the default Unix disk-based file system, which Am-utils picks up 3443during the autoconfiguration phase. Some systems have more than one 3444type, such as IRIX, that comes with EFS (Extent File System) and XFS 3445(Extended File System). In those cases, you may explicitly set the file 3446system type, by using entries such: 3447 3448@example 3449ez1 type:=efs;dev:=/dev/xd0a 3450ez2 type:=xfs;dev:=/dev/sd3c 3451@end example 3452 3453The UFS/XFS/EFS filesystems are never timed out by default, i.e. they 3454will never be unmounted by @i{Amd}. If automatic unmounting is 3455desired, the ``unmount'' option should be added to the mount options 3456for the entry. 3457 3458@c ---------------------------------------------------------------- 3459@node Caching Filesystem, CD-ROM Filesystem, Unix Filesystem, Filesystem Types 3460@comment node-name, next, previous, up 3461@section Caching Filesystem (@samp{cachefs}) 3462@cindex Caching Filesystem 3463@cindex cachefs, filesystem type 3464@cindex Filesystem type; cachefs 3465 3466The @dfn{cachefs} (@samp{type:=cachefs}) filesystem caches files from 3467one location onto another, presumably providing faster access. It is 3468particularly useful to cache from a larger and remote (slower) NFS 3469partition to a smaller and local (faster) UFS directory. 3470 3471@noindent 3472The following options must be specified: 3473 3474@table @code 3475@cindex cachedir, mount option 3476@cindex Mount option; cachedir 3477@item cachedir 3478the directory where the cache is stored. 3479@item rfs 3480the path name to the ``back file system'' to be cached from. 3481@item fs 3482the ``front file system'' mount point to the cached files, where @i{Amd} 3483will set a symbolic link pointing to. 3484@end table 3485 3486A CacheFS entry for, say, the @file{/import} @i{Amd} mount point, might 3487be: 3488 3489@example 3490copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt 3491@end example 3492 3493Access to the pathname @file{/import/copt} will follow a symbolic link 3494to @file{/n/import/copt}. The latter is the mount point for a caching 3495file system, that caches from @file{/import/opt} to @file{/cache}. 3496 3497The cachefs filesystem is never timed out by default, i.e. it will 3498never be unmounted by @i{Amd}. If automatic unmounting is desired, the 3499``unmount'' option should be added to the mount options for the entry. 3500 3501@b{Caveats}: 3502@enumerate 3503@item This file system is currently only implemented for Solaris 2.x! 3504@item Before being used for the first time, the cache directory @i{must} be 3505initialized with @samp{cfsadmin -c @var{cachedir}}. See the manual page for 3506@b{cfsadmin}(1M) for more information. 3507@item The ``back file system'' mounted must be a complete file system, not 3508a subdirectory thereof; otherwise you will get an error ``Invalid Argument''. 3509@item If @i{Amd} aborts abnormally, the state of the cache may be 3510inconsistent, requiring running the command @file{fsck -F cachefs 3511@var{cachedir}}. Otherwise you will get the error ``No Space Left on Device''. 3512@end enumerate 3513 3514@c ---------------------------------------------------------------- 3515@node CD-ROM Filesystem, UDF Filesystem, Caching Filesystem, Filesystem Types 3516@comment node-name, next, previous, up 3517@section CD-ROM Filesystem (@samp{cdfs}) 3518@cindex CD-ROM Filesystem 3519@cindex cdfs, filesystem type 3520@cindex Filesystem type; cdfs 3521 3522The @dfn{cdfs} (@samp{type:=cdfs}) filesystem mounts a CD-ROM with an 3523ISO9660 format filesystem on it. 3524 3525@noindent 3526The following option must be specified: 3527 3528@table @code 3529@cindex dev, mount option 3530@cindex Mount option; dev 3531@item dev 3532the block special device to be mounted. 3533@end table 3534 3535Some operating systems will fail to mount read-only CDs unless the 3536@samp{ro} option is specified. A cdfs entry might be: 3537 3538@example 3539cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ 3540 os==sunos5;addopts:=ro;type:=cdfs;dev:=/dev/dsk/c0t6d0s2 3541@end example 3542 3543@c ---------------------------------------------------------------- 3544@node UDF Filesystem, Loopback Filesystem, CD-ROM Filesystem, Filesystem Types 3545@comment node-name, next, previous, up 3546@section CD-ROM Filesystem (@samp{udf}) 3547@cindex CD-ROM Filesystem 3548@cindex udf, filesystem type 3549@cindex Filesystem type; udf 3550 3551The @dfn{udf} (@samp{type:=udf}) filesystem mounts media with a 3552Universal Disk Format (UDF) filesystem on it, e.g., a video DVD. 3553 3554@noindent 3555The following option must be specified: 3556 3557@table @code 3558@cindex dev, mount option 3559@cindex Mount option; dev 3560@item dev 3561the block special device to be mounted. 3562@end table 3563 3564Some operating systems will fail to mount read-only media unless the 3565@samp{ro} option is specified. A udf entry might be: 3566 3567@example 3568udf os==sunos4;type:=udf;dev:=/dev/sr0 \ 3569 os==sunos5;addopts:=ro;type:=udf;dev:=/dev/dsk/c0t6d0s2 3570@end example 3571 3572@c ---------------------------------------------------------------- 3573@node Loopback Filesystem, Memory/RAM Filesystem, UDF Filesystem, Filesystem Types 3574@comment node-name, next, previous, up 3575@section Loopback Filesystem (@samp{lofs}) 3576@cindex Loopback Filesystem 3577@cindex lofs, filesystem type 3578@cindex Filesystem type; lofs 3579 3580The @dfn{lofs} (@samp{type:=lofs}) filesystem is also called the 3581loopback filesystem. It mounts a local directory on another, thus 3582providing mount-time binding to another location (unlike symbolic 3583links). 3584 3585The loopback filesystem is particularly useful within the context of a 3586chroot-ed directory (via @b{chroot}(2)), to provide access to 3587directories otherwise inaccessible. 3588 3589@noindent 3590The following option must be specified: 3591 3592@table @code 3593@cindex rfs, mount option 3594@cindex Mount option; rfs 3595@item rfs 3596the pathname to be mounted on top of @code{$@{fs@}}. 3597@end table 3598 3599Usually, the FTP server runs in a chroot-ed environment, for security 3600reasons. In this example, lofs is used to provide a subdirectory within 3601a user's home directory, also available for public ftp. 3602 3603@example 3604lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk 3605@end example 3606 3607@c ---------------------------------------------------------------- 3608@node Memory/RAM Filesystem, Null Filesystem, Loopback Filesystem, Filesystem Types 3609@comment node-name, next, previous, up 3610@section Memory/RAM Filesystem (@samp{mfs}) 3611@cindex Memory/RAM Filesystem 3612@cindex mfs, filesystem type 3613@cindex Filesystem type; mfs 3614 3615The @dfn{mfs} (@samp{type:=mfs}) filesystem is available in 4.4BSD, 3616Linux, and other systems. It creates a filesystem in a portion of the 3617system's memory, thus providing very fast file (volatile) access. 3618 3619XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3620 3621@c ---------------------------------------------------------------- 3622@node Null Filesystem, Floppy Filesystem, Memory/RAM Filesystem, Filesystem Types 3623@comment node-name, next, previous, up 3624@section Null Filesystem (@samp{nullfs}) 3625@cindex Null Filesystem 3626@cindex nullfs, filesystem type 3627@cindex Filesystem type; nullfs 3628 3629The @dfn{nullfs} (@samp{type:=nullfs}) filesystem is available from 4.4BSD, 3630and is very similar to the loopback filesystem, @dfn{lofs}. 3631 3632XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3633 3634@c ---------------------------------------------------------------- 3635@node Floppy Filesystem, Translucent Filesystem, Null Filesystem, Filesystem Types 3636@comment node-name, next, previous, up 3637@section Floppy Filesystem (@samp{pcfs}) 3638@cindex Floppy Filesystem 3639@cindex pcfs, filesystem type 3640@cindex Filesystem type; pcfs 3641 3642The @dfn{pcfs} (@samp{type:=pcfs}) filesystem mounts a floppy previously 3643formatted for the MS-DOS format. 3644 3645@noindent 3646The following option must be specified: 3647 3648@table @code 3649@cindex dev, mount option 3650@cindex Mount option; dev 3651@item dev 3652the block special device to be mounted. 3653@end table 3654 3655A pcfs entry might be: 3656 3657@example 3658pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ 3659 os==sunos5;type:=pcfs;dev:=/dev/diskette 3660@end example 3661 3662@c ---------------------------------------------------------------- 3663@node Translucent Filesystem, Shared Memory+Swap Filesystem, Floppy Filesystem, Filesystem Types 3664@comment node-name, next, previous, up 3665@section Translucent Filesystem (@samp{tfs}) 3666@cindex Translucent Filesystem 3667@cindex tfs, filesystem type 3668@cindex Filesystem type; tfs 3669 3670The @dfn{tfs} (@samp{type:=tfs}) filesystem is an older version of the 36714.4BSD @dfn{unionfs}. 3672 3673XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3674 3675@c ---------------------------------------------------------------- 3676@node Shared Memory+Swap Filesystem, User ID Mapping Filesystem, Translucent Filesystem, Filesystem Types 3677@comment node-name, next, previous, up 3678@section Shared Memory+Swap Filesystem (@samp{tmpfs}) 3679@cindex Shared Memory and Swap Filesystem 3680@cindex tmpfs, filesystem type 3681@cindex Filesystem type; tmpfs 3682 3683The @dfn{tmpfs} (@samp{type:=tmpfs}) filesystem shares memory between a 3684the swap device and the rest of the system. It is generally used to 3685provide a fast access @file{/tmp} directory, one that uses memory that 3686is otherwise unused. This filesystem is available in SunOS 4.x and 5.x. 3687 3688XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3689 3690@c ---------------------------------------------------------------- 3691@node User ID Mapping Filesystem, Program Filesystem, Shared Memory+Swap Filesystem, Filesystem Types 3692@comment node-name, next, previous, up 3693@section User ID Mapping Filesystem (@samp{umapfs}) 3694@cindex User ID Mapping Filesystem 3695@cindex umapfs, filesystem type 3696@cindex Filesystem type; umapfs 3697 3698The @dfn{umapfs} (@samp{type:=umapfs}) filesystem maps User IDs of file 3699ownership, and is available from 4.4BSD. 3700 3701XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3702 3703@c ---------------------------------------------------------------- 3704@node Program Filesystem, Symbolic Link Filesystem, User ID Mapping Filesystem, Filesystem Types 3705@comment node-name, next, previous, up 3706@section Program Filesystem (@samp{program}) 3707@cindex Program filesystem 3708@cindex Mount a filesystem under program control 3709@cindex program, filesystem type 3710@cindex Filesystem type; program 3711 3712The @dfn{program} (@samp{type:=program}) filesystem type allows a 3713program to be run whenever a mount or unmount is required. This allows 3714easy addition of support for other filesystem types, such as MIT's 3715Remote Virtual Disk (RVD) which has a programmatic interface via the 3716commands @samp{rvdmount} and @samp{rvdunmount}. 3717 3718@noindent 3719Both of the following options must be specified: 3720 3721@table @code 3722@cindex mount, mount option 3723@cindex Mount option; mount 3724@item mount 3725the program which will perform the mount. 3726 3727@cindex unmount, mount option 3728@cindex umount, mount option 3729@cindex Mount option; unmount 3730@cindex Mount option; umount 3731@item unmount 3732@item umount 3733the program which will perform the unmount. For convenience, you may 3734use either @samp{unmount} or @samp{umount} but not both. If neither 3735is defined, @i{Amd} will default to @samp{umount $@{fs@}} (the actual 3736unmount program pathname will be automatically determined at the time 3737GNU @code{configure} runs.) 3738@end table 3739 3740The exit code from these two programs is interpreted as a Unix error 3741code. As usual, exit code zero indicates success. To execute the 3742program, @i{Amd} splits the string on whitespace to create an array of 3743substrings. Single quotes @samp{'} can be used to quote whitespace 3744if that is required in an argument. There is no way to escape or change 3745the single quote character. 3746 3747To run e.g. the program @samp{rvdmount} with a host name and filesystem as 3748arguments, it would be specified by 3749@samp{fs:=$@{autodir@}$@{path@};type:=program;mount:="/etc/rvdmount 3750rvdmount fserver $@{fs@}";unmount:="/etc/rdvumount rvdumount $@{fs@}"}. 3751 3752The first element in the array is taken as the pathname of the program 3753to execute. The other members of the array form the argument vector 3754to be passed to the program, @dfn{including argument zero}. The array 3755is exactly the same as the array passed to the execv() system call 3756(man execv for details). The split string must have at least two 3757elements. The programs are directly executed by @i{Amd}, not via a 3758shell. Therefore, if a script is to be used as a mount/umount 3759program, it @dfn{must} begin with a @code{#!} interpreter specification. 3760 3761Often, this program mount type is used for Samba mounts, where you 3762need a double slash in pathnames. However, @i{Amd} normalizes 3763sequences of slashes into one slash. Therefore, you must use an 3764escaped slash, preceded by an escaped backslash. So to get a double 3765slash in the mount command, you need the eight character sequence 3766@samp{\\\/\\\/} in your map. For example: 3767 3768@samp{mount="/sbin/mount mount -r -t smbfs -o-N,-Ihostname \\\/\\\/guest@@venus/mp3"} 3769 3770If a filesystem type is to be heavily used, it may be worthwhile adding 3771a new filesystem type into @i{Amd}, but for most uses the program 3772filesystem should suffice. 3773 3774When the program is run, standard input and standard error are inherited 3775from the current values used by @i{Amd}. Standard output is a 3776duplicate of standard error. The value specified with the @code{-l} 3777command line option has no effect on standard error. 3778 3779@i{Amd} guarantees that the mountpoint will be created before calling 3780the mount program, and that it will be removed after the umount 3781program returns success. 3782 3783@c ---------------------------------------------------------------- 3784@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types 3785@comment node-name, next, previous, up 3786@section Symbolic Link Filesystem (@samp{link}) 3787@cindex Symbolic link filesystem 3788@cindex Referencing part of the local name space 3789@cindex Mounting part of the local name space 3790@cindex How to reference part of the local name space 3791@cindex link, filesystem type 3792@cindex symlink, link filesystem type 3793@cindex Filesystem type; link 3794 3795Each filesystem type creates a symbolic link to point from the volume 3796name to the physical mount point. The @samp{link} filesystem does the 3797same without any other side effects. This allows any part of the 3798machines name space to be accessed via @i{Amd}. 3799 3800One common use for the symlink filesystem is @file{/homes} which can be 3801made to contain an entry for each user which points to their 3802(auto-mounted) home directory. Although this may seem rather expensive, 3803it provides a great deal of administrative flexibility. 3804 3805@noindent 3806The following option must be defined: 3807 3808@table @code 3809@item fs 3810The value of @var{fs} option specifies the destination of the link, as 3811modified by the @var{sublink} option. If @var{sublink} is non-null, it 3812is appended to @code{$@{fs@}}@code{/} and the resulting string is used 3813as the target. 3814@end table 3815 3816The @samp{link} filesystem can be thought of as identical to the 3817@samp{ufs} filesystem but without actually mounting anything. 3818 3819An example entry might be: 3820 3821@example 3822jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp 3823@end example 3824which would return a symbolic link pointing to @file{/home/charm/jsp}. 3825 3826@c ---------------------------------------------------------------- 3827@node Symbolic Link Filesystem II, NFS-Link Filesystem, Symbolic Link Filesystem, Filesystem Types 3828@comment node-name, next, previous, up 3829@section Symbolic Link Filesystem II (@samp{linkx}) 3830@cindex Symbolic link filesystem II 3831@cindex Referencing an existing part of the local name space 3832@cindex Mounting an existing part of the local name space 3833@cindex How to reference an existing part of the local name space 3834@cindex linkx, filesystem type 3835@cindex symlink, linkx filesystem type 3836@cindex Filesystem type; linkx 3837 3838The @dfn{linkx} (@samp{type:=linkx}) filesystem type is identical to @samp{link} with the 3839exception that the target of the link must exist. Existence is checked 3840with the @b{lstat}(2) system call. 3841 3842The @samp{linkx} filesystem type is particularly useful for wildcard map 3843entries. In this case, a list of possible targets can be given and 3844@i{Amd} will choose the first one which exists on the local machine. 3845 3846@c ---------------------------------------------------------------- 3847@node NFS-Link Filesystem, Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types 3848@comment node-name, next, previous, up 3849@section NFS-Link Filesystem (@samp{nfsl}) 3850@cindex NFS-Link filesystem II 3851@cindex Referencing an existing part of the name space if target exists 3852@cindex Mounting a remote part of the name space if target is missing 3853@cindex Symlink if target exists, NFS otherwise 3854@cindex nfsl, filesystem type 3855@cindex symlink, nfsl filesystem type 3856@cindex Filesystem type; nfsl 3857 3858The @dfn{nfsl} (@samp{type:=nfsl}) filesystem type is a combination of two others: 3859@samp{link} and @samp{nfs}. If the local host name is equal to the 3860value of @code{$@{rhost@}} @emph{and} the target pathname listed in 3861@code{$@{fs@}} exists, @samp{nfsl} will behave exactly as 3862@samp{type:=link}, and refer to the target as a symbolic link. If the 3863local host name is not equal to the value of @code{$@{rhost@}}, or if 3864the target of the link does not exist, @i{Amd} will treat it as 3865@samp{type:=nfs}, and will mount a remote pathname for it. 3866 3867The @samp{nfsl} filesystem type is particularly useful as a shorthand 3868for the more cumbersome and yet one of the most popular @i{Amd} 3869entries. For example, you can simplify all map entries that look like: 3870 3871@example 3872zing -fs:=/n/shekel/u/zing \ 3873 host!=shekel;type:=nfs;rhost:=shekel;rfs:=$@{fs@} \ 3874 host==shekel;type:=link 3875@end example 3876 3877or 3878 3879@example 3880zing -fs:=/n/shekel/u/zing \ 3881 exists($@{fs@});type:=link \ 3882 !exists($@{fs@});type:=nfs;rhost:=shekel;rfs:=$@{fs@} 3883@end example 3884 3885into a shorter form 3886 3887@example 3888zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=$@{fs@} 3889@end example 3890 3891Not just does it make the maps smaller and simpler, but it avoids 3892possible mistakes that often happen when forgetting to set up the two 3893entries (one for @samp{type:=nfs} and the other for @samp{type:=link}) 3894necessary to perform transparent mounts of existing or remote mounts. 3895 3896@c ---------------------------------------------------------------- 3897@node Automount Filesystem, Direct Automount Filesystem, NFS-Link Filesystem, Filesystem Types 3898@comment node-name, next, previous, up 3899@section Automount Filesystem (@samp{auto}) 3900@cindex Automount filesystem 3901@cindex Map cache types 3902@cindex Setting map cache parameters 3903@cindex How to set map cache parameters 3904@cindex How to start an indirect automount point 3905@cindex auto, filesystem type 3906@cindex Filesystem type; auto 3907@cindex SIGHUP signal 3908@cindex Map cache synchronizing 3909@cindex Synchronizing the map cache 3910@cindex Map cache options 3911@cindex Regular expressions in maps 3912 3913The @dfn{auto} (@samp{type:=auto}) filesystem type creates a new automount point below an 3914existing automount point. Top-level automount points appear as system 3915mount points. An automount mount point can also appear as a 3916sub-directory of an existing automount point. This allows some 3917additional structure to be added, for example to mimic the mount tree of 3918another machine. 3919 3920The following options may be specified: 3921 3922@table @code 3923@cindex cache, mount map option 3924@cindex Mount map option; cache 3925@item cache 3926specifies whether the data in this mount-map should be 3927cached. The default value is @samp{none}, in which case 3928no caching is done in order to conserve memory. 3929 3930However, better performance and reliability can be obtained by caching 3931some or all of a mount-map. 3932 3933If the cache option specifies @samp{all}, 3934the entire map is enumerated when the mount point is created. 3935 3936If the cache option specifies @samp{inc}, caching is done incrementally 3937as and when data is required. 3938Some map types do not support cache mode @samp{all}, in which case @samp{inc} 3939is used whenever @samp{all} is requested. 3940 3941Caching can be entirely disabled by using cache mode @samp{none}. 3942 3943If the cache option specifies @samp{regexp} then the entire map will be 3944enumerated and each key will be treated as an egrep-style regular 3945expression. The order in which a cached map is searched does not 3946correspond to the ordering in the source map so the regular expressions 3947should be mutually exclusive to avoid confusion. 3948 3949Each mount map type has a default cache type, usually @samp{inc}, which 3950can be selected by specifying @samp{mapdefault}. 3951 3952The cache mode for a mount map can only be selected on the command line. 3953Starting @i{Amd} with the command: 3954 3955@example 3956amd /homes hesiod.homes -cache:=inc 3957@end example 3958 3959will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name 3960server with local incremental caching of all successfully resolved names. 3961 3962All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} 3963signal and, if cache @samp{all} mode was selected, the cache will be 3964reloaded. This can be used to inform @i{Amd} that a map has been 3965updated. In addition, whenever a cache lookup fails and @i{Amd} needs 3966to examine a map, the map's modify time is examined. If the cache is 3967out of date with respect to the map then it is flushed as if a 3968@samp{SIGHUP} had been received. 3969 3970An additional option (@samp{sync}) may be specified to force @i{Amd} to 3971check the map's modify time whenever a cached entry is being used. For 3972example, an incremental, synchronized cache would be created by the 3973following command: 3974 3975@example 3976amd /homes hesiod.homes -cache:=inc,sync 3977@end example 3978 3979@item fs 3980specifies the name of the mount map to use for the new mount point. 3981 3982Arguably this should have been specified with the @code{$@{rfs@}} option but 3983we are now stuck with it due to historical accident. 3984 3985@c %If the string @samp{.} is used then the same map is used; 3986@c %in addition the lookup prefix is set to the name of the mount point followed 3987@c %by a slash @samp{/}. 3988@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. 3989@c 3990 3991@item pref 3992alters the name that is looked up in the mount map. If 3993@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended 3994to the name requested by the kernel @dfn{before} the map is 3995searched. The default prefix is the prefix of the parent map (if any) 3996with name of the auto node appended to it. That means if you want no 3997prefix you must say so in the map: @samp{pref:=null}. 3998 3999@item opts 4000Normally, @samp{auto} style maps are not browsable even if you turn on 4001directory browsability (@pxref{browsable_dirs Parameter}). To enable 4002browsing entries in @samp{auto} maps, specify @samp{opts:=browsable} 4003or @samp{opts:=fullybrowsable} in 4004the description of this map. 4005 4006@end table 4007 4008The server @samp{dylan.doc.ic.ac.uk} has two user disks: 4009@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as 4010@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since 4011@samp{/home} is already an automount point, this naming is achieved with 4012the following map entries:@refill 4013 4014@example 4015dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4016dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 4017dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 4018@end example 4019 4020@c ---------------------------------------------------------------- 4021@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types 4022@comment node-name, next, previous, up 4023@section Direct Automount Filesystem (@samp{direct}) 4024@cindex Direct automount filesystem 4025@cindex How to start a direct automount point 4026@cindex direct, filesystem type 4027@cindex Filesystem type; direct 4028 4029The @dfn{direct} (@samp{type:=direct}) filesystem is almost identical to 4030the automount filesystem. Instead of appearing to be a directory of 4031mount points, it appears as a symbolic link to a mounted filesystem. 4032The mount is done at the time the link is accessed. @xref{Automount 4033Filesystem}, for a list of required options. 4034 4035Direct automount points are created by specifying the @samp{direct} 4036filesystem type on the command line: 4037 4038@example 4039amd ... /usr/man auto.direct -type:=direct 4040@end example 4041 4042where @samp{auto.direct} would contain an entry such as: 4043 4044@example 4045usr/man -type:=nfs;rfs:=/usr/man \ 4046 rhost:=man-server1 rhost:=man-server2 4047@end example 4048 4049In this example, @samp{man-server1} and @samp{man-server2} are file 4050servers which export copies of the manual pages. Note that the key 4051which is looked up is the name of the automount point without the 4052leading @samp{/}. 4053 4054Note that the implementation of the traditional @dfn{direct} filesystem is 4055essentially a hack (pretending that the root of an NFS filesystem is a 4056symlink) and many modern operating systems get very unhappy about 4057it. For example, Linux kernel 2.4+ completely disallows it, and Solaris 40582.8 fails to unmount it when @i{Amd} shuts down. Therefore, the use of 4059the traditional @dfn{direct} filesystem is strongly discouraged; it is 4060only semi-supported, at best. 4061 4062The autofs implementations that permit direct mounts are fully 4063supported, however. That currently includes all versions of 4064Solaris. Linux autofs does NOT support direct mounts at all. 4065 4066@c ---------------------------------------------------------------- 4067@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types 4068@comment node-name, next, previous, up 4069@section Union Filesystem (@samp{union}) 4070@cindex Union filesystem 4071@cindex union, filesystem type 4072@cindex Filesystem type; union 4073 4074The @dfn{union} (@samp{type:=union}) filesystem type allows the contents of several 4075directories to be merged and made visible in a single directory. This 4076can be used to overcome one of the major limitations of the Unix mount 4077mechanism which only allows complete directories to be mounted. 4078 4079For example, supposing @file{/tmp} and @file{/var/tmp} were to be merged 4080into a new directory called @file{/mtmp}, with files in @file{/var/tmp} 4081taking precedence. The following command could be used to achieve this 4082effect: 4083 4084@example 4085amd ... /mtmp union:/tmp:/var/tmp -type:=union 4086@end example 4087 4088Currently, the unioned directories must @emph{not} be automounted. That 4089would cause a deadlock. This seriously limits the current usefulness of 4090this filesystem type and the problem will be addressed in a future 4091release of @i{Amd}. 4092 4093Files created in the union directory are actually created in the last 4094named directory. This is done by creating a wildcard entry which points 4095to the correct directory. The wildcard entry is visible if the union 4096directory is listed, so allowing you to see which directory has 4097priority. 4098 4099The files visible in the union directory are computed at the time 4100@i{Amd} is started, and are not kept up-to-date with respect to the 4101underlying directories. Similarly, if a link is removed, for example 4102with the @samp{rm} command, it will be lost forever. 4103 4104@c ---------------------------------------------------------------- 4105@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types 4106@comment node-name, next, previous, up 4107@section Error Filesystem (@samp{error}) 4108@cindex Error filesystem 4109@cindex error, filesystem type 4110@cindex Filesystem type; error 4111 4112The @dfn{error} (@samp{type:=error}) filesystem type is used internally as a catch-all in the 4113case where none of the other filesystems was selected, or some other 4114error occurred. Lookups and mounts always fail with ``No such file or 4115directory''. All other operations trivially succeed. 4116 4117The error filesystem is not directly accessible. 4118 4119@c ---------------------------------------------------------------- 4120@node Top-level Filesystem, Root Filesystem, Error Filesystem, Filesystem Types 4121@comment node-name, next, previous, up 4122@section Top-level Filesystem (@samp{toplvl}) 4123@cindex Top level filesystem 4124@cindex toplvl, filesystem type 4125@cindex Filesystem type; toplvl 4126 4127The @dfn{toplvl} (@samp{type:=toplvl}) filesystems is derived from the @samp{auto} filesystem 4128and is used to mount the top-level automount nodes. Requests of this 4129type are automatically generated from the command line arguments. 4130 4131@c ---------------------------------------------------------------- 4132@node Root Filesystem, Inheritance Filesystem, Top-level Filesystem, Filesystem Types 4133@comment node-name, next, previous, up 4134@section Root Filesystem (@samp{root}) 4135@cindex Root filesystem 4136@cindex root, filesystem type 4137@cindex Filesystem type; root 4138 4139The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal 4140placeholder onto which @i{Amd} can pin @samp{toplvl} mounts. Only one 4141node of this type need ever exist and one is created automatically 4142during startup. The effect of having more than one root node is 4143undefined. 4144 4145The root filesystem is not directly accessible. 4146 4147@c ---------------------------------------------------------------- 4148@node Inheritance Filesystem, , Root Filesystem, Filesystem Types 4149@comment node-name, next, previous, up 4150@section Inheritance Filesystem (@samp{inherit}) 4151@cindex Inheritance filesystem 4152@cindex Nodes generated on a restart 4153@cindex inherit, filesystem type 4154@cindex Filesystem type; inherit 4155 4156The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly 4157accessible. Instead, internal mount nodes of this type are 4158automatically generated when @i{Amd} is started with the @code{-r} option. 4159At this time the system mount table is scanned to locate any filesystems 4160which are already mounted. If any reference to these filesystems is 4161made through @i{Amd} then instead of attempting to mount it, @i{Amd} 4162simulates the mount and @dfn{inherits} the filesystem. This allows a 4163new version of @i{Amd} to be installed on a live system simply by 4164killing the old daemon with @samp{SIGTERM} and starting the new one.@refill 4165 4166This filesystem type is not generally visible externally, but it is 4167possible that the output from @samp{amq -m} may list @samp{inherit} as 4168the filesystem type. This happens when an inherit operation cannot 4169be completed for some reason, usually because a fileserver is down. 4170 4171@c ################################################################ 4172@node Amd Configuration File, Run-time Administration, Filesystem Types, Top 4173@comment node-name, next, previous, up 4174@chapter Amd Configuration File 4175@cindex Amd Configuration File 4176@cindex amd.conf 4177 4178The @samp{amd.conf} file is the configuration file for @i{Amd}, as part 4179of the am-utils suite. This file contains runtime configuration 4180information for the @i{Amd} automounter program. 4181 4182@menu 4183* File Format:: 4184* The Global Section:: 4185* Regular Map Sections:: 4186* Common Parameters:: 4187* Global Parameters:: 4188* Regular Map Parameters:: 4189* amd.conf Examples:: 4190@end menu 4191 4192@c ================================================================ 4193@node File Format, The Global Section, Amd Configuration File, Amd Configuration File 4194@comment node-name, next, previous, up 4195@section File Format 4196@cindex amd.conf file format 4197 4198The @samp{amd.conf} file consists of sections and parameters. A section 4199begins with the name of the section in square brackets @samp{[]} and 4200continues until the next section begins or the end of the file is reached. 4201Sections contain parameters of the form @samp{name = value}. 4202 4203The file is line-based --- that is, each newline-terminated line 4204represents either a comment, a section name or a parameter. No 4205line-continuation syntax is available. 4206 4207Section names, parameter names and their values are case sensitive. 4208 4209Only the first equals sign in a parameter is significant. Whitespace 4210before or after the first equals sign is discarded. Leading, trailing 4211and internal whitespace in section and parameter names is irrelevant. 4212Leading and trailing whitespace in a parameter value is discarded. 4213Internal whitespace within a parameter value is not allowed, unless the 4214whole parameter value is quoted with double quotes as in @samp{name = 4215"some value"}. 4216 4217Any line beginning with a pound sign @samp{#} is ignored, as are lines 4218containing only whitespace. 4219 4220The values following the equals sign in parameters are all either a 4221string (no quotes needed if string does not include spaces) or a 4222boolean, which may be given as @samp{yes}/@samp{no}. Case is significant in all 4223values. Some items such as cache timeouts are numeric. 4224 4225@c ================================================================ 4226@node The Global Section, Regular Map Sections, File Format, Amd Configuration File 4227@comment node-name, next, previous, up 4228@section The Global Section 4229@cindex amd.conf global section 4230 4231The global section must be specified as @samp{[global]}. Parameters in 4232this section either apply to @i{Amd} as a whole, or to all other regular map 4233sections which follow. There should be only one global section defined 4234in one configuration file. 4235 4236It is highly recommended that this section be specified first in the 4237configuration file. If it is not, then regular map sections which 4238precede it will not use global values defined later. 4239 4240@c ================================================================ 4241@node Regular Map Sections, Common Parameters, The Global Section, Amd Configuration File 4242@comment node-name, next, previous, up 4243@section Regular Map Sections 4244@cindex amd.conf regular map sections 4245 4246Parameters in regular (non-global) sections apply to a single map entry. 4247For example, if the map section @samp{[/homes]} is defined, then all 4248parameters following it will be applied to the @file{/homes} 4249@i{Amd}-managed mount point. 4250 4251@c ================================================================ 4252@node Common Parameters, Global Parameters, Regular Map Sections, Amd Configuration File 4253@comment node-name, next, previous, up 4254@section Common Parameters 4255@cindex amd.conf common parameters 4256 4257These parameters can be specified either in the global or a map-specific 4258section. Entries specified in a map-specific section override the default 4259value or one defined in the global section. If such a common parameter is 4260specified only in the global section, it is applicable to all regular map 4261sections that follow. 4262 4263@menu 4264* autofs_use_lofs Parameter:: 4265* browsable_dirs Parameter:: 4266* map_defaults Parameter:: 4267* map_options Parameter:: 4268* map_type Parameter:: 4269* mount_type Parameter:: 4270* search_path Parameter:: 4271* selectors_in_defaults Parameter:: 4272* sun_map_syntax Parameter:: 4273@end menu 4274 4275@c ---------------------------------------------------------------- 4276@node autofs_use_lofs Parameter, browsable_dirs Parameter, Common Parameters, Common Parameters 4277@comment node-name, next, previous, up 4278@subsection @t{autofs_use_lofs} Parameter 4279@cindex autofs_use_lofs Parameter 4280 4281(type=string, default=@samp{yes}). 4282When set to @samp{yes}, @i{Amd}'s autofs code will use lofs-type 4283(loopback) mounts for @code{type:=link} mounts, as well as several 4284other cases that require local references. This has the advantage 4285that @i{Amd} does not use a secondary mount point and users do not see 4286external pathnames (the infamous @code{/bin/pwd} problem, where it 4287reports a different path than the user chdir'ed into). One of the 4288disadvantages of using this option is that the autofs code is 4289relatively new and the in-place mounts have not been throughly tested. 4290 4291If this option is set to @samp{no}, then @i{Amd}'s autofs code will 4292use symlinks instead of lofs-type mounts for local references. This 4293has the advantage of using simpler (more stable) code, but at the 4294expense of negating one of autofs's big advantages: the hiding of 4295@i{Amd}'s internal paths. Note that symlinks are not supported in all 4296autofs implementations, especially those derived from Solaris Autofs 4297v1. Also, on Solaris 2.6 and newer, autofs symlinks are not cached, 4298resulting in repeated up-call requests to @i{Amd}. 4299 4300@c ---------------------------------------------------------------- 4301@node browsable_dirs Parameter, map_defaults Parameter, autofs_use_lofs Parameter, Common Parameters 4302@comment node-name, next, previous, up 4303@subsection @t{browsable_dirs} Parameter 4304@cindex browsable_dirs Parameter 4305 4306(type=string, default=@samp{no}). If @samp{yes}, then @i{Amd}'s top-level 4307mount points will be browsable to @b{readdir}(3) calls. This means you 4308could run for example @b{ls}(1) and see what keys are available to mount 4309in that directory. Not all entries are made visible to @b{readdir}(3): 4310the @samp{/defaults} entry, wildcard entries, and those with a @file{/} 4311in them are not included. If you specify @samp{full} to this option, 4312all but the @samp{/defaults} entry will be visible. Note that if you run 4313a command which will attempt to @b{stat}(2) the entries, such as often 4314done by @samp{ls -l} or @samp{ls -F}, @i{Amd} will attempt to mount 4315@i{every} entry in that map. This is often called a ``mount storm''. 4316 4317Note that mount storms are mostly avoided by using autofs mounts 4318(@samp{mount_type = autofs}). 4319 4320@c ---------------------------------------------------------------- 4321@node map_defaults Parameter, map_options Parameter, browsable_dirs Parameter, Common Parameters 4322@comment node-name, next, previous, up 4323@subsection @t{map_defaults} Parameter 4324@cindex map_defaults Parameter 4325 4326(type=string, default to empty). This option sets a string to be used 4327as the map's @code{/defaults} entry, overriding any @code{/defaults} 4328specified in the map. This allows local users to override a given 4329map's defaults without modifying maps globally (which is impossible in 4330sites where the maps are managed by a different administrative group). 4331 4332@c ---------------------------------------------------------------- 4333@node map_options Parameter, map_type Parameter, map_defaults Parameter, Common Parameters 4334@comment node-name, next, previous, up 4335@subsection @t{map_options} Parameter 4336@cindex map_options Parameter 4337 4338(type=string, default no options). This option is the same as 4339specifying map options on the command line to @i{Amd}, such as 4340@samp{cache:=all}. 4341 4342@c ---------------------------------------------------------------- 4343@node map_type Parameter, mount_type Parameter, map_options Parameter, Common Parameters 4344@comment node-name, next, previous, up 4345@subsection @t{map_type} Parameter 4346@cindex map_type Parameter 4347 4348(type=string, default search all map types). If specified, @i{Amd} will 4349initialize the map only for the type given. This is useful to avoid the 4350default map search type used by @i{Amd} which takes longer and can have 4351undesired side-effects such as initializing NIS even if not used. 4352Possible values are 4353 4354@table @samp 4355@item file 4356plain files 4357@item hesiod 4358Hesiod name service from MIT 4359@item ldap 4360Lightweight Directory Access Protocol 4361@item ndbm 4362(New) dbm style hash files 4363@item nis 4364Network Information Services (version 2) 4365@item nisplus 4366Network Information Services Plus (version 3) 4367@item passwd 4368local password files 4369@item union 4370union maps 4371@end table 4372 4373@c ---------------------------------------------------------------- 4374@node mount_type Parameter, search_path Parameter, map_type Parameter, Common Parameters 4375@comment node-name, next, previous, up 4376@subsection @t{mount_type} Parameter 4377@cindex mount_type Parameter 4378 4379(type=string, default=@samp{nfs}). All @i{Amd} mount types default to NFS. 4380That is, @i{Amd} is an NFS server on the map mount points, for the local 4381host it is running on. If @samp{autofs} is specified, @i{Amd} will be 4382an autofs server for those mount points. 4383 4384@c ---------------------------------------------------------------- 4385@node search_path Parameter, selectors_in_defaults Parameter, mount_type Parameter, Common Parameters 4386@comment node-name, next, previous, up 4387@subsection @t{search_path} Parameter 4388@cindex search_path Parameter 4389 4390(type=string, default no search path). This provides a 4391(colon-delimited) search path for file maps. Using a search path, 4392sites can allow for local map customizations and overrides, and can 4393distributed maps in several locations as needed. 4394 4395@c ---------------------------------------------------------------- 4396@node selectors_in_defaults Parameter, sun_map_syntax Parameter, search_path Parameter, Common Parameters 4397@comment node-name, next, previous, up 4398@subsection @t{selectors_in_defaults} Parameter 4399@cindex selectors_in_defaults Parameter 4400 4401(type=boolean, default=@samp{no}). If @samp{yes}, then the 4402@samp{/defaults} entry of maps will search for and process any 4403selectors before setting defaults for all other keys in that map. 4404Useful when you want to set different options for a complete map based 4405on some parameters. For example, you may want to better the NFS 4406performance over slow slip-based networks as follows: 4407 4408@example 4409/defaults \ 4410 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \ 4411 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192 4412@end example 4413 4414Deprecated form: selectors_on_default. 4415 4416@c ---------------------------------------------------------------- 4417@node sun_map_syntax Parameter, , selectors_in_defaults Parameter, Common Parameters 4418@comment node-name, next, previous, up 4419@subsection @t{sun_map_syntax} Parameter 4420@cindex sun_map_syntax Parameter 4421 4422(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will 4423parse the map according to the Sun Automount syntax. 4424 4425 4426@c ================================================================ 4427@node Global Parameters, Regular Map Parameters, Common Parameters, Amd Configuration File 4428@comment node-name, next, previous, up 4429@section Global Parameters 4430@cindex amd.conf global parameters 4431 4432The following parameters are applicable to the @samp{[global]} section only. 4433 4434@menu 4435* arch Parameter:: 4436* auto_attrcache Parameter:: 4437* auto_dir Parameter:: 4438* cache_duration Parameter:: 4439* cluster Parameter:: 4440* debug_mtab_file Parameter:: 4441* debug_options Parameter:: 4442* dismount_interval Parameter:: 4443* domain_strip Parameter:: 4444* exec_map_timeout Parameter:: 4445* forced_unmounts Parameter:: 4446* full_os Parameter:: 4447* fully_qualified_hosts Parameter:: 4448* hesiod_base Parameter:: 4449* karch Parameter:: 4450* ldap_base Parameter:: 4451* ldap_cache_maxmem Parameter:: 4452* ldap_cache_seconds Parameter:: 4453* ldap_hostports Parameter:: 4454* ldap_proto_version Parameter:: 4455* local_domain Parameter:: 4456* localhost_address Parameter:: 4457* log_file Parameter:: 4458* log_options Parameter:: 4459* map_reload_interval Parameter:: 4460* nfs_allow_any_interface Parameter:: 4461* nfs_allow_insecure_port Parameter:: 4462* nfs_proto Parameter:: 4463* nfs_retransmit_counter Parameter:: 4464* nfs_retransmit_counter_udp Parameter:: 4465* nfs_retransmit_counter_tcp Parameter:: 4466* nfs_retransmit_counter_toplvl Parameter:: 4467* nfs_retry_interval Parameter:: 4468* nfs_retry_interval_udp Parameter:: 4469* nfs_retry_interval_tcp Parameter:: 4470* nfs_retry_interval_toplvl Parameter:: 4471* nfs_vers Parameter:: 4472* nis_domain Parameter:: 4473* normalize_hostnames Parameter:: 4474* normalize_slashes Parameter:: 4475* os Parameter:: 4476* osver Parameter:: 4477* pid_file Parameter:: 4478* plock Parameter:: 4479* portmap_program Parameter:: 4480* preferred_amq_port Parameter:: 4481* print_pid Parameter:: 4482* print_version Parameter:: 4483* restart_mounts Parameter:: 4484* show_statfs_entries Parameter:: 4485* truncate_log Parameter:: 4486* unmount_on_exit Parameter:: 4487* use_tcpwrappers Parameter:: 4488* vendor Parameter:: 4489@end menu 4490 4491@c ---------------------------------------------------------------- 4492@node arch Parameter, auto_attrcache Parameter, Global Parameters, Global Parameters 4493@comment node-name, next, previous, up 4494@subsection @t{arch} Parameter 4495@cindex arch Parameter 4496 4497(type=string, default to compiled in value). Same as the @code{-A} 4498option to @i{Amd}. Allows you to override the value of the @i{arch} 4499@i{Amd} variable. 4500 4501@c ---------------------------------------------------------------- 4502@node auto_attrcache Parameter, auto_dir Parameter, arch Parameter, Global Parameters 4503@comment node-name, next, previous, up 4504@subsection @t{auto_attrcache} Parameter 4505@cindex auto_attrcache Parameter 4506 4507(type=numeric, default=0). Specify in seconds (or units of 0.1 4508seconds, depending on the OS), what is the (kernel-side) NFS attribute 4509cache timeout for @i{Amd}'s own automount points. A value of 0 is 4510supposed to turn off attribute caching, meaning that @i{Amd} will be 4511consulted via a kernel-RPC each time someone stat()'s the mount point 4512(which could be abused as a denial-of-service attack). 4513 4514@emph{WARNING}: @i{Amd} depends on being able to turn off the NFS 4515attribute cache of the client OS. If it cannot be turned off, then 4516users may get ESTALE errors or symlinks that point to the wrong 4517places. This is more likely under heavy use of @i{Amd}, for example 4518if your system is experiencing frequent map changes or frequent 4519mounts/unmounts. Therefore, under normal circumstances, this 4520parameter should remain set to 0, to ensure that the attribute cache 4521is indeed off. 4522 4523Unfortunately, some kernels (e.g., certain BSDs) don't have a way to 4524turn off the NFS attribute cache. Setting this parameter to 0 is 4525supposed to turn off attribute caching entirely, but unfortunately it 4526does not; instead, the attribute cache is set to some internal 4527hard-coded default (usually anywhere from 5-30 seconds). If you 4528suspect that your OS doesn't have a reliable way of turning off the 4529attribute cache, then it is better to set this parameter to the 4530smallest possible non-zero value (set @samp{auto_attrcache=1} in your 4531@code{amd.conf}). This will not eliminate the problem, but reduce the 4532risk window somewhat. The best solutions are (1) to use @i{Amd} in 4533Autofs mode, if it's supported in your OS, and (2) talk to your OS 4534vendor to support a true @samp{noac} flag. See the 4535@uref{http://www.am-utils.org/docs/am-utils/attrcache.txt,README.attrcache} 4536document for more details. 4537 4538If you are able to turn off the attribute cache on your OS, alas, 4539@i{Amd}'s performance may degrade (when not using Autofs) because 4540every traversal of an automounter-controlled pathname will result in a 4541lookup request from the kernel to @i{Amd}. Under heavy loads, for 4542example when using recursive tools like @samp{find}, @samp{rdist}, or 4543@samp{rsync}, this performance degradation can be noticeable. There 4544are two possible solutions that some administrators have chosen to 4545improve performance: 4546 4547@enumerate 4548 4549@item 4550First, you can turn off unmounting using the @samp{nounmount} mount 4551option. This will ensure that no @i{Amd} symlink could ever change, 4552thereby the kernel's attribute cache and @i{Amd} will always be in 4553sync. However, this method will cause the number of mounts to keep 4554growing, even if some are no longer in use; this has the disadvantage 4555that your system could be more susceptible to hangs if even one of 4556those accumulating mounts hangs due to a downed server. 4557 4558@item 4559Second, you can turn on attribute caching carefully by setting a small 4560automounter attribute cache value (say, one second), and a relatively 4561large dismount interval (say, one hour). (@xref{dismount_interval 4562Parameter}.) For example, you can set this in your @code{amd.conf}: 4563 4564@example 4565[global] 4566auto_attrcache = 1 4567dismount_interval = 3600 4568@end example 4569 4570This has the benefit of using the kernel's attribute cache and thus 4571improving performance. The disadvantage with this option is that the 4572window of vulnerability is not eliminated entirely: it is only made 4573smaller. 4574 4575@end enumerate 4576 4577@c ---------------------------------------------------------------- 4578@node auto_dir Parameter, cache_duration Parameter, auto_attrcache Parameter, Global Parameters 4579@comment node-name, next, previous, up 4580@subsection @t{auto_dir} Parameter 4581@cindex auto_dir Parameter 4582 4583(type=string, default=@samp{/a}). Same as the @code{-a} option to @i{Amd}. 4584This sets the private directory where @i{Amd} will create 4585sub-directories for its real mount points. 4586 4587@c ---------------------------------------------------------------- 4588@node cache_duration Parameter, cluster Parameter, auto_dir Parameter, Global Parameters 4589@comment node-name, next, previous, up 4590@subsection @t{cache_duration} Parameter 4591@cindex cache_duration Parameter 4592 4593(type=numeric, default=300). Same as the @code{-c} option to @i{Amd}. 4594Sets the duration in seconds that looked-up or mounted map entries 4595remain in the cache. 4596 4597@c ---------------------------------------------------------------- 4598@node cluster Parameter, debug_mtab_file Parameter, cache_duration Parameter, Global Parameters 4599@comment node-name, next, previous, up 4600@subsection @t{cluster} Parameter 4601@cindex cluster Parameter 4602 4603(type=string, default no cluster). Same as the @code{-C} option to 4604@i{Amd}. Specifies the alternate HP-UX cluster to use. 4605 4606@c ---------------------------------------------------------------- 4607@node debug_mtab_file Parameter, debug_options Parameter, cluster Parameter, Global Parameters 4608@comment node-name, next, previous, up 4609@subsection @t{debug_mtab_file} Parameter 4610@cindex debug_mtab_file Parameter 4611 4612(type=string, default="/tmp/mtab"). Path to mtab file that is used 4613by @i{Amd} to store a list of mounted file systems during debug-mtab mode. 4614This option only applies to systems that store mtab information on disk. 4615 4616@c ---------------------------------------------------------------- 4617@node debug_options Parameter, dismount_interval Parameter, debug_mtab_file Parameter, Global Parameters 4618@comment node-name, next, previous, up 4619@subsection @t{debug_options} Parameter 4620@cindex debug_options Parameter 4621 4622(type=string, default no debug options). Same as the @code{-D} option 4623to @i{Amd}. Specify any debugging options for @i{Amd}. Works only if 4624am-utils was configured for debugging using the @code{--enable-debug} 4625option. The additional @samp{mem} option can be turned on via 4626@code{--enable-debug=mem}. Otherwise debugging options are ignored. 4627Options are comma delimited, and can be preceded by the string 4628@samp{no} to negate their meaning. You can get the list of supported 4629debugging and logging options by running @code{amd -H}. Possible 4630values those listed for the -D option. @xref{-D Option}. 4631 4632@c ---------------------------------------------------------------- 4633@node dismount_interval Parameter, domain_strip Parameter, debug_options Parameter, Global Parameters 4634@comment node-name, next, previous, up 4635@subsection @t{dismount_interval} Parameter 4636@cindex dismount_interval Parameter 4637 4638(type=numeric, default=120). Same as the @code{-w} option to 4639@i{Amd}. Specify in seconds, the time between attempts to dismount file 4640systems that have exceeded their cached times. 4641 4642@c ---------------------------------------------------------------- 4643@node domain_strip Parameter, exec_map_timeout Parameter, dismount_interval Parameter, Global Parameters 4644@comment node-name, next, previous, up 4645@subsection @t{domain_strip} Parameter 4646@cindex domain_strip Parameter 4647 4648(type=boolean, default=@samp{yes}). If @samp{yes}, then the domain 4649name part referred to by @code{$@{rhost@}} is stripped off. This is 4650useful to keep logs and smaller. If @samp{no}, then the domain name 4651part is left changed. This is useful when using multiple domains with 4652the same maps (as you may have hosts whose domain-stripped name is 4653identical). 4654 4655@c ---------------------------------------------------------------- 4656@node exec_map_timeout Parameter, forced_unmounts Parameter, domain_strip Parameter, Global Parameters 4657@comment node-name, next, previous, up 4658@subsection @t{exec_map_timeout} Parameter 4659@cindex exec_map_timeout Parameter 4660 4661(type=numeric, default=10). The timeout in seconds that @i{Amd} will 4662wait for an executable map program before an answer is returned from 4663that program (or script). This value should be set to as small as 4664possible while still allowing normal replies to be returned before the 4665timer expires, because during the time that the executable map program 4666is queried, @i{Amd} is essentially waiting and is thus not responding 4667to any other queries. @xref{Executable maps}. 4668 4669@c ---------------------------------------------------------------- 4670@node forced_unmounts Parameter, full_os Parameter, exec_map_timeout Parameter, Global Parameters 4671@comment node-name, next, previous, up 4672@subsection @t{forced_unmounts} Parameter 4673@cindex forced_unmounts Parameter 4674 4675(type=boolean, default=@samp{no}). 4676Sometimes, mount points are hung due to unrecoverable conditions, such 4677as when NFS servers migrate, change their IP address, are down 4678permanently, or due to hardware failures, and more. In this case, 4679attempting to unmount an existing mount point, or even just to 4680@b{stat}(2) it, results in one of three fatal errors: EIO, ESTALE, or 4681EBUSY. At that point, @i{Amd} can do little to recover that hung 4682point (in fact, the OS cannot automatically recover either). For that 4683reason, some OSs support special kinds of forced unmounts, which must 4684be used very carefully: they will force an unmount immediately (or 4685lazily on Linux), which could result in application data loss. 4686However, that may be the only way to recover the entire host (without 4687rebooting). Once a hung mount point is forced out, @i{Amd} can then 4688re-mount a replacement one (if available), bringing a mostly-hung 4689system back to operation and avoiding a potentially costly reboot. 4690 4691If the @samp{forced_unmounts} option is set to @samp{yes}, and the 4692client OS supports forced or lazy unmounts, then @i{Amd} will attempt 4693to use them if it gets any of the three serious error conditions 4694listed above. Note that @i{Amd} will force the unmount of mount 4695points that returned EBUSY only for @samp{type:=toplvl} mounts 4696(@pxref{Top-level Filesystem}): that is, @i{Amd}'s own mount points. 4697This is useful to recover from a previously hung @i{Amd}, and to 4698ensure that an existing @i{Amd} can shutdown cleanly even if some 4699processes are keeping its mount points busy (i.e., when a user's shell 4700process uses @code{cd} to set its CWD to @i{Amd}'s own mount point). 4701 4702If this option is set to @samp{no} (the default), then @i{Amd} will 4703not attempt this special recovery procedure. 4704 4705@c ---------------------------------------------------------------- 4706@node full_os Parameter, fully_qualified_hosts Parameter, forced_unmounts Parameter, Global Parameters 4707@comment node-name, next, previous, up 4708@subsection @t{full_os} Parameter 4709@cindex full_os Parameter 4710 4711(type=string, default to compiled in value). The full name of the 4712operating system, along with its version. Allows you to override the 4713compiled-in full name and version of the operating system. Useful when 4714the compiled-in name is not desired. For example, the full operating 4715system name on linux comes up as @samp{linux}, but you can override it 4716to @samp{linux-2.2.5}. 4717 4718@c ---------------------------------------------------------------- 4719@node fully_qualified_hosts Parameter, hesiod_base Parameter, full_os Parameter, Global Parameters 4720@comment node-name, next, previous, up 4721@subsection @t{fully_qualified_hosts} Parameter 4722@cindex fully_qualified_hosts Parameter 4723 4724(type=string, default=@samp{no}). If @samp{yes}, @i{Amd} will perform RPC 4725authentication using fully-qualified host names. This is necessary for 4726some systems, and especially when performing cross-domain mounting. For 4727this function to work, the @i{Amd} variable @samp{$@{hostd@}} is used, 4728requiring that @samp{$@{domain@}} not be null. 4729 4730@c ---------------------------------------------------------------- 4731@node hesiod_base Parameter, karch Parameter, fully_qualified_hosts Parameter, Global Parameters 4732@comment node-name, next, previous, up 4733@subsection @t{hesiod_base} Parameter 4734@cindex hesiod_base Parameter 4735 4736(type=string, default=@samp{automount}). Specify the base name for 4737hesiod maps. 4738 4739@c ---------------------------------------------------------------- 4740@node karch Parameter, ldap_base Parameter, hesiod_base Parameter, Global Parameters 4741@comment node-name, next, previous, up 4742@subsection @t{karch} Parameter 4743@cindex karch Parameter 4744 4745(type=string, default to karch of the system). Same as the @code{-k} 4746option to @i{Amd}. Allows you to override the kernel-architecture of 4747your system. Useful for example on Sun (Sparc) machines, where you can 4748build one @i{Amd} binary, and run it on multiple machines, yet you want 4749each one to get the correct @i{karch} variable set (for example, sun4c, 4750sun4m, sun4u, etc.) Note that if not specified, @i{Amd} will use 4751@b{uname}(2) to figure out the kernel architecture of the machine. 4752 4753@c ---------------------------------------------------------------- 4754@node ldap_base Parameter, ldap_cache_maxmem Parameter, karch Parameter, Global Parameters 4755@comment node-name, next, previous, up 4756@subsection @t{ldap_base} Parameter 4757@cindex ldap_base Parameter 4758 4759(type=string, default not set). 4760Specify the base name for LDAP. This often includes LDAP-specific 4761values such as country and organization. 4762 4763@c ---------------------------------------------------------------- 4764@node ldap_cache_maxmem Parameter, ldap_cache_seconds Parameter, ldap_base Parameter, Global Parameters 4765@comment node-name, next, previous, up 4766@subsection @t{ldap_cache_maxmem} Parameter 4767@cindex ldap_cache_maxmem Parameter 4768 4769(type=numeric, default=131072). Specify the maximum memory @i{Amd} 4770should use to cache LDAP entries. 4771 4772@c ---------------------------------------------------------------- 4773@node ldap_cache_seconds Parameter, ldap_hostports Parameter, ldap_cache_maxmem Parameter, Global Parameters 4774@comment node-name, next, previous, up 4775@subsection @t{ldap_cache_seconds} Parameter 4776@cindex ldap_cache_seconds Parameter 4777 4778(type=numeric, default=0). Specify the number of seconds to keep 4779entries in the cache. 4780 4781@c ---------------------------------------------------------------- 4782@node ldap_hostports Parameter, ldap_proto_version Parameter, ldap_cache_seconds Parameter, Global Parameters 4783@comment node-name, next, previous, up 4784@subsection @t{ldap_hostports} Parameter 4785@cindex ldap_hostports Parameter 4786 4787(type=string, default not set). 4788Specify the LDAP host and port values. 4789 4790@c ---------------------------------------------------------------- 4791@node ldap_proto_version Parameter, local_domain Parameter, ldap_hostports Parameter, Global Parameters 4792@comment node-name, next, previous, up 4793@subsection @t{ldap_proto_version} Parameter 4794@cindex ldap_proto_version Parameter 4795 4796(type=numeric, default=2). Specify the LDAP protocol version to use. 4797With a value of 3 will use LDAPv3 protocol. 4798 4799@c ---------------------------------------------------------------- 4800@node local_domain Parameter, localhost_address Parameter, ldap_proto_version Parameter, Global Parameters 4801@comment node-name, next, previous, up 4802@subsection @t{local_domain} Parameter 4803@cindex local_domain Parameter 4804 4805(type=string, default no sub-domain). Same as the @code{-d} option 4806to @i{Amd}. Specify the local domain name. If this option is not given 4807the domain name is determined from the hostname, by removing the first 4808component of the fully-qualified host name. 4809 4810@c ---------------------------------------------------------------- 4811@node localhost_address Parameter, log_file Parameter, local_domain Parameter, Global Parameters 4812@comment node-name, next, previous, up 4813@subsection @t{localhost_address} Parameter 4814@cindex localhost_address Parameter 4815 4816(type=string, default to localhost or 127.0.0.1). Specify the name or 4817IP address for @i{Amd} to use when connecting the sockets for the 4818local NFS server and the RPC server. This defaults to 127.0.0.1 or 4819whatever the host reports as its local address. This parameter is 4820useful on hosts with multiple addresses where you want to force 4821@i{Amd} to connect to a specific address. 4822 4823@c ---------------------------------------------------------------- 4824@node log_file Parameter, log_options Parameter, localhost_address Parameter, Global Parameters 4825@comment node-name, next, previous, up 4826@subsection @t{log_file} Parameter 4827@cindex log_file Parameter 4828 4829(type=string, default=@samp{stderr}). Same as the @code{-l} option to 4830@i{Amd}. Specify a file name to log @i{Amd} events to. 4831If the string @samp{/dev/stderr} is specified, 4832@i{Amd} will send its events to the standard error file descriptor. 4833 4834If the string @samp{syslog} is given, @i{Amd} will record its events 4835with the system logger @b{syslogd}(8). If your system supports syslog 4836facilities, then the default facility used is @samp{LOG_DAEMON}. 4837 4838When using syslog, if you wish to change the facility, append its name 4839to the option name, delimited by a single colon. For example, if it is 4840the string @samp{syslog:local7} then @i{Amd} will log messages via 4841@b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If the facility 4842name specified is not recognized, @i{Amd} will default to @samp{LOG_DAEMON}. 4843Note: while you can use any syslog facility available on your system, it 4844is generally a bad idea to use those reserved for other services such as 4845@samp{kern}, @samp{lpr}, @samp{cron}, etc. 4846 4847@c ---------------------------------------------------------------- 4848@node log_options Parameter, map_reload_interval Parameter, log_file Parameter, Global Parameters 4849@comment node-name, next, previous, up 4850@subsection @t{log_options} Parameter 4851@cindex log_options Parameter 4852 4853(type=string, default=``defaults''). Same as the @code{-x} 4854option to @i{Amd}. Specify any logging options for @i{Amd}. Options 4855are comma delimited, and can be preceded by the string @samp{no} to 4856negate their meaning. The @samp{debug} logging option is only available 4857if am-utils was configured with @code{--enable-debug}. You can get the 4858list of supported debugging options by running @code{amd -H}. Possible 4859values are: 4860 4861@table @samp 4862@item all 4863all messages 4864@item defaults 4865an alias for "fatal,error,user,warning,info" 4866@item debug 4867debug messages 4868@item error 4869non-fatal system errors (cannot be turned off) 4870@item fatal 4871fatal errors (cannot be turned off) 4872@item info 4873information 4874@item map 4875map errors 4876@item stats 4877additional statistical information 4878@item user 4879non-fatal user errors 4880@item warn 4881warnings 4882@item warning 4883warnings 4884@end table 4885 4886@c ---------------------------------------------------------------- 4887@node map_reload_interval Parameter, nfs_allow_any_interface Parameter, log_options Parameter, Global Parameters 4888@comment node-name, next, previous, up 4889@subsection @t{map_reload_interval} Parameter 4890@cindex map_reload_interval Parameter 4891 4892(type=numeric, default=3600). The number of seconds that @i{Amd} will 4893wait before it checks to see if any maps have changed at their source 4894(NIS servers, LDAP servers, files, etc.). @i{Amd} will reload only 4895those maps that have changed. 4896 4897@c ---------------------------------------------------------------- 4898@node nfs_allow_any_interface Parameter, nfs_allow_insecure_port Parameter, map_reload_interval Parameter, Global Parameters 4899@comment node-name, next, previous, up 4900@subsection @t{nfs_allow_any_interface} Parameter 4901@cindex nfs_allow_any_interface Parameter 4902 4903(type=string, default=@samp{no}). Normally @i{Amd} accepts local NFS 4904packets only from 127.0.0.1. If this parameter is set to @samp{yes}, 4905then @i{amd} will accept local NFS packets from any local interface; 4906this is useful on hosts that may have multiple interfaces where the 4907system is forced to send all outgoing packets (even those bound to the 4908same host) via an address other than 127.0.0.1. 4909 4910@c ---------------------------------------------------------------- 4911@node nfs_allow_insecure_port Parameter, nfs_proto Parameter, nfs_allow_any_interface Parameter, Global Parameters 4912@comment node-name, next, previous, up 4913@subsection @t{nfs_allow_insecure_port} Parameter 4914@cindex nfs_allow_insecure_port Parameter 4915 4916(type=string, default=@samp{no}). Normally @i{Amd} will refuse requests 4917coming from unprivileged ports (i.e., ports >= 1024 on Unix systems), 4918so that only privileged users and the kernel can send NFS requests to 4919it. However, some kernels (certain versions of Darwin, MacOS X, and 4920Linux) have bugs that cause them to use unprivileged ports in certain 4921situations, which causes @i{Amd} to stop dead in its tracks. This 4922parameter allows @i{Amd} to operate normally even on such systems, at the 4923expense of a slight decrease in the security of its operations. If 4924you see messages like ``ignoring request from foo:1234, port not 4925reserved'' in your @i{Amd} log, try enabling this parameter and give it 4926another go. 4927 4928@c ---------------------------------------------------------------- 4929@node nfs_proto Parameter, nfs_retransmit_counter Parameter, nfs_allow_insecure_port Parameter, Global Parameters 4930@comment node-name, next, previous, up 4931@subsection @t{nfs_proto} Parameter 4932@cindex nfs_proto Parameter 4933 4934(type=string, default to trying version tcp then udp). By default, 4935@i{Amd} tries @code{tcp} and then @code{udp}. This option forces the 4936overall NFS protocol used to TCP or UDP. It overrides what is in the 4937@i{Amd} maps, and is useful when @i{Amd} is compiled with TCP support 4938in NFSv2/NFSv3 that may not be stable. With this option you can turn 4939off the complete usage of TCP for NFS dynamically (without having to 4940recompile @i{Amd}), and use UDP only, until such time as TCP support 4941is desired again. 4942 4943@c ---------------------------------------------------------------- 4944@node nfs_retransmit_counter Parameter, nfs_retransmit_counter_udp Parameter, nfs_proto Parameter, Global Parameters 4945@comment node-name, next, previous, up 4946@subsection @t{nfs_retransmit_counter} Parameter 4947@cindex nfs_retransmit_counter Parameter 4948 4949(type=numeric, default=11). Same as the @i{retransmit} part of the 4950@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the 4951number of NFS retransmissions that the kernel will use to communicate 4952with @i{Amd} using either UDP or TCP mounts. @xref{-t Option}. 4953 4954@c ---------------------------------------------------------------- 4955@node nfs_retransmit_counter_udp Parameter, nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter Parameter, Global Parameters 4956@comment node-name, next, previous, up 4957@subsection @t{nfs_retransmit_counter_udp} Parameter 4958@cindex nfs_retransmit_counter_udp Parameter 4959@cindex nfs_retransmit_counter Parameter 4960@cindex UDP 4961 4962(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4963parameter, but applied globally only to UDP mounts. 4964@xref{nfs_retransmit_counter Parameter}. 4965 4966@c ---------------------------------------------------------------- 4967@node nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter_toplvl Parameter, nfs_retransmit_counter_udp Parameter, Global Parameters 4968@comment node-name, next, previous, up 4969@subsection @t{nfs_retransmit_counter_tcp} Parameter 4970@cindex nfs_retransmit_counter_tcp Parameter 4971@cindex nfs_retransmit_counter Parameter 4972@cindex TCP 4973 4974(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4975parameter, but applied globally only to TCP mounts. 4976@xref{nfs_retransmit_counter Parameter}. 4977 4978@c ---------------------------------------------------------------- 4979@node nfs_retransmit_counter_toplvl Parameter, nfs_retry_interval Parameter, nfs_retransmit_counter_tcp Parameter, Global Parameters 4980@comment node-name, next, previous, up 4981@subsection @t{nfs_retransmit_counter_toplvl} Parameter 4982@cindex nfs_retransmit_counter_toplvl Parameter 4983@cindex nfs_retransmit_counter Parameter 4984@cindex UDP 4985 4986(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4987parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 4988systems it is useful to set this differently than the OS default, so 4989as to better tune @i{Amd}'s responsiveness under heavy scheduler 4990loads. @xref{nfs_retransmit_counter Parameter}. 4991 4992@c ---------------------------------------------------------------- 4993@node nfs_retry_interval Parameter, nfs_retry_interval_udp Parameter, nfs_retransmit_counter_toplvl Parameter, Global Parameters 4994@comment node-name, next, previous, up 4995@subsection @t{nfs_retry_interval} Parameter 4996@cindex nfs_retry_interval Parameter 4997 4998(type=numeric, default=8). Same as the @i{timeout} part of the 4999@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the NFS 5000timeout interval, in @emph{tenths} of seconds, between NFS/RPC retries 5001(for UDP or TCP). This is the value that the kernel will use to 5002communicate with @i{Amd}. @xref{-t Option}. 5003 5004@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 5005retries. The values of the @i{nfs_retransmit_counter} and the 5006@i{nfs_retry_interval} parameters change the overall retry interval. 5007Too long an interval gives poor interactive response; too short an 5008interval causes excessive retries. 5009 5010@c ---------------------------------------------------------------- 5011@node nfs_retry_interval_udp Parameter, nfs_retry_interval_tcp Parameter, nfs_retry_interval Parameter, Global Parameters 5012@comment node-name, next, previous, up 5013@subsection @t{nfs_retry_interval_udp} Parameter 5014@cindex nfs_retry_interval_udp Parameter 5015@cindex nfs_retry_interval Parameter 5016@cindex UDP 5017 5018(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5019parameter, but applied globally only to UDP mounts. 5020@xref{nfs_retry_interval Parameter}. 5021 5022@c ---------------------------------------------------------------- 5023@node nfs_retry_interval_tcp Parameter, nfs_retry_interval_toplvl Parameter, nfs_retry_interval_udp Parameter, Global Parameters 5024@comment node-name, next, previous, up 5025@subsection @t{nfs_retry_interval_tcp} Parameter 5026@cindex nfs_retry_interval_tcp Parameter 5027@cindex nfs_retry_interval Parameter 5028@cindex TCP 5029 5030(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5031parameter, but applied globally only to TCP mounts. 5032@xref{nfs_retry_interval Parameter}. 5033 5034@c ---------------------------------------------------------------- 5035@node nfs_retry_interval_toplvl Parameter, nfs_vers Parameter, nfs_retry_interval_tcp Parameter, Global Parameters 5036@comment node-name, next, previous, up 5037@subsection @t{nfs_retry_interval_toplvl} Parameter 5038@cindex nfs_retry_interval_toplvl Parameter 5039@cindex nfs_retry_interval Parameter 5040@cindex UDP 5041 5042(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5043parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 5044systems it is useful to set this differently than the OS default, so 5045as to better tune @i{Amd}'s responsiveness under heavy scheduler 5046loads. @xref{nfs_retry_interval Parameter}. 5047 5048@c ---------------------------------------------------------------- 5049@node nfs_vers Parameter, nis_domain Parameter, nfs_retry_interval_toplvl Parameter, Global Parameters 5050@comment node-name, next, previous, up 5051@subsection @t{nfs_vers} Parameter 5052@cindex nfs_vers Parameter 5053 5054(type=numeric, default to trying version 3 then 2). By default, 5055@i{Amd} tries version 3 and then version 2. This option forces the 5056overall NFS protocol used to version 3 or 2. It overrides what is in 5057the @i{Amd} maps, and is useful when @i{Amd} is compiled with NFSv3 5058support that may not be stable. With this option you can turn off the 5059complete usage of NFSv3 dynamically (without having to recompile 5060@i{Amd}), and use NFSv2 only, until such time as NFSv3 support is 5061desired again. 5062 5063@c ---------------------------------------------------------------- 5064@node nis_domain Parameter, normalize_hostnames Parameter, nfs_vers Parameter, Global Parameters 5065@comment node-name, next, previous, up 5066@subsection @t{nis_domain} Parameter 5067@cindex nis_domain Parameter 5068 5069(type=string, default to local NIS domain name). Same as the 5070@code{-y} option to @i{Amd}. Specify an alternative NIS domain from 5071which to fetch the NIS maps. The default is the system domain name. 5072This option is ignored if NIS support is not available. 5073 5074@c ---------------------------------------------------------------- 5075@node normalize_hostnames Parameter, normalize_slashes Parameter, nis_domain Parameter, Global Parameters 5076@comment node-name, next, previous, up 5077@subsection @t{normalize_hostnames} Parameter 5078@cindex normalize_hostnames Parameter 5079 5080(type=boolean, default=@samp{no}). Same as the @code{-n} option to @i{Amd}. 5081If @samp{yes}, then the name referred to by @code{$@{rhost@}} is normalized 5082relative to the host database before being used. The effect is to 5083translate aliases into ``official'' names. 5084 5085@c ---------------------------------------------------------------- 5086@node normalize_slashes Parameter, os Parameter, normalize_hostnames Parameter, Global Parameters 5087@comment node-name, next, previous, up 5088@subsection @t{normalize_slashes} Parameter 5089@cindex normalize_slashes Parameter 5090 5091(type=boolean, default=@samp{yes}). If @samp{yes} then amd will 5092condense all multiple @code{/} (slash) characters into one and remove 5093all trailing slashes. If @samp{no}, then amd will not touch strings 5094that may contain repeated or trailing slashes. The latter is 5095sometimes useful with SMB mounts, which often require multiple slash 5096characters in pathnames. 5097 5098@c ---------------------------------------------------------------- 5099@node os Parameter, osver Parameter, normalize_slashes Parameter, Global Parameters 5100@comment node-name, next, previous, up 5101@subsection @t{os} Parameter 5102@cindex os Parameter 5103 5104(type=string, default to compiled in value). Same as the @code{-O} 5105option to @i{Amd}. Allows you to override the compiled-in name of the 5106operating system. Useful when the built-in name is not desired for 5107backward compatibility reasons. For example, if the built-in name is 5108@samp{sunos5}, you can override it to @samp{sos5}, and use older maps 5109which were written with the latter in mind. 5110 5111 5112@c ---------------------------------------------------------------- 5113@node osver Parameter, pid_file Parameter, os Parameter, Global Parameters 5114@comment node-name, next, previous, up 5115@subsection @t{osver} Parameter 5116@cindex osver Parameter 5117 5118(type=string, default to compiled in value). Same as the @code{-o} 5119option to @i{Amd}. Allows you to override the compiled-in version 5120number of the operating system. Useful when the built-in version is not 5121desired for backward compatibility reasons. For example, if the build 5122in version is @samp{2.5.1}, you can override it to @samp{5.5.1}, and use 5123older maps that were written with the latter in mind. 5124 5125@c ---------------------------------------------------------------- 5126@node pid_file Parameter, plock Parameter, osver Parameter, Global Parameters 5127@comment node-name, next, previous, up 5128@subsection @t{pid_file} Parameter 5129@cindex pid_file Parameter 5130 5131(type=string, default=@samp{/dev/stdout}). Specify a file to store the process 5132ID of the running daemon into. If not specified, @i{Amd} will print its 5133process id onto the standard output. Useful for killing @i{Amd} after 5134it had run. Note that the PID of a running @i{Amd} can also be 5135retrieved via @i{Amq} (@pxref{Amq -p option}). 5136 5137This file is used only if the @samp{print_pid} option is on 5138(@pxref{print_pid Parameter}). 5139 5140@c ---------------------------------------------------------------- 5141@node plock Parameter, portmap_program Parameter, pid_file Parameter, Global Parameters 5142@comment node-name, next, previous, up 5143@subsection @t{plock} Parameter 5144@cindex plock Parameter 5145 5146(type=boolean, default=@samp{yes}). Same as the @code{-S} option to @i{Amd}. 5147If @samp{yes}, lock the running executable pages of @i{Amd} into memory. 5148To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 5149or @b{mlockall}(2) 5150call can lock the @i{Amd} process into memory. This way there is less 5151chance the operating system will schedule, page out, and swap the 5152@i{Amd} process as needed. This improves @i{Amd}'s performance, at the 5153cost of reserving the memory used by the @i{Amd} process (making it 5154unavailable for other processes). 5155 5156@c ---------------------------------------------------------------- 5157@node portmap_program Parameter, preferred_amq_port Parameter, plock Parameter, Global Parameters 5158@comment node-name, next, previous, up 5159@subsection @t{portmap_program} Parameter 5160@cindex portmap_program Parameter 5161 5162(type=numeric, default=300019). Specify an alternate Port-mapper RPC 5163program number, other than the official number. This is useful when 5164running multiple @i{Amd} processes. For example, you can run another 5165@i{Amd} in ``test'' mode, without affecting the primary @i{Amd} process 5166in any way. For safety reasons, the alternate program numbers that can 5167be specified must be in the range 300019-300029, inclusive. @i{Amq} has 5168an option @code{-P} which can be used to specify an alternate program 5169number of an @i{Amd} to contact. In this way, amq can fully control any 5170number of @i{Amd} processes running on the same host. 5171 5172@c ---------------------------------------------------------------- 5173@node preferred_amq_port Parameter, print_pid Parameter, portmap_program Parameter, Global Parameters 5174@comment node-name, next, previous, up 5175@subsection @t{preferred_amq_port} Parameter 5176@cindex preferred_amq_port Parameter 5177 5178(type=numeric, default=0). Specify an alternate Port-mapper RPC port 5179number for @i{Amd}'s @i{Amq} service. This is used for both UDP and 5180TCP. Setting this value to 0 (or not defining it) will cause @i{Amd} 5181to select an arbitrary port number. Setting the @i{Amq} RPC service 5182port to a specific number is useful in firewalled or NAT'ed 5183environments, where you need to know which port @i{Amd} will listen 5184on. 5185 5186@c ---------------------------------------------------------------- 5187@node print_pid Parameter, print_version Parameter, preferred_amq_port Parameter, Global Parameters 5188@comment node-name, next, previous, up 5189@subsection @t{print_pid} Parameter 5190@cindex print_pid Parameter 5191 5192(type=boolean, default=@samp{no}). Same as the @code{-p} option to @i{Amd}. 5193If @samp{yes}, @i{Amd} will print its process ID upon starting. 5194 5195@c ---------------------------------------------------------------- 5196@node print_version Parameter, restart_mounts Parameter, print_pid Parameter, Global Parameters 5197@comment node-name, next, previous, up 5198@subsection @t{print_version} Parameter 5199@cindex print_version Parameter 5200 5201(type=boolean, default=@samp{no}). Same as the @code{-v} option to @i{Amd}, 5202but the version prints and @i{Amd} continues to run. If @samp{yes}, @i{Amd} 5203will print its version information string, which includes some 5204configuration and compilation values. 5205 5206@c ---------------------------------------------------------------- 5207@node restart_mounts Parameter, show_statfs_entries Parameter, print_version Parameter, Global Parameters 5208@comment node-name, next, previous, up 5209@subsection @t{restart_mounts} Parameter 5210@cindex restart_mounts Parameter 5211 5212(type=boolean, default=@samp{no}). Same as the @code{-r} option to @i{Amd}. 5213If @samp{yes} @i{Amd} will scan the mount table to determine which file 5214systems are currently mounted. Whenever one of these would have been 5215auto-mounted, @i{Amd} inherits it. 5216 5217@c ---------------------------------------------------------------- 5218@node show_statfs_entries Parameter, truncate_log Parameter, restart_mounts Parameter, Global Parameters 5219@comment node-name, next, previous, up 5220@subsection @t{show_statfs_entries} Parameter 5221@cindex show_statfs_entries Parameter 5222 5223(type=boolean), default=@samp{no}). If @samp{yes}, then all maps which are 5224browsable will also show the number of entries (keys) they have when 5225@b{df}(1) runs. (This is accomplished by returning non-zero values to 5226the @b{statfs}(2) system call). 5227 5228@c ---------------------------------------------------------------- 5229@node truncate_log Parameter, unmount_on_exit Parameter, show_statfs_entries Parameter, Global Parameters 5230@comment node-name, next, previous, up 5231@subsection @t{truncate_log} Parameter 5232@cindex truncate_log Parameter 5233 5234(type=boolean), default=@samp{no}). If @samp{yes}, then @i{Amd} will 5235truncate the log file (if it's a regular file) on startup. This could 5236be useful when conducting extensive testing on @i{Amd} maps (or 5237@i{Amd} itself) and you don't want to see log data from a previous run 5238in the same file. 5239 5240@c ---------------------------------------------------------------- 5241@node unmount_on_exit Parameter, use_tcpwrappers Parameter, truncate_log Parameter, Global Parameters 5242@comment node-name, next, previous, up 5243@subsection @t{unmount_on_exit} Parameter 5244@cindex unmount_on_exit Parameter 5245 5246(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will attempt 5247to unmount all file systems which it knows about. Normally it leaves 5248all (esp. NFS) mounted file systems intact. Note that @i{Amd} does not 5249know about file systems mounted before it starts up, unless the 5250@samp{restart_mounts} option is used (@pxref{restart_mounts Parameter}). 5251 5252@c ---------------------------------------------------------------- 5253@node use_tcpwrappers Parameter, vendor Parameter, unmount_on_exit Parameter, Global Parameters 5254@comment node-name, next, previous, up 5255@subsection @t{use_tcpwrappers} Parameter 5256@cindex use_tcpwrappers Parameter 5257 5258(type=boolean), default=@samp{yes}). If @samp{yes}, then amd will use 5259the tcpwrappers (tcpd/librwap) library (if available) to control 5260access to @i{Amd} via the @code{/etc/hosts.allow} and 5261@code{/etc/hosts.deny} files. @i{Amd} will verify that the host 5262running @i{Amq} is authorized to connect. The @code{amd} service name 5263must used in the @code{/etc/hosts.allow} and @code{/etc/hosts.deny} 5264files. For example, to allow only localhost to connect to @i{Amd}, 5265add this line to @code{/etc/hosts.allow}: 5266 5267@example 5268amd: localhost 5269@end example 5270 5271and this line to @code{/etc/hosts.deny}: 5272 5273@example 5274amd: ALL 5275@end example 5276 5277Consult the man pages for @b{hosts_access}(5) for more information on using 5278the tcpwrappers access-control library. 5279 5280Note that in particular, you should not configure your @code{hosts.allow} 5281file to spawn a command for @i{Amd}: that will cause @i{Amd} to not be able 5282to @code{waitpid} on the child process ID of any background un/mount that 5283@i{Amd} issued, resulting in a confused @i{Amd} that does not know what 5284happened to those background un/mount requests. 5285 5286@c ---------------------------------------------------------------- 5287@node vendor Parameter, , use_tcpwrappers Parameter, Global Parameters 5288@comment node-name, next, previous, up 5289@subsection @t{vendor} Parameter 5290@cindex vendor Parameter 5291 5292(type=string, default to compiled in value). The name of the vendor of 5293the operating system. Overrides the compiled-in vendor name. Useful 5294when the compiled-in name is not desired. For example, most Intel based 5295systems set the vendor name to @samp{unknown}, but you can set it to 5296@samp{redhat}. 5297 5298@c ================================================================ 5299@node Regular Map Parameters, amd.conf Examples, Global Parameters, Amd Configuration File 5300@comment node-name, next, previous, up 5301@section Regular Map Parameters 5302@cindex amd.conf regular map parameters 5303 5304The following parameters are applicable only to regular map sections. 5305 5306@menu 5307* map_name Parameter:: 5308* tag Parameter:: 5309@end menu 5310 5311@c ---------------------------------------------------------------- 5312@node map_name Parameter, tag Parameter, Regular Map Parameters, Regular Map Parameters 5313@comment node-name, next, previous, up 5314@subsection map_name Parameter 5315@cindex map_name Parameter 5316 5317(type=string, must be specified). Name of the map where the keys are 5318located. 5319 5320@c ---------------------------------------------------------------- 5321@node tag Parameter, , map_name Parameter, Regular Map Parameters 5322@comment node-name, next, previous, up 5323@subsection tag Parameter 5324@cindex tag Parameter 5325 5326(type=string, default no tag). Each map entry in the configuration file 5327can be tagged. If no tag is specified, that map section will always be 5328processed by @i{Amd}. If it is specified, then @i{Amd} will process the map 5329if the @code{-T} option was given to @i{Amd}, and the value given to that 5330command-line option matches that in the map section. 5331 5332@c ================================================================ 5333@node amd.conf Examples, , Regular Map Parameters, Amd Configuration File 5334@comment node-name, next, previous, up 5335@section amd.conf Examples 5336@cindex amd.conf examples 5337 5338The following is the actual @code{amd.conf} file I used at the 5339Computer Science Department of Columbia University. 5340 5341@example 5342# GLOBAL OPTIONS SECTION 5343[ global ] 5344normalize_hostnames = no 5345print_pid = no 5346#pid_file = /var/run/amd.pid 5347restart_mounts = yes 5348#unmount_on_exit = yes 5349auto_dir = /n 5350log_file = /var/log/amd 5351log_options = all 5352#debug_options = defaults 5353plock = no 5354selectors_in_defaults = yes 5355# config.guess picks up "sunos5" and I don't want to edit my maps yet 5356os = sos5 5357# if you print_version after setting up "os", it will show it. 5358print_version = no 5359map_type = file 5360search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib 5361browsable_dirs = yes 5362fully_qualified_hosts = no 5363 5364# DEFINE AN AMD MOUNT POINT 5365[ /u ] 5366map_name = amd.u 5367 5368[ /proj ] 5369map_name = amd.proj 5370 5371[ /src ] 5372map_name = amd.src 5373 5374[ /misc ] 5375map_name = amd.misc 5376 5377[ /import ] 5378map_name = amd.import 5379 5380[ /tftpboot/.amd ] 5381tag = tftpboot 5382map_name = amd.tftpboot 5383@end example 5384 5385@c ################################################################ 5386@node Run-time Administration, FSinfo, Amd Configuration File, Top 5387@comment node-name, next, previous, up 5388@chapter Run-time Administration 5389@cindex Run-time administration 5390@cindex Amq command 5391 5392@menu 5393* Starting Amd:: 5394* Stopping Amd:: 5395* Restarting Amd:: 5396* Controlling Amd:: 5397@end menu 5398 5399@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration 5400@comment node-name, next, previous, up 5401@section Starting @i{Amd} 5402@cindex Starting Amd 5403@cindex Additions to /etc/rc.local 5404@cindex /etc/rc.local additions 5405@cindex ctl-amd 5406 5407@i{Amd} is best started from @samp{/etc/rc.local} on BSD systems, or 5408from the appropriate start-level script in @samp{/etc/init.d} on System V 5409systems. 5410 5411@example 5412if [ -f /usr/local/sbin/ctl-amd ]; then 5413 /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console 5414fi 5415@end example 5416 5417@noindent 5418The shell script, @samp{ctl-amd} is used to start, stop, or restart 5419@i{Amd}. It is a relatively generic script. All options you want to 5420set should not be made in this script, but rather updated in the 5421@file{amd.conf} file. @xref{Amd Configuration File}. 5422 5423If you do not wish to use an @i{Amd} configuration file, you may start 5424@i{Amd} manually. For example, getting the map entries via NIS: 5425 5426@example 5427amd -r -l /var/log/amd `ypcat -k auto.master` 5428@end example 5429 5430@node Stopping Amd, Restarting Amd, Starting Amd, Run-time Administration 5431@comment node-name, next, previous, up 5432@section Stopping @i{Amd} 5433@cindex Stopping Amd 5434@cindex SIGTERM signal 5435@cindex SIGINT signal 5436 5437@i{Amd} stops in response to two signals. 5438 5439@table @samp 5440@item SIGTERM 5441causes the top-level automount points to be unmounted and then @i{Amd} 5442to exit. Any automounted filesystems are left mounted. They can be 5443recovered by restarting @i{Amd} with the @code{-r} command line option.@refill 5444 5445@item SIGINT 5446causes @i{Amd} to attempt to unmount any filesystems which it has 5447automounted, in addition to the actions of @samp{SIGTERM}. This signal 5448is primarily used for debugging.@refill 5449@end table 5450 5451Actions taken for other signals are undefined. 5452 5453The easiest and safest way to stop @i{Amd}, without having to find its 5454process ID by hand, is to use the @file{ctl-amd} script, as with: 5455 5456@example 5457ctl-amd stop 5458@end example 5459 5460@node Restarting Amd, Controlling Amd, Stopping Amd, Run-time Administration 5461@comment node-name, next, previous, up 5462@section Restarting @i{Amd} 5463@cindex Restarting Amd 5464@cindex Killing and starting Amd 5465 5466Before @i{Amd} can be started, it is vital to ensure that no other 5467@i{Amd} processes are managing any of the mount points, and that the 5468previous process(es) have terminated cleanly. When a terminating signal 5469is set to @i{Amd}, the automounter does @emph{not} terminate right then. 5470Rather, it starts by unmounting all of its managed mount mounts in the 5471background, and then terminates. It usually takes a few seconds for 5472this process to happen, but it can take an arbitrarily longer time. If 5473two or more @i{Amd} processes attempt to manage the same mount point, it 5474usually will result in a system lockup. 5475 5476The easiest and safest way to restart @i{Amd}, without having to find 5477its process ID by hand, sending it the @samp{SIGTERM} signal, waiting for @i{Amd} 5478to die cleanly, and verifying so, is to use the @file{ctl-amd} script, 5479as with: 5480 5481@example 5482ctl-amd restart 5483@end example 5484 5485The script will locate the process ID of @i{Amd}, kill it, and wait for 5486it to die cleanly before starting a new instance of the automounter. 5487@file{ctl-amd} will wait for a total of 30 seconds for @i{Amd} to die, 5488and will check once every 5 seconds if it had. 5489 5490@node Controlling Amd, , Restarting Amd, Run-time Administration 5491@comment node-name, next, previous, up 5492@section Controlling @i{Amd} 5493@cindex Controlling Amd 5494@cindex Discovering what is going on at run-time 5495@cindex Listing currently mounted filesystems 5496 5497It is sometimes desirable or necessary to exercise external control 5498over some of @i{Amd}'s internal state. To support this requirement, 5499@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. 5500A variety of information is available. 5501 5502@i{Amq} generally applies an operation, specified by a single letter option, 5503to a list of mount points. The default operation is to obtain statistics 5504about each mount point. This is similar to the output shown above 5505but includes information about the number and type of accesses to each 5506mount point. 5507 5508@menu 5509* Amq default:: Default command behavior. 5510* Amq -f option:: Flushing the map cache. 5511* Amq -h option:: Controlling a non-local host. 5512* Amq -H option:: Print help message. 5513* Amq -l option:: Controlling the log file. 5514* Amq -m option:: Obtaining mount statistics. 5515* Amq -p option:: Getting Amd's process ID. 5516* Amq -P option:: Contacting alternate Amd processes. 5517* Amq -q option:: Suppress synchronous unmounting errors. 5518* Amq -s option:: Obtaining global statistics. 5519* Amq -T option:: Use TCP transport. 5520* Amq -U option:: Use UDP transport. 5521* Amq -u option:: Forcing volumes to time out. 5522* Amq -v option:: Version information. 5523* Amq -w option:: Print Amd current working directory. 5524* Other Amq options:: Three other special options. 5525@end menu 5526 5527@c ---------------------------------------------------------------- 5528@node Amq default, Amq -f option, Controlling Amd, Controlling Amd 5529@comment node-name, next, previous, up 5530@subsection @i{Amq} default information 5531 5532With no arguments, @dfn{Amq} obtains a brief list of all existing 5533mounts created by @i{Amd}. This is different from the list displayed by 5534@b{df}(1) since the latter only includes system mount points. 5535 5536@noindent 5537The output from this option includes the following information: 5538 5539@itemize @bullet 5540@item 5541the automount point, 5542@item 5543the filesystem type, 5544@item 5545the mount map or mount information, 5546@item 5547the internal, or system mount point. 5548@end itemize 5549 5550@noindent 5551For example: 5552 5553@example 5554/ root "root" sky:(pid75) 5555/homes toplvl /usr/local/etc/amd.homes /homes 5556/home toplvl /usr/local/etc/amd.home /home 5557/homes/jsp nfs charm:/home/charm /a/charm/home/charm/jsp 5558/homes/phjk nfs toytown:/home/toytown /a/toytown/home/toytown/ai/phjk 5559@end example 5560 5561@noindent 5562If an argument is given then statistics for that volume name will 5563be output. For example: 5564 5565@example 5566What Uid Getattr Lookup RdDir RdLnk Statfs Mounted@@ 5567/homes 0 1196 512 22 0 30 90/09/14 12:32:55 5568/homes/jsp 0 0 0 0 1180 0 90/10/13 12:56:58 5569@end example 5570 5571@table @code 5572@item What 5573the volume name. 5574 5575@item Uid 5576ignored. 5577 5578@item Getattr 5579the count of NFS @dfn{getattr} requests on this node. This should only be 5580non-zero for directory nodes. 5581 5582@item Lookup 5583the count of NFS @dfn{lookup} requests on this node. This should only be 5584non-zero for directory nodes. 5585 5586@item RdDir 5587the count of NFS @dfn{readdir} requests on this node. This should only 5588be non-zero for directory nodes. 5589 5590@item RdLnk 5591the count of NFS @dfn{readlink} requests on this node. This should be 5592zero for directory nodes. 5593 5594@item Statfs 5595the count of NFS @dfn{statfs} requests on this node. This should only 5596be non-zero for top-level automount points. 5597 5598@item Mounted@@ 5599the date and time the volume name was first referenced. 5600@end table 5601 5602@c ---------------------------------------------------------------- 5603@node Amq -f option, Amq -h option, Amq default, Controlling Amd 5604@comment node-name, next, previous, up 5605@subsection @i{Amq} @code{-f} option 5606@cindex Flushing the map cache 5607@cindex Map cache, flushing 5608 5609The @code{-f} option causes @i{Amd} to flush the internal mount map cache. 5610This is useful for example in Hesiod maps since @i{Amd} will not 5611automatically notice when they have been updated. The map cache can 5612also be synchronized with the map source by using the @samp{sync} option 5613(@pxref{Automount Filesystem}).@refill 5614 5615@c ---------------------------------------------------------------- 5616@node Amq -h option, Amq -H option, Amq -f option, Controlling Amd 5617@comment node-name, next, previous, up 5618@subsection @i{Amq} @code{-h} option 5619@cindex Querying an alternate host 5620 5621By default the local host is used. In an HP-UX cluster the root server 5622is used since that is the only place in the cluster where @i{Amd} will 5623be running. To query @i{Amd} on another host the @code{-h} option should 5624be used. 5625 5626@c ---------------------------------------------------------------- 5627@node Amq -H option, Amq -l option, Amq -h option, Controlling Amd 5628@comment node-name, next, previous, up 5629@subsection @i{Amq} @code{-H} option 5630@cindex Displaying brief help 5631@cindex Help; showing from Amq 5632 5633Print a brief help and usage string. 5634 5635@c ---------------------------------------------------------------- 5636@node Amq -l option, Amq -m option, Amq -H option, Controlling Amd 5637@comment node-name, next, previous, up 5638@subsection @i{Amq} @code{-l} option 5639@cindex Resetting the Amd log file 5640@cindex Setting the Amd log file via Amq 5641@cindex Log file, resetting 5642 5643Tell @i{Amd} to use @i{log_file} as the log file name. For security 5644reasons, this @emph{must} be the same log file which @i{Amd} used when 5645started. This option is therefore only useful to refresh @i{Amd}'s open 5646file handle on the log file, so that it can be rotated and compressed 5647via daily cron jobs. 5648 5649@c ---------------------------------------------------------------- 5650@node Amq -m option, Amq -p option, Amq -l option, Controlling Amd 5651@comment node-name, next, previous, up 5652@subsection @i{Amq} @code{-m} option 5653 5654The @code{-m} option displays similar information about mounted 5655filesystems, rather than automount points. The output includes the 5656following information: 5657 5658@itemize @bullet 5659@item 5660the mount information, 5661@item 5662the mount point, 5663@item 5664the filesystem type, 5665@item 5666the number of references to this filesystem, 5667@item 5668the server hostname, 5669@item 5670the state of the file server, 5671@item 5672any error which has occurred. 5673@end itemize 5674 5675For example: 5676 5677@example 5678"root" truth:(pid602) root 1 localhost is up 5679hesiod.home /home toplvl 1 localhost is up 5680hesiod.vol /vol toplvl 1 localhost is up 5681hesiod.homes /homes toplvl 1 localhost is up 5682amy:/home/amy /a/amy/home/amy nfs 5 amy is up 5683swan:/home/swan /a/swan/home/swan nfs 0 swan is up (Permission denied) 5684ex:/home/ex /a/ex/home/ex nfs 0 ex is down 5685@end example 5686 5687When the reference count is zero the filesystem is not mounted but 5688the mount point and server information is still being maintained 5689by @i{Amd}. 5690 5691@c ---------------------------------------------------------------- 5692@ignore 5693@comment Retained for future consideration: from the description of the 5694@comment amq -M option removed in amd 6.0.5. 5695 5696A future release of @i{Amd} will include code to allow the @b{mount}(8) 5697command to mount automount points: 5698 5699@example 5700mount -t amd /vol hesiod.vol 5701@end example 5702 5703This will then allow @i{Amd} to be controlled from the standard system 5704filesystem mount list. 5705 5706@end ignore 5707 5708@c ---------------------------------------------------------------- 5709@node Amq -p option, Amq -P option, Amq -m option, Controlling Amd 5710@comment node-name, next, previous, up 5711@subsection @i{Amq} @code{-p} option 5712@cindex Process ID; Amd 5713@cindex Amd's process ID 5714@cindex Amd's PID 5715@cindex PID; Amd 5716 5717Return the process ID of the remote or locally running @i{Amd}. Useful 5718when you need to send a signal to the local @i{Amd} process, and would 5719rather not have to search through the process table. This option is 5720used in the @file{ctl-amd} script. 5721 5722@c ---------------------------------------------------------------- 5723@node Amq -P option, Amq -q option, Amq -p option, Controlling Amd 5724@comment node-name, next, previous, up 5725@subsection @i{Amq} @code{-P} option 5726@cindex Multiple Amd processes 5727@cindex Running multiple Amd 5728@cindex Debugging a new Amd configuration 5729@cindex RPC Program numbers; Amd 5730 5731Contact an alternate running @i{Amd} that had registered itself on a 5732different RPC @var{program_number} and apply all other operations to 5733that instance of the automounter. This is useful when you run multiple 5734copies of @i{Amd}, and need to manage each one separately. If not 5735specified, @i{Amq} will use the default program number for @i{Amd}, 300019. 5736For security reasons, the only alternate program numbers @i{Amd} can use 5737range from 300019 to 300029, inclusive. 5738 5739For example, to kill an alternate running @i{Amd}: 5740 5741@example 5742kill `amq -p -P 300020` 5743@end example 5744 5745@c ---------------------------------------------------------------- 5746@node Amq -q option, Amq -s option, Amq -P option, Controlling Amd 5747@comment node-name, next, previous, up 5748@subsection @i{Amq} @code{-q} option 5749@cindex Unmounting a filesystem 5750 5751Suppress any error messages produced when a synchronous unmount fails. 5752See @ref{Amq -u option}. 5753 5754@c ---------------------------------------------------------------- 5755@node Amq -s option, Amq -T option, Amq -q option, Controlling Amd 5756@comment node-name, next, previous, up 5757@subsection @i{Amq} @code{-s} option 5758@cindex Global statistics 5759@cindex Statistics 5760 5761The @code{-s} option displays global statistics. If any other options are specified 5762or any filesystems named then this option is ignored. For example: 5763 5764@example 5765requests stale mount mount unmount 5766deferred fhandles ok failed failed 57671054 1 487 290 7017 5768@end example 5769 5770@table @samp 5771@item Deferred requests 5772are those for which an immediate reply could not be constructed. For 5773example, this would happen if a background mount was required. 5774 5775@item Stale filehandles 5776counts the number of times the kernel passes a stale filehandle to @i{Amd}. 5777Large numbers indicate problems. 5778 5779@item Mount ok 5780counts the number of automounts which were successful. 5781 5782@item Mount failed 5783counts the number of automounts which failed. 5784 5785@item Unmount failed 5786counts the number of times a filesystem could not be unmounted. Very 5787large numbers here indicate that the time between unmount attempts 5788should be increased. 5789@end table 5790 5791@c ---------------------------------------------------------------- 5792@node Amq -T option, Amq -U option, Amq -s option, Controlling Amd 5793@comment node-name, next, previous, up 5794@subsection @i{Amq} @code{-T} option 5795@cindex Forcing Amq to use a TCP transport 5796@cindex TCP; using with Amq 5797 5798The @code{-T} option causes the @i{Amq} to contact @i{Amd} using the TCP 5799transport only (connection oriented). Normally, @i{Amq} will use TCP 5800first, and if that failed, will try UDP. 5801 5802@c ---------------------------------------------------------------- 5803@node Amq -U option, Amq -u option, Amq -T option, Controlling Amd 5804@comment node-name, next, previous, up 5805@subsection @i{Amq} @code{-U} option 5806@cindex Forcing Amq to use a UDP transport 5807@cindex UDP; using with Amq 5808 5809The @code{-U} option causes the @i{Amq} to contact @i{Amd} using the UDP 5810transport only (connectionless). Normally, @i{Amq} will use TCP first, 5811and if that failed, will try UDP. 5812 5813@c ---------------------------------------------------------------- 5814@node Amq -u option, Amq -v option, Amq -U option, Controlling Amd 5815@comment node-name, next, previous, up 5816@subsection @i{Amq} @code{-u} option 5817@cindex Forcing filesystem to time out 5818@cindex Unmounting a filesystem 5819 5820The @code{-u} option causes the time-to-live interval of the named 5821mount points to be expired, thus causing an unmount attempt. This is 5822the only safe way to unmount an automounted filesystem. If @code{-u} 5823is repeated, then @i{Amd} will attempt to unmount the filesystem 5824synchronously. This makes things like 5825 5826@example 5827amq -uu /t/cd0d && eject cd0 5828@end example 5829 5830@noindent 5831work as expected. Any error messages this might produce can be 5832suppressed with the @code{-q} option. See @ref{Amq -q option}. 5833 5834@c The @code{-H} option informs @i{Amd} that the specified mount point 5835@c has hung - as if its keepalive timer had expired. 5836 5837@c ---------------------------------------------------------------- 5838@node Amq -v option, Amq -w option, Amq -u option, Controlling Amd 5839@comment node-name, next, previous, up 5840@subsection @i{Amq} @code{-v} option 5841@cindex Version information at run-time 5842 5843The @code{-v} option displays the version of @i{Amd} in a similar way to 5844@i{Amd}'s @code{-v} option. 5845 5846@c ---------------------------------------------------------------- 5847@node Amq -w option, Other Amq options, Amq -v option, Controlling Amd 5848@comment node-name, next, previous, up 5849@subsection @i{Amq} @code{-w} option 5850@cindex Getting real working directory 5851 5852The @code{-w} option translates a full pathname as returned by 5853@b{getpwd}(3) into a short @i{Amd} pathname that goes through its mount 5854points. This option requires that @i{Amd} is running. 5855 5856@c ---------------------------------------------------------------- 5857@node Other Amq options, , Amq -w option, Controlling Amd 5858@comment node-name, next, previous, up 5859@subsection Other @i{Amq} options 5860@cindex Logging options via Amq 5861@cindex Debugging options via Amq 5862 5863Two other operations are implemented. These modify the state of @i{Amd} 5864as a whole, rather than any particular filesystem. The @code{-x} and 5865@code{-D} options have exactly the same effect as @i{Amd}'s corresponding 5866command line options. 5867 5868When @i{Amd} receives the @code{-x} flag, it disallows turning off the 5869@samp{fatal} or @samp{error} flags. Both are on by default. They are 5870mandatory so that @i{Amd} could report important errors, including 5871errors relating to turning flags on/off. 5872 5873@c ################################################################ 5874@node FSinfo, Hlfsd, Run-time Administration, Top 5875@comment node-name, next, previous, up 5876@chapter FSinfo 5877@cindex FSinfo 5878@cindex Filesystem info package 5879 5880XXX: this chapter should be reviewed by someone knowledgeable with 5881fsinfo. 5882 5883@menu 5884* FSinfo Overview:: Introduction to FSinfo. 5885* Using FSinfo:: Basic concepts. 5886* FSinfo Grammar:: Language syntax, semantics and examples. 5887* FSinfo host definitions:: Defining a new host. 5888* FSinfo host attributes:: Definable host attributes. 5889* FSinfo filesystems:: Defining locally attached filesystems. 5890* FSinfo static mounts:: Defining additional static mounts. 5891* FSinfo automount definitions:: 5892* FSinfo Command Line Options:: 5893* FSinfo errors:: 5894@end menu 5895 5896@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo 5897@comment node-name, next, previous, up 5898@section @i{FSinfo} overview 5899@cindex FSinfo overview 5900 5901@i{FSinfo} is a filesystem management tool. It has been designed to 5902work with @i{Amd} to help system administrators keep track of the ever 5903increasing filesystem namespace under their control. 5904 5905The purpose of @i{FSinfo} is to generate all the important standard 5906filesystem data files from a single set of input data. Starting with a 5907single data source guarantees that all the generated files are 5908self-consistent. One of the possible output data formats is a set of 5909@i{Amd} maps which can be used among the set of hosts described in the 5910input data. 5911 5912@i{FSinfo} implements a declarative language. This language is 5913specifically designed for describing filesystem namespace and physical 5914layouts. The basic declaration defines a mounted filesystem including 5915its device name, mount point, and all the volumes and access 5916permissions. @i{FSinfo} reads this information and builds an internal 5917map of the entire network of hosts. Using this map, many different data 5918formats can be produced including @file{/etc/fstab}, 5919@file{/etc/exports}, @i{Amd} mount maps and 5920@file{/etc/bootparams}.@refill 5921 5922@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo 5923@comment node-name, next, previous, up 5924@section Using @i{FSinfo} 5925@cindex Using FSinfo 5926 5927The basic strategy when using @i{FSinfo} is to gather all the 5928information about all disks on all machines into one set of 5929declarations. For each machine being managed, the following data is 5930required: 5931 5932@itemize @bullet 5933@item 5934Hostname 5935@item 5936List of all filesystems and, optionally, their mount points. 5937@item 5938Names of volumes stored on each filesystem. 5939@item 5940NFS export information for each volume. 5941@item 5942The list of static filesystem mounts. 5943@end itemize 5944 5945The following information can also be entered into the same 5946configuration files so that all data can be kept in one place. 5947 5948@itemize @bullet 5949@item 5950List of network interfaces 5951@item 5952IP address of each interface 5953@item 5954Hardware address of each interface 5955@item 5956Dumpset to which each filesystem belongs 5957@item 5958and more @dots{} 5959@end itemize 5960 5961To generate @i{Amd} mount maps, the automount tree must also be defined 5962(@pxref{FSinfo automount definitions}). This will have been designed at 5963the time the volume names were allocated. Some volume names will not be 5964automounted, so @i{FSinfo} needs an explicit list of which volumes 5965should be automounted.@refill 5966 5967Hostnames are required at several places in the @i{FSinfo} language. It 5968is important to stick to either fully qualified names or unqualified 5969names. Using a mixture of the two will inevitably result in confusion. 5970 5971Sometimes volumes need to be referenced which are not defined in the set 5972of hosts being managed with @i{FSinfo}. The required action is to add a 5973dummy set of definitions for the host and volume names required. Since 5974the files generated for those particular hosts will not be used on them, 5975the exact values used is not critical. 5976 5977@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo 5978@comment node-name, next, previous, up 5979@section @i{FSinfo} grammar 5980@cindex FSinfo grammar 5981@cindex Grammar, FSinfo 5982 5983@i{FSinfo} has a relatively simple grammar. Distinct syntactic 5984constructs exist for each of the different types of data, though they 5985share a common flavor. Several conventions are used in the grammar 5986fragments below. 5987 5988The notation, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more 5989@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one 5990@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input 5991tokens. Items in angle brackets, @i{eg} @var{<hostname>}, represent 5992strings in the input. Strings need not be in double quotes, except to 5993differentiate them from reserved words. Quoted strings may include the 5994usual set of C ``@t{\}'' escape sequences with one exception: a 5995backslash-newline-whitespace sequence is squashed into a single space 5996character. To defeat this feature, put a further backslash at the start 5997of the second line. 5998 5999At the outermost level of the grammar, the input consists of a 6000sequence of host and automount declarations. These declarations are 6001all parsed before they are analyzed. This means they can appear in 6002any order and cyclic host references are possible. 6003 6004@example 6005fsinfo : @i{list(}fsinfo_attr@i{)} ; 6006 6007fsinfo_attr : host | automount ; 6008@end example 6009 6010@menu 6011* FSinfo host definitions:: 6012* FSinfo automount definitions:: 6013@end menu 6014 6015@node FSinfo host definitions, FSinfo host attributes, FSinfo Grammar, FSinfo 6016@comment node-name, next, previous, up 6017@section @i{FSinfo} host definitions 6018@cindex FSinfo host definitions 6019@cindex Defining a host, FSinfo 6020 6021A host declaration consists of three parts: a set of machine attribute 6022data, a list of filesystems physically attached to the machine, and a 6023list of additional statically mounted filesystems. 6024 6025@example 6026host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; 6027@end example 6028 6029Each host must be declared in this way exactly once. Such things as the 6030hardware address, the architecture and operating system types and the 6031cluster name are all specified within the @dfn{host data}. 6032 6033All the disks the machine has should then be described in the @dfn{list 6034of filesystems}. When describing disks, you can specify what 6035@dfn{volname} the disk/partition should have and all such entries are 6036built up into a dictionary which can then be used for building the 6037automounter maps. 6038 6039The @dfn{list of mounts} specifies all the filesystems that should be 6040statically mounted on the machine. 6041 6042@menu 6043* FSinfo host attributes:: 6044* FSinfo filesystems:: 6045* FSinfo static mounts:: 6046@end menu 6047 6048@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions 6049@comment node-name, next, previous, up 6050@section @i{FSinfo} host attributes 6051@cindex FSinfo host attributes 6052@cindex Defining host attributes, FSinfo 6053 6054The host data, @dfn{host_data}, always includes the @dfn{hostname}. In 6055addition, several other host attributes can be given. 6056 6057@example 6058host_data : @var{<hostname>} 6059 | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} 6060 ; 6061 6062host_attrs : host_attr "=" @var{<string>} 6063 | netif 6064 ; 6065 6066host_attr : "config" 6067 | "arch" 6068 | "os" 6069 | "cluster" 6070 ; 6071@end example 6072 6073The @dfn{hostname} is, typically, the fully qualified hostname of the 6074machine. 6075 6076Examples: 6077 6078@example 6079host dylan.doc.ic.ac.uk 6080 6081host @{ 6082 os = hpux 6083 arch = hp300 6084@} dougal.doc.ic.ac.uk 6085@end example 6086 6087The options that can be given as host attributes are shown below. 6088 6089@menu 6090* FSinfo netif Option:: FSinfo host netif. 6091* FSinfo config Option:: FSinfo host config. 6092* FSinfo arch Option:: FSinfo host arch. 6093* FSinfo os Option:: FSinfo host os. 6094* FSinfo cluster Option:: FSinfo host cluster. 6095@end menu 6096 6097@node FSinfo netif Option, FSinfo config Option, , FSinfo host attributes 6098@comment node-name, next, previous, up 6099@subsection netif Option 6100 6101This defines the set of network interfaces configured on the machine. 6102The interface attributes collected by @i{FSinfo} are the IP address, 6103subnet mask and hardware address. Multiple interfaces may be defined 6104for hosts with several interfaces by an entry for each interface. The 6105values given are sanity checked, but are currently unused for anything 6106else. 6107 6108@example 6109netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; 6110 6111netif_attrs : netif_attr "=" @var{<string>} ; 6112 6113netif_attr : "inaddr" | "netmask" | "hwaddr" ; 6114@end example 6115 6116Examples: 6117 6118@example 6119netif ie0 @{ 6120 inaddr = 129.31.81.37 6121 netmask = 0xfffffe00 6122 hwaddr = "08:00:20:01:a6:a5" 6123@} 6124 6125netif ec0 @{ @} 6126@end example 6127 6128@node FSinfo config Option, FSinfo arch Option, FSinfo netif Option, FSinfo host attributes 6129@comment node-name, next, previous, up 6130@subsection config Option 6131@cindex FSinfo config host attribute 6132@cindex config, FSinfo host attribute 6133 6134This option allows you to specify configuration variables for the 6135startup scripts (@file{rc} scripts). A simple string should immediately 6136follow the keyword. 6137 6138Example: 6139 6140@example 6141config "NFS_SERVER=true" 6142config "ZEPHYR=true" 6143@end example 6144 6145This option is currently unsupported. 6146 6147@node FSinfo arch Option, FSinfo os Option, FSinfo config Option, FSinfo host attributes 6148@comment node-name, next, previous, up 6149@subsection arch Option 6150@cindex FSinfo arch host attribute 6151@cindex arch, FSinfo host attribute 6152 6153This defines the architecture of the machine. For example: 6154 6155@example 6156arch = hp300 6157@end example 6158 6159This is intended to be of use when building architecture specific 6160mountmaps, however, the option is currently unsupported. 6161 6162@node FSinfo os Option, FSinfo cluster Option, FSinfo arch Option, FSinfo host attributes 6163@comment node-name, next, previous, up 6164@subsection os Option 6165@cindex FSinfo os host attribute 6166@cindex os, FSinfo host attribute 6167 6168This defines the operating system type of the host. For example: 6169 6170@example 6171os = hpux 6172@end example 6173 6174This information is used when creating the @file{fstab} files, for 6175example in choosing which format to use for the @file{fstab} entries 6176within the file. 6177 6178@node FSinfo cluster Option, , FSinfo os Option, FSinfo host attributes 6179@comment node-name, next, previous, up 6180@subsection cluster Option 6181@cindex FSinfo cluster host attribute 6182@cindex cluster, FSinfo host attribute 6183 6184This is used for specifying in which cluster the machine belongs. For 6185example: 6186 6187@example 6188cluster = "theory" 6189@end example 6190 6191The cluster is intended to be used when generating the automount maps, 6192although it is currently unsupported. 6193 6194@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions 6195@comment node-name, next, previous, up 6196@section @i{FSinfo} filesystems 6197@cindex FSinfo filesystems 6198 6199The list of physically attached filesystems follows the machine 6200attributes. These should define all the filesystems available from this 6201machine, whether exported or not. In addition to the device name, 6202filesystems have several attributes, such as filesystem type, mount 6203options, and @samp{fsck} pass number which are needed to generate 6204@file{fstab} entries. 6205 6206@example 6207filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; 6208 6209fs_data : fs_data_attr "=" @var{<string>} 6210 | mount 6211 ; 6212 6213fs_data_attr 6214 : "fstype" | "opts" | "passno" 6215 | "freq" | "dumpset" | "log" 6216 ; 6217@end example 6218 6219Here, @var{<device>} is the device name of the disk (for example, 6220@file{/dev/dsk/2s0}). The device name is used for building the mount 6221maps and for the @file{fstab} file. The attributes that can be 6222specified are shown in the following section. 6223 6224The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. 6225 6226@example 6227host dylan.doc.ic.ac.uk 6228 6229fs /dev/dsk/0s0 @{ 6230 fstype = swap 6231@} 6232 6233fs /dev/dsk/0s0 @{ 6234 fstype = hfs 6235 opts = rw,noquota,grpid 6236 passno = 0; 6237 freq = 1; 6238 mount / @{ @} 6239@} 6240 6241fs /dev/dsk/1s0 @{ 6242 fstype = hfs 6243 opts = defaults 6244 passno = 1; 6245 freq = 1; 6246 mount /usr @{ 6247 local @{ 6248 exportfs "dougal eden dylan zebedee brian" 6249 volname /nfs/hp300/local 6250 @} 6251 @} 6252@} 6253 6254fs /dev/dsk/2s0 @{ 6255 fstype = hfs 6256 opts = defaults 6257 passno = 1; 6258 freq = 1; 6259 mount default @{ 6260 exportfs "toytown_clients hangers_on" 6261 volname /home/dylan/dk2 6262 @} 6263@} 6264 6265fs /dev/dsk/3s0 @{ 6266 fstype = hfs 6267 opts = defaults 6268 passno = 1; 6269 freq = 1; 6270 mount default @{ 6271 exportfs "toytown_clients hangers_on" 6272 volname /home/dylan/dk3 6273 @} 6274@} 6275 6276fs /dev/dsk/5s0 @{ 6277 fstype = hfs 6278 opts = defaults 6279 passno = 1; 6280 freq = 1; 6281 mount default @{ 6282 exportfs "toytown_clients hangers_on" 6283 volname /home/dylan/dk5 6284 @} 6285@} 6286@end example 6287 6288@menu 6289* FSinfo fstype Option:: FSinfo filesystems fstype. 6290* FSinfo opts Option:: FSinfo filesystems opts. 6291* FSinfo passno Option:: FSinfo filesystems passno. 6292* FSinfo freq Option:: FSinfo filesystems freq. 6293* FSinfo mount Option:: FSinfo filesystems mount. 6294* FSinfo dumpset Option:: FSinfo filesystems dumpset. 6295* FSinfo log Option:: FSinfo filesystems log. 6296@end menu 6297 6298@node FSinfo fstype Option, FSinfo opts Option, , FSinfo filesystems 6299@comment node-name, next, previous, up 6300@subsection fstype Option 6301@cindex FSinfo fstype filesystems option 6302@cindex fstype, FSinfo filesystems option 6303@cindex export, FSinfo special fstype 6304 6305This specifies the type of filesystem being declared and will be placed 6306into the @file{fstab} file as is. The value of this option will be 6307handed to @code{mount} as the filesystem type---it should have such 6308values as @code{4.2}, @code{nfs} or @code{swap}. The value is not 6309examined for correctness. 6310 6311There is one special case. If the filesystem type is specified as 6312@samp{export} then the filesystem information will not be added to the 6313host's @file{fstab} information, but it will still be visible on the 6314network. This is useful for defining hosts which contain referenced 6315volumes but which are not under full control of @i{FSinfo}. 6316 6317Example: 6318 6319@example 6320fstype = swap 6321@end example 6322 6323@node FSinfo opts Option, FSinfo passno Option, FSinfo fstype Option, FSinfo filesystems 6324@comment node-name, next, previous, up 6325@subsection opts Option 6326@cindex FSinfo opts filesystems option 6327@cindex opts, FSinfo filesystems option 6328 6329This defines any options that should be given to @b{mount}(8) in the 6330@file{fstab} file. For example: 6331 6332@example 6333opts = rw,nosuid,grpid 6334@end example 6335 6336@node FSinfo passno Option, FSinfo freq Option, FSinfo opts Option, FSinfo filesystems 6337@comment node-name, next, previous, up 6338@subsection passno Option 6339@cindex FSinfo passno filesystems option 6340@cindex passno, FSinfo filesystems option 6341 6342This defines the @b{fsck}(8) pass number in which to check the 6343filesystem. This value will be placed into the @file{fstab} file. 6344 6345Example: 6346 6347@example 6348passno = 1 6349@end example 6350 6351@node FSinfo freq Option, FSinfo mount Option, FSinfo passno Option, FSinfo filesystems 6352@comment node-name, next, previous, up 6353@subsection freq Option 6354@cindex FSinfo freq filesystems option 6355@cindex freq, FSinfo filesystems option 6356 6357This defines the interval (in days) between dumps. The value is placed 6358as is into the @file{fstab} file. 6359 6360Example: 6361 6362@example 6363freq = 3 6364@end example 6365 6366@node FSinfo mount Option, FSinfo dumpset Option, FSinfo freq Option, FSinfo filesystems 6367@comment node-name, next, previous, up 6368@subsection mount Option 6369@cindex FSinfo mount filesystems option 6370@cindex mount, FSinfo filesystems option 6371@cindex exportfs, FSinfo mount option 6372@cindex volname, FSinfo mount option 6373@cindex sel, FSinfo mount option 6374 6375This defines the mountpoint at which to place the filesystem. If the 6376mountpoint of the filesystem is specified as @code{default}, then the 6377filesystem will be mounted in the automounter's tree under its volume 6378name and the mount will automatically be inherited by the automounter. 6379 6380Following the mountpoint, namespace information for the filesystem may 6381be described. The options that can be given here are @code{exportfs}, 6382@code{volname} and @code{sel}. 6383 6384The format is: 6385 6386@example 6387mount : "mount" vol_tree ; 6388 6389vol_tree : @i{list(}vol_tree_attr@i{)} ; 6390 6391vol_tree_attr 6392 : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; 6393 6394vol_tree_info 6395 : "exportfs" @var{<export-data>} 6396 | "volname" @var{<volname>} 6397 | "sel" @var{<selector-list>} 6398 ; 6399@end example 6400 6401Example: 6402 6403@example 6404mount default @{ 6405 exportfs "dylan dougal florence zebedee" 6406 volname /vol/andrew 6407@} 6408@end example 6409 6410In the above example, the filesystem currently being declared will have 6411an entry placed into the @file{exports} file allowing the filesystem to 6412be exported to the machines @code{dylan}, @code{dougal}, @code{florence} 6413and @code{zebedee}. The volume name by which the filesystem will be 6414referred to remotely, is @file{/vol/andrew}. By declaring the 6415mountpoint to be @code{default}, the filesystem will be mounted on the 6416local machine in the automounter tree, where @i{Amd} will automatically 6417inherit the mount as @file{/vol/andrew}.@refill 6418 6419@table @samp 6420@item exportfs 6421a string defining which machines the filesystem may be exported to. 6422This is copied, as is, into the @file{exports} file---no sanity checking 6423is performed on this string.@refill 6424 6425@item volname 6426a string which declares the remote name by which to reference the 6427filesystem. The string is entered into a dictionary and allows you to 6428refer to this filesystem in other places by this volume name.@refill 6429 6430@item sel 6431a string which is placed into the automounter maps as a selector for the 6432filesystem.@refill 6433 6434@end table 6435 6436@node FSinfo dumpset Option, FSinfo log Option, FSinfo mount Option, FSinfo filesystems 6437@comment node-name, next, previous, up 6438@subsection dumpset Option 6439@cindex FSinfo dumpset filesystems option 6440@cindex dumpset, FSinfo filesystems option 6441 6442This provides support for Imperial College's local file backup tools and 6443is not documented further here. 6444 6445@node FSinfo log Option, , FSinfo dumpset Option, FSinfo filesystems 6446@comment node-name, next, previous, up 6447@subsection log Option 6448@cindex FSinfo log filesystems option 6449@cindex log, FSinfo filesystems option 6450 6451Specifies the log device for the current filesystem. This is ignored if 6452not required by the particular filesystem type. 6453 6454@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions 6455@comment node-name, next, previous, up 6456@section @i{FSinfo} static mounts 6457@cindex FSinfo static mounts 6458@cindex Statically mounts filesystems, FSinfo 6459 6460Each host may also have a number of statically mounted filesystems. For 6461example, the host may be a diskless workstation in which case it will 6462have no @code{fs} declarations. In this case the @code{mount} 6463declaration is used to determine from where its filesystems will be 6464mounted. In addition to being added to the @file{fstab} file, this 6465information can also be used to generate a suitable @file{bootparams} 6466file.@refill 6467 6468@example 6469mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; 6470 6471localinfo : localinfo_attr @var{<string>} ; 6472 6473localinfo_attr 6474 : "as" 6475 | "from" 6476 | "fstype" 6477 | "opts" 6478 ; 6479@end example 6480 6481The filesystem specified to be mounted will be searched for in the 6482dictionary of volume names built when scanning the list of hosts' 6483definitions. 6484 6485The attributes have the following semantics: 6486@table @samp 6487@item from @var{machine} 6488mount the filesystem from the machine with the hostname of 6489@dfn{machine}.@refill 6490 6491@item as @var{mountpoint} 6492mount the filesystem locally as the name given, in case this is 6493different from the advertised volume name of the filesystem. 6494 6495@item opts @var{options} 6496native @b{mount}(8) options. 6497 6498@item fstype @var{type} 6499type of filesystem to be mounted. 6500@end table 6501 6502An example: 6503 6504@example 6505mount /export/exec/hp300/local as /usr/local 6506@end example 6507 6508If the mountpoint specified is either @file{/} or @file{swap}, the 6509machine will be considered to be booting off the net and this will be 6510noted for use in generating a @file{bootparams} file for the host which 6511owns the filesystems. 6512 6513@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo 6514@comment node-name, next, previous, up 6515@section Defining an @i{Amd} Mount Map in @i{FSinfo} 6516@cindex FSinfo automount definitions 6517@cindex Defining an Amd mount map, FSinfo 6518 6519The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining 6520all the automount trees. @i{FSinfo} takes all the definitions found and 6521builds one map for each top level tree. 6522 6523The automount tree is usually defined last. A single automount 6524configuration will usually apply to an entire management domain. One 6525@code{automount} declaration is needed for each @i{Amd} automount point. 6526@i{FSinfo} determines whether the automount point is @dfn{direct} 6527(@pxref{Direct Automount Filesystem}) or @dfn{indirect} 6528(@pxref{Top-level Filesystem}). Direct automount points are 6529distinguished by the fact that there is no underlying 6530@dfn{automount_tree}.@refill 6531 6532@example 6533automount : "automount" @i{opt(}auto_opts@i{)} automount_tree ; 6534 6535auto_opts : "opts" @var{<mount-options>} ; 6536 6537automount_tree 6538 : @i{list(}automount_attr@i{)} 6539 ; 6540 6541automount_attr 6542 : @var{<string>} "=" @var{<volname>} 6543 | @var{<string>} "->" @var{<symlink>} 6544 | @var{<string>} "@{" automount_tree "@}" 6545 ; 6546@end example 6547 6548If @var{<mount-options>} is given, then it is the string to be placed in 6549the maps for @i{Amd} for the @code{opts} option. 6550 6551A @dfn{map} is typically a tree of filesystems, for example @file{home} 6552normally contains a tree of filesystems representing other machines in 6553the network. 6554 6555A map can either be given as a name representing an already defined 6556volume name, or it can be a tree. A tree is represented by placing 6557braces after the name. For example, to define a tree @file{/vol}, the 6558following map would be defined: 6559 6560@example 6561automount /vol @{ @} 6562@end example 6563 6564Within a tree, the only items that can appear are more maps. 6565For example: 6566 6567@example 6568automount /vol @{ 6569 andrew @{ @} 6570 X11 @{ @} 6571@} 6572@end example 6573 6574In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} 6575and @file{/vol/X11} and a map entry will be generated for each. If the 6576volumes are defined more than once, then @i{FSinfo} will generate 6577a series of alternate entries for them in the maps.@refill 6578 6579Instead of a tree, either a link (@var{name} @code{->} 6580@var{destination}) or a reference can be specified (@var{name} @code{=} 6581@var{destination}). A link creates a symbolic link to the string 6582specified, without further processing the entry. A reference will 6583examine the destination filesystem and optimize the reference. For 6584example, to create an entry for @code{njw} in the @file{/homes} map, 6585either of the two forms can be used:@refill 6586 6587@example 6588automount /homes @{ 6589 njw -> /home/dylan/njw 6590@} 6591@end example 6592 6593or 6594 6595@example 6596automount /homes @{ 6597 njw = /home/dylan/njw 6598@} 6599@end example 6600 6601In the first example, when @file{/homes/njw} is referenced from @i{Amd}, 6602a link will be created leading to @file{/home/dylan/njw} and the 6603automounter will be referenced a second time to resolve this filename. 6604The map entry would be: 6605 6606@example 6607njw type:=link;fs:=/home/dylan/njw 6608@end example 6609 6610In the second example, the destination directory is analyzed and found 6611to be in the filesystem @file{/home/dylan} which has previously been 6612defined in the maps. Hence the map entry will look like: 6613 6614@example 6615njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw 6616@end example 6617 6618Creating only one symbolic link, and one access to @i{Amd}. 6619 6620@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo 6621@comment node-name, next, previous, up 6622@section @i{FSinfo} Command Line Options 6623@cindex FSinfo command line options 6624@cindex Command line options, FSinfo 6625 6626@i{FSinfo} is started from the command line by using the command: 6627 6628@example 6629fsinfo [@i{options}] @i{files} ... 6630@end example 6631 6632The input to @i{FSinfo} is a single set of definitions of machines and 6633automount maps. If multiple files are given on the command-line, then 6634the files are concatenated together to form the input source. The files 6635are passed individually through the C pre-processor before being parsed. 6636 6637Several options define a prefix for the name of an output file. If the 6638prefix is not specified no output of that type is produced. The suffix 6639used will correspond either to the hostname to which a file belongs, or 6640to the type of output if only one file is produced. Dumpsets and the 6641@file{bootparams} file are in the latter class. To put the output into 6642a subdirectory simply put a @file{/} at the end of the prefix, making 6643sure that the directory has already been made before running 6644@i{Fsinfo}. 6645 6646@menu 6647* -a FSinfo Option:: Amd automount directory: 6648* -b FSinfo Option:: Prefix for bootparams files. 6649* -d FSinfo Option:: Prefix for dumpset data files. 6650* -e FSinfo Option:: Prefix for exports files. 6651* -f FSinfo Option:: Prefix for fstab files. 6652* -h FSinfo Option:: Local hostname. 6653* -m FSinfo Option:: Prefix for automount maps. 6654* -q FSinfo Option:: Ultra quiet mode. 6655* -v FSinfo Option:: Verbose mode. 6656* -I FSinfo Option:: Define new #include directory. 6657* -D-FSinfo Option:: Define macro. 6658* -U FSinfo Option:: Undefine macro. 6659@end menu 6660 6661@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options 6662@comment node-name, next, previous, up 6663@subsection @code{-a} @var{autodir} 6664 6665Specifies the directory name in which to place the automounter's 6666mountpoints. This defaults to @file{/a}. Some sites have the autodir set 6667to be @file{/amd}, and this would be achieved by: 6668 6669@example 6670fsinfo -a /amd ... 6671@end example 6672 6673@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options 6674@comment node-name, next, previous, up 6675@subsection @code{-b} @var{bootparams} 6676@cindex bootparams, FSinfo prefix 6677 6678This specifies the prefix for the @file{bootparams} filename. If it is 6679not given, then the file will not be generated. The @file{bootparams} 6680file will be constructed for the destination machine and will be placed 6681into a file named @file{bootparams} and prefixed by this string. The 6682file generated contains a list of entries describing each diskless 6683client that can boot from the destination machine. 6684 6685As an example, to create a @file{bootparams} file in the directory 6686@file{generic}, the following would be used: 6687 6688@example 6689fsinfo -b generic/ ... 6690@end example 6691 6692@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options 6693@comment node-name, next, previous, up 6694@subsection @code{-d} @var{dumpsets} 6695@cindex dumpset, FSinfo prefix 6696 6697This specifies the prefix for the @file{dumpsets} file. If it is not 6698specified, then the file will not be generated. The file will be for 6699the destination machine and will be placed into a filename 6700@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is 6701for use by Imperial College's local backup system. 6702 6703For example, to create a @file{dumpsets} file in the directory @file{generic}, 6704then you would use the following: 6705 6706@example 6707fsinfo -d generic/ ... 6708@end example 6709 6710@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options 6711@comment node-name, next, previous, up 6712@subsection @code{-e} @var{exportfs} 6713@cindex exports, FSinfo prefix 6714 6715Defines the prefix for the @file{exports} files. If it is not given, 6716then the file will not be generated. For each machine defined in the 6717configuration files as having disks, an @file{exports} file is 6718constructed and given a filename determined by the name of the machine, 6719prefixed with this string. If a machine is defined as diskless, then no 6720@file{exports} file will be created for it. The files contain entries 6721for directories on the machine that may be exported to clients. 6722 6723Example: To create the @file{exports} files for each diskfull machine 6724and place them into the directory @file{exports}: 6725 6726@example 6727fsinfo -e exports/ ... 6728@end example 6729 6730@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options 6731@comment node-name, next, previous, up 6732@subsection @code{-f} @var{fstab} 6733@cindex fstab, FSinfo prefix 6734 6735This defines the prefix for the @file{fstab} files. The files will only 6736be created if this prefix is defined. For each machine defined in the 6737configuration files, a @file{fstab} file is created with the filename 6738determined by prefixing this string with the name of the machine. These 6739files contain entries for filesystems and partitions to mount at boot 6740time. 6741 6742Example, to create the files in the directory @file{fstabs}: 6743 6744@example 6745fsinfo -f fstabs/ ... 6746@end example 6747 6748@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options 6749@comment node-name, next, previous, up 6750@subsection @code{-h} @var{hostname} 6751@cindex hostname, FSinfo command line option 6752 6753Defines the hostname of the destination machine to process for. If this 6754is not specified, it defaults to the local machine name, as returned by 6755@b{gethostname}(2). 6756 6757Example: 6758 6759@example 6760fsinfo -h dylan.doc.ic.ac.uk ... 6761@end example 6762 6763@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options 6764@comment node-name, next, previous, up 6765@subsection @code{-m} @var{mount-maps} 6766@cindex maps, FSinfo command line option 6767 6768Defines the prefix for the automounter files. The maps will only be 6769produced if this prefix is defined. The mount maps suitable for the 6770network defined by the configuration files will be placed into files 6771with names calculated by prefixing this string to the name of each map. 6772 6773For example, to create the automounter maps and place them in the 6774directory @file{automaps}: 6775 6776@example 6777fsinfo -m automaps/ ... 6778@end example 6779 6780@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options 6781@comment node-name, next, previous, up 6782@subsection @code{-q} 6783@cindex quiet, FSinfo command line option 6784 6785Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and 6786only outputs any error messages which are generated. 6787 6788@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options 6789@comment node-name, next, previous, up 6790@subsection @code{-v} 6791@cindex verbose, FSinfo command line option 6792 6793Selects verbose mode. When this is activated, the program will display 6794more messages, and display all the information discovered when 6795performing the semantic analysis phase. Each verbose message is output 6796to @file{stdout} on a line starting with a @samp{#} character. 6797 6798@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options 6799@comment node-name, next, previous, up 6800@subsection @code{-D} @var{name}@i{[=defn]} 6801 6802Defines a symbol @dfn{name} for the preprocessor when reading the 6803configuration files. Equivalent to @code{#define} directive. 6804 6805@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options 6806@comment node-name, next, previous, up 6807@subsection @code{-I} @var{directory} 6808 6809This option is passed into the preprocessor for the configuration files. 6810It specifies directories in which to find include files 6811 6812@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options 6813@comment node-name, next, previous, up 6814@subsection @code{-U} @var{name} 6815 6816Removes any initial definition of the symbol @dfn{name}. Inverse of the 6817@code{-D} option. 6818 6819@node FSinfo errors, , FSinfo Command Line Options, FSinfo 6820@comment node-name, next, previous, up 6821@section Errors produced by @i{FSinfo} 6822@cindex FSinfo error messages 6823 6824The following table documents the errors and warnings which @i{FSinfo} may produce. 6825 6826@table @t 6827 6828@item " expected 6829Occurs if an unescaped newline is found in a quoted string. 6830 6831@item ambiguous mount: @var{volume} is a replicated filesystem 6832If several filesystems are declared as having the same volume name, they 6833will be considered replicated filesystems. To mount a replicated 6834filesystem statically, a specific host will need to be named, to say 6835which particular copy to try and mount, else this error will 6836result. 6837 6838@item can't open @var{filename} for writing 6839Occurs if any errors are encountered when opening an output file. 6840 6841@item cannot determine localname since volname @var{volume} is not uniquely defined 6842If a volume is replicated and an attempt is made to mount the filesystem 6843statically without specifying a local mountpoint, @i{FSinfo} cannot 6844calculate a mountpoint, as the desired pathname would be 6845ambiguous. 6846 6847@item @var{device} has duplicate exportfs data 6848Produced if the @samp{exportfs} option is used multiple times within the 6849same branch of a filesystem definition. For example, if you attempt to 6850set the @samp{exportfs} data at different levels of the mountpoint 6851directory tree. 6852 6853@item dump frequency for @var{host}:@var{device} is non-zero 6854Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6855or @samp{export} and the @samp{dump} option is set to a value greater 6856than zero. Swap devices should not be dumped. 6857 6858@item duplicate host @var{hostname}! 6859If a host has more than one definition. 6860 6861@item end of file within comment 6862A comment was unterminated before the end of one of the configuration 6863files. 6864 6865@item @var{filename}: cannot open for reading 6866If a file specified on the command line as containing configuration data 6867could not be opened. 6868 6869@item @var{filesystem} has a volname but no exportfs data 6870Occurs when a volume name is declared for a file system, but the string 6871specifying what machines the filesystem can be exported to is 6872missing. 6873 6874@item fs field "@var{field-name}" already set 6875Occurs when multiple definitions are given for one of the attributes of a 6876host's filesystem. 6877 6878@item host field "@var{field-name}" already set 6879If duplicate definitions are given for any of the fields with a host 6880definition. 6881 6882@item @var{host}:@var{device} has more than one mount point 6883Occurs if the mount option for a host's filesystem specifies multiple 6884trees at which to place the mountpoint. 6885 6886@item @var{host}:@var{device} has no mount point 6887Occurs if the @samp{mount} option is not specified for a host's 6888filesystem. 6889 6890@item @var{host}:@var{device} needs field "@var{field-name}" 6891Occurs when a filesystem is missing a required field. @var{field-name} could 6892be one of @samp{fstype}, @samp{opts}, @samp{passno} or 6893@samp{mount}. 6894 6895@item @var{host}:mount field specified for swap partition 6896Occurs if a mountpoint is given for a filesystem whose type is declared 6897to be @samp{swap}. 6898 6899@item malformed IP dotted quad: @var{address} 6900If the Internet address of an interface is incorrectly specified. An 6901Internet address definition is handled to @b{inet_addr}(3N) to see if it 6902can cope. If not, then this message will be displayed. 6903 6904@item malformed netmask: @var{netmask} 6905If the netmask cannot be decoded as though it were a hexadecimal number, 6906then this message will be displayed. It will typically be caused by 6907incorrect characters in the @var{netmask} value. 6908 6909@item mount field "@var{field-name}" already set 6910Occurs when a static mount has multiple definitions of the same field. 6911 6912@item mount tree field "@var{field-name}" already set 6913Occurs when the @var{field-name} is defined more than once during the 6914definition of a filesystems mountpoint. 6915 6916@item netif field @var{field-name} already set 6917Occurs if you attempt to define an attribute of an interface more than 6918once. 6919 6920@item network booting requires both root and swap areas 6921Occurs if a machine has mount declarations for either the root partition 6922or the swap area, but not both. You cannot define a machine to only 6923partially boot via the network. 6924 6925@item no disk mounts on @var{hostname} 6926If there are no static mounts, nor local disk mounts specified for a 6927machine, this message will be displayed. 6928 6929@item no volname given for @var{host}:@var{device} 6930Occurs when a filesystem is defined to be mounted on @file{default}, but 6931no volume name is given for the file system, then the mountpoint cannot 6932be determined. 6933 6934@item not allowed '/' in a directory name 6935Occurs when a pathname with multiple directory elements is specified as 6936the name for an automounter tree. A tree should only have one name at 6937each level. 6938 6939@item pass number for @var{host}:@var{device} is non-zero 6940Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6941or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices 6942should not be fsck'd. @xref{FSinfo fstype Option}. 6943 6944@item sub-directory @var{directory} of @var{directory-tree} starts with '/' 6945Within the filesystem specification for a host, if an element 6946@var{directory} of the mountpoint begins with a @samp{/} and it is not 6947the start of the tree. 6948 6949@item sub-directory of @var{directory-tree} is named "default" 6950@samp{default} is a keyword used to specify if a mountpoint should be 6951automatically calculated by @i{FSinfo}. If you attempt to specify a 6952directory name as this, it will use the filename of @file{default} but 6953will produce this warning. 6954 6955@item unknown \ sequence 6956Occurs if an unknown escape sequence is found inside a string. Within a 6957string, you can give the standard C escape sequences for strings, such 6958as newlines and tab characters. 6959 6960@item unknown directory attribute 6961If an unknown keyword is found while reading the definition of a host's 6962filesystem mount option. 6963 6964@item unknown filesystem attribute 6965Occurs if an unrecognized keyword is used when defining a host's 6966filesystems. 6967 6968@item unknown host attribute 6969Occurs if an unrecognized keyword is used when defining a host. 6970 6971@item unknown mount attribute 6972Occurs if an unrecognized keyword is found while parsing the list of 6973static mounts. 6974 6975@item unknown volname @var{volume} automounted @i{[} on @i{name} @i{]} 6976Occurs if @var{volume} is used in a definition of an automount map but the volume 6977name has not been declared during the host filesystem definitions. 6978 6979@item volname @var{volume} is unknown 6980Occurs if an attempt is made to mount or reference a volume name which 6981has not been declared during the host filesystem definitions. 6982 6983@item volname @var{volume} not exported from @var{machine} 6984Occurs if you attempt to mount the volume @var{volume} from a machine 6985which has not declared itself to have such a filesystem 6986available. 6987 6988@end table 6989 6990@c ################################################################ 6991@node Hlfsd, Assorted Tools, FSinfo, Top 6992@comment node-name, next, previous, up 6993@chapter Hlfsd 6994@pindex Hlfsd 6995@cindex Home-Link Filesystem 6996 6997@i{Hlfsd} is a daemon which implements a filesystem containing a 6998symbolic link to subdirectory within a user's home directory, depending 6999on the user which accessed that link. It was primarily designed to 7000redirect incoming mail to users' home directories, so that it can be read 7001from anywhere. It was designed and implemented by 7002@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} and 7003@email{dupuy AT cs.columbia.edu,Alexander Dupuy}, at the 7004@uref{http://www.cs.columbia.edu/,Computer Science Department} of 7005@uref{http://www.columbia.edu/,Columbia University}. A 7006@uref{http://www.fsl.cs.sunysb.edu/docs/hlfsd/hlfsd.html,paper} 7007on @i{Hlfsd} was presented at the Usenix LISA VII conference in 1993. 7008 7009@i{Hlfsd} operates by mounting itself as an NFS server for the directory 7010containing @i{linkname}, which defaults to @file{/hlfs/home}. Lookups 7011within that directory are handled by @i{Hlfsd}, which uses the 7012password map to determine how to resolve the lookup. The directory will 7013be created if it doesn't already exist. The symbolic link will be to 7014the accessing user's home directory, with @i{subdir} appended to it. If 7015not specified, @i{subdir} defaults to @file{.hlfsdir}. This directory 7016will also be created if it does not already exist. 7017 7018A @samp{SIGTERM} sent to @i{Hlfsd} will cause it to shutdown. A 7019@samp{SIGHUP} will flush the internal caches, and reload the password 7020map. It will also close and reopen the log file, to enable the original 7021log file to be removed or rotated. A @samp{SIGUSR1} will cause it to 7022dump its internal table of user IDs and home directories to the file 7023@file{/tmp/hlfsddump}. 7024 7025@menu 7026* Introduction to Hlfsd:: 7027* Background to Mail Delivery:: 7028* Using Hlfsd:: 7029@end menu 7030 7031@c ================================================================ 7032@node Introduction to Hlfsd, Background to Mail Delivery, Hlfsd, Hlfsd 7033@comment node-name, next, previous, up 7034@section Introduction to Hlfsd 7035@cindex Introduction to Hlfsd 7036@cindex Hlfsd; introduction 7037 7038Electronic mail has become one of the major applications for many 7039computer networks, and use of this service is expected to increase over 7040time, as networks proliferate and become faster. Providing a convenient 7041environment for users to read, compose, and send electronic mail has 7042become a requirement for systems administrators (SAs). 7043 7044Widely used methods for handling mail usually require users to be logged 7045into a designated ``home'' machine, where their mailbox files reside. 7046Only on that one machine can they read newly arrived mail. Since users 7047have to be logged into that system to read their mail, they often find 7048it convenient to run all of their other processes on that system as 7049well, including memory and CPU-intensive jobs. For example, in our 7050department, we have allocated and configured several multi-processor 7051servers to handle such demanding CPU/memory applications, but these were 7052underutilized, in large part due to the inconvenience of not being able 7053to read mail on those machines. (No home directories were located on 7054these designated CPU-servers, since we did not want NFS service for 7055users' home directories to have to compete with CPU-intensive jobs. At the 7056same time, we discouraged users from running demanding applications on 7057their home machines.) 7058 7059Many different solutions have been proposed to allow users to read their 7060mail on any host. However, all of these solutions fail in one or more 7061of several ways: 7062 7063@itemize @bullet 7064 7065@item 7066they introduce new single points of failure 7067 7068@item 7069they require using different mail transfer agents (MTAs) or user agents 7070(UAs) 7071 7072@item 7073they do not solve the problem for all cases, i.e. the solution is only 7074partially successful for a particular environment. 7075 7076@end itemize 7077 7078We have designed a simple filesystem, called the @dfn{Home-Link File 7079System}, to provide the ability to deliver mail to users' home 7080directories, without modification to mail-related applications. We have 7081endeavored to make it as stable as possible. Of great importance to us 7082was to make sure the HLFS daemon, @file{hlfsd} , would not hang under 7083any circumstances, and would take the next-best action when faced with 7084problems. Compared to alternative methods, @i{Hlfsd} is a stable, more 7085general solution, and easier to install/use. In fact, in some ways, we 7086have even managed to improve the reliability and security of mail 7087service. 7088 7089Our server implements a small filesystem containing a symbolic link 7090to a subdirectory of the invoking user's home directory, and named symbolic 7091links to users' mailbox files. 7092 7093The @i{Hlfsd} server finds out the @var{uid} of the process that is 7094accessing its mount point, and resolves the pathname component @samp{home} as a 7095symbolic link to a subdirectory within the home directory given by the 7096@var{uid}'s entry in the password file. If the @var{gid} of the process 7097that attempts to access a mailbox file is a special one (called 7098HLFS_GID), then the server maps the name of the @emph{next} pathname 7099component directly to the user's mailbox. This is necessary so that 7100access to a mailbox file by users other than the owner can succeed. The 7101server has safety features in case of failures such as hung filesystems 7102or home directory filesystems that are inaccessible or full. 7103 7104On most of our machines, mail gets delivered to the directory 7105@file{/var/spool/mail}. Many programs, including UAs, depend on that 7106path. @i{Hlfsd} creates a directory @file{/mail}, and mounts itself on 7107top of that directory. @i{Hlfsd} implements the path name component 7108called @samp{home}, pointing to a subdirectory of the user's home directory. 7109We have made @file{/var/spool/mail} a symbolic link to 7110@file{/mail/home}, so that accessing @file{/var/spool/mail} actually 7111causes access to a subdirectory within a user's home directory. 7112 7113The following table shows an example of how resolving the pathname 7114@file{/var/mail/@i{NAME}} to @file{/users/ezk/.mailspool/@i{NAME}} proceeds. 7115 7116@multitable {Resolving Component} {Pathname left to resolve} {Value if symbolic link} 7117 7118@item @b{Resolving Component} 7119@tab @b{Pathname left to resolve} 7120@tab @b{Value if symbolic link} 7121 7122@item @t{/} 7123@tab @t{var/mail/}@i{NAME} 7124 7125@item @t{var/} 7126@tab @t{mail/}@i{NAME} 7127 7128@item @t{mail}@@ 7129@tab @t{/mail/home/}@i{NAME} 7130@tab @t{mail}@@ -> @t{/mail/home} 7131 7132@item @t{/} 7133@tab @t{mail/home/}@i{NAME} 7134 7135@item @t{mail/} 7136@tab @t{home/}@i{NAME} 7137 7138@item @t{home}@@ 7139@tab @i{NAME} 7140@tab @t{home}@@ -> @t{/users/ezk/.mailspool} 7141 7142@item @t{/} 7143@tab @t{users/ezk/.mailspool/}@i{NAME} 7144 7145@item @t{users/} 7146@tab @t{ezk/.mailspool/}@i{NAME} 7147 7148@item @t{ezk/} 7149@tab @t{.mailspool/}@i{NAME} 7150 7151@item @t{.mailspool/} 7152@tab @i{NAME} 7153 7154@item @i{NAME} 7155 7156@end multitable 7157 7158@c ================================================================ 7159@node Background to Mail Delivery, Using Hlfsd, Introduction to Hlfsd, Hlfsd 7160@comment node-name, next, previous, up 7161@section Background to Mail Delivery 7162@cindex Background to Mail Delivery 7163@cindex Hlfsd; background 7164 7165This section provides an in-depth discussion of why available methods 7166for delivering mail to home directories are not as good as the one used 7167by @i{Hlfsd}. 7168 7169@menu 7170* Single-Host Mail Spool Directory:: 7171* Centralized Mail Spool Directory:: 7172* Distributed Mail Spool Service:: 7173* Why Deliver Into the Home Directory?:: 7174@end menu 7175 7176@c ---------------------------------------------------------------- 7177@node Single-Host Mail Spool Directory, Centralized Mail Spool Directory, Background to Mail Delivery, Background to Mail Delivery 7178@comment node-name, next, previous, up 7179@subsection Single-Host Mail Spool Directory 7180@cindex Single-Host Mail Spool Directory 7181 7182The most common method for mail delivery is for mail to be appended to a 7183mailbox file in a standard spool directory on the designated ``mail 7184home'' machine of the user. The greatest advantage of this method is 7185that it is the default method most vendors provide with their systems, 7186thus very little (if any) configuration is required on the SA's part. 7187All they need to set up are mail aliases directing mail to the host on 7188which the user's mailbox file is assigned. (Otherwise, mail is 7189delivered locally, and users find mailboxes on many machines.) 7190 7191As users become more sophisticated, and aided by windowing systems, they 7192find themselves logging in on multiple hosts at once, performing several 7193tasks concurrently. They ask to be able to read their mail on any host 7194on the network, not just the one designated as their ``mail home''. 7195 7196@c ---------------------------------------------------------------- 7197@node Centralized Mail Spool Directory, Distributed Mail Spool Service, Single-Host Mail Spool Directory, Background to Mail Delivery 7198@comment node-name, next, previous, up 7199@subsection Centralized Mail Spool Directory 7200@cindex Centralized Mail Spool Directory 7201 7202A popular method for providing mail readability from any host is to have 7203all mail delivered to a mail spool directory on a designated 7204``mail-server'' which is exported via NFS to all of the hosts on the 7205network. Configuring such a system is relatively easy. On most 7206systems, the bulk of the work is a one-time addition to one or two 7207configuration files in @file{/etc}. The file-server's spool directory 7208is then hard-mounted across every machine on the local network. In 7209small environments with only a handful of hosts this can be an 7210acceptable solution. In our department, with a couple of hundred active 7211hosts and thousands of mail messages processed daily, this was deemed 7212completely unacceptable, as it introduced several types of problems: 7213 7214@table @b 7215 7216@item Scalability and Performance 7217 7218As more and more machines get added to the network, more mail traffic 7219has to go over NFS to and from the mail-server. Users like to run 7220mail-watchers, and read their mail often. The stress on the shared 7221infrastructure increases with every user and host added; loads on the 7222mail server would most certainly be high since all mail delivery goes 7223through that one machine.@footnote{ Delivery via NFS-mounted filesystems 7224may require usage of @samp{rpc.lockd} and @samp{rpc.statd} to provide 7225distributed file-locking, both of which are widely regarded as unstable 7226and unreliable. Furthermore, this will degrade performance, as local 7227processes as well as remote @samp{nfsd} processes are kept busy.} This 7228leads to lower reliability and performance. To reduce the number of 7229concurrent connections between clients and the server host, some SAs 7230have resorted to automounting the mail-spool directory. But this 7231solution only makes things worse: since users often run mail watchers, 7232and many popular applications such as @samp{trn}, @samp{emacs}, 7233@samp{csh} or @samp{ksh} check periodically for new mail, the 7234automounted directory would be effectively permanently mounted. If it 7235gets unmounted automatically by the automounter program, it is most 7236likely to get mounted shortly afterwards, consuming more I/O resources 7237by the constant cycle of mount and umount calls. 7238 7239@item Reliability 7240 7241The mail-server host and its network connectivity must be very reliable. 7242Worse, since the spool directory has to be hard-mounted,@footnote{No SA 7243in their right minds would soft-mount read/write partitions --- the 7244chances for data loss are too great.} many processes which access the 7245spool directory (various shells, @samp{login}, @samp{emacs}, etc.) 7246would be hung as long as connectivity to the mail-server is severed. To 7247improve reliability, SAs may choose to backup the mail-server's spool 7248partition several times a day. This may make things worse since reading 7249or delivering mail while backups are in progress may cause backups to be 7250inconsistent; more backups consume more backup-media resources, and 7251increase the load on the mail-server host. 7252 7253@end table 7254 7255@c ---------------------------------------------------------------- 7256@node Distributed Mail Spool Service, Why Deliver Into the Home Directory?, Centralized Mail Spool Directory, Background to Mail Delivery 7257@comment node-name, next, previous, up 7258@subsection Distributed Mail Spool Service 7259@cindex Distributed Mail Spool Service 7260 7261Despite the existence of a few systems that support delivery to users' 7262home directories, mail delivery to home directories hasn't caught on. 7263We believe the main reason is that there are too many programs that 7264``know'' where mailbox files reside. Besides the obvious (the delivery 7265program @file{/bin/mail} and mail readers like @file{/usr/ucb/Mail}, 7266@samp{mush}, @samp{mm}, etc.), other programs that know mailbox location 7267are login, from, almost every shell, @samp{xbiff}, @samp{xmailbox}, and 7268even some programs not directly related to mail, such as @samp{emacs} 7269and @samp{trn}. Although some of these programs can be configured to 7270look in different directories with the use of environment variables and 7271other resources, many of them cannot. The overall porting work is 7272significant. 7273 7274Other methods that have yet to catch on require the use of a special 7275mail-reading server, such as IMAP or POP. The main disadvantage of 7276these systems is that UAs need to be modified to use these services --- 7277a long and involved task. That is why they are not popular at this 7278time. 7279 7280Several other ideas have been proposed and even used in various 7281environments. None of them is robust. They are mostly very 7282specialized, inflexible, and do not extend to the general case. Some of 7283the ideas are plain bad, potentially leading to lost or corrupt mail: 7284 7285@table @b 7286 7287@item automounters 7288 7289Using an automounter such as @i{Amd} to provide a set of symbolic links 7290from the normal spool directory to user home directories is not 7291sufficient. UAs rename, unlink, and recreate the mailbox as a regular 7292file, therefore it must be a real file, not a symbolic link. 7293Furthermore, it must reside in a real directory which is writable by the 7294UAs and MTAs. This method may also require populating 7295@file{/var/spool/mail} with symbolic links and making sure they are 7296updated. Making @i{Amd} manage that directory directly fails, since 7297many various lock files need to be managed as well. Also, @i{Amd} does 7298not provide all of the NFS operations which are required to write mail 7299such as write, create, remove, and unlink. 7300 7301@item @code{$MAIL} 7302 7303Setting this variable to an automounted directory pointing to the user's 7304mail spool host only solves the problem for those programs which know 7305and use @code{$MAIL}. Many programs don't, therefore this solution is partial 7306and of limited flexibility. Also, it requires the SAs or the users to 7307set it themselves --- an added level of inconvenience and possible 7308failures. 7309 7310@item @t{/bin/mail} 7311 7312Using a different mail delivery agent could be the solution. One such 7313example is @samp{hdmail}. However, @samp{hdmail} still requires 7314modifying all UAs, the MTA's configuration, installing new daemons, and 7315changing login scripts. This makes the system less upgradable or 7316compatible with others, and adds one more complicated system for SAs to 7317deal with. It is not a complete solution because it still requires each 7318user have their @code{$MAIL} variable setup correctly, and that every program 7319use this variable. 7320 7321@end table 7322 7323@c ---------------------------------------------------------------- 7324@node Why Deliver Into the Home Directory?, , Distributed Mail Spool Service, Background to Mail Delivery 7325@comment node-name, next, previous, up 7326@subsection Why Deliver Into the Home Directory? 7327@cindex Why Deliver Into the Home Directory? 7328@cindex Hlfsd; Why Deliver Into the Home Directory? 7329 7330There are several major reasons why SAs might want to deliver mail 7331directly into the users' home directories: 7332 7333@table @b 7334 7335@item Location 7336 7337Many mail readers need to move mail from the spool directory to the 7338user's home directory. It speeds up this operation if the two are on 7339the same filesystem. If for some reason the user's home directory is 7340inaccessible, it isn't that useful to be able to read mail, since there 7341is no place to move it to. In some cases, trying to move mail to a 7342non-existent or hung filesystem may result in mail loss. 7343 7344@item Distribution 7345 7346Having all mail spool directories spread among the many more filesystems 7347minimizes the chances that complete environments will grind to a halt 7348when a single server is down. It does increase the chance that there 7349will be someone who is not able to read their mail when a machine is 7350down, but that is usually preferred to having no one be able to read 7351their mail because a centralized mail server is down. The problem of 7352losing some mail due to the (presumably) higher chances that a user's 7353machine is down is minimized in HLFS. 7354 7355@item Security 7356 7357Delivering mail to users' home directories has another advantage --- 7358enhanced security and privacy. Since a shared system mail spool 7359directory has to be world-readable and searchable, any user can see 7360whether other users have mail, when they last received new mail, or when 7361they last read their mail. Programs such as @samp{finger} display this 7362information, which some consider an infringement of privacy. While it 7363is possible to disable this feature of @samp{finger} so that remote 7364users cannot see a mailbox file's status, this doesn't prevent local 7365users from getting the information. Furthermore, there are more 7366programs which make use of this information. In shared environments, 7367disabling such programs has to be done on a system-wide basis, but with 7368mail delivered to users' home directories, users less concerned with 7369privacy who do want to let others know when they last received or read 7370mail can easily do so using file protection bits. 7371 7372@c Lastly, on systems that do not export their NFS filesystem with 7373@c @t{anon=0}, superusers are less likely to snoop around others' mail, as 7374@c they become ``nobodies'' across NFS. 7375 7376@end table 7377 7378In summary, delivering mail to home directories provides users the 7379functionality sought, and also avoids most of the problems just 7380discussed. 7381 7382@c ================================================================ 7383@node Using Hlfsd, , Background to Mail Delivery, Hlfsd 7384@comment node-name, next, previous, up 7385@section Using Hlfsd 7386@cindex Using Hlfsd 7387@cindex Hlfsd; using 7388 7389@menu 7390* Controlling Hlfsd:: 7391* Hlfsd Options:: 7392* Hlfsd Files:: 7393@end menu 7394 7395@c ---------------------------------------------------------------- 7396@node Controlling Hlfsd, Hlfsd Options, Using Hlfsd, Using Hlfsd 7397@comment node-name, next, previous, up 7398@subsection Controlling Hlfsd 7399@cindex Controlling Hlfsd 7400@cindex Hlfsd; controlling 7401@pindex ctl-hlfsd 7402 7403Much the same way @i{Amd} is controlled by @file{ctl-amd}, so does 7404@i{Hlfsd} get controlled by the @file{ctl-hlfsd} script: 7405 7406@table @t 7407 7408@item ctl-hlfsd start 7409Start a new @i{Hlfsd}. 7410 7411@item ctl-hlfsd stop 7412Stop a running @i{Hlfsd}. 7413 7414@item ctl-hlfsd restart 7415Stop a running @i{Hlfsd}, wait for 10 seconds, and then start a new 7416one. It is hoped that within 10 seconds, the previously running 7417@i{Hlfsd} terminate properly; otherwise, starting a second one could 7418cause system lockup. 7419 7420@end table 7421 7422For example, on our systems, we start @i{Hlfsd} within @file{ctl-hlfsd} 7423as follows on Solaris 2 systems: 7424 7425@example 7426hlfsd -a /var/alt_mail -x all -l /var/log/hlfsd /mail/home .mailspool 7427@end example 7428 7429The directory @file{/var/alt_mail} is a directory in the root partition 7430where alternate mail will be delivered into, when it cannot be delivered 7431into the user's home directory. 7432 7433Normal mail gets delivered into @file{/var/mail}, but on our systems, 7434that is a symbolic link to @file{/mail/home}. @file{/mail} is managed 7435by @i{Hlfsd}, which creates a dynamic symlink named @samp{home}, 7436pointing to the subdirectory @file{.mailspool} @emph{within} the 7437accessing user's home directory. This results in mail which normally 7438should go to @file{/var/mail/@code{$USER}}, to go to 7439@file{@code{$HOME}/.mailspool/@code{$USER}}. 7440 7441@i{Hlfsd} does not create the @file{/var/mail} symlink. This needs to 7442be created (manually) once on each host, by the system administrators, 7443as follows: 7444 7445@example 7446mv /var/mail /var/alt_mail 7447ln -s /mail/home /var/mail 7448@end example 7449 7450@i{Hlfsd} also responds to the following signals: 7451 7452A @samp{SIGHUP} signal sent to @i{Hlfsd} will force it to reload the 7453password map immediately. 7454 7455A @samp{SIGUSR1} signal sent to @i{Hlfsd} will cause it to dump its 7456internal password map to the file @file{/usr/tmp/hlfsd.dump.XXXXXX}, 7457where @samp{XXXXXX} will be replaced by a random string generated by 7458@b{mktemp}(3) or (the more secure) @b{mkstemp}(3). 7459 7460@c ---------------------------------------------------------------- 7461@node Hlfsd Options, Hlfsd Files, Controlling Hlfsd, Using Hlfsd 7462@comment node-name, next, previous, up 7463@subsection Hlfsd Options 7464@cindex Hlfsd Options 7465@cindex Hlfsd; Options 7466 7467@table @t 7468 7469@item -a @var{alt_dir} 7470Alternate directory. The name of the directory to which the symbolic 7471link returned by @i{Hlfsd} will point, if it cannot access the home 7472directory of the user. This defaults to @file{/var/hlfs}. This 7473directory will be created if it doesn't exist. It is expected that 7474either users will read these files, or the system administrators will 7475run a script to resend this ``lost mail'' to its owner. 7476 7477@item -c @var{cache-interval} 7478Caching interval. @i{Hlfsd} will cache the validity of home directories 7479for this interval, in seconds. Entries which have been verified within 7480the last @var{cache-interval} seconds will not be verified again, since 7481the operation could be expensive, and the entries are most likely still 7482valid. After the interval has expired, @i{Hlfsd} will re-verify the 7483validity of the user's home directory, and reset the cache time-counter. 7484The default value for @var{cache-interval} is 300 seconds (5 minutes). 7485 7486@item -f 7487Force fast startup. This option tells @i{Hlfsd} to skip startup-time 7488consistency checks such as existence of mount directory, alternate spool 7489directory, symlink to be hidden under the mount directory, their 7490permissions and validity. 7491 7492@item -g @var{group} 7493Set the special group HLFS_GID to @var{group}. Programs such as 7494@file{/usr/ucb/from} or @file{/usr/sbin/in.comsat}, which access the 7495mailboxes of other users, must be setgid @samp{HLFS_GID} to work properly. The 7496default group is @samp{hlfs}. If no group is provided, and there is no 7497group @samp{hlfs}, this feature is disabled. 7498 7499@item -h 7500Help. Print a brief help message, and exit. 7501 7502@item -i @var{reload-interval} 7503Map-reloading interval. Each @var{reload-interval} seconds, @i{Hlfsd} 7504will reload the password map. @i{Hlfsd} needs the password map for the 7505UIDs and home directory pathnames. @i{Hlfsd} schedules a @samp{SIGALRM} to 7506reload the password maps. A @samp{SIGHUP} sent to @i{Hlfsd} will force it to 7507reload the maps immediately. The default value for 7508@var{reload-interval} is 900 seconds (15 minutes.) 7509 7510@item -l @var{logfile} 7511Specify a log file to which @i{Hlfsd} will record events. If 7512@var{logfile} is the string @samp{syslog} then the log messages will be 7513sent to the system log daemon by @b{syslog}(3), using the @samp{LOG_DAEMON} 7514facility. This is also the default. 7515 7516@item -n 7517No verify. @i{Hlfsd} will not verify the validity of the symbolic link 7518it will be returning, or that the user's home directory contains 7519sufficient disk-space for spooling. This can speed up @i{Hlfsd} at the 7520cost of possibly returning symbolic links to home directories which are 7521not currently accessible or are full. By default, @i{Hlfsd} validates 7522the symbolic-link in the background. The @code{-n} option overrides the 7523meaning of the @code{-c} option, since no caching is necessary. 7524 7525@item -o @var{mount-options} 7526Mount options which @i{Hlfsd} will use to mount itself on top of 7527@var{dirname}. By default, @var{mount-options} is set to @samp{ro}. If 7528the system supports symbolic-link caching, default options are set 7529to @samp{ro,nocache}. 7530 7531@item -p 7532Print PID. Outputs the process-id of @i{Hlfsd} to standard output where 7533it can be saved into a file. 7534 7535@item -v 7536Version. Displays version information to standard error. 7537 7538@item -x @var{log-options} 7539Specify run-time logging options. The options are a comma separated 7540list chosen from: @samp{fatal}, @samp{error}, @samp{user}, @samp{warn}, @samp{info}, @samp{map}, @samp{stats}, @samp{all}. 7541 7542@item -C 7543Force @i{Hlfsd} to run on systems that cannot turn off the NFS 7544attribute-cache. Use of this option on those systems is discouraged, as 7545it may result in loss or misdelivery of mail. The option is ignored on 7546systems that can turn off the attribute-cache. 7547 7548@item -D @var{log-options} 7549Select from a variety of debugging options. Prefixing an option with 7550the string @samp{no} reverses the effect of that option. Options are 7551cumulative. The most useful option is @samp{all}. Since this option is 7552only used for debugging other options are not documented here. A fuller 7553description is available in the program source. 7554 7555@item -P @var{password-file} 7556Read the user-name, user-id, and home directory information from the 7557file @var{password-file}. Normally, @i{Hlfsd} will use @b{getpwent}(3) 7558to read the password database. This option allows you to override the 7559default database, and is useful if you want to map users' mail files to 7560a directory other than their home directory. Only the username, uid, 7561and home-directory fields of the file @var{password-file} are read and 7562checked. All other fields are ignored. The file @var{password-file} 7563must otherwise be compliant with Unix Version 7 colon-delimited format 7564@b{passwd}(4). 7565 7566@end table 7567 7568@c ---------------------------------------------------------------- 7569@node Hlfsd Files, , Hlfsd Options, Using Hlfsd 7570@comment node-name, next, previous, up 7571@subsection Hlfsd Files 7572@cindex Hlfsd Files 7573@cindex Hlfsd; Files 7574 7575The following files are used by @i{Hlfsd}: 7576 7577@table @file 7578 7579@item /hlfs 7580directory under which @i{Hlfsd} mounts itself and manages the symbolic 7581link @file{home}. 7582 7583@item .hlfsdir 7584default sub-directory in the user's home directory, to which the 7585@file{home} symbolic link returned by @i{Hlfsd} points. 7586 7587@item /var/hlfs 7588directory to which @file{home} symbolic link returned by @i{Hlfsd} 7589points if it is unable to verify the that user's home directory is 7590accessible. 7591 7592@item /usr/tmp/hlfsd.dump.XXXXXX 7593file to which @i{Hlfsd} will dump its internal password map when it 7594receives the @samp{SIGUSR1} signal. @samp{XXXXXX} will be replaced by 7595a random string generated by @b{mktemp}(3) or (the more secure) 7596@b{mkstemp}(3). 7597 7598@end table 7599 7600For discussion on other files used by @i{Hlfsd}, see @xref{lostaltmail}, and 7601@ref{lostaltmail.conf-sample}. 7602 7603@c ################################################################ 7604@node Assorted Tools, Examples, Hlfsd, Top 7605@comment node-name, next, previous, up 7606@chapter Assorted Tools 7607@cindex Assorted Tools 7608 7609The following are additional utilities and scripts included with 7610am-utils, and get installed. 7611 7612@menu 7613* am-eject:: 7614* amd.conf-sample:: 7615* amd2ldif:: 7616* amd2sun:: 7617* automount2amd:: 7618* ctl-amd:: 7619* ctl-hlfsd:: 7620* expn:: 7621* fix-amd-map:: 7622* fixmount:: 7623* fixrmtab:: 7624* lostaltmail:: 7625* lostaltmail.conf-sample:: 7626* mk-amd-map:: 7627* pawd:: 7628* redhat-ctl-amd:: 7629* wait4amd:: 7630* wait4amd2die:: 7631* wire-test:: 7632@end menu 7633 7634@c ---------------------------------------------------------------- 7635@node am-eject, amd.conf-sample, Assorted Tools, Assorted Tools 7636@comment node-name, next, previous, up 7637@section am-eject 7638@pindex am-eject 7639 7640A shell script unmounts a floppy or CD-ROM that is automounted, and 7641then attempts to eject the removable device. 7642 7643@c ---------------------------------------------------------------- 7644@node amd.conf-sample, amd2ldif, am-eject, Assorted Tools 7645@comment node-name, next, previous, up 7646@section amd.conf-sample 7647@pindex amd.conf-sample 7648 7649A sample @i{Amd} configuration file. @xref{Amd Configuration File}. 7650 7651@c ---------------------------------------------------------------- 7652@node amd2ldif, amd2sun, amd.conf-sample, Assorted Tools 7653@comment node-name, next, previous, up 7654@section amd2ldif 7655@pindex amd2ldif 7656 7657A script to convert @i{Amd} maps to LDAP input files. Use it as follows: 7658 7659@example 7660amd2ldif @i{mapname} @i{base} < @i{amd.mapfile} > @i{mapfile.ldif} 7661@end example 7662 7663@c ---------------------------------------------------------------- 7664@node amd2sun, automount2amd, amd2ldif, Assorted Tools 7665@comment node-name, next, previous, up 7666@section amd2sun 7667@pindex amd2sun 7668 7669A script to convert @i{Amd} maps to Sun Automounter maps. Use it as 7670follows 7671 7672@example 7673amd2sun < @i{amd.mapfile} > @i{auto_mapfile} 7674@end example 7675 7676@c ---------------------------------------------------------------- 7677@node automount2amd, ctl-amd, amd2sun, Assorted Tools 7678@comment node-name, next, previous, up 7679@section automount2amd 7680@pindex automount2amd 7681 7682A script to convert old Sun Automounter maps to @i{Amd} maps. 7683 7684Say you have the Sun automount file @i{auto.foo}, with these two lines: 7685@example 7686home earth:/home 7687moon -ro,intr server:/proj/images 7688@end example 7689Running 7690@example 7691automount2amd auto.foo > amd.foo 7692@end example 7693 7694will produce the @i{Amd} map @i{amd.foo} with this content: 7695 7696@example 7697# generated by automount2amd on Sat Aug 14 17:59:32 US/Eastern 1999 7698 7699/defaults \\ 7700 type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7701 7702home \ 7703 host==earth;type:=link;fs:=/home \\ 7704 rhost:=earth;rfs:=/home 7705 7706moon \ 7707 -addopts:=ro,intr \\ 7708 host==server;type:=link;fs:=/proj/images \\ 7709 rhost:=server;rfs:=/proj/images 7710@end example 7711 7712This perl script will use the following @i{/default} entry 7713@example 7714type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7715@end example 7716If you wish to override that, define the @b{$DEFAULTS} environment 7717variable, or modify the script. 7718 7719If you wish to generate Amd maps using the @i{hostd} (@pxref{hostd 7720Selector Variable}) @i{Amd} map syntax, then define the environment 7721variable @b{$DOMAIN} or modify the script. 7722 7723Note that automount2amd does not understand the syntax in newer Sun 7724Automount maps, those used with autofs. 7725 7726@c ---------------------------------------------------------------- 7727@node ctl-amd, ctl-hlfsd, automount2amd, Assorted Tools 7728@comment node-name, next, previous, up 7729@section ctl-amd 7730@pindex ctl-amd 7731 7732A script to start, stop, or restart @i{Amd}. Use it as follows: 7733 7734@table @t 7735@item ctl-amd start 7736Start a new @i{Amd} process. 7737@item ctl-amd stop 7738Stop the running @i{Amd}. 7739@item ctl-amd restart 7740Stop the running @i{Amd} (if any), safely wait for it to terminate, and 7741then start a new process --- only if the previous one died cleanly. 7742@end table 7743 7744@xref{Run-time Administration}, for more details. 7745 7746@c ---------------------------------------------------------------- 7747@node ctl-hlfsd, expn, ctl-amd, Assorted Tools 7748@comment node-name, next, previous, up 7749@section ctl-hlfsd 7750@pindex ctl-hlfsd 7751 7752A script for controlling @i{Hlfsd}, much the same way @file{ctl-amd} 7753controls @i{Amd}. Use it as follows: 7754 7755@table @t 7756@item ctl-hlfsd start 7757Start a new @i{Hlfsd} process. 7758@item ctl-hlfsd stop 7759Stop the running @i{Hlfsd}. 7760@item ctl-hlfsd restart 7761Stop the running @i{Hlfsd} (if any), wait for 10 seconds for it to 7762terminate, and then start a new process --- only if the previous one 7763died cleanly. 7764@end table 7765 7766@xref{Hlfsd}, for more details. 7767 7768@c ---------------------------------------------------------------- 7769@node expn, fix-amd-map, ctl-hlfsd, Assorted Tools 7770@comment node-name, next, previous, up 7771@section expn 7772@pindex expn 7773 7774A script to expand email addresses into their full name. It is 7775generally useful when using with the @file{lostaltmail} script, but is a 7776useful tools otherwise. 7777 7778@example 7779$ expn -v ezk@@example.com 7780ezk@@example.com -> 7781 ezk@@shekel.example.com 7782ezk@@shekel.example.com -> 7783 Erez Zadok <"| /usr/local/mh/lib/slocal -user ezk || exit 75> 7784 Erez Zadok <\ezk> 7785 Erez Zadok </u/zing/ezk/.mailspool/backup> 7786@end example 7787 7788@c ---------------------------------------------------------------- 7789@node fix-amd-map, fixmount, expn, Assorted Tools 7790@comment node-name, next, previous, up 7791@section fix-amd-map 7792@pindex fix-amd-map 7793 7794Am-utils changed some of the syntax and default values of some 7795variables. For example, the default value for @samp{$@{os@}} for 7796Solaris 2.x (aka SunOS 5.x) systems used to be @samp{sos5}, it is now 7797more automatically generated from @file{config.guess} and its value is 7798@samp{sunos5}. 7799 7800This script converts older @i{Amd} maps to new ones. Use it as follows: 7801 7802@example 7803fix-amd-map < @i{old.map} > @i{new.map} 7804@end example 7805 7806@c ---------------------------------------------------------------- 7807@node fixmount, fixrmtab, fix-amd-map, Assorted Tools 7808@comment node-name, next, previous, up 7809@section fixmount 7810@pindex fixmount 7811 7812@samp{fixmount} is a variant of @b{showmount}(8) that can delete bogus 7813mount entries in remote @b{mountd}(8) daemons. This is useful to 7814cleanup otherwise ever-accumulating ``junk''. Use it for example: 7815 7816@example 7817fixmount -r @i{host} 7818@end example 7819 7820See the online manual page for @samp{fixmount} for more details of its 7821usage. 7822 7823@c ---------------------------------------------------------------- 7824@node fixrmtab, lostaltmail, fixmount, Assorted Tools 7825@comment node-name, next, previous, up 7826@section fixrmtab 7827@pindex fixrmtab 7828 7829A script to invalidate @file{/etc/rmtab} entries for hosts named. Also 7830restart mountd for changes to take effect. Use it for example: 7831 7832@example 7833fixrmtab @i{host1} @i{host2} @i{...} 7834@end example 7835 7836@c ---------------------------------------------------------------- 7837@node lostaltmail, lostaltmail.conf-sample, fixrmtab, Assorted Tools 7838@comment node-name, next, previous, up 7839@section lostaltmail 7840@pindex lostaltmail 7841 7842A script used with @i{Hlfsd} to resend any ``lost'' mail. @i{Hlfsd} 7843redirects mail which cannot be written into the user's home directory to 7844an alternate directory. This is useful to continue delivering mail, 7845even if the user's file system was unavailable, full, or over quota. 7846But, the mail which gets delivered to the alternate directory needs to 7847be resent to its respective users. This is what the @samp{lostaltmail} 7848script does. 7849 7850Use it as follows: 7851 7852@example 7853lostaltmail 7854@end example 7855 7856This script needs a configuration file @samp{lostaltmail.conf} set up 7857with the right parameters to properly work. @xref{Hlfsd}, for more 7858details. 7859 7860@c ---------------------------------------------------------------- 7861@node lostaltmail.conf-sample, mk-amd-map, lostaltmail, Assorted Tools 7862@comment node-name, next, previous, up 7863@section lostaltmail.conf-sample 7864@pindex lostaltmail.conf-sample 7865@cindex lostaltmail; configuration file 7866 7867This is a text file with configuration parameters needed for the 7868@samp{lostaltmail} script. The script includes comments explaining each 7869of the configuration variables. See it for more information. Also 7870@pxref{Hlfsd} for general information. 7871 7872@c ---------------------------------------------------------------- 7873@node mk-amd-map, pawd, lostaltmail.conf-sample, Assorted Tools 7874@comment node-name, next, previous, up 7875@section mk-amd-map 7876@pindex mk-amd-map 7877 7878This program converts a normal @i{Amd} map file into an ndbm database 7879with the same prefix as the named file. Use it as follows: 7880 7881@example 7882mk-amd-map @i{mapname} 7883@end example 7884 7885@c ---------------------------------------------------------------- 7886@node pawd, redhat-ctl-amd, mk-amd-map, Assorted Tools 7887@comment node-name, next, previous, up 7888@section pawd 7889@pindex pawd 7890 7891@i{Pawd} is used to print the current working directory, adjusted to 7892reflect proper paths that can be reused to go through the automounter 7893for the shortest possible path. In particular, the path printed back 7894does not include any of @i{Amd}'s local mount points. Using them is 7895unsafe, because @i{Amd} may unmount managed file systems from the mount 7896points, and thus including them in paths may not always find the files 7897within. 7898 7899Without any arguments, @i{Pawd} will print the automounter adjusted 7900current working directory. With any number of arguments, it will print 7901the adjusted path of each one of the arguments. 7902 7903@c ---------------------------------------------------------------- 7904@node redhat-ctl-amd, wait4amd, pawd, Assorted Tools 7905@comment node-name, next, previous, up 7906@section redhat-ctl-amd 7907@pindex redhat-ctl-amd 7908 7909This script is similar to @i{ctl-amd} (@pxref{ctl-amd}) but is intended 7910for Red Hat Linux systems. You can safely copy @i{redhat-ctl-amd} onto 7911@file{/etc/rc.d/init.d/amd}. The script supplied by @i{Am-utils} is 7912usually better than the one provided by Red Hat, because the Red Hat 7913script does not correctly kill @i{Amd} processes: it is too quick to 7914kill the wrong processes, leaving stale or hung mount points behind. 7915 7916@c ---------------------------------------------------------------- 7917@node wait4amd, wait4amd2die, redhat-ctl-amd, Assorted Tools 7918@comment node-name, next, previous, up 7919@section wait4amd 7920@pindex wait4amd 7921 7922A script to wait for @i{Amd} to start on a particular host before 7923performing an arbitrary command. The command is executed repeatedly, 7924with 1 second intervals in between. You may interrupt the script using 7925@samp{^C} (or whatever keyboard sequence your terminal's @samp{intr} function 7926is bound to). 7927 7928Examples: 7929 7930@table @t 7931@item wait4amd saturn amq -p -h saturn 7932When @i{Amd} is up on host @samp{saturn}, get the process ID of that 7933running @i{Amd}. 7934@item wait4amd pluto rlogin pluto 7935Remote login to host @samp{pluto} when @i{Amd} is up on that host. It 7936is generally necessary to wait for @i{Amd} to properly start and 7937initialize on a remote host before logging in to it, because otherwise 7938user home directories may not be accessible across the network. 7939@item wait4amd pluto 7940A short-hand version of the previous command, since the most useful 7941reason for this script is to login to a remote host. I use it very 7942often when testing out new versions of @i{Amd}, and need to reboot hung 7943hosts. 7944@end table 7945 7946@c ---------------------------------------------------------------- 7947@node wait4amd2die, wire-test, wait4amd, Assorted Tools 7948@comment node-name, next, previous, up 7949@section wait4amd2die 7950@pindex wait4amd2die 7951 7952This script is used internally by @samp{ctl-amd} when used to restart 7953@i{Amd}. It waits for @i{Amd} to terminate. If it detected that 7954@i{Amd} terminated cleanly, this script will return an exist status of 7955zero. Otherwise, it will return a non-zero exit status. 7956 7957The script tests for @i{Amd}'s existence once every 5 seconds, six 7958times, for a total of 30 seconds. It will return a zero exist status as 7959soon as it detects that @i{Amd} dies. 7960 7961@c ---------------------------------------------------------------- 7962@node wire-test, , wait4amd2die, Assorted Tools 7963@comment node-name, next, previous, up 7964@section wire-test 7965@pindex wire-test 7966 7967A simple program to test if some of the most basic networking functions 7968in am-util's library @file{libamu} work. It also tests the combination 7969of NFS protocol and version number that are supported from the current 7970host, to a remote one. 7971 7972For example, in this test a machine which only supports NFS Version 2 is 7973contacting a remote host that can support the same version, but using 7974both UDP and TCP. If no host name is specified, @samp{wire-test} will 7975try @file{localhost}. 7976 7977@example 7978$ wire-test moisil 7979Network name is "mcl-lab-net.cs.columbia.edu" 7980Network number is "128.59.13" 7981Network name is "old-net.cs.columbia.edu" 7982Network number is "128.59.16" 7983My IP address is 0x7f000001. 7984NFS Version and protocol tests to host "moisil"... 7985 testing vers=2, proto="udp" -> found version 2. 7986 testing vers=3, proto="udp" -> failed! 7987 testing vers=2, proto="tcp" -> found version 2. 7988 testing vers=3, proto="tcp" -> failed! 7989@end example 7990 7991@c ################################################################ 7992@node Examples, Internals, Assorted Tools, Top 7993@comment node-name, next, previous, up 7994@chapter Examples 7995 7996@menu 7997* User Filesystems:: 7998* Home Directories:: 7999* Architecture Sharing:: 8000* Wildcard Names:: 8001* rwho servers:: 8002* /vol:: 8003* /defaults with selectors:: 8004* /tftpboot in a chroot-ed environment:: 8005 8006@end menu 8007 8008@node User Filesystems, Home Directories, Examples, Examples 8009@comment node-name, next, previous, up 8010@section User Filesystems 8011@cindex User filesystems 8012@cindex Mounting user filesystems 8013 8014With more than one fileserver, the directories most frequently 8015cross-mounted are those containing user home directories. A common 8016convention used at Imperial College is to mount the user disks under 8017@t{/home/}@i{machine}. 8018 8019Typically, the @samp{/etc/fstab} file contained a long list of entries 8020such as: 8021 8022@example 8023@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... 8024@end example 8025 8026for each fileserver on the network. 8027 8028There are numerous problems with this system. The mount list can become 8029quite large and some of the machines may be down when a system is 8030booted. When a new fileserver is installed, @samp{/etc/fstab} must be 8031updated on every machine, the mount directory created and the filesystem 8032mounted. 8033 8034In many environments most people use the same few workstations, but 8035it is convenient to go to a colleague's machine and access your own 8036files. When a server goes down, it can cause a process on a client 8037machine to hang. By minimizing the mounted filesystems to only include 8038those actively being used, there is less chance that a filesystem will 8039be mounted when a server goes down. 8040 8041The following is a short extract from a map taken from a research fileserver 8042at Imperial College. 8043 8044Note the entry for @samp{localhost} which is used for users such as 8045the operator (@samp{opr}) who have a home directory on most machine as 8046@samp{/home/localhost/opr}. 8047 8048@example 8049/defaults opts:=rw,intr,grpid,nosuid 8050charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8051 host==$@{key@};type:=ufs;dev:=/dev/xd0g 8052# 8053... 8054 8055# 8056localhost type:=link;fs:=$@{host@} 8057... 8058# 8059# dylan has two user disks so have a 8060# top directory in which to mount them. 8061# 8062dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8063# 8064dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8065 host==dylan;type:=ufs;dev:=/dev/dsk/2s0 8066# 8067dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8068 host==dylan;type:=ufs;dev:=/dev/dsk/5s0 8069... 8070# 8071toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8072 host==$@{key@};type:=ufs;dev:=/dev/xy1g 8073... 8074# 8075zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8076 host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 8077# 8078# Just for access... 8079# 8080gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8081gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} 8082# 8083gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} 8084... 8085@end example 8086 8087This map is shared by most of the machines listed so on those 8088systems any of the user disks is accessible via a consistent name. 8089@i{Amd} is started with the following command 8090 8091@example 8092amd /home amd.home 8093@end example 8094 8095Note that when mounting a remote filesystem, the @dfn{automounted} 8096mount point is referenced, so that the filesystem will be mounted if 8097it is not yet (at the time the remote @samp{mountd} obtains the file handle). 8098 8099@node Home Directories, Architecture Sharing, User Filesystems, Examples 8100@comment node-name, next, previous, up 8101@section Home Directories 8102@cindex Home directories 8103@cindex Example of mounting home directories 8104@cindex Mount home directories 8105 8106One convention for home directories is to locate them in @samp{/homes} 8107so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more 8108than a single fileserver it is convenient to spread user files across 8109several machines. All that is required is a mount-map which converts 8110login names to an automounted directory. 8111 8112Such a map might be started by the command: 8113 8114@example 8115amd /homes amd.homes 8116@end example 8117 8118where the map @samp{amd.homes} contained the entries: 8119 8120@example 8121/defaults type:=link # All the entries are of type:=link 8122jsp fs:=/home/charm/jsp 8123njw fs:=/home/dylan/dk5/njw 8124... 8125phjk fs:=/home/toytown/ai/phjk 8126sjv fs:=/home/ganymede/sjv 8127@end example 8128 8129Whenever a login name is accessed in @samp{/homes} a symbolic link 8130appears pointing to the real location of that user's home directory. In 8131this example, @samp{/homes/jsp} would appear to be a symbolic link 8132pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also 8133be an automount point. 8134 8135This system causes an extra level of symbolic links to be used. 8136Although that turns out to be relatively inexpensive, an alternative is 8137to directly mount the required filesystems in the @samp{/homes} 8138map. The required map is simple, but long, and its creation is best automated. 8139The entry for @samp{jsp} could be: 8140 8141@example 8142jsp -sublink:=$@{key@};rfs:=/home/charm \ 8143 host==charm;type:=ufs;dev:=/dev/xd0g \ 8144 host!=charm;type:=nfs;rhost:=charm 8145@end example 8146 8147This map can become quite big if it contains a large number of entries. 8148By combining two other features of @i{Amd} it can be greatly simplified. 8149 8150First the UFS partitions should be mounted under the control of 8151@samp{/etc/fstab}, taking care that they are mounted in the same place 8152that @i{Amd} would have automounted them. In most cases this would be 8153something like @samp{/a/@dfn{host}/home/@dfn{host}} and 8154@samp{/etc/fstab} on host @samp{charm} would have a line:@refill 8155 8156@example 8157/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 8158@end example 8159 8160The map can then be changed to: 8161 8162@example 8163/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid 8164jsp rhost:=charm;rfs:=/home/charm 8165njw rhost:=dylan;rfs:=/home/dylan/dk5 8166... 8167phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} 8168sjv rhost:=ganymede;rfs:=/home/ganymede 8169@end example 8170 8171This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} 8172not equal to @code{$@{rhost@}}). On the machine where the filesystem is 8173stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} 8174will construct a local filesystem mount point which corresponds to the 8175name of the locally mounted UFS partition. If @i{Amd} is started with 8176the @code{-r} option then instead of attempting an NFS mount, @i{Amd} will 8177simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If 8178@code{-r} is not used then a loopback NFS mount will be made. This type of 8179mount is known to cause a deadlock on many systems. 8180 8181@node Architecture Sharing, Wildcard Names, Home Directories, Examples 8182@comment node-name, next, previous, up 8183@section Architecture Sharing 8184@cindex Architecture sharing 8185@cindex Sharing a fileserver between architectures 8186@cindex Architecture dependent volumes 8187 8188@c %At the moment some of the research machines have sets of software 8189@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, 8190@c %system sources, local sources, prolog libraries and so on. 8191Often a filesystem will be shared by machines of different architectures. 8192Separate trees can be maintained for the executable images for each 8193architecture, but it may be more convenient to have a shared tree, 8194with distinct subdirectories. 8195 8196A shared tree might have the following structure on the fileserver (called 8197@samp{fserver} in the example): 8198 8199@example 8200local/tex 8201local/tex/fonts 8202local/tex/lib 8203local/tex/bin 8204local/tex/bin/sun3 8205local/tex/bin/sun4 8206local/tex/bin/hp9000 8207... 8208@end example 8209 8210In this example, the subdirectories of @samp{local/tex/bin} should be 8211hidden when accessed via the automount point (conventionally @samp{/vol}). 8212A mount-map for @samp{/vol} to achieve this would look like: 8213 8214@example 8215/defaults sublink:=$@{/key@};rhost:=fserver;type:=link 8216tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8217tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ 8218 host==fserver;fs:=/usr/local/tex 8219tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ 8220 host==fserver;fs:=/usr/local/tex 8221tex/bin -sublink:=$@{/key@}/$@{arch@} \ 8222 host!=fserver;type:=nfs;rfs:=/vol/tex \ 8223 host:=fserver;fs:=/usr/local/tex 8224@end example 8225 8226When @samp{/vol/tex/bin} is referenced, the current machine architecture 8227is automatically appended to the path by the @code{$@{sublink@}} 8228variable. This means that users can have @samp{/vol/tex/bin} in their 8229@samp{PATH} without concern for architecture dependencies. 8230 8231@node Wildcard Names, rwho servers, Architecture Sharing, Examples 8232@comment node-name, next, previous, up 8233@section Wildcard Names & Replicated Servers 8234 8235By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing 8236directory with additional entries. 8237The system files are usually mounted under @samp{/usr}. If instead, 8238@i{Amd} is mounted on @samp{/usr}, additional 8239names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. 8240A map to do this would have the form: 8241 8242@example 8243local type:=auto;fs:=local-map 8244share type:=auto;fs:=share-map 8245* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ 8246 rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 8247@end example 8248 8249Note that the assignment to @code{$@{sublink@}} is surrounded by double 8250quotes to prevent the incoming key from causing the map to be 8251misinterpreted. This map has the effect of directing any access to 8252@samp{/usr/local} or @samp{/usr/share} to another automount point. 8253 8254In this example, it is assumed that the @samp{/usr} files are replicated 8255on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. 8256For any references other than to @samp{local} and @samp{share} one of 8257the servers is used and a symbolic link to 8258@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is 8259returned once an appropriate filesystem has been mounted.@refill 8260 8261@node rwho servers, /vol, Wildcard Names, Examples 8262@comment node-name, next, previous, up 8263@section @samp{rwho} servers 8264@cindex rwho servers 8265@cindex Architecture specific mounts 8266@cindex Example of architecture specific mounts 8267 8268The @samp{/usr/spool/rwho} directory is a good candidate for automounting. 8269For efficiency reasons it is best to capture the rwho data on a small 8270number of machines and then mount that information onto a large number 8271of clients. The data written into the rwho files is byte order dependent 8272so only servers with the correct byte ordering can be used by a client: 8273 8274@example 8275/defaults type:=nfs 8276usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ 8277 rhost:=vaxA rhost:=vaxB \ 8278 || -rfs:=/usr/spool/rwho \ 8279 rhost:=sun4 rhost:=hp300 8280@end example 8281 8282@node /vol, /defaults with selectors, rwho servers, Examples 8283@comment node-name, next, previous, up 8284@section @samp{/vol} 8285@cindex /vol 8286@cindex Catch-all mount point 8287@cindex Generic volume name 8288 8289@samp{/vol} is used as a catch-all for volumes which do not have other 8290conventional names. 8291 8292Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. 8293The @samp{r+d} tree is used for new or experimental software that needs 8294to be available everywhere without installing it on all the fileservers. 8295Users wishing to try out the new software then simply include 8296@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill 8297 8298The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has 8299different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} 8300sub-directories for each machine architecture. For example, 8301@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory 8302@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed 8303a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be 8304returned.@refill 8305 8306@example 8307/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft 8308wp -opts:=rw,grpid,nosuid;rhost:=charm \ 8309 host==charm;type:=link;fs:=/usr/local/wp \ 8310 host!=charm;type:=nfs;rfs:=/vol/wp 8311... 8312# 8313src -opts:=rw,grpid,nosuid;rhost:=charm \ 8314 host==charm;type:=link;fs:=/usr/src \ 8315 host!=charm;type:=nfs;rfs:=/vol/src 8316# 8317r+d type:=auto;fs:=$@{map@};pref:=r+d/ 8318# per architecture bin,etc,lib&ucb... 8319r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8320r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8321r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8322r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8323r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8324r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8325r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8326# hades pictures 8327pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8328 host==thpfs;type:=link;fs:=/nbsd/pictures \ 8329 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures 8330# hades tools 8331hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8332 host==thpfs;type:=link;fs:=/nbsd/hades \ 8333 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades 8334# bsd tools for hp. 8335bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ 8336 host==thpfs;type:=link;fs:=/nbsd/bsd \ 8337 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd 8338@end example 8339 8340@node /defaults with selectors, /tftpboot in a chroot-ed environment, /vol, Examples 8341@comment node-name, next, previous, up 8342@section @samp{/defaults} with selectors 8343@cindex /defaults with selectors 8344@cindex selectors on default 8345 8346It is sometimes useful to have different defaults for a given map. To 8347achieve this, the @samp{/defaults} entry must be able to process normal 8348selectors. This feature is turned on by setting 8349@samp{selectors_in_defaults = yes} in the @file{amd.conf} file. 8350@xref{selectors_in_defaults Parameter}. 8351 8352In this example, I set different default NFS mount options for hosts 8353which are running over a slower network link. By setting a smaller size 8354for the NFS read and write buffer sizes, you can greatly improve remote 8355file service performance. 8356 8357@example 8358/defaults \ 8359 wire==slip-net;opts:=rw,intr,rsize=1024,wsize=1024,timeo=20,retrans=10 \ 8360 wire!=slip-net;opts:=rw,intr 8361@end example 8362 8363@node /tftpboot in a chroot-ed environment, , /defaults with selectors, Examples 8364@comment node-name, next, previous, up 8365@section @samp{/tftpboot} in a chroot-ed environment 8366@cindex /tftpboot in a chroot-ed environment 8367@cindex chroot; /tftpboot example 8368 8369In this complex example, we attempt to run an @i{Amd} process 8370@emph{inside} a chroot-ed environment. @samp{tftpd} (Trivial FTP) is 8371used to trivially retrieve files used to boot X-Terminals, Network 8372Printers, Network routers, diskless workstations, and other such 8373devices. For security reasons, @samp{tftpd} (and also @samp{ftpd}) 8374processes are run using the @b{chroot}(2) system call. This provides an 8375environment for these processes, where access to any files outside the 8376directory where the chroot-ed process runs is denied. 8377 8378For example, if you start @samp{tftpd} on your system with 8379 8380@example 8381chroot /tftpboot /usr/sbin/tftpd 8382@end example 8383 8384@noindent 8385then the @samp{tftpd} process will not be able to access any files 8386outside @file{/tftpboot}. This ensures that no one can retrieve files 8387such as @file{/etc/passwd} and run password crackers on it. 8388 8389Since the TFTP service works by broadcast, it is necessary to have at 8390least one TFTP server running on each subnet. If you have lots of files 8391that you need to make available for @samp{tftp}, and many subnets, it 8392could take significant amounts of disk space on each host serving them. 8393 8394A solution we implemented at Columbia University was to have every host 8395run @samp{tftpd}, but have those servers retrieve the boot files from 8396two replicated servers. Those replicated servers have special 8397partitions dedicated to the many network boot files. 8398 8399We start @i{Amd} as follows: 8400 8401@example 8402amd /tftpboot/.amd amd.tftpboot 8403@end example 8404 8405That is, @i{Amd} is serving the directory @file{/tftpboot/.amd}. The 8406@samp{tftp} server runs inside @file{/tftpboot} and is chroot-ed in that 8407directory too. The @file{amd.tftpboot} map looks like: 8408 8409@example 8410# 8411# Amd /tftpboot directory -> host map 8412# 8413 8414/defaults opts:=nosuid,ro,intr,soft;fs:=/tftpboot/import;type:=nfs 8415 8416tp host==lol;rfs:=/n/lol/import/tftpboot;type:=lofs \ 8417 host==ober;rfs:=/n/ober/misc/win/tftpboot;type:=lofs \ 8418 rhost:=ober;rfs:=/n/ober/misc/win/tftpboot \ 8419 rhost:=lol;rfs:=/n/lol/import/tftpboot 8420@end example 8421 8422To help understand this example, I list a few of the file entries that 8423are created inside @file{/tftpboot}: 8424 8425@example 8426$ ls -la /tftpboot 8427dr-xr-xr-x 2 root 512 Aug 30 23:11 .amd 8428drwxrwsr-x 12 root 512 Aug 30 08:00 import 8429lrwxrwxrwx 1 root 33 Feb 27 1997 adminpr.cfg -> ./.amd/tp/hplj/adminpr.cfg 8430lrwxrwxrwx 1 root 22 Dec 5 1996 tekxp -> ./.amd/tp/xterms/tekxp 8431lrwxrwxrwx 1 root 1 Dec 5 1996 tftpboot -> . 8432@end example 8433 8434Here is an explanation of each of the entries listed above: 8435 8436@table @code 8437 8438@item .amd 8439This is the @i{Amd} mount point. Note that you do not need to run a 8440separate @i{Amd} process for the TFTP service. The @b{chroot}(2) system 8441call only protects against file access, but the same process can still 8442serve files and directories inside and outside the chroot-ed 8443environment, because @i{Amd} itself was not run in chroot-ed mode. 8444 8445@item import 8446This is the mount point where @i{Amd} will mount the directories 8447containing the boot files. The map is designed so that remote 8448directories will be NFS mounted (even if they are already mounted 8449elsewhere), and local directories are loopback mounted (since they are 8450not accessible outside the chroot-ed @file{/tftpboot} directory). 8451 8452@item adminpr.cfg 8453@itemx tekxp 8454Two manually created symbolic links to directories @emph{inside} the 8455@i{Amd}-managed directory. The crossing of the component @file{tp} will 8456cause @i{Amd} to automount one of the remote replicas. Once crossed, 8457access to files inside proceeds as usual. The @samp{adminpr.cfg} is a 8458configuration file for an HP Laser-Jet 4si printer, and the @samp{tekxp} 8459is a directory for Tektronix X-Terminal boot files. 8460 8461@item tftpboot 8462This innocent looking symlink is important. Usually, when devices boot 8463via the TFTP service, they perform the @samp{get file} command to 8464retrieve @var{file}. However, some devices assume that @samp{tftpd} 8465does not run in a chroot-ed environment, but rather ``unprotected'', and 8466thus use a full pathname for files to retrieve, as in @samp{get 8467/tftpboot/file}. This symlink effectively strips out the leading 8468@file{/tftpboot/}. 8469 8470@end table 8471 8472@c ################################################################ 8473@node Internals, Acknowledgments & Trademarks, Examples, Top 8474@comment node-name, next, previous, up 8475@chapter Internals 8476 8477Note that there are more error and logging messages possible than are 8478listed here. Most of them are self-explanatory. Refer to the program 8479sources for more details on the rest. 8480 8481@menu 8482* Log Messages:: 8483@end menu 8484 8485@node Log Messages, , Internals, Internals 8486@comment node-name, next, previous, up 8487@section Log Messages 8488 8489In the following sections a brief explanation is given of some of the 8490log messages made by @i{Amd}. Where the message is in @samp{typewriter} 8491font, it corresponds exactly to the message produced by @i{Amd}. Words 8492in @dfn{italic} are replaced by an appropriate string. Variables, 8493@code{$@{@i{var}@}}, indicate that the value of the appropriate variable is 8494output. 8495 8496Log messages are either sent directly to a file, 8497or logged via the @b{syslog}(3) mechanism. @xref{log_file Parameter}. 8498In either case, entries in the file are of the form: 8499@example 8500@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} 8501@end example 8502 8503@menu 8504* Fatal errors:: 8505* Info messages:: 8506@end menu 8507 8508@node Fatal errors, Info messages, Log Messages, Log Messages 8509@comment node-name, next, previous, up 8510@subsection Fatal errors 8511 8512@i{Amd} attempts to deal with unusual events. Whenever it is not 8513possible to deal with such an error, @i{Amd} will log an appropriate 8514message and, if it cannot possibly continue, will either exit or abort. 8515These messages are selected by @samp{-x fatal} on the command line. 8516When @b{syslog}(3) is being used, they are logged with level 8517@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to 8518remain in a precarious state and should be restarted at the earliest 8519opportunity. 8520 8521@table @t 8522 8523@item Attempting to inherit not-a-filesystem 8524The prototype mount point created during a filesystem restart did not 8525contain a reference to the restarted filesystem. This error ``should 8526never happen''. 8527 8528@item Can't bind to domain "@i{NIS-domain}" 8529A specific NIS domain was requested on the command line, but no server 8530for that domain is available on the local net. 8531 8532@item Can't determine IP address of this host (@i{hostname}) 8533When @i{Amd} starts it determines its own IP address. If this lookup 8534fails then @i{Amd} cannot continue. The hostname it looks up is that 8535obtained returned by @b{gethostname}(2) system call. 8536 8537@item Can't find root file handle for @i{automount point} 8538@i{Amd} creates its own file handles for the automount points. When it 8539mounts itself as a server, it must pass these file handles to the local 8540kernel. If the filehandle is not obtainable the mount point is ignored. 8541This error ``should never happen''. 8542 8543@item Must be root to mount filesystems (euid = @i{euid}) 8544To prevent embarrassment, @i{Amd} makes sure it has appropriate system 8545privileges. This amounts to having an euid of 0. The check is made 8546after argument processing complete to give non-root users a chance to 8547access the @code{-v} option. 8548 8549@item No work to do - quitting 8550No automount points were given on the command line and so there is no 8551work to do. 8552 8553@item Out of memory 8554While attempting to malloc some memory, the memory space available to 8555@i{Amd} was exhausted. This is an unrecoverable error. 8556 8557@item Out of memory in realloc 8558While attempting to realloc some memory, the memory space available to 8559@i{Amd} was exhausted. This is an unrecoverable error. 8560 8561@item cannot create rpc/udp service 8562Either the NFS or AMQ endpoint could not be created. 8563 8564@item gethostname: @i{description} 8565The @b{gethostname}(2) system call failed during startup. 8566 8567@item host name is not set 8568The @b{gethostname}(2) system call returned a zero length host name. 8569This can happen if @i{Amd} is started in single user mode just after 8570booting the system. 8571 8572@item ifs_match called! 8573An internal error occurred while restarting a pre-mounted filesystem. 8574This error ``should never happen''. 8575 8576@item mount_afs: @i{description} 8577An error occurred while @i{Amd} was mounting itself. 8578 8579@item run_rpc failed 8580Somehow the main NFS server loop failed. This error ``should never 8581happen''. 8582 8583@item unable to free rpc arguments in amqprog_1 8584The incoming arguments to the AMQ server could not be free'ed. 8585 8586@item unable to free rpc arguments in nfs_program_1 8587The incoming arguments to the NFS server could not be free'ed. 8588 8589@item unable to register (AMQ_PROGRAM, AMQ_VERSION, udp) 8590The AMQ server could not be registered with the local portmapper or the 8591internal RPC dispatcher. 8592 8593@item unable to register (NFS_PROGRAM, NFS_VERSION, 0) 8594The NFS server could not be registered with the internal RPC dispatcher. 8595 8596@end table 8597 8598XXX: This section needs to be updated 8599 8600@node Info messages, , Fatal errors, Log Messages 8601@comment node-name, next, previous, up 8602@subsection Info messages 8603 8604@i{Amd} generates information messages to record state changes. These 8605messages are selected by @samp{-x info} on the command line. When 8606@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. 8607 8608The messages listed below can be generated and are in a format suitable 8609for simple statistical analysis. @dfn{mount-info} is the string 8610that is displayed by @dfn{Amq} in its mount information column and 8611placed in the system mount table. 8612 8613@table @t 8614 8615@item "@t{$@{@i{path}@}}" forcibly timed out 8616An automount point has been timed out by the @i{Amq} command. 8617 8618@item "@t{$@{@i{path}@}}" has timed out 8619No access to the automount point has been made within the timeout 8620period. 8621 8622@item Filehandle denied for "$@{@i{rhost}@}:$@{@i{rfs}@}" 8623The mount daemon refused to return a file handle for the requested filesystem. 8624 8625@item Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}": @i{description} 8626The mount daemon gave some other error for the requested filesystem. 8627 8628@item Finishing with status @i{exit-status} 8629@i{Amd} is about to exit with the given exit status. 8630 8631@item Re-synchronizing cache for map @t{$@{@i{map}@}} 8632The named map has been modified and the internal cache is being re-synchronized. 8633 8634@item file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored 8635An automount point has timed out, but the corresponding file server is 8636known to be down. This message is only produced once for each mount 8637point for which the server is down. 8638 8639@item file server @t{$@{@i{rhost}@}} type nfs is down 8640An NFS file server that was previously up is now down. 8641 8642@item file server @t{$@{@i{rhost}@}} type nfs is up 8643An NFS file server that was previously down is now up. 8644 8645@item file server @t{$@{@i{rhost}@}} type nfs starts down 8646A new NFS file server has been referenced and is known to be down. 8647 8648@item file server @t{$@{@i{rhost}@}} type nfs starts up 8649A new NFS file server has been referenced and is known to be up. 8650 8651@item mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out 8652Attempts to mount a filesystem for the given automount point have failed 8653to complete within 30 seconds. 8654 8655@item @i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8656A new file system has been mounted. 8657 8658@item @i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8659@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. 8660 8661@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} 8662A file system has been unmounted. 8663 8664@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}} 8665A file system of which only a sub-directory was in use has been unmounted. 8666 8667@item restarting @i{mount-info} on @t{$@{@i{fs}@}} 8668A pre-mounted file system has been noted. 8669 8670@end table 8671 8672XXX: This section needs to be updated 8673 8674@c ################################################################ 8675@node Acknowledgments & Trademarks, Index, Internals, Top 8676@comment node-name, next, previous, up 8677@unnumbered Acknowledgments & Trademarks 8678 8679Many thanks to the Am-Utils Users 8680mailing list through the months developing am-utils. These members 8681have contributed to the discussions, ideas, code and documentation, 8682and subjected their systems to alpha quality code. Special thanks go 8683to those @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors} who have 8684submitted patches, and especially to the maintainers: 8685 8686@itemize @bullet 8687@item @uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} 8688@item @email{ionut AT badula.org,Ion Badulescu} 8689@item @email{ro AT techfak.uni-bielefeld.de,Rainer Orth} 8690@item @email{nick.williams AT morganstanley.com,Nick Williams} 8691@end itemize 8692 8693Thanks to the Formal Methods Group at Imperial College for suffering 8694patiently while @i{Amd} was being developed on their machines. 8695 8696Thanks to the many people who have helped with the development of 8697@i{Amd}, especially Piete Brooks at the Cambridge University Computing 8698Lab for many hours of testing, experimentation and discussion. 8699 8700Thanks to the older @email{amd-workers AT majordomo.glue.umd.edu,Amd 8701Workers} mailing list (now defunct) members for many suggestions and 8702bug reports to @i{Amd}. 8703 8704@itemize @bullet 8705@item 8706@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital 8707Equipment Corporation. 8708@item 8709@b{AIX} and @b{IBM} are registered trademarks of International Business 8710Machines Corporation. 8711@item 8712@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun 8713Microsystems, Inc. 8714@item 8715@b{UNIX} is a registered trademark in the USA and other countries, 8716exclusively licensed through X/Open Company, Ltd. 8717@item 8718All other registered trademarks are owned by their respective owners. 8719@end itemize 8720 8721@c ################################################################ 8722@node Index, , Acknowledgments & Trademarks, Top 8723@comment node-name, next, previous, up 8724@unnumbered Index 8725 8726@printindex cp 8727 8728@contents 8729@bye 8730 8731@c ==================================================================== 8732@c ISPELL LOCAL WORDS: 8733@c LocalWords: setfilename amdref overfullrule settitle titlepage titlefont nz 8734@c LocalWords: authorfont vskip ifinfo iftex cindex unnumberedsec dfn xref vol 8735@c LocalWords: locationN pxref jpo nott concentrix Sjoerd sjoerd cwi Eitan vuw 8736@c LocalWords: Mizrotsky eitan shumuji dgux fpx scp hcx metcalf masala hlh OTS 8737@c LocalWords: Presnell srp cgl Trost trost ogi pyrOSx OSx tubsibr riscix iX 8738@c LocalWords: Piete pb Lindblad cjl ai umax utek xinu Mitchum D'Souza dsouza 8739@c LocalWords: mrc apu alliant aviion AViiON fps macII multimax tahoe vax emph 8740@c LocalWords: mapdefault valA valB valC YPTSDIR ETCDIR substr MAKEDBM YPDBDIR 8741@c LocalWords: NOPUSH njw dylan dk dylan njw anydir domN achilles mjh pref sel 8742@c LocalWords: gdef loc loc loc ldots autodir remopts rwho rwho styx styx yoyo 8743@c LocalWords: noindent gould rvdmount rvdunmount fserver mtmp unioned logfile 8744@c LocalWords: dmn esac phjk toytown toytown toytown toytown phjk RdDir RdLnk 8745@c LocalWords: volname attrs netif dougal inaddr hwaddr ec mountmaps passno xy 8746@c LocalWords: freq dumpset hfs brian florence localinfo fstabs automaps defn 8747@c LocalWords: localname fsck'd opr gummo sjv ganymede sjv fserv fserv fserv 8748@c LocalWords: vaxA vaxB wp thpfs nbsd asis ifs amqprog free'ed printindex gov 8749@c LocalWords: LocalWords syncodeindex Distrib bsdnet lanl AutoMounter acis ic 8750@c LocalWords: ac uk aix bsd Mullender nl il DG lcs hpux irix ucsf NeXT cse cl 8751@c LocalWords: mt FX hp ibm mips utils def def Domainname eg hostd getwd tmp 8752@c LocalWords: subsubsection rw grpid intr noconn nocto nodevs nosuid retrans 8753@c LocalWords: rsize tcp timeo nounmount utimeout DDEBUG nodaemon fd hostnames 8754@c LocalWords: pid Amd's pendry vangogh nfsx backoff stats nomap nostats CRIT 8755@c LocalWords: noinfo clustername RVD dsk dsk amq hostports osver statfs str 8756@c LocalWords: ou counter's amdmaps proj src tftpboot sh mv cd sbin ypcat inet 8757@c LocalWords: Getattr getattr localhost fhandles netmask fstype noquota addr 8758@c LocalWords: exportfs Dumpsets dumpsets pindex ldif fixmount fixrmtab euid 8759@c LocalWords: lostaltmail realloc netnumber itemx primnetnum primnetname ARG 8760@c LocalWords: subsnetname subsnetnum netgrp netgroup multitable Shlib dec osf 8761@c LocalWords: hppa pc bsdi freebsd netbsd openbsd ncr sysv rs acdirmax fsid 8762@c LocalWords: acdirmin acregmax acregmin actimeo dumbtimr nfsv noac noauto sd 8763@c LocalWords: nocache nodev noint nosub pgthresh posix rdonly suid symttl mfs 8764@c LocalWords: AMFS umapfs myftpdir unionfs es mapname mapfile mapfile slocal 8765@c LocalWords: mailspool saturn saturn notknown lol ober dr xr xr drwxrwsr cfg 8766@c LocalWords: lrwxrwxrwx adminpr hplj adminpr cfg tekxp xterms tekxp Dupuy tp 8767@c LocalWords: linkname hlfsddump dirname rmtab pluto rlogin direntry pg vr dn 8768@c LocalWords: maxmem hlfsdir xmailbox showmount cn amdmap amdmapName resvport 8769@c LocalWords: objectClass amdmapKey amdmapValue ln powerpc amdmapTimestamp ez 8770@c LocalWords: moisil FSinfo Libtool Unmounting sublink fileservers NullProc 8771@c LocalWords: gethostname mount's unmounts linkx remounts unmounting UAs SA's 8772@c LocalWords: mountpoint mountpoints unescaped UIDs util's overlayed uref EFS 8773@c LocalWords: serv maxgroups nfsl cachedir copt cfsadmin efs addopts fg ROMs 8774@c LocalWords: nointr extatt setchapternewpage columnfractions alphaev gnulibc 8775@c LocalWords: freebsdelf gnuoldld ifhtml defperm nodefperm norrip RRIP rrip 8776@c LocalWords: noversion attr XXXXXX netgrpd rh mkstemp uid gid noexec mntfs 8777@c LocalWords: nomnttab optionstr hrtime xdrtrace getpwd proplist redhat ctl 8778@c LocalWords: texinfo texi ib sp cartouche ified xlatecookie dircategory sc 8779@c LocalWords: AddInfo suse Novell softlookup ENOENT USB fullybrowsable LDAPv 8780@c LocalWords: amy ie xfffffe zebedee andrew diskfull hdmail searchable si 8781@c LocalWords: Orth ESTALE 8782