1\input texinfo @c -*-texinfo-*- 2@c $NetBSD: am-utils.texi,v 1.1.1.3 2015/01/17 16:34:15 christos Exp $ 3@c 4@c Copyright (c) 1997-2014 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. Neither the name of the University nor the names of its contributors 22@c may be used to endorse or promote products derived from this software 23@c without specific prior written permission. 24@c 25@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35@c 36@c 37@c File: am-utils/doc/am-utils.texi 38@c 39@setfilename am-utils.info 40 41@include version.texi 42 43@c info directory entry 44@dircategory Administration 45@direntry 46* Am-utils: (am-utils). The Amd automounter suite of utilities 47@end direntry 48 49@settitle Am-utils (4.4BSD Automounter Utilities) 50@setchapternewpage odd 51 52@titlepage 53@title Am-utils (4.4BSD Automounter Utilities) 54@subtitle For version @value{VERSION}, @value{UPDATED} 55 56@author Erez Zadok 57(Originally by Jan-Simon Pendry and Nick Williams) 58 59@page 60Copyright @copyright{} 1997-2014 Erez Zadok 61@* 62Copyright @copyright{} 1989 Jan-Simon Pendry 63@* 64Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 65@* 66Copyright @copyright{} 1989 The Regents of the University of California. 67@sp 1 68All Rights Reserved. 69@vskip 1ex 70Permission to copy this document, or any portion of it, as 71necessary for use of this software is granted provided this 72copyright notice and statement of permission are included. 73@end titlepage 74@page 75 76@c Define a new index for options. 77@syncodeindex pg cp 78@syncodeindex vr cp 79 80@ifinfo 81 82@c ################################################################ 83@node Top, License, , (DIR) 84 85@b{Am-utils (4.4BSD Automounter Utilities) User Manual} 86@* 87For version @value{VERSION}, @value{UPDATED} 88 89@b{Erez Zadok} 90@* 91(Originally by Jan-Simon Pendry and Nick Williams) 92 93Copyright @copyright{} 1997-2014 Erez Zadok 94@* 95Copyright @copyright{} 1989 Jan-Simon Pendry 96@* 97Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 98@* 99Copyright @copyright{} 1989 The Regents of the University of California. 100@* 101All Rights Reserved. 102 103Permission to copy this document, or any portion of it, as 104necessary for use of this software is granted provided this 105copyright notice and statement of permission are included. 106 107Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd 108automounter, the Amq query and control program, the Hlfsd daemon, and 109other tools. This Info file describes how to use and understand the 110tools within Am-utils. 111@end ifinfo 112 113@menu 114* License:: Explains the terms and conditions for using 115 and distributing Am-utils. 116* Distrib:: How to get the latest Am-utils distribution. 117* AddInfo:: How to get additional information. 118* Intro:: An introduction to Automounting concepts. 119* History:: History of am-utils' development. 120* Overview:: An overview of Amd. 121* Supported Platforms:: Machines and Systems supported by Amd. 122* Mount Maps:: Details of mount maps. 123* Amd Command Line Options:: All the Amd command line options explained. 124* Filesystem Types:: The different mount types supported by Amd. 125* Amd Configuration File:: The amd.conf file syntax and meaning. 126* Run-time Administration:: How to start, stop and control Amd. 127* FSinfo:: The FSinfo filesystem management tool. 128* Hlfsd:: The Home-Link Filesystem server. 129* Assorted Tools:: Other tools which come with am-utils. 130* Examples:: Some examples showing how Amd might be used. 131* Internals:: Implementation details. 132* Acknowledgments & Trademarks:: Legal Notes. 133 134Indexes 135* Index:: An item for each concept. 136@end menu 137 138@iftex 139@unnumbered Preface 140 141This manual documents the use of the 4.4BSD automounter tool suite, 142which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is 143primarily a reference manual. While no tutorial exists, there are 144examples available. @xref{Examples}. 145 146This manual comes in two forms: the published form and the Info form. 147The Info form is for on-line perusal with the INFO program which is 148distributed along with GNU texinfo package (a version of which is 149available for GNU Emacs).@footnote{GNU packages can be found in 150@url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially 151the same text and are generated from a common source file, which is 152distributed with the @i{Am-utils} source. 153@end iftex 154 155@c ################################################################ 156@node License, Distrib, Top, Top 157@unnumbered License 158@cindex License Information 159 160@i{Am-utils} is not in the public domain; it is copyrighted and there are 161restrictions on its distribution. 162 163Redistribution and use in source and binary forms, with or without 164modification, are permitted provided that the following conditions are 165met: 166 167@enumerate 168 169@item 170Redistributions of source code must retain the above copyright notice, 171this list of conditions and the following disclaimer. 172 173@item 174Redistributions in binary form must reproduce the above copyright 175notice, this list of conditions and the following disclaimer in the 176documentation and/or other materials provided with the distribution. 177 178@item 179Neither the name of the University nor the names of its contributors may 180be used to endorse or promote products derived from this software 181without specific prior written permission. 182 183@end enumerate 184 185THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 186ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 187IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 188PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 189BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 190CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 191SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 192INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 193CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 194ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 195THE POSSIBILITY OF SUCH DAMAGE. 196 197@c ################################################################ 198@node Distrib, AddInfo, License, Top 199@unnumbered Source Distribution 200@cindex Source code distribution 201@cindex Obtaining the source code 202 203The @i{Am-utils} home page is located in 204@example 205@url{http://www.am-utils.org/} 206@end example 207 208You can get the latest distribution version of @i{Am-utils} from 209@example 210@url{ftp://ftp.am-utils.org/pub/am-utils/am-utils.tar.gz} 211@end example 212 213Additional alpha, beta, and release distributions are available in 214@example 215@url{ftp://ftp.am-utils.org/pub/am-utils/}. 216@end example 217 218Revision 5.2 was part of the 4.3BSD Reno distribution. 219 220Revision 5.3bsdnet, a late alpha version of 5.3, was part 221of the BSD network version 2 distribution 222 223Revision 6.0 was made independently by 224Erez Zadok at the Computer Science 225Department of @uref{http://www.cs.columbia.edu/,Columbia University}, 226as part of his 227@uref{http://www.fsl.cs.sunysb.edu/docs/zadok-thesis-proposal/,PhD 228thesis work}. Am-utils (especially version 6.1) continues to be 229developed and maintained at the 230@uref{http://www.cs.sunysb.edu/,Computer Science Department} of 231@uref{http://www.stonybrook.edu/,Stony Brook University}, as a service 232to the user community. 233 234 235@xref{History}, for more details. 236 237@c ################################################################ 238@node AddInfo, Intro, Distrib, Top 239@unnumbered Getting Additional Information 240@cindex Getting Additional Information 241 242@unnumberedsec Bug Reports 243@cindex Bug reports 244 245Before reporting a bug, see if it is a known one in the 246@uref{http://www.am-utils.org/docs/am-utils/BUGS.txt,bugs} file. 247 248If you find a problem and hopefully you can reproduce it, please 249describe it in detail and 250@uref{https://bugzilla.filesystems.org/,submit a bug report} via 251@uref{http://www.bugzilla.org/,Bugzilla}. Alternatively, you can send 252your bug report to the ``am-utils'' list (see 253@url{http://www.am-utils.org/} under ``Mailing Lists'') quoting the details 254of the release and your configuration. These details can be obtained 255by running the command @samp{amd -v}. It would greatly help if you 256could provide a reproducible procedure for detecting the bug you are 257reporting. 258 259Providing working patches is highly encouraged. Every patch 260incorporated, however small, will get its author an honorable mention in 261the @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors 262file}. 263 264@unnumberedsec Mailing Lists 265@cindex Mailing lists 266 267There are several mailing lists for people interested in keeping up-to-date 268with developments. 269 270@c ############### 271 272@enumerate 273 274@item 275The users mailing list, @samp{am-utils} is for 276 277@itemize @minus 278@item 279announcements of alpha and beta releases of am-utils 280@item 281reporting of bugs and patches 282@item 283discussions of new features for am-utils 284@item 285implementation and porting issues 286@end itemize 287 288To subscribe, visit @url{http://www.am-utils.org/} under ``Mailing 289Lists.'' After subscribing, you can post a message to this list. To 290avoid as much spam as possible, only subscribers to this list may post 291to it. 292 293Subscribers of @samp{am-utils} are most helpful if they have the time 294and resources to test new and development versions of amd, on as many 295different platforms as possible. They should also be prepared to 296learn and use the GNU Autoconf, Automake, and Libtool packages, as 297needed; and of course, become familiar with the complex code in the 298am-utils package. In other words, subscribers on this list should 299hopefully be able to contribute meaningfully to the development of 300amd. 301 302Note that this @samp{am-utils} list used to be called @samp{amd-dev} 303before January 1st, 2004. Please use the new name, @samp{am-utils}. 304 305@item 306The announcements mailing list, @samp{am-utils-announce} is for 307announcements only (mostly new releases). To subscribe, visit 308@url{http://www.am-utils.org/} under ``Mailing Lists.'' 309This list is read-only: only am-utils developers may post to it. 310 311@item 312We distribute nightly CVS snapshots in 313@url{ftp://ftp.am-utils.org/pub/am-utils/snapshots/daily/}. If you 314like to get email notices of commits to the am-utils CVS repository, 315subscribe to the CVS logs mailing list, @samp{am-utils-cvs} at 316@url{http://www.am-utils.org/} under ``Mailing Lists.'' 317 318@item 319The older list which was used to user discussions, @samp{amd-workers}, 320is defunct as of January 2004. (Its last address was 321@email{amd-workers AT majordomo.glue.umd.edu}.) Don't use 322@samp{amd-workers}: use the newer, more active @samp{am-utils} list. 323 324@item 325For completeness, there's a developers-only closed list called 326@samp{am-utils-developers} (see @url{http://www.am-utils.org/} under 327``Mailing Lists''). 328 329@end enumerate 330 331@unnumberedsec Am-utils Book 332@cindex Am-utils book 333@cindex Amd book 334@cindex Automounter book 335@cindex book 336 337@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} wrote a 338@uref{http://www.fsl.cs.sunysb.edu/docs/amd-book/,book}, titled @i{Linux NFS and 339Automounter Administration}, ISBN 0-7821-2739-8, (Sybex, 2001). The 340book is full of details and examples that go beyond what this manual 341has. The book also covers NFS in great detail. Although the book is 342geared toward Linux users, it is general enough for any Unix 343administrator and contains specific sections for non-Linux systems. 344 345@c ################################################################ 346@node Intro, History, AddInfo, Top 347@unnumbered Introduction 348@cindex Introduction 349 350An @dfn{automounter} maintains a cache of mounted filesystems. 351Filesystems are mounted on demand when they are first referenced, 352and unmounted after a period of inactivity. 353 354@i{Amd} may be used as a replacement for Sun's automounter. The choice 355of which filesystem to mount can be controlled dynamically with 356@dfn{selectors}. Selectors allow decisions of the form ``hostname is 357@var{this},'' or ``architecture is not @var{that}.'' Selectors may be 358combined arbitrarily. @i{Amd} also supports a variety of filesystem 359types, including NFS, UFS and the novel @dfn{program} filesystem. The 360combination of selectors and multiple filesystem types allows identical 361configuration files to be used on all machines thus reducing the 362administrative overhead. 363 364@i{Amd} ensures that it will not hang if a remote server goes down. 365Moreover, @i{Amd} can determine when a remote server has become 366inaccessible and then mount replacement filesystems as and when they 367become available. 368 369@i{Amd} contains no proprietary source code and has been ported to 370numerous flavors of Unix. 371 372@c ################################################################ 373@node History, Overview, Intro, Top 374@unnumbered History 375@cindex History 376 377The @i{Amd} package has been without an official maintainer since 1992. 378Several people have stepped in to maintain it unofficially. Most 379notable were the `upl' (Unofficial Patch Level) releases of @i{Amd}, 380created by me (@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok}), and available from 381@url{ftp://ftp.am-utils.org/pub/amd/}. The last such unofficial 382release was `upl102'. 383 384Through the process of patching and aging, it was becoming more and more 385apparent that @i{Amd} was in much need of revitalizing. Maintaining 386@i{Amd} had become a difficult task. I took it upon myself to cleanup 387the code, so that it would be easier to port to new platforms, add new 388features, keep up with the many new feature requests, and deal with the 389never ending stream of bug reports. 390 391I have been working on such a release of @i{Amd} on and off since 392January of 1996. The new suite of tools is currently named "am-utils" 393(AutoMounter Utilities), in line with GNU naming conventions, befitting 394the contents of the package. In October of 1996 I had received enough 395offers to help me with this task that I decided to make a mailing list 396for this group of people. Around the same time, @i{Amd} had become a 397necessary part of my PhD thesis work, resulting in more work performed 398on am-utils. 399 400Am-utils version 6.0 was numbered with a major new release number to 401distinguish it from the last official release of @i{Amd} (5.x). Many 402new features have been added such as a GNU @code{configure} system, NFS 403Version 3, a run-time configuration file (`amd.conf'), many new ports, 404more scripts and programs, as well as numerous bug fixes. Another 405reason for the new major release number was to alert users of am-utils 406that user-visible interfaces may have changed. In order to make @i{Amd} 407work well for the next 10 years, and be easier to maintain, it was 408necessary to remove old or unused features, change various syntax files, 409etc. However, great care was taken to ensure the maximum possible 410backwards compatibility. 411 412Am-utils version 6.1 has autofs support for Linux and Solaris 2.5+ as 413@i{the} major new feature, in addition to several other minor new 414features. The autofs support is completely transparent to the 415end-user, aside from the fact that @code{/bin/pwd} now always returns 416the correct amd-ified path. The administrator can easily switch 417between NFS and autofs mounts by changing one parameter in 418@code{amd.conf}. Autofs support and maintenance was developed in 419conjunction with @email{ionut AT badula.org,Ion Badulescu}. 420 421@c ################################################################ 422@node Overview, Supported Platforms, History, Top 423@chapter Overview 424 425@i{Amd} maintains a cache of mounted filesystems. Filesystems are 426@dfn{demand-mounted} when they are first referenced, and unmounted after 427a period of inactivity. @i{Amd} may be used as a replacement for Sun's 428@b{automount}(8) program. It contains no proprietary source code and 429has been ported to numerous flavors of Unix. @xref{Supported 430Platforms}.@refill 431 432@i{Amd} was designed as the basis for experimenting with filesystem 433layout and management. Although @i{Amd} has many direct applications it 434is loaded with additional features which have little practical use. At 435some point the infrequently used components may be removed to streamline 436the production system. 437 438@i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating 439each member of a list of possible filesystem locations one by one. 440@i{Amd} checks that each cached mapping remains valid. Should a mapping be 441lost -- such as happens when a fileserver goes down -- @i{Amd} automatically 442selects a replacement should one be available. 443 444@menu 445* Fundamentals:: 446* Filesystems and Volumes:: 447* Volume Naming:: 448* Volume Binding:: 449* Operational Principles:: 450* Mounting a Volume:: 451* Automatic Unmounting:: 452* Keep-alives:: 453* Non-blocking Operation:: 454@end menu 455 456@node Fundamentals, Filesystems and Volumes, Overview, Overview 457@comment node-name, next, previous, up 458@section Fundamentals 459@cindex Automounter fundamentals 460 461The fundamental concept behind @i{Amd} is the ability to separate the 462name used to refer to a file from the name used to refer to its physical 463storage location. This allows the same files to be accessed with the 464same name regardless of where in the network the name is used. This is 465very different from placing @file{/n/hostname} in front of the pathname 466since that includes location dependent information which may change if 467files are moved to another machine. 468 469By placing the required mappings in a centrally administered database, 470filesystems can be re-organized without requiring changes to 471configuration files, shell scripts and so on. 472 473@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview 474@comment node-name, next, previous, up 475@section Filesystems and Volumes 476@cindex Filesystem 477@cindex Volume 478@cindex Fileserver 479@cindex sublink 480 481@i{Amd} views the world as a set of fileservers, each containing one or 482more filesystems where each filesystem contains one or more 483@dfn{volumes}. Here the term @dfn{volume} is used to refer to a 484coherent set of files such as a user's home directory or a @TeX{} 485distribution.@refill 486 487In order to access the contents of a volume, @i{Amd} must be told in 488which filesystem the volume resides and which host owns the filesystem. 489By default the host is assumed to be local and the volume is assumed to 490be the entire filesystem. If a filesystem contains more than one 491volume, then a @dfn{sublink} is used to refer to the sub-directory 492within the filesystem where the volume can be found. 493 494@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview 495@comment node-name, next, previous, up 496@section Volume Naming 497@cindex Volume names 498@cindex Network-wide naming 499@cindex Replicated volumes 500@cindex Duplicated volumes 501@cindex Replacement volumes 502 503Volume names are defined to be unique across the entire network. A 504volume name is the pathname to the volume's root as known by the users 505of that volume. Since this name uniquely identifies the volume 506contents, all volumes can be named and accessed from each host, subject 507to administrative controls. 508 509Volumes may be replicated or duplicated. Replicated volumes contain 510identical copies of the same data and reside at two or more locations in 511the network. Each of the replicated volumes can be used 512interchangeably. Duplicated volumes each have the same name but contain 513different, though functionally identical, data. For example, 514@samp{/vol/tex} might be the name of a @TeX{} distribution which varied 515for each machine architecture.@refill 516 517@i{Amd} provides facilities to take advantage of both replicated and 518duplicated volumes. Configuration options allow a single set of 519configuration data to be shared across an entire network by taking 520advantage of replicated and duplicated volumes. 521 522@i{Amd} can take advantage of replacement volumes by mounting them as 523required should an active fileserver become unavailable. 524 525@node Volume Binding, Operational Principles, Volume Naming, Overview 526@comment node-name, next, previous, up 527@section Volume Binding 528@cindex Volume binding 529@cindex Unix namespace 530@cindex Namespace 531@cindex Binding names to filesystems 532 533Unix implements a namespace of hierarchically mounted filesystems. Two 534forms of binding between names and files are provided. A @dfn{hard 535link} completes the binding when the name is added to the filesystem. A 536@dfn{soft link} delays the binding until the name is accessed. An 537@dfn{automounter} adds a further form in which the binding of name to 538filesystem is delayed until the name is accessed.@refill 539 540The target volume, in its general form, is a tuple (host, filesystem, 541sublink) which can be used to name the physical location of any volume 542in the network. 543 544When a target is referenced, @i{Amd} ignores the sublink element and 545determines whether the required filesystem is already mounted. This is 546done by computing the local mount point for the filesystem and checking 547for an existing filesystem mounted at the same place. If such a 548filesystem already exists then it is assumed to be functionally 549identical to the target filesystem. By default there is a one-to-one 550mapping between the pair (host, filesystem) and the local mount point so 551this assumption is valid. 552 553@node Operational Principles, Mounting a Volume, Volume Binding, Overview 554@comment node-name, next, previous, up 555@section Operational Principles 556@cindex Operational principles 557 558@i{Amd} operates by introducing new mount points into the namespace. 559These are called @dfn{automount} points. The kernel sees these 560automount points as NFS filesystems being served by @i{Amd}. Having 561attached itself to the namespace, @i{Amd} is now able to control the 562view the rest of the system has of those mount points. RPC calls are 563received from the kernel one at a time. 564 565When a @dfn{lookup} call is received @i{Amd} checks whether the name is 566already known. If it is not, the required volume is mounted. A 567symbolic link pointing to the volume root is then returned. Once the 568symbolic link is returned, the kernel will send all other requests 569direct to the mounted filesystem. 570 571If a volume is not yet mounted, @i{Amd} consults a configuration 572@dfn{mount-map} corresponding to the automount point. @i{Amd} then 573makes a runtime decision on what and where to mount a filesystem based 574on the information obtained from the map. 575 576@i{Amd} does not implement all the NFS requests; only those relevant 577to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. 578Some other calls are also implemented but most simply return an error 579code; for example @dfn{mkdir} always returns ``read-only filesystem''. 580 581@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview 582@comment node-name, next, previous, up 583@section Mounting a Volume 584@cindex Mounting a volume 585@cindex Location lists 586@cindex Alternate locations 587@cindex Mount retries 588@cindex Background mounts 589 590Each automount point has a corresponding mount map. The mount map 591contains a list of key--value pairs. The key is the name of the volume 592to be mounted. The value is a list of locations describing where the 593filesystem is stored in the network. In the source for the map the 594value would look like 595 596@display 597location1 location2 @dots{} locationN 598@end display 599 600@i{Amd} examines each location in turn. Each location may contain 601@dfn{selectors} which control whether @i{Amd} can use that location. 602For example, the location may be restricted to use by certain hosts. 603Those locations which cannot be used are ignored. 604 605@i{Amd} attempts to mount the filesystem described by each remaining 606location until a mount succeeds or @i{Amd} can no longer proceed. The 607latter can occur in three ways: 608 609@itemize @bullet 610@item 611If none of the locations could be used, or if all of the locations 612caused an error, then the last error is returned. 613 614@item 615If a location could be used but was being mounted in the background then 616@i{Amd} marks that mount as being ``in progress'' and continues with 617the next request; no reply is sent to the kernel. 618 619@item 620Lastly, one or more of the mounts may have been @dfn{deferred}. A mount 621is deferred if extra information is required before the mount can 622proceed. When the information becomes available the mount will take 623place, but in the mean time no reply is sent to the kernel. If the 624mount is deferred, @i{Amd} continues to try any remaining locations. 625@end itemize 626 627Once a volume has been mounted, @i{Amd} establishes a @dfn{volume 628mapping} which is used to satisfy subsequent requests.@refill 629 630@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview 631@comment node-name, next, previous, up 632@section Automatic Unmounting 633 634To avoid an ever increasing number of filesystem mounts, @i{Amd} removes 635volume mappings which have not been used recently. A time-to-live 636interval is associated with each mapping and when that expires the 637mapping is removed. When the last reference to a filesystem is removed, 638that filesystem is unmounted. If the unmount fails, for example the 639filesystem is still busy, the mapping is re-instated and its 640time-to-live interval is extended. The global default for this grace 641period is controlled by the @code{-w} command-line option (@pxref{-w 642Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval} 643(@pxref{dismount_interval Parameter}). It is also possible to set this 644value on a per-mount basis (@pxref{opts Option, opts, opts}). 645 646Filesystems can be forcefully timed out using the @i{Amq} command. 647@xref{Run-time Administration}. Note that on new enough systems that 648support forced unmounts, such as Linux, @i{Amd} can try to use the 649@b{umount2}(2) system call to force the unmount, if the regular 650@b{umount}(2) system call failed in a way that indicates that the 651mount point is hung or stale. @xref{forced_unmounts Parameter}. 652 653@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview 654@comment node-name, next, previous, up 655@section Keep-alives 656@cindex Keep-alives 657@cindex Server crashes 658@cindex NFS ping 659 660Use of some filesystem types requires the presence of a server on 661another machine. If a machine crashes then it is of no concern to 662processes on that machine that the filesystem is unavailable. However, 663to processes on a remote host using that machine as a fileserver this 664event is important. This situation is most widely recognized when an 665NFS server crashes and the behavior observed on client machines is that 666more and more processes hang. In order to provide the possibility of 667recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some 668filesystem types. Currently only NFS makes use of this service. 669 670The basis of the NFS keep-alive implementation is the observation that 671most sites maintain replicated copies of common system data such as 672manual pages, most or all programs, system source code and so on. If 673one of those servers goes down it would be reasonable to mount one of 674the others as a replacement. 675 676The first part of the process is to keep track of which fileservers are 677up and which are down. @i{Amd} does this by sending RPC requests to the 678servers' NFS @code{NullProc} and checking whether a reply is returned. 679While the server state is uncertain the requests are re-transmitted at 680three second intervals and if no reply is received after four attempts 681the server is marked down. If a reply is received the fileserver is 682marked up and stays in that state for 30 seconds at which time another 683NFS ping is sent. This interval is configurable and can even be 684turned off using the @i{ping} option. @xref{opts Option}. 685 686Once a fileserver is marked down, requests continue to be sent every 30 687seconds in order to determine when the fileserver comes back up. During 688this time any reference through @i{Amd} to the filesystems on that 689server fail with the error ``Operation would block''. If a replacement 690volume is available then it will be mounted, otherwise the error is 691returned to the user. 692 693@c @i{Amd} keeps track of which servers are up and which are down. 694@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and 695@c checking whether a reply is returned. If no replies are received after a 696@c short period, @i{Amd} marks the fileserver @dfn{down}. 697@c RPC requests continue to be sent so that it will notice when a fileserver 698@c comes back up. 699@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability 700@c of the NFS service that is important, not the existence of a base kernel. 701@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate 702@c filesystem is mounted if one is available. 703@c 704Although this action does not protect user files, which are unique on 705the network, or processes which do not access files via @i{Amd} or 706already have open files on the hung filesystem, it can prevent most new 707processes from hanging. 708@c 709@c With a suitable combination of filesystem management and mount-maps, 710@c machines can be protected against most server downtime. This can be 711@c enhanced by allocating boot-servers dynamically which allows a diskless 712@c workstation to be quickly restarted if necessary. Once the root filesystem 713@c is mounted, @i{Amd} can be started and allowed to mount the remainder of 714@c the filesystem from whichever fileservers are available. 715 716@node Non-blocking Operation, , Keep-alives, Overview 717@comment node-name, next, previous, up 718@section Non-blocking Operation 719@cindex Non-blocking operation 720@cindex Multiple-threaded server 721@cindex RPC retries 722 723Since there is only one instance of @i{Amd} for each automount point, 724and usually only one instance on each machine, it is important that it 725is always available to service kernel calls. @i{Amd} goes to great 726lengths to ensure that it does not block in a system call. As a last 727resort @i{Amd} will fork before it attempts a system call that may block 728indefinitely, such as mounting an NFS filesystem. Other tasks such as 729obtaining filehandle information for an NFS filesystem, are done using a 730purpose built non-blocking RPC library which is integrated with 731@i{Amd}'s task scheduler. This library is also used to implement NFS 732keep-alives (@pxref{Keep-alives}). 733 734Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it 735to complete before replying to the kernel. However, this would cause 736@i{Amd} to block waiting for a reply to be constructed. Rather than do 737this, @i{Amd} simply @dfn{drops} the call under the assumption that the 738kernel RPC mechanism will automatically retry the request. 739 740@c ################################################################ 741@node Supported Platforms, Mount Maps, Overview, Top 742@comment node-name, next, previous, up 743@chapter Supported Platforms 744@cindex Supported Platforms 745@cindex shared libraries 746@cindex NFS V.3 support 747 748@i{Am-utils} has been ported to a wide variety of machines and operating 749systems. @i{Am-utils}'s code works for little-endian and big-endian 750machines, as well as 32 bit and 64 bit architectures. Furthermore, when 751@i{Am-utils} ports to an Operating System on one architecture, it is generally 752readily portable to the same Operating System on all platforms on which 753it is available. 754 755See the @file{INSTALL} in the distribution for more specific details on 756building and/or configuring for some systems. 757 758@c ################################################################ 759@node Mount Maps, Amd Command Line Options, Supported Platforms, Top 760@comment node-name, next, previous, up 761@chapter Mount Maps 762@cindex Mount maps 763@cindex Automounter configuration maps 764@cindex Mount information 765 766@i{Amd} has no built-in knowledge of machines or filesystems. 767External @dfn{mount-maps} are used to provide the required information. 768Specifically, @i{Amd} needs to know when and under what conditions it 769should mount filesystems. 770 771The map entry corresponding to the requested name contains a list of 772possible locations from which to resolve the request. Each location 773specifies filesystem type, information required by that filesystem (for 774example the block special device in the case of UFS), and some 775information describing where to mount the filesystem (@pxref{fs Option}). A 776location may also contain @dfn{selectors} (@pxref{Selectors}).@refill 777 778@menu 779* Map Types:: 780* Key Lookup:: 781* Location Format:: 782@end menu 783 784@node Map Types, Key Lookup, Mount Maps, Mount Maps 785@comment node-name, next, previous, up 786@section Map Types 787@cindex Mount map types 788@cindex Map types 789@cindex Configuration map types 790@cindex Types of mount map 791@cindex Types of configuration map 792@cindex Determining the map type 793 794A mount-map provides the run-time configuration information to @i{Amd}. 795Maps can be implemented in many ways. Some of the forms supported by 796@i{Amd} are regular files, ndbm databases, NIS maps, the @dfn{Hesiod} 797name server, and even the password file. 798 799A mount-map @dfn{name} is a sequence of characters. When an automount 800point is created a handle on the mount-map is obtained. For each map 801type configured, @i{Amd} attempts to reference the map of the 802appropriate type. If a map is found, @i{Amd} notes the type for future 803use and deletes the reference, for example closing any open file 804descriptors. The available maps are configured when @i{Amd} is built 805and can be displayed by running the command @samp{amd -v}. 806 807When using an @i{Amd} configuration file (@pxref{Amd Configuration File}) 808and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may 809force the map used to any type. 810 811By default, @i{Amd} caches data in a mode dependent on the type of map. 812This is the same as specifying @samp{cache:=mapdefault} and selects a 813suitable default cache mode depending on the map type. The individual 814defaults are described below. The @var{cache} option can be specified 815on automount points to alter the caching behavior (@pxref{Automount 816Filesystem}).@refill 817 818The following map types have been implemented, though some are not 819available on all machines. Run the command @samp{amd -v} to obtain a 820list of map types configured on your machine. 821 822@menu 823* File maps:: 824* ndbm maps:: 825* NIS maps:: 826* NIS+ maps:: 827* Hesiod maps:: 828* Password maps:: 829* Union maps:: 830* LDAP maps:: 831* Executable maps:: 832@end menu 833 834@c ---------------------------------------------------------------- 835@node File maps, ndbm maps, Map Types, Map Types 836@comment node-name, next, previous, up 837@subsection File maps 838@cindex File maps 839@cindex Flat file maps 840@cindex File map syntactic conventions 841 842When @i{Amd} searches a file for a map entry it does a simple scan of 843the file and supports both comments and continuation lines. 844 845Continuation lines are indicated by a backslash character (@samp{\}) as 846the last character of a line in the file. The backslash, newline character 847@emph{and any leading white space on the following line} are discarded. A maximum 848line length of 2047 characters is enforced after continuation lines are read 849but before comments are stripped. Each line must end with 850a newline character; that is newlines are terminators, not separators. 851The following examples illustrate this: 852 853@example 854key valA valB; \ 855 valC 856@end example 857 858specifies @emph{three} locations, and is identical to 859 860@example 861key valA valB; valC 862@end example 863 864However, 865 866@example 867key valA valB;\ 868 valC 869@end example 870 871specifies only @emph{two} locations, and is identical to 872 873@example 874key valA valB;valC 875@end example 876 877After a complete line has been read from the file, including 878continuations, @i{Amd} determines whether there is a comment on the 879line. A comment begins with a hash (``@samp{#}'') character and 880continues to the end of the line. There is no way to escape or change 881the comment lead-in character. 882 883Note that continuation lines and comment support @dfn{only} apply to 884file maps, or ndbm maps built with the @code{mk-amd-map} program. 885 886When caching is enabled, file maps have a default cache mode of 887@code{all} (@pxref{Automount Filesystem}). 888 889@c ---------------------------------------------------------------- 890@node ndbm maps, NIS maps, File maps, Map Types 891@comment node-name, next, previous, up 892@subsection ndbm maps 893@cindex ndbm maps 894 895An ndbm map may be used as a fast access form of a file map. The program, 896@code{mk-amd-map}, converts a normal map file into an ndbm database. 897This program supports the same continuation and comment conventions that 898are provided for file maps. Note that ndbm format files may @emph{not} 899be sharable across machine architectures. The notion of speed generally 900only applies to large maps; a small map, less than a single disk block, 901is almost certainly better implemented as a file map. 902 903ndbm maps have a default cache mode of @samp{all} 904(@pxref{Automount Filesystem}). 905 906@c ---------------------------------------------------------------- 907@node NIS maps, NIS+ maps, ndbm maps, Map Types 908@comment node-name, next, previous, up 909@subsection NIS maps 910@cindex NIS (YP) maps 911 912When using NIS (formerly YP), an @i{Amd} map is implemented directly 913by the underlying NIS map. Comments and continuation lines are 914@emph{not} supported in the automounter and must be stripped when 915constructing the NIS server's database. 916 917NIS maps have a default cache mode of @code{all} (@pxref{Automount 918Filesystem}). 919 920The following rule illustrates what could be added to your NIS @file{Makefile}, 921in this case causing the @file{amd.home} map to be rebuilt: 922@example 923$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home 924 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ 925 awk '@{ \ 926 for (i = 1; i <= NF; i++) \ 927 if (i == NF) @{ \ 928 if (substr($$i, length($$i), 1) == "\\") \ 929 printf("%s", substr($$i, 1, length($$i) - 1)); \ 930 else \ 931 printf("%s\n", $$i); \ 932 @} \ 933 else \ 934 printf("%s ", $$i); \ 935 @}' | \ 936 $(MAKEDBM) - $(YPDBDIR)/amd.home; \ 937 touch $(YPTSDIR)/amd.home.time; \ 938 echo "updated amd.home"; \ 939 if [ ! $(NOPUSH) ]; then \ 940 $(YPPUSH) amd.home; \ 941 echo "pushed amd.home"; \ 942 else \ 943 : ; \ 944 fi 945@end example 946 947Here @code{$(YPTSDIR)} contains the time stamp files, and 948@code{$(YPDBDIR)} contains the dbm format NIS files. 949 950@c ---------------------------------------------------------------- 951@node NIS+ maps, Hesiod maps, NIS maps, Map Types 952@comment node-name, next, previous, up 953@subsection NIS+ maps 954@cindex NIS+ maps 955 956NIS+ maps do not support cache mode @samp{all} and, when caching is 957enabled, have a default cache mode of @samp{inc}. 958 959XXX: FILL IN WITH AN EXAMPLE. 960 961@c ---------------------------------------------------------------- 962@node Hesiod maps, Password maps, NIS+ maps, Map Types 963@comment node-name, next, previous, up 964@subsection Hesiod maps 965@cindex Hesiod maps 966 967When the map name begins with the string @samp{hesiod.} lookups are made 968using the @dfn{Hesiod} name server. The string following the dot is 969used as a name qualifier and is prepended with the key being located. 970The entire string is then resolved in the @code{automount} context, or 971the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base 972Parameter}). For example, if the key is @samp{jsp} and map name is 973@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve 974@samp{jsp.homes.automount}. 975 976Hesiod maps do not support cache mode @samp{all} and, when caching is 977enabled, have a default cache mode of @samp{inc} (@pxref{Automount 978Filesystem}). 979 980The following is an example of a @dfn{Hesiod} map entry: 981 982@example 983jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" 984njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" 985@end example 986 987@c ---------------------------------------------------------------- 988@node Password maps, Union maps, Hesiod maps, Map Types 989@comment node-name, next, previous, up 990@subsection Password maps 991@cindex Password file maps 992@cindex /etc/passwd maps 993@cindex User maps, automatic generation 994@cindex Automatic generation of user maps 995@cindex Using the password file as a map 996 997The password map support is unlike the four previous map types. When 998the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user 999name in the password file and re-arrange the home directory field to 1000produce a usable map entry. 1001 1002@i{Amd} assumes the home directory has the format 1003`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. 1004@c @footnote{This interpretation is not necessarily exactly what you want.} 1005It breaks this string into a map entry where @code{$@{rfs@}} has the 1006value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value 1007`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the 1008value @i{login}.@refill 1009 1010Thus if the password file entry was 1011 1012@example 1013/home/achilles/jsp 1014@end example 1015 1016the map entry used by @i{Amd} would be 1017 1018@example 1019rfs:=/home/achilles;rhost:=achilles;sublink:=jsp 1020@end example 1021 1022Similarly, if the password file entry was 1023 1024@example 1025/home/cc/sugar/mjh 1026@end example 1027 1028the map entry used by @i{Amd} would be 1029 1030@example 1031rfs:=/home/sugar;rhost:=sugar.cc;sublink:=mhj 1032@end example 1033 1034@c ---------------------------------------------------------------- 1035@node Union maps, LDAP maps, Password maps, Map Types 1036@comment node-name, next, previous, up 1037@subsection Union maps 1038@cindex Union file maps 1039 1040The union map support is provided specifically for use with the union 1041filesystem, @pxref{Union Filesystem}. 1042 1043It is identified by the string @samp{union:} which is followed by a 1044colon separated list of directories. The directories are read in order, 1045and the names of all entries are recorded in the map cache. Later 1046directories take precedence over earlier ones. The union filesystem 1047type then uses the map cache to determine the union of the names in all 1048the directories. 1049 1050@c ---------------------------------------------------------------- 1051@node LDAP maps, Executable maps, Union maps, Map Types 1052@comment node-name, next, previous, up 1053@subsection LDAP maps 1054@cindex LDAP maps 1055@cindex Lightweight Directory Access Protocol 1056 1057LDAP (Lightweight Directory Access Protocol) maps do not support cache 1058mode @samp{all} and, when caching is enabled, have a default cache mode 1059of @samp{inc}. 1060 1061For example, an @i{Amd} map @samp{amd.home} that looks as follows: 1062 1063@example 1064/defaults opts:=rw,intr;type:=link 1065 1066zing -rhost:=shekel \ 1067 host==shekel \ 1068 host!=shekel;type:=nfs 1069@end example 1070@noindent 1071when converted to LDAP (@pxref{amd2ldif}), will result in the following 1072LDAP database: 1073@example 1074$ amd2ldif amd.home CUCS < amd.home 1075dn: cn=amdmap timestamp, CUCS 1076cn : amdmap timestamp 1077objectClass : amdmapTimestamp 1078amdmapTimestamp: 873071363 1079 1080dn: cn=amdmap amd.home[/defaults], CUCS 1081cn : amdmap amd.home[/defaults] 1082objectClass : amdmap 1083amdmapName : amd.home 1084amdmapKey : /defaults 1085amdmapValue : opts:=rw,intr;type:=link 1086 1087dn: cn=amdmap amd.home[], CUCS 1088cn : amdmap amd.home[] 1089objectClass : amdmap 1090amdmapName : amd.home 1091amdmapKey : 1092amdmapValue : 1093 1094dn: cn=amdmap amd.home[zing], CUCS 1095cn : amdmap amd.home[zing] 1096objectClass : amdmap 1097amdmapName : amd.home 1098amdmapKey : zing 1099amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs 1100@end example 1101 1102@c ---------------------------------------------------------------- 1103@node Executable maps, , LDAP maps, Map Types 1104@comment node-name, next, previous, up 1105@subsection Executable maps 1106@cindex Executable maps 1107 1108An executable map is a dynamic map in which the keys and values for 1109the maps are generated on the fly by a program or script. The program 1110is expected to take a single parameter argument which is the key to 1111lookup. If the key is found, the program should print on stdout the 1112key-value pair that were found; if the key was not found, nothing 1113should be printed out. Below is an sample of such a map script: 1114 1115@example 1116#!/bin/sh 1117# executable map example 1118case "$1" in 1119 "/defaults" ) 1120 echo "/defaults type:=nfs;rfs:=filer" 1121 ;; 1122 "a" ) 1123 echo "a type:=nfs;fs:=/tmp" 1124 ;; 1125 "b" ) 1126 echo "b type:=link;fs:=/usr/local" 1127 ;; 1128 * ) # no match, echo nothing 1129 ;; 1130esac 1131@end example 1132 1133@xref{exec_map_timeout Parameter}. 1134 1135@c ---------------------------------------------------------------- 1136@c subsection Gdbm 1137@c ---------------------------------------------------------------- 1138@node Key Lookup, Location Format, Map Types, Mount Maps 1139@comment node-name, next, previous, up 1140@section How keys are looked up 1141@cindex Key lookup 1142@cindex Map lookup 1143@cindex Looking up keys 1144@cindex How keys are looked up 1145@cindex Wildcards in maps 1146 1147The key is located in the map whose type was determined when the 1148automount point was first created. In general the key is a pathname 1149component. In some circumstances this may be modified by variable 1150expansion (@pxref{Variable Expansion}) and prefixing. If the automount 1151point has a prefix, specified by the @var{pref} option, then that is 1152prepended to the search key before the map is searched. 1153 1154If the map cache is a @samp{regexp} cache then the key is treated as an 1155egrep-style regular expression, otherwise a normal string comparison is 1156made. 1157 1158If the key cannot be found then a @dfn{wildcard} match is attempted. 1159@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and 1160attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. 1161 1162For example, the following sequence would be checked if @file{home/dylan/dk2} was 1163being located: 1164 1165@example 1166 home/dylan/dk2 1167 home/dylan/* 1168 home/* 1169 * 1170@end example 1171 1172At any point when a wildcard is found, @i{Amd} proceeds as if an exact 1173match had been found and the value field is then used to resolve the 1174mount request, otherwise an error code is propagated back to the kernel. 1175(@pxref{Filesystem Types}).@refill 1176 1177@node Location Format, , Key Lookup, Mount Maps 1178@comment node-name, next, previous, up 1179@section Location Format 1180@cindex Location format 1181@cindex Map entry format 1182@cindex How locations are parsed 1183 1184The value field from the lookup provides the information required to 1185mount a filesystem. The information is parsed according to the syntax 1186shown below. 1187 1188@display 1189@i{location-list}: 1190 @i{location-selection} 1191 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} 1192@i{location-selection}: 1193 @i{location} 1194 @i{location-selection} @i{white-space} @i{location} 1195@i{location}: 1196 @i{location-info} 1197 @t{-}@i{location-info} 1198 @t{-} 1199@i{location-info}: 1200 @i{sel-or-opt} 1201 @i{location-info}@t{;}@i{sel-or-opt} 1202 @t{;} 1203@i{sel-or-opt}: 1204 @i{selection} 1205 @i{opt-ass} 1206@i{selection}: 1207 selector@t{==}@i{value} 1208 selector@t{!=}@i{value} 1209@i{opt-ass}: 1210 option@t{:=}@i{value} 1211@i{white-space}: 1212 space 1213 tab 1214@end display 1215 1216Note that unquoted whitespace is not allowed in a location description. 1217White space is only allowed, and is mandatory, where shown with non-terminal 1218@i{white-space}. 1219 1220A @dfn{location-selection} is a list of possible volumes with which to 1221satisfy the request. Each @dfn{location-selection} is tried 1222sequentially, until either one succeeds or all fail. This, by the 1223way, is different from the historically documented behavior, which 1224claimed (falsely, at least for last 3 years) that @i{Amd} would 1225attempt to mount all @dfn{location-selection}s in parallel and the 1226first one to succeed would be used. 1227 1228@dfn{location-selection}s are optionally separated by the @samp{||} 1229operator. The effect of this operator is to prevent use of 1230location-selections to its right if any of the location-selections on 1231its left were selected, whether or not any of them were successfully 1232mounted (@pxref{Selectors}).@refill 1233 1234The location-selection, and singleton @dfn{location-list}, 1235@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS 1236filesystem from the block special device @file{/dev/xd1g}. 1237 1238The @dfn{sel-or-opt} component is either the name of an option required 1239by a specific filesystem, or it is the name of a built-in, predefined 1240selector such as the architecture type. The value may be quoted with 1241double quotes @samp{"}, for example 1242@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the 1243value is parsed and there is no way to get a double quote into a value 1244field. Double quotes are used to get white space into a value field, 1245which is needed for the program filesystem (@pxref{Program Filesystem}).@refill 1246 1247@menu 1248* Map Defaults:: 1249* Variable Expansion:: 1250* Selectors:: 1251* Map Options:: 1252@end menu 1253 1254@node Map Defaults, Variable Expansion, Location Format, Location Format 1255@comment node-name, next, previous, up 1256@subsection Map Defaults 1257@cindex Map defaults 1258@cindex How to set default map parameters 1259@cindex Setting default map parameters 1260 1261A location beginning with a dash @samp{-} is used to specify default 1262values for subsequent locations. Any previously specified defaults in 1263the location-list are discarded. The default string can be empty in 1264which case no defaults apply. 1265 1266The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point 1267to @file{/mnt} and cause mounts to be read-only by default. Defaults 1268specified this way are appended to, and so override, any global map 1269defaults given with @samp{/defaults}). 1270 1271@c 1272@c A @samp{/defaults} value @dfn{gdef} and a location list 1273@c \begin{quote} 1274@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$ 1275@c \end{quote} 1276@c is equivalent to 1277@c \begin{quote} 1278@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$ 1279@c \end{quote} 1280@c which is equivalent to 1281@c \begin{quote} 1282@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$ 1283@c \end{quote} 1284 1285@node Variable Expansion, Selectors, Map Defaults, Location Format 1286@comment node-name, next, previous, up 1287@subsection Variable Expansion 1288@cindex Variable expansion 1289@cindex How variables are expanded 1290@cindex Pathname operators 1291@cindex Domain stripping 1292@cindex Domainname operators 1293@cindex Stripping the local domain name 1294@cindex Environment variables 1295@cindex How to access environment variables in maps 1296 1297To allow generic location specifications @i{Amd} does variable expansion 1298on each location and also on some of the option strings. Any option or 1299selector appearing in the form @code{$@dfn{var}} is replaced by the 1300current value of that option or selector. For example, if the value of 1301@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and 1302@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then 1303after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. 1304Any environment variable can be accessed in a similar way.@refill 1305 1306Two pathname operators are available when expanding a variable. If the 1307variable name begins with @samp{/} then only the last component of the 1308pathname is substituted. For example, if @code{$@{path@}} was 1309@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. 1310Similarly, if the variable name ends with @samp{/} then all but the last 1311component of the pathname is substituted. In the previous example, 1312@code{$@{path/@}} would be expanded to @samp{/foo}.@refill 1313 1314Two domain name operators are also provided. If the variable name 1315begins with @samp{.} then only the domain part of the name is 1316substituted. For example, if @code{$@{rhost@}} was 1317@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to 1318@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} 1319then only the host component is substituted. In the previous example, 1320@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill 1321 1322Variable expansion is a two phase process. Before a location is parsed, 1323all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The 1324location is then parsed, selections are evaluated and option assignments 1325recorded. If there were no selections or they all succeeded the 1326location is used and the values of the following options are expanded in 1327the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, 1328@var{remopts}, @var{mount} and @var{unmount}. 1329 1330Note that expansion of option values is done after @dfn{all} assignments 1331have been completed and not in a purely left to right order as is done 1332by the shell. This generally has the desired effect but care must be 1333taken if one of the options references another, in which case the 1334ordering can become significant. 1335 1336There are two special cases concerning variable expansion: 1337 1338@enumerate 1339@item 1340before a map is consulted, any selectors in the name received 1341from the kernel are expanded. For example, if the request from the 1342kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture 1343was @samp{vax}, the value given to @code{$@{key@}} would be 1344@samp{vax.bin}.@refill 1345 1346@item 1347the value of @code{$@{rhost@}} is expanded and normalized before the 1348other options are expanded. The normalization process strips any local 1349sub-domain components. For example, if @code{$@{domain@}} was 1350@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially 1351@samp{snow.Berkeley.EDU}, after the normalization it would simply be 1352@samp{snow}. Hostname normalization is currently done in a 1353@emph{case-dependent} manner.@refill 1354@end enumerate 1355 1356@c====================================================================== 1357@node Selectors, Map Options, Variable Expansion, Location Format 1358@comment node-name, next, previous, up 1359@subsection Selectors 1360@cindex Selectors 1361 1362Selectors are used to control the use of a location. It is possible to 1363share a mount map between many machines in such a way that filesystem 1364location, architecture and operating system differences are hidden from 1365the users. A selector of the form @samp{arch==sun3;os==sunos4} would only 1366apply on Sun-3s running SunOS 4.x. 1367 1368Selectors can be negated by using @samp{!=} instead of @samp{==}. For 1369example to select a location on all non-Vax machines the selector 1370@samp{arch!=vax} would be used. 1371 1372Selectors are evaluated left to right. If a selector fails then that 1373location is ignored. Thus the selectors form a conjunction and the 1374locations form a disjunction. If all the locations are ignored or 1375otherwise fail then @i{Amd} uses the @dfn{error} filesystem 1376(@pxref{Error Filesystem}). This is equivalent to having a location 1377@samp{type:=error} at the end of each mount-map entry.@refill 1378 1379The default value of many of the selectors listed here can be overridden 1380by an @i{Amd} command line switch or in an @i{Amd} configuration file. 1381@xref{Amd Configuration File}. 1382 1383The following selectors are currently implemented. 1384 1385@menu 1386* arch Selector Variable:: 1387* autodir Selector Variable:: 1388* byte Selector Variable:: 1389* cluster Selector Variable:: 1390* domain Selector Variable:: 1391* dollar Selector Variable:: 1392* host Selector Variable:: 1393* hostd Selector Variable:: 1394* karch Selector Variable:: 1395* os Selector Variable:: 1396* osver Selector Variable:: 1397* full_os Selector Variable:: 1398* vendor Selector Variable:: 1399 1400* key Selector Variable:: 1401* map Selector Variable:: 1402* netnumber Selector Variable:: 1403* network Selector Variable:: 1404* path Selector Variable:: 1405* wire Selector Variable:: 1406* uid Selector Variable:: 1407* gid Selector Variable:: 1408 1409* exists Selector Function:: 1410* false Selector Function:: 1411* netgrp Selector Function:: 1412* netgrpd Selector Function:: 1413* in_network Selector Function:: 1414* true Selector Function:: 1415* xhost Selector Function:: 1416@end menu 1417 1418@c ---------------------------------------------------------------- 1419@node arch Selector Variable, autodir Selector Variable, Selectors, Selectors 1420@comment node-name, next, previous, up 1421@subsubsection arch Selector Variable 1422@cindex arch Selector Variable 1423@cindex arch, mount selector 1424@cindex Mount selector; arch 1425@cindex Selector; arch 1426 1427The machine architecture which was automatically determined at compile 1428time. The architecture type can be displayed by running the command 1429@samp{amd -v}. You can override this value also using the @code{-A} 1430command line option. @xref{Supported Platforms}.@refill 1431 1432@c ---------------------------------------------------------------- 1433@node autodir Selector Variable, byte Selector Variable, arch Selector Variable, Selectors 1434@comment node-name, next, previous, up 1435@subsubsection autodir Selector Variable 1436@cindex autodir Selector Variable 1437@cindex autodir, mount selector 1438@cindex Mount selector; autodir 1439@cindex Selector; autodir 1440 1441The default directory under which to mount filesystems. This may be 1442changed by the @code{-a} command line option. @xref{fs Option}. 1443 1444@c ---------------------------------------------------------------- 1445@node byte Selector Variable, cluster Selector Variable, autodir Selector Variable, Selectors 1446@comment node-name, next, previous, up 1447@subsubsection byte Selector Variable 1448@cindex byte Selector Variable 1449@cindex byte, mount selector 1450@cindex Mount selector; byte 1451@cindex Selector; byte 1452 1453The machine's byte ordering. This is either @samp{little}, indicating 1454little-endian, or @samp{big}, indicating big-endian. One possible use 1455is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to 1456share ndbm databases, however this use can be considered a courageous 1457juggling act. 1458 1459@c ---------------------------------------------------------------- 1460@node cluster Selector Variable, domain Selector Variable, byte Selector Variable, Selectors 1461@comment node-name, next, previous, up 1462@subsubsection cluster Selector Variable 1463@cindex cluster Selector Variable 1464@cindex cluster, mount selector 1465@cindex Mount selector; cluster 1466@cindex Selector; cluster 1467 1468This is provided as a hook for the name of the local cluster. This can 1469be used to decide which servers to use for copies of replicated 1470filesystems. @code{$@{cluster@}} defaults to the value of 1471@code{$@{domain@}} unless a different value is set with the @code{-C} 1472command line option. 1473 1474@c ---------------------------------------------------------------- 1475@node domain Selector Variable, dollar Selector Variable, cluster Selector Variable, Selectors 1476@comment node-name, next, previous, up 1477@subsubsection domain Selector Variable 1478@cindex domain Selector Variable 1479@cindex domain, mount selector 1480@cindex Mount selector; domain 1481@cindex Selector; domain 1482 1483The local domain name as specified by the @code{-d} command line option. 1484@xref{host Selector Variable}. 1485 1486@c ---------------------------------------------------------------- 1487@node dollar Selector Variable, host Selector Variable, domain Selector Variable, Selectors 1488@comment node-name, next, previous, up 1489@subsubsection dollar Selector Variable 1490@cindex dollar Selector Variable 1491 1492This is a special variable, whose sole purpose is to produce a literal 1493dollar sign in the value of another variable. For example, if you have 1494a remote file system whose name is @samp{/disk$s}, you can mount it by 1495setting the remote file system variable as follows: 1496 1497@example 1498rfs:=/disk$@{dollar@}s 1499@end example 1500 1501@c ---------------------------------------------------------------- 1502@node host Selector Variable, hostd Selector Variable, dollar Selector Variable, Selectors 1503@comment node-name, next, previous, up 1504@subsubsection host Selector Variable 1505@cindex host Selector Variable 1506@cindex host, mount selector 1507@cindex Mount selector; host 1508@cindex Selector; host 1509 1510The local hostname as determined by @b{gethostname}(2). If no domain 1511name was specified on the command line and the hostname contains a 1512period @samp{.} then the string before the period is used as the host 1513name, and the string after the period is assigned to @code{$@{domain@}}. 1514For example, if the hostname is @samp{styx.doc.ic.ac.uk} then 1515@code{host} would be @samp{styx} and @code{domain} would be 1516@samp{doc.ic.ac.uk}. @code{hostd} would be 1517@samp{styx.doc.ic.ac.uk}.@refill 1518 1519@c ---------------------------------------------------------------- 1520@node hostd Selector Variable, karch Selector Variable, host Selector Variable, Selectors 1521@comment node-name, next, previous, up 1522@subsubsection hostd Selector Variable 1523@cindex hostd Selector Variable 1524@cindex hostd, mount selector 1525@cindex Mount selector; hostd 1526@cindex Selector; hostd 1527 1528This resolves to the @code{$@{host@}} and @code{$@{domain@}} 1529concatenated with a @samp{.} inserted between them if required. If 1530@code{$@{domain@}} is an empty string then @code{$@{host@}} and 1531@code{$@{hostd@}} will be identical. 1532 1533@c ---------------------------------------------------------------- 1534@node karch Selector Variable, os Selector Variable, hostd Selector Variable, Selectors 1535@comment node-name, next, previous, up 1536@subsubsection karch Selector Variable 1537@cindex karch Selector Variable 1538@cindex karch, mount selector 1539@cindex Mount selector; karch 1540@cindex Selector; karch 1541 1542This is provided as a hook for the kernel architecture. This is used on 1543SunOS 4 and SunOS 5, for example, to distinguish between different 1544@samp{/usr/kvm} volumes. @code{$@{karch@}} defaults to the ``machine'' 1545value gotten from @b{uname}(2). If the @b{uname}(2) system call is not 1546available, the value of @code{$@{karch@}} defaults to that of 1547@code{$@{arch@}}. Finally, a different value can be set with the @code{-k} 1548command line option. 1549 1550@c ---------------------------------------------------------------- 1551@node os Selector Variable, osver Selector Variable, karch Selector Variable, Selectors 1552@comment node-name, next, previous, up 1553@subsubsection os Selector Variable 1554@cindex os Selector Variable 1555@cindex os, mount selector 1556@cindex Mount selector; os 1557@cindex Selector; os 1558 1559The operating system. Like the machine architecture, this is 1560automatically determined at compile time. The operating system name can 1561be displayed by running the command @samp{amd -v}. @xref{Supported 1562Platforms}.@refill 1563 1564@c ---------------------------------------------------------------- 1565@node osver Selector Variable, full_os Selector Variable, os Selector Variable, Selectors 1566@comment node-name, next, previous, up 1567@subsubsection osver Selector Variable 1568@cindex osver Selector Variable 1569@cindex osver, mount selector 1570@cindex Mount selector; osver 1571@cindex Selector; osver 1572 1573The operating system version. 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 full_os Selector Variable, vendor Selector Variable, osver Selector Variable, Selectors 1580@comment node-name, next, previous, up 1581@subsubsection full_os Selector Variable 1582@cindex full_os Selector Variable 1583@cindex full_os, mount selector 1584@cindex Mount selector; full_os 1585@cindex Selector; full_os 1586 1587The full name of the operating system, including its version. This 1588value is automatically determined at compile time. The full operating 1589system name and version can be displayed by running the command 1590@samp{amd -v}. @xref{Supported Platforms}.@refill 1591 1592@c ---------------------------------------------------------------- 1593@node vendor Selector Variable, key Selector Variable, full_os Selector Variable, Selectors 1594@comment node-name, next, previous, up 1595@subsubsection vendor Selector Variable 1596@cindex vendor Selector Variable 1597@cindex vendor, mount selector 1598@cindex Mount selector; vendor 1599@cindex Selector; vendor 1600 1601The name of the vendor of the operating system. This value is 1602automatically determined at compile time. The name of the vendor can be 1603displayed by running the command @samp{amd -v}. @xref{Supported 1604Platforms}.@refill 1605 1606 1607@c ---------------------------------------------------------------- 1608@ifhtml 1609<HR> 1610@end ifhtml 1611@sp 3 1612The following selectors are also provided. Unlike the other selectors, 1613they vary for each lookup. Note that when the name from the kernel is 1614expanded prior to a map lookup, these selectors are all defined as empty 1615strings. 1616 1617@c ---------------------------------------------------------------- 1618@node key Selector Variable, map Selector Variable, vendor Selector Variable, Selectors 1619@comment node-name, next, previous, up 1620@subsubsection key Selector Variable 1621@cindex key Selector Variable 1622@cindex key, mount selector 1623@cindex Mount selector; key 1624@cindex Selector; key 1625 1626The name being resolved. For example, if @file{/home} is an automount 1627point, then accessing @file{/home/foo} would set @code{$@{key@}} to the 1628string @samp{foo}. The key is prefixed by the @var{pref} option set in 1629the parent mount point. The default prefix is an empty string. If the 1630prefix was @file{blah/} then @code{$@{key@}} would be set to 1631@file{blah/foo}.@refill 1632 1633@c ---------------------------------------------------------------- 1634@node map Selector Variable, netnumber Selector Variable, key Selector Variable, Selectors 1635@comment node-name, next, previous, up 1636@subsubsection map Selector Variable 1637@cindex map Selector Variable 1638@cindex map, mount selector 1639@cindex Mount selector; map 1640@cindex Selector; map 1641 1642The name of the mount map being used. 1643 1644@c ---------------------------------------------------------------- 1645@node netnumber Selector Variable, network Selector Variable, map Selector Variable, Selectors 1646@comment node-name, next, previous, up 1647@subsubsection netnumber Selector Variable 1648@cindex netnumber Selector Variable 1649@cindex netnumber, mount selector 1650@cindex Mount selector; netnumber 1651@cindex Selector; netnumber 1652 1653This selector is identical to the @samp{in_network} selector function, 1654see @ref{in_network Selector Function}. It will match either the name 1655or number of @i{any} network interface on which this host is connected 1656to. The names and numbers of all attached interfaces are available from 1657the output of @samp{amd -v}. 1658 1659@c ---------------------------------------------------------------- 1660@node network Selector Variable, path Selector Variable, netnumber Selector Variable, Selectors 1661@comment node-name, next, previous, up 1662@subsubsection network Selector Variable 1663@cindex network Selector Variable 1664@cindex network, mount selector 1665@cindex Mount selector; network 1666@cindex Selector; network 1667 1668This selector is identical to the @samp{in_network} selector function, 1669see @ref{in_network Selector Function}. It will match either the name 1670or number of @i{any} network interface on which this host is connected 1671to. The names and numbers of all attached interfaces are available from 1672the output of @samp{amd -v}. 1673 1674@c ---------------------------------------------------------------- 1675@node path Selector Variable, wire Selector Variable, network Selector Variable, Selectors 1676@comment node-name, next, previous, up 1677@subsubsection path Selector Variable 1678@cindex path Selector Variable 1679@cindex path, mount selector 1680@cindex Mount selector; path 1681@cindex Selector; path 1682 1683The full pathname of the name being resolved. For example 1684@file{/home/foo} in the example above. 1685 1686@c ---------------------------------------------------------------- 1687@node wire Selector Variable, uid Selector Variable, path Selector Variable, Selectors 1688@comment node-name, next, previous, up 1689@subsubsection wire Selector Variable 1690@cindex wire Selector Variable 1691@cindex wire, mount selector 1692@cindex Mount selector; wire 1693@cindex Selector; wire 1694 1695This selector is identical to the @samp{in_network} selector function, 1696see @ref{in_network Selector Function}. It will match either the name 1697or number of @i{any} network interface on which this host is connected 1698to. The names and numbers of all attached interfaces are available from 1699the output of @samp{amd -v}. 1700 1701@c ---------------------------------------------------------------- 1702@node uid Selector Variable, gid Selector Variable, wire Selector Variable, Selectors 1703@comment node-name, next, previous, up 1704@subsubsection uid Selector Variable 1705@cindex uid Selector Variable 1706@cindex uid, mount selector 1707@cindex Mount selector; uid 1708@cindex Selector; uid 1709 1710This selector provides the numeric effective user ID (UID) of the user 1711which last accessed an automounted path name. This simple example shows 1712how floppy mounting can be assigned only to machine owners: 1713 1714@example 1715floppy -type:=pcfs \ 1716 uid==2301;host==shekel;dev:=/dev/floppy \ 1717 uid==6712;host==titan;dev=/dev/fd0 \ 1718 uid==0;dev:=/dev/fd0c \ 1719 type:=error 1720@end example 1721 1722The example allows two machine owners to mount floppies on their 1723designated workstations, allows the root user to mount on any host, and 1724otherwise forces an error. 1725 1726@c ---------------------------------------------------------------- 1727@node gid Selector Variable, exists Selector Function, uid Selector Variable, Selectors 1728@comment node-name, next, previous, up 1729@subsubsection gid Selector Variable 1730@cindex gid Selector Variable 1731@cindex gid, mount selector 1732@cindex Mount selector; gid 1733@cindex Selector; gid 1734 1735This selector provides the numeric effective group ID (GID) of the user 1736which last accessed an automounted path name. 1737 1738@c ---------------------------------------------------------------- 1739@ifhtml 1740<HR> 1741@end ifhtml 1742@sp 2 1743The following boolean functions are selectors which take an argument 1744@i{ARG}. They return a value of true or false, and thus do not need to 1745be compared with a value. Each of these may be negated by prepending 1746@samp{!} to their name. 1747 1748@c ---------------------------------------------------------------- 1749@node exists Selector Function, false Selector Function, gid Selector Variable, Selectors 1750@comment node-name, next, previous, up 1751@subsubsection exists Selector Function 1752@cindex exists Selector Function 1753@cindex exists, boolean mount selector 1754@cindex !exists, boolean mount selector 1755@cindex Mount selector; exists 1756@cindex Selector; exists 1757 1758If the file listed by @i{ARG} exists (via @b{lstat}(2)), this function 1759evaluates to true. Otherwise it evaluates to false. 1760 1761@c ---------------------------------------------------------------- 1762@node false Selector Function, netgrp Selector Function, exists Selector Function, Selectors 1763@comment node-name, next, previous, up 1764@subsubsection false Selector Function 1765@cindex false Selector Function 1766@cindex false, boolean mount selector 1767@cindex !false, boolean mount selector 1768@cindex Mount selector; false 1769@cindex Selector; false 1770 1771Always evaluates to false. @i{ARG} is ignored. 1772 1773@c ---------------------------------------------------------------- 1774@node netgrp Selector Function, netgrpd Selector Function, false Selector Function, Selectors 1775@comment node-name, next, previous, up 1776@subsubsection netgrp Selector Function 1777@cindex netgrp Selector Function 1778@cindex netgrp, boolean mount selector 1779@cindex !netgrp, boolean mount selector 1780@cindex Mount selector; netgrp 1781@cindex Selector; netgrp 1782 1783The argument @i{ARG} of this selector is a netgroup name followed 1784optionally by a comma and a host name. If the host name is not 1785specified, it defaults to @code{$@{host@}}. If the host name (short 1786name) is a member of the netgroup, this selector evaluates to true. 1787Otherwise it evaluates to false. 1788 1789For example, suppose you have a netgroup @samp{ppp-hosts}, and for 1790reasons of performance, these have a local @file{/home} partition, 1791while all other clients on the faster network can access a shared home 1792directory. A common map to use for both might look like the 1793following: 1794 1795@example 1796home/* netgrp(ppp-hosts);type:=link;fs:=/local/$@{key@} \ 1797 !netgrp(ppp-hosts);type:=nfs;rhost:=serv1;rfs:=/remote/$@{key@} 1798@end example 1799 1800A more complex example that takes advantage of the two argument netgrp 1801mount selector is given in the following scenario. Suppose one wants 1802to mount the local scratch space from a each host under 1803@file{scratch/<hostname>} and some hosts have their scratch space in a 1804different path than others. Hosts in the netgroup @samp{apple-hosts} 1805have their scratch space in the @file{/apple} path, where hosts in the 1806netgroup @samp{cherry-hosts} have their scratch space in the 1807@file{/cherry} path. For hosts that are neither in the 1808@samp{apple-hosts} or @samp{cherry-hosts} netgroups we want to make a 1809symlink pointing to nowhere but provide a descriptive error message in 1810the link destination: 1811 1812@example 1813scratch/* netgrp(apple-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1814 rfs:="/apple" \ 1815 netgrp(cherry-hosts,$@{/key@});type:=nfs;rhost:=$@{/key@};\ 1816 rfs:="/cherry" \ 1817 type:=link;rfs:="no local partition for $@{/key@}" 1818@end example 1819 1820@c ---------------------------------------------------------------- 1821@node netgrpd Selector Function, in_network Selector Function, netgrp Selector Function, Selectors 1822@comment node-name, next, previous, up 1823@subsubsection netgrpd Selector Function 1824@cindex netgrpd Selector Function 1825@cindex netgrpd, boolean mount selector 1826@cindex !netgrpd, boolean mount selector 1827@cindex Mount selector; netgrpd 1828@cindex Selector; netgrpd 1829 1830The argument @i{ARG} of this selector is a netgroup name followed 1831optionally by a comma and a host name. If the host name is not 1832specified, it defaults to @code{$@{hostd@}}. If the host name 1833(fully-qualified name) is a member of the netgroup, this selector 1834evaluates to true. Otherwise it evaluates to false. 1835 1836The @samp{netgrpd} function uses fully-qualified host names to match 1837netgroup names, while the @samp{netgrp} function (@pxref{netgrp 1838Selector Function}) uses short host names. 1839 1840@c ---------------------------------------------------------------- 1841@node in_network Selector Function, true Selector Function, netgrpd Selector Function, Selectors 1842@comment node-name, next, previous, up 1843@subsubsection in_network Selector Function 1844@cindex in_network Selector Function 1845@cindex in_network, boolean mount selector 1846@cindex !in_network, boolean mount selector 1847@cindex Mount selector; in_network 1848@cindex Selector; in_network 1849 1850This selector matches against any network name or number with an 1851optional netmask. First, if the current host has any network interface that is 1852locally attached to the network specified in @i{ARG} (either via name or 1853number), this selector evaluates to true. 1854 1855Second, @samp{in_network} supports a network/netmask syntax such as 1856@samp{128.59.16.0/255.255.255.0}, @samp{128.59.16.0/24}, 1857@samp{128.59.16.0/0xffffff00}, or @samp{128.59.16.0/}. Using the last 1858form, @i{Amd} will match the specified network number against the 1859default netmasks of each of the locally attached interfaces. 1860 1861If the selector does not match, it evaluates to false. 1862 1863For example, suppose you have two servers that have an exportable 1864@file{/opt} that smaller clients can NFS mount. The two servers are 1865say, @samp{serv1} on network @samp{foo-net.site.com} and @samp{serv2} on 1866network @samp{123.4.5.0}. You can write a map to be used by all clients 1867that will attempt to mount the closest one as follows: 1868 1869@example 1870opt in_network(foo-net.site.com);rhost:=serv1;rfs:=/opt \ 1871 in_network(123.4.5.0);rhost:=serv2;rfs:=/opt \ 1872 rhost:=fallback-server 1873@end example 1874 1875@c ---------------------------------------------------------------- 1876@node true Selector Function, xhost Selector Function, in_network Selector Function, Selectors 1877@comment node-name, next, previous, up 1878@subsubsection true Selector Function 1879@cindex true Selector Function 1880@cindex true, boolean mount selector 1881@cindex !true, boolean mount selector 1882@cindex Mount selector; true 1883@cindex Selector; true 1884 1885Always evaluates to true. @i{ARG} is ignored. 1886 1887@c ---------------------------------------------------------------- 1888@node xhost Selector Function, , true Selector Function, Selectors 1889@comment node-name, next, previous, up 1890@subsubsection xhost Selector Function 1891@cindex xhost Selector Function 1892@cindex xhost, boolean mount selector 1893@cindex !xhost, boolean mount selector 1894@cindex Mount selector; xhost 1895@cindex Selector; xhost 1896@cindex CNAMEs 1897 1898This function compares @i{ARG} against the current hostname, similarly 1899to the @ref{host Selector Variable}. However, this function will 1900also match if @i{ARG} is a CNAME (DNS Canonical Name, or alias) for 1901the current host's name. 1902 1903@c ================================================================ 1904@node Map Options, , Selectors, Location Format 1905@comment node-name, next, previous, up 1906@subsection Map Options 1907@cindex Map options 1908@cindex Setting map options 1909 1910Options are parsed concurrently with selectors. The difference is that 1911when an option is seen the string following the @samp{:=} is 1912recorded for later use. As a minimum the @var{type} option must be 1913specified. Each filesystem type has other options which must also be 1914specified. @xref{Filesystem Types}, for details on the filesystem 1915specific options.@refill 1916 1917Superfluous option specifications are ignored and are not reported 1918as errors. 1919 1920The following options apply to more than one filesystem type. 1921 1922@menu 1923* addopts Option:: 1924* delay Option:: 1925* fs Option:: 1926* opts Option:: 1927* remopts Option:: 1928* sublink Option:: 1929* type Option:: 1930@end menu 1931 1932@node addopts Option, delay Option, Map Options, Map Options 1933@comment node-name, next, previous, up 1934@subsubsection addopts Option 1935@cindex Setting additional options on a mount location 1936@cindex Overriding or adding options to a mount 1937@cindex addopts, mount option 1938@cindex Mount option; addopts 1939 1940This option adds additional options to default options normally 1941specified in the @samp{/defaults} entry or the defaults of the key entry 1942being processed (@pxref{opts Option}). Normally when you specify 1943@samp{opts} in both the @samp{/defaults} and the map entry, the latter 1944overrides the former completely. But with @samp{addopts} it will append 1945the options and override any conflicting ones. 1946 1947@samp{addopts} also overrides the value of the @samp{remopts} option 1948(@pxref{remopts Option}), which unless specified defaults to the value 1949of @samp{opts}. 1950 1951Options which start with @samp{no} will override those with the same 1952name that do not start with @samp{no} and vice verse. Special handling 1953is given to inverted options such as @samp{soft} and @samp{hard}, 1954@samp{bg} and @samp{fg}, @samp{ro} and @samp{rw}, etc. 1955 1956For example, if the default options specified were 1957@example 1958opts:=rw,nosuid,intr,rsize=1024,wsize=1024,quota,posix 1959@end example 1960 1961and the ones specified in a map entry were 1962 1963@example 1964addopts:=grpid,suid,ro,rsize=2048,quota,nointr 1965@end example 1966 1967then the actual options used would be 1968 1969@example 1970wsize=1024,posix,grpid,suid,ro,rsize=2048,quota,nointr 1971@end example 1972 1973@node delay Option, fs Option, addopts Option, Map Options 1974@comment node-name, next, previous, up 1975@subsubsection delay Option 1976@cindex Setting a delay on a mount location 1977@cindex Delaying mounts from specific locations 1978@cindex Primary server 1979@cindex Secondary server 1980@cindex delay, mount option 1981@cindex Mount option; delay 1982 1983The delay, in seconds, before an attempt will be made to mount from the 1984current location. Auxiliary data, such as network address, file handles 1985and so on are computed regardless of this value. 1986 1987A delay can be used to implement the notion of primary and secondary 1988file servers. The secondary servers would have a delay of a few 1989seconds, thus giving the primary servers a chance to respond first. 1990 1991@node fs Option, opts Option, delay Option, Map Options 1992@comment node-name, next, previous, up 1993@subsubsection fs Option 1994@cindex Setting the local mount point 1995@cindex Overriding the default mount point 1996@cindex fs, mount option 1997@cindex Mount option; fs 1998 1999The local mount point. The semantics of this option vary between 2000filesystems. 2001 2002For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the 2003local mount point. For other filesystem types it has other meanings 2004which are described in the section describing the respective filesystem 2005type. It is important that this string uniquely identifies the 2006filesystem being mounted. To satisfy this requirement, it should 2007contain the name of the host on which the filesystem is resident and the 2008pathname of the filesystem on the local or remote host. 2009 2010The reason for requiring the hostname is clear if replicated filesystems 2011are considered. If a fileserver goes down and a replacement filesystem 2012is mounted then the @dfn{local} mount point @dfn{must} be different from 2013that of the filesystem which is hung. Some encoding of the filesystem 2014name is required if more than one filesystem is to be mounted from any 2015given host. 2016 2017If the hostname is first in the path then all mounts from a particular 2018host will be gathered below a single directory. If that server goes 2019down then the hung mount points are less likely to be accidentally 2020referenced, for example when @b{getcwd}(3) traverses the namespace to 2021find the pathname of the current directory. 2022 2023The @samp{fs} option defaults to 2024@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, 2025@samp{rhost} defaults to the local host name (@code{$@{host@}}) and 2026@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full 2027path of the requested file; @samp{/home/foo} in the example above 2028(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may 2029be changed with the @code{-a} command line option. Sun's automounter 2030defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between 2031the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins 2032with a @samp{/}.@refill 2033 2034@node opts Option, remopts Option, fs Option, Map Options 2035@comment node-name, next, previous, up 2036@subsubsection opts Option 2037@cindex Setting system mount options 2038@cindex Passing parameters to the mount system call 2039@cindex mount system call 2040@cindex mount system call flags 2041@cindex The mount system call 2042@cindex opts, mount option 2043@cindex Mount option; opts 2044 2045The options to pass to the mount system call. A leading @samp{-} is 2046silently ignored. The mount options supported generally correspond to 2047those used by @b{mount}(8) and are listed below. Some additional 2048pseudo-options are interpreted by @i{Amd} and are also listed. 2049 2050Unless specifically overridden, each of the system default mount options 2051applies. Any options not recognized are ignored. If no options list is 2052supplied the string @samp{rw,defaults} is used and all the system 2053default mount options apply. Options which are not applicable for a 2054particular operating system are silently ignored. For example, only 4.4BSD 2055is known to implement the @code{compress} and @code{spongy} options. 2056 2057@table @code 2058 2059@item acdirmax=@var{n} 2060@cindex Mount flags; acdirmax 2061Set the maximum directory attribute cache timeout to @var{n}. 2062 2063@item acdirmin=@var{n} 2064@cindex Mount flags; acdirmin 2065Set the minimum directory attribute cache timeout to @var{n}. 2066 2067@item acregmax=@var{n} 2068@cindex Mount flags; acregmax 2069Set the maximum file attribute cache timeout to @var{n}. 2070 2071@item acregmin=@var{n} 2072@cindex Mount flags; acregmin 2073Set the minimum file attribute cache timeout to @var{n}. 2074 2075@item actimeo=@var{n} 2076@cindex Mount flags; actimeo 2077Set the overall attribute cache timeout to @var{n}. 2078 2079@item auto 2080@cindex Mount flags; auto 2081@itemx ignore 2082@cindex Mount flags; ignore 2083Ignore this mount by @b{df}(1). 2084 2085@item cache 2086@cindex Mount flags; cache 2087Allow data to be cached from a remote server for this mount. 2088 2089@item closesession 2090@cindex Mount flags; closesession 2091For UDF mounts, close the session when unmounting. 2092 2093@item compress 2094@cindex Mount flags; compress 2095Use NFS compression protocol. 2096 2097@item defperm 2098@cindex Mount flags; defperm 2099Ignore the permission mode bits, and default file permissions to 0555, 2100UID 0, and GID 0. Useful for CD-ROMs formatted as ISO-9660. 2101 2102@item dev 2103@cindex Mount flags; dev 2104Allow local special devices on this filesystem. 2105 2106@item dirmask=@var{n} 2107@cindex Mount flags; dirmask 2108For PCFS mounts, specify the maximum file permissions for directories 2109in the file system. See the @samp{mask} option's description for more 2110details. The mask value of @var{n} can be specified in decimal, 2111octal, or hexadecimal. 2112 2113@item dumbtimr 2114@cindex Mount flags; dumbtimr 2115Turn off the dynamic retransmit timeout estimator. This may be useful 2116for UDP mounts that exhibit high retry rates, since it is possible that 2117the dynamically estimated timeout interval is too short. 2118 2119@item extatt 2120@cindex Mount flags; extatt 2121Enable extended attributes in ISO-9660 file systems. 2122 2123@item fsid 2124@cindex Mount flags; fsid 2125Set ID of filesystem. 2126 2127@item gens 2128@cindex Mount flags; gens 2129Enable generations in ISO-9660 file systems. Generations allow you to 2130see all versions of a given file. 2131 2132@item gmtoff=@var{n} 2133@cindex Mount flags; gmtoff 2134For UDF mounts, set the time zone offset from UTC to @var{n} seconds, 2135with positive values indicating east of the Prime Meridian. If not 2136set, the user's current time zone will be used. 2137 2138@item group=@var{n} 2139@cindex Mount flags; group 2140For PCFS and UDF mounts, set the group of the files in the file system 2141to @var{n} (which can either be a group name or a GID number). The 2142default group is the group of the directory on which the file system 2143is being mounted. 2144 2145@item grpid 2146@cindex Mount flags; grpid 2147Use BSD directory group-id semantics. 2148 2149@item int 2150@cindex Mount flags; int 2151@itemx intr 2152@cindex Mount flags; intr 2153Allow keyboard interrupts on hard mounts. 2154 2155@item lock 2156@cindex Mount flags; lock 2157Use the NFS locking protocol (default) 2158 2159@item longname 2160@cindex Mount Flags; longname 2161For PCFS mounts, force Win95 long names. 2162 2163@item mask=@var{n} 2164@cindex Mount flags; mask 2165For PCFS mounts, specify the maximum file permissions for files in the 2166file system. For example, a mask of 755 specifies that, by default, 2167the owner should have read, write, and execute permissions for files, 2168but others should only have read and execute permissions. Only the 2169nine low-order bits of mask are used. The default mask is taken from 2170the directory on which the file system is being mounted. The mask 2171value of @var{n} can be specified in decimal, octal, or hexadecimal. 2172 2173@item multi 2174@cindex Mount flags; multi 2175Perform multi-component lookup on files. 2176 2177@item maxgroups 2178@cindex Mount flags; maxgroups 2179Set the maximum number of groups to allow for this mount. 2180 2181@item nfsv3 2182@cindex Mount flags; nfsv3 2183Use NFS Version 3 for this mount. 2184 2185@item noac 2186@cindex Mount flags; noac 2187Turn off the attribute cache. 2188 2189@item noauto 2190@cindex Mount flags; noauto 2191This option is used by the mount command in @samp{/etc/fstab} or 2192@samp{/etc/vfstab} and means not to mount this file system when mount -a 2193is used. 2194 2195@item nocache 2196@cindex Mount flags; nocache 2197Do not allow data to be cached from a remote server for this 2198mount. 2199 2200@item nocasetrans 2201@cindex Mount flags; nocasetrans 2202Don't do case translation. Useful for CD-ROMS formatted as 2203ISO-9660. 2204 2205@item noconn 2206@cindex Mount flags; noconn 2207Don't make a connection on datagram transports. 2208 2209@item nocto 2210@cindex Mount flags; nocto 2211No close-to-open consistency. 2212 2213@item nodefperm 2214@cindex Mount flags; nodefperm 2215Do not ignore the permission mode bits. Useful for CD-ROMS formatted as 2216ISO-9660. 2217 2218@item nodev 2219@cindex Mount flags; nodev 2220@itemx nodevs 2221@cindex Mount flags; nodevs 2222Don't allow local special devices on this filesystem. 2223 2224@item noexec 2225@cindex Mount flags; noexec 2226Don't allow program execution. 2227 2228@item noint 2229@cindex Mount flags; noint 2230Do not allow keyboard interrupts for this mount 2231 2232@item nojoliet 2233@cindex Mount flags; nojoliet 2234Turn off the Joliet extensions. Useful for CD-ROMS formatted as ISO-9660. 2235 2236@item nolock 2237@cindex Mount flags; nolock 2238Do not use the NFS locking protocol 2239 2240@item nomnttab 2241@cindex Mount flags; nomnttab 2242This option is used internally to tell Amd that a Solaris 8 system using 2243mntfs is in use. 2244 2245@item norrip 2246@cindex Mount flags; norrip 2247Turn off using of the Rock Ridge Interchange Protocol (RRIP) extensions 2248to ISO-9660. 2249 2250@item nosub 2251@cindex Mount flags; nosub 2252Disallow mounts beneath this mount. 2253 2254@item nosuid 2255@cindex Mount flags; nosuid 2256Don't allow set-uid or set-gid executables on this filesystem. 2257 2258@item noversion 2259@cindex Mount flags; noversion 2260Strip the extension @samp{;#} from the version string of files recorded 2261on an ISO-9660 CD-ROM. 2262 2263@item nowin95 2264@cindex Mount Flags; nowin95 2265For PCFS mounts, completely ignore Win95 entries. 2266 2267@item optionstr 2268@cindex Mount flags; optionstr 2269Under Solaris 8, provide the kernel a string of options to parse and 2270show as part of the special in-kernel mount file system. 2271 2272@item overlay 2273@cindex Mount flags; overlay 2274Overlay this mount on top of an existing mount, if any. 2275 2276@item pgthresh=@var{n} 2277@cindex Mount flags; pgthresh 2278Set the paging threshold to @var{n} kilobytes. 2279 2280@item port=@var{n} 2281@cindex Mount flags; port 2282Set the NFS port to @var{n}. 2283 2284@item posix 2285@cindex Mount flags; posix 2286Turn on POSIX static pathconf for mounts. 2287 2288@item private 2289@cindex Mount flags; private 2290Use local locking instead of the NLM protocol, useful for IRIX 6 only. 2291 2292@item proplist 2293@cindex Mount flags; proplist 2294Support property lists (ACLs) for this mount, useful primarily for Tru64 2295UNIX. 2296 2297@item proto=@var{s} 2298@cindex Mount flags; proto 2299Use transport protocol @var{s} for NFS (can be @code{"tcp"} or @code{"udp"}). 2300 2301@item quota 2302@cindex Mount flags; quota 2303Enable quota checking on this mount. 2304 2305@item rdonly 2306@cindex Mount flags; rdonly 2307@itemx ro 2308@cindex Mount flags; ro 2309Mount this filesystem readonly. 2310 2311@item resvport 2312@cindex Mount flags; resvport 2313Use a reserved port (smaller than 1024) for remote NFS mounts. Most 2314systems assume that, but some allow for mounts to occur on non-reserved 2315ports. This causes problems when such a system tries to NFS mount one 2316that requires reserved ports. It is recommended that this option always 2317be on. 2318 2319@item retrans=@i{n} 2320@cindex Mount flags; retrans 2321The number of NFS retransmits made before a user error is generated by a 2322@samp{soft} mounted filesystem, and before a @samp{hard} mounted 2323filesystem reports @samp{NFS server @dfn{yoyo} not responding still 2324trying}. 2325 2326@item retry 2327@cindex Mount flags; retry 2328Set the NFS retry counter. 2329 2330@item rrcaseins 2331@cindex Mount flags; rrcaseins 2332Enable the Rock Ridge Interchange Protocol (RRIP) case insensitive extensions. 2333Useful for CD-ROMS formatted as ISO-9660. 2334 2335@item rrip 2336@cindex Mount flags; rrip 2337Uses the Rock Ridge Interchange Protocol (RRIP) extensions to ISO-9660. 2338 2339@item rsize=@var{n} 2340@cindex Mount flags; rsize 2341The NFS read packet size. You may need to set this if you are using 2342NFS/UDP through a gateway or a slow link. 2343 2344@item rw 2345@cindex Mount flags; rw 2346Allow reads and writes on this filesystem. 2347 2348@item sessionnr=@var{n} 2349@cindex Mount Flags; sessionnr 2350For multisession UDF mounts, use session number @var{n} when mounting. 2351 2352@item shortname 2353@cindex Mount Flags; longname 2354For PCFS mounts, force old DOS short names only. 2355 2356@item soft 2357@cindex Mount flags; soft 2358Give up after @dfn{retrans} retransmissions. 2359 2360@item spongy 2361@cindex Mount flags; spongy 2362Like @samp{soft} for status requests, and @samp{hard} for data transfers. 2363 2364@item suid 2365@cindex Mount flags; suid 2366Allow set-uid programs on this mount. 2367 2368@item symttl 2369@cindex Mount flags; symttl 2370Turn off the symbolic link cache time-to-live. 2371 2372@item sync 2373@cindex Mount flags; sync 2374Perform synchronous filesystem operations on this mount. 2375 2376@item tcp 2377@cindex Mount flags; tcp 2378Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not 2379support TCP/IP mounts. 2380 2381@item timeo=@var{n} 2382@cindex Mount flags; timeo 2383The NFS timeout, in tenth-seconds, before a request is retransmitted. 2384 2385@item user=@var{n} 2386@cindex Mount flags; user 2387For PCFS and UDF mounts, set the owner of the files in the file system 2388to @var{n} (which can either be a user name or a UID number). The 2389default owner is the owner of the directory on which the file system 2390is being mounted. 2391 2392@item vers=@var{n} 2393@cindex Mount flags; vers 2394Use NFS protocol version number @var{n} (can be 2 or 3). 2395 2396@item wsize=@var{n} 2397@cindex Mount flags; wsize 2398The NFS write packet size. You may need to set this if you are using 2399NFS/UDP through a gateway or a slow link. 2400 2401@end table 2402 2403The following options are implemented by @i{Amd}, rather than being 2404passed to the kernel. 2405 2406@table @code 2407 2408@item nounmount 2409@cindex Mount flags; nounmount 2410Configures the mount so that its time-to-live will never expire. This 2411is the default for non-network based filesystem types (such as 2412mounting local disks, floppies, and CD-ROMs). See also the related 2413@i{unmount} option. 2414@c 2415@c Implementation broken: 2416 2417@item ping=@var{n} 2418@cindex Mount flags; ping 2419The interval, in seconds, between keep-alive pings. When four 2420consecutive pings have failed the mount point is marked as hung. This 2421interval defaults to 30 seconds; if the ping interval is set to zero, 2422@i{Amd} will use the default 30-second interval. If the interval is 2423set to -1 (or any other negative value), no pings are sent and the 2424host is assumed to be always up, which can cause unmounts to hang See 2425the @i{softlookup} option for a better alternative. Turning pings off 2426can be useful in NFS-HA (High-Availability) sites where the NFS 2427service rarely goes down. Setting the ping value to a large value can 2428reduce the amount of NFS_NULL chatter on your network considerably, 2429especially in large sites. 2430 2431Note that if you have multiple @i{Amd} entries using the same file 2432server, and each entry sets a different value of N, then each time Amd 2433mounts a new entry, the ping value will be re-evaluated (and updated, 2434turned off, or turned back on as needed). Finally, note that NFS_NULL 2435pings are sent for both UDP and TCP mounts, because even a hung TCP 2436mount can cause user processes to hang. 2437 2438@item public 2439@cindex Mount flags; public 2440Use WebNFS multi-component lookup on the public file handle instead of 2441the mount protocol to obtain NFS file handles, as documented in the 2442WebNFS Client Specification, RFC 2054. This means that @i{Amd} will not 2443attempt to contact the remote portmapper or remote mountd daemon, and 2444will only connect to the well-known NFS port 2049 or the port specified 2445with the @i{port} mount option, thus making it easier to use NFS through 2446a firewall. 2447 2448@item retry=@var{n} 2449@cindex Mount flags; retry=@var{n} 2450The number of times to retry the mount system call. 2451 2452@item softlookup 2453@cindex Mount flags; softlookup 2454Configures @i{Amd}'s behavior with respect to already-mounted shares from 2455NFS fileservers that are unreachable. If softlookup is specified, 2456trying to access such a share will result in an error (EIO, which is 2457changed from the ENOENT 6.0 used to return). If it is not specified, a 2458regular symlink is provided and the access will probably hang 2459in the NFS filesystem. 2460 2461The default behavior depends on whether the mount is 'soft' or 'hard'; 2462softlookup can be used to change this default. This is changed from 6.0 2463which always behaved as if softlookup was specified. 2464 2465@item unmount 2466@cindex Mount flags; unmount 2467Configures the mount so that its time-to-live will indeed expire (and 2468thus may be automatically unmounted). This is also the default for 2469network-based filesystem types (e.g., NFS). This option is useful for 2470removable local media such as CD-ROMs, USB drives, etc. so they can 2471expire when not in use, and get unmounted (such drives can get work 2472out when they keep spinning). See also the related @i{nounmount} 2473option. 2474 2475@item utimeout=@var{n} 2476@cindex Mount flags; utimeout=@var{n} 2477The interval, in seconds, that looked up and mounted map entries are 2478cached. After that period of time, @i{Amd} will attempt to unmount 2479the entries. If, however, the unmount fails (with EBUSY), then 2480@i{Amd} will extend the mount's time-to-live by the @i{utimeout} value 2481before the next unmount attempt is made. In fact the interval is 2482extended before the unmount is attempted, to avoid thrashing. The 2483default value is 120 seconds (two minutes) or as set by the @code{-w} 2484command line option. 2485 2486@item xlatecookie 2487@cindex Mount flags; xlatecookie 2488Translate directory cookies between 32-long and 64-long lengths. 2489 2490@end table 2491 2492@node remopts Option, sublink Option, opts Option, Map Options 2493@comment node-name, next, previous, up 2494@subsubsection remopts Option 2495@cindex Setting system mount options for non-local networks 2496@cindex remopts, mount option 2497@cindex Mount option; remopts 2498 2499This option has the same use as @code{$@{opts@}} but applies only when 2500the remote host is on a non-local network. For example, when using NFS 2501across a gateway it is often necessary to use smaller values for the 2502data read and write sizes. This can simply be done by specifying the 2503small values in @var{remopts}. When a non-local host is accessed, the 2504smaller sizes will automatically be used. 2505 2506@i{Amd} determines whether a host is local by examining the network 2507interface configuration at startup. Any interface changes made after 2508@i{Amd} has been started will not be noticed. The likely effect will 2509be that a host may incorrectly be declared non-local. 2510 2511Unless otherwise set, the value of @code{$@{remopts@}} is the same as 2512the value of @code{$@{opts@}}. 2513 2514@node sublink Option, type Option, remopts Option, Map Options 2515@comment node-name, next, previous, up 2516@subsubsection sublink Option 2517@cindex Setting the sublink option 2518@cindex sublink, mount option 2519@cindex Mount option; sublink 2520 2521The subdirectory within the mounted filesystem to which the reference 2522should point. This can be used to prevent duplicate mounts in cases 2523where multiple directories in the same mounted filesystem are used. 2524 2525@node type Option, , sublink Option, Map Options 2526@comment node-name, next, previous, up 2527@subsubsection type Option 2528@cindex Setting the filesystem type option 2529@cindex type, mount option 2530@cindex Mount option; type 2531 2532The filesystem type to be used. @xref{Filesystem Types}, for a full 2533description of each type.@refill 2534 2535@c ################################################################ 2536@node Amd Command Line Options, Filesystem Types, Mount Maps, Top 2537@comment node-name, next, previous, up 2538@chapter @i{Amd} Command Line Options 2539@cindex Command line options, Amd 2540@cindex Amd command line options 2541@cindex Overriding defaults on the command line 2542 2543Many of @i{Amd}'s parameters can be set from the command line. The 2544command line is also used to specify automount points and maps. 2545 2546The general format of a command line is 2547 2548@example 2549amd [@i{options}] [@{ @i{directory} @i{map-name} [-@i{map-options}] @} ...] 2550@end example 2551 2552For each directory and map-name given or specified in the 2553@file{amd.conf} file, @i{Amd} establishes an automount point. The 2554@dfn{map-options} may be any sequence of options or 2555selectors---@pxref{Location Format}. The @dfn{map-options} apply only 2556to @i{Amd}'s mount point. 2557 2558@samp{type:=toplvl;cache:=mapdefault;fs:=$@{map@}} is the default value for the 2559map options. Default options for a map are read from a special entry in 2560the map whose key is the string @samp{/defaults}. When default options 2561are given they are prepended to any options specified in the mount-map 2562locations as explained in @ref{Map Defaults}. 2563 2564The @dfn{options} are any combination of those listed below. 2565 2566Once the command line has been parsed, the automount points are mounted. 2567The mount points are created if they do not already exist, in which case they 2568will be removed when @i{Amd} exits. 2569Finally, @i{Amd} disassociates itself from its controlling terminal and 2570forks into the background. 2571 2572Note: Even if @i{Amd} has been built with @samp{-DDEBUG} (via 2573@code{configure --enable-debug}), it will still background itself and 2574disassociate itself from the controlling terminal. To use a debugger it 2575is necessary to specify @samp{-D daemon} on the command line. 2576However, even with all of this, mounts and unmounts are performed in the 2577background, and @i{Amd} will always fork before doing them. Therefore, 2578debugging what happens closely during un/mounts is more challenging. 2579 2580@emph{All} of @i{Amd}'s command options (save @code{-F} and @code{-T}) 2581can be specified in the @file{amd.conf} file. @xref{Amd Configuration 2582File}. If @i{Amd} is invoked without any command line options, it will 2583default to using the configuration file @file{/etc/amd.conf}, if one 2584exists. 2585 2586@menu 2587* -a Option:: Automount directory. 2588* -c Option:: Cache timeout interval. 2589* -d Option:: Domain name. 2590* -k Option:: Kernel architecture. 2591* -l Option:: Log file. 2592* -n Option:: Hostname normalization. 2593* -o Option:: Operating system version. 2594* -p Option:: Output process id. 2595* -r Option:: Restart existing mounts. 2596* -t Option:: Kernel RPC timeout. 2597* -v Option:: Version information. 2598* -w Option:: Wait interval after failed unmount. 2599* -x Option:: Log options. 2600* -y Option:: NIS domain. 2601* -A Option:: Operating system Architecture. 2602* -C Option:: Cluster name. 2603* -D Option:: Debug flags. 2604* -F Option:: Amd configuration file. 2605* -H Option:: Show brief help. 2606* -O Option:: Operating system name. 2607* -S Option:: Lock executable pages in memory. 2608* -T Option:: Set tag for configuration file. 2609@end menu 2610 2611@c ---------------------------------------------------------------- 2612@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options 2613@comment node-name, next, previous, up 2614@section @code{-a} @var{directory} 2615@cindex Automount directory 2616@cindex Setting the default mount directory 2617 2618Specifies the default mount directory. This option changes the variable 2619@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, 2620some sites prefer @file{/amd} or @file{/n}. 2621 2622@example 2623amd -a /amd ... 2624@end example 2625 2626@c ---------------------------------------------------------------- 2627@node -c Option, -d Option, -a Option, Amd Command Line Options 2628@comment node-name, next, previous, up 2629@section @code{-c} @var{cache-interval} 2630@cindex Cache interval 2631@cindex Interval before a filesystem times out 2632@cindex Setting the interval before a filesystem times out 2633@cindex Changing the interval before a filesystem times out 2634 2635Selects the period, in seconds, for which a name is cached by @i{Amd}. 2636If no reference is made to the volume in this period, @i{Amd} discards 2637the volume name to filesystem mapping. 2638 2639Once the last reference to a filesystem has been removed, @i{Amd} 2640attempts to unmount the filesystem. If the unmount fails the interval 2641is extended by a further period as specified by the @samp{-w} command 2642line option or by the @samp{utimeout} mount option. 2643 2644The default @dfn{cache-interval} is 300 seconds (five minutes). 2645 2646@c ---------------------------------------------------------------- 2647@node -d Option, -k Option, -c Option, Amd Command Line Options 2648@comment node-name, next, previous, up 2649@section @code{-d} @var{domain} 2650@cindex Domain name 2651@cindex Setting the local domain name 2652@cindex Overriding the local domain name 2653 2654Specifies the host's domain. This sets the internal variable 2655@code{$@{domain@}} and affects the @code{$@{hostd@}} variable. 2656 2657If this option is not specified and the hostname already contains the 2658local domain then that is used, otherwise the default value of 2659@code{$@{domain@}} is @samp{unknown.domain}. 2660 2661For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could 2662be started as follows: 2663 2664@example 2665amd -d doc.ic.ac.uk ... 2666@end example 2667 2668@c ---------------------------------------------------------------- 2669@node -k Option, -l Option, -d Option, Amd Command Line Options 2670@comment node-name, next, previous, up 2671@section @code{-k} @var{kernel-architecture} 2672@cindex Setting the Kernel architecture 2673 2674Specifies the kernel architecture of the system. This is usually the 2675output of @samp{uname -m} (the ``machine'' value gotten from 2676@b{uname}(2)). If the @b{uname}(2) system call is not available, the 2677value of @code{$@{karch@}} defaults to that of @code{$@{arch@}}. 2678 2679The only effect of this option is to set the variable @code{$@{karch@}}. 2680 2681This option would be used as follows: 2682 2683@example 2684amd -k `arch -k` ... 2685@end example 2686 2687@c ---------------------------------------------------------------- 2688@node -l Option, -n Option, -k Option, Amd Command Line Options 2689@comment node-name, next, previous, up 2690@section @code{-l} @var{log-option} 2691@cindex Log filename 2692@cindex Setting the log file 2693@cindex Using syslog to log errors 2694@cindex syslog 2695 2696Selects the form of logging to be made. Several special @dfn{log-options} 2697are recognized. 2698 2699@enumerate 2700@item 2701If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the 2702@b{syslog}(3) mechanism. If your system supports syslog facilities, then 2703the default facility used is @samp{LOG_DAEMON}. 2704 2705@item 2706@cindex syslog facility; specifying an alternate 2707When using syslog, if you wish to change the facility, append its name 2708to the log option name, delimited by a single colon. For example, if 2709@dfn{log-options} is the string @samp{syslog:local7} then @b{Amd} will 2710log messages via @b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If 2711the facility name specified is not recognized, @i{Amd} will default to 2712@samp{LOG_DAEMON}. Note: while you can use any syslog facility 2713available on your system, it is generally a bad idea to use those 2714reserved for other services such as @samp{kern}, @samp{lpr}, 2715@samp{cron}, etc. 2716 2717@item 2718If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use 2719standard error, which is also the default target for log messages. To 2720implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} 2721driver. 2722@end enumerate 2723 2724Any other string is taken as a filename to use for logging. Log 2725messages are appended to the file if it already exists, otherwise a new 2726file is created. The file is opened once and then held open, rather 2727than being re-opened for each message. 2728 2729Normally, when long-running daemons hold an open file descriptor on a 2730log file, it is impossible to ``rotate'' the log file and compress older 2731logs on a daily basis. The daemon needs to be told to discard (via 2732@b{close}(2)) its file handle, and re-open the log file. This is done 2733using @code{amq -l} @i{log-option}. @xref{Amq -l option}. 2734 2735If the @samp{syslog} option is specified but the system does not support 2736syslog or if the named file cannot be opened or created, @i{Amd} will 2737use standard error. Error messages generated before @i{Amd} has 2738finished parsing the command line are printed on standard error. 2739 2740Since @i{Amd} tends to generate a lot of logging information (especially 2741if debugging was turned on), and due to it being an important program 2742running on the system, it is usually best to log to a separate disk 2743file. In that case @i{Amd} would be started as follows: 2744 2745@example 2746amd -l /var/log/amd ... 2747@end example 2748 2749@c ---------------------------------------------------------------- 2750@node -n Option, -o Option, -l Option, Amd Command Line Options 2751@comment node-name, next, previous, up 2752@section @code{-n} 2753@cindex Hostname normalization 2754@cindex Aliased hostnames 2755@cindex Resolving aliased hostnames 2756@cindex Normalizing hostnames 2757 2758Normalizes the remote hostname before using it. Normalization is done 2759by replacing the value of @code{$@{rhost@}} with the (generally fully 2760qualified) primary name returned by a hostname lookup. 2761 2762This option should be used if several names are used to refer to a 2763single host in a mount map. 2764 2765@c ---------------------------------------------------------------- 2766@node -o Option, -p Option, -n Option, Amd Command Line Options 2767@comment node-name, next, previous, up 2768@section @code{-o} @var{op-sys-ver} 2769@cindex Operating System version 2770@cindex Setting the Operating System version 2771 2772Overrides the compiled-in version number of the operating system, with 2773@var{op-sys-ver}. Useful when the built-in version is not desired for 2774backward compatibility reasons. For example, if the built-in version is 2775@samp{2.5.1}, you can override it to @samp{5.5.1}, and use older maps 2776that were written with the latter in mind. 2777 2778@c ---------------------------------------------------------------- 2779@node -p Option, -r Option, -o Option, Amd Command Line Options 2780@comment node-name, next, previous, up 2781@section @code{-p} 2782@cindex Process id 2783@cindex Displaying the process id 2784@cindex process id of Amd daemon 2785@cindex pid file, creating with -p option 2786@cindex Creating a pid file 2787 2788Causes @i{Amd}'s process id to be printed on standard output. 2789This can be redirected to a suitable file for use with kill: 2790 2791@example 2792amd -p > /var/run/amd.pid ... 2793@end example 2794 2795This option only has an affect if @i{Amd} is running in daemon mode. 2796If @i{Amd} is started with the @code{-D daemon} debug flag, this 2797option is ignored. 2798 2799@c ---------------------------------------------------------------- 2800@node -r Option, -t Option, -p Option, Amd Command Line Options 2801@comment node-name, next, previous, up 2802@section @code{-r} 2803@cindex Restarting existing mounts 2804@cindex Picking up existing mounts 2805 2806Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). 2807@c @dfn{This option will be made the default in the next release.} 2808 2809@c ---------------------------------------------------------------- 2810@node -t Option, -v Option, -r Option, Amd Command Line Options 2811@comment node-name, next, previous, up 2812@section @code{-t} @var{timeout.retransmit} 2813@cindex Setting Amd's RPC parameters 2814 2815Specifies the RPC @dfn{timeout} interval and the @dfn{retransmit} 2816counter used by the kernel to communicate to @i{Amd}. These are used to 2817set the @samp{timeo} and @samp{retrans} mount options, respectively. 2818The default timeout is 0.8 seconds, and the default number of 2819retransmissions is 11. 2820 2821@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 2822retries. The values of these parameters change the overall retry 2823interval. Too long an interval gives poor interactive response; too 2824short an interval causes excessive retries. 2825 2826@c ---------------------------------------------------------------- 2827@node -v Option, -w Option, -t Option, Amd Command Line Options 2828@comment node-name, next, previous, up 2829@section @code{-v} 2830@cindex Version information 2831@cindex Discovering version information 2832@cindex How to discover your version of Amd 2833 2834Print version information on standard error and then exit. The output 2835is of the form: 2836 2837@example 2838Copyright (c) 1997-1999 Erez Zadok 2839Copyright (c) 1990 Jan-Simon Pendry 2840Copyright (c) 1990 Imperial College of Science, Technology & Medicine 2841Copyright (c) 1990 The Regents of the University of California. 2842am-utils version 6.0a15 (build 61). 2843Built by ezk@@example.com on date Wed Oct 22 15:21:03 EDT 1997. 2844cpu=sparc (big-endian), arch=sun4, karch=sun4u. 2845full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun. 2846Map support for: root, passwd, union, nisplus, nis, ndbm, file, error. 2847AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit, 2848 ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error. 2849FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, udf, ufs. 2850Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13). 2851Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14). 2852Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16). 2853@end example 2854 2855The information includes the version number, number of times @i{Amd} was 2856compiled on the local system, release date and name of the release. 2857Following come the cpu type, byte ordering, and the architecture and 2858kernel architecture as @code{$@{arch@}} and @code{$@{karch@}}, 2859respectively. The next line lists the operating system full name, short 2860name, version, and vendor. These four values correspond to the 2861variables @code{$@{full_os@}}, @code{$@{os@}}, @code{$@{osver@}}, and 2862@code{$@{vendor@}}, respectively. @xref{Supported Platforms}. 2863 2864Then come a list of map types supported, filesystems internally 2865supported by @i{Amd} (AMFS), and generic filesystems available (FS). 2866Finally all known networks (if any) of this host are listed by name 2867and number. They are available via the variables 2868@code{$@{wire@}} or @code{$@{network@}}, and 2869@code{$@{netnumber@}} (@pxref{Selectors}) or the @samp{in_network} 2870selector function (@pxref{in_network Selector Function}). 2871 2872@c ---------------------------------------------------------------- 2873@node -w Option, -x Option, -v Option, Amd Command Line Options 2874@comment node-name, next, previous, up 2875@section @code{-w} @var{wait-timeout} 2876@cindex Setting the interval between unmount attempts 2877@cindex unmount attempt backoff interval 2878 2879Selects the interval in seconds between unmount attempts after the 2880initial time-to-live has expired. 2881 2882This defaults to 120 seconds (two minutes). 2883 2884@c ---------------------------------------------------------------- 2885@node -x Option, -y Option, -w Option, Amd Command Line Options 2886@comment node-name, next, previous, up 2887@section @code{-x} @var{opts} 2888@cindex Log message selection 2889@cindex Selecting specific log messages 2890@cindex How to select log messages 2891@cindex syslog priorities 2892 2893Specifies the type and verbosity of log messages. @dfn{opts} is 2894a comma separated list selected from the following options: 2895 2896@table @code 2897@item fatal 2898Fatal errors (cannot be turned off) 2899@item error 2900Non-fatal errors (cannot be turned off) 2901@item user 2902Non-fatal user errors 2903@item warn 2904Recoverable errors 2905@item warning 2906Alias for @code{warn} 2907@item info 2908Information messages 2909@item map 2910Mount map usage 2911@item stats 2912Additional statistics 2913@item all 2914All of the above 2915@item defaults 2916An alias for "fatal,error,user,warning,info". 2917@end table 2918 2919Initially a set of default logging flags is enabled. This is as if 2920@samp{-x defaults} 2921or 2922@samp{-x fatal,error,user,warning,info} 2923had been selected. The command line is 2924parsed and logging is controlled by the @code{-x} option. The very first 2925set of logging flags is saved and can not be subsequently disabled using 2926@i{Amq}. This default set of options is useful for general production 2927use.@refill 2928 2929The @samp{info} messages include details of what is mounted and 2930unmounted and when filesystems have timed out. If you want to have the 2931default set of messages without the @samp{info} messages then you simply 2932need @samp{-x noinfo}. The messages given by @samp{user} relate to 2933errors in the mount maps, so these are useful when new maps are 2934installed. The following table lists the syslog priorities used for each 2935of the message types.@refill 2936 2937@table @code 2938@item fatal 2939@samp{LOG_CRIT} 2940@item error 2941@samp{LOG_ERR} 2942@item user 2943@samp{LOG_WARNING} 2944@item warning 2945@samp{LOG_WARNING} 2946@item info 2947@samp{LOG_INFO} 2948@item debug 2949@samp{LOG_DEBUG} 2950@item map 2951@samp{LOG_DEBUG} 2952@item stats 2953@samp{LOG_INFO} 2954@end table 2955 2956The options can be prefixed by the string @samp{no} to indicate 2957that this option should be turned off. For example, to obtain all 2958but @samp{info} messages the option @samp{-x all,noinfo} would be used. 2959 2960If @i{Amd} was built with debugging enabled the @code{debug} option is 2961automatically enabled regardless of the command line options. 2962 2963@c ---------------------------------------------------------------- 2964@node -y Option, -A Option, -x Option, Amd Command Line Options 2965@comment node-name, next, previous, up 2966@section @code{-y} @var{NIS-domain} 2967@cindex NIS (YP) domain name 2968@cindex Overriding the NIS (YP) domain name 2969@cindex Setting the NIS (YP) domain name 2970@cindex YP domain name 2971 2972Selects an alternate NIS domain. This is useful for debugging and 2973cross-domain shared mounting. If this flag is specified, @i{Amd} 2974immediately attempts to bind to a server for this domain. 2975@c @i{Amd} refers to NIS maps when it starts, unless the @code{-m} option 2976@c is specified, and whenever required in a mount map. 2977 2978@c ---------------------------------------------------------------- 2979@node -A Option, -C Option, -y Option, Amd Command Line Options 2980@comment node-name, next, previous, up 2981@section @code{-A} @var{architecture} 2982@cindex Setting the operating system architecture 2983 2984Specifies the OS architecture of the system. 2985The only effect of this option is to set the variable @code{$@{arch@}}. 2986 2987This option would be used as follows: 2988 2989@example 2990amd -A i386 ... 2991@end example 2992 2993@c ---------------------------------------------------------------- 2994@node -C Option, -D Option, -A Option, Amd Command Line Options 2995@comment node-name, next, previous, up 2996@section @code{-C} @var{cluster-name} 2997@cindex Cluster names 2998@cindex Setting the cluster name 2999 3000Specifies the name of the cluster of which the local machine is a member. 3001The only effect is to set the variable @code{$@{cluster@}}. 3002The @dfn{cluster-name} is will usually obtained by running another command which uses 3003a database to map the local hostname into a cluster name. 3004@code{$@{cluster@}} can then be used as a selector to restrict mounting of 3005replicated data. 3006If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. 3007This would be used as follows: 3008 3009@example 3010amd -C `clustername` ... 3011@end example 3012 3013@c ---------------------------------------------------------------- 3014@node -D Option, -F Option, -C Option, Amd Command Line Options 3015@comment node-name, next, previous, up 3016@section @code{-D} @var{opts} 3017@cindex Debug options 3018@cindex Setting debug flags 3019 3020Controls the verbosity and coverage of the debugging trace; @dfn{opts} 3021is a comma separated list of debugging options. The @code{-D} option is 3022only available if @i{Amd} was compiled with @samp{-DDEBUG}, or 3023configured with @code{configure --enable-debug}. The memory debugging 3024facilities (@samp{mem}) are only available if @i{Amd} was compiled with 3025@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}), or configured with 3026@code{configure --enable-debug=mem}. 3027 3028The most common options to use are @samp{-D trace} and @samp{-D test} 3029(which turns on all the useful debug options). As usual, every option 3030can be prefixed with @samp{no} to turn it off. 3031 3032@table @code 3033@item all 3034all options (excluding hrtime and mtab) 3035@item defaults 3036``sensible'' default options (all--excluding hrtime, mtab, and xdrtrace) 3037@item test 3038full debug options plus mtab,nodaemon,nofork,noamq 3039@item amq 3040register @i{Amd} with the RPC portmapper, for @i{Amq} 3041@item daemon 3042enter daemon mode 3043@item fork 3044fork child worker (hlfsd only) 3045@item full 3046program trace 3047@item hrtime 3048print high resolution time stamps (only if @b{syslog}(3) is not used) 3049@item info 3050@cindex debugging hesiod resolver service 3051@cindex Hesiod; turning on RES_DEBUG 3052info service specific debugging (hesiod, nis, etc.) In the case of 3053hesiod maps, turns on the hesiod RES_DEBUG internal debugging option. 3054@item mem 3055trace memory allocations. Needs to be explicitly enabled at compile 3056time with --enable-debug=mem. 3057@item mtab 3058use local mount-table file (defaults to @file{/tmp/mtab}, @pxref{debug_mtab_file Parameter}) 3059@item readdir 3060show readdir progress 3061@item str 3062debug string munging 3063@item trace 3064trace RPC protocol and NFS mount arguments 3065@item xdrtrace 3066trace XDR routines 3067@end table 3068 3069You may also refer to the program source for a more detailed explanation 3070of the available options. 3071 3072@c ---------------------------------------------------------------- 3073@node -F Option, -H Option, -D Option, Amd Command Line Options 3074@comment node-name, next, previous, up 3075@section @code{-F} @var{conf-file} 3076@cindex Amd configuration file; specifying name 3077@cindex Amd configuration file 3078@cindex amd.conf file 3079 3080Specify an @i{Amd} configuration file @var{conf-file} to use. For a 3081description of the format and syntax, @pxref{Amd Configuration File}. 3082This configuration file is used to specify any options in lieu of typing 3083many of them on the command line. The @file{amd.conf} file includes 3084directives for every command line option @i{Amd} has, and many more that 3085are only available via the configuration file facility. The 3086configuration file specified by this option is processed after all other 3087options had been processed, regardless of the actual location of this 3088option on the command line. 3089 3090@c ---------------------------------------------------------------- 3091@node -H Option, -O Option, -F Option, Amd Command Line Options 3092@comment node-name, next, previous, up 3093@section @code{-H} 3094@cindex Displaying brief help 3095@cindex Help; showing from Amd 3096 3097Print a brief help and usage string. 3098 3099@c ---------------------------------------------------------------- 3100@node -O Option, -S Option, -H Option, Amd Command Line Options 3101@comment node-name, next, previous, up 3102@section @code{-O} @var{op-sys-name} 3103@cindex Operating System name 3104@cindex Setting the Operating System name 3105 3106Overrides the compiled-in name of the operating system, with 3107@var{op-sys-name}. Useful when the built-in name is not desired for 3108backward compatibility reasons. For example, if the build in name is 3109@samp{sunos5}, you can override it to the old name @samp{sos5}, and use 3110older maps which were written with the latter in mind. 3111 3112@c ---------------------------------------------------------------- 3113@node -S Option, -T Option, -O Option, Amd Command Line Options 3114@comment node-name, next, previous, up 3115@section @code{-S} 3116@cindex plock; using 3117@cindex mlockall; using 3118@cindex locking executable pages in memory 3119 3120Do @emph{not} lock the running executable pages of @i{Amd} into memory. 3121To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 3122or @b{mlockall}(2) 3123call lock the @i{Amd} process into memory. This way there is less 3124chance the operating system will schedule, page out, and swap the 3125@i{Amd} process as needed. This tends to improve @i{Amd}'s performance, 3126at the cost of reserving the memory used by the @i{Amd} process (making 3127it unavailable for other processes). If this behavior is not desired, 3128use the @code{-S} option. 3129 3130@c ---------------------------------------------------------------- 3131@node -T Option, , -S Option, Amd Command Line Options 3132@comment node-name, next, previous, up 3133@section @code{-T} @var{tag} 3134@cindex Tags for Amd configuration file 3135@cindex Configuration file; tags 3136 3137Specify a tag to use with @file{amd.conf}. All map entries tagged with 3138@var{tag} will be processed. Map entries that are not tagged are always 3139processed. Map entries that are tagged with a tag other than @var{tag} 3140will not be processed. 3141 3142@c ################################################################ 3143@node Filesystem Types, Amd Configuration File, Amd Command Line Options, Top 3144@comment node-name, next, previous, up 3145@chapter Filesystem Types 3146@cindex Filesystem types 3147@cindex Mount types 3148@cindex Types of filesystem 3149 3150To mount a volume, @i{Amd} must be told the type of filesystem to be 3151used. Each filesystem type typically requires additional information 3152such as the fileserver name for NFS. 3153 3154From the point of view of @i{Amd}, a @dfn{filesystem} is anything that 3155can resolve an incoming name lookup. An important feature is support 3156for multiple filesystem types. Some of these filesystems are 3157implemented in the local kernel and some on remote fileservers, whilst 3158the others are implemented internally by @i{Amd}.@refill 3159 3160The two common filesystem types are UFS and NFS. Four other user 3161accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and 3162@samp{direct}) are also implemented internally by @i{Amd} and these are 3163described below. There are two additional filesystem types internal to 3164@i{Amd} which are not directly accessible to the user (@samp{inherit} 3165and @samp{error}). Their use is described since they may still have an 3166effect visible to the user.@refill 3167 3168@menu 3169* Network Filesystem:: A single NFS filesystem. 3170* Network Host Filesystem:: NFS mount a host's entire export tree. 3171* Network Filesystem Group:: An atomic group of NFS filesystems. 3172* Unix Filesystem:: Native disk filesystem. 3173* Caching Filesystem:: Caching from remote server filesystem. 3174* CD-ROM Filesystem:: ISO9660 CD ROM. 3175* UDF Filesystem:: Universal Disk Format filesystem. 3176* Loopback Filesystem:: Local loopback-mount filesystem. 3177* Memory/RAM Filesystem:: A memory or RAM-based filesystem. 3178* Null Filesystem:: 4.4BSD's loopback-mount filesystem. 3179* Floppy Filesystem:: MS-DOS Floppy filesystem. 3180* Translucent Filesystem:: The directory merging filesystem. 3181* Shared Memory+Swap Filesystem:: Sun's tmpfs filesystem. 3182* User ID Mapping Filesystem:: 4.4BSD's umapfs filesystem. 3183* Program Filesystem:: Generic Program mounts. 3184* Symbolic Link Filesystem:: Local link. 3185* Symbolic Link Filesystem II:: Local link referencing existing filesystem. 3186* NFS-Link Filesystem:: Link if path exists, NFS otherwise. 3187* Automount Filesystem:: 3188* Direct Automount Filesystem:: 3189* Union Filesystem:: 3190* Error Filesystem:: 3191* Top-level Filesystem:: 3192* Root Filesystem:: 3193* Inheritance Filesystem:: 3194@end menu 3195 3196@c ---------------------------------------------------------------- 3197@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types 3198@comment node-name, next, previous, up 3199@section Network Filesystem (@samp{nfs}) 3200@cindex NFS 3201@cindex Mounting an NFS filesystem 3202@cindex How to mount and NFS filesystem 3203@cindex nfs, filesystem type 3204@cindex Filesystem type; nfs 3205 3206The @dfn{nfs} (@samp{type:=nfs}) filesystem type provides access to Sun's NFS. 3207 3208@noindent 3209The following options must be specified: 3210 3211@table @code 3212@cindex rhost, mount option 3213@cindex Mount option; rhost 3214@item rhost 3215the remote fileserver. This must be an entry in the hosts database. IP 3216addresses are not accepted. The default value is taken 3217from the local host name (@code{$@{host@}}) if no other value is 3218specified. 3219 3220@cindex rfs, mount option 3221@cindex Mount option; rfs 3222@item rfs 3223the remote filesystem. 3224If no value is specified for this option, an internal default of 3225@code{$@{path@}} is used. 3226@end table 3227 3228NFS mounts require a two stage process. First, the @dfn{file handle} of 3229the remote file system must be obtained from the server. Then a mount 3230system call must be done on the local system. @i{Amd} keeps a cache 3231of file handles for remote file systems. The cache entries have a 3232lifetime of a few minutes. 3233 3234If a required file handle is not in the cache, @i{Amd} sends a request 3235to the remote server to obtain it. 3236@c @i{Amd} @dfn{does not} wait for 3237@c a response; it notes that one of the locations needs retrying, but 3238@c continues with any remaining locations. When the file handle becomes 3239@c available, and assuming none of the other locations was successfully 3240@c mounted, @i{Amd} will retry the mount. This mechanism allows several 3241@c NFS filesystems to be mounted in parallel. 3242@c @footnote{The mechanism 3243@c is general, however NFS is the only filesystem 3244@c for which the required hooks have been written.} 3245@c The first one which responds with a valid file handle will be used. 3246 3247Historically, this documentation has maintained that @i{Amd} will try 3248all the locations in parallel and use the first one which responds 3249with a valid file handle. This has not been the case for quite some 3250time, however. Instead, @i{Amd} will go through each location, one by 3251one, and will only skip to the next one if the previous one either 3252fails or times out. 3253 3254@noindent 3255An NFS entry might be: 3256 3257@example 3258jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp 3259@end example 3260 3261The mount system call and any unmount attempts are always done 3262in a new task to avoid the possibility of blocking @i{Amd}. 3263 3264@c ---------------------------------------------------------------- 3265@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types 3266@comment node-name, next, previous, up 3267@section Network Host Filesystem (@samp{host}) 3268@cindex Network host filesystem 3269@cindex Mounting entire export trees 3270@cindex How to mount all NFS exported filesystems 3271@cindex host, filesystem type 3272@cindex Filesystem type; host 3273 3274@c NOTE: the current implementation of the @dfn{host} filesystem type 3275@c sometimes fails to maintain a consistent view of the remote mount tree. 3276@c This happens when the mount times out and only some of the remote mounts 3277@c are successfully unmounted. To prevent this from occurring, use the 3278@c @samp{nounmount} mount option. 3279 3280The @dfn{host} (@samp{type:=host}) filesystem allows access to the entire export tree of an 3281NFS server. The implementation is layered above the @samp{nfs} 3282implementation so keep-alives work in the same way. The only option 3283which needs to be specified is @samp{rhost} which is the name of the 3284fileserver to mount. 3285 3286The @samp{host} filesystem type works by querying the mount daemon on 3287the given fileserver to obtain its export list. @i{Amd} then obtains 3288filehandles for each of the exported filesystems. Any errors at this 3289stage cause that particular filesystem to be ignored. Finally each 3290filesystem is mounted. Again, errors are logged but ignored. One 3291common reason for mounts to fail is that the mount point does not exist. 3292Although @i{Amd} attempts to automatically create the mount point, it 3293may be on a remote filesystem to which @i{Amd} does not have write 3294permission. 3295 3296When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} 3297remounts any filesystems which had successfully been unmounted. To do 3298this @i{Amd} queries the mount daemon again and obtains a fresh copy of 3299the export list. @i{Amd} then tries to mount any exported filesystems 3300which are not currently mounted. 3301 3302Sun's automounter provides a special @samp{-hosts} map. To achieve the 3303same effect with @i{Amd} requires two steps. First a mount map must 3304be created as follows: 3305 3306@example 3307* type:=host;rhost:=$@{key@};fs:=$@{autodir@}/$@{rhost@}/root 3308@end example 3309 3310@noindent 3311and then start @i{Amd} with the following command 3312 3313@example 3314amd /net net.map 3315@end example 3316 3317@noindent 3318where @samp{net.map} is the name of map described above. Note that the 3319value of @code{$@{fs@}} is overridden in the map. This is done to avoid 3320a clash between the mount tree and any other filesystem already mounted 3321from the same fileserver. 3322 3323If different mount options are needed for different hosts then 3324additional entries can be added to the map, for example 3325 3326@example 3327host2 opts:=ro,nosuid,soft 3328@end example 3329 3330@noindent 3331would soft mount @samp{host2} read-only. 3332 3333@c ---------------------------------------------------------------- 3334@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types 3335@comment node-name, next, previous, up 3336@section Network Filesystem Group (@samp{nfsx}) 3337@cindex Network filesystem group 3338@cindex Atomic NFS mounts 3339@cindex Mounting an atomic group of NFS filesystems 3340@cindex How to mount an atomic group of NFS filesystems 3341@cindex nfsx, filesystem type 3342@cindex Filesystem type; nfsx 3343 3344The @dfn{nfsx} (@samp{type:=nfsx}) filesystem allows a group of filesystems to be mounted 3345from a single NFS server. The implementation is layered above the 3346@samp{nfs} implementation so keep-alives work in the same way. 3347 3348@emph{WARNING}: @samp{nfsx} is meant to be a ``last resort'' kind of 3349solution. It is racy and poorly supported. The authors @emph{highly} 3350recommend that other solutions be considered before relying on it. 3351 3352The options are the same as for the @samp{nfs} filesystem with one 3353difference for @samp{rfs}, as explained below. 3354 3355@noindent 3356The following options should be specified: 3357 3358@table @code 3359@item rhost 3360the remote fileserver. The default value is taken from the local 3361host name (@code{$@{host@}}) if no other value is specified. 3362 3363@item rfs 3364is a list of filesystems to mount, and must be specified. 3365The list is in the form of a comma separated strings. 3366@end table 3367 3368@noindent 3369For example: 3370 3371@example 3372pub type:=nfsx;rhost:=gould;\ 3373 rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root 3374@end example 3375 3376The first string defines the root of the tree, and is applied as a 3377prefix to the remaining members of the list which define the individual 3378filesystems. The first string is @emph{not} used as a filesystem name. 3379A serial operation is used to determine the local mount points to 3380ensure a consistent layout of a tree of mounts. 3381 3382Here, the @emph{three} filesystems, @samp{/public}, 3383@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill 3384 3385A local mount point, @code{$@{fs@}}, @emph{must} be specified. The 3386default local mount point will not work correctly in the general case. 3387A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill 3388 3389@c ---------------------------------------------------------------- 3390@node Unix Filesystem, Caching Filesystem, Network Filesystem Group, Filesystem Types 3391@comment node-name, next, previous, up 3392@section Unix Filesystem (@samp{ufs}, @samp{xfs}, or @samp{efs}) 3393@cindex Unix filesystem 3394@cindex UFS 3395@cindex XFS 3396@cindex EFS 3397@cindex Mounting a UFS filesystem 3398@cindex Mounting a local disk 3399@cindex How to mount a UFS filesystems 3400@cindex How to mount a local disk 3401@cindex Disk filesystems 3402@cindex ufs, filesystem type 3403@cindex Filesystem type; ufs 3404@cindex xfs, filesystem type 3405@cindex Filesystem type; xfs 3406@cindex efs, filesystem type 3407@cindex Filesystem type; efs 3408 3409The @dfn{ufs} (@samp{type:=ufs}) filesystem type provides access to the system's standard 3410disk filesystem---usually a derivative of the Berkeley Fast Filesystem. 3411 3412@noindent 3413The following option must be specified: 3414 3415@table @code 3416@cindex dev, mount option 3417@cindex Mount option; dev 3418@item dev 3419the block special device to be mounted. 3420@end table 3421 3422A UFS entry might be: 3423 3424@example 3425jsp host==charm;type:=ufs;dev:=/dev/sd0d;sublink:=jsp 3426@end example 3427 3428UFS is the default Unix disk-based file system, which Am-utils picks up 3429during the autoconfiguration phase. Some systems have more than one 3430type, such as IRIX, that comes with EFS (Extent File System) and XFS 3431(Extended File System). In those cases, you may explicitly set the file 3432system type, by using entries such: 3433 3434@example 3435ez1 type:=efs;dev:=/dev/xd0a 3436ez2 type:=xfs;dev:=/dev/sd3c 3437@end example 3438 3439The UFS/XFS/EFS filesystems are never timed out by default, i.e. they 3440will never be unmounted by @i{Amd}. If automatic unmounting is 3441desired, the ``unmount'' option should be added to the mount options 3442for the entry. 3443 3444@c ---------------------------------------------------------------- 3445@node Caching Filesystem, CD-ROM Filesystem, Unix Filesystem, Filesystem Types 3446@comment node-name, next, previous, up 3447@section Caching Filesystem (@samp{cachefs}) 3448@cindex Caching Filesystem 3449@cindex cachefs, filesystem type 3450@cindex Filesystem type; cachefs 3451 3452The @dfn{cachefs} (@samp{type:=cachefs}) filesystem caches files from 3453one location onto another, presumably providing faster access. It is 3454particularly useful to cache from a larger and remote (slower) NFS 3455partition to a smaller and local (faster) UFS directory. 3456 3457@noindent 3458The following options must be specified: 3459 3460@table @code 3461@cindex cachedir, mount option 3462@cindex Mount option; cachedir 3463@item cachedir 3464the directory where the cache is stored. 3465@item rfs 3466the path name to the ``back file system'' to be cached from. 3467@item fs 3468the ``front file system'' mount point to the cached files, where @i{Amd} 3469will set a symbolic link pointing to. 3470@end table 3471 3472A CacheFS entry for, say, the @file{/import} @i{Amd} mount point, might 3473be: 3474 3475@example 3476copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt 3477@end example 3478 3479Access to the pathname @file{/import/copt} will follow a symbolic link 3480to @file{/n/import/copt}. The latter is the mount point for a caching 3481file system, that caches from @file{/import/opt} to @file{/cache}. 3482 3483The cachefs filesystem is never timed out by default, i.e. it will 3484never be unmounted by @i{Amd}. If automatic unmounting is desired, the 3485``unmount'' option should be added to the mount options for the entry. 3486 3487@b{Caveats}: 3488@enumerate 3489@item This file system is currently only implemented for Solaris 2.x! 3490@item Before being used for the first time, the cache directory @i{must} be 3491initialized with @samp{cfsadmin -c @var{cachedir}}. See the manual page for 3492@b{cfsadmin}(1M) for more information. 3493@item The ``back file system'' mounted must be a complete file system, not 3494a subdirectory thereof; otherwise you will get an error ``Invalid Argument''. 3495@item If @i{Amd} aborts abnormally, the state of the cache may be 3496inconsistent, requiring running the command @file{fsck -F cachefs 3497@var{cachedir}}. Otherwise you will get the error ``No Space Left on Device''. 3498@end enumerate 3499 3500@c ---------------------------------------------------------------- 3501@node CD-ROM Filesystem, UDF Filesystem, Caching Filesystem, Filesystem Types 3502@comment node-name, next, previous, up 3503@section CD-ROM Filesystem (@samp{cdfs}) 3504@cindex CD-ROM Filesystem 3505@cindex cdfs, filesystem type 3506@cindex Filesystem type; cdfs 3507 3508The @dfn{cdfs} (@samp{type:=cdfs}) filesystem mounts a CD-ROM with an 3509ISO9660 format filesystem on it. 3510 3511@noindent 3512The following option must be specified: 3513 3514@table @code 3515@cindex dev, mount option 3516@cindex Mount option; dev 3517@item dev 3518the block special device to be mounted. 3519@end table 3520 3521Some operating systems will fail to mount read-only CDs unless the 3522@samp{ro} option is specified. A cdfs entry might be: 3523 3524@example 3525cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ 3526 os==sunos5;addopts:=ro;type:=cdfs;dev:=/dev/dsk/c0t6d0s2 3527@end example 3528 3529@c ---------------------------------------------------------------- 3530@node UDF Filesystem, Loopback Filesystem, CD-ROM Filesystem, Filesystem Types 3531@comment node-name, next, previous, up 3532@section CD-ROM Filesystem (@samp{udf}) 3533@cindex CD-ROM Filesystem 3534@cindex udf, filesystem type 3535@cindex Filesystem type; udf 3536 3537The @dfn{udf} (@samp{type:=udf}) filesystem mounts media with a 3538Universal Disk Format (UDF) filesystem on it, e.g., a video DVD. 3539 3540@noindent 3541The following option must be specified: 3542 3543@table @code 3544@cindex dev, mount option 3545@cindex Mount option; dev 3546@item dev 3547the block special device to be mounted. 3548@end table 3549 3550Some operating systems will fail to mount read-only media unless the 3551@samp{ro} option is specified. A udf entry might be: 3552 3553@example 3554udf os==sunos4;type:=udf;dev:=/dev/sr0 \ 3555 os==sunos5;addopts:=ro;type:=udf;dev:=/dev/dsk/c0t6d0s2 3556@end example 3557 3558@c ---------------------------------------------------------------- 3559@node Loopback Filesystem, Memory/RAM Filesystem, UDF Filesystem, Filesystem Types 3560@comment node-name, next, previous, up 3561@section Loopback Filesystem (@samp{lofs}) 3562@cindex Loopback Filesystem 3563@cindex lofs, filesystem type 3564@cindex Filesystem type; lofs 3565 3566The @dfn{lofs} (@samp{type:=lofs}) filesystem is also called the 3567loopback filesystem. It mounts a local directory on another, thus 3568providing mount-time binding to another location (unlike symbolic 3569links). 3570 3571The loopback filesystem is particularly useful within the context of a 3572chroot-ed directory (via @b{chroot}(2)), to provide access to 3573directories otherwise inaccessible. 3574 3575@noindent 3576The following option must be specified: 3577 3578@table @code 3579@cindex rfs, mount option 3580@cindex Mount option; rfs 3581@item rfs 3582the pathname to be mounted on top of @code{$@{fs@}}. 3583@end table 3584 3585Usually, the FTP server runs in a chroot-ed environment, for security 3586reasons. In this example, lofs is used to provide a subdirectory within 3587a user's home directory, also available for public ftp. 3588 3589@example 3590lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk 3591@end example 3592 3593@c ---------------------------------------------------------------- 3594@node Memory/RAM Filesystem, Null Filesystem, Loopback Filesystem, Filesystem Types 3595@comment node-name, next, previous, up 3596@section Memory/RAM Filesystem (@samp{mfs}) 3597@cindex Memory/RAM Filesystem 3598@cindex mfs, filesystem type 3599@cindex Filesystem type; mfs 3600 3601The @dfn{mfs} (@samp{type:=mfs}) filesystem is available in 4.4BSD, 3602Linux, and other systems. It creates a filesystem in a portion of the 3603system's memory, thus providing very fast file (volatile) access. 3604 3605XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3606 3607@c ---------------------------------------------------------------- 3608@node Null Filesystem, Floppy Filesystem, Memory/RAM Filesystem, Filesystem Types 3609@comment node-name, next, previous, up 3610@section Null Filesystem (@samp{nullfs}) 3611@cindex Null Filesystem 3612@cindex nullfs, filesystem type 3613@cindex Filesystem type; nullfs 3614 3615The @dfn{nullfs} (@samp{type:=nullfs}) filesystem is available from 4.4BSD, 3616and is very similar to the loopback filesystem, @dfn{lofs}. 3617 3618XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3619 3620@c ---------------------------------------------------------------- 3621@node Floppy Filesystem, Translucent Filesystem, Null Filesystem, Filesystem Types 3622@comment node-name, next, previous, up 3623@section Floppy Filesystem (@samp{pcfs}) 3624@cindex Floppy Filesystem 3625@cindex pcfs, filesystem type 3626@cindex Filesystem type; pcfs 3627 3628The @dfn{pcfs} (@samp{type:=pcfs}) filesystem mounts a floppy previously 3629formatted for the MS-DOS format. 3630 3631@noindent 3632The following option must be specified: 3633 3634@table @code 3635@cindex dev, mount option 3636@cindex Mount option; dev 3637@item dev 3638the block special device to be mounted. 3639@end table 3640 3641A pcfs entry might be: 3642 3643@example 3644pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ 3645 os==sunos5;type:=pcfs;dev:=/dev/diskette 3646@end example 3647 3648@c ---------------------------------------------------------------- 3649@node Translucent Filesystem, Shared Memory+Swap Filesystem, Floppy Filesystem, Filesystem Types 3650@comment node-name, next, previous, up 3651@section Translucent Filesystem (@samp{tfs}) 3652@cindex Translucent Filesystem 3653@cindex tfs, filesystem type 3654@cindex Filesystem type; tfs 3655 3656The @dfn{tfs} (@samp{type:=tfs}) filesystem is an older version of the 36574.4BSD @dfn{unionfs}. 3658 3659XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3660 3661@c ---------------------------------------------------------------- 3662@node Shared Memory+Swap Filesystem, User ID Mapping Filesystem, Translucent Filesystem, Filesystem Types 3663@comment node-name, next, previous, up 3664@section Shared Memory+Swap Filesystem (@samp{tmpfs}) 3665@cindex Shared Memory and Swap Filesystem 3666@cindex tmpfs, filesystem type 3667@cindex Filesystem type; tmpfs 3668 3669The @dfn{tmpfs} (@samp{type:=tmpfs}) filesystem shares memory between a 3670the swap device and the rest of the system. It is generally used to 3671provide a fast access @file{/tmp} directory, one that uses memory that 3672is otherwise unused. This filesystem is available in SunOS 4.x and 5.x. 3673 3674XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3675 3676@c ---------------------------------------------------------------- 3677@node User ID Mapping Filesystem, Program Filesystem, Shared Memory+Swap Filesystem, Filesystem Types 3678@comment node-name, next, previous, up 3679@section User ID Mapping Filesystem (@samp{umapfs}) 3680@cindex User ID Mapping Filesystem 3681@cindex umapfs, filesystem type 3682@cindex Filesystem type; umapfs 3683 3684The @dfn{umapfs} (@samp{type:=umapfs}) filesystem maps User IDs of file 3685ownership, and is available from 4.4BSD. 3686 3687XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET! 3688 3689@c ---------------------------------------------------------------- 3690@node Program Filesystem, Symbolic Link Filesystem, User ID Mapping Filesystem, Filesystem Types 3691@comment node-name, next, previous, up 3692@section Program Filesystem (@samp{program}) 3693@cindex Program filesystem 3694@cindex Mount a filesystem under program control 3695@cindex program, filesystem type 3696@cindex Filesystem type; program 3697 3698The @dfn{program} (@samp{type:=program}) filesystem type allows a 3699program to be run whenever a mount or unmount is required. This allows 3700easy addition of support for other filesystem types, such as MIT's 3701Remote Virtual Disk (RVD) which has a programmatic interface via the 3702commands @samp{rvdmount} and @samp{rvdunmount}. 3703 3704@noindent 3705Both of the following options must be specified: 3706 3707@table @code 3708@cindex mount, mount option 3709@cindex Mount option; mount 3710@item mount 3711the program which will perform the mount. 3712 3713@cindex unmount, mount option 3714@cindex umount, mount option 3715@cindex Mount option; unmount 3716@cindex Mount option; umount 3717@item unmount 3718@item umount 3719the program which will perform the unmount. For convenience, you may 3720use either @samp{unmount} or @samp{umount} but not both. If neither 3721is defined, @i{Amd} will default to @samp{umount $@{fs@}} (the actual 3722unmount program pathname will be automatically determined at the time 3723GNU @code{configure} runs.) 3724@end table 3725 3726The exit code from these two programs is interpreted as a Unix error 3727code. As usual, exit code zero indicates success. To execute the 3728program, @i{Amd} splits the string on whitespace to create an array of 3729substrings. Single quotes @samp{'} can be used to quote whitespace 3730if that is required in an argument. There is no way to escape or change 3731the single quote character. 3732 3733To run e.g. the program @samp{rvdmount} with a host name and filesystem as 3734arguments, it would be specified by 3735@samp{fs:=$@{autodir@}$@{path@};type:=program;mount:="/etc/rvdmount 3736rvdmount fserver $@{fs@}";unmount:="/etc/rdvumount rvdumount $@{fs@}"}. 3737 3738The first element in the array is taken as the pathname of the program 3739to execute. The other members of the array form the argument vector 3740to be passed to the program, @dfn{including argument zero}. The array 3741is exactly the same as the array passed to the execv() system call 3742(man execv for details). The split string must have at least two 3743elements. The programs are directly executed by @i{Amd}, not via a 3744shell. Therefore, if a script is to be used as a mount/umount 3745program, it @dfn{must} begin with a @code{#!} interpreter specification. 3746 3747Often, this program mount type is used for Samba mounts, where you 3748need a double slash in pathnames. However, @i{Amd} normalizes 3749sequences of slashes into one slash. Therefore, you must use an 3750escaped slash, preceded by an escaped backslash. So to get a double 3751slash in the mount command, you need the eight character sequence 3752@samp{\\\/\\\/} in your map. For example: 3753 3754@samp{mount="/sbin/mount mount -r -t smbfs -o-N,-Ihostname \\\/\\\/guest@@venus/mp3"} 3755 3756If a filesystem type is to be heavily used, it may be worthwhile adding 3757a new filesystem type into @i{Amd}, but for most uses the program 3758filesystem should suffice. 3759 3760When the program is run, standard input and standard error are inherited 3761from the current values used by @i{Amd}. Standard output is a 3762duplicate of standard error. The value specified with the @code{-l} 3763command line option has no effect on standard error. 3764 3765@i{Amd} guarantees that the mountpoint will be created before calling 3766the mount program, and that it will be removed after the umount 3767program returns success. 3768 3769@c ---------------------------------------------------------------- 3770@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types 3771@comment node-name, next, previous, up 3772@section Symbolic Link Filesystem (@samp{link}) 3773@cindex Symbolic link filesystem 3774@cindex Referencing part of the local name space 3775@cindex Mounting part of the local name space 3776@cindex How to reference part of the local name space 3777@cindex link, filesystem type 3778@cindex symlink, link filesystem type 3779@cindex Filesystem type; link 3780 3781Each filesystem type creates a symbolic link to point from the volume 3782name to the physical mount point. The @samp{link} filesystem does the 3783same without any other side effects. This allows any part of the 3784machines name space to be accessed via @i{Amd}. 3785 3786One common use for the symlink filesystem is @file{/homes} which can be 3787made to contain an entry for each user which points to their 3788(auto-mounted) home directory. Although this may seem rather expensive, 3789it provides a great deal of administrative flexibility. 3790 3791@noindent 3792The following option must be defined: 3793 3794@table @code 3795@item fs 3796The value of @var{fs} option specifies the destination of the link, as 3797modified by the @var{sublink} option. If @var{sublink} is non-null, it 3798is appended to @code{$@{fs@}}@code{/} and the resulting string is used 3799as the target. 3800@end table 3801 3802The @samp{link} filesystem can be thought of as identical to the 3803@samp{ufs} filesystem but without actually mounting anything. 3804 3805An example entry might be: 3806 3807@example 3808jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp 3809@end example 3810which would return a symbolic link pointing to @file{/home/charm/jsp}. 3811 3812@c ---------------------------------------------------------------- 3813@node Symbolic Link Filesystem II, NFS-Link Filesystem, Symbolic Link Filesystem, Filesystem Types 3814@comment node-name, next, previous, up 3815@section Symbolic Link Filesystem II (@samp{linkx}) 3816@cindex Symbolic link filesystem II 3817@cindex Referencing an existing part of the local name space 3818@cindex Mounting an existing part of the local name space 3819@cindex How to reference an existing part of the local name space 3820@cindex linkx, filesystem type 3821@cindex symlink, linkx filesystem type 3822@cindex Filesystem type; linkx 3823 3824The @dfn{linkx} (@samp{type:=linkx}) filesystem type is identical to @samp{link} with the 3825exception that the target of the link must exist. Existence is checked 3826with the @b{lstat}(2) system call. 3827 3828The @samp{linkx} filesystem type is particularly useful for wildcard map 3829entries. In this case, a list of possible targets can be given and 3830@i{Amd} will choose the first one which exists on the local machine. 3831 3832@c ---------------------------------------------------------------- 3833@node NFS-Link Filesystem, Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types 3834@comment node-name, next, previous, up 3835@section NFS-Link Filesystem (@samp{nfsl}) 3836@cindex NFS-Link filesystem II 3837@cindex Referencing an existing part of the name space if target exists 3838@cindex Mounting a remote part of the name space if target is missing 3839@cindex Symlink if target exists, NFS otherwise 3840@cindex nfsl, filesystem type 3841@cindex symlink, nfsl filesystem type 3842@cindex Filesystem type; nfsl 3843 3844The @dfn{nfsl} (@samp{type:=nfsl}) filesystem type is a combination of two others: 3845@samp{link} and @samp{nfs}. If the local host name is equal to the 3846value of @code{$@{rhost@}} @emph{and} the target pathname listed in 3847@code{$@{fs@}} exists, @samp{nfsl} will behave exactly as 3848@samp{type:=link}, and refer to the target as a symbolic link. If the 3849local host name is not equal to the value of @code{$@{rhost@}}, or if 3850the target of the link does not exist, @i{Amd} will treat it as 3851@samp{type:=nfs}, and will mount a remote pathname for it. 3852 3853The @samp{nfsl} filesystem type is particularly useful as a shorthand 3854for the more cumbersome and yet one of the most popular @i{Amd} 3855entries. For example, you can simplify all map entries that look like: 3856 3857@example 3858zing -fs:=/n/shekel/u/zing \ 3859 host!=shekel;type:=nfs;rhost:=shekel;rfs:=$@{fs@} \ 3860 host==shekel;type:=link 3861@end example 3862 3863or 3864 3865@example 3866zing -fs:=/n/shekel/u/zing \ 3867 exists($@{fs@});type:=link \ 3868 !exists($@{fs@});type:=nfs;rhost:=shekel;rfs:=$@{fs@} 3869@end example 3870 3871into a shorter form 3872 3873@example 3874zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=$@{fs@} 3875@end example 3876 3877Not just does it make the maps smaller and simpler, but it avoids 3878possible mistakes that often happen when forgetting to set up the two 3879entries (one for @samp{type:=nfs} and the other for @samp{type:=link}) 3880necessary to perform transparent mounts of existing or remote mounts. 3881 3882@c ---------------------------------------------------------------- 3883@node Automount Filesystem, Direct Automount Filesystem, NFS-Link Filesystem, Filesystem Types 3884@comment node-name, next, previous, up 3885@section Automount Filesystem (@samp{auto}) 3886@cindex Automount filesystem 3887@cindex Map cache types 3888@cindex Setting map cache parameters 3889@cindex How to set map cache parameters 3890@cindex How to start an indirect automount point 3891@cindex auto, filesystem type 3892@cindex Filesystem type; auto 3893@cindex SIGHUP signal 3894@cindex Map cache synchronizing 3895@cindex Synchronizing the map cache 3896@cindex Map cache options 3897@cindex Regular expressions in maps 3898 3899The @dfn{auto} (@samp{type:=auto}) filesystem type creates a new automount point below an 3900existing automount point. Top-level automount points appear as system 3901mount points. An automount mount point can also appear as a 3902sub-directory of an existing automount point. This allows some 3903additional structure to be added, for example to mimic the mount tree of 3904another machine. 3905 3906The following options may be specified: 3907 3908@table @code 3909@cindex cache, mount map option 3910@cindex Mount map option; cache 3911@item cache 3912specifies whether the data in this mount-map should be 3913cached. The default value is @samp{none}, in which case 3914no caching is done in order to conserve memory. 3915 3916However, better performance and reliability can be obtained by caching 3917some or all of a mount-map. 3918 3919If the cache option specifies @samp{all}, 3920the entire map is enumerated when the mount point is created. 3921 3922If the cache option specifies @samp{inc}, caching is done incrementally 3923as and when data is required. 3924Some map types do not support cache mode @samp{all}, in which case @samp{inc} 3925is used whenever @samp{all} is requested. 3926 3927Caching can be entirely disabled by using cache mode @samp{none}. 3928 3929If the cache option specifies @samp{regexp} then the entire map will be 3930enumerated and each key will be treated as an egrep-style regular 3931expression. The order in which a cached map is searched does not 3932correspond to the ordering in the source map so the regular expressions 3933should be mutually exclusive to avoid confusion. 3934 3935Each mount map type has a default cache type, usually @samp{inc}, which 3936can be selected by specifying @samp{mapdefault}. 3937 3938The cache mode for a mount map can only be selected on the command line. 3939Starting @i{Amd} with the command: 3940 3941@example 3942amd /homes hesiod.homes -cache:=inc 3943@end example 3944 3945will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name 3946server with local incremental caching of all successfully resolved names. 3947 3948All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} 3949signal and, if cache @samp{all} mode was selected, the cache will be 3950reloaded. This can be used to inform @i{Amd} that a map has been 3951updated. In addition, whenever a cache lookup fails and @i{Amd} needs 3952to examine a map, the map's modify time is examined. If the cache is 3953out of date with respect to the map then it is flushed as if a 3954@samp{SIGHUP} had been received. 3955 3956An additional option (@samp{sync}) may be specified to force @i{Amd} to 3957check the map's modify time whenever a cached entry is being used. For 3958example, an incremental, synchronized cache would be created by the 3959following command: 3960 3961@example 3962amd /homes hesiod.homes -cache:=inc,sync 3963@end example 3964 3965@item fs 3966specifies the name of the mount map to use for the new mount point. 3967 3968Arguably this should have been specified with the @code{$@{rfs@}} option but 3969we are now stuck with it due to historical accident. 3970 3971@c %If the string @samp{.} is used then the same map is used; 3972@c %in addition the lookup prefix is set to the name of the mount point followed 3973@c %by a slash @samp{/}. 3974@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. 3975@c 3976 3977@item pref 3978alters the name that is looked up in the mount map. If 3979@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended 3980to the name requested by the kernel @dfn{before} the map is 3981searched. The default prefix is the prefix of the parent map (if any) 3982with name of the auto node appended to it. That means if you want no 3983prefix you must say so in the map: @samp{pref:=null}. 3984 3985@item opts 3986Normally, @samp{auto} style maps are not browsable even if you turn on 3987directory browsability (@pxref{browsable_dirs Parameter}). To enable 3988browsing entries in @samp{auto} maps, specify @samp{opts:=browsable} 3989or @samp{opts:=fullybrowsable} in 3990the description of this map. 3991 3992@end table 3993 3994The server @samp{dylan.doc.ic.ac.uk} has two user disks: 3995@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as 3996@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since 3997@samp{/home} is already an automount point, this naming is achieved with 3998the following map entries:@refill 3999 4000@example 4001dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4002dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 4003dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 4004@end example 4005 4006@c ---------------------------------------------------------------- 4007@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types 4008@comment node-name, next, previous, up 4009@section Direct Automount Filesystem (@samp{direct}) 4010@cindex Direct automount filesystem 4011@cindex How to start a direct automount point 4012@cindex direct, filesystem type 4013@cindex Filesystem type; direct 4014 4015The @dfn{direct} (@samp{type:=direct}) filesystem is almost identical to 4016the automount filesystem. Instead of appearing to be a directory of 4017mount points, it appears as a symbolic link to a mounted filesystem. 4018The mount is done at the time the link is accessed. @xref{Automount 4019Filesystem}, for a list of required options. 4020 4021Direct automount points are created by specifying the @samp{direct} 4022filesystem type on the command line: 4023 4024@example 4025amd ... /usr/man auto.direct -type:=direct 4026@end example 4027 4028where @samp{auto.direct} would contain an entry such as: 4029 4030@example 4031usr/man -type:=nfs;rfs:=/usr/man \ 4032 rhost:=man-server1 rhost:=man-server2 4033@end example 4034 4035In this example, @samp{man-server1} and @samp{man-server2} are file 4036servers which export copies of the manual pages. Note that the key 4037which is looked up is the name of the automount point without the 4038leading @samp{/}. 4039 4040Note that the implementation of the traditional @dfn{direct} filesystem is 4041essentially a hack (pretending that the root of an NFS filesystem is a 4042symlink) and many modern operating systems get very unhappy about 4043it. For example, Linux kernel 2.4+ completely disallows it, and Solaris 40442.8 fails to unmount it when @i{Amd} shuts down. Therefore, the use of 4045the traditional @dfn{direct} filesystem is strongly discouraged; it is 4046only semi-supported, at best. 4047 4048The autofs implementations that permit direct mounts are fully 4049supported, however. That currently includes all versions of 4050Solaris. Linux autofs does NOT support direct mounts at all. 4051 4052@c ---------------------------------------------------------------- 4053@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types 4054@comment node-name, next, previous, up 4055@section Union Filesystem (@samp{union}) 4056@cindex Union filesystem 4057@cindex union, filesystem type 4058@cindex Filesystem type; union 4059 4060The @dfn{union} (@samp{type:=union}) filesystem type allows the contents of several 4061directories to be merged and made visible in a single directory. This 4062can be used to overcome one of the major limitations of the Unix mount 4063mechanism which only allows complete directories to be mounted. 4064 4065For example, supposing @file{/tmp} and @file{/var/tmp} were to be merged 4066into a new directory called @file{/mtmp}, with files in @file{/var/tmp} 4067taking precedence. The following command could be used to achieve this 4068effect: 4069 4070@example 4071amd ... /mtmp union:/tmp:/var/tmp -type:=union 4072@end example 4073 4074Currently, the unioned directories must @emph{not} be automounted. That 4075would cause a deadlock. This seriously limits the current usefulness of 4076this filesystem type and the problem will be addressed in a future 4077release of @i{Amd}. 4078 4079Files created in the union directory are actually created in the last 4080named directory. This is done by creating a wildcard entry which points 4081to the correct directory. The wildcard entry is visible if the union 4082directory is listed, so allowing you to see which directory has 4083priority. 4084 4085The files visible in the union directory are computed at the time 4086@i{Amd} is started, and are not kept up-to-date with respect to the 4087underlying directories. Similarly, if a link is removed, for example 4088with the @samp{rm} command, it will be lost forever. 4089 4090@c ---------------------------------------------------------------- 4091@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types 4092@comment node-name, next, previous, up 4093@section Error Filesystem (@samp{error}) 4094@cindex Error filesystem 4095@cindex error, filesystem type 4096@cindex Filesystem type; error 4097 4098The @dfn{error} (@samp{type:=error}) filesystem type is used internally as a catch-all in the 4099case where none of the other filesystems was selected, or some other 4100error occurred. Lookups and mounts always fail with ``No such file or 4101directory''. All other operations trivially succeed. 4102 4103The error filesystem is not directly accessible. 4104 4105@c ---------------------------------------------------------------- 4106@node Top-level Filesystem, Root Filesystem, Error Filesystem, Filesystem Types 4107@comment node-name, next, previous, up 4108@section Top-level Filesystem (@samp{toplvl}) 4109@cindex Top level filesystem 4110@cindex toplvl, filesystem type 4111@cindex Filesystem type; toplvl 4112 4113The @dfn{toplvl} (@samp{type:=toplvl}) filesystems is derived from the @samp{auto} filesystem 4114and is used to mount the top-level automount nodes. Requests of this 4115type are automatically generated from the command line arguments. 4116 4117@c ---------------------------------------------------------------- 4118@node Root Filesystem, Inheritance Filesystem, Top-level Filesystem, Filesystem Types 4119@comment node-name, next, previous, up 4120@section Root Filesystem (@samp{root}) 4121@cindex Root filesystem 4122@cindex root, filesystem type 4123@cindex Filesystem type; root 4124 4125The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal 4126placeholder onto which @i{Amd} can pin @samp{toplvl} mounts. Only one 4127node of this type need ever exist and one is created automatically 4128during startup. The effect of having more than one root node is 4129undefined. 4130 4131The root filesystem is not directly accessible. 4132 4133@c ---------------------------------------------------------------- 4134@node Inheritance Filesystem, , Root Filesystem, Filesystem Types 4135@comment node-name, next, previous, up 4136@section Inheritance Filesystem (@samp{inherit}) 4137@cindex Inheritance filesystem 4138@cindex Nodes generated on a restart 4139@cindex inherit, filesystem type 4140@cindex Filesystem type; inherit 4141 4142The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly 4143accessible. Instead, internal mount nodes of this type are 4144automatically generated when @i{Amd} is started with the @code{-r} option. 4145At this time the system mount table is scanned to locate any filesystems 4146which are already mounted. If any reference to these filesystems is 4147made through @i{Amd} then instead of attempting to mount it, @i{Amd} 4148simulates the mount and @dfn{inherits} the filesystem. This allows a 4149new version of @i{Amd} to be installed on a live system simply by 4150killing the old daemon with @samp{SIGTERM} and starting the new one.@refill 4151 4152This filesystem type is not generally visible externally, but it is 4153possible that the output from @samp{amq -m} may list @samp{inherit} as 4154the filesystem type. This happens when an inherit operation cannot 4155be completed for some reason, usually because a fileserver is down. 4156 4157@c ################################################################ 4158@node Amd Configuration File, Run-time Administration, Filesystem Types, Top 4159@comment node-name, next, previous, up 4160@chapter Amd Configuration File 4161@cindex Amd Configuration File 4162@cindex amd.conf 4163 4164The @samp{amd.conf} file is the configuration file for @i{Amd}, as part 4165of the am-utils suite. This file contains runtime configuration 4166information for the @i{Amd} automounter program. 4167 4168@menu 4169* File Format:: 4170* The Global Section:: 4171* Regular Map Sections:: 4172* Common Parameters:: 4173* Global Parameters:: 4174* Regular Map Parameters:: 4175* amd.conf Examples:: 4176@end menu 4177 4178@c ================================================================ 4179@node File Format, The Global Section, Amd Configuration File, Amd Configuration File 4180@comment node-name, next, previous, up 4181@section File Format 4182@cindex amd.conf file format 4183 4184The @samp{amd.conf} file consists of sections and parameters. A section 4185begins with the name of the section in square brackets @samp{[]} and 4186continues until the next section begins or the end of the file is reached. 4187Sections contain parameters of the form @samp{name = value}. 4188 4189The file is line-based --- that is, each newline-terminated line 4190represents either a comment, a section name or a parameter. No 4191line-continuation syntax is available. 4192 4193Section names, parameter names and their values are case sensitive. 4194 4195Only the first equals sign in a parameter is significant. Whitespace 4196before or after the first equals sign is discarded. Leading, trailing 4197and internal whitespace in section and parameter names is irrelevant. 4198Leading and trailing whitespace in a parameter value is discarded. 4199Internal whitespace within a parameter value is not allowed, unless the 4200whole parameter value is quoted with double quotes as in @samp{name = 4201"some value"}. 4202 4203Any line beginning with a pound sign @samp{#} is ignored, as are lines 4204containing only whitespace. 4205 4206The values following the equals sign in parameters are all either a 4207string (no quotes needed if string does not include spaces) or a 4208boolean, which may be given as @samp{yes}/@samp{no}. Case is significant in all 4209values. Some items such as cache timeouts are numeric. 4210 4211@c ================================================================ 4212@node The Global Section, Regular Map Sections, File Format, Amd Configuration File 4213@comment node-name, next, previous, up 4214@section The Global Section 4215@cindex amd.conf global section 4216 4217The global section must be specified as @samp{[global]}. Parameters in 4218this section either apply to @i{Amd} as a whole, or to all other regular map 4219sections which follow. There should be only one global section defined 4220in one configuration file. 4221 4222It is highly recommended that this section be specified first in the 4223configuration file. If it is not, then regular map sections which 4224precede it will not use global values defined later. 4225 4226@c ================================================================ 4227@node Regular Map Sections, Common Parameters, The Global Section, Amd Configuration File 4228@comment node-name, next, previous, up 4229@section Regular Map Sections 4230@cindex amd.conf regular map sections 4231 4232Parameters in regular (non-global) sections apply to a single map entry. 4233For example, if the map section @samp{[/homes]} is defined, then all 4234parameters following it will be applied to the @file{/homes} 4235@i{Amd}-managed mount point. 4236 4237@c ================================================================ 4238@node Common Parameters, Global Parameters, Regular Map Sections, Amd Configuration File 4239@comment node-name, next, previous, up 4240@section Common Parameters 4241@cindex amd.conf common parameters 4242 4243These parameters can be specified either in the global or a map-specific 4244section. Entries specified in a map-specific section override the default 4245value or one defined in the global section. If such a common parameter is 4246specified only in the global section, it is applicable to all regular map 4247sections that follow. 4248 4249@menu 4250* autofs_use_lofs Parameter:: 4251* browsable_dirs Parameter:: 4252* map_defaults Parameter:: 4253* map_options Parameter:: 4254* map_type Parameter:: 4255* mount_type Parameter:: 4256* search_path Parameter:: 4257* selectors_in_defaults Parameter:: 4258* sun_map_syntax Parameter:: 4259@end menu 4260 4261@c ---------------------------------------------------------------- 4262@node autofs_use_lofs Parameter, browsable_dirs Parameter, Common Parameters, Common Parameters 4263@comment node-name, next, previous, up 4264@subsection @t{autofs_use_lofs} Parameter 4265@cindex autofs_use_lofs Parameter 4266 4267(type=string, default=@samp{yes}). 4268When set to @samp{yes}, @i{Amd}'s autofs code will use lofs-type 4269(loopback) mounts for @code{type:=link} mounts, as well as several 4270other cases that require local references. This has the advantage 4271that @i{Amd} does not use a secondary mount point and users do not see 4272external pathnames (the infamous @code{/bin/pwd} problem, where it 4273reports a different path than the user chdir'ed into). One of the 4274disadvantages of using this option is that the autofs code is 4275relatively new and the in-place mounts have not been throughly tested. 4276 4277If this option is set to @samp{no}, then @i{Amd}'s autofs code will 4278use symlinks instead of lofs-type mounts for local references. This 4279has the advantage of using simpler (more stable) code, but at the 4280expense of negating one of autofs's big advantages: the hiding of 4281@i{Amd}'s internal paths. Note that symlinks are not supported in all 4282autofs implementations, especially those derived from Solaris Autofs 4283v1. Also, on Solaris 2.6 and newer, autofs symlinks are not cached, 4284resulting in repeated up-call requests to @i{Amd}. 4285 4286@c ---------------------------------------------------------------- 4287@node browsable_dirs Parameter, map_defaults Parameter, autofs_use_lofs Parameter, Common Parameters 4288@comment node-name, next, previous, up 4289@subsection @t{browsable_dirs} Parameter 4290@cindex browsable_dirs Parameter 4291 4292(type=string, default=@samp{no}). If @samp{yes}, then @i{Amd}'s top-level 4293mount points will be browsable to @b{readdir}(3) calls. This means you 4294could run for example @b{ls}(1) and see what keys are available to mount 4295in that directory. Not all entries are made visible to @b{readdir}(3): 4296the @samp{/defaults} entry, wildcard entries, and those with a @file{/} 4297in them are not included. If you specify @samp{full} to this option, 4298all but the @samp{/defaults} entry will be visible. Note that if you run 4299a command which will attempt to @b{stat}(2) the entries, such as often 4300done by @samp{ls -l} or @samp{ls -F}, @i{Amd} will attempt to mount 4301@i{every} entry in that map. This is often called a ``mount storm''. 4302 4303Note that mount storms are mostly avoided by using autofs mounts 4304(@samp{mount_type = autofs}). 4305 4306@c ---------------------------------------------------------------- 4307@node map_defaults Parameter, map_options Parameter, browsable_dirs Parameter, Common Parameters 4308@comment node-name, next, previous, up 4309@subsection @t{map_defaults} Parameter 4310@cindex map_defaults Parameter 4311 4312(type=string, default to empty). This option sets a string to be used 4313as the map's @code{/defaults} entry, overriding any @code{/defaults} 4314specified in the map. This allows local users to override a given 4315map's defaults without modifying maps globally (which is impossible in 4316sites where the maps are managed by a different administrative group). 4317 4318@c ---------------------------------------------------------------- 4319@node map_options Parameter, map_type Parameter, map_defaults Parameter, Common Parameters 4320@comment node-name, next, previous, up 4321@subsection @t{map_options} Parameter 4322@cindex map_options Parameter 4323 4324(type=string, default no options). This option is the same as 4325specifying map options on the command line to @i{Amd}, such as 4326@samp{cache:=all}. 4327 4328@c ---------------------------------------------------------------- 4329@node map_type Parameter, mount_type Parameter, map_options Parameter, Common Parameters 4330@comment node-name, next, previous, up 4331@subsection @t{map_type} Parameter 4332@cindex map_type Parameter 4333 4334(type=string, default search all map types). If specified, @i{Amd} will 4335initialize the map only for the type given. This is useful to avoid the 4336default map search type used by @i{Amd} which takes longer and can have 4337undesired side-effects such as initializing NIS even if not used. 4338Possible values are 4339 4340@table @samp 4341@item file 4342plain files 4343@item hesiod 4344Hesiod name service from MIT 4345@item ldap 4346Lightweight Directory Access Protocol 4347@item ndbm 4348(New) dbm style hash files 4349@item nis 4350Network Information Services (version 2) 4351@item nisplus 4352Network Information Services Plus (version 3) 4353@item passwd 4354local password files 4355@item union 4356union maps 4357@end table 4358 4359@c ---------------------------------------------------------------- 4360@node mount_type Parameter, search_path Parameter, map_type Parameter, Common Parameters 4361@comment node-name, next, previous, up 4362@subsection @t{mount_type} Parameter 4363@cindex mount_type Parameter 4364 4365(type=string, default=@samp{nfs}). All @i{Amd} mount types default to NFS. 4366That is, @i{Amd} is an NFS server on the map mount points, for the local 4367host it is running on. If @samp{autofs} is specified, @i{Amd} will be 4368an autofs server for those mount points. 4369 4370@c ---------------------------------------------------------------- 4371@node search_path Parameter, selectors_in_defaults Parameter, mount_type Parameter, Common Parameters 4372@comment node-name, next, previous, up 4373@subsection @t{search_path} Parameter 4374@cindex search_path Parameter 4375 4376(type=string, default no search path). This provides a 4377(colon-delimited) search path for file maps. Using a search path, 4378sites can allow for local map customizations and overrides, and can 4379distributed maps in several locations as needed. 4380 4381@c ---------------------------------------------------------------- 4382@node selectors_in_defaults Parameter, sun_map_syntax Parameter, search_path Parameter, Common Parameters 4383@comment node-name, next, previous, up 4384@subsection @t{selectors_in_defaults} Parameter 4385@cindex selectors_in_defaults Parameter 4386 4387(type=boolean, default=@samp{no}). If @samp{yes}, then the 4388@samp{/defaults} entry of maps will search for and process any 4389selectors before setting defaults for all other keys in that map. 4390Useful when you want to set different options for a complete map based 4391on some parameters. For example, you may want to better the NFS 4392performance over slow slip-based networks as follows: 4393 4394@example 4395/defaults \ 4396 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \ 4397 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192 4398@end example 4399 4400Deprecated form: selectors_on_default. 4401 4402@c ---------------------------------------------------------------- 4403@node sun_map_syntax Parameter, , selectors_in_defaults Parameter, Common Parameters 4404@comment node-name, next, previous, up 4405@subsection @t{sun_map_syntax} Parameter 4406@cindex sun_map_syntax Parameter 4407 4408(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will 4409parse the map according to the Sun Automount syntax. 4410 4411 4412@c ================================================================ 4413@node Global Parameters, Regular Map Parameters, Common Parameters, Amd Configuration File 4414@comment node-name, next, previous, up 4415@section Global Parameters 4416@cindex amd.conf global parameters 4417 4418The following parameters are applicable to the @samp{[global]} section only. 4419 4420@menu 4421* arch Parameter:: 4422* auto_attrcache Parameter:: 4423* auto_dir Parameter:: 4424* cache_duration Parameter:: 4425* cluster Parameter:: 4426* debug_mtab_file Parameter:: 4427* debug_options Parameter:: 4428* dismount_interval Parameter:: 4429* domain_strip Parameter:: 4430* exec_map_timeout Parameter:: 4431* forced_unmounts Parameter:: 4432* full_os Parameter:: 4433* fully_qualified_hosts Parameter:: 4434* hesiod_base Parameter:: 4435* karch Parameter:: 4436* ldap_base Parameter:: 4437* ldap_cache_maxmem Parameter:: 4438* ldap_cache_seconds Parameter:: 4439* ldap_hostports Parameter:: 4440* ldap_proto_version Parameter:: 4441* local_domain Parameter:: 4442* localhost_address Parameter:: 4443* log_file Parameter:: 4444* log_options Parameter:: 4445* map_reload_interval Parameter:: 4446* nfs_allow_any_interface Parameter:: 4447* nfs_allow_insecure_port Parameter:: 4448* nfs_proto Parameter:: 4449* nfs_retransmit_counter Parameter:: 4450* nfs_retransmit_counter_udp Parameter:: 4451* nfs_retransmit_counter_tcp Parameter:: 4452* nfs_retransmit_counter_toplvl Parameter:: 4453* nfs_retry_interval Parameter:: 4454* nfs_retry_interval_udp Parameter:: 4455* nfs_retry_interval_tcp Parameter:: 4456* nfs_retry_interval_toplvl Parameter:: 4457* nfs_vers Parameter:: 4458* nis_domain Parameter:: 4459* normalize_hostnames Parameter:: 4460* normalize_slashes Parameter:: 4461* os Parameter:: 4462* osver Parameter:: 4463* pid_file Parameter:: 4464* plock Parameter:: 4465* portmap_program Parameter:: 4466* preferred_amq_port Parameter:: 4467* print_pid Parameter:: 4468* print_version Parameter:: 4469* restart_mounts Parameter:: 4470* show_statfs_entries Parameter:: 4471* truncate_log Parameter:: 4472* unmount_on_exit Parameter:: 4473* use_tcpwrappers Parameter:: 4474* vendor Parameter:: 4475@end menu 4476 4477@c ---------------------------------------------------------------- 4478@node arch Parameter, auto_attrcache Parameter, Global Parameters, Global Parameters 4479@comment node-name, next, previous, up 4480@subsection @t{arch} Parameter 4481@cindex arch Parameter 4482 4483(type=string, default to compiled in value). Same as the @code{-A} 4484option to @i{Amd}. Allows you to override the value of the @i{arch} 4485@i{Amd} variable. 4486 4487@c ---------------------------------------------------------------- 4488@node auto_attrcache Parameter, auto_dir Parameter, arch Parameter, Global Parameters 4489@comment node-name, next, previous, up 4490@subsection @t{auto_attrcache} Parameter 4491@cindex auto_attrcache Parameter 4492 4493(type=numeric, default=0). Specify in seconds (or units of 0.1 4494seconds, depending on the OS), what is the (kernel-side) NFS attribute 4495cache timeout for @i{Amd}'s own automount points. A value of 0 is 4496supposed to turn off attribute caching, meaning that @i{Amd} will be 4497consulted via a kernel-RPC each time someone stat()'s the mount point 4498(which could be abused as a denial-of-service attack). 4499 4500@emph{WARNING}: @i{Amd} depends on being able to turn off the NFS 4501attribute cache of the client OS. If it cannot be turned off, then 4502users may get ESTALE errors or symlinks that point to the wrong 4503places. This is more likely under heavy use of @i{Amd}, for example 4504if your system is experiencing frequent map changes or frequent 4505mounts/unmounts. Therefore, under normal circumstances, this 4506parameter should remain set to 0, to ensure that the attribute cache 4507is indeed off. 4508 4509Unfortunately, some kernels (e.g., certain BSDs) don't have a way to 4510turn off the NFS attribute cache. Setting this parameter to 0 is 4511supposed to turn off attribute caching entirely, but unfortunately it 4512does not; instead, the attribute cache is set to some internal 4513hard-coded default (usually anywhere from 5-30 seconds). If you 4514suspect that your OS doesn't have a reliable way of turning off the 4515attribute cache, then it is better to set this parameter to the 4516smallest possible non-zero value (set @samp{auto_attrcache=1} in your 4517@code{amd.conf}). This will not eliminate the problem, but reduce the 4518risk window somewhat. The best solutions are (1) to use @i{Amd} in 4519Autofs mode, if it's supported in your OS, and (2) talk to your OS 4520vendor to support a true @samp{noac} flag. See the 4521@uref{http://www.am-utils.org/docs/am-utils/attrcache.txt,README.attrcache} 4522document for more details. 4523 4524If you are able to turn off the attribute cache on your OS, alas, 4525@i{Amd}'s performance may degrade (when not using Autofs) because 4526every traversal of an automounter-controlled pathname will result in a 4527lookup request from the kernel to @i{Amd}. Under heavy loads, for 4528example when using recursive tools like @samp{find}, @samp{rdist}, or 4529@samp{rsync}, this performance degradation can be noticeable. There 4530are two possible solutions that some administrators have chosen to 4531improve performance: 4532 4533@enumerate 4534 4535@item 4536First, you can turn off unmounting using the @samp{nounmount} mount 4537option. This will ensure that no @i{Amd} symlink could ever change, 4538thereby the kernel's attribute cache and @i{Amd} will always be in 4539sync. However, this method will cause the number of mounts to keep 4540growing, even if some are no longer in use; this has the disadvantage 4541that your system could be more susceptible to hangs if even one of 4542those accumulating mounts hangs due to a downed server. 4543 4544@item 4545Second, you can turn on attribute caching carefully by setting a small 4546automounter attribute cache value (say, one second), and a relatively 4547large dismount interval (say, one hour). (@xref{dismount_interval 4548Parameter}.) For example, you can set this in your @code{amd.conf}: 4549 4550@example 4551[global] 4552auto_attrcache = 1 4553dismount_interval = 3600 4554@end example 4555 4556This has the benefit of using the kernel's attribute cache and thus 4557improving performance. The disadvantage with this option is that the 4558window of vulnerability is not eliminated entirely: it is only made 4559smaller. 4560 4561@end enumerate 4562 4563@c ---------------------------------------------------------------- 4564@node auto_dir Parameter, cache_duration Parameter, auto_attrcache Parameter, Global Parameters 4565@comment node-name, next, previous, up 4566@subsection @t{auto_dir} Parameter 4567@cindex auto_dir Parameter 4568 4569(type=string, default=@samp{/a}). Same as the @code{-a} option to @i{Amd}. 4570This sets the private directory where @i{Amd} will create 4571sub-directories for its real mount points. 4572 4573@c ---------------------------------------------------------------- 4574@node cache_duration Parameter, cluster Parameter, auto_dir Parameter, Global Parameters 4575@comment node-name, next, previous, up 4576@subsection @t{cache_duration} Parameter 4577@cindex cache_duration Parameter 4578 4579(type=numeric, default=300). Same as the @code{-c} option to @i{Amd}. 4580Sets the duration in seconds that looked-up or mounted map entries 4581remain in the cache. 4582 4583@c ---------------------------------------------------------------- 4584@node cluster Parameter, debug_mtab_file Parameter, cache_duration Parameter, Global Parameters 4585@comment node-name, next, previous, up 4586@subsection @t{cluster} Parameter 4587@cindex cluster Parameter 4588 4589(type=string, default no cluster). Same as the @code{-C} option to 4590@i{Amd}. Specifies the alternate HP-UX cluster to use. 4591 4592@c ---------------------------------------------------------------- 4593@node debug_mtab_file Parameter, debug_options Parameter, cluster Parameter, Global Parameters 4594@comment node-name, next, previous, up 4595@subsection @t{debug_mtab_file} Parameter 4596@cindex debug_mtab_file Parameter 4597 4598(type=string, default="/tmp/mtab"). Path to mtab file that is used 4599by @i{Amd} to store a list of mounted file systems during debug-mtab mode. 4600This option only applies to systems that store mtab information on disk. 4601 4602@c ---------------------------------------------------------------- 4603@node debug_options Parameter, dismount_interval Parameter, debug_mtab_file Parameter, Global Parameters 4604@comment node-name, next, previous, up 4605@subsection @t{debug_options} Parameter 4606@cindex debug_options Parameter 4607 4608(type=string, default no debug options). Same as the @code{-D} option 4609to @i{Amd}. Specify any debugging options for @i{Amd}. Works only if 4610am-utils was configured for debugging using the @code{--enable-debug} 4611option. The additional @samp{mem} option can be turned on via 4612@code{--enable-debug=mem}. Otherwise debugging options are ignored. 4613Options are comma delimited, and can be preceded by the string 4614@samp{no} to negate their meaning. You can get the list of supported 4615debugging and logging options by running @code{amd -H}. Possible 4616values those listed for the -D option. @xref{-D Option}. 4617 4618@c ---------------------------------------------------------------- 4619@node dismount_interval Parameter, domain_strip Parameter, debug_options Parameter, Global Parameters 4620@comment node-name, next, previous, up 4621@subsection @t{dismount_interval} Parameter 4622@cindex dismount_interval Parameter 4623 4624(type=numeric, default=120). Same as the @code{-w} option to 4625@i{Amd}. Specify in seconds, the time between attempts to dismount file 4626systems that have exceeded their cached times. 4627 4628@c ---------------------------------------------------------------- 4629@node domain_strip Parameter, exec_map_timeout Parameter, dismount_interval Parameter, Global Parameters 4630@comment node-name, next, previous, up 4631@subsection @t{domain_strip} Parameter 4632@cindex domain_strip Parameter 4633 4634(type=boolean, default=@samp{yes}). If @samp{yes}, then the domain 4635name part referred to by @code{$@{rhost@}} is stripped off. This is 4636useful to keep logs and smaller. If @samp{no}, then the domain name 4637part is left changed. This is useful when using multiple domains with 4638the same maps (as you may have hosts whose domain-stripped name is 4639identical). 4640 4641@c ---------------------------------------------------------------- 4642@node exec_map_timeout Parameter, forced_unmounts Parameter, domain_strip Parameter, Global Parameters 4643@comment node-name, next, previous, up 4644@subsection @t{exec_map_timeout} Parameter 4645@cindex exec_map_timeout Parameter 4646 4647(type=numeric, default=10). The timeout in seconds that @i{Amd} will 4648wait for an executable map program before an answer is returned from 4649that program (or script). This value should be set to as small as 4650possible while still allowing normal replies to be returned before the 4651timer expires, because during the time that the executable map program 4652is queried, @i{Amd} is essentially waiting and is thus not responding 4653to any other queries. @xref{Executable maps}. 4654 4655@c ---------------------------------------------------------------- 4656@node forced_unmounts Parameter, full_os Parameter, exec_map_timeout Parameter, Global Parameters 4657@comment node-name, next, previous, up 4658@subsection @t{forced_unmounts} Parameter 4659@cindex forced_unmounts Parameter 4660 4661(type=boolean, default=@samp{no}). 4662Sometimes, mount points are hung due to unrecoverable conditions, such 4663as when NFS servers migrate, change their IP address, are down 4664permanently, or due to hardware failures, and more. In this case, 4665attempting to unmount an existing mount point, or even just to 4666@b{stat}(2) it, results in one of three fatal errors: EIO, ESTALE, or 4667EBUSY. At that point, @i{Amd} can do little to recover that hung 4668point (in fact, the OS cannot automatically recover either). For that 4669reason, some OSs support special kinds of forced unmounts, which must 4670be used very carefully: they will force an unmount immediately (or 4671lazily on Linux), which could result in application data loss. 4672However, that may be the only way to recover the entire host (without 4673rebooting). Once a hung mount point is forced out, @i{Amd} can then 4674re-mount a replacement one (if available), bringing a mostly-hung 4675system back to operation and avoiding a potentially costly reboot. 4676 4677If the @samp{forced_unmounts} option is set to @samp{yes}, and the 4678client OS supports forced or lazy unmounts, then @i{Amd} will attempt 4679to use them if it gets any of the three serious error conditions 4680listed above. Note that @i{Amd} will force the unmount of mount 4681points that returned EBUSY only for @samp{type:=toplvl} mounts 4682(@pxref{Top-level Filesystem}): that is, @i{Amd}'s own mount points. 4683This is useful to recover from a previously hung @i{Amd}, and to 4684ensure that an existing @i{Amd} can shutdown cleanly even if some 4685processes are keeping its mount points busy (i.e., when a user's shell 4686process uses @code{cd} to set its CWD to @i{Amd}'s own mount point). 4687 4688If this option is set to @samp{no} (the default), then @i{Amd} will 4689not attempt this special recovery procedure. 4690 4691@c ---------------------------------------------------------------- 4692@node full_os Parameter, fully_qualified_hosts Parameter, forced_unmounts Parameter, Global Parameters 4693@comment node-name, next, previous, up 4694@subsection @t{full_os} Parameter 4695@cindex full_os Parameter 4696 4697(type=string, default to compiled in value). The full name of the 4698operating system, along with its version. Allows you to override the 4699compiled-in full name and version of the operating system. Useful when 4700the compiled-in name is not desired. For example, the full operating 4701system name on linux comes up as @samp{linux}, but you can override it 4702to @samp{linux-2.2.5}. 4703 4704@c ---------------------------------------------------------------- 4705@node fully_qualified_hosts Parameter, hesiod_base Parameter, full_os Parameter, Global Parameters 4706@comment node-name, next, previous, up 4707@subsection @t{fully_qualified_hosts} Parameter 4708@cindex fully_qualified_hosts Parameter 4709 4710(type=string, default=@samp{no}). If @samp{yes}, @i{Amd} will perform RPC 4711authentication using fully-qualified host names. This is necessary for 4712some systems, and especially when performing cross-domain mounting. For 4713this function to work, the @i{Amd} variable @samp{$@{hostd@}} is used, 4714requiring that @samp{$@{domain@}} not be null. 4715 4716@c ---------------------------------------------------------------- 4717@node hesiod_base Parameter, karch Parameter, fully_qualified_hosts Parameter, Global Parameters 4718@comment node-name, next, previous, up 4719@subsection @t{hesiod_base} Parameter 4720@cindex hesiod_base Parameter 4721 4722(type=string, default=@samp{automount}). Specify the base name for 4723hesiod maps. 4724 4725@c ---------------------------------------------------------------- 4726@node karch Parameter, ldap_base Parameter, hesiod_base Parameter, Global Parameters 4727@comment node-name, next, previous, up 4728@subsection @t{karch} Parameter 4729@cindex karch Parameter 4730 4731(type=string, default to karch of the system). Same as the @code{-k} 4732option to @i{Amd}. Allows you to override the kernel-architecture of 4733your system. Useful for example on Sun (Sparc) machines, where you can 4734build one @i{Amd} binary, and run it on multiple machines, yet you want 4735each one to get the correct @i{karch} variable set (for example, sun4c, 4736sun4m, sun4u, etc.) Note that if not specified, @i{Amd} will use 4737@b{uname}(2) to figure out the kernel architecture of the machine. 4738 4739@c ---------------------------------------------------------------- 4740@node ldap_base Parameter, ldap_cache_maxmem Parameter, karch Parameter, Global Parameters 4741@comment node-name, next, previous, up 4742@subsection @t{ldap_base} Parameter 4743@cindex ldap_base Parameter 4744 4745(type=string, default not set). 4746Specify the base name for LDAP. This often includes LDAP-specific 4747values such as country and organization. 4748 4749@c ---------------------------------------------------------------- 4750@node ldap_cache_maxmem Parameter, ldap_cache_seconds Parameter, ldap_base Parameter, Global Parameters 4751@comment node-name, next, previous, up 4752@subsection @t{ldap_cache_maxmem} Parameter 4753@cindex ldap_cache_maxmem Parameter 4754 4755(type=numeric, default=131072). Specify the maximum memory @i{Amd} 4756should use to cache LDAP entries. 4757 4758@c ---------------------------------------------------------------- 4759@node ldap_cache_seconds Parameter, ldap_hostports Parameter, ldap_cache_maxmem Parameter, Global Parameters 4760@comment node-name, next, previous, up 4761@subsection @t{ldap_cache_seconds} Parameter 4762@cindex ldap_cache_seconds Parameter 4763 4764(type=numeric, default=0). Specify the number of seconds to keep 4765entries in the cache. 4766 4767@c ---------------------------------------------------------------- 4768@node ldap_hostports Parameter, ldap_proto_version Parameter, ldap_cache_seconds Parameter, Global Parameters 4769@comment node-name, next, previous, up 4770@subsection @t{ldap_hostports} Parameter 4771@cindex ldap_hostports Parameter 4772 4773(type=string, default not set). 4774Specify the LDAP host and port values. 4775 4776@c ---------------------------------------------------------------- 4777@node ldap_proto_version Parameter, local_domain Parameter, ldap_hostports Parameter, Global Parameters 4778@comment node-name, next, previous, up 4779@subsection @t{ldap_proto_version} Parameter 4780@cindex ldap_proto_version Parameter 4781 4782(type=numeric, default=2). Specify the LDAP protocol version to use. 4783With a value of 3 will use LDAPv3 protocol. 4784 4785@c ---------------------------------------------------------------- 4786@node local_domain Parameter, localhost_address Parameter, ldap_proto_version Parameter, Global Parameters 4787@comment node-name, next, previous, up 4788@subsection @t{local_domain} Parameter 4789@cindex local_domain Parameter 4790 4791(type=string, default no sub-domain). Same as the @code{-d} option 4792to @i{Amd}. Specify the local domain name. If this option is not given 4793the domain name is determined from the hostname, by removing the first 4794component of the fully-qualified host name. 4795 4796@c ---------------------------------------------------------------- 4797@node localhost_address Parameter, log_file Parameter, local_domain Parameter, Global Parameters 4798@comment node-name, next, previous, up 4799@subsection @t{localhost_address} Parameter 4800@cindex localhost_address Parameter 4801 4802(type=string, default to localhost or 127.0.0.1). Specify the name or 4803IP address for @i{Amd} to use when connecting the sockets for the 4804local NFS server and the RPC server. This defaults to 127.0.0.1 or 4805whatever the host reports as its local address. This parameter is 4806useful on hosts with multiple addresses where you want to force 4807@i{Amd} to connect to a specific address. 4808 4809@c ---------------------------------------------------------------- 4810@node log_file Parameter, log_options Parameter, localhost_address Parameter, Global Parameters 4811@comment node-name, next, previous, up 4812@subsection @t{log_file} Parameter 4813@cindex log_file Parameter 4814 4815(type=string, default=@samp{stderr}). Same as the @code{-l} option to 4816@i{Amd}. Specify a file name to log @i{Amd} events to. 4817If the string @samp{/dev/stderr} is specified, 4818@i{Amd} will send its events to the standard error file descriptor. 4819 4820If the string @samp{syslog} is given, @i{Amd} will record its events 4821with the system logger @b{syslogd}(8). If your system supports syslog 4822facilities, then the default facility used is @samp{LOG_DAEMON}. 4823 4824When using syslog, if you wish to change the facility, append its name 4825to the option name, delimited by a single colon. For example, if it is 4826the string @samp{syslog:local7} then @i{Amd} will log messages via 4827@b{syslog}(3) using the @samp{LOG_LOCAL7} facility. If the facility 4828name specified is not recognized, @i{Amd} will default to @samp{LOG_DAEMON}. 4829Note: while you can use any syslog facility available on your system, it 4830is generally a bad idea to use those reserved for other services such as 4831@samp{kern}, @samp{lpr}, @samp{cron}, etc. 4832 4833@c ---------------------------------------------------------------- 4834@node log_options Parameter, map_reload_interval Parameter, log_file Parameter, Global Parameters 4835@comment node-name, next, previous, up 4836@subsection @t{log_options} Parameter 4837@cindex log_options Parameter 4838 4839(type=string, default=``defaults''). Same as the @code{-x} 4840option to @i{Amd}. Specify any logging options for @i{Amd}. Options 4841are comma delimited, and can be preceded by the string @samp{no} to 4842negate their meaning. The @samp{debug} logging option is only available 4843if am-utils was configured with @code{--enable-debug}. You can get the 4844list of supported debugging options by running @code{amd -H}. Possible 4845values are: 4846 4847@table @samp 4848@item all 4849all messages 4850@item defaults 4851an alias for "fatal,error,user,warning,info" 4852@item debug 4853debug messages 4854@item error 4855non-fatal system errors (cannot be turned off) 4856@item fatal 4857fatal errors (cannot be turned off) 4858@item info 4859information 4860@item map 4861map errors 4862@item stats 4863additional statistical information 4864@item user 4865non-fatal user errors 4866@item warn 4867warnings 4868@item warning 4869warnings 4870@end table 4871 4872@c ---------------------------------------------------------------- 4873@node map_reload_interval Parameter, nfs_allow_any_interface Parameter, log_options Parameter, Global Parameters 4874@comment node-name, next, previous, up 4875@subsection @t{map_reload_interval} Parameter 4876@cindex map_reload_interval Parameter 4877 4878(type=numeric, default=3600). The number of seconds that @i{Amd} will 4879wait before it checks to see if any maps have changed at their source 4880(NIS servers, LDAP servers, files, etc.). @i{Amd} will reload only 4881those maps that have changed. 4882 4883@c ---------------------------------------------------------------- 4884@node nfs_allow_any_interface Parameter, nfs_allow_insecure_port Parameter, map_reload_interval Parameter, Global Parameters 4885@comment node-name, next, previous, up 4886@subsection @t{nfs_allow_any_interface} Parameter 4887@cindex nfs_allow_any_interface Parameter 4888 4889(type=string, default=@samp{no}). Normally @i{Amd} accepts local NFS 4890packets only from 127.0.0.1. If this parameter is set to @samp{yes}, 4891then @i{amd} will accept local NFS packets from any local interface; 4892this is useful on hosts that may have multiple interfaces where the 4893system is forced to send all outgoing packets (even those bound to the 4894same host) via an address other than 127.0.0.1. 4895 4896@c ---------------------------------------------------------------- 4897@node nfs_allow_insecure_port Parameter, nfs_proto Parameter, nfs_allow_any_interface Parameter, Global Parameters 4898@comment node-name, next, previous, up 4899@subsection @t{nfs_allow_insecure_port} Parameter 4900@cindex nfs_allow_insecure_port Parameter 4901 4902(type=string, default=@samp{no}). Normally @i{Amd} will refuse requests 4903coming from unprivileged ports (i.e., ports >= 1024 on Unix systems), 4904so that only privileged users and the kernel can send NFS requests to 4905it. However, some kernels (certain versions of Darwin, MacOS X, and 4906Linux) have bugs that cause them to use unprivileged ports in certain 4907situations, which causes @i{Amd} to stop dead in its tracks. This 4908parameter allows @i{Amd} to operate normally even on such systems, at the 4909expense of a slight decrease in the security of its operations. If 4910you see messages like ``ignoring request from foo:1234, port not 4911reserved'' in your @i{Amd} log, try enabling this parameter and give it 4912another go. 4913 4914@c ---------------------------------------------------------------- 4915@node nfs_proto Parameter, nfs_retransmit_counter Parameter, nfs_allow_insecure_port Parameter, Global Parameters 4916@comment node-name, next, previous, up 4917@subsection @t{nfs_proto} Parameter 4918@cindex nfs_proto Parameter 4919 4920(type=string, default to trying version tcp then udp). By default, 4921@i{Amd} tries @code{tcp} and then @code{udp}. This option forces the 4922overall NFS protocol used to TCP or UDP. It overrides what is in the 4923@i{Amd} maps, and is useful when @i{Amd} is compiled with TCP support 4924in NFSv2/NFSv3 that may not be stable. With this option you can turn 4925off the complete usage of TCP for NFS dynamically (without having to 4926recompile @i{Amd}), and use UDP only, until such time as TCP support 4927is desired again. 4928 4929@c ---------------------------------------------------------------- 4930@node nfs_retransmit_counter Parameter, nfs_retransmit_counter_udp Parameter, nfs_proto Parameter, Global Parameters 4931@comment node-name, next, previous, up 4932@subsection @t{nfs_retransmit_counter} Parameter 4933@cindex nfs_retransmit_counter Parameter 4934 4935(type=numeric, default=11). Same as the @i{retransmit} part of the 4936@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the 4937number of NFS retransmissions that the kernel will use to communicate 4938with @i{Amd} using either UDP or TCP mounts. @xref{-t Option}. 4939 4940@c ---------------------------------------------------------------- 4941@node nfs_retransmit_counter_udp Parameter, nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter Parameter, Global Parameters 4942@comment node-name, next, previous, up 4943@subsection @t{nfs_retransmit_counter_udp} Parameter 4944@cindex nfs_retransmit_counter_udp Parameter 4945@cindex nfs_retransmit_counter Parameter 4946@cindex UDP 4947 4948(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4949parameter, but applied globally only to UDP mounts. 4950@xref{nfs_retransmit_counter Parameter}. 4951 4952@c ---------------------------------------------------------------- 4953@node nfs_retransmit_counter_tcp Parameter, nfs_retransmit_counter_toplvl Parameter, nfs_retransmit_counter_udp Parameter, Global Parameters 4954@comment node-name, next, previous, up 4955@subsection @t{nfs_retransmit_counter_tcp} Parameter 4956@cindex nfs_retransmit_counter_tcp Parameter 4957@cindex nfs_retransmit_counter Parameter 4958@cindex TCP 4959 4960(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4961parameter, but applied globally only to TCP mounts. 4962@xref{nfs_retransmit_counter Parameter}. 4963 4964@c ---------------------------------------------------------------- 4965@node nfs_retransmit_counter_toplvl Parameter, nfs_retry_interval Parameter, nfs_retransmit_counter_tcp Parameter, Global Parameters 4966@comment node-name, next, previous, up 4967@subsection @t{nfs_retransmit_counter_toplvl} Parameter 4968@cindex nfs_retransmit_counter_toplvl Parameter 4969@cindex nfs_retransmit_counter Parameter 4970@cindex UDP 4971 4972(type=numeric, default=11). Same as the @i{nfs_retransmit_counter} 4973parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 4974systems it is useful to set this differently than the OS default, so 4975as to better tune @i{Amd}'s responsiveness under heavy scheduler 4976loads. @xref{nfs_retransmit_counter Parameter}. 4977 4978@c ---------------------------------------------------------------- 4979@node nfs_retry_interval Parameter, nfs_retry_interval_udp Parameter, nfs_retransmit_counter_toplvl Parameter, Global Parameters 4980@comment node-name, next, previous, up 4981@subsection @t{nfs_retry_interval} Parameter 4982@cindex nfs_retry_interval Parameter 4983 4984(type=numeric, default=8). Same as the @i{timeout} part of the 4985@code{-t} @i{timeout.retransmit} option to @i{Amd}. Specifies the NFS 4986timeout interval, in @emph{tenths} of seconds, between NFS/RPC retries 4987(for UDP or TCP). This is the value that the kernel will use to 4988communicate with @i{Amd}. @xref{-t Option}. 4989 4990@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 4991retries. The values of the @i{nfs_retransmit_counter} and the 4992@i{nfs_retry_interval} parameters change the overall retry interval. 4993Too long an interval gives poor interactive response; too short an 4994interval causes excessive retries. 4995 4996@c ---------------------------------------------------------------- 4997@node nfs_retry_interval_udp Parameter, nfs_retry_interval_tcp Parameter, nfs_retry_interval Parameter, Global Parameters 4998@comment node-name, next, previous, up 4999@subsection @t{nfs_retry_interval_udp} Parameter 5000@cindex nfs_retry_interval_udp Parameter 5001@cindex nfs_retry_interval Parameter 5002@cindex UDP 5003 5004(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5005parameter, but applied globally only to UDP mounts. 5006@xref{nfs_retry_interval Parameter}. 5007 5008@c ---------------------------------------------------------------- 5009@node nfs_retry_interval_tcp Parameter, nfs_retry_interval_toplvl Parameter, nfs_retry_interval_udp Parameter, Global Parameters 5010@comment node-name, next, previous, up 5011@subsection @t{nfs_retry_interval_tcp} Parameter 5012@cindex nfs_retry_interval_tcp Parameter 5013@cindex nfs_retry_interval Parameter 5014@cindex TCP 5015 5016(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5017parameter, but applied globally only to TCP mounts. 5018@xref{nfs_retry_interval Parameter}. 5019 5020@c ---------------------------------------------------------------- 5021@node nfs_retry_interval_toplvl Parameter, nfs_vers Parameter, nfs_retry_interval_tcp Parameter, Global Parameters 5022@comment node-name, next, previous, up 5023@subsection @t{nfs_retry_interval_toplvl} Parameter 5024@cindex nfs_retry_interval_toplvl Parameter 5025@cindex nfs_retry_interval Parameter 5026@cindex UDP 5027 5028(type=numeric, default=8). Same as the @i{nfs_retry_interval} 5029parameter, applied only for @i{Amd}'s top-level UDP mounts. On some 5030systems it is useful to set this differently than the OS default, so 5031as to better tune @i{Amd}'s responsiveness under heavy scheduler 5032loads. @xref{nfs_retry_interval Parameter}. 5033 5034@c ---------------------------------------------------------------- 5035@node nfs_vers Parameter, nis_domain Parameter, nfs_retry_interval_toplvl Parameter, Global Parameters 5036@comment node-name, next, previous, up 5037@subsection @t{nfs_vers} Parameter 5038@cindex nfs_vers Parameter 5039 5040(type=numeric, default to trying version 3 then 2). By default, 5041@i{Amd} tries version 3 and then version 2. This option forces the 5042overall NFS protocol used to version 3 or 2. It overrides what is in 5043the @i{Amd} maps, and is useful when @i{Amd} is compiled with NFSv3 5044support that may not be stable. With this option you can turn off the 5045complete usage of NFSv3 dynamically (without having to recompile 5046@i{Amd}), and use NFSv2 only, until such time as NFSv3 support is 5047desired again. 5048 5049@c ---------------------------------------------------------------- 5050@node nis_domain Parameter, normalize_hostnames Parameter, nfs_vers Parameter, Global Parameters 5051@comment node-name, next, previous, up 5052@subsection @t{nis_domain} Parameter 5053@cindex nis_domain Parameter 5054 5055(type=string, default to local NIS domain name). Same as the 5056@code{-y} option to @i{Amd}. Specify an alternative NIS domain from 5057which to fetch the NIS maps. The default is the system domain name. 5058This option is ignored if NIS support is not available. 5059 5060@c ---------------------------------------------------------------- 5061@node normalize_hostnames Parameter, normalize_slashes Parameter, nis_domain Parameter, Global Parameters 5062@comment node-name, next, previous, up 5063@subsection @t{normalize_hostnames} Parameter 5064@cindex normalize_hostnames Parameter 5065 5066(type=boolean, default=@samp{no}). Same as the @code{-n} option to @i{Amd}. 5067If @samp{yes}, then the name referred to by @code{$@{rhost@}} is normalized 5068relative to the host database before being used. The effect is to 5069translate aliases into ``official'' names. 5070 5071@c ---------------------------------------------------------------- 5072@node normalize_slashes Parameter, os Parameter, normalize_hostnames Parameter, Global Parameters 5073@comment node-name, next, previous, up 5074@subsection @t{normalize_slashes} Parameter 5075@cindex normalize_slashes Parameter 5076 5077(type=boolean, default=@samp{yes}). If @samp{yes} then amd will 5078condense all multiple @code{/} (slash) characters into one and remove 5079all trailing slashes. If @samp{no}, then amd will not touch strings 5080that may contain repeated or trailing slashes. The latter is 5081sometimes useful with SMB mounts, which often require multiple slash 5082characters in pathnames. 5083 5084@c ---------------------------------------------------------------- 5085@node os Parameter, osver Parameter, normalize_slashes Parameter, Global Parameters 5086@comment node-name, next, previous, up 5087@subsection @t{os} Parameter 5088@cindex os Parameter 5089 5090(type=string, default to compiled in value). Same as the @code{-O} 5091option to @i{Amd}. Allows you to override the compiled-in name of the 5092operating system. Useful when the built-in name is not desired for 5093backward compatibility reasons. For example, if the built-in name is 5094@samp{sunos5}, you can override it to @samp{sos5}, and use older maps 5095which were written with the latter in mind. 5096 5097 5098@c ---------------------------------------------------------------- 5099@node osver Parameter, pid_file Parameter, os Parameter, Global Parameters 5100@comment node-name, next, previous, up 5101@subsection @t{osver} Parameter 5102@cindex osver 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 version 5106number of the operating system. Useful when the built-in version is not 5107desired for backward compatibility reasons. For example, if the build 5108in version is @samp{2.5.1}, you can override it to @samp{5.5.1}, and use 5109older maps that were written with the latter in mind. 5110 5111@c ---------------------------------------------------------------- 5112@node pid_file Parameter, plock Parameter, osver Parameter, Global Parameters 5113@comment node-name, next, previous, up 5114@subsection @t{pid_file} Parameter 5115@cindex pid_file Parameter 5116 5117(type=string, default=@samp{/dev/stdout}). Specify a file to store the process 5118ID of the running daemon into. If not specified, @i{Amd} will print its 5119process id onto the standard output. Useful for killing @i{Amd} after 5120it had run. Note that the PID of a running @i{Amd} can also be 5121retrieved via @i{Amq} (@pxref{Amq -p option}). 5122 5123This file is used only if the @samp{print_pid} option is on 5124(@pxref{print_pid Parameter}). 5125 5126@c ---------------------------------------------------------------- 5127@node plock Parameter, portmap_program Parameter, pid_file Parameter, Global Parameters 5128@comment node-name, next, previous, up 5129@subsection @t{plock} Parameter 5130@cindex plock Parameter 5131 5132(type=boolean, default=@samp{yes}). Same as the @code{-S} option to @i{Amd}. 5133If @samp{yes}, lock the running executable pages of @i{Amd} into memory. 5134To improve @i{Amd}'s performance, systems that support the @b{plock}(3) 5135or @b{mlockall}(2) 5136call can lock the @i{Amd} process into memory. This way there is less 5137chance the operating system will schedule, page out, and swap the 5138@i{Amd} process as needed. This improves @i{Amd}'s performance, at the 5139cost of reserving the memory used by the @i{Amd} process (making it 5140unavailable for other processes). 5141 5142@c ---------------------------------------------------------------- 5143@node portmap_program Parameter, preferred_amq_port Parameter, plock Parameter, Global Parameters 5144@comment node-name, next, previous, up 5145@subsection @t{portmap_program} Parameter 5146@cindex portmap_program Parameter 5147 5148(type=numeric, default=300019). Specify an alternate Port-mapper RPC 5149program number, other than the official number. This is useful when 5150running multiple @i{Amd} processes. For example, you can run another 5151@i{Amd} in ``test'' mode, without affecting the primary @i{Amd} process 5152in any way. For safety reasons, the alternate program numbers that can 5153be specified must be in the range 300019-300029, inclusive. @i{Amq} has 5154an option @code{-P} which can be used to specify an alternate program 5155number of an @i{Amd} to contact. In this way, amq can fully control any 5156number of @i{Amd} processes running on the same host. 5157 5158@c ---------------------------------------------------------------- 5159@node preferred_amq_port Parameter, print_pid Parameter, portmap_program Parameter, Global Parameters 5160@comment node-name, next, previous, up 5161@subsection @t{preferred_amq_port} Parameter 5162@cindex preferred_amq_port Parameter 5163 5164(type=numeric, default=0). Specify an alternate Port-mapper RPC port 5165number for @i{Amd}'s @i{Amq} service. This is used for both UDP and 5166TCP. Setting this value to 0 (or not defining it) will cause @i{Amd} 5167to select an arbitrary port number. Setting the @i{Amq} RPC service 5168port to a specific number is useful in firewalled or NAT'ed 5169environments, where you need to know which port @i{Amd} will listen 5170on. 5171 5172@c ---------------------------------------------------------------- 5173@node print_pid Parameter, print_version Parameter, preferred_amq_port Parameter, Global Parameters 5174@comment node-name, next, previous, up 5175@subsection @t{print_pid} Parameter 5176@cindex print_pid Parameter 5177 5178(type=boolean, default=@samp{no}). Same as the @code{-p} option to @i{Amd}. 5179If @samp{yes}, @i{Amd} will print its process ID upon starting. 5180 5181@c ---------------------------------------------------------------- 5182@node print_version Parameter, restart_mounts Parameter, print_pid Parameter, Global Parameters 5183@comment node-name, next, previous, up 5184@subsection @t{print_version} Parameter 5185@cindex print_version Parameter 5186 5187(type=boolean, default=@samp{no}). Same as the @code{-v} option to @i{Amd}, 5188but the version prints and @i{Amd} continues to run. If @samp{yes}, @i{Amd} 5189will print its version information string, which includes some 5190configuration and compilation values. 5191 5192@c ---------------------------------------------------------------- 5193@node restart_mounts Parameter, show_statfs_entries Parameter, print_version Parameter, Global Parameters 5194@comment node-name, next, previous, up 5195@subsection @t{restart_mounts} Parameter 5196@cindex restart_mounts Parameter 5197 5198(type=boolean, default=@samp{no}). Same as the @code{-r} option to @i{Amd}. 5199If @samp{yes} @i{Amd} will scan the mount table to determine which file 5200systems are currently mounted. Whenever one of these would have been 5201auto-mounted, @i{Amd} inherits it. 5202 5203@c ---------------------------------------------------------------- 5204@node show_statfs_entries Parameter, truncate_log Parameter, restart_mounts Parameter, Global Parameters 5205@comment node-name, next, previous, up 5206@subsection @t{show_statfs_entries} Parameter 5207@cindex show_statfs_entries Parameter 5208 5209(type=boolean), default=@samp{no}). If @samp{yes}, then all maps which are 5210browsable will also show the number of entries (keys) they have when 5211@b{df}(1) runs. (This is accomplished by returning non-zero values to 5212the @b{statfs}(2) system call). 5213 5214@c ---------------------------------------------------------------- 5215@node truncate_log Parameter, unmount_on_exit Parameter, show_statfs_entries Parameter, Global Parameters 5216@comment node-name, next, previous, up 5217@subsection @t{truncate_log} Parameter 5218@cindex truncate_log Parameter 5219 5220(type=boolean), default=@samp{no}). If @samp{yes}, then @i{Amd} will 5221truncate the log file (if it's a regular file) on startup. This could 5222be useful when conducting extensive testing on @i{Amd} maps (or 5223@i{Amd} itself) and you don't want to see log data from a previous run 5224in the same file. 5225 5226@c ---------------------------------------------------------------- 5227@node unmount_on_exit Parameter, use_tcpwrappers Parameter, truncate_log Parameter, Global Parameters 5228@comment node-name, next, previous, up 5229@subsection @t{unmount_on_exit} Parameter 5230@cindex unmount_on_exit Parameter 5231 5232(type=boolean, default=@samp{no}). If @samp{yes}, then @i{Amd} will attempt 5233to unmount all file systems which it knows about. Normally it leaves 5234all (esp. NFS) mounted file systems intact. Note that @i{Amd} does not 5235know about file systems mounted before it starts up, unless the 5236@samp{restart_mounts} option is used (@pxref{restart_mounts Parameter}). 5237 5238@c ---------------------------------------------------------------- 5239@node use_tcpwrappers Parameter, vendor Parameter, unmount_on_exit Parameter, Global Parameters 5240@comment node-name, next, previous, up 5241@subsection @t{use_tcpwrappers} Parameter 5242@cindex use_tcpwrappers Parameter 5243 5244(type=boolean), default=@samp{yes}). If @samp{yes}, then amd will use 5245the tcpwrappers (tcpd/librwap) library (if available) to control 5246access to @i{Amd} via the @code{/etc/hosts.allow} and 5247@code{/etc/hosts.deny} files. @i{Amd} will verify that the host 5248running @i{Amq} is authorized to connect. The @code{amd} service name 5249must used in the @code{/etc/hosts.allow} and @code{/etc/hosts.deny} 5250files. For example, to allow only localhost to connect to @i{Amd}, 5251add this line to @code{/etc/hosts.allow}: 5252 5253@example 5254amd: localhost 5255@end example 5256 5257and this line to @code{/etc/hosts.deny}: 5258 5259@example 5260amd: ALL 5261@end example 5262 5263Consult the man pages for @b{hosts_access}(5) for more information on using 5264the tcpwrappers access-control library. 5265 5266Note that in particular, you should not configure your @code{hosts.allow} 5267file to spawn a command for @i{Amd}: that will cause @i{Amd} to not be able 5268to @code{waitpid} on the child process ID of any background un/mount that 5269@i{Amd} issued, resulting in a confused @i{Amd} that does not know what 5270happened to those background un/mount requests. 5271 5272@c ---------------------------------------------------------------- 5273@node vendor Parameter, , use_tcpwrappers Parameter, Global Parameters 5274@comment node-name, next, previous, up 5275@subsection @t{vendor} Parameter 5276@cindex vendor Parameter 5277 5278(type=string, default to compiled in value). The name of the vendor of 5279the operating system. Overrides the compiled-in vendor name. Useful 5280when the compiled-in name is not desired. For example, most Intel based 5281systems set the vendor name to @samp{unknown}, but you can set it to 5282@samp{redhat}. 5283 5284@c ================================================================ 5285@node Regular Map Parameters, amd.conf Examples, Global Parameters, Amd Configuration File 5286@comment node-name, next, previous, up 5287@section Regular Map Parameters 5288@cindex amd.conf regular map parameters 5289 5290The following parameters are applicable only to regular map sections. 5291 5292@menu 5293* map_name Parameter:: 5294* tag Parameter:: 5295@end menu 5296 5297@c ---------------------------------------------------------------- 5298@node map_name Parameter, tag Parameter, Regular Map Parameters, Regular Map Parameters 5299@comment node-name, next, previous, up 5300@subsection map_name Parameter 5301@cindex map_name Parameter 5302 5303(type=string, must be specified). Name of the map where the keys are 5304located. 5305 5306@c ---------------------------------------------------------------- 5307@node tag Parameter, , map_name Parameter, Regular Map Parameters 5308@comment node-name, next, previous, up 5309@subsection tag Parameter 5310@cindex tag Parameter 5311 5312(type=string, default no tag). Each map entry in the configuration file 5313can be tagged. If no tag is specified, that map section will always be 5314processed by @i{Amd}. If it is specified, then @i{Amd} will process the map 5315if the @code{-T} option was given to @i{Amd}, and the value given to that 5316command-line option matches that in the map section. 5317 5318@c ================================================================ 5319@node amd.conf Examples, , Regular Map Parameters, Amd Configuration File 5320@comment node-name, next, previous, up 5321@section amd.conf Examples 5322@cindex amd.conf examples 5323 5324The following is the actual @code{amd.conf} file I used at the 5325Computer Science Department of Columbia University. 5326 5327@example 5328# GLOBAL OPTIONS SECTION 5329[ global ] 5330normalize_hostnames = no 5331print_pid = no 5332#pid_file = /var/run/amd.pid 5333restart_mounts = yes 5334#unmount_on_exit = yes 5335auto_dir = /n 5336log_file = /var/log/amd 5337log_options = all 5338#debug_options = defaults 5339plock = no 5340selectors_in_defaults = yes 5341# config.guess picks up "sunos5" and I don't want to edit my maps yet 5342os = sos5 5343# if you print_version after setting up "os", it will show it. 5344print_version = no 5345map_type = file 5346search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib 5347browsable_dirs = yes 5348fully_qualified_hosts = no 5349 5350# DEFINE AN AMD MOUNT POINT 5351[ /u ] 5352map_name = amd.u 5353 5354[ /proj ] 5355map_name = amd.proj 5356 5357[ /src ] 5358map_name = amd.src 5359 5360[ /misc ] 5361map_name = amd.misc 5362 5363[ /import ] 5364map_name = amd.import 5365 5366[ /tftpboot/.amd ] 5367tag = tftpboot 5368map_name = amd.tftpboot 5369@end example 5370 5371@c ################################################################ 5372@node Run-time Administration, FSinfo, Amd Configuration File, Top 5373@comment node-name, next, previous, up 5374@chapter Run-time Administration 5375@cindex Run-time administration 5376@cindex Amq command 5377 5378@menu 5379* Starting Amd:: 5380* Stopping Amd:: 5381* Restarting Amd:: 5382* Controlling Amd:: 5383@end menu 5384 5385@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration 5386@comment node-name, next, previous, up 5387@section Starting @i{Amd} 5388@cindex Starting Amd 5389@cindex Additions to /etc/rc.local 5390@cindex /etc/rc.local additions 5391@cindex ctl-amd 5392 5393@i{Amd} is best started from @samp{/etc/rc.local} on BSD systems, or 5394from the appropriate start-level script in @samp{/etc/init.d} on System V 5395systems. 5396 5397@example 5398if [ -f /usr/local/sbin/ctl-amd ]; then 5399 /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console 5400fi 5401@end example 5402 5403@noindent 5404The shell script, @samp{ctl-amd} is used to start, stop, or restart 5405@i{Amd}. It is a relatively generic script. All options you want to 5406set should not be made in this script, but rather updated in the 5407@file{amd.conf} file. @xref{Amd Configuration File}. 5408 5409If you do not wish to use an @i{Amd} configuration file, you may start 5410@i{Amd} manually. For example, getting the map entries via NIS: 5411 5412@example 5413amd -r -l /var/log/amd `ypcat -k auto.master` 5414@end example 5415 5416@node Stopping Amd, Restarting Amd, Starting Amd, Run-time Administration 5417@comment node-name, next, previous, up 5418@section Stopping @i{Amd} 5419@cindex Stopping Amd 5420@cindex SIGTERM signal 5421@cindex SIGINT signal 5422 5423@i{Amd} stops in response to two signals. 5424 5425@table @samp 5426@item SIGTERM 5427causes the top-level automount points to be unmounted and then @i{Amd} 5428to exit. Any automounted filesystems are left mounted. They can be 5429recovered by restarting @i{Amd} with the @code{-r} command line option.@refill 5430 5431@item SIGINT 5432causes @i{Amd} to attempt to unmount any filesystems which it has 5433automounted, in addition to the actions of @samp{SIGTERM}. This signal 5434is primarily used for debugging.@refill 5435@end table 5436 5437Actions taken for other signals are undefined. 5438 5439The easiest and safest way to stop @i{Amd}, without having to find its 5440process ID by hand, is to use the @file{ctl-amd} script, as with: 5441 5442@example 5443ctl-amd stop 5444@end example 5445 5446@node Restarting Amd, Controlling Amd, Stopping Amd, Run-time Administration 5447@comment node-name, next, previous, up 5448@section Restarting @i{Amd} 5449@cindex Restarting Amd 5450@cindex Killing and starting Amd 5451 5452Before @i{Amd} can be started, it is vital to ensure that no other 5453@i{Amd} processes are managing any of the mount points, and that the 5454previous process(es) have terminated cleanly. When a terminating signal 5455is set to @i{Amd}, the automounter does @emph{not} terminate right then. 5456Rather, it starts by unmounting all of its managed mount mounts in the 5457background, and then terminates. It usually takes a few seconds for 5458this process to happen, but it can take an arbitrarily longer time. If 5459two or more @i{Amd} processes attempt to manage the same mount point, it 5460usually will result in a system lockup. 5461 5462The easiest and safest way to restart @i{Amd}, without having to find 5463its process ID by hand, sending it the @samp{SIGTERM} signal, waiting for @i{Amd} 5464to die cleanly, and verifying so, is to use the @file{ctl-amd} script, 5465as with: 5466 5467@example 5468ctl-amd restart 5469@end example 5470 5471The script will locate the process ID of @i{Amd}, kill it, and wait for 5472it to die cleanly before starting a new instance of the automounter. 5473@file{ctl-amd} will wait for a total of 30 seconds for @i{Amd} to die, 5474and will check once every 5 seconds if it had. 5475 5476@node Controlling Amd, , Restarting Amd, Run-time Administration 5477@comment node-name, next, previous, up 5478@section Controlling @i{Amd} 5479@cindex Controlling Amd 5480@cindex Discovering what is going on at run-time 5481@cindex Listing currently mounted filesystems 5482 5483It is sometimes desirable or necessary to exercise external control 5484over some of @i{Amd}'s internal state. To support this requirement, 5485@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. 5486A variety of information is available. 5487 5488@i{Amq} generally applies an operation, specified by a single letter option, 5489to a list of mount points. The default operation is to obtain statistics 5490about each mount point. This is similar to the output shown above 5491but includes information about the number and type of accesses to each 5492mount point. 5493 5494@menu 5495* Amq default:: Default command behavior. 5496* Amq -f option:: Flushing the map cache. 5497* Amq -h option:: Controlling a non-local host. 5498* Amq -H option:: Print help message. 5499* Amq -l option:: Controlling the log file. 5500* Amq -m option:: Obtaining mount statistics. 5501* Amq -p option:: Getting Amd's process ID. 5502* Amq -P option:: Contacting alternate Amd processes. 5503* Amq -q option:: Suppress synchronous unmounting errors. 5504* Amq -s option:: Obtaining global statistics. 5505* Amq -T option:: Use TCP transport. 5506* Amq -U option:: Use UDP transport. 5507* Amq -u option:: Forcing volumes to time out. 5508* Amq -v option:: Version information. 5509* Amq -w option:: Print Amd current working directory. 5510* Other Amq options:: Three other special options. 5511@end menu 5512 5513@c ---------------------------------------------------------------- 5514@node Amq default, Amq -f option, Controlling Amd, Controlling Amd 5515@comment node-name, next, previous, up 5516@subsection @i{Amq} default information 5517 5518With no arguments, @dfn{Amq} obtains a brief list of all existing 5519mounts created by @i{Amd}. This is different from the list displayed by 5520@b{df}(1) since the latter only includes system mount points. 5521 5522@noindent 5523The output from this option includes the following information: 5524 5525@itemize @bullet 5526@item 5527the automount point, 5528@item 5529the filesystem type, 5530@item 5531the mount map or mount information, 5532@item 5533the internal, or system mount point. 5534@end itemize 5535 5536@noindent 5537For example: 5538 5539@example 5540/ root "root" sky:(pid75) 5541/homes toplvl /usr/local/etc/amd.homes /homes 5542/home toplvl /usr/local/etc/amd.home /home 5543/homes/jsp nfs charm:/home/charm /a/charm/home/charm/jsp 5544/homes/phjk nfs toytown:/home/toytown /a/toytown/home/toytown/ai/phjk 5545@end example 5546 5547@noindent 5548If an argument is given then statistics for that volume name will 5549be output. For example: 5550 5551@example 5552What Uid Getattr Lookup RdDir RdLnk Statfs Mounted@@ 5553/homes 0 1196 512 22 0 30 90/09/14 12:32:55 5554/homes/jsp 0 0 0 0 1180 0 90/10/13 12:56:58 5555@end example 5556 5557@table @code 5558@item What 5559the volume name. 5560 5561@item Uid 5562ignored. 5563 5564@item Getattr 5565the count of NFS @dfn{getattr} requests on this node. This should only be 5566non-zero for directory nodes. 5567 5568@item Lookup 5569the count of NFS @dfn{lookup} requests on this node. This should only be 5570non-zero for directory nodes. 5571 5572@item RdDir 5573the count of NFS @dfn{readdir} requests on this node. This should only 5574be non-zero for directory nodes. 5575 5576@item RdLnk 5577the count of NFS @dfn{readlink} requests on this node. This should be 5578zero for directory nodes. 5579 5580@item Statfs 5581the count of NFS @dfn{statfs} requests on this node. This should only 5582be non-zero for top-level automount points. 5583 5584@item Mounted@@ 5585the date and time the volume name was first referenced. 5586@end table 5587 5588@c ---------------------------------------------------------------- 5589@node Amq -f option, Amq -h option, Amq default, Controlling Amd 5590@comment node-name, next, previous, up 5591@subsection @i{Amq} @code{-f} option 5592@cindex Flushing the map cache 5593@cindex Map cache, flushing 5594 5595The @code{-f} option causes @i{Amd} to flush the internal mount map cache. 5596This is useful for example in Hesiod maps since @i{Amd} will not 5597automatically notice when they have been updated. The map cache can 5598also be synchronized with the map source by using the @samp{sync} option 5599(@pxref{Automount Filesystem}).@refill 5600 5601@c ---------------------------------------------------------------- 5602@node Amq -h option, Amq -H option, Amq -f option, Controlling Amd 5603@comment node-name, next, previous, up 5604@subsection @i{Amq} @code{-h} option 5605@cindex Querying an alternate host 5606 5607By default the local host is used. In an HP-UX cluster the root server 5608is used since that is the only place in the cluster where @i{Amd} will 5609be running. To query @i{Amd} on another host the @code{-h} option should 5610be used. 5611 5612@c ---------------------------------------------------------------- 5613@node Amq -H option, Amq -l option, Amq -h option, Controlling Amd 5614@comment node-name, next, previous, up 5615@subsection @i{Amq} @code{-H} option 5616@cindex Displaying brief help 5617@cindex Help; showing from Amq 5618 5619Print a brief help and usage string. 5620 5621@c ---------------------------------------------------------------- 5622@node Amq -l option, Amq -m option, Amq -H option, Controlling Amd 5623@comment node-name, next, previous, up 5624@subsection @i{Amq} @code{-l} option 5625@cindex Resetting the Amd log file 5626@cindex Setting the Amd log file via Amq 5627@cindex Log file, resetting 5628 5629Tell @i{Amd} to use @i{log_file} as the log file name. For security 5630reasons, this @emph{must} be the same log file which @i{Amd} used when 5631started. This option is therefore only useful to refresh @i{Amd}'s open 5632file handle on the log file, so that it can be rotated and compressed 5633via daily cron jobs. 5634 5635@c ---------------------------------------------------------------- 5636@node Amq -m option, Amq -p option, Amq -l option, Controlling Amd 5637@comment node-name, next, previous, up 5638@subsection @i{Amq} @code{-m} option 5639 5640The @code{-m} option displays similar information about mounted 5641filesystems, rather than automount points. The output includes the 5642following information: 5643 5644@itemize @bullet 5645@item 5646the mount information, 5647@item 5648the mount point, 5649@item 5650the filesystem type, 5651@item 5652the number of references to this filesystem, 5653@item 5654the server hostname, 5655@item 5656the state of the file server, 5657@item 5658any error which has occurred. 5659@end itemize 5660 5661For example: 5662 5663@example 5664"root" truth:(pid602) root 1 localhost is up 5665hesiod.home /home toplvl 1 localhost is up 5666hesiod.vol /vol toplvl 1 localhost is up 5667hesiod.homes /homes toplvl 1 localhost is up 5668amy:/home/amy /a/amy/home/amy nfs 5 amy is up 5669swan:/home/swan /a/swan/home/swan nfs 0 swan is up (Permission denied) 5670ex:/home/ex /a/ex/home/ex nfs 0 ex is down 5671@end example 5672 5673When the reference count is zero the filesystem is not mounted but 5674the mount point and server information is still being maintained 5675by @i{Amd}. 5676 5677@c ---------------------------------------------------------------- 5678@ignore 5679@comment Retained for future consideration: from the description of the 5680@comment amq -M option removed in amd 6.0.5. 5681 5682A future release of @i{Amd} will include code to allow the @b{mount}(8) 5683command to mount automount points: 5684 5685@example 5686mount -t amd /vol hesiod.vol 5687@end example 5688 5689This will then allow @i{Amd} to be controlled from the standard system 5690filesystem mount list. 5691 5692@end ignore 5693 5694@c ---------------------------------------------------------------- 5695@node Amq -p option, Amq -P option, Amq -m option, Controlling Amd 5696@comment node-name, next, previous, up 5697@subsection @i{Amq} @code{-p} option 5698@cindex Process ID; Amd 5699@cindex Amd's process ID 5700@cindex Amd's PID 5701@cindex PID; Amd 5702 5703Return the process ID of the remote or locally running @i{Amd}. Useful 5704when you need to send a signal to the local @i{Amd} process, and would 5705rather not have to search through the process table. This option is 5706used in the @file{ctl-amd} script. 5707 5708@c ---------------------------------------------------------------- 5709@node Amq -P option, Amq -q option, Amq -p option, Controlling Amd 5710@comment node-name, next, previous, up 5711@subsection @i{Amq} @code{-P} option 5712@cindex Multiple Amd processes 5713@cindex Running multiple Amd 5714@cindex Debugging a new Amd configuration 5715@cindex RPC Program numbers; Amd 5716 5717Contact an alternate running @i{Amd} that had registered itself on a 5718different RPC @var{program_number} and apply all other operations to 5719that instance of the automounter. This is useful when you run multiple 5720copies of @i{Amd}, and need to manage each one separately. If not 5721specified, @i{Amq} will use the default program number for @i{Amd}, 300019. 5722For security reasons, the only alternate program numbers @i{Amd} can use 5723range from 300019 to 300029, inclusive. 5724 5725For example, to kill an alternate running @i{Amd}: 5726 5727@example 5728kill `amq -p -P 300020` 5729@end example 5730 5731@c ---------------------------------------------------------------- 5732@node Amq -q option, Amq -s option, Amq -P option, Controlling Amd 5733@comment node-name, next, previous, up 5734@subsection @i{Amq} @code{-q} option 5735@cindex Unmounting a filesystem 5736 5737Suppress any error messages produced when a synchronous unmount fails. 5738See @ref{Amq -u option}. 5739 5740@c ---------------------------------------------------------------- 5741@node Amq -s option, Amq -T option, Amq -q option, Controlling Amd 5742@comment node-name, next, previous, up 5743@subsection @i{Amq} @code{-s} option 5744@cindex Global statistics 5745@cindex Statistics 5746 5747The @code{-s} option displays global statistics. If any other options are specified 5748or any filesystems named then this option is ignored. For example: 5749 5750@example 5751requests stale mount mount unmount 5752deferred fhandles ok failed failed 57531054 1 487 290 7017 5754@end example 5755 5756@table @samp 5757@item Deferred requests 5758are those for which an immediate reply could not be constructed. For 5759example, this would happen if a background mount was required. 5760 5761@item Stale filehandles 5762counts the number of times the kernel passes a stale filehandle to @i{Amd}. 5763Large numbers indicate problems. 5764 5765@item Mount ok 5766counts the number of automounts which were successful. 5767 5768@item Mount failed 5769counts the number of automounts which failed. 5770 5771@item Unmount failed 5772counts the number of times a filesystem could not be unmounted. Very 5773large numbers here indicate that the time between unmount attempts 5774should be increased. 5775@end table 5776 5777@c ---------------------------------------------------------------- 5778@node Amq -T option, Amq -U option, Amq -s option, Controlling Amd 5779@comment node-name, next, previous, up 5780@subsection @i{Amq} @code{-T} option 5781@cindex Forcing Amq to use a TCP transport 5782@cindex TCP; using with Amq 5783 5784The @code{-T} option causes the @i{Amq} to contact @i{Amd} using the TCP 5785transport only (connection oriented). Normally, @i{Amq} will use TCP 5786first, and if that failed, will try UDP. 5787 5788@c ---------------------------------------------------------------- 5789@node Amq -U option, Amq -u option, Amq -T option, Controlling Amd 5790@comment node-name, next, previous, up 5791@subsection @i{Amq} @code{-U} option 5792@cindex Forcing Amq to use a UDP transport 5793@cindex UDP; using with Amq 5794 5795The @code{-U} option causes the @i{Amq} to contact @i{Amd} using the UDP 5796transport only (connectionless). Normally, @i{Amq} will use TCP first, 5797and if that failed, will try UDP. 5798 5799@c ---------------------------------------------------------------- 5800@node Amq -u option, Amq -v option, Amq -U option, Controlling Amd 5801@comment node-name, next, previous, up 5802@subsection @i{Amq} @code{-u} option 5803@cindex Forcing filesystem to time out 5804@cindex Unmounting a filesystem 5805 5806The @code{-u} option causes the time-to-live interval of the named 5807mount points to be expired, thus causing an unmount attempt. This is 5808the only safe way to unmount an automounted filesystem. If @code{-u} 5809is repeated, then @i{Amd} will attempt to unmount the filesystem 5810synchronously. This makes things like 5811 5812@example 5813amq -uu /t/cd0d && eject cd0 5814@end example 5815 5816@noindent 5817work as expected. Any error messages this might produce can be 5818suppressed with the @code{-q} option. See @ref{Amq -q option}. 5819 5820@c The @code{-H} option informs @i{Amd} that the specified mount point 5821@c has hung - as if its keepalive timer had expired. 5822 5823@c ---------------------------------------------------------------- 5824@node Amq -v option, Amq -w option, Amq -u option, Controlling Amd 5825@comment node-name, next, previous, up 5826@subsection @i{Amq} @code{-v} option 5827@cindex Version information at run-time 5828 5829The @code{-v} option displays the version of @i{Amd} in a similar way to 5830@i{Amd}'s @code{-v} option. 5831 5832@c ---------------------------------------------------------------- 5833@node Amq -w option, Other Amq options, Amq -v option, Controlling Amd 5834@comment node-name, next, previous, up 5835@subsection @i{Amq} @code{-w} option 5836@cindex Getting real working directory 5837 5838The @code{-w} option translates a full pathname as returned by 5839@b{getpwd}(3) into a short @i{Amd} pathname that goes through its mount 5840points. This option requires that @i{Amd} is running. 5841 5842@c ---------------------------------------------------------------- 5843@node Other Amq options, , Amq -w option, Controlling Amd 5844@comment node-name, next, previous, up 5845@subsection Other @i{Amq} options 5846@cindex Logging options via Amq 5847@cindex Debugging options via Amq 5848 5849Two other operations are implemented. These modify the state of @i{Amd} 5850as a whole, rather than any particular filesystem. The @code{-x} and 5851@code{-D} options have exactly the same effect as @i{Amd}'s corresponding 5852command line options. 5853 5854When @i{Amd} receives the @code{-x} flag, it disallows turning off the 5855@samp{fatal} or @samp{error} flags. Both are on by default. They are 5856mandatory so that @i{Amd} could report important errors, including 5857errors relating to turning flags on/off. 5858 5859@c ################################################################ 5860@node FSinfo, Hlfsd, Run-time Administration, Top 5861@comment node-name, next, previous, up 5862@chapter FSinfo 5863@cindex FSinfo 5864@cindex Filesystem info package 5865 5866XXX: this chapter should be reviewed by someone knowledgeable with 5867fsinfo. 5868 5869@menu 5870* FSinfo Overview:: Introduction to FSinfo. 5871* Using FSinfo:: Basic concepts. 5872* FSinfo Grammar:: Language syntax, semantics and examples. 5873* FSinfo host definitions:: Defining a new host. 5874* FSinfo host attributes:: Definable host attributes. 5875* FSinfo filesystems:: Defining locally attached filesystems. 5876* FSinfo static mounts:: Defining additional static mounts. 5877* FSinfo automount definitions:: 5878* FSinfo Command Line Options:: 5879* FSinfo errors:: 5880@end menu 5881 5882@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo 5883@comment node-name, next, previous, up 5884@section @i{FSinfo} overview 5885@cindex FSinfo overview 5886 5887@i{FSinfo} is a filesystem management tool. It has been designed to 5888work with @i{Amd} to help system administrators keep track of the ever 5889increasing filesystem namespace under their control. 5890 5891The purpose of @i{FSinfo} is to generate all the important standard 5892filesystem data files from a single set of input data. Starting with a 5893single data source guarantees that all the generated files are 5894self-consistent. One of the possible output data formats is a set of 5895@i{Amd} maps which can be used among the set of hosts described in the 5896input data. 5897 5898@i{FSinfo} implements a declarative language. This language is 5899specifically designed for describing filesystem namespace and physical 5900layouts. The basic declaration defines a mounted filesystem including 5901its device name, mount point, and all the volumes and access 5902permissions. @i{FSinfo} reads this information and builds an internal 5903map of the entire network of hosts. Using this map, many different data 5904formats can be produced including @file{/etc/fstab}, 5905@file{/etc/exports}, @i{Amd} mount maps and 5906@file{/etc/bootparams}.@refill 5907 5908@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo 5909@comment node-name, next, previous, up 5910@section Using @i{FSinfo} 5911@cindex Using FSinfo 5912 5913The basic strategy when using @i{FSinfo} is to gather all the 5914information about all disks on all machines into one set of 5915declarations. For each machine being managed, the following data is 5916required: 5917 5918@itemize @bullet 5919@item 5920Hostname 5921@item 5922List of all filesystems and, optionally, their mount points. 5923@item 5924Names of volumes stored on each filesystem. 5925@item 5926NFS export information for each volume. 5927@item 5928The list of static filesystem mounts. 5929@end itemize 5930 5931The following information can also be entered into the same 5932configuration files so that all data can be kept in one place. 5933 5934@itemize @bullet 5935@item 5936List of network interfaces 5937@item 5938IP address of each interface 5939@item 5940Hardware address of each interface 5941@item 5942Dumpset to which each filesystem belongs 5943@item 5944and more @dots{} 5945@end itemize 5946 5947To generate @i{Amd} mount maps, the automount tree must also be defined 5948(@pxref{FSinfo automount definitions}). This will have been designed at 5949the time the volume names were allocated. Some volume names will not be 5950automounted, so @i{FSinfo} needs an explicit list of which volumes 5951should be automounted.@refill 5952 5953Hostnames are required at several places in the @i{FSinfo} language. It 5954is important to stick to either fully qualified names or unqualified 5955names. Using a mixture of the two will inevitably result in confusion. 5956 5957Sometimes volumes need to be referenced which are not defined in the set 5958of hosts being managed with @i{FSinfo}. The required action is to add a 5959dummy set of definitions for the host and volume names required. Since 5960the files generated for those particular hosts will not be used on them, 5961the exact values used is not critical. 5962 5963@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo 5964@comment node-name, next, previous, up 5965@section @i{FSinfo} grammar 5966@cindex FSinfo grammar 5967@cindex Grammar, FSinfo 5968 5969@i{FSinfo} has a relatively simple grammar. Distinct syntactic 5970constructs exist for each of the different types of data, though they 5971share a common flavor. Several conventions are used in the grammar 5972fragments below. 5973 5974The notation, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more 5975@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one 5976@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input 5977tokens. Items in angle brackets, @i{eg} @var{<hostname>}, represent 5978strings in the input. Strings need not be in double quotes, except to 5979differentiate them from reserved words. Quoted strings may include the 5980usual set of C ``@t{\}'' escape sequences with one exception: a 5981backslash-newline-whitespace sequence is squashed into a single space 5982character. To defeat this feature, put a further backslash at the start 5983of the second line. 5984 5985At the outermost level of the grammar, the input consists of a 5986sequence of host and automount declarations. These declarations are 5987all parsed before they are analyzed. This means they can appear in 5988any order and cyclic host references are possible. 5989 5990@example 5991fsinfo : @i{list(}fsinfo_attr@i{)} ; 5992 5993fsinfo_attr : host | automount ; 5994@end example 5995 5996@menu 5997* FSinfo host definitions:: 5998* FSinfo automount definitions:: 5999@end menu 6000 6001@node FSinfo host definitions, FSinfo host attributes, FSinfo Grammar, FSinfo 6002@comment node-name, next, previous, up 6003@section @i{FSinfo} host definitions 6004@cindex FSinfo host definitions 6005@cindex Defining a host, FSinfo 6006 6007A host declaration consists of three parts: a set of machine attribute 6008data, a list of filesystems physically attached to the machine, and a 6009list of additional statically mounted filesystems. 6010 6011@example 6012host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; 6013@end example 6014 6015Each host must be declared in this way exactly once. Such things as the 6016hardware address, the architecture and operating system types and the 6017cluster name are all specified within the @dfn{host data}. 6018 6019All the disks the machine has should then be described in the @dfn{list 6020of filesystems}. When describing disks, you can specify what 6021@dfn{volname} the disk/partition should have and all such entries are 6022built up into a dictionary which can then be used for building the 6023automounter maps. 6024 6025The @dfn{list of mounts} specifies all the filesystems that should be 6026statically mounted on the machine. 6027 6028@menu 6029* FSinfo host attributes:: 6030* FSinfo filesystems:: 6031* FSinfo static mounts:: 6032@end menu 6033 6034@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions 6035@comment node-name, next, previous, up 6036@section @i{FSinfo} host attributes 6037@cindex FSinfo host attributes 6038@cindex Defining host attributes, FSinfo 6039 6040The host data, @dfn{host_data}, always includes the @dfn{hostname}. In 6041addition, several other host attributes can be given. 6042 6043@example 6044host_data : @var{<hostname>} 6045 | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} 6046 ; 6047 6048host_attrs : host_attr "=" @var{<string>} 6049 | netif 6050 ; 6051 6052host_attr : "config" 6053 | "arch" 6054 | "os" 6055 | "cluster" 6056 ; 6057@end example 6058 6059The @dfn{hostname} is, typically, the fully qualified hostname of the 6060machine. 6061 6062Examples: 6063 6064@example 6065host dylan.doc.ic.ac.uk 6066 6067host @{ 6068 os = hpux 6069 arch = hp300 6070@} dougal.doc.ic.ac.uk 6071@end example 6072 6073The options that can be given as host attributes are shown below. 6074 6075@menu 6076* FSinfo netif Option:: FSinfo host netif. 6077* FSinfo config Option:: FSinfo host config. 6078* FSinfo arch Option:: FSinfo host arch. 6079* FSinfo os Option:: FSinfo host os. 6080* FSinfo cluster Option:: FSinfo host cluster. 6081@end menu 6082 6083@node FSinfo netif Option, FSinfo config Option, , FSinfo host attributes 6084@comment node-name, next, previous, up 6085@subsection netif Option 6086 6087This defines the set of network interfaces configured on the machine. 6088The interface attributes collected by @i{FSinfo} are the IP address, 6089subnet mask and hardware address. Multiple interfaces may be defined 6090for hosts with several interfaces by an entry for each interface. The 6091values given are sanity checked, but are currently unused for anything 6092else. 6093 6094@example 6095netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; 6096 6097netif_attrs : netif_attr "=" @var{<string>} ; 6098 6099netif_attr : "inaddr" | "netmask" | "hwaddr" ; 6100@end example 6101 6102Examples: 6103 6104@example 6105netif ie0 @{ 6106 inaddr = 129.31.81.37 6107 netmask = 0xfffffe00 6108 hwaddr = "08:00:20:01:a6:a5" 6109@} 6110 6111netif ec0 @{ @} 6112@end example 6113 6114@node FSinfo config Option, FSinfo arch Option, FSinfo netif Option, FSinfo host attributes 6115@comment node-name, next, previous, up 6116@subsection config Option 6117@cindex FSinfo config host attribute 6118@cindex config, FSinfo host attribute 6119 6120This option allows you to specify configuration variables for the 6121startup scripts (@file{rc} scripts). A simple string should immediately 6122follow the keyword. 6123 6124Example: 6125 6126@example 6127config "NFS_SERVER=true" 6128config "ZEPHYR=true" 6129@end example 6130 6131This option is currently unsupported. 6132 6133@node FSinfo arch Option, FSinfo os Option, FSinfo config Option, FSinfo host attributes 6134@comment node-name, next, previous, up 6135@subsection arch Option 6136@cindex FSinfo arch host attribute 6137@cindex arch, FSinfo host attribute 6138 6139This defines the architecture of the machine. For example: 6140 6141@example 6142arch = hp300 6143@end example 6144 6145This is intended to be of use when building architecture specific 6146mountmaps, however, the option is currently unsupported. 6147 6148@node FSinfo os Option, FSinfo cluster Option, FSinfo arch Option, FSinfo host attributes 6149@comment node-name, next, previous, up 6150@subsection os Option 6151@cindex FSinfo os host attribute 6152@cindex os, FSinfo host attribute 6153 6154This defines the operating system type of the host. For example: 6155 6156@example 6157os = hpux 6158@end example 6159 6160This information is used when creating the @file{fstab} files, for 6161example in choosing which format to use for the @file{fstab} entries 6162within the file. 6163 6164@node FSinfo cluster Option, , FSinfo os Option, FSinfo host attributes 6165@comment node-name, next, previous, up 6166@subsection cluster Option 6167@cindex FSinfo cluster host attribute 6168@cindex cluster, FSinfo host attribute 6169 6170This is used for specifying in which cluster the machine belongs. For 6171example: 6172 6173@example 6174cluster = "theory" 6175@end example 6176 6177The cluster is intended to be used when generating the automount maps, 6178although it is currently unsupported. 6179 6180@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions 6181@comment node-name, next, previous, up 6182@section @i{FSinfo} filesystems 6183@cindex FSinfo filesystems 6184 6185The list of physically attached filesystems follows the machine 6186attributes. These should define all the filesystems available from this 6187machine, whether exported or not. In addition to the device name, 6188filesystems have several attributes, such as filesystem type, mount 6189options, and @samp{fsck} pass number which are needed to generate 6190@file{fstab} entries. 6191 6192@example 6193filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; 6194 6195fs_data : fs_data_attr "=" @var{<string>} 6196 | mount 6197 ; 6198 6199fs_data_attr 6200 : "fstype" | "opts" | "passno" 6201 | "freq" | "dumpset" | "log" 6202 ; 6203@end example 6204 6205Here, @var{<device>} is the device name of the disk (for example, 6206@file{/dev/dsk/2s0}). The device name is used for building the mount 6207maps and for the @file{fstab} file. The attributes that can be 6208specified are shown in the following section. 6209 6210The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. 6211 6212@example 6213host dylan.doc.ic.ac.uk 6214 6215fs /dev/dsk/0s0 @{ 6216 fstype = swap 6217@} 6218 6219fs /dev/dsk/0s0 @{ 6220 fstype = hfs 6221 opts = rw,noquota,grpid 6222 passno = 0; 6223 freq = 1; 6224 mount / @{ @} 6225@} 6226 6227fs /dev/dsk/1s0 @{ 6228 fstype = hfs 6229 opts = defaults 6230 passno = 1; 6231 freq = 1; 6232 mount /usr @{ 6233 local @{ 6234 exportfs "dougal eden dylan zebedee brian" 6235 volname /nfs/hp300/local 6236 @} 6237 @} 6238@} 6239 6240fs /dev/dsk/2s0 @{ 6241 fstype = hfs 6242 opts = defaults 6243 passno = 1; 6244 freq = 1; 6245 mount default @{ 6246 exportfs "toytown_clients hangers_on" 6247 volname /home/dylan/dk2 6248 @} 6249@} 6250 6251fs /dev/dsk/3s0 @{ 6252 fstype = hfs 6253 opts = defaults 6254 passno = 1; 6255 freq = 1; 6256 mount default @{ 6257 exportfs "toytown_clients hangers_on" 6258 volname /home/dylan/dk3 6259 @} 6260@} 6261 6262fs /dev/dsk/5s0 @{ 6263 fstype = hfs 6264 opts = defaults 6265 passno = 1; 6266 freq = 1; 6267 mount default @{ 6268 exportfs "toytown_clients hangers_on" 6269 volname /home/dylan/dk5 6270 @} 6271@} 6272@end example 6273 6274@menu 6275* FSinfo fstype Option:: FSinfo filesystems fstype. 6276* FSinfo opts Option:: FSinfo filesystems opts. 6277* FSinfo passno Option:: FSinfo filesystems passno. 6278* FSinfo freq Option:: FSinfo filesystems freq. 6279* FSinfo mount Option:: FSinfo filesystems mount. 6280* FSinfo dumpset Option:: FSinfo filesystems dumpset. 6281* FSinfo log Option:: FSinfo filesystems log. 6282@end menu 6283 6284@node FSinfo fstype Option, FSinfo opts Option, , FSinfo filesystems 6285@comment node-name, next, previous, up 6286@subsection fstype Option 6287@cindex FSinfo fstype filesystems option 6288@cindex fstype, FSinfo filesystems option 6289@cindex export, FSinfo special fstype 6290 6291This specifies the type of filesystem being declared and will be placed 6292into the @file{fstab} file as is. The value of this option will be 6293handed to @code{mount} as the filesystem type---it should have such 6294values as @code{4.2}, @code{nfs} or @code{swap}. The value is not 6295examined for correctness. 6296 6297There is one special case. If the filesystem type is specified as 6298@samp{export} then the filesystem information will not be added to the 6299host's @file{fstab} information, but it will still be visible on the 6300network. This is useful for defining hosts which contain referenced 6301volumes but which are not under full control of @i{FSinfo}. 6302 6303Example: 6304 6305@example 6306fstype = swap 6307@end example 6308 6309@node FSinfo opts Option, FSinfo passno Option, FSinfo fstype Option, FSinfo filesystems 6310@comment node-name, next, previous, up 6311@subsection opts Option 6312@cindex FSinfo opts filesystems option 6313@cindex opts, FSinfo filesystems option 6314 6315This defines any options that should be given to @b{mount}(8) in the 6316@file{fstab} file. For example: 6317 6318@example 6319opts = rw,nosuid,grpid 6320@end example 6321 6322@node FSinfo passno Option, FSinfo freq Option, FSinfo opts Option, FSinfo filesystems 6323@comment node-name, next, previous, up 6324@subsection passno Option 6325@cindex FSinfo passno filesystems option 6326@cindex passno, FSinfo filesystems option 6327 6328This defines the @b{fsck}(8) pass number in which to check the 6329filesystem. This value will be placed into the @file{fstab} file. 6330 6331Example: 6332 6333@example 6334passno = 1 6335@end example 6336 6337@node FSinfo freq Option, FSinfo mount Option, FSinfo passno Option, FSinfo filesystems 6338@comment node-name, next, previous, up 6339@subsection freq Option 6340@cindex FSinfo freq filesystems option 6341@cindex freq, FSinfo filesystems option 6342 6343This defines the interval (in days) between dumps. The value is placed 6344as is into the @file{fstab} file. 6345 6346Example: 6347 6348@example 6349freq = 3 6350@end example 6351 6352@node FSinfo mount Option, FSinfo dumpset Option, FSinfo freq Option, FSinfo filesystems 6353@comment node-name, next, previous, up 6354@subsection mount Option 6355@cindex FSinfo mount filesystems option 6356@cindex mount, FSinfo filesystems option 6357@cindex exportfs, FSinfo mount option 6358@cindex volname, FSinfo mount option 6359@cindex sel, FSinfo mount option 6360 6361This defines the mountpoint at which to place the filesystem. If the 6362mountpoint of the filesystem is specified as @code{default}, then the 6363filesystem will be mounted in the automounter's tree under its volume 6364name and the mount will automatically be inherited by the automounter. 6365 6366Following the mountpoint, namespace information for the filesystem may 6367be described. The options that can be given here are @code{exportfs}, 6368@code{volname} and @code{sel}. 6369 6370The format is: 6371 6372@example 6373mount : "mount" vol_tree ; 6374 6375vol_tree : @i{list(}vol_tree_attr@i{)} ; 6376 6377vol_tree_attr 6378 : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; 6379 6380vol_tree_info 6381 : "exportfs" @var{<export-data>} 6382 | "volname" @var{<volname>} 6383 | "sel" @var{<selector-list>} 6384 ; 6385@end example 6386 6387Example: 6388 6389@example 6390mount default @{ 6391 exportfs "dylan dougal florence zebedee" 6392 volname /vol/andrew 6393@} 6394@end example 6395 6396In the above example, the filesystem currently being declared will have 6397an entry placed into the @file{exports} file allowing the filesystem to 6398be exported to the machines @code{dylan}, @code{dougal}, @code{florence} 6399and @code{zebedee}. The volume name by which the filesystem will be 6400referred to remotely, is @file{/vol/andrew}. By declaring the 6401mountpoint to be @code{default}, the filesystem will be mounted on the 6402local machine in the automounter tree, where @i{Amd} will automatically 6403inherit the mount as @file{/vol/andrew}.@refill 6404 6405@table @samp 6406@item exportfs 6407a string defining which machines the filesystem may be exported to. 6408This is copied, as is, into the @file{exports} file---no sanity checking 6409is performed on this string.@refill 6410 6411@item volname 6412a string which declares the remote name by which to reference the 6413filesystem. The string is entered into a dictionary and allows you to 6414refer to this filesystem in other places by this volume name.@refill 6415 6416@item sel 6417a string which is placed into the automounter maps as a selector for the 6418filesystem.@refill 6419 6420@end table 6421 6422@node FSinfo dumpset Option, FSinfo log Option, FSinfo mount Option, FSinfo filesystems 6423@comment node-name, next, previous, up 6424@subsection dumpset Option 6425@cindex FSinfo dumpset filesystems option 6426@cindex dumpset, FSinfo filesystems option 6427 6428This provides support for Imperial College's local file backup tools and 6429is not documented further here. 6430 6431@node FSinfo log Option, , FSinfo dumpset Option, FSinfo filesystems 6432@comment node-name, next, previous, up 6433@subsection log Option 6434@cindex FSinfo log filesystems option 6435@cindex log, FSinfo filesystems option 6436 6437Specifies the log device for the current filesystem. This is ignored if 6438not required by the particular filesystem type. 6439 6440@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions 6441@comment node-name, next, previous, up 6442@section @i{FSinfo} static mounts 6443@cindex FSinfo static mounts 6444@cindex Statically mounts filesystems, FSinfo 6445 6446Each host may also have a number of statically mounted filesystems. For 6447example, the host may be a diskless workstation in which case it will 6448have no @code{fs} declarations. In this case the @code{mount} 6449declaration is used to determine from where its filesystems will be 6450mounted. In addition to being added to the @file{fstab} file, this 6451information can also be used to generate a suitable @file{bootparams} 6452file.@refill 6453 6454@example 6455mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; 6456 6457localinfo : localinfo_attr @var{<string>} ; 6458 6459localinfo_attr 6460 : "as" 6461 | "from" 6462 | "fstype" 6463 | "opts" 6464 ; 6465@end example 6466 6467The filesystem specified to be mounted will be searched for in the 6468dictionary of volume names built when scanning the list of hosts' 6469definitions. 6470 6471The attributes have the following semantics: 6472@table @samp 6473@item from @var{machine} 6474mount the filesystem from the machine with the hostname of 6475@dfn{machine}.@refill 6476 6477@item as @var{mountpoint} 6478mount the filesystem locally as the name given, in case this is 6479different from the advertised volume name of the filesystem. 6480 6481@item opts @var{options} 6482native @b{mount}(8) options. 6483 6484@item fstype @var{type} 6485type of filesystem to be mounted. 6486@end table 6487 6488An example: 6489 6490@example 6491mount /export/exec/hp300/local as /usr/local 6492@end example 6493 6494If the mountpoint specified is either @file{/} or @file{swap}, the 6495machine will be considered to be booting off the net and this will be 6496noted for use in generating a @file{bootparams} file for the host which 6497owns the filesystems. 6498 6499@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo 6500@comment node-name, next, previous, up 6501@section Defining an @i{Amd} Mount Map in @i{FSinfo} 6502@cindex FSinfo automount definitions 6503@cindex Defining an Amd mount map, FSinfo 6504 6505The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining 6506all the automount trees. @i{FSinfo} takes all the definitions found and 6507builds one map for each top level tree. 6508 6509The automount tree is usually defined last. A single automount 6510configuration will usually apply to an entire management domain. One 6511@code{automount} declaration is needed for each @i{Amd} automount point. 6512@i{FSinfo} determines whether the automount point is @dfn{direct} 6513(@pxref{Direct Automount Filesystem}) or @dfn{indirect} 6514(@pxref{Top-level Filesystem}). Direct automount points are 6515distinguished by the fact that there is no underlying 6516@dfn{automount_tree}.@refill 6517 6518@example 6519automount : "automount" @i{opt(}auto_opts@i{)} automount_tree ; 6520 6521auto_opts : "opts" @var{<mount-options>} ; 6522 6523automount_tree 6524 : @i{list(}automount_attr@i{)} 6525 ; 6526 6527automount_attr 6528 : @var{<string>} "=" @var{<volname>} 6529 | @var{<string>} "->" @var{<symlink>} 6530 | @var{<string>} "@{" automount_tree "@}" 6531 ; 6532@end example 6533 6534If @var{<mount-options>} is given, then it is the string to be placed in 6535the maps for @i{Amd} for the @code{opts} option. 6536 6537A @dfn{map} is typically a tree of filesystems, for example @file{home} 6538normally contains a tree of filesystems representing other machines in 6539the network. 6540 6541A map can either be given as a name representing an already defined 6542volume name, or it can be a tree. A tree is represented by placing 6543braces after the name. For example, to define a tree @file{/vol}, the 6544following map would be defined: 6545 6546@example 6547automount /vol @{ @} 6548@end example 6549 6550Within a tree, the only items that can appear are more maps. 6551For example: 6552 6553@example 6554automount /vol @{ 6555 andrew @{ @} 6556 X11 @{ @} 6557@} 6558@end example 6559 6560In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} 6561and @file{/vol/X11} and a map entry will be generated for each. If the 6562volumes are defined more than once, then @i{FSinfo} will generate 6563a series of alternate entries for them in the maps.@refill 6564 6565Instead of a tree, either a link (@var{name} @code{->} 6566@var{destination}) or a reference can be specified (@var{name} @code{=} 6567@var{destination}). A link creates a symbolic link to the string 6568specified, without further processing the entry. A reference will 6569examine the destination filesystem and optimize the reference. For 6570example, to create an entry for @code{njw} in the @file{/homes} map, 6571either of the two forms can be used:@refill 6572 6573@example 6574automount /homes @{ 6575 njw -> /home/dylan/njw 6576@} 6577@end example 6578 6579or 6580 6581@example 6582automount /homes @{ 6583 njw = /home/dylan/njw 6584@} 6585@end example 6586 6587In the first example, when @file{/homes/njw} is referenced from @i{Amd}, 6588a link will be created leading to @file{/home/dylan/njw} and the 6589automounter will be referenced a second time to resolve this filename. 6590The map entry would be: 6591 6592@example 6593njw type:=link;fs:=/home/dylan/njw 6594@end example 6595 6596In the second example, the destination directory is analyzed and found 6597to be in the filesystem @file{/home/dylan} which has previously been 6598defined in the maps. Hence the map entry will look like: 6599 6600@example 6601njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw 6602@end example 6603 6604Creating only one symbolic link, and one access to @i{Amd}. 6605 6606@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo 6607@comment node-name, next, previous, up 6608@section @i{FSinfo} Command Line Options 6609@cindex FSinfo command line options 6610@cindex Command line options, FSinfo 6611 6612@i{FSinfo} is started from the command line by using the command: 6613 6614@example 6615fsinfo [@i{options}] @i{files} ... 6616@end example 6617 6618The input to @i{FSinfo} is a single set of definitions of machines and 6619automount maps. If multiple files are given on the command-line, then 6620the files are concatenated together to form the input source. The files 6621are passed individually through the C pre-processor before being parsed. 6622 6623Several options define a prefix for the name of an output file. If the 6624prefix is not specified no output of that type is produced. The suffix 6625used will correspond either to the hostname to which a file belongs, or 6626to the type of output if only one file is produced. Dumpsets and the 6627@file{bootparams} file are in the latter class. To put the output into 6628a subdirectory simply put a @file{/} at the end of the prefix, making 6629sure that the directory has already been made before running 6630@i{Fsinfo}. 6631 6632@menu 6633* -a FSinfo Option:: Amd automount directory: 6634* -b FSinfo Option:: Prefix for bootparams files. 6635* -d FSinfo Option:: Prefix for dumpset data files. 6636* -e FSinfo Option:: Prefix for exports files. 6637* -f FSinfo Option:: Prefix for fstab files. 6638* -h FSinfo Option:: Local hostname. 6639* -m FSinfo Option:: Prefix for automount maps. 6640* -q FSinfo Option:: Ultra quiet mode. 6641* -v FSinfo Option:: Verbose mode. 6642* -I FSinfo Option:: Define new #include directory. 6643* -D-FSinfo Option:: Define macro. 6644* -U FSinfo Option:: Undefine macro. 6645@end menu 6646 6647@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options 6648@comment node-name, next, previous, up 6649@subsection @code{-a} @var{autodir} 6650 6651Specifies the directory name in which to place the automounter's 6652mountpoints. This defaults to @file{/a}. Some sites have the autodir set 6653to be @file{/amd}, and this would be achieved by: 6654 6655@example 6656fsinfo -a /amd ... 6657@end example 6658 6659@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options 6660@comment node-name, next, previous, up 6661@subsection @code{-b} @var{bootparams} 6662@cindex bootparams, FSinfo prefix 6663 6664This specifies the prefix for the @file{bootparams} filename. If it is 6665not given, then the file will not be generated. The @file{bootparams} 6666file will be constructed for the destination machine and will be placed 6667into a file named @file{bootparams} and prefixed by this string. The 6668file generated contains a list of entries describing each diskless 6669client that can boot from the destination machine. 6670 6671As an example, to create a @file{bootparams} file in the directory 6672@file{generic}, the following would be used: 6673 6674@example 6675fsinfo -b generic/ ... 6676@end example 6677 6678@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options 6679@comment node-name, next, previous, up 6680@subsection @code{-d} @var{dumpsets} 6681@cindex dumpset, FSinfo prefix 6682 6683This specifies the prefix for the @file{dumpsets} file. If it is not 6684specified, then the file will not be generated. The file will be for 6685the destination machine and will be placed into a filename 6686@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is 6687for use by Imperial College's local backup system. 6688 6689For example, to create a @file{dumpsets} file in the directory @file{generic}, 6690then you would use the following: 6691 6692@example 6693fsinfo -d generic/ ... 6694@end example 6695 6696@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options 6697@comment node-name, next, previous, up 6698@subsection @code{-e} @var{exportfs} 6699@cindex exports, FSinfo prefix 6700 6701Defines the prefix for the @file{exports} files. If it is not given, 6702then the file will not be generated. For each machine defined in the 6703configuration files as having disks, an @file{exports} file is 6704constructed and given a filename determined by the name of the machine, 6705prefixed with this string. If a machine is defined as diskless, then no 6706@file{exports} file will be created for it. The files contain entries 6707for directories on the machine that may be exported to clients. 6708 6709Example: To create the @file{exports} files for each diskfull machine 6710and place them into the directory @file{exports}: 6711 6712@example 6713fsinfo -e exports/ ... 6714@end example 6715 6716@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options 6717@comment node-name, next, previous, up 6718@subsection @code{-f} @var{fstab} 6719@cindex fstab, FSinfo prefix 6720 6721This defines the prefix for the @file{fstab} files. The files will only 6722be created if this prefix is defined. For each machine defined in the 6723configuration files, a @file{fstab} file is created with the filename 6724determined by prefixing this string with the name of the machine. These 6725files contain entries for filesystems and partitions to mount at boot 6726time. 6727 6728Example, to create the files in the directory @file{fstabs}: 6729 6730@example 6731fsinfo -f fstabs/ ... 6732@end example 6733 6734@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options 6735@comment node-name, next, previous, up 6736@subsection @code{-h} @var{hostname} 6737@cindex hostname, FSinfo command line option 6738 6739Defines the hostname of the destination machine to process for. If this 6740is not specified, it defaults to the local machine name, as returned by 6741@b{gethostname}(2). 6742 6743Example: 6744 6745@example 6746fsinfo -h dylan.doc.ic.ac.uk ... 6747@end example 6748 6749@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options 6750@comment node-name, next, previous, up 6751@subsection @code{-m} @var{mount-maps} 6752@cindex maps, FSinfo command line option 6753 6754Defines the prefix for the automounter files. The maps will only be 6755produced if this prefix is defined. The mount maps suitable for the 6756network defined by the configuration files will be placed into files 6757with names calculated by prefixing this string to the name of each map. 6758 6759For example, to create the automounter maps and place them in the 6760directory @file{automaps}: 6761 6762@example 6763fsinfo -m automaps/ ... 6764@end example 6765 6766@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options 6767@comment node-name, next, previous, up 6768@subsection @code{-q} 6769@cindex quiet, FSinfo command line option 6770 6771Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and 6772only outputs any error messages which are generated. 6773 6774@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options 6775@comment node-name, next, previous, up 6776@subsection @code{-v} 6777@cindex verbose, FSinfo command line option 6778 6779Selects verbose mode. When this is activated, the program will display 6780more messages, and display all the information discovered when 6781performing the semantic analysis phase. Each verbose message is output 6782to @file{stdout} on a line starting with a @samp{#} character. 6783 6784@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options 6785@comment node-name, next, previous, up 6786@subsection @code{-D} @var{name}@i{[=defn]} 6787 6788Defines a symbol @dfn{name} for the preprocessor when reading the 6789configuration files. Equivalent to @code{#define} directive. 6790 6791@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options 6792@comment node-name, next, previous, up 6793@subsection @code{-I} @var{directory} 6794 6795This option is passed into the preprocessor for the configuration files. 6796It specifies directories in which to find include files 6797 6798@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options 6799@comment node-name, next, previous, up 6800@subsection @code{-U} @var{name} 6801 6802Removes any initial definition of the symbol @dfn{name}. Inverse of the 6803@code{-D} option. 6804 6805@node FSinfo errors, , FSinfo Command Line Options, FSinfo 6806@comment node-name, next, previous, up 6807@section Errors produced by @i{FSinfo} 6808@cindex FSinfo error messages 6809 6810The following table documents the errors and warnings which @i{FSinfo} may produce. 6811 6812@table @t 6813 6814@item " expected 6815Occurs if an unescaped newline is found in a quoted string. 6816 6817@item ambiguous mount: @var{volume} is a replicated filesystem 6818If several filesystems are declared as having the same volume name, they 6819will be considered replicated filesystems. To mount a replicated 6820filesystem statically, a specific host will need to be named, to say 6821which particular copy to try and mount, else this error will 6822result. 6823 6824@item can't open @var{filename} for writing 6825Occurs if any errors are encountered when opening an output file. 6826 6827@item cannot determine localname since volname @var{volume} is not uniquely defined 6828If a volume is replicated and an attempt is made to mount the filesystem 6829statically without specifying a local mountpoint, @i{FSinfo} cannot 6830calculate a mountpoint, as the desired pathname would be 6831ambiguous. 6832 6833@item @var{device} has duplicate exportfs data 6834Produced if the @samp{exportfs} option is used multiple times within the 6835same branch of a filesystem definition. For example, if you attempt to 6836set the @samp{exportfs} data at different levels of the mountpoint 6837directory tree. 6838 6839@item dump frequency for @var{host}:@var{device} is non-zero 6840Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6841or @samp{export} and the @samp{dump} option is set to a value greater 6842than zero. Swap devices should not be dumped. 6843 6844@item duplicate host @var{hostname}! 6845If a host has more than one definition. 6846 6847@item end of file within comment 6848A comment was unterminated before the end of one of the configuration 6849files. 6850 6851@item @var{filename}: cannot open for reading 6852If a file specified on the command line as containing configuration data 6853could not be opened. 6854 6855@item @var{filesystem} has a volname but no exportfs data 6856Occurs when a volume name is declared for a file system, but the string 6857specifying what machines the filesystem can be exported to is 6858missing. 6859 6860@item fs field "@var{field-name}" already set 6861Occurs when multiple definitions are given for one of the attributes of a 6862host's filesystem. 6863 6864@item host field "@var{field-name}" already set 6865If duplicate definitions are given for any of the fields with a host 6866definition. 6867 6868@item @var{host}:@var{device} has more than one mount point 6869Occurs if the mount option for a host's filesystem specifies multiple 6870trees at which to place the mountpoint. 6871 6872@item @var{host}:@var{device} has no mount point 6873Occurs if the @samp{mount} option is not specified for a host's 6874filesystem. 6875 6876@item @var{host}:@var{device} needs field "@var{field-name}" 6877Occurs when a filesystem is missing a required field. @var{field-name} could 6878be one of @samp{fstype}, @samp{opts}, @samp{passno} or 6879@samp{mount}. 6880 6881@item @var{host}:mount field specified for swap partition 6882Occurs if a mountpoint is given for a filesystem whose type is declared 6883to be @samp{swap}. 6884 6885@item malformed IP dotted quad: @var{address} 6886If the Internet address of an interface is incorrectly specified. An 6887Internet address definition is handled to @b{inet_addr}(3N) to see if it 6888can cope. If not, then this message will be displayed. 6889 6890@item malformed netmask: @var{netmask} 6891If the netmask cannot be decoded as though it were a hexadecimal number, 6892then this message will be displayed. It will typically be caused by 6893incorrect characters in the @var{netmask} value. 6894 6895@item mount field "@var{field-name}" already set 6896Occurs when a static mount has multiple definitions of the same field. 6897 6898@item mount tree field "@var{field-name}" already set 6899Occurs when the @var{field-name} is defined more than once during the 6900definition of a filesystems mountpoint. 6901 6902@item netif field @var{field-name} already set 6903Occurs if you attempt to define an attribute of an interface more than 6904once. 6905 6906@item network booting requires both root and swap areas 6907Occurs if a machine has mount declarations for either the root partition 6908or the swap area, but not both. You cannot define a machine to only 6909partially boot via the network. 6910 6911@item no disk mounts on @var{hostname} 6912If there are no static mounts, nor local disk mounts specified for a 6913machine, this message will be displayed. 6914 6915@item no volname given for @var{host}:@var{device} 6916Occurs when a filesystem is defined to be mounted on @file{default}, but 6917no volume name is given for the file system, then the mountpoint cannot 6918be determined. 6919 6920@item not allowed '/' in a directory name 6921Occurs when a pathname with multiple directory elements is specified as 6922the name for an automounter tree. A tree should only have one name at 6923each level. 6924 6925@item pass number for @var{host}:@var{device} is non-zero 6926Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 6927or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices 6928should not be fsck'd. @xref{FSinfo fstype Option}. 6929 6930@item sub-directory @var{directory} of @var{directory-tree} starts with '/' 6931Within the filesystem specification for a host, if an element 6932@var{directory} of the mountpoint begins with a @samp{/} and it is not 6933the start of the tree. 6934 6935@item sub-directory of @var{directory-tree} is named "default" 6936@samp{default} is a keyword used to specify if a mountpoint should be 6937automatically calculated by @i{FSinfo}. If you attempt to specify a 6938directory name as this, it will use the filename of @file{default} but 6939will produce this warning. 6940 6941@item unknown \ sequence 6942Occurs if an unknown escape sequence is found inside a string. Within a 6943string, you can give the standard C escape sequences for strings, such 6944as newlines and tab characters. 6945 6946@item unknown directory attribute 6947If an unknown keyword is found while reading the definition of a host's 6948filesystem mount option. 6949 6950@item unknown filesystem attribute 6951Occurs if an unrecognized keyword is used when defining a host's 6952filesystems. 6953 6954@item unknown host attribute 6955Occurs if an unrecognized keyword is used when defining a host. 6956 6957@item unknown mount attribute 6958Occurs if an unrecognized keyword is found while parsing the list of 6959static mounts. 6960 6961@item unknown volname @var{volume} automounted @i{[} on @i{name} @i{]} 6962Occurs if @var{volume} is used in a definition of an automount map but the volume 6963name has not been declared during the host filesystem definitions. 6964 6965@item volname @var{volume} is unknown 6966Occurs if an attempt is made to mount or reference a volume name which 6967has not been declared during the host filesystem definitions. 6968 6969@item volname @var{volume} not exported from @var{machine} 6970Occurs if you attempt to mount the volume @var{volume} from a machine 6971which has not declared itself to have such a filesystem 6972available. 6973 6974@end table 6975 6976@c ################################################################ 6977@node Hlfsd, Assorted Tools, FSinfo, Top 6978@comment node-name, next, previous, up 6979@chapter Hlfsd 6980@pindex Hlfsd 6981@cindex Home-Link Filesystem 6982 6983@i{Hlfsd} is a daemon which implements a filesystem containing a 6984symbolic link to subdirectory within a user's home directory, depending 6985on the user which accessed that link. It was primarily designed to 6986redirect incoming mail to users' home directories, so that it can be read 6987from anywhere. It was designed and implemented by 6988@uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} and 6989@email{dupuy AT cs.columbia.edu,Alexander Dupuy}, at the 6990@uref{http://www.cs.columbia.edu/,Computer Science Department} of 6991@uref{http://www.columbia.edu/,Columbia University}. A 6992@uref{http://www.fsl.cs.sunysb.edu/docs/hlfsd/hlfsd.html,paper} 6993on @i{Hlfsd} was presented at the Usenix LISA VII conference in 1993. 6994 6995@i{Hlfsd} operates by mounting itself as an NFS server for the directory 6996containing @i{linkname}, which defaults to @file{/hlfs/home}. Lookups 6997within that directory are handled by @i{Hlfsd}, which uses the 6998password map to determine how to resolve the lookup. The directory will 6999be created if it doesn't already exist. The symbolic link will be to 7000the accessing user's home directory, with @i{subdir} appended to it. If 7001not specified, @i{subdir} defaults to @file{.hlfsdir}. This directory 7002will also be created if it does not already exist. 7003 7004A @samp{SIGTERM} sent to @i{Hlfsd} will cause it to shutdown. A 7005@samp{SIGHUP} will flush the internal caches, and reload the password 7006map. It will also close and reopen the log file, to enable the original 7007log file to be removed or rotated. A @samp{SIGUSR1} will cause it to 7008dump its internal table of user IDs and home directories to the file 7009@file{/tmp/hlfsddump}. 7010 7011@menu 7012* Introduction to Hlfsd:: 7013* Background to Mail Delivery:: 7014* Using Hlfsd:: 7015@end menu 7016 7017@c ================================================================ 7018@node Introduction to Hlfsd, Background to Mail Delivery, Hlfsd, Hlfsd 7019@comment node-name, next, previous, up 7020@section Introduction to Hlfsd 7021@cindex Introduction to Hlfsd 7022@cindex Hlfsd; introduction 7023 7024Electronic mail has become one of the major applications for many 7025computer networks, and use of this service is expected to increase over 7026time, as networks proliferate and become faster. Providing a convenient 7027environment for users to read, compose, and send electronic mail has 7028become a requirement for systems administrators (SAs). 7029 7030Widely used methods for handling mail usually require users to be logged 7031into a designated ``home'' machine, where their mailbox files reside. 7032Only on that one machine can they read newly arrived mail. Since users 7033have to be logged into that system to read their mail, they often find 7034it convenient to run all of their other processes on that system as 7035well, including memory and CPU-intensive jobs. For example, in our 7036department, we have allocated and configured several multi-processor 7037servers to handle such demanding CPU/memory applications, but these were 7038underutilized, in large part due to the inconvenience of not being able 7039to read mail on those machines. (No home directories were located on 7040these designated CPU-servers, since we did not want NFS service for 7041users' home directories to have to compete with CPU-intensive jobs. At the 7042same time, we discouraged users from running demanding applications on 7043their home machines.) 7044 7045Many different solutions have been proposed to allow users to read their 7046mail on any host. However, all of these solutions fail in one or more 7047of several ways: 7048 7049@itemize @bullet 7050 7051@item 7052they introduce new single points of failure 7053 7054@item 7055they require using different mail transfer agents (MTAs) or user agents 7056(UAs) 7057 7058@item 7059they do not solve the problem for all cases, i.e. the solution is only 7060partially successful for a particular environment. 7061 7062@end itemize 7063 7064We have designed a simple filesystem, called the @dfn{Home-Link File 7065System}, to provide the ability to deliver mail to users' home 7066directories, without modification to mail-related applications. We have 7067endeavored to make it as stable as possible. Of great importance to us 7068was to make sure the HLFS daemon, @file{hlfsd} , would not hang under 7069any circumstances, and would take the next-best action when faced with 7070problems. Compared to alternative methods, @i{Hlfsd} is a stable, more 7071general solution, and easier to install/use. In fact, in some ways, we 7072have even managed to improve the reliability and security of mail 7073service. 7074 7075Our server implements a small filesystem containing a symbolic link 7076to a subdirectory of the invoking user's home directory, and named symbolic 7077links to users' mailbox files. 7078 7079The @i{Hlfsd} server finds out the @var{uid} of the process that is 7080accessing its mount point, and resolves the pathname component @samp{home} as a 7081symbolic link to a subdirectory within the home directory given by the 7082@var{uid}'s entry in the password file. If the @var{gid} of the process 7083that attempts to access a mailbox file is a special one (called 7084HLFS_GID), then the server maps the name of the @emph{next} pathname 7085component directly to the user's mailbox. This is necessary so that 7086access to a mailbox file by users other than the owner can succeed. The 7087server has safety features in case of failures such as hung filesystems 7088or home directory filesystems that are inaccessible or full. 7089 7090On most of our machines, mail gets delivered to the directory 7091@file{/var/spool/mail}. Many programs, including UAs, depend on that 7092path. @i{Hlfsd} creates a directory @file{/mail}, and mounts itself on 7093top of that directory. @i{Hlfsd} implements the path name component 7094called @samp{home}, pointing to a subdirectory of the user's home directory. 7095We have made @file{/var/spool/mail} a symbolic link to 7096@file{/mail/home}, so that accessing @file{/var/spool/mail} actually 7097causes access to a subdirectory within a user's home directory. 7098 7099The following table shows an example of how resolving the pathname 7100@file{/var/mail/@i{NAME}} to @file{/users/ezk/.mailspool/@i{NAME}} proceeds. 7101 7102@multitable {Resolving Component} {Pathname left to resolve} {Value if symbolic link} 7103 7104@item @b{Resolving Component} 7105@tab @b{Pathname left to resolve} 7106@tab @b{Value if symbolic link} 7107 7108@item @t{/} 7109@tab @t{var/mail/}@i{NAME} 7110 7111@item @t{var/} 7112@tab @t{mail/}@i{NAME} 7113 7114@item @t{mail}@@ 7115@tab @t{/mail/home/}@i{NAME} 7116@tab @t{mail}@@ -> @t{/mail/home} 7117 7118@item @t{/} 7119@tab @t{mail/home/}@i{NAME} 7120 7121@item @t{mail/} 7122@tab @t{home/}@i{NAME} 7123 7124@item @t{home}@@ 7125@tab @i{NAME} 7126@tab @t{home}@@ -> @t{/users/ezk/.mailspool} 7127 7128@item @t{/} 7129@tab @t{users/ezk/.mailspool/}@i{NAME} 7130 7131@item @t{users/} 7132@tab @t{ezk/.mailspool/}@i{NAME} 7133 7134@item @t{ezk/} 7135@tab @t{.mailspool/}@i{NAME} 7136 7137@item @t{.mailspool/} 7138@tab @i{NAME} 7139 7140@item @i{NAME} 7141 7142@end multitable 7143 7144@c ================================================================ 7145@node Background to Mail Delivery, Using Hlfsd, Introduction to Hlfsd, Hlfsd 7146@comment node-name, next, previous, up 7147@section Background to Mail Delivery 7148@cindex Background to Mail Delivery 7149@cindex Hlfsd; background 7150 7151This section provides an in-depth discussion of why available methods 7152for delivering mail to home directories are not as good as the one used 7153by @i{Hlfsd}. 7154 7155@menu 7156* Single-Host Mail Spool Directory:: 7157* Centralized Mail Spool Directory:: 7158* Distributed Mail Spool Service:: 7159* Why Deliver Into the Home Directory?:: 7160@end menu 7161 7162@c ---------------------------------------------------------------- 7163@node Single-Host Mail Spool Directory, Centralized Mail Spool Directory, Background to Mail Delivery, Background to Mail Delivery 7164@comment node-name, next, previous, up 7165@subsection Single-Host Mail Spool Directory 7166@cindex Single-Host Mail Spool Directory 7167 7168The most common method for mail delivery is for mail to be appended to a 7169mailbox file in a standard spool directory on the designated ``mail 7170home'' machine of the user. The greatest advantage of this method is 7171that it is the default method most vendors provide with their systems, 7172thus very little (if any) configuration is required on the SA's part. 7173All they need to set up are mail aliases directing mail to the host on 7174which the user's mailbox file is assigned. (Otherwise, mail is 7175delivered locally, and users find mailboxes on many machines.) 7176 7177As users become more sophisticated, and aided by windowing systems, they 7178find themselves logging in on multiple hosts at once, performing several 7179tasks concurrently. They ask to be able to read their mail on any host 7180on the network, not just the one designated as their ``mail home''. 7181 7182@c ---------------------------------------------------------------- 7183@node Centralized Mail Spool Directory, Distributed Mail Spool Service, Single-Host Mail Spool Directory, Background to Mail Delivery 7184@comment node-name, next, previous, up 7185@subsection Centralized Mail Spool Directory 7186@cindex Centralized Mail Spool Directory 7187 7188A popular method for providing mail readability from any host is to have 7189all mail delivered to a mail spool directory on a designated 7190``mail-server'' which is exported via NFS to all of the hosts on the 7191network. Configuring such a system is relatively easy. On most 7192systems, the bulk of the work is a one-time addition to one or two 7193configuration files in @file{/etc}. The file-server's spool directory 7194is then hard-mounted across every machine on the local network. In 7195small environments with only a handful of hosts this can be an 7196acceptable solution. In our department, with a couple of hundred active 7197hosts and thousands of mail messages processed daily, this was deemed 7198completely unacceptable, as it introduced several types of problems: 7199 7200@table @b 7201 7202@item Scalability and Performance 7203 7204As more and more machines get added to the network, more mail traffic 7205has to go over NFS to and from the mail-server. Users like to run 7206mail-watchers, and read their mail often. The stress on the shared 7207infrastructure increases with every user and host added; loads on the 7208mail server would most certainly be high since all mail delivery goes 7209through that one machine.@footnote{ Delivery via NFS-mounted filesystems 7210may require usage of @samp{rpc.lockd} and @samp{rpc.statd} to provide 7211distributed file-locking, both of which are widely regarded as unstable 7212and unreliable. Furthermore, this will degrade performance, as local 7213processes as well as remote @samp{nfsd} processes are kept busy.} This 7214leads to lower reliability and performance. To reduce the number of 7215concurrent connections between clients and the server host, some SAs 7216have resorted to automounting the mail-spool directory. But this 7217solution only makes things worse: since users often run mail watchers, 7218and many popular applications such as @samp{trn}, @samp{emacs}, 7219@samp{csh} or @samp{ksh} check periodically for new mail, the 7220automounted directory would be effectively permanently mounted. If it 7221gets unmounted automatically by the automounter program, it is most 7222likely to get mounted shortly afterwards, consuming more I/O resources 7223by the constant cycle of mount and umount calls. 7224 7225@item Reliability 7226 7227The mail-server host and its network connectivity must be very reliable. 7228Worse, since the spool directory has to be hard-mounted,@footnote{No SA 7229in their right minds would soft-mount read/write partitions --- the 7230chances for data loss are too great.} many processes which access the 7231spool directory (various shells, @samp{login}, @samp{emacs}, etc.) 7232would be hung as long as connectivity to the mail-server is severed. To 7233improve reliability, SAs may choose to backup the mail-server's spool 7234partition several times a day. This may make things worse since reading 7235or delivering mail while backups are in progress may cause backups to be 7236inconsistent; more backups consume more backup-media resources, and 7237increase the load on the mail-server host. 7238 7239@end table 7240 7241@c ---------------------------------------------------------------- 7242@node Distributed Mail Spool Service, Why Deliver Into the Home Directory?, Centralized Mail Spool Directory, Background to Mail Delivery 7243@comment node-name, next, previous, up 7244@subsection Distributed Mail Spool Service 7245@cindex Distributed Mail Spool Service 7246 7247Despite the existence of a few systems that support delivery to users' 7248home directories, mail delivery to home directories hasn't caught on. 7249We believe the main reason is that there are too many programs that 7250``know'' where mailbox files reside. Besides the obvious (the delivery 7251program @file{/bin/mail} and mail readers like @file{/usr/ucb/Mail}, 7252@samp{mush}, @samp{mm}, etc.), other programs that know mailbox location 7253are login, from, almost every shell, @samp{xbiff}, @samp{xmailbox}, and 7254even some programs not directly related to mail, such as @samp{emacs} 7255and @samp{trn}. Although some of these programs can be configured to 7256look in different directories with the use of environment variables and 7257other resources, many of them cannot. The overall porting work is 7258significant. 7259 7260Other methods that have yet to catch on require the use of a special 7261mail-reading server, such as IMAP or POP. The main disadvantage of 7262these systems is that UAs need to be modified to use these services --- 7263a long and involved task. That is why they are not popular at this 7264time. 7265 7266Several other ideas have been proposed and even used in various 7267environments. None of them is robust. They are mostly very 7268specialized, inflexible, and do not extend to the general case. Some of 7269the ideas are plain bad, potentially leading to lost or corrupt mail: 7270 7271@table @b 7272 7273@item automounters 7274 7275Using an automounter such as @i{Amd} to provide a set of symbolic links 7276from the normal spool directory to user home directories is not 7277sufficient. UAs rename, unlink, and recreate the mailbox as a regular 7278file, therefore it must be a real file, not a symbolic link. 7279Furthermore, it must reside in a real directory which is writable by the 7280UAs and MTAs. This method may also require populating 7281@file{/var/spool/mail} with symbolic links and making sure they are 7282updated. Making @i{Amd} manage that directory directly fails, since 7283many various lock files need to be managed as well. Also, @i{Amd} does 7284not provide all of the NFS operations which are required to write mail 7285such as write, create, remove, and unlink. 7286 7287@item @code{$MAIL} 7288 7289Setting this variable to an automounted directory pointing to the user's 7290mail spool host only solves the problem for those programs which know 7291and use @code{$MAIL}. Many programs don't, therefore this solution is partial 7292and of limited flexibility. Also, it requires the SAs or the users to 7293set it themselves --- an added level of inconvenience and possible 7294failures. 7295 7296@item @t{/bin/mail} 7297 7298Using a different mail delivery agent could be the solution. One such 7299example is @samp{hdmail}. However, @samp{hdmail} still requires 7300modifying all UAs, the MTA's configuration, installing new daemons, and 7301changing login scripts. This makes the system less upgradable or 7302compatible with others, and adds one more complicated system for SAs to 7303deal with. It is not a complete solution because it still requires each 7304user have their @code{$MAIL} variable setup correctly, and that every program 7305use this variable. 7306 7307@end table 7308 7309@c ---------------------------------------------------------------- 7310@node Why Deliver Into the Home Directory?, , Distributed Mail Spool Service, Background to Mail Delivery 7311@comment node-name, next, previous, up 7312@subsection Why Deliver Into the Home Directory? 7313@cindex Why Deliver Into the Home Directory? 7314@cindex Hlfsd; Why Deliver Into the Home Directory? 7315 7316There are several major reasons why SAs might want to deliver mail 7317directly into the users' home directories: 7318 7319@table @b 7320 7321@item Location 7322 7323Many mail readers need to move mail from the spool directory to the 7324user's home directory. It speeds up this operation if the two are on 7325the same filesystem. If for some reason the user's home directory is 7326inaccessible, it isn't that useful to be able to read mail, since there 7327is no place to move it to. In some cases, trying to move mail to a 7328non-existent or hung filesystem may result in mail loss. 7329 7330@item Distribution 7331 7332Having all mail spool directories spread among the many more filesystems 7333minimizes the chances that complete environments will grind to a halt 7334when a single server is down. It does increase the chance that there 7335will be someone who is not able to read their mail when a machine is 7336down, but that is usually preferred to having no one be able to read 7337their mail because a centralized mail server is down. The problem of 7338losing some mail due to the (presumably) higher chances that a user's 7339machine is down is minimized in HLFS. 7340 7341@item Security 7342 7343Delivering mail to users' home directories has another advantage --- 7344enhanced security and privacy. Since a shared system mail spool 7345directory has to be world-readable and searchable, any user can see 7346whether other users have mail, when they last received new mail, or when 7347they last read their mail. Programs such as @samp{finger} display this 7348information, which some consider an infringement of privacy. While it 7349is possible to disable this feature of @samp{finger} so that remote 7350users cannot see a mailbox file's status, this doesn't prevent local 7351users from getting the information. Furthermore, there are more 7352programs which make use of this information. In shared environments, 7353disabling such programs has to be done on a system-wide basis, but with 7354mail delivered to users' home directories, users less concerned with 7355privacy who do want to let others know when they last received or read 7356mail can easily do so using file protection bits. 7357 7358@c Lastly, on systems that do not export their NFS filesystem with 7359@c @t{anon=0}, superusers are less likely to snoop around others' mail, as 7360@c they become ``nobodies'' across NFS. 7361 7362@end table 7363 7364In summary, delivering mail to home directories provides users the 7365functionality sought, and also avoids most of the problems just 7366discussed. 7367 7368@c ================================================================ 7369@node Using Hlfsd, , Background to Mail Delivery, Hlfsd 7370@comment node-name, next, previous, up 7371@section Using Hlfsd 7372@cindex Using Hlfsd 7373@cindex Hlfsd; using 7374 7375@menu 7376* Controlling Hlfsd:: 7377* Hlfsd Options:: 7378* Hlfsd Files:: 7379@end menu 7380 7381@c ---------------------------------------------------------------- 7382@node Controlling Hlfsd, Hlfsd Options, Using Hlfsd, Using Hlfsd 7383@comment node-name, next, previous, up 7384@subsection Controlling Hlfsd 7385@cindex Controlling Hlfsd 7386@cindex Hlfsd; controlling 7387@pindex ctl-hlfsd 7388 7389Much the same way @i{Amd} is controlled by @file{ctl-amd}, so does 7390@i{Hlfsd} get controlled by the @file{ctl-hlfsd} script: 7391 7392@table @t 7393 7394@item ctl-hlfsd start 7395Start a new @i{Hlfsd}. 7396 7397@item ctl-hlfsd stop 7398Stop a running @i{Hlfsd}. 7399 7400@item ctl-hlfsd restart 7401Stop a running @i{Hlfsd}, wait for 10 seconds, and then start a new 7402one. It is hoped that within 10 seconds, the previously running 7403@i{Hlfsd} terminate properly; otherwise, starting a second one could 7404cause system lockup. 7405 7406@end table 7407 7408For example, on our systems, we start @i{Hlfsd} within @file{ctl-hlfsd} 7409as follows on Solaris 2 systems: 7410 7411@example 7412hlfsd -a /var/alt_mail -x all -l /var/log/hlfsd /mail/home .mailspool 7413@end example 7414 7415The directory @file{/var/alt_mail} is a directory in the root partition 7416where alternate mail will be delivered into, when it cannot be delivered 7417into the user's home directory. 7418 7419Normal mail gets delivered into @file{/var/mail}, but on our systems, 7420that is a symbolic link to @file{/mail/home}. @file{/mail} is managed 7421by @i{Hlfsd}, which creates a dynamic symlink named @samp{home}, 7422pointing to the subdirectory @file{.mailspool} @emph{within} the 7423accessing user's home directory. This results in mail which normally 7424should go to @file{/var/mail/@code{$USER}}, to go to 7425@file{@code{$HOME}/.mailspool/@code{$USER}}. 7426 7427@i{Hlfsd} does not create the @file{/var/mail} symlink. This needs to 7428be created (manually) once on each host, by the system administrators, 7429as follows: 7430 7431@example 7432mv /var/mail /var/alt_mail 7433ln -s /mail/home /var/mail 7434@end example 7435 7436@i{Hlfsd} also responds to the following signals: 7437 7438A @samp{SIGHUP} signal sent to @i{Hlfsd} will force it to reload the 7439password map immediately. 7440 7441A @samp{SIGUSR1} signal sent to @i{Hlfsd} will cause it to dump its 7442internal password map to the file @file{/usr/tmp/hlfsd.dump.XXXXXX}, 7443where @samp{XXXXXX} will be replaced by a random string generated by 7444@b{mktemp}(3) or (the more secure) @b{mkstemp}(3). 7445 7446@c ---------------------------------------------------------------- 7447@node Hlfsd Options, Hlfsd Files, Controlling Hlfsd, Using Hlfsd 7448@comment node-name, next, previous, up 7449@subsection Hlfsd Options 7450@cindex Hlfsd Options 7451@cindex Hlfsd; Options 7452 7453@table @t 7454 7455@item -a @var{alt_dir} 7456Alternate directory. The name of the directory to which the symbolic 7457link returned by @i{Hlfsd} will point, if it cannot access the home 7458directory of the user. This defaults to @file{/var/hlfs}. This 7459directory will be created if it doesn't exist. It is expected that 7460either users will read these files, or the system administrators will 7461run a script to resend this ``lost mail'' to its owner. 7462 7463@item -c @var{cache-interval} 7464Caching interval. @i{Hlfsd} will cache the validity of home directories 7465for this interval, in seconds. Entries which have been verified within 7466the last @var{cache-interval} seconds will not be verified again, since 7467the operation could be expensive, and the entries are most likely still 7468valid. After the interval has expired, @i{Hlfsd} will re-verify the 7469validity of the user's home directory, and reset the cache time-counter. 7470The default value for @var{cache-interval} is 300 seconds (5 minutes). 7471 7472@item -f 7473Force fast startup. This option tells @i{Hlfsd} to skip startup-time 7474consistency checks such as existence of mount directory, alternate spool 7475directory, symlink to be hidden under the mount directory, their 7476permissions and validity. 7477 7478@item -g @var{group} 7479Set the special group HLFS_GID to @var{group}. Programs such as 7480@file{/usr/ucb/from} or @file{/usr/sbin/in.comsat}, which access the 7481mailboxes of other users, must be setgid @samp{HLFS_GID} to work properly. The 7482default group is @samp{hlfs}. If no group is provided, and there is no 7483group @samp{hlfs}, this feature is disabled. 7484 7485@item -h 7486Help. Print a brief help message, and exit. 7487 7488@item -i @var{reload-interval} 7489Map-reloading interval. Each @var{reload-interval} seconds, @i{Hlfsd} 7490will reload the password map. @i{Hlfsd} needs the password map for the 7491UIDs and home directory pathnames. @i{Hlfsd} schedules a @samp{SIGALRM} to 7492reload the password maps. A @samp{SIGHUP} sent to @i{Hlfsd} will force it to 7493reload the maps immediately. The default value for 7494@var{reload-interval} is 900 seconds (15 minutes.) 7495 7496@item -l @var{logfile} 7497Specify a log file to which @i{Hlfsd} will record events. If 7498@var{logfile} is the string @samp{syslog} then the log messages will be 7499sent to the system log daemon by @b{syslog}(3), using the @samp{LOG_DAEMON} 7500facility. This is also the default. 7501 7502@item -n 7503No verify. @i{Hlfsd} will not verify the validity of the symbolic link 7504it will be returning, or that the user's home directory contains 7505sufficient disk-space for spooling. This can speed up @i{Hlfsd} at the 7506cost of possibly returning symbolic links to home directories which are 7507not currently accessible or are full. By default, @i{Hlfsd} validates 7508the symbolic-link in the background. The @code{-n} option overrides the 7509meaning of the @code{-c} option, since no caching is necessary. 7510 7511@item -o @var{mount-options} 7512Mount options which @i{Hlfsd} will use to mount itself on top of 7513@var{dirname}. By default, @var{mount-options} is set to @samp{ro}. If 7514the system supports symbolic-link caching, default options are set 7515to @samp{ro,nocache}. 7516 7517@item -p 7518Print PID. Outputs the process-id of @i{Hlfsd} to standard output where 7519it can be saved into a file. 7520 7521@item -v 7522Version. Displays version information to standard error. 7523 7524@item -x @var{log-options} 7525Specify run-time logging options. The options are a comma separated 7526list chosen from: @samp{fatal}, @samp{error}, @samp{user}, @samp{warn}, @samp{info}, @samp{map}, @samp{stats}, @samp{all}. 7527 7528@item -C 7529Force @i{Hlfsd} to run on systems that cannot turn off the NFS 7530attribute-cache. Use of this option on those systems is discouraged, as 7531it may result in loss or misdelivery of mail. The option is ignored on 7532systems that can turn off the attribute-cache. 7533 7534@item -D @var{log-options} 7535Select from a variety of debugging options. Prefixing an option with 7536the string @samp{no} reverses the effect of that option. Options are 7537cumulative. The most useful option is @samp{all}. Since this option is 7538only used for debugging other options are not documented here. A fuller 7539description is available in the program source. 7540 7541@item -P @var{password-file} 7542Read the user-name, user-id, and home directory information from the 7543file @var{password-file}. Normally, @i{Hlfsd} will use @b{getpwent}(3) 7544to read the password database. This option allows you to override the 7545default database, and is useful if you want to map users' mail files to 7546a directory other than their home directory. Only the username, uid, 7547and home-directory fields of the file @var{password-file} are read and 7548checked. All other fields are ignored. The file @var{password-file} 7549must otherwise be compliant with Unix Version 7 colon-delimited format 7550@b{passwd}(4). 7551 7552@end table 7553 7554@c ---------------------------------------------------------------- 7555@node Hlfsd Files, , Hlfsd Options, Using Hlfsd 7556@comment node-name, next, previous, up 7557@subsection Hlfsd Files 7558@cindex Hlfsd Files 7559@cindex Hlfsd; Files 7560 7561The following files are used by @i{Hlfsd}: 7562 7563@table @file 7564 7565@item /hlfs 7566directory under which @i{Hlfsd} mounts itself and manages the symbolic 7567link @file{home}. 7568 7569@item .hlfsdir 7570default sub-directory in the user's home directory, to which the 7571@file{home} symbolic link returned by @i{Hlfsd} points. 7572 7573@item /var/hlfs 7574directory to which @file{home} symbolic link returned by @i{Hlfsd} 7575points if it is unable to verify the that user's home directory is 7576accessible. 7577 7578@item /usr/tmp/hlfsd.dump.XXXXXX 7579file to which @i{Hlfsd} will dump its internal password map when it 7580receives the @samp{SIGUSR1} signal. @samp{XXXXXX} will be replaced by 7581a random string generated by @b{mktemp}(3) or (the more secure) 7582@b{mkstemp}(3). 7583 7584@end table 7585 7586For discussion on other files used by @i{Hlfsd}, see @xref{lostaltmail}, and 7587@ref{lostaltmail.conf-sample}. 7588 7589@c ################################################################ 7590@node Assorted Tools, Examples, Hlfsd, Top 7591@comment node-name, next, previous, up 7592@chapter Assorted Tools 7593@cindex Assorted Tools 7594 7595The following are additional utilities and scripts included with 7596am-utils, and get installed. 7597 7598@menu 7599* am-eject:: 7600* amd.conf-sample:: 7601* amd2ldif:: 7602* amd2sun:: 7603* automount2amd:: 7604* ctl-amd:: 7605* ctl-hlfsd:: 7606* fix-amd-map:: 7607* fixmount:: 7608* fixrmtab:: 7609* lostaltmail:: 7610* lostaltmail.conf-sample:: 7611* mk-amd-map:: 7612* pawd:: 7613* redhat-ctl-amd:: 7614* wait4amd:: 7615* wait4amd2die:: 7616* wire-test:: 7617@end menu 7618 7619@c ---------------------------------------------------------------- 7620@node am-eject, amd.conf-sample, Assorted Tools, Assorted Tools 7621@comment node-name, next, previous, up 7622@section am-eject 7623@pindex am-eject 7624 7625A shell script unmounts a floppy or CD-ROM that is automounted, and 7626then attempts to eject the removable device. 7627 7628@c ---------------------------------------------------------------- 7629@node amd.conf-sample, amd2ldif, am-eject, Assorted Tools 7630@comment node-name, next, previous, up 7631@section amd.conf-sample 7632@pindex amd.conf-sample 7633 7634A sample @i{Amd} configuration file. @xref{Amd Configuration File}. 7635 7636@c ---------------------------------------------------------------- 7637@node amd2ldif, amd2sun, amd.conf-sample, Assorted Tools 7638@comment node-name, next, previous, up 7639@section amd2ldif 7640@pindex amd2ldif 7641 7642A script to convert @i{Amd} maps to LDAP input files. Use it as follows: 7643 7644@example 7645amd2ldif @i{mapname} @i{base} < @i{amd.mapfile} > @i{mapfile.ldif} 7646@end example 7647 7648@c ---------------------------------------------------------------- 7649@node amd2sun, automount2amd, amd2ldif, Assorted Tools 7650@comment node-name, next, previous, up 7651@section amd2sun 7652@pindex amd2sun 7653 7654A script to convert @i{Amd} maps to Sun Automounter maps. Use it as 7655follows 7656 7657@example 7658amd2sun < @i{amd.mapfile} > @i{auto_mapfile} 7659@end example 7660 7661@c ---------------------------------------------------------------- 7662@node automount2amd, ctl-amd, amd2sun, Assorted Tools 7663@comment node-name, next, previous, up 7664@section automount2amd 7665@pindex automount2amd 7666 7667A script to convert old Sun Automounter maps to @i{Amd} maps. 7668 7669Say you have the Sun automount file @i{auto.foo}, with these two lines: 7670@example 7671home earth:/home 7672moon -ro,intr server:/proj/images 7673@end example 7674Running 7675@example 7676automount2amd auto.foo > amd.foo 7677@end example 7678 7679will produce the @i{Amd} map @i{amd.foo} with this content: 7680 7681@example 7682# generated by automount2amd on Sat Aug 14 17:59:32 US/Eastern 1999 7683 7684/defaults \\ 7685 type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7686 7687home \ 7688 host==earth;type:=link;fs:=/home \\ 7689 rhost:=earth;rfs:=/home 7690 7691moon \ 7692 -addopts:=ro,intr \\ 7693 host==server;type:=link;fs:=/proj/images \\ 7694 rhost:=server;rfs:=/proj/images 7695@end example 7696 7697This perl script will use the following @i{/default} entry 7698@example 7699type:=nfs;opts:=rw,grpid,nosuid,utimeout=600 7700@end example 7701If you wish to override that, define the @b{$DEFAULTS} environment 7702variable, or modify the script. 7703 7704If you wish to generate Amd maps using the @i{hostd} (@pxref{hostd 7705Selector Variable}) @i{Amd} map syntax, then define the environment 7706variable @b{$DOMAIN} or modify the script. 7707 7708Note that automount2amd does not understand the syntax in newer Sun 7709Automount maps, those used with autofs. 7710 7711@c ---------------------------------------------------------------- 7712@node ctl-amd, ctl-hlfsd, automount2amd, Assorted Tools 7713@comment node-name, next, previous, up 7714@section ctl-amd 7715@pindex ctl-amd 7716 7717A script to start, stop, or restart @i{Amd}. Use it as follows: 7718 7719@table @t 7720@item ctl-amd start 7721Start a new @i{Amd} process. 7722@item ctl-amd stop 7723Stop the running @i{Amd}. 7724@item ctl-amd restart 7725Stop the running @i{Amd} (if any), safely wait for it to terminate, and 7726then start a new process --- only if the previous one died cleanly. 7727@end table 7728 7729@xref{Run-time Administration}, for more details. 7730 7731@c ---------------------------------------------------------------- 7732@node ctl-hlfsd, fix-amd-map, ctl-amd, Assorted Tools 7733@comment node-name, next, previous, up 7734@section ctl-hlfsd 7735@pindex ctl-hlfsd 7736 7737A script for controlling @i{Hlfsd}, much the same way @file{ctl-amd} 7738controls @i{Amd}. Use it as follows: 7739 7740@table @t 7741@item ctl-hlfsd start 7742Start a new @i{Hlfsd} process. 7743@item ctl-hlfsd stop 7744Stop the running @i{Hlfsd}. 7745@item ctl-hlfsd restart 7746Stop the running @i{Hlfsd} (if any), wait for 10 seconds for it to 7747terminate, and then start a new process --- only if the previous one 7748died cleanly. 7749@end table 7750 7751@xref{Hlfsd}, for more details. 7752 7753@c ---------------------------------------------------------------- 7754@node fix-amd-map, fixmount, ctl-hlfsd, Assorted Tools 7755@comment node-name, next, previous, up 7756@section fix-amd-map 7757@pindex fix-amd-map 7758 7759Am-utils changed some of the syntax and default values of some 7760variables. For example, the default value for @samp{$@{os@}} for 7761Solaris 2.x (aka SunOS 5.x) systems used to be @samp{sos5}, it is now 7762more automatically generated from @file{config.guess} and its value is 7763@samp{sunos5}. 7764 7765This script converts older @i{Amd} maps to new ones. Use it as follows: 7766 7767@example 7768fix-amd-map < @i{old.map} > @i{new.map} 7769@end example 7770 7771@c ---------------------------------------------------------------- 7772@node fixmount, fixrmtab, fix-amd-map, Assorted Tools 7773@comment node-name, next, previous, up 7774@section fixmount 7775@pindex fixmount 7776 7777@samp{fixmount} is a variant of @b{showmount}(8) that can delete bogus 7778mount entries in remote @b{mountd}(8) daemons. This is useful to 7779cleanup otherwise ever-accumulating ``junk''. Use it for example: 7780 7781@example 7782fixmount -r @i{host} 7783@end example 7784 7785See the online manual page for @samp{fixmount} for more details of its 7786usage. 7787 7788@c ---------------------------------------------------------------- 7789@node fixrmtab, lostaltmail, fixmount, Assorted Tools 7790@comment node-name, next, previous, up 7791@section fixrmtab 7792@pindex fixrmtab 7793 7794A script to invalidate @file{/etc/rmtab} entries for hosts named. Also 7795restart mountd for changes to take effect. Use it for example: 7796 7797@example 7798fixrmtab @i{host1} @i{host2} @i{...} 7799@end example 7800 7801@c ---------------------------------------------------------------- 7802@node lostaltmail, lostaltmail.conf-sample, fixrmtab, Assorted Tools 7803@comment node-name, next, previous, up 7804@section lostaltmail 7805@pindex lostaltmail 7806 7807A script used with @i{Hlfsd} to resend any ``lost'' mail. @i{Hlfsd} 7808redirects mail which cannot be written into the user's home directory to 7809an alternate directory. This is useful to continue delivering mail, 7810even if the user's file system was unavailable, full, or over quota. 7811But, the mail which gets delivered to the alternate directory needs to 7812be resent to its respective users. This is what the @samp{lostaltmail} 7813script does. 7814 7815Use it as follows: 7816 7817@example 7818lostaltmail 7819@end example 7820 7821This script needs a configuration file @samp{lostaltmail.conf} set up 7822with the right parameters to properly work. @xref{Hlfsd}, for more 7823details. 7824 7825@c ---------------------------------------------------------------- 7826@node lostaltmail.conf-sample, mk-amd-map, lostaltmail, Assorted Tools 7827@comment node-name, next, previous, up 7828@section lostaltmail.conf-sample 7829@pindex lostaltmail.conf-sample 7830@cindex lostaltmail; configuration file 7831 7832This is a text file with configuration parameters needed for the 7833@samp{lostaltmail} script. The script includes comments explaining each 7834of the configuration variables. See it for more information. Also 7835@pxref{Hlfsd} for general information. 7836 7837@c ---------------------------------------------------------------- 7838@node mk-amd-map, pawd, lostaltmail.conf-sample, Assorted Tools 7839@comment node-name, next, previous, up 7840@section mk-amd-map 7841@pindex mk-amd-map 7842 7843This program converts a normal @i{Amd} map file into an ndbm database 7844with the same prefix as the named file. Use it as follows: 7845 7846@example 7847mk-amd-map @i{mapname} 7848@end example 7849 7850@c ---------------------------------------------------------------- 7851@node pawd, redhat-ctl-amd, mk-amd-map, Assorted Tools 7852@comment node-name, next, previous, up 7853@section pawd 7854@pindex pawd 7855 7856@i{Pawd} is used to print the current working directory, adjusted to 7857reflect proper paths that can be reused to go through the automounter 7858for the shortest possible path. In particular, the path printed back 7859does not include any of @i{Amd}'s local mount points. Using them is 7860unsafe, because @i{Amd} may unmount managed file systems from the mount 7861points, and thus including them in paths may not always find the files 7862within. 7863 7864Without any arguments, @i{Pawd} will print the automounter adjusted 7865current working directory. With any number of arguments, it will print 7866the adjusted path of each one of the arguments. 7867 7868@c ---------------------------------------------------------------- 7869@node redhat-ctl-amd, wait4amd, pawd, Assorted Tools 7870@comment node-name, next, previous, up 7871@section redhat-ctl-amd 7872@pindex redhat-ctl-amd 7873 7874This script is similar to @i{ctl-amd} (@pxref{ctl-amd}) but is intended 7875for Red Hat Linux systems. You can safely copy @i{redhat-ctl-amd} onto 7876@file{/etc/rc.d/init.d/amd}. The script supplied by @i{Am-utils} is 7877usually better than the one provided by Red Hat, because the Red Hat 7878script does not correctly kill @i{Amd} processes: it is too quick to 7879kill the wrong processes, leaving stale or hung mount points behind. 7880 7881@c ---------------------------------------------------------------- 7882@node wait4amd, wait4amd2die, redhat-ctl-amd, Assorted Tools 7883@comment node-name, next, previous, up 7884@section wait4amd 7885@pindex wait4amd 7886 7887A script to wait for @i{Amd} to start on a particular host before 7888performing an arbitrary command. The command is executed repeatedly, 7889with 1 second intervals in between. You may interrupt the script using 7890@samp{^C} (or whatever keyboard sequence your terminal's @samp{intr} function 7891is bound to). 7892 7893Examples: 7894 7895@table @t 7896@item wait4amd saturn amq -p -h saturn 7897When @i{Amd} is up on host @samp{saturn}, get the process ID of that 7898running @i{Amd}. 7899@item wait4amd pluto rlogin pluto 7900Remote login to host @samp{pluto} when @i{Amd} is up on that host. It 7901is generally necessary to wait for @i{Amd} to properly start and 7902initialize on a remote host before logging in to it, because otherwise 7903user home directories may not be accessible across the network. 7904@item wait4amd pluto 7905A short-hand version of the previous command, since the most useful 7906reason for this script is to login to a remote host. I use it very 7907often when testing out new versions of @i{Amd}, and need to reboot hung 7908hosts. 7909@end table 7910 7911@c ---------------------------------------------------------------- 7912@node wait4amd2die, wire-test, wait4amd, Assorted Tools 7913@comment node-name, next, previous, up 7914@section wait4amd2die 7915@pindex wait4amd2die 7916 7917This script is used internally by @samp{ctl-amd} when used to restart 7918@i{Amd}. It waits for @i{Amd} to terminate. If it detected that 7919@i{Amd} terminated cleanly, this script will return an exist status of 7920zero. Otherwise, it will return a non-zero exit status. 7921 7922The script tests for @i{Amd}'s existence once every 5 seconds, six 7923times, for a total of 30 seconds. It will return a zero exist status as 7924soon as it detects that @i{Amd} dies. 7925 7926@c ---------------------------------------------------------------- 7927@node wire-test, , wait4amd2die, Assorted Tools 7928@comment node-name, next, previous, up 7929@section wire-test 7930@pindex wire-test 7931 7932A simple program to test if some of the most basic networking functions 7933in am-util's library @file{libamu} work. It also tests the combination 7934of NFS protocol and version number that are supported from the current 7935host, to a remote one. 7936 7937For example, in this test a machine which only supports NFS Version 2 is 7938contacting a remote host that can support the same version, but using 7939both UDP and TCP. If no host name is specified, @samp{wire-test} will 7940try @file{localhost}. 7941 7942@example 7943$ wire-test moisil 7944Network name is "mcl-lab-net.cs.columbia.edu" 7945Network number is "128.59.13" 7946Network name is "old-net.cs.columbia.edu" 7947Network number is "128.59.16" 7948My IP address is 0x7f000001. 7949NFS Version and protocol tests to host "moisil"... 7950 testing vers=2, proto="udp" -> found version 2. 7951 testing vers=3, proto="udp" -> failed! 7952 testing vers=2, proto="tcp" -> found version 2. 7953 testing vers=3, proto="tcp" -> failed! 7954@end example 7955 7956@c ################################################################ 7957@node Examples, Internals, Assorted Tools, Top 7958@comment node-name, next, previous, up 7959@chapter Examples 7960 7961@menu 7962* User Filesystems:: 7963* Home Directories:: 7964* Architecture Sharing:: 7965* Wildcard Names:: 7966* rwho servers:: 7967* /vol:: 7968* /defaults with selectors:: 7969* /tftpboot in a chroot-ed environment:: 7970 7971@end menu 7972 7973@node User Filesystems, Home Directories, Examples, Examples 7974@comment node-name, next, previous, up 7975@section User Filesystems 7976@cindex User filesystems 7977@cindex Mounting user filesystems 7978 7979With more than one fileserver, the directories most frequently 7980cross-mounted are those containing user home directories. A common 7981convention used at Imperial College is to mount the user disks under 7982@t{/home/}@i{machine}. 7983 7984Typically, the @samp{/etc/fstab} file contained a long list of entries 7985such as: 7986 7987@example 7988@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... 7989@end example 7990 7991for each fileserver on the network. 7992 7993There are numerous problems with this system. The mount list can become 7994quite large and some of the machines may be down when a system is 7995booted. When a new fileserver is installed, @samp{/etc/fstab} must be 7996updated on every machine, the mount directory created and the filesystem 7997mounted. 7998 7999In many environments most people use the same few workstations, but 8000it is convenient to go to a colleague's machine and access your own 8001files. When a server goes down, it can cause a process on a client 8002machine to hang. By minimizing the mounted filesystems to only include 8003those actively being used, there is less chance that a filesystem will 8004be mounted when a server goes down. 8005 8006The following is a short extract from a map taken from a research fileserver 8007at Imperial College. 8008 8009Note the entry for @samp{localhost} which is used for users such as 8010the operator (@samp{opr}) who have a home directory on most machine as 8011@samp{/home/localhost/opr}. 8012 8013@example 8014/defaults opts:=rw,intr,grpid,nosuid 8015charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8016 host==$@{key@};type:=ufs;dev:=/dev/xd0g 8017# 8018... 8019 8020# 8021localhost type:=link;fs:=$@{host@} 8022... 8023# 8024# dylan has two user disks so have a 8025# top directory in which to mount them. 8026# 8027dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8028# 8029dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8030 host==dylan;type:=ufs;dev:=/dev/dsk/2s0 8031# 8032dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 8033 host==dylan;type:=ufs;dev:=/dev/dsk/5s0 8034... 8035# 8036toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8037 host==$@{key@};type:=ufs;dev:=/dev/xy1g 8038... 8039# 8040zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 8041 host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 8042# 8043# Just for access... 8044# 8045gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8046gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} 8047# 8048gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} 8049... 8050@end example 8051 8052This map is shared by most of the machines listed so on those 8053systems any of the user disks is accessible via a consistent name. 8054@i{Amd} is started with the following command 8055 8056@example 8057amd /home amd.home 8058@end example 8059 8060Note that when mounting a remote filesystem, the @dfn{automounted} 8061mount point is referenced, so that the filesystem will be mounted if 8062it is not yet (at the time the remote @samp{mountd} obtains the file handle). 8063 8064@node Home Directories, Architecture Sharing, User Filesystems, Examples 8065@comment node-name, next, previous, up 8066@section Home Directories 8067@cindex Home directories 8068@cindex Example of mounting home directories 8069@cindex Mount home directories 8070 8071One convention for home directories is to locate them in @samp{/homes} 8072so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more 8073than a single fileserver it is convenient to spread user files across 8074several machines. All that is required is a mount-map which converts 8075login names to an automounted directory. 8076 8077Such a map might be started by the command: 8078 8079@example 8080amd /homes amd.homes 8081@end example 8082 8083where the map @samp{amd.homes} contained the entries: 8084 8085@example 8086/defaults type:=link # All the entries are of type:=link 8087jsp fs:=/home/charm/jsp 8088njw fs:=/home/dylan/dk5/njw 8089... 8090phjk fs:=/home/toytown/ai/phjk 8091sjv fs:=/home/ganymede/sjv 8092@end example 8093 8094Whenever a login name is accessed in @samp{/homes} a symbolic link 8095appears pointing to the real location of that user's home directory. In 8096this example, @samp{/homes/jsp} would appear to be a symbolic link 8097pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also 8098be an automount point. 8099 8100This system causes an extra level of symbolic links to be used. 8101Although that turns out to be relatively inexpensive, an alternative is 8102to directly mount the required filesystems in the @samp{/homes} 8103map. The required map is simple, but long, and its creation is best automated. 8104The entry for @samp{jsp} could be: 8105 8106@example 8107jsp -sublink:=$@{key@};rfs:=/home/charm \ 8108 host==charm;type:=ufs;dev:=/dev/xd0g \ 8109 host!=charm;type:=nfs;rhost:=charm 8110@end example 8111 8112This map can become quite big if it contains a large number of entries. 8113By combining two other features of @i{Amd} it can be greatly simplified. 8114 8115First the UFS partitions should be mounted under the control of 8116@samp{/etc/fstab}, taking care that they are mounted in the same place 8117that @i{Amd} would have automounted them. In most cases this would be 8118something like @samp{/a/@dfn{host}/home/@dfn{host}} and 8119@samp{/etc/fstab} on host @samp{charm} would have a line:@refill 8120 8121@example 8122/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 8123@end example 8124 8125The map can then be changed to: 8126 8127@example 8128/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid 8129jsp rhost:=charm;rfs:=/home/charm 8130njw rhost:=dylan;rfs:=/home/dylan/dk5 8131... 8132phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} 8133sjv rhost:=ganymede;rfs:=/home/ganymede 8134@end example 8135 8136This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} 8137not equal to @code{$@{rhost@}}). On the machine where the filesystem is 8138stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} 8139will construct a local filesystem mount point which corresponds to the 8140name of the locally mounted UFS partition. If @i{Amd} is started with 8141the @code{-r} option then instead of attempting an NFS mount, @i{Amd} will 8142simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If 8143@code{-r} is not used then a loopback NFS mount will be made. This type of 8144mount is known to cause a deadlock on many systems. 8145 8146@node Architecture Sharing, Wildcard Names, Home Directories, Examples 8147@comment node-name, next, previous, up 8148@section Architecture Sharing 8149@cindex Architecture sharing 8150@cindex Sharing a fileserver between architectures 8151@cindex Architecture dependent volumes 8152 8153@c %At the moment some of the research machines have sets of software 8154@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, 8155@c %system sources, local sources, prolog libraries and so on. 8156Often a filesystem will be shared by machines of different architectures. 8157Separate trees can be maintained for the executable images for each 8158architecture, but it may be more convenient to have a shared tree, 8159with distinct subdirectories. 8160 8161A shared tree might have the following structure on the fileserver (called 8162@samp{fserver} in the example): 8163 8164@example 8165local/tex 8166local/tex/fonts 8167local/tex/lib 8168local/tex/bin 8169local/tex/bin/sun3 8170local/tex/bin/sun4 8171local/tex/bin/hp9000 8172... 8173@end example 8174 8175In this example, the subdirectories of @samp{local/tex/bin} should be 8176hidden when accessed via the automount point (conventionally @samp{/vol}). 8177A mount-map for @samp{/vol} to achieve this would look like: 8178 8179@example 8180/defaults sublink:=$@{/key@};rhost:=fserver;type:=link 8181tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ 8182tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ 8183 host==fserver;fs:=/usr/local/tex 8184tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ 8185 host==fserver;fs:=/usr/local/tex 8186tex/bin -sublink:=$@{/key@}/$@{arch@} \ 8187 host!=fserver;type:=nfs;rfs:=/vol/tex \ 8188 host:=fserver;fs:=/usr/local/tex 8189@end example 8190 8191When @samp{/vol/tex/bin} is referenced, the current machine architecture 8192is automatically appended to the path by the @code{$@{sublink@}} 8193variable. This means that users can have @samp{/vol/tex/bin} in their 8194@samp{PATH} without concern for architecture dependencies. 8195 8196@node Wildcard Names, rwho servers, Architecture Sharing, Examples 8197@comment node-name, next, previous, up 8198@section Wildcard Names & Replicated Servers 8199 8200By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing 8201directory with additional entries. 8202The system files are usually mounted under @samp{/usr}. If instead, 8203@i{Amd} is mounted on @samp{/usr}, additional 8204names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. 8205A map to do this would have the form: 8206 8207@example 8208local type:=auto;fs:=local-map 8209share type:=auto;fs:=share-map 8210* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ 8211 rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 8212@end example 8213 8214Note that the assignment to @code{$@{sublink@}} is surrounded by double 8215quotes to prevent the incoming key from causing the map to be 8216misinterpreted. This map has the effect of directing any access to 8217@samp{/usr/local} or @samp{/usr/share} to another automount point. 8218 8219In this example, it is assumed that the @samp{/usr} files are replicated 8220on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. 8221For any references other than to @samp{local} and @samp{share} one of 8222the servers is used and a symbolic link to 8223@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is 8224returned once an appropriate filesystem has been mounted.@refill 8225 8226@node rwho servers, /vol, Wildcard Names, Examples 8227@comment node-name, next, previous, up 8228@section @samp{rwho} servers 8229@cindex rwho servers 8230@cindex Architecture specific mounts 8231@cindex Example of architecture specific mounts 8232 8233The @samp{/usr/spool/rwho} directory is a good candidate for automounting. 8234For efficiency reasons it is best to capture the rwho data on a small 8235number of machines and then mount that information onto a large number 8236of clients. The data written into the rwho files is byte order dependent 8237so only servers with the correct byte ordering can be used by a client: 8238 8239@example 8240/defaults type:=nfs 8241usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ 8242 rhost:=vaxA rhost:=vaxB \ 8243 || -rfs:=/usr/spool/rwho \ 8244 rhost:=sun4 rhost:=hp300 8245@end example 8246 8247@node /vol, /defaults with selectors, rwho servers, Examples 8248@comment node-name, next, previous, up 8249@section @samp{/vol} 8250@cindex /vol 8251@cindex Catch-all mount point 8252@cindex Generic volume name 8253 8254@samp{/vol} is used as a catch-all for volumes which do not have other 8255conventional names. 8256 8257Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. 8258The @samp{r+d} tree is used for new or experimental software that needs 8259to be available everywhere without installing it on all the fileservers. 8260Users wishing to try out the new software then simply include 8261@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill 8262 8263The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has 8264different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} 8265sub-directories for each machine architecture. For example, 8266@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory 8267@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed 8268a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be 8269returned.@refill 8270 8271@example 8272/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft 8273wp -opts:=rw,grpid,nosuid;rhost:=charm \ 8274 host==charm;type:=link;fs:=/usr/local/wp \ 8275 host!=charm;type:=nfs;rfs:=/vol/wp 8276... 8277# 8278src -opts:=rw,grpid,nosuid;rhost:=charm \ 8279 host==charm;type:=link;fs:=/usr/src \ 8280 host!=charm;type:=nfs;rfs:=/vol/src 8281# 8282r+d type:=auto;fs:=$@{map@};pref:=r+d/ 8283# per architecture bin,etc,lib&ucb... 8284r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8285r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8286r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8287r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8288r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8289r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 8290r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 8291# hades pictures 8292pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8293 host==thpfs;type:=link;fs:=/nbsd/pictures \ 8294 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures 8295# hades tools 8296hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ 8297 host==thpfs;type:=link;fs:=/nbsd/hades \ 8298 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades 8299# bsd tools for hp. 8300bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ 8301 host==thpfs;type:=link;fs:=/nbsd/bsd \ 8302 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd 8303@end example 8304 8305@node /defaults with selectors, /tftpboot in a chroot-ed environment, /vol, Examples 8306@comment node-name, next, previous, up 8307@section @samp{/defaults} with selectors 8308@cindex /defaults with selectors 8309@cindex selectors on default 8310 8311It is sometimes useful to have different defaults for a given map. To 8312achieve this, the @samp{/defaults} entry must be able to process normal 8313selectors. This feature is turned on by setting 8314@samp{selectors_in_defaults = yes} in the @file{amd.conf} file. 8315@xref{selectors_in_defaults Parameter}. 8316 8317In this example, I set different default NFS mount options for hosts 8318which are running over a slower network link. By setting a smaller size 8319for the NFS read and write buffer sizes, you can greatly improve remote 8320file service performance. 8321 8322@example 8323/defaults \ 8324 wire==slip-net;opts:=rw,intr,rsize=1024,wsize=1024,timeo=20,retrans=10 \ 8325 wire!=slip-net;opts:=rw,intr 8326@end example 8327 8328@node /tftpboot in a chroot-ed environment, , /defaults with selectors, Examples 8329@comment node-name, next, previous, up 8330@section @samp{/tftpboot} in a chroot-ed environment 8331@cindex /tftpboot in a chroot-ed environment 8332@cindex chroot; /tftpboot example 8333 8334In this complex example, we attempt to run an @i{Amd} process 8335@emph{inside} a chroot-ed environment. @samp{tftpd} (Trivial FTP) is 8336used to trivially retrieve files used to boot X-Terminals, Network 8337Printers, Network routers, diskless workstations, and other such 8338devices. For security reasons, @samp{tftpd} (and also @samp{ftpd}) 8339processes are run using the @b{chroot}(2) system call. This provides an 8340environment for these processes, where access to any files outside the 8341directory where the chroot-ed process runs is denied. 8342 8343For example, if you start @samp{tftpd} on your system with 8344 8345@example 8346chroot /tftpboot /usr/sbin/tftpd 8347@end example 8348 8349@noindent 8350then the @samp{tftpd} process will not be able to access any files 8351outside @file{/tftpboot}. This ensures that no one can retrieve files 8352such as @file{/etc/passwd} and run password crackers on it. 8353 8354Since the TFTP service works by broadcast, it is necessary to have at 8355least one TFTP server running on each subnet. If you have lots of files 8356that you need to make available for @samp{tftp}, and many subnets, it 8357could take significant amounts of disk space on each host serving them. 8358 8359A solution we implemented at Columbia University was to have every host 8360run @samp{tftpd}, but have those servers retrieve the boot files from 8361two replicated servers. Those replicated servers have special 8362partitions dedicated to the many network boot files. 8363 8364We start @i{Amd} as follows: 8365 8366@example 8367amd /tftpboot/.amd amd.tftpboot 8368@end example 8369 8370That is, @i{Amd} is serving the directory @file{/tftpboot/.amd}. The 8371@samp{tftp} server runs inside @file{/tftpboot} and is chroot-ed in that 8372directory too. The @file{amd.tftpboot} map looks like: 8373 8374@example 8375# 8376# Amd /tftpboot directory -> host map 8377# 8378 8379/defaults opts:=nosuid,ro,intr,soft;fs:=/tftpboot/import;type:=nfs 8380 8381tp host==lol;rfs:=/n/lol/import/tftpboot;type:=lofs \ 8382 host==ober;rfs:=/n/ober/misc/win/tftpboot;type:=lofs \ 8383 rhost:=ober;rfs:=/n/ober/misc/win/tftpboot \ 8384 rhost:=lol;rfs:=/n/lol/import/tftpboot 8385@end example 8386 8387To help understand this example, I list a few of the file entries that 8388are created inside @file{/tftpboot}: 8389 8390@example 8391$ ls -la /tftpboot 8392dr-xr-xr-x 2 root 512 Aug 30 23:11 .amd 8393drwxrwsr-x 12 root 512 Aug 30 08:00 import 8394lrwxrwxrwx 1 root 33 Feb 27 1997 adminpr.cfg -> ./.amd/tp/hplj/adminpr.cfg 8395lrwxrwxrwx 1 root 22 Dec 5 1996 tekxp -> ./.amd/tp/xterms/tekxp 8396lrwxrwxrwx 1 root 1 Dec 5 1996 tftpboot -> . 8397@end example 8398 8399Here is an explanation of each of the entries listed above: 8400 8401@table @code 8402 8403@item .amd 8404This is the @i{Amd} mount point. Note that you do not need to run a 8405separate @i{Amd} process for the TFTP service. The @b{chroot}(2) system 8406call only protects against file access, but the same process can still 8407serve files and directories inside and outside the chroot-ed 8408environment, because @i{Amd} itself was not run in chroot-ed mode. 8409 8410@item import 8411This is the mount point where @i{Amd} will mount the directories 8412containing the boot files. The map is designed so that remote 8413directories will be NFS mounted (even if they are already mounted 8414elsewhere), and local directories are loopback mounted (since they are 8415not accessible outside the chroot-ed @file{/tftpboot} directory). 8416 8417@item adminpr.cfg 8418@itemx tekxp 8419Two manually created symbolic links to directories @emph{inside} the 8420@i{Amd}-managed directory. The crossing of the component @file{tp} will 8421cause @i{Amd} to automount one of the remote replicas. Once crossed, 8422access to files inside proceeds as usual. The @samp{adminpr.cfg} is a 8423configuration file for an HP Laser-Jet 4si printer, and the @samp{tekxp} 8424is a directory for Tektronix X-Terminal boot files. 8425 8426@item tftpboot 8427This innocent looking symlink is important. Usually, when devices boot 8428via the TFTP service, they perform the @samp{get file} command to 8429retrieve @var{file}. However, some devices assume that @samp{tftpd} 8430does not run in a chroot-ed environment, but rather ``unprotected'', and 8431thus use a full pathname for files to retrieve, as in @samp{get 8432/tftpboot/file}. This symlink effectively strips out the leading 8433@file{/tftpboot/}. 8434 8435@end table 8436 8437@c ################################################################ 8438@node Internals, Acknowledgments & Trademarks, Examples, Top 8439@comment node-name, next, previous, up 8440@chapter Internals 8441 8442Note that there are more error and logging messages possible than are 8443listed here. Most of them are self-explanatory. Refer to the program 8444sources for more details on the rest. 8445 8446@menu 8447* Log Messages:: 8448@end menu 8449 8450@node Log Messages, , Internals, Internals 8451@comment node-name, next, previous, up 8452@section Log Messages 8453 8454In the following sections a brief explanation is given of some of the 8455log messages made by @i{Amd}. Where the message is in @samp{typewriter} 8456font, it corresponds exactly to the message produced by @i{Amd}. Words 8457in @dfn{italic} are replaced by an appropriate string. Variables, 8458@code{$@{@i{var}@}}, indicate that the value of the appropriate variable is 8459output. 8460 8461Log messages are either sent directly to a file, 8462or logged via the @b{syslog}(3) mechanism. @xref{log_file Parameter}. 8463In either case, entries in the file are of the form: 8464@example 8465@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} 8466@end example 8467 8468@menu 8469* Fatal errors:: 8470* Info messages:: 8471@end menu 8472 8473@node Fatal errors, Info messages, Log Messages, Log Messages 8474@comment node-name, next, previous, up 8475@subsection Fatal errors 8476 8477@i{Amd} attempts to deal with unusual events. Whenever it is not 8478possible to deal with such an error, @i{Amd} will log an appropriate 8479message and, if it cannot possibly continue, will either exit or abort. 8480These messages are selected by @samp{-x fatal} on the command line. 8481When @b{syslog}(3) is being used, they are logged with level 8482@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to 8483remain in a precarious state and should be restarted at the earliest 8484opportunity. 8485 8486@table @t 8487 8488@item Attempting to inherit not-a-filesystem 8489The prototype mount point created during a filesystem restart did not 8490contain a reference to the restarted filesystem. This error ``should 8491never happen''. 8492 8493@item Can't bind to domain "@i{NIS-domain}" 8494A specific NIS domain was requested on the command line, but no server 8495for that domain is available on the local net. 8496 8497@item Can't determine IP address of this host (@i{hostname}) 8498When @i{Amd} starts it determines its own IP address. If this lookup 8499fails then @i{Amd} cannot continue. The hostname it looks up is that 8500obtained returned by @b{gethostname}(2) system call. 8501 8502@item Can't find root file handle for @i{automount point} 8503@i{Amd} creates its own file handles for the automount points. When it 8504mounts itself as a server, it must pass these file handles to the local 8505kernel. If the filehandle is not obtainable the mount point is ignored. 8506This error ``should never happen''. 8507 8508@item Must be root to mount filesystems (euid = @i{euid}) 8509To prevent embarrassment, @i{Amd} makes sure it has appropriate system 8510privileges. This amounts to having an euid of 0. The check is made 8511after argument processing complete to give non-root users a chance to 8512access the @code{-v} option. 8513 8514@item No work to do - quitting 8515No automount points were given on the command line and so there is no 8516work to do. 8517 8518@item Out of memory 8519While attempting to malloc some memory, the memory space available to 8520@i{Amd} was exhausted. This is an unrecoverable error. 8521 8522@item Out of memory in realloc 8523While attempting to realloc some memory, the memory space available to 8524@i{Amd} was exhausted. This is an unrecoverable error. 8525 8526@item cannot create rpc/udp service 8527Either the NFS or AMQ endpoint could not be created. 8528 8529@item gethostname: @i{description} 8530The @b{gethostname}(2) system call failed during startup. 8531 8532@item host name is not set 8533The @b{gethostname}(2) system call returned a zero length host name. 8534This can happen if @i{Amd} is started in single user mode just after 8535booting the system. 8536 8537@item ifs_match called! 8538An internal error occurred while restarting a pre-mounted filesystem. 8539This error ``should never happen''. 8540 8541@item mount_afs: @i{description} 8542An error occurred while @i{Amd} was mounting itself. 8543 8544@item run_rpc failed 8545Somehow the main NFS server loop failed. This error ``should never 8546happen''. 8547 8548@item unable to free rpc arguments in amqprog_1 8549The incoming arguments to the AMQ server could not be free'ed. 8550 8551@item unable to free rpc arguments in nfs_program_1 8552The incoming arguments to the NFS server could not be free'ed. 8553 8554@item unable to register (AMQ_PROGRAM, AMQ_VERSION, udp) 8555The AMQ server could not be registered with the local portmapper or the 8556internal RPC dispatcher. 8557 8558@item unable to register (NFS_PROGRAM, NFS_VERSION, 0) 8559The NFS server could not be registered with the internal RPC dispatcher. 8560 8561@end table 8562 8563XXX: This section needs to be updated 8564 8565@node Info messages, , Fatal errors, Log Messages 8566@comment node-name, next, previous, up 8567@subsection Info messages 8568 8569@i{Amd} generates information messages to record state changes. These 8570messages are selected by @samp{-x info} on the command line. When 8571@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. 8572 8573The messages listed below can be generated and are in a format suitable 8574for simple statistical analysis. @dfn{mount-info} is the string 8575that is displayed by @dfn{Amq} in its mount information column and 8576placed in the system mount table. 8577 8578@table @t 8579 8580@item "@t{$@{@i{path}@}}" forcibly timed out 8581An automount point has been timed out by the @i{Amq} command. 8582 8583@item "@t{$@{@i{path}@}}" has timed out 8584No access to the automount point has been made within the timeout 8585period. 8586 8587@item Filehandle denied for "$@{@i{rhost}@}:$@{@i{rfs}@}" 8588The mount daemon refused to return a file handle for the requested filesystem. 8589 8590@item Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}": @i{description} 8591The mount daemon gave some other error for the requested filesystem. 8592 8593@item Finishing with status @i{exit-status} 8594@i{Amd} is about to exit with the given exit status. 8595 8596@item Re-synchronizing cache for map @t{$@{@i{map}@}} 8597The named map has been modified and the internal cache is being re-synchronized. 8598 8599@item file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored 8600An automount point has timed out, but the corresponding file server is 8601known to be down. This message is only produced once for each mount 8602point for which the server is down. 8603 8604@item file server @t{$@{@i{rhost}@}} type nfs is down 8605An NFS file server that was previously up is now down. 8606 8607@item file server @t{$@{@i{rhost}@}} type nfs is up 8608An NFS file server that was previously down is now up. 8609 8610@item file server @t{$@{@i{rhost}@}} type nfs starts down 8611A new NFS file server has been referenced and is known to be down. 8612 8613@item file server @t{$@{@i{rhost}@}} type nfs starts up 8614A new NFS file server has been referenced and is known to be up. 8615 8616@item mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out 8617Attempts to mount a filesystem for the given automount point have failed 8618to complete within 30 seconds. 8619 8620@item @i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8621A new file system has been mounted. 8622 8623@item @i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}} 8624@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. 8625 8626@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} 8627A file system has been unmounted. 8628 8629@item @i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}} 8630A file system of which only a sub-directory was in use has been unmounted. 8631 8632@item restarting @i{mount-info} on @t{$@{@i{fs}@}} 8633A pre-mounted file system has been noted. 8634 8635@end table 8636 8637XXX: This section needs to be updated 8638 8639@c ################################################################ 8640@node Acknowledgments & Trademarks, Index, Internals, Top 8641@comment node-name, next, previous, up 8642@unnumbered Acknowledgments & Trademarks 8643 8644Many thanks to the Am-Utils Users 8645mailing list through the months developing am-utils. These members 8646have contributed to the discussions, ideas, code and documentation, 8647and subjected their systems to alpha quality code. Special thanks go 8648to those @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors} who have 8649submitted patches, and especially to the maintainers: 8650 8651@itemize @bullet 8652@item @uref{http://www.cs.sunysb.edu/~ezk,Erez Zadok} 8653@item @email{ionut AT badula.org,Ion Badulescu} 8654@item @email{ro AT techfak.uni-bielefeld.de,Rainer Orth} 8655@item @email{nick.williams AT morganstanley.com,Nick Williams} 8656@end itemize 8657 8658Thanks to the Formal Methods Group at Imperial College for suffering 8659patiently while @i{Amd} was being developed on their machines. 8660 8661Thanks to the many people who have helped with the development of 8662@i{Amd}, especially Piete Brooks at the Cambridge University Computing 8663Lab for many hours of testing, experimentation and discussion. 8664 8665Thanks to the older @email{amd-workers AT majordomo.glue.umd.edu,Amd 8666Workers} mailing list (now defunct) members for many suggestions and 8667bug reports to @i{Amd}. 8668 8669@itemize @bullet 8670@item 8671@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital 8672Equipment Corporation. 8673@item 8674@b{AIX} and @b{IBM} are registered trademarks of International Business 8675Machines Corporation. 8676@item 8677@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun 8678Microsystems, Inc. 8679@item 8680@b{UNIX} is a registered trademark in the USA and other countries, 8681exclusively licensed through X/Open Company, Ltd. 8682@item 8683All other registered trademarks are owned by their respective owners. 8684@end itemize 8685 8686@c ################################################################ 8687@node Index, , Acknowledgments & Trademarks, Top 8688@comment node-name, next, previous, up 8689@unnumbered Index 8690 8691@printindex cp 8692 8693@contents 8694@bye 8695 8696@c ==================================================================== 8697@c ISPELL LOCAL WORDS: 8698@c LocalWords: setfilename amdref overfullrule settitle titlepage titlefont nz 8699@c LocalWords: authorfont vskip ifinfo iftex cindex unnumberedsec dfn xref vol 8700@c LocalWords: locationN pxref jpo nott concentrix Sjoerd sjoerd cwi Eitan vuw 8701@c LocalWords: Mizrotsky eitan shumuji dgux fpx scp hcx metcalf masala hlh OTS 8702@c LocalWords: Presnell srp cgl Trost trost ogi pyrOSx OSx tubsibr riscix iX 8703@c LocalWords: Piete pb Lindblad cjl ai umax utek xinu Mitchum D'Souza dsouza 8704@c LocalWords: mrc apu alliant aviion AViiON fps macII multimax tahoe vax emph 8705@c LocalWords: mapdefault valA valB valC YPTSDIR ETCDIR substr MAKEDBM YPDBDIR 8706@c LocalWords: NOPUSH njw dylan dk dylan njw anydir domN achilles mjh pref sel 8707@c LocalWords: gdef loc loc loc ldots autodir remopts rwho rwho styx styx yoyo 8708@c LocalWords: noindent gould rvdmount rvdunmount fserver mtmp unioned logfile 8709@c LocalWords: dmn esac phjk toytown toytown toytown toytown phjk RdDir RdLnk 8710@c LocalWords: volname attrs netif dougal inaddr hwaddr ec mountmaps passno xy 8711@c LocalWords: freq dumpset hfs brian florence localinfo fstabs automaps defn 8712@c LocalWords: localname fsck'd opr gummo sjv ganymede sjv fserv fserv fserv 8713@c LocalWords: vaxA vaxB wp thpfs nbsd asis ifs amqprog free'ed printindex gov 8714@c LocalWords: LocalWords syncodeindex Distrib bsdnet lanl AutoMounter acis ic 8715@c LocalWords: ac uk aix bsd Mullender nl il DG lcs hpux irix ucsf NeXT cse cl 8716@c LocalWords: mt FX hp ibm mips utils def def Domainname eg hostd getwd tmp 8717@c LocalWords: subsubsection rw grpid intr noconn nocto nodevs nosuid retrans 8718@c LocalWords: rsize tcp timeo nounmount utimeout DDEBUG nodaemon fd hostnames 8719@c LocalWords: pid Amd's pendry vangogh nfsx backoff stats nomap nostats CRIT 8720@c LocalWords: noinfo clustername RVD dsk dsk amq hostports osver statfs str 8721@c LocalWords: ou counter's amdmaps proj src tftpboot sh mv cd sbin ypcat inet 8722@c LocalWords: Getattr getattr localhost fhandles netmask fstype noquota addr 8723@c LocalWords: exportfs Dumpsets dumpsets pindex ldif fixmount fixrmtab euid 8724@c LocalWords: lostaltmail realloc netnumber itemx primnetnum primnetname ARG 8725@c LocalWords: subsnetname subsnetnum netgrp netgroup multitable Shlib dec osf 8726@c LocalWords: hppa pc bsdi freebsd netbsd openbsd ncr sysv rs acdirmax fsid 8727@c LocalWords: acdirmin acregmax acregmin actimeo dumbtimr nfsv noac noauto sd 8728@c LocalWords: nocache nodev noint nosub pgthresh posix rdonly suid symttl mfs 8729@c LocalWords: AMFS umapfs myftpdir unionfs es mapname mapfile mapfile slocal 8730@c LocalWords: mailspool saturn saturn notknown lol ober dr xr xr drwxrwsr cfg 8731@c LocalWords: lrwxrwxrwx adminpr hplj adminpr cfg tekxp xterms tekxp Dupuy tp 8732@c LocalWords: linkname hlfsddump dirname rmtab pluto rlogin direntry pg vr dn 8733@c LocalWords: maxmem hlfsdir xmailbox showmount cn amdmap amdmapName resvport 8734@c LocalWords: objectClass amdmapKey amdmapValue ln powerpc amdmapTimestamp ez 8735@c LocalWords: moisil FSinfo Libtool Unmounting sublink fileservers NullProc 8736@c LocalWords: gethostname mount's unmounts linkx remounts unmounting UAs SA's 8737@c LocalWords: mountpoint mountpoints unescaped UIDs util's overlayed uref EFS 8738@c LocalWords: serv maxgroups nfsl cachedir copt cfsadmin efs addopts fg ROMs 8739@c LocalWords: nointr extatt setchapternewpage columnfractions alphaev gnulibc 8740@c LocalWords: freebsdelf gnuoldld ifhtml defperm nodefperm norrip RRIP rrip 8741@c LocalWords: noversion attr XXXXXX netgrpd rh mkstemp uid gid noexec mntfs 8742@c LocalWords: nomnttab optionstr hrtime xdrtrace getpwd proplist redhat ctl 8743@c LocalWords: texinfo texi ib sp cartouche ified xlatecookie dircategory sc 8744@c LocalWords: AddInfo suse Novell softlookup ENOENT USB fullybrowsable LDAPv 8745@c LocalWords: amy ie xfffffe zebedee andrew diskfull hdmail searchable si 8746@c LocalWords: Orth ESTALE 8747