1\input texinfo @c -*-texinfo-*- 2@c 3@c Copyright (c) 1989 Jan-Simon Pendry 4@c Copyright (c) 1989 Imperial College of Science, Technology & Medicine 5@c Copyright (c) 1989 The Regents of the University of California. 6@c All rights reserved. 7@c 8@c This code is derived from software contributed to Berkeley by 9@c Jan-Simon Pendry at Imperial College, London. 10@c 11@c Redistribution and use in source and binary forms, with or without 12@c modification, are permitted provided that the following conditions 13@c are met: 14@c 1. Redistributions of source code must retain the above copyright 15@c notice, this list of conditions and the following disclaimer. 16@c 2. Redistributions in binary form must reproduce the above copyright 17@c notice, this list of conditions and the following disclaimer in the 18@c documentation and/or other materials provided with the distribution. 19@c 3. All advertising materials mentioning features or use of this software 20@c must display the following acknowledgement: 21@c This product includes software developed by the University of 22@c California, Berkeley and its contributors. 23@c 4. Neither the name of the University nor the names of its contributors 24@c may be used to endorse or promote products derived from this software 25@c without specific prior written permission. 26@c 27@c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 28@c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 29@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 30@c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 31@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 32@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 33@c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 34@c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 35@c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 36@c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 37@c 38@c @(#)amdref.texinfo 8.1 (Berkeley) 06/06/93 39@c 40@c $Id: amdref.texinfo,v 5.2.2.1 1992/02/09 15:11:50 jsp beta $ 41@c 42@setfilename amdref.info 43@c @setfilename /usr/local/emacs/info/amd 44@tex 45\overfullrule=0pt 46@end tex 47 48@settitle 4.4 BSD Automounter Reference Manual 49@titlepage 50@sp 6 51@center @titlefont{Amd} 52@sp 2 53@center @titlefont{The 4.4 BSD Automounter} 54@sp 2 55@center @titlefont{Reference Manual} 56@sp 2 57@center @authorfont{Jan-Simon Pendry} 58@sp 59@center @i{and} 60@sp 61@center @authorfont{Nick Williams} 62@sp 4 63@center Last updated March 1991 64@center Documentation for software revision 5.3 Alpha 65@page 66Copyright @copyright{} 1989 Jan-Simon Pendry 67@sp -1 68Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine 69@sp -1 70Copyright @copyright{} 1989 The Regents of the University of California. 71@sp 0 72All Rights Reserved. 73@vskip 1ex 74Permission to copy this document, or any portion of it, as 75necessary for use of this software is granted provided this 76copyright notice and statement of permission are included. 77@end titlepage 78@page 79@ifinfo 80@node Top, License, , (DIR) 81 82Amd - The 4.4 BSD Automounter 83***************************** 84 85Amd is the 4.4 BSD Automounter. This Info file describes how 86to use and understand Amd. 87@end ifinfo 88 89@menu 90* License:: Explains the terms and conditions for using 91 and distributing Amd. 92* Distrib:: How to get the latest Amd distribution. 93* Intro:: An introduction to Automounting concepts. 94* Overview:: An overview of Amd. 95* Supported Platforms:: Machines and Systems supported by Amd. 96* Mount Maps:: Details of mount maps 97* Amd Command Line Options:: All the Amd command line options explained. 98* Filesystem Types:: The different mount types supported by Amd. 99* Run-time Administration:: How to start, stop and control Amd. 100* FSinfo:: The FSinfo filesystem management tool. 101* Internals:: Internals. 102* Acknowledgements & Trademarks:: Legal notes. 103* Examples:: Some examples showing how Amd might be used. 104* Internals:: Implementation details. 105* Acknowledgements & Trademarks:: 106 107Indexes 108* Index:: An item for each concept. 109@end menu 110 111@iftex 112@unnumbered Preface 113 114This manual documents the use of the 4.4 BSD automounter---@i{Amd}. 115This is primarily a reference manual. Unfortunately, no tutorial 116exists. 117 118This manual comes in two forms: the published form and the Info form. 119The Info form is for on-line perusal with the INFO program which is 120distributed along with GNU Emacs. Both forms contain substantially the 121same text and are generated from a common source file, which is 122distributed with the @i{Amd} source. 123@end iftex 124 125@node License, Distrib, Top, Top 126@unnumbered License 127@cindex License Information 128 129@i{Amd} is not in the public domain; it is copyrighted and there are 130restrictions on its distribution. 131 132Redistribution and use in source and binary forms are permitted provided 133that: (1) source distributions retain this entire copyright notice and 134comment, and (2) distributions including binaries display the following 135acknowledgement: ``This product includes software developed by The 136University of California, Berkeley and its Contributors'' in the 137documentation or other materials provided with the distribution and in 138all advertising materials mentioning features or use of this software. 139neither the name of the University nor the names of its Contributors may 140be used to endorse or promote products derived from this software 141without specific prior written permission. 142 143THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED 144WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 145MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 146 147@node Distrib, Intro, License, Top 148@unnumbered Source Distribution 149@cindex Source code distribution 150@cindex Obtaining the source code 151 152If you have access to the Internet, you can get the latest distribution 153version of @i{Amd} from host @file{usc.edu} using anonymous FTP. Move to 154the directory @file{/pub/amd} on that host and fetch the file @file{amd.tar.Z}. 155 156If you are in the UK, you can get the latest distribution version of 157@i{Amd} from the UKnet info-server. Start by sending email to 158@file{info-server@@doc.ic.ac.uk}. 159 160Sites on the UK JANET network can get the latest distribution by using 161anonymous NIFTP to fetch the file @samp{<AMD>amd.tar.Z} from host 162@samp{uk.ac.imperial.doc.src}. 163 164Revision 5.2 was part of the 4.3 BSD Reno distribution. 165 166Revision 5.3bsdnet, a late alpha version of 5.3, was part 167of the BSD network version 2 distribution 168 169@unnumberedsec Bug Reports 170@cindex Bug reports 171 172Send all bug reports to @file{jsp@@doc.ic.ac.uk} quoting the details of 173the release and your configuration. These can be obtained by running 174the command @samp{amd -v}. 175 176@unnumberedsec Mailing List 177@cindex Mailing list 178 179There is a mailing list for people interested in keeping uptodate with 180developments. To subscribe, send a note to @file{amd-workers-request@@acl.lanl.gov}. 181 182@node Intro, Overview, Distrib, Top 183@unnumbered Introduction 184@cindex Introduction 185 186An @dfn{automounter} maintains a cache of mounted filesystems. 187Filesystems are mounted on demand when they are first referenced, 188and unmounted after a period of inactivity. 189 190@i{Amd} may be used as a replacement for Sun's automounter. The choice 191of which filesystem to mount can be controlled dynamically with 192@dfn{selectors}. Selectors allow decisions of the form ``hostname is 193@var{this},'' or ``architecture is not @var{that}.'' Selectors may be 194combined arbitrarily. @i{Amd} also supports a variety of filesystem 195types, including NFS, UFS and the novel @dfn{program} filesystem. The 196combination of selectors and multiple filesystem types allows identical 197configuration files to be used on all machines so reducing the 198administrative overhead. 199 200@i{Amd} ensures that it will not hang if a remote server goes down. 201Moreover, @i{Amd} can determine when a remote server has become 202inaccessible and then mount replacement filesystems as and when they 203become available. 204 205@i{Amd} contains no proprietary source code and has been ported to 206numerous flavours of Unix. 207 208@node Overview, Supported Platforms, Intro, Top 209@chapter Overview 210 211@i{Amd} maintains a cache of mounted filesystems. Filesystems are 212@dfn{demand-mounted} when they are first referenced, and unmounted after 213a period of inactivity. @i{Amd} may be used as a replacement for Sun's 214@b{automount}(8) program. It contains no proprietary source code and 215has been ported to numerous flavours of Unix. @xref{Supported Operating 216Systems}.@refill 217 218@i{Amd} was designed as the basis for experimenting with filesystem 219layout and management. Although @i{Amd} has many direct applications it 220is loaded with additional features which have little practical use. At 221some point the infrequently used components may be removed to streamline 222the production system. 223 224@c @i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating 225@c each member of a list of possible filesystem locations in parallel. 226@c @i{Amd} checks that each cached mapping remains valid. Should a mapping be 227@c lost -- such as happens when a fileserver goes down -- @i{Amd} automatically 228@c selects a replacement should one be available. 229@c 230@menu 231* Fundamentals:: 232* Filesystems and Volumes:: 233* Volume Naming:: 234* Volume Binding:: 235* Operational Principles:: 236* Mounting a Volume:: 237* Automatic Unmounting:: 238* Keep-alives:: 239* Non-blocking Operation:: 240@end menu 241 242@node Fundamentals, Filesystems and Volumes, Overview, Overview 243@comment node-name, next, previous, up 244@section Fundamentals 245@cindex Automounter fundamentals 246 247The fundamental concept behind @i{Amd} is the ability to separate the 248name used to refer to a file from the name used to refer to its physical 249storage location. This allows the same files to be accessed with the 250same name regardless of where in the network the name is used. This is 251very different from placing @file{/n/hostname} in front of the pathname 252since that includes location dependent information which may change if 253files are moved to another machine. 254 255By placing the required mappings in a centrally administered database, 256filesystems can be re-organised without requiring changes to 257configuration files, shell scripts and so on. 258 259@node Filesystems and Volumes, Volume Naming, Fundamentals, Overview 260@comment node-name, next, previous, up 261@section Filesystems and Volumes 262@cindex Filesystem 263@cindex Volume 264@cindex Fileserver 265@cindex sublink 266 267@i{Amd} views the world as a set of fileservers, each containg one or 268more filesystems where each filesystem contains one or more 269@dfn{volumes}. Here the term @dfn{volume} is used to refer to a 270coherent set of files such as a user's home directory or a @TeX{} 271distribution.@refill 272 273In order to access the contents of a volume, @i{Amd} must be told in 274which filesystem the volume resides and which host owns the filesystem. 275By default the host is assumed to be local and the volume is assumed to 276be the entire filesystem. If a filesystem contains more than one 277volume, then a @dfn{sublink} is used to refer to the sub-directory 278within the filesystem where the volume can be found. 279 280@node Volume Naming, Volume Binding, Filesystems and Volumes, Overview 281@comment node-name, next, previous, up 282@section Volume Naming 283@cindex Volume names 284@cindex Network-wide naming 285@cindex Replicated volumes 286@cindex Duplicated volumes 287@cindex Replacement volumes 288 289Volume names are defined to be unique across the entire network. A 290volume name is the pathname to the volume's root as known by the users 291of that volume. Since this name uniquely identifies the volume 292contents, all volumes can be named and accessed from each host, subject 293to administrative controls. 294 295Volumes may be replicated or duplicated. Replicated volumes contain 296identical copies of the same data and reside at two or more locations in 297the network. Each of the replicated volumes can be used 298interchangeably. Duplicated volumes each have the same name but contain 299different, though functionally identical, data. For example, 300@samp{/vol/tex} might be the name of a @TeX{} distribution which varied 301for each machine architecture.@refill 302 303@i{Amd} provides facilities to take advantage of both replicated and 304duplicated volumes. Configuration options allow a single set of 305configuration data to be shared across an entire network by taking 306advantage of replicated and duplicated volumes. 307 308@i{Amd} can take advantage of replacement volumes by mounting them as 309required should an active fileserver become unavailable. 310 311@node Volume Binding, Operational Principles, Volume Naming, Overview 312@comment node-name, next, previous, up 313@section Volume Binding 314@cindex Volume binding 315@cindex Unix namespace 316@cindex Namespace 317@cindex Binding names to filesystems 318 319Unix implements a namespace of hierarchically mounted filesystems. Two 320forms of binding between names and files are provided. A @dfn{hard 321link} completes the binding when the name is added to the filesystem. A 322@dfn{soft link} delays the binding until the name is accessed. An 323@dfn{automounter} adds a further form in which the binding of name to 324filesystem is delayed until the name is accessed.@refill 325 326The target volume, in its general form, is a tuple (host, filesystem, 327sublink) which can be used to name the physical location of any volume 328in the network. 329 330When a target is referenced, @i{Amd} ignores the sublink element and 331determines whether the required filesystem is already mounted. This is 332done by computing the local mount point for the filesystem and checking 333for an existing filesystem mounted at the same place. If such a 334filesystem already exists then it is assumed to be functionally 335identical to the target filesystem. By default there is a one-to-one 336mapping between the pair (host, filesystem) and the local mount point so 337this assumption is valid. 338 339@node Operational Principles, Mounting a Volume, Volume Binding, Overview 340@comment node-name, next, previous, up 341@section Operational Principles 342@cindex Operational principles 343 344@i{Amd} operates by introducing new mount points into the namespace. 345These are called @dfn{automount} points. The kernel sees these 346automount points as NFS filesystems being served by @i{Amd}. Having 347attached itself to the namespace, @i{Amd} is now able to control the 348view the rest of the system has of those mount points. RPC calls are 349received from the kernel one at a time. 350 351When a @dfn{lookup} call is received @i{Amd} checks whether the name is 352already known. If it is not, the required volume is mounted. A 353symbolic link pointing to the volume root is then returned. Once the 354symbolic link is returned, the kernel will send all other requests 355direct to the mounted filesystem. 356 357If a volume is not yet mounted, @i{Amd} consults a configuration 358@dfn{mount-map} corresponding to the automount point. @i{Amd} then 359makes a runtime decision on what and where to mount a filesystem based 360on the information obtained from the map. 361 362@i{Amd} does not implement all the NFS requests; only those relevant 363to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}. 364Some other calls are also implemented but most simply return an error 365code; for example @dfn{mkdir} always returns ``read-only filesystem''. 366 367@node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview 368@comment node-name, next, previous, up 369@section Mounting a Volume 370@cindex Mounting a volume 371@cindex Location lists 372@cindex Alternate locations 373@cindex Mount retries 374@cindex Background mounts 375 376Each automount point has a corresponding mount map. The mount map 377contains a list of key--value pairs. The key is the name of the volume 378to be mounted. The value is a list of locations describing where the 379filesystem is stored in the network. In the source for the map the 380value would look like 381 382@display 383location1 location2 @dots{} locationN 384@end display 385 386@i{Amd} examines each location in turn. Each location may contain 387@dfn{selectors} which control whether @i{Amd} can use that location. 388For example, the location may be restricted to use by certain hosts. 389Those locations which cannot be used are ignored. 390 391@i{Amd} attempts to mount the filesystem described by each remaining 392location until a mount succeeds or @i{Amd} can no longer proceed. The 393latter can occur in three ways: 394 395@itemize @bullet 396@item 397If none of the locations could be used, or if all of the locations 398caused an error, then the last error is returned. 399 400@item 401If a location could be used but was being mounted in the background then 402@i{Amd} marks that mount as being ``in progress'' and continues with 403the next request; no reply is sent to the kernel. 404 405@item 406Lastly, one or more of the mounts may have been @dfn{deferred}. A mount 407is deferred if extra information is required before the mount can 408proceed. When the information becomes available the mount will take 409place, but in the mean time no reply is sent to the kernel. If the 410mount is deferred, @i{Amd} continues to try any remaining locations. 411@end itemize 412 413Once a volume has been mounted, @i{Amd} establishes a @dfn{volume 414mapping} which is used to satisfy subsequent requests.@refill 415 416@node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview 417@comment node-name, next, previous, up 418@section Automatic Unmounting 419 420To avoid an ever increasing number of filesystem mounts, @i{Amd} removes 421volume mappings which have not been used recently. A time-to-live 422interval is associated with each mapping and when that expires the 423mapping is removed. When the last reference to a filesystem is removed, 424that filesystem is unmounted. If the unmount fails, for example the 425filesystem is still busy, the mapping is re-instated and its 426time-to-live interval is extended. The global default for this grace 427period is controlled by the ``-w'' command-line option (@pxref{-w 428Option, -w}). It is also possible to set this value on a per-mount 429basis (@pxref{opts Option, opts, opts}).@refill 430 431Filesystems can be forcefully timed out using the @i{Amq} command. 432@xref{Run-time Administration}. 433 434@node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview 435@comment node-name, next, previous, up 436@section Keep-alives 437@cindex Keep-alives 438@cindex Server crashes 439@cindex NFS ping 440 441Use of some filesystem types requires the presence of a server on 442another machine. If a machine crashes then it is of no concern to 443processes on that machine that the filesystem is unavailable. However, 444to processes on a remote host using that machine as a fileserver this 445event is important. This situation is most widely recognised when an 446NFS server crashes and the behaviour observed on client machines is that 447more and more processes hang. In order to provide the possibility of 448recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some 449filesystem types. Currently only NFS makes use of this service. 450 451The basis of the NFS keep-alive implementation is the observation that 452most sites maintain replicated copies of common system data such as 453manual pages, most or all programs, system source code and so on. If 454one of those servers goes down it would be reasonable to mount one of 455the others as a replacement. 456 457The first part of the process is to keep track of which fileservers are 458up and which are down. @i{Amd} does this by sending RPC requests to the 459servers' NFS @code{NullProc} and checking whether a reply is returned. 460While the server state is uncertain the requests are re-transmitted at 461three second intervals and if no reply is received after four attempts 462the server is marked down. If a reply is received the fileserver is 463marked up and stays in that state for 30 seconds at which time another 464NFS ping is sent. 465 466Once a fileserver is marked down, requests continue to be sent every 30 467seconds in order to determine when the fileserver comes back up. During 468this time any reference through @i{Amd} to the filesystems on that 469server fail with the error ``Operation would block''. If a replacement 470volume is available then it will be mounted, otherwise the error is 471returned to the user. 472 473@c @i{Amd} keeps track of which servers are up and which are down. 474@c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and 475@c checking whether a reply is returned. If no replies are received after a 476@c short period, @i{Amd} marks the fileserver @dfn{down}. 477@c RPC requests continue to be sent so that it will notice when a fileserver 478@c comes back up. 479@c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability 480@c of the NFS service that is important, not the existence of a base kernel. 481@c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate 482@c filesystem is mounted if one is available. 483@c 484Although this action does not protect user files, which are unique on 485the network, or processes which do not access files via @i{Amd} or 486already have open files on the hung filesystem, it can prevent most new 487processes from hanging. 488 489By default, fileserver state is not maintained for NFS/TCP mounts. The 490remote fileserver is always assumed to be up. 491@c 492@c With a suitable combination of filesystem management and mount-maps, 493@c machines can be protected against most server downtime. This can be 494@c enhanced by allocating boot-servers dynamically which allows a diskless 495@c workstation to be quickly restarted if necessary. Once the root filesystem 496@c is mounted, @i{Amd} can be started and allowed to mount the remainder of 497@c the filesystem from whichever fileservers are available. 498 499@node Non-blocking Operation, , Keep-alives, Overview 500@comment node-name, next, previous, up 501@section Non-blocking Operation 502@cindex Non-blocking operation 503@cindex Multiple-threaded server 504@cindex RPC retries 505 506Since there is only one instance of @i{Amd} for each automount point, 507and usually only one instance on each machine, it is important that it 508is always available to service kernel calls. @i{Amd} goes to great 509lengths to ensure that it does not block in a system call. As a last 510resort @i{Amd} will fork before it attempts a system call that may block 511indefinitely, such as mounting an NFS filesystem. Other tasks such as 512obtaining filehandle information for an NFS filesystem, are done using a 513purpose built non-blocking RPC library which is integrated with 514@i{Amd}'s task scheduler. This library is also used to implement NFS 515keep-alives (@pxref{Keep-alives}). 516 517Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it 518to complete before replying to the kernel. However, this would cause 519@i{Amd} to block waiting for a reply to be constructed. Rather than do 520this, @i{Amd} simply @dfn{drops} the call under the assumption that the 521kernel RPC mechanism will automatically retry the request. 522 523@node Supported Platforms, Mount Maps, Overview, Top 524@comment node-name, next, previous, up 525@chapter Supported Platforms 526 527@i{Amd} has been ported to a wide variety of machines and operating systems. 528The table below lists those platforms supported by the current release. 529 530@menu 531* Supported Operating Systems:: 532* Supported Machine Architectures:: 533@end menu 534 535@node Supported Operating Systems, Supported Machine Architectures, Supported Platforms, Supported Platforms 536@comment node-name, next, previous, up 537@section Supported Operating Systems 538@cindex Operating system names 539@cindex Operating systems supported by Amd 540@cindex Supported operating systems 541 542The following operating systems are currently supported by @i{Amd}. 543@i{Amd}'s conventional name for each system is given. 544 545@table @code 546@item acis43 5474.3 BSD for IBM RT. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 548@item aix3 549AIX 3.1. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 550@item aux 551System V for Mac-II. Contributed by Julian Onions @t{<jpo@@cs.nott.ac.uk>} 552@item bsd44 5534.4 BSD. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 554@item concentrix 555Concentrix 5.0. Contributed by Sjoerd Mullender @t{<sjoerd@@cwi.nl>} 556@item convex 557Convex OS 7.1. Contributed by Eitan Mizrotsky @t{<eitan@@shumuji.ac.il>} 558@item dgux 559Data General DG/UX. Contributed by Mark Davies @t{<mark@@comp.vuw.ac.nz>} 560@item fpx4 561Celerity FPX 4.1/2. Contributed by Stephen Pope @t{<scp@@grizzly.acl.lanl.gov>} 562@item hcx 563Harris HCX/UX. Contributed by Chris Metcalf @t{<metcalf@@masala.lcs.mit.edu>} 564@item hlh42 565HLH OTS 1.@i{x} (4.2 BSD). Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 566@item hpux 567HP-UX 6.@i{x} or 7.0. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 568@item irix 569SGI Irix. Contributed by Scott R. Presnell @t{<srp@@cgl.ucsf.edu>} 570@item next 571Mach for NeXT. Contributed by Bill Trost @t{<trost%reed@@cse.ogi.edu>} 572@item pyrOSx 573Pyramid OSx. Contributed by Stefan Petri @t{<petri@@tubsibr.UUCP>} 574@item riscix 575Acorn RISC iX. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} 576@item sos3 577SunOS 3.4 & 3.5. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 578@item sos4 579SunOS 4.@i{x}. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 580@item u2_2 581Ultrix 2.2. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} 582@item u3_0 583Ultrix 3. Contributed by Piete Brooks @t{<pb@@cam.cl.ac.uk>} 584@item u4_0 585Ultrix 4.0. Contributed by Chris Lindblad @t{<cjl@@ai.mit.edu>} 586@item umax43 587Umax 4.3 BSD. Contributed by Sjoerd Mullender @t{<sjoerd@@cwi.nl>} 588@item utek 589Utek 4.0. Contributed by Bill Trost @t{<trost%reed@@cse.ogi.edu>} 590@item xinu43 591mt Xinu MORE/bsd. Contributed by Jan-Simon Pendry @t{<jsp@@doc.ic.ac.uk>} 592@end table 593 594@node Supported Machine Architectures, , Supported Operating Systems, Supported Platforms 595@comment node-name, next, previous, up 596@section Supported Machine Architectures 597@cindex Supported machine architectures 598@cindex Machine architecture names 599@cindex Machine architectures supported by Amd 600 601@table @code 602@item alliant 603Alliant FX/4 604@item arm 605Acorn ARM 606@item aviion 607Data General AViiON 608@item encore 609Encore 610@item fps500 611FPS Model 500 612@item hp9000 613HP 9000/300 family 614@item hp9k8 615HP 9000/800 family 616@item ibm032 617IBM RT 618@item ibm6000 619IBM RISC System/6000 620@item iris4d 621SGI Iris 4D 622@item macII 623Apple Mac II 624@item mips 625MIPS RISC 626@item multimax 627Encore Multimax 628@item orion105 629HLH Orion 1/05 630@item sun3 631Sun-3 family 632@item sun4 633Sun-4 family 634@item tahoe 635Tahoe family 636@item vax 637DEC Vax 638@end table 639 640@node Mount Maps, Amd Command Line Options, Supported Platforms, Top 641@comment node-name, next, previous, up 642@chapter Mount Maps 643@cindex Mount maps 644@cindex Automounter configuration maps 645@cindex Mount information 646 647@i{Amd} has no built-in knowledge of machines or filesystems. 648External @dfn{mount-maps} are used to provide the required information. 649Specifically, @i{Amd} needs to know when and under what conditions it 650should mount filesystems. 651 652The map entry corresponding to the requested name contains a list of 653possible locations from which to resolve the request. Each location 654specifies filesystem type, information required by that filesystem (for 655example the block special device in the case of UFS), and some 656information describing where to mount the filesystem (@pxref{fs Option}). A 657location may also contain @dfn{selectors} (@pxref{Selectors}).@refill 658 659@menu 660* Map Types:: 661* Key Lookup:: 662* Location Format:: 663@end menu 664 665@node Map Types, Key Lookup, Mount Maps, Mount Maps 666@comment node-name, next, previous, up 667@section Map Types 668@cindex Mount map types 669@cindex Map types 670@cindex Configuration map types 671@cindex Types of mount map 672@cindex Types of configuration map 673@cindex Determining the map type 674 675A mount-map provides the run-time configuration information to @i{Amd}. 676Maps can be implemented in many ways. Some of the forms supported by 677@i{Amd} are regular files, ndbm databases, NIS maps the @dfn{Hesiod} 678name server and even the password file. 679 680A mount-map @dfn{name} is a sequence of characters. When an automount 681point is created a handle on the mount-map is obtained. For each map 682type configured @i{Amd} attempts to reference the a map of the 683appropriate type. If a map is found, @i{Amd} notes the type for future 684use and deletes the reference, for example closing any open file 685descriptors. The available maps are configure when @i{Amd} is built and 686can be displayed by running the command @samp{amd -v}. 687 688By default, @i{Amd} caches data in a mode dependent on the type of map. 689This is the same as specifying @samp{cache:=mapdefault} and selects a 690suitable default cache mode depending on the map type. The individual 691defaults are described below. The @var{cache} option can be specified 692on automount points to alter the caching behaviour (@pxref{Automount 693Filesystem}).@refill 694 695The following map types have been implemented, though some are not 696available on all machines. Run the command @samp{amd -v} to obtain a 697list of map types configured on your machine. 698 699@menu 700* File maps:: 701* ndbm maps:: 702* NIS maps:: 703* Hesiod maps:: 704* Password maps:: 705* Union maps:: 706@end menu 707 708@node File maps, ndbm maps, Map Types, Map Types 709@comment node-name, next, previous, up 710@subsection File maps 711@cindex File maps 712@cindex Flat file maps 713@cindex File map syntactic conventions 714 715When @i{Amd} searches a file for a map entry it does a simple scan of 716the file and supports both comments and continuation lines. 717 718Continuation lines are indicated by a backslash character (@samp{\}) as 719the last character of a line in the file. The backslash, newline character 720@emph{and any leading white space on the following line} are discarded. A maximum 721line length of 2047 characters is enforced after continuation lines are read 722but before comments are stripped. Each line must end with 723a newline character; that is newlines are terminators, not separators. 724The following examples illustrate this: 725 726@example 727key valA valB; \ 728 valC 729@end example 730 731specifies @emph{three} locations, and is identical to 732 733@example 734key valA valB; valC 735@end example 736 737However, 738 739@example 740key valA valB;\ 741 valC 742@end example 743 744specifies only @emph{two} locations, and is identical to 745 746@example 747key valA valB;valC 748@end example 749 750After a complete line has been read from the file, including 751continuations, @i{Amd} determines whether there is a comment on the 752line. A comment begins with a hash (``@samp{#}'') character and 753continues to the end of the line. There is no way to escape or change 754the comment lead-in character. 755 756Note that continuation lines and comment support @dfn{only} apply to 757file maps, or ndbm maps built with the @code{mk-amd-map} program. 758 759When caching is enabled, file maps have a default cache mode of 760@code{all} (@pxref{Automount Filesystem}). 761 762@node ndbm maps, NIS maps, File maps, Map Types 763@comment node-name, next, previous, up 764@subsection ndbm maps 765@cindex ndbm maps 766 767An ndbm map may be used as a fast access form of a file map. The program, 768@code{mk-amd-map}, converts a normal map file into an ndbm database. 769This program supports the same continuation and comment conventions that 770are provided for file maps. Note that ndbm format files may @emph{not} 771be sharable across machine architectures. The notion of speed generally 772only applies to large maps; a small map, less than a single disk block, 773is almost certainly better implemented as a file map. 774 775ndbm maps do not support cache mode @samp{all} and, when caching is 776enabled, have a default cache mode of @samp{inc} (@pxref{Automount Filesystem}). 777 778@node NIS maps, Hesiod maps, ndbm maps, Map Types 779@comment node-name, next, previous, up 780@subsection NIS maps 781@cindex NIS (YP) maps 782 783When using NIS (formerly YP), an @i{Amd} map is implemented directly 784by the underlying NIS map. Comments and continuation lines are 785@emph{not} supported in the automounter and must be stripped when 786constructing the NIS server's database. 787 788NIS maps do not support cache mode @code{all} and, when caching is 789enabled, have a default cache mode of @code{inc} (@pxref{Automount Filesystem}). 790 791The following rule illustrates what could be added to your NIS @file{Makefile}, 792in this case causing the @file{amd.home} map to be rebuilt: 793@example 794$(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home 795 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \ 796 awk '@{ \ 797 for (i = 1; i <= NF; i++) \ 798 if (i == NF) @{ \ 799 if (substr($$i, length($$i), 1) == "\\") \ 800 printf("%s", substr($$i, 1, length($$i) - 1)); \ 801 else \ 802 printf("%s\n", $$i); \ 803 @} \ 804 else \ 805 printf("%s ", $$i); \ 806 @}' | \ 807 $(MAKEDBM) - $(YPDBDIR)/amd.home; \ 808 touch $(YPTSDIR)/amd.home.time; \ 809 echo "updated amd.home"; \ 810 if [ ! $(NOPUSH) ]; then \ 811 $(YPPUSH) amd.home; \ 812 echo "pushed amd.home"; \ 813 else \ 814 : ; \ 815 fi 816@end example 817 818Here @code{$(YPTSDIR)} contains the time stamp files, and @code{$(YPDBDIR)} contains 819the dbm format NIS files. 820 821@node Hesiod maps, Password maps, NIS maps, Map Types 822@comment node-name, next, previous, up 823@subsection Hesiod maps 824@cindex Hesiod maps 825 826When the map name begins with the string @samp{hesiod.} lookups are made 827using the @dfn{Hesiod} name server. The string following the dot is 828used as a name qualifier and is prepended with the key being located. 829The entire string is then resolved in the @code{automount} context. For 830example, if the the key is @samp{jsp} and map name is 831@samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve 832@samp{jsp.homes.automount}. 833 834Hesiod maps do not support cache mode @samp{all} and, when caching is 835enabled, have a default cache mode of @samp{inc} (@pxref{Automount Filesystem}). 836 837The following is an example of a @dfn{Hesiod} map entry: 838 839@example 840jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp" 841njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw" 842@end example 843 844@node Password maps, Union maps, Hesiod maps, Map Types 845@comment node-name, next, previous, up 846@subsection Password maps 847@cindex Password file maps 848@cindex /etc/passwd maps 849@cindex User maps, automatic generation 850@cindex Automatic generation of user maps 851@cindex Using the password file as a map 852 853The password map support is unlike the four previous map types. When 854the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user 855name in the password file and re-arrange the home directory field to 856produce a usable map entry. 857 858@i{Amd} assumes the home directory has the format 859`@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'. 860@c @footnote{This interpretation is not necessarily exactly what you want.} 861It breaks this string into a map entry where @code{$@{rfs@}} has the 862value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value 863`@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the 864value @samp{login}.@refill 865 866Thus if the password file entry was 867 868@example 869/home/achilles/jsp 870@end example 871 872the map entry used by @i{Amd} would be 873 874@example 875rfs:=/home/achilles;rhost:=achilles;sublink:=jsp 876@end example 877 878Similarly, if the password file entry was 879 880@example 881/home/cc/sugar/mjh 882@end example 883 884the map entry used by @i{Amd} would be 885 886@example 887rfs:=/home/sugar;rhost:=sugar.cc;sublink:=jsp 888@end example 889 890@node Union maps, , Password maps, Map Types 891@comment node-name, next, previous, up 892@subsection Union maps 893@cindex Union file maps 894 895The union map support is provided specifically for use with the union 896filesystem, @pxref{Union Filesystem}. 897 898It is identified by the string @samp{union:} which is followed by a 899colon separated list of directories. The directories are read in order, 900and the names of all entries are recorded in the map cache. Later 901directories take precedence over earlier ones. The union filesystem 902type then uses the map cache to determine the union of the names in all 903the directories. 904 905@c subsection Gdbm 906 907@node Key Lookup, Location Format, Map Types, Mount Maps 908@comment node-name, next, previous, up 909@section How keys are looked up 910@cindex Key lookup 911@cindex Map lookup 912@cindex Looking up keys 913@cindex How keys are looked up 914@cindex Wildcards in maps 915 916The key is located in the map whose type was determined when the 917automount point was first created. In general the key is a pathname 918component. In some circumstances this may be modified by variable 919expansion (@pxref{Variable Expansion}) and prefixing. If the automount 920point has a prefix, specified by the @var{pref} option, then that is 921prepended to the search key before the map is searched. 922 923If the map cache is a @samp{regexp} cache then the key is treated as an 924egrep-style regular expression, otherwise a normal string comparison is 925made. 926 927If the key cannot be found then a @dfn{wildcard} match is attempted. 928@i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and 929attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}. 930 931@group 932For example, the following sequence would be checked if @file{home/dylan/dk2} was 933being located: 934 935@example 936 home/dylan/dk2 937 home/dylan/* 938 home/* 939 * 940@end example 941@end group 942 943At any point when a wildcard is found, @i{Amd} proceeds as if an exact 944match had been found and the value field is then used to resolve the 945mount request, otherwise an error code is propagated back to the kernel. 946(@pxref{Filesystem Types}).@refill 947 948@node Location Format, , Key Lookup, Mount Maps 949@comment node-name, next, previous, up 950@section Location Format 951@cindex Location format 952@cindex Map entry format 953@cindex How locations are parsed 954 955The value field from the lookup provides the information required to 956mount a filesystem. The information is parsed according to the syntax 957shown below. 958 959@display 960@i{location-list}: 961 @i{location-selection} 962 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection} 963@i{location-selection}: 964 @i{location} 965 @i{location-selection} @i{white-space} @i{location} 966@i{location}: 967 @i{location-info} 968 @t{-}@i{location-info} 969 @t{-} 970@i{location-info}: 971 @i{sel-or-opt} 972 @i{location-info}@t{;}@i{sel-or-opt} 973 @t{;} 974@i{sel-or-opt}: 975 @i{selection} 976 @i{opt-ass} 977@i{selection}: 978 selector@t{==}@i{value} 979 selector@t{!=}@i{value} 980@i{opt-ass}: 981 option@t{:=}@i{value} 982@i{white-space}: 983 space 984 tab 985@end display 986 987Note that unquoted whitespace is not allowed in a location description. 988White space is only allowed, and is mandatory, where shown with non-terminal 989@samp{white-space}. 990 991A @dfn{location-selection} is a list of possible volumes with which to 992satisfy the request. @dfn{location-selection}s are separated by the 993@samp{||} operator. The effect of this operator is to prevent use of 994location-selections to its right if any of the location-selections on 995its left were selected whether or not any of them were successfully 996mounted (@pxref{Selectors}).@refill 997 998The location-selection, and singleton @dfn{location-list}, 999@samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS 1000filesystem from the block special device @file{/dev/xd1g}. 1001 1002The @dfn{sel-or-opt} component is either the name of an option required 1003by a specific filesystem, or it is the name of a built-in, predefined 1004selector such as the architecture type. The value may be quoted with 1005double quotes @samp{"}, for example 1006@samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the 1007value is parsed and there is no way to get a double quote into a value 1008field. Double quotes are used to get white space into a value field, 1009which is needed for the program filesystem (@pxref{Program Filesystem}).@refill 1010 1011@menu 1012* Map Defaults:: 1013* Variable Expansion:: 1014* Selectors:: 1015* Map Options:: 1016@end menu 1017 1018@node Map Defaults, Variable Expansion, Location Format, Location Format 1019@comment node-name, next, previous, up 1020@subsection Map Defaults 1021@cindex Map defaults 1022@cindex How to set default map parameters 1023@cindex Setting default map parameters 1024 1025A location beginning with a dash @samp{-} is used to specify default 1026values for subsequent locations. Any previously specified defaults in 1027the location-list are discarded. The default string can be empty in 1028which case no defaults apply. 1029 1030The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point 1031to @file{/mnt} and cause mounts to be read-only by default. Defaults 1032specified this way are appended to, and so override, any global map 1033defaults given with @samp{/defaults}). 1034@c 1035@c A @samp{/defaults} value @dfn{gdef} and a location list 1036@c \begin{quote} 1037@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$ 1038@c \end{quote} 1039@c is equivalent to 1040@c \begin{quote} 1041@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$ 1042@c \end{quote} 1043@c which is equivalent to 1044@c \begin{quote} 1045@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$ 1046@c \end{quote} 1047 1048@node Variable Expansion, Selectors, Map Defaults, Location Format 1049@comment node-name, next, previous, up 1050@subsection Variable Expansion 1051@cindex Variable expansion 1052@cindex How variables are expanded 1053@cindex Pathname operators 1054@cindex Domain stripping 1055@cindex Domainname operators 1056@cindex Stripping the local domain name 1057@cindex Environment variables 1058@cindex How to access environment variables in maps 1059 1060To allow generic location specifications @i{Amd} does variable expansion 1061on each location and also on some of the option strings. Any option or 1062selector appearing in the form @code{$@dfn{var}} is replaced by the 1063current value of that option or selector. For example, if the value of 1064@code{$@{key@}} was @samp{bin}, @code{$@{autodir@}} was @samp{/a} and 1065@code{$@{fs@}} was `@t{$@{autodir@}}@t{/local/}@t{$@{key@}}' then 1066after expansion @code{$@{fs@}} would have the value @samp{/a/local/bin}. 1067Any environment variable can be accessed in a similar way.@refill 1068 1069Two pathname operators are available when expanding a variable. If the 1070variable name begins with @samp{/} then only the last component of 1071then pathname is substituted. For example, if @code{$@{path@}} was 1072@samp{/foo/bar} then @code{$@{/path@}} would be expanded to @samp{bar}. 1073Similarly, if the variable name ends with @samp{/} then all but the 1074last component of the pathname is substituted. In the previous example, 1075@code{$@{path/@}} would be expanded to @samp{/foo}.@refill 1076 1077Two domain name operators are also provided. If the variable name 1078begins with @samp{.} then only the domain part of the name is 1079substituted. For example, if @code{$@{rhost@}} was 1080@samp{swan.doc.ic.ac.uk} then @code{$@{.rhost@}} would be expanded to 1081@samp{doc.ic.ac.uk}. Similarly, if the variable name ends with @samp{.} 1082then only the host component is substituted. In the previous example, 1083@code{$@{rhost.@}} would be expanded to @samp{swan}.@refill 1084 1085Variable expansion is a two phase process. Before a location is parsed, 1086all references to selectors, @i{eg} @code{$@{path@}}, are expanded. The 1087location is then parsed, selections are evaluated and option assignments 1088recorded. If there were no selections or they all succeeded the 1089location is used and the values of the following options are expanded in 1090the order given: @var{sublink}, @var{rfs}, @var{fs}, @var{opts}, 1091@var{remopts}, @var{mount} and @var{unmount}. 1092 1093Note that expansion of option values is done after @dfn{all} assignments 1094have been completed and not in a purely left to right order as is done 1095by the shell. This generally has the desired effect but care must be 1096taken if one of the options references another, in which case the 1097ordering can become significant. 1098 1099There are two special cases concerning variable expansion: 1100 1101@enumerate 1102@item 1103before a map is consulted, any selectors in the name received 1104from the kernel are expanded. For example, if the request from the 1105kernel was for `@t{$@{arch@}}@t{.bin}' and the machine architecture 1106was @samp{vax}, the value given to @code{$@{key@}} would be 1107@samp{vax.bin}.@refill 1108 1109@item 1110the value of @code{$@{rhost@}} is expanded and normalized before the 1111other options are expanded. The normalization process strips any local 1112sub-domain components. For example, if @code{$@{domain@}} was 1113@samp{Berkeley.EDU} and @code{$@{rhost@}} was initially 1114@samp{snow.Berkeley.EDU}, after the normalization it would simply be 1115@samp{snow}. Hostname normalization is currently done in a 1116@emph{case-dependent} manner.@refill 1117@end enumerate 1118 1119@node Selectors, Map Options, Variable Expansion, Location Format 1120@comment node-name, next, previous, up 1121@subsection Selectors 1122@cindex Selectors 1123 1124Selectors are used to control the use of a location. It is possible to 1125share a mount map between many machines in such a way that filesystem 1126location, architecture and operating system differences are hidden from 1127the users. A selector of the form @samp{arch==sun3;os==sos4} would only 1128apply on Sun-3s running SunOS 4.x. 1129 1130Selectors are evaluated left to right. If a selector fails then that 1131location is ignored. Thus the selectors form a conjunction and the 1132locations form a disjunction. If all the locations are ignored or 1133otherwise fail then @i{Amd} uses the @dfn{error} filesystem 1134(@pxref{Error Filesystem}). This is equivalent to having a location 1135@samp{type:=error} at the end of each mount-map entry.@refill 1136 1137The selectors currently implemented are: 1138 1139@table @samp 1140@cindex arch, mount selector 1141@cindex Mount selector; arch 1142@cindex Selector; arch 1143@item arch 1144the machine architecture which was automatically determined at compile 1145time. The architecture type can be displayed by running the command 1146@samp{amd -v}. @xref{Supported Machine Architectures}.@refill 1147 1148@item autodir 1149@cindex autodir, mount selector 1150@cindex Mount selector; autodir 1151@cindex Selector; autodir 1152the default directory under which to mount filesystems. This may be 1153changed by the ``-a'' command line option. See the @var{fs} option. 1154 1155@item byte 1156@cindex byte, mount selector 1157@cindex Mount selector; byte 1158@cindex Selector; byte 1159the machine's byte ordering. This is either @samp{little}, indicating 1160little-endian, or @samp{big}, indicating big-endian. One possible use 1161is to share @samp{rwho} databases (@pxref{rwho servers}). Another is to 1162share ndbm databases, however this use can be considered a courageous 1163juggling act. 1164 1165@item cluster 1166@cindex cluster, mount selector 1167@cindex Mount selector; cluster 1168@cindex Selector; cluster 1169is provided as a hook for the name of the local cluster. This can be 1170used to decide which servers to use for copies of replicated 1171filesystems. @code{$@{cluster@}} defaults to the value of 1172@code{$@{domain@}} unless a different value is set with the ``-C'' 1173command line option. 1174 1175@item domain 1176@cindex domain, mount selector 1177@cindex Mount selector; domain 1178@cindex Selector; domain 1179the local domain name as specified by the ``-d'' command line option. 1180See @samp{host}. 1181 1182@item host 1183@cindex host, mount selector 1184@cindex Mount selector; host 1185@cindex Selector; host 1186the local hostname as determined by @b{gethostname}(2). If no domain 1187name was specified on the command line and the hostname contains a 1188period @samp{.} then the string before the period is used as the 1189host name, and the string after the period is assigned to 1190@code{$@{domain@}}. For example, if the hostname is 1191@samp{styx.doc.ic.ac.uk} then @code{host} would be @samp{styx} and 1192@code{domain} would be @samp{doc.ic.ac.uk}. @code{hostd} would be 1193@samp{styx.doc.ic.ac.uk}.@refill 1194 1195@item hostd 1196@cindex hostd, mount selector 1197@cindex Mount selector; hostd 1198@cindex Selector; hostd 1199is @code{$@{host@}} and @code{$@{domain@}} concatenated with a 1200@samp{.} inserted between them if required. If @code{$@{domain@}} 1201is an empty string then @code{$@{host@}} and @code{$@{hostd@}} will be 1202identical. 1203 1204@item karch 1205@cindex karch, mount selector 1206@cindex Mount selector; karch 1207@cindex Selector; karch 1208is provided as a hook for the kernel architecture. This is used on 1209SunOS 4, for example, to distinguish between different @samp{/usr/kvm} 1210volumes. @code{$@{karch@}} defaults to the value of @code{$@{arch@}} 1211unless a different value is set with the ``-k'' command line option. 1212 1213@item os 1214@cindex os, mount selector 1215@cindex Mount selector; os 1216@cindex Selector; os 1217the operating system. Like the machine architecture, this is 1218automatically determined at compile time. The operating system name can 1219be displayed by running the command @samp{amd -v}. @xref{Supported 1220Operating Systems}.@refill 1221 1222@end table 1223 1224The following selectors are also provided. Unlike the other selectors, 1225they vary for each lookup. Note that when the name from the kernel is 1226expanded prior to a map lookup, these selectors are all defined as empty 1227strings. 1228 1229@table @samp 1230@item key 1231@cindex key, mount selector 1232@cindex Mount selector; key 1233@cindex Selector; key 1234the name being resolved. For example, if @file{/home} is an automount 1235point, then accessing @file{/home/foo} would set @code{$@{key@}} to the 1236string @samp{foo}. The key is prefixed by the @var{pref} option set in 1237the parent mount point. The default prefix is an empty string. If the 1238prefix was @file{blah/} then @code{$@{key@}} would be set to 1239@file{blah/foo}.@refill 1240 1241@item map 1242@cindex map, mount selector 1243@cindex Mount selector; map 1244@cindex Selector; map 1245the name of the mount map being used. 1246 1247@item path 1248@cindex path, mount selector 1249@cindex Mount selector; path 1250@cindex Selector; path 1251the full pathname of the name being resolved. For example 1252@file{/home/foo} in the example above. 1253 1254@item wire 1255@cindex wire, mount selector 1256@cindex Mount selector; wire 1257@cindex Selector; wire 1258the name of the network to which the primary network interface is 1259attached. If a symbolic name cannot be found in the networks or hosts 1260database then dotted IP address format is used. This value is also 1261output by the ``-v'' option. 1262 1263@end table 1264 1265Selectors can be negated by using @samp{!=} instead of @samp{==}. For 1266example to select a location on all non-Vax machines the selector 1267@samp{arch!=vax} would be used. 1268 1269@node Map Options, , Selectors, Location Format 1270@comment node-name, next, previous, up 1271@subsection Map Options 1272@cindex Map options 1273@cindex Setting map options 1274 1275Options are parsed concurrently with selectors. The difference is that 1276when an option is seen the string following the @samp{:=} is 1277recorded for later use. As a minimum the @var{type} option must be 1278specified. Each filesystem type has other options which must also be 1279specified. @xref{Filesystem Types}, for details on the filesystem 1280specific options.@refill 1281 1282Superfluous option specifications are ignored and are not reported 1283as errors. 1284 1285The following options apply to more than one filesystem type. 1286 1287@menu 1288* delay Option:: 1289* fs Option:: 1290* opts Option:: 1291* remopts Option:: 1292* sublink Option:: 1293* type Option:: 1294@end menu 1295 1296@node delay Option, fs Option, Map Options, Map Options 1297@comment node-name, next, previous, up 1298@subsubsection delay Option 1299@cindex Setting a delay on a mount location 1300@cindex Delaying mounts from specific locations 1301@cindex Primary server 1302@cindex Secondary server 1303@cindex delay, mount option 1304@cindex Mount option; delay 1305 1306The delay, in seconds, before an attempt will be made to mount from the current location. 1307Auxilliary data, such as network address, file handles and so on are computed 1308regardless of this value. 1309 1310A delay can be used to implement the notion of primary and secondary file servers. 1311The secondary servers would have a delay of a few seconds, 1312thus giving the primary servers a chance to respond first. 1313 1314@node fs Option, opts Option, delay Option, Map Options 1315@comment node-name, next, previous, up 1316@subsubsection fs Option 1317@cindex Setting the local mount point 1318@cindex Overriding the default mount point 1319@cindex fs, mount option 1320@cindex Mount option; fs 1321 1322The local mount point. The semantics of this option vary between 1323filesystems. 1324 1325For NFS and UFS filesystems the value of @code{$@{fs@}} is used as the 1326local mount point. For other filesystem types it has other meanings 1327which are described in the section describing the respective filesystem 1328type. It is important that this string uniquely identifies the 1329filesystem being mounted. To satisfy this requirement, it should 1330contain the name of the host on which the filesystem is resident and the 1331pathname of the filesystem on the local or remote host. 1332 1333The reason for requiring the hostname is clear if replicated filesystems 1334are considered. If a fileserver goes down and a replacement filesystem 1335is mounted then the @dfn{local} mount point @dfn{must} be different from 1336that of the filesystem which is hung. Some encoding of the filesystem 1337name is required if more than one filesystem is to be mounted from any 1338given host. 1339 1340If the hostname is first in the path then all mounts from a particular 1341host will be gathered below a single directory. If that server goes 1342down then the hung mount points are less likely to be accidentally 1343referenced, for example when @b{getwd}(3) traverses the namespace to 1344find the pathname of the current directory. 1345 1346The @samp{fs} option defaults to 1347@code{$@{autodir@}/$@{rhost@}$@{rfs@}}. In addition, 1348@samp{rhost} defaults to the local host name (@code{$@{host@}}) and 1349@samp{rfs} defaults to the value of @code{$@{path@}}, which is the full 1350path of the requested file; @samp{/home/foo} in the example above 1351(@pxref{Selectors}). @code{$@{autodir@}} defaults to @samp{/a} but may 1352be changed with the ``-a'' command line option. Sun's automounter 1353defaults to @samp{/tmp_mnt}. Note that there is no @samp{/} between 1354the @code{$@{rhost@}} and @code{$@{rfs@}} since @code{$@{rfs@}} begins 1355with a @samp{/}.@refill 1356 1357@node opts Option, remopts Option, fs Option, Map Options 1358@comment node-name, next, previous, up 1359@subsubsection opts Option 1360@cindex Setting system mount options 1361@cindex Passing parameters to the mount system call 1362@cindex mount system call 1363@cindex mount system call flags 1364@cindex The mount system call 1365@cindex opts, mount option 1366@cindex Mount option; opts 1367 1368The options to pass to the mount system call. A leading @samp{-} is 1369silently ignored. The mount options supported generally correspond to 1370those used by @b{mount}(8) and are listed below. Some additional 1371pseudo-options are interpreted by @i{Amd} and are also listed. 1372 1373Unless specifically overridden, each of the system default mount options 1374applies. Any options not recognised are ignored. If no options list is 1375supplied the string @samp{rw,defaults} is used and all the system 1376default mount options apply. Options which are not applicable for a 1377particular operating system are silently ignored. For example, only 4.4 1378BSD is known to implement the @code{compress} and @code{spongy} options. 1379 1380@table @code 1381@item compress 1382Use NFS compression protocol. 1383@item grpid 1384Use BSD directory group-id semantics. 1385@item intr 1386Allow keyboard interrupts on hard mounts. 1387@item noconn 1388Don't make a connection on datagram transports. 1389@item nocto 1390No close-to-open consistency. 1391@item nodevs 1392Don't allow local special devices on this filesystem. 1393@item nosuid 1394Don't allow set-uid or set-gid executables on this filesystem. 1395@item quota 1396Enable quota checking on this mount. 1397@item retrans=@i{n} 1398The number of NFS retransmits made before a user error is generated by a 1399@samp{soft} mounted filesystem, and before a @samp{hard} mounted 1400filesystem reports @samp{NFS server @dfn{yoyo} not responding still 1401trying}. 1402@item ro 1403Mount this filesystem readonly. 1404@item rsize=@var{n} 1405The NFS read packet size. You may need to set this if you are using 1406NFS/UDP through a gateway. 1407@item soft 1408Give up after @dfn{retrans} retransmissions. 1409@item spongy 1410Like @samp{soft} for status requests, and @samp{hard} for data transfers. 1411@item tcp 1412Use TCP/IP instead of UDP/IP, ignored if the NFS implementation does not 1413support TCP/IP mounts. 1414@item timeo=@var{n} 1415The NFS timeout, in tenth-seconds, before a request is retransmitted. 1416@item wsize=@var{n} 1417The NFS write packet size. You may need to set this if you are using 1418NFS/UDP through a gateway. 1419@end table 1420 1421The following options are implemented by @i{Amd}, rather than being 1422passed to the kernel. 1423 1424@table @code 1425@item nounmount 1426Configures the mount so that its time-to-live will 1427never expire. This is also the default for some filesystem types. 1428@c 1429@c Implementation broken: 1430@item ping=@var{n} 1431The interval, in seconds, between keep-alive pings. When four 1432consecutive pings have failed the mount point is marked as hung. This 1433interval defaults to 30 seconds. If the ping interval is less than zero, 1434no pings are sent and the host is assumed to be always 1435up. By default, pings are not sent for an NFS/TCP mount. 1436@item retry=@var{n} 1437The number of times to retry the mount system call. 1438@item utimeout=@var{n} 1439The interval, in seconds, by which the mount's 1440time-to-live is extended after an unmount attempt 1441has failed. In fact the interval is extended before the unmount is 1442attempted to avoid thrashing. The default value is 120 seconds (two 1443minutes) or as set by the ``-w'' command line option. 1444@end table 1445 1446@node remopts Option, sublink Option, opts Option, Map Options 1447@comment node-name, next, previous, up 1448@subsubsection remopts Option 1449@cindex Setting system mount options for non-local networks 1450@cindex remopts, mount option 1451@cindex Mount option; remopts 1452 1453This option has the same use as @code{$@{opts@}} but applies only when 1454the remote host is on a non-local network. For example, when using NFS 1455across a gateway it is often necessary to use smaller values for the 1456data read and write sizes. This can simply be done by specifying the 1457small values in @var{remopts}. When a non-local host is accessed, the 1458smaller sizes will automatically be used. 1459 1460@i{Amd} determines whether a host is local by examining the network 1461interface configuration at startup. Any interface changes made after 1462@i{Amd} has been started will not be noticed. The likely effect will 1463be that a host may incorrectly be declared non-local. 1464 1465Unless otherwise set, the value of @code{$@{rem@}} is the same as the 1466value of @code{$@{opts@}}. 1467 1468@node sublink Option, type Option, remopts Option, Map Options 1469@comment node-name, next, previous, up 1470@subsubsection sublink Option 1471@cindex Setting the sublink option 1472@cindex sublink, mount option 1473@cindex Mount option; sublink 1474 1475The subdirectory within the mounted filesystem to which the reference 1476should point. This can be used to prevent duplicate mounts in cases 1477where multiple directories in the same mounted filesystem are used. 1478 1479@node type Option, , sublink Option, Map Options 1480@comment node-name, next, previous, up 1481@subsubsection type Option 1482@cindex Setting the filesystem type option 1483@cindex type, mount option 1484@cindex Mount option; type 1485 1486The filesystem type to be used. @xref{Filesystem Types}, for a full 1487description of each type.@refill 1488 1489@node Amd Command Line Options, Filesystem Types, Mount Maps, Top 1490@comment node-name, next, previous, up 1491@chapter @i{Amd} Command Line Options 1492@cindex Command line options, Amd 1493@cindex Amd command line options 1494@cindex Overriding defaults on the command line 1495 1496Many of @i{Amd}'s parameters can be set from the command line. The 1497command line is also used to specify automount points and maps. 1498 1499The general format of a command line is 1500 1501@example 1502amd [@i{options}] @{ @i{directory} @i{map-name} [-@i{map-options}] @} ... 1503@end example 1504 1505For each directory and map-name given, @i{Amd} establishes an 1506automount point. The @dfn{map-options} may be any sequence of options 1507or selectors---@pxref{Location Format}. The @dfn{map-options} 1508apply only to @i{Amd}'s mount point. 1509 1510@samp{type:=toplvl;cache:=mapdefault;fs:=$@{map@}} is the default value for the 1511map options. Default options for a map are read from a special entry in 1512the map whose key is the string @samp{/defaults}. When default options 1513are given they are prepended to any options specified in the mount-map 1514locations as explained in. @xref{Map Defaults}, for more details. 1515 1516The @dfn{options} are any combination of those listed below. 1517 1518Once the command line has been parsed, the automount points are mounted. 1519The mount points are created if they do not already exist, in which case they 1520will be removed when @i{Amd} exits. 1521Finally, @i{Amd} disassociates itself from its controlling terminal and 1522forks into the background. 1523 1524Note: Even if @i{Amd} has been built with @samp{-DDEBUG} it will still 1525background itself and disassociate itself from the controlling terminal. 1526To use a debugger it is necessary to specify @samp{-D nodaemon} on the 1527command line. 1528 1529@menu 1530* -a Option:: Automount directory. 1531* -c Option:: Cache timeout interval. 1532* -d Option:: Domain name. 1533* -k Option:: Kernel architecture. 1534* -l Option:: Log file. 1535* -n Option:: Hostname normalisation. 1536* -p Option:: Output process id. 1537* -r Option:: Restart existing mounts. 1538* -t Option:: Kernel RPC timeout. 1539* -v Option:: Version information. 1540* -w Option:: Wait interval after failed unmount. 1541* -x Option:: Log options. 1542* -y Option:: NIS domain. 1543* -C-Option:: Cluster name. 1544* -D-Option:: Debug flags. 1545@end menu 1546 1547@node -a Option, -c Option, Amd Command Line Options, Amd Command Line Options 1548@comment node-name, next, previous, up 1549@section @code{-a} @var{directory} 1550@cindex Automount directory 1551@cindex Setting the default mount directory 1552 1553Specifies the default mount directory. This option changes the variable 1554@code{$@{autodir@}} which otherwise defaults to @file{/a}. For example, 1555some sites prefer @file{/amd}. 1556 1557@example 1558amd -a /amd ... 1559@end example 1560 1561@node -c Option, -d Option, -a Option, Amd Command Line Options 1562@comment node-name, next, previous, up 1563@section @code{-c} @var{cache-interval} 1564@cindex Cache interval 1565@cindex Interval before a filesystem times out 1566@cindex Setting the interval before a filesystem times out 1567@cindex Changing the interval before a filesystem times out 1568 1569Selects the period, in seconds, for which a name is cached by @i{Amd}. 1570If no reference is made to the volume in this period, @i{Amd} discards 1571the volume name to filesystem mapping. 1572 1573Once the last reference to a filesystem has been removed, @i{Amd} 1574attempts to unmount the filesystem. If the unmount fails the interval 1575is extended by a further period as specified by the @samp{-w} command 1576line option or by the @samp{utimeout} mount option. 1577 1578The default @dfn{cache-interval} is 300 seconds (five minutes). 1579 1580@node -d Option, -k Option, -c Option, Amd Command Line Options 1581@comment node-name, next, previous, up 1582@section @code{-d} @var{domain} 1583@cindex Domain name 1584@cindex Setting the local domain name 1585@cindex Overriding the local domain name 1586 1587Specifies the host's domain. This sets the internal variable 1588@code{$@{domain@}} and affects the @code{$@{hostd@}} variable. 1589 1590If this option is not specified and the hostname already contains the 1591local domain then that is used, otherwise the default value of 1592@code{$@{domain@}} is @samp{unknown.domain}. 1593 1594For example, if the local domain was @samp{doc.ic.ac.uk}, @i{Amd} could 1595be started as follows: 1596 1597@example 1598amd -d doc.ic.ac.uk ... 1599@end example 1600 1601@node -k Option, -l Option, -d Option, Amd Command Line Options 1602@comment node-name, next, previous, up 1603@section @code{-k} @var{kernel-architecture} 1604@cindex Setting the Kernel architecture 1605 1606Specifies the kernel architecture of the system. This is usually the 1607output of @samp{arch -k} and its only effect is to set the variable 1608@code{$@{karch@}}. If this option is not given, @code{$@{karch@}} has 1609the same value as @code{$@{arch@}}. 1610 1611This would be used as follows: 1612 1613@example 1614amd -k `arch -k` ... 1615@end example 1616 1617@node -l Option, -n Option, -k Option, Amd Command Line Options 1618@comment node-name, next, previous, up 1619@section @code{-l} @var{log-option} 1620@cindex Log filename 1621@cindex Setting the log file 1622@cindex Using syslog to log errors 1623@cindex syslog 1624 1625Selects the form of logging to be made. Two special @dfn{log-options} 1626are recognised. 1627 1628@enumerate 1629@item 1630If @dfn{log-option} is the string @samp{syslog}, @i{Amd} will use the 1631@b{syslog}(3) mechanism.@refill 1632 1633@item 1634If @dfn{log-option} is the string @samp{/dev/stderr}, @i{Amd} will use 1635standard error, which is also the default target for log messages. To 1636implement this, @i{Amd} simulates the effect of the @samp{/dev/fd} 1637driver. 1638@end enumerate 1639 1640Any other string is taken as a filename to use for logging. Log 1641messages are appended to the file if it already exists, otherwise a new 1642file is created. The file is opened once and then held open, rather 1643than being re-opened for each message. 1644 1645If the @samp{syslog} option is specified but the system does not support 1646syslog or if the named file cannot be opened or created, @i{Amd} will 1647use standard error. Error messages generated before @i{Amd} has 1648finished parsing the command line are printed on standard error. 1649 1650Using @samp{syslog} is usually best, in which case @i{Amd} would be 1651started as follows: 1652 1653@example 1654amd -l syslog ... 1655@end example 1656 1657@node -n Option, -p Option, -l Option, Amd Command Line Options 1658@comment node-name, next, previous, up 1659@section @code{-n} 1660@cindex Hostname normalisation 1661@cindex Aliased hostnames 1662@cindex Resolving aliased hostnames 1663@cindex Normalising hostnames 1664 1665Normalises the remote hostname before using it. Normalisation is done 1666by replacing the value of @code{$@{rhost@}} with the primary name 1667returned by a hostname lookup. 1668 1669This option should be used if several names are used to refer to a 1670single host in a mount map. 1671 1672@node -p Option, -r Option, -n Option, Amd Command Line Options 1673@comment node-name, next, previous, up 1674@section @code{-p} 1675@cindex Process id 1676@cindex Displaying the process id 1677@cindex process id of Amd daemon 1678@cindex pid file, creating with -p option 1679@cindex Creating a pid file 1680 1681Causes @i{Amd}'s process id to be printed on standard output. 1682This can be redirected to a suitable file for use with kill: 1683 1684@example 1685amd -p > /var/run/amd.pid ... 1686@end example 1687 1688This option only has an affect if @i{Amd} is running in daemon mode. 1689If @i{Amd} is started with the @code{-D nodaemon} debug flag, this 1690option is ignored. 1691 1692@node -r Option, -t Option, -p Option, Amd Command Line Options 1693@comment node-name, next, previous, up 1694@section @code{-r} 1695@cindex Restarting existing mounts 1696@cindex Picking up existing mounts 1697 1698Tells @i{Amd} to restart existing mounts (@pxref{Inheritance Filesystem}). 1699@c @dfn{This option will be made the default in the next release.} 1700 1701@node -t Option, -v Option, -r Option, Amd Command Line Options 1702@comment node-name, next, previous, up 1703@section @code{-t} @var{timeout.retransmit} 1704@cindex Setting Amd's RPC parameters 1705 1706Specifies the RPC @dfn{timeout} and @dfn{retransmit} intervals used by 1707the kernel to communicate to @i{Amd}. These are used to set the 1708@samp{timeo} and @samp{retrans} mount options. 1709 1710@i{Amd} relies on the kernel RPC retransmit mechanism to trigger mount 1711retries. The value of this parameter changes the retry interval. Too 1712long an interval gives poor interactive response, too short an interval 1713causes excessive retries. 1714 1715@node -v Option, -w Option, -t Option, Amd Command Line Options 1716@comment node-name, next, previous, up 1717@section @code{-v} 1718@cindex Version information 1719@cindex Discovering version information 1720@cindex How to discover your version of Amd 1721 1722Print version information on standard error and then exit. The output 1723is of the form: 1724 1725@example 1726amd 5.2.1.11 of 91/03/17 18:04:05 5.3Alpha11 #0: Sun Mar 17 18:07:28 GMT 1991 1727Built by pendry@@vangogh.Berkeley.EDU for a hp300 running bsd44 (big-endian). 1728Map support for: root, passwd, union, file, error. 1729FS: ufs, nfs, nfsx, host, link, program, union, auto, direct, toplvl, error. 1730Primary network is 128.32.130.0. 1731@end example 1732 1733The information includes the version number, release date and name of 1734the release. The architecture (@pxref{Supported Machine Architectures}), 1735operating system (@pxref{Supported Operating Systems}) 1736and byte ordering are also printed as they appear in the @code{$@{os@}}, 1737@code{$@{arch@}} and @code{$@{byte@}} variables.@refill 1738 1739@node -w Option, -x Option, -v Option, Amd Command Line Options 1740@comment node-name, next, previous, up 1741@section @code{-w} @var{wait-timeout} 1742@cindex Setting the interval between unmount attempts 1743@cindex unmount attempt backoff interval 1744 1745Selects the interval in seconds between unmount attempts after the 1746initial time-to-live has expired. 1747 1748This defaults to 120 seconds (two minutes). 1749 1750@node -x Option, -y Option, -w Option, Amd Command Line Options 1751@comment node-name, next, previous, up 1752@section @code{-x} @var{opts} 1753@cindex Log message selection 1754@cindex Selecting specific log messages 1755@cindex How to select log messages 1756@cindex syslog priorities 1757 1758Specifies the type and verbosity of log messages. @dfn{opts} is 1759a comma separated list selected from the following options: 1760 1761@table @code 1762@item fatal 1763Fatal errors 1764@item error 1765Non-fatal errors 1766@item user 1767Non-fatal user errors 1768@item warn 1769Recoverable errors 1770@item warning 1771Alias for @code{warn} 1772@item info 1773Information messages 1774@item map 1775Mount map usage 1776@item stats 1777Additional statistics 1778@item all 1779All of the above 1780@end table 1781 1782Initially a set of default logging flags is enabled. This is as if 1783@samp{-x all,nomap,nostats} had been selected. The command line is 1784parsed and logging is controlled by the ``-x'' option. The very first 1785set of logging flags is saved and can not be subsequently disabled using 1786@i{Amq}. This default set of options is useful for general production 1787use.@refill 1788 1789The @samp{info} messages include details of what is mounted and 1790unmounted and when filesystems have timed out. If you want to have the 1791default set of messages without the @samp{info} messages then you simply 1792need @samp{-x noinfo}. The messages given by @samp{user} relate to 1793errors in the mount maps, so these are useful when new maps are 1794installed. The following table lists the syslog priorites used for each 1795of the message types.@refill 1796 1797@table @code 1798@item fatal 1799LOG_CRIT 1800@item error 1801LOG_ERR 1802@item user 1803LOG_WARNING 1804@item warning 1805LOG_WARNING 1806@item info 1807LOG_INFO 1808@item debug 1809LOG_DEBUG 1810@item map 1811LOG_DEBUG 1812@item stats 1813LOG_INFO 1814@end table 1815 1816 1817The options can be prefixed by the string @samp{no} to indicate 1818that this option should be turned off. For example, to obtain all 1819but @samp{info} messages the option @samp{-x all,noinfo} would be used. 1820 1821If @i{Amd} was built with debugging enabled the @code{debug} option is 1822automatically enabled regardless of the command line options. 1823 1824@node -y Option, -C-Option, -x Option, Amd Command Line Options 1825@comment node-name, next, previous, up 1826@section @code{-y} @var{NIS-domain} 1827@cindex NIS (YP) domain name 1828@cindex Overriding the NIS (YP) domain name 1829@cindex Setting the NIS (YP) domain name 1830@cindex YP domain name 1831 1832Selects an alternate NIS domain. This is useful for debugging and 1833cross-domain shared mounting. If this flag is specified, @i{Amd} 1834immediately attempts to bind to a server for this domain. 1835@c @i{Amd} refers to NIS maps when it starts, unless the ``-m'' option 1836@c is specified, and whenever required in a mount map. 1837 1838@node -C-Option, -D-Option, -y Option, Amd Command Line Options 1839@comment node-name, next, previous, up 1840@section @code{-C} @var{cluster-name} 1841@cindex Cluster names 1842@cindex Setting the cluster name 1843 1844Specifies the name of the cluster of which the local machine is a member. 1845The only effect is to set the variable @code{$@{cluster@}}. 1846The @dfn{cluster-name} is will usually obtained by running another command which uses 1847a database to map the local hostname into a cluster name. 1848@code{$@{cluster@}} can then be used as a selector to restrict mounting of 1849replicated data. 1850If this option is not given, @code{$@{cluster@}} has the same value as @code{$@{domain@}}. 1851This would be used as follows: 1852 1853@example 1854amd -C `clustername` ... 1855@end example 1856 1857@node -D-Option, , -C-Option, Amd Command Line Options 1858@comment node-name, next, previous, up 1859@section @code{-D} @var{opts} 1860@cindex Debug options 1861@cindex Setting debug flags 1862 1863Controls the verbosity and coverage of the debugging trace; @dfn{opts} 1864is a comma separated list of debugging options. The ``-D'' option is 1865only available if @i{Amd} was compiled with @samp{-DDEBUG}. The memory 1866debugging facilities are only available if @i{Amd} was compiled with 1867@samp{-DDEBUG_MEM} (in addition to @samp{-DDEBUG}). 1868 1869The most common options to use are @samp{-D trace} and @samp{-D test} 1870(which turns on all the useful debug options). See the program source 1871for a more detailed explanation of the available options. 1872 1873@node Filesystem Types, Run-time Administration, Amd Command Line Options, Top 1874@comment node-name, next, previous, up 1875@chapter Filesystem Types 1876@cindex Filesystem types 1877@cindex Mount types 1878@cindex Types of filesystem 1879 1880To mount a volume, @i{Amd} must be told the type of filesystem to be 1881used. Each filesystem type typically requires additional information 1882such as the fileserver name for NFS. 1883 1884From the point of view of @i{Amd}, a @dfn{filesystem} is anything that 1885can resolve an incoming name lookup. An important feature is support 1886for multiple filesystem types. Some of these filesystems are 1887implemented in the local kernel and some on remote fileservers, whilst 1888the others are implemented internally by @i{Amd}.@refill 1889 1890The two common filesystem types are UFS and NFS. Four other user 1891accessible filesystems (@samp{link}, @samp{program}, @samp{auto} and 1892@samp{direct}) are also implemented internally by @i{Amd} and these are 1893described below. There are two additional filesystem types internal to 1894@i{Amd} which are not directly accessible to the user (@samp{inherit} 1895and @samp{error}). Their use is described since they may still have an 1896effect visible to the user.@refill 1897 1898@menu 1899* Network Filesystem:: A single NFS filesystem. 1900* Network Host Filesystem:: NFS mount a host's entire export tree. 1901* Network Filesystem Group:: An atomic group of NFS filesystems. 1902* Unix Filesystem:: Native disk filesystem. 1903* Program Filesystem:: Generic Program mounts. 1904* Symbolic Link Filesystem:: Local link referencing existing filesystem. 1905* Automount Filesystem:: 1906* Direct Automount Filesystem:: 1907* Union Filesystem:: 1908* Error Filesystem:: 1909* Top-level Filesystem:: 1910* Root Filesystem:: 1911* Inheritance Filesystem:: 1912@end menu 1913 1914@node Network Filesystem, Network Host Filesystem, Filesystem Types, Filesystem Types 1915@comment node-name, next, previous, up 1916@section Network Filesystem (@samp{type:=nfs}) 1917@cindex NFS 1918@cindex Mounting an NFS filesystem 1919@cindex How to mount and NFS filesystem 1920@cindex nfs, filesystem type 1921@cindex Filesystem type; nfs 1922 1923The @dfn{nfs} filesystem type provides access to Sun's NFS. 1924 1925@noindent 1926The following options must be specified: 1927 1928@table @code 1929@cindex rhost, mount option 1930@cindex Mount option; rhost 1931@item rhost 1932the remote fileserver. This must be an entry in the hosts database. IP 1933addresses are not accepted. The default value is taken 1934from the local host name (@code{$@{host@}}) if no other value is 1935specified. 1936 1937@cindex rfs, mount option 1938@cindex Mount option; rfs 1939@item rfs 1940the remote filesystem. 1941If no value is specified for this option, an internal default of 1942@code{$@{path@}} is used. 1943@end table 1944 1945NFS mounts require a two stage process. First, the @dfn{file handle} of 1946the remote file system must be obtained from the server. Then a mount 1947system call must be done on the local system. @i{Amd} keeps a cache 1948of file handles for remote file systems. The cache entries have a 1949lifetime of a few minutes. 1950 1951If a required file handle is not in the cache, @i{Amd} sends a request 1952to the remote server to obtain it. @i{Amd} @dfn{does not} wait for 1953a response; it notes that one of the locations needs retrying, but 1954continues with any remaining locations. When the file handle becomes 1955available, and assuming none of the other locations was successfully 1956mounted, @i{Amd} will retry the mount. This mechanism allows several 1957NFS filesystems to be mounted in parallel. 1958@c @footnote{The mechanism 1959@c is general, however NFS is the only filesystem 1960@c for which the required hooks have been written.} 1961The first one which responds with a valid file handle will be used. 1962 1963@noindent 1964An NFS entry might be: 1965 1966@example 1967jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp 1968@end example 1969 1970The mount system call and any unmount attempts are always done 1971in a new task to avoid the possibilty of blocking @i{Amd}. 1972 1973@node Network Host Filesystem, Network Filesystem Group, Network Filesystem, Filesystem Types 1974@comment node-name, next, previous, up 1975@section Network Host Filesystem (@samp{type:=host}) 1976@cindex Network host filesystem 1977@cindex Mounting entire export trees 1978@cindex How to mount all NFS exported filesystems 1979@cindex host, filesystem type 1980@cindex Filesystem type; host 1981 1982@c NOTE: the current implementation of the @dfn{host} filesystem type 1983@c sometimes fails to maintain a consistent view of the remote mount tree. 1984@c This happens when the mount times out and only some of the remote mounts 1985@c are successfully unmounted. To prevent this from occuring, use the 1986@c @samp{nounmount} mount option. 1987 1988The @dfn{host} filesystem allows access to the entire export tree of an 1989NFS server. The implementation is layered above the @samp{nfs} 1990implementation so keep-alives work in the same way. The only option 1991which needs to specified is @samp{rhost} which is the name of the 1992fileserver to mount. 1993 1994The @samp{host} filesystem type works by querying the mount daemon on 1995the given fileserver to obtain its export list. @i{Amd} then obtains 1996filehandles for each of the exported filesystems. Any errors at this 1997stage cause that particular filesystem to be ignored. Finally each 1998filesystem is mounted. Again, errors are logged but ignored. One 1999common reason for mounts to fail is that the mount point does not exist. 2000Although @i{Amd} attempts to automatically create the mount point, it 2001may be on a remote filesystem to which @i{Amd} does not have write 2002permission. 2003 2004When an attempt to unmount a @samp{host} filesystem mount fails, @i{Amd} 2005remounts any filesystems which had succesfully been unmounted. To do 2006this @i{Amd} queries the mount daemon again and obtains a fresh copy of 2007the export list. @i{Amd} then tries to mount any exported filesystems 2008which are not currently mounted. 2009 2010Sun's automounter provides a special @samp{-hosts} map. To achieve the 2011same effect with @i{Amd} requires two steps. First a mount map must 2012be created as follows: 2013 2014@example 2015/defaults type:=host;fs:=$@{autodir@}/$@{rhost@}/root;rhost:=$@{key@} 2016* opts:=rw,nosuid,grpid 2017@end example 2018 2019@noindent 2020and then start @i{Amd} with the following command 2021 2022@example 2023amd /n net.map 2024@end example 2025 2026@noindent 2027where @samp{net.map} is the name of map described above. Note that the 2028value of @code{$@{fs@}} is overridden in the map. This is done to avoid 2029a clash between the mount tree and any other filesystem already mounted 2030from the same fileserver. 2031 2032If different mount options are needed for different hosts then 2033additional entries can be added to the map, for example 2034 2035@example 2036host2 opts:=ro,nosuid,soft 2037@end example 2038 2039@noindent 2040would soft mount @samp{host2} read-only. 2041 2042@node Network Filesystem Group, Unix Filesystem, Network Host Filesystem, Filesystem Types 2043@comment node-name, next, previous, up 2044@section Network Filesystem Group (@samp{type:=nfsx}) 2045@cindex Network filesystem group 2046@cindex Atomic NFS mounts 2047@cindex Mounting an atomic group of NFS filesystems 2048@cindex How to mount an atomic group of NFS filesystems 2049@cindex nfsx, filesystem type 2050@cindex Filesystem type; nfsx 2051 2052The @dfn{nfsx} filesystem allows a group of filesystems to be mounted 2053from a single NFS server. The implementation is layered above the 2054@samp{nfs} implementation so keep-alives work in the same way. 2055 2056The options are the same as for the @samp{nfs} filesystem with one 2057difference. 2058 2059@noindent 2060The following options must be specified: 2061 2062@table @code 2063@item rhost 2064the remote fileserver. This must be an entry in the hosts database. IP 2065addresses are not accepted. The default value is taken from the local 2066host name (@code{$@{host@}}) if no other value is specified. 2067 2068@item rfs 2069as a list of filesystems to mount. The list is in the form of a comma 2070separated strings. 2071@end table 2072 2073@noindent 2074For example: 2075 2076@example 2077pub type:=nfsx;rhost:=gould;\ 2078 rfs:=/public,/,graphics,usenet;fs:=$@{autodir@}/$@{rhost@}/root 2079@end example 2080 2081The first string defines the root of the tree, and is applied as a 2082prefix to the remaining members of the list which define the individual 2083filesystems. The first string is @emph{not} used as a filesystem name. 2084A parallel operation is used to determine the local mount points to 2085ensure a consistent layout of a tree of mounts. 2086 2087Here, the @emph{three} filesystems, @samp{/public}, 2088@samp{/public/graphics} and @samp{/public/usenet}, would be mounted.@refill 2089 2090A local mount point, @code{$@{fs@}}, @emph{must} be specified. The 2091default local mount point will not work correctly in the general case. 2092A suggestion is to use @samp{fs:=$@{autodir@}/$@{rhost@}/root}.@refill 2093 2094@node Unix Filesystem, Program Filesystem, Network Filesystem Group, Filesystem Types 2095@comment node-name, next, previous, up 2096@section Unix Filesystem (@samp{type:=ufs}) 2097@cindex Unix filesystem 2098@cindex UFS 2099@cindex Mounting a UFS filesystem 2100@cindex Mounting a local disk 2101@cindex How to mount a UFS filesystems 2102@cindex How to mount a local disk 2103@cindex Disk filesystems 2104@cindex ufs, filesystem type 2105@cindex Filesystem type; ufs 2106 2107The @dfn{ufs} filesystem type provides access to the system's 2108standard disk filesystem---usually a derivative of the Berkeley Fast Filesystem. 2109 2110@noindent 2111The following option must be specified: 2112 2113@table @code 2114@cindex dev, mount option 2115@cindex Mount option; dev 2116@item dev 2117the block special device to be mounted. 2118@end table 2119 2120A UFS entry might be: 2121 2122@example 2123jsp host==charm;type:=ufs;dev:=/dev/xd0g;sublink:=jsp 2124@end example 2125 2126@node Program Filesystem, Symbolic Link Filesystem, Unix Filesystem, Filesystem Types 2127@comment node-name, next, previous, up 2128@section Program Filesystem (@samp{type:=program}) 2129@cindex Program filesystem 2130@cindex Mount a filesystem under program control 2131@cindex program, filesystem type 2132@cindex Filesystem type; program 2133 2134The @dfn{program} filesystem type allows a program to be run whenever a 2135mount or unmount is required. This allows easy addition of support for 2136other filesystem types, such as MIT's Remote Virtual Disk (RVD) 2137which has a programmatic interface via the commands 2138@samp{rvdmount} and @samp{rvdunmount}. 2139 2140@noindent 2141The following options must be specified: 2142 2143@table @code 2144@cindex mount, mount option 2145@cindex Mount option; mount 2146@item mount 2147the program which will perform the mount. 2148 2149@cindex unmount, mount option 2150@cindex Mount option; unmount 2151@item unmount 2152the program which will perform the unmount. 2153@end table 2154 2155The exit code from these two programs is interpreted as a Unix error 2156code. As usual, exit code zero indicates success. To execute the 2157program @i{Amd} splits the string on whitespace to create an array of 2158substrings. Single quotes @samp{'} can be used to quote whitespace 2159if that is required in an argument. There is no way to escape or change 2160the quote character. 2161 2162To run the program @samp{rvdmount} with a host name and filesystem as 2163arguments would be specified by @samp{mount:="/etc/rvdmount rvdmount 2164fserver $@{path@}"}. 2165 2166The first element in the array is taken as the pathname of the program 2167to execute. The other members of the array form the argument vector to 2168be passed to the program, @dfn{including argument zero}. This means 2169that the split string must have at least two elements. The program is 2170directly executed by @i{Amd}, not via a shell. This means that scripts 2171must begin with a @code{#!} interpreter specification. 2172 2173If a filesystem type is to be heavily used, it may be worthwhile adding 2174a new filesystem type into @i{Amd}, but for most uses the program 2175filesystem should suffice. 2176 2177When the program is run, standard input and standard error are inherited 2178from the current values used by @i{Amd}. Standard output is a 2179duplicate of standard error. The value specified with the ``-l'' 2180command line option has no effect on standard error. 2181 2182@node Symbolic Link Filesystem, Symbolic Link Filesystem II, Program Filesystem, Filesystem Types 2183@comment node-name, next, previous, up 2184@section Symbolic Link Filesystem (@samp{type:=link}) 2185@cindex Symbolic link filesystem 2186@cindex Referencing part of the local name space 2187@cindex Mounting part of the local name space 2188@cindex How to reference part of the local name space 2189@cindex link, filesystem type 2190@cindex symlink, link filesystem type 2191@cindex Filesystem type; link 2192 2193Each filesystem type creates a symbolic link to point from the volume 2194name to the physical mount point. The @samp{link} filesystem does the 2195same without any other side effects. This allows any part of the 2196machines name space to be accessed via @i{Amd}. 2197 2198One common use for the symlink filesystem is @file{/homes} which can be 2199made to contain an entry for each user which points to their 2200(auto-mounted) home directory. Although this may seem rather expensive, 2201it provides a great deal of administrative flexibility. 2202 2203@noindent 2204The following option must be defined: 2205 2206@table @code 2207@item fs 2208The value of @var{fs} option specifies the destination of the link, as 2209modified by the @var{sublink} option. If @var{sublink} is non-null, it 2210is appended to @code{$@{fs@}}@code{/} and the resulting string is used 2211as the target. 2212@end table 2213 2214The @samp{link} filesystem can be though of as identical to the 2215@samp{ufs} filesystem but without actually mounting anything. 2216 2217An example entry might be: 2218 2219@example 2220jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp 2221@end example 2222which would return a symbolic link pointing to @file{/home/charm/jsp}. 2223 2224@node Symbolic Link Filesystem II, Automount Filesystem, Program Filesystem, Filesystem Types 2225@comment node-name, next, previous, up 2226@section Symbolic Link Filesystem II (@samp{type:=link}) 2227@cindex Symbolic link filesystem II 2228@cindex Referencing an existing part of the local name space 2229@cindex Mounting an existing part of the local name space 2230@cindex How to reference an existing part of the local name space 2231@cindex linkx, filesystem type 2232@cindex symlink, linkx filesystem type 2233@cindex Filesystem type; linkx 2234 2235The @samp{linkx} filesystem type is identical to @samp{link} with the 2236exception that the target of the link must exist. Existence is checked 2237with the @samp{lstat} system call. 2238 2239The @samp{linkx} filesystem type is particularly useful for wildcard map 2240entries. In this case, a list of possible targets can be give and 2241@i{Amd} will choose the first one which exists on the local machine. 2242 2243@node Automount Filesystem, Direct Automount Filesystem, Symbolic Link Filesystem II, Filesystem Types 2244@comment node-name, next, previous, up 2245@section Automount Filesystem (@samp{type:=auto}) 2246@cindex Automount filesystem 2247@cindex Map cache types 2248@cindex Setting map cache parameters 2249@cindex How to set map cache parameters 2250@cindex How to start an indirect automount point 2251@cindex auto, filesystem type 2252@cindex Filesystem type; auto 2253@cindex SIGHUP signal 2254@cindex Map cache synchronising 2255@cindex Synchronising the map cache 2256@cindex Map cache options 2257@cindex Regular expressions in maps 2258 2259The @dfn{auto} filesystem type creates a new automount point below an 2260existing automount point. Top-level automount points appear as system 2261mount points. An automount mount point can also appear as a 2262sub-directory of an existing automount point. This allows some 2263additional structure to be added, for example to mimic the mount tree of 2264another machine. 2265 2266The following options may be specified: 2267 2268@table @code 2269@cindex cache, mount option 2270@cindex Mount option; cache 2271@item cache 2272specifies whether the data in this mount-map should be 2273cached. The default value is @samp{none}, in which case 2274no caching is done in order to conserve memory. 2275However, better performance and reliability can be obtained by caching 2276some or all of a mount-map. 2277 2278If the cache option specifies @samp{all}, 2279the entire map is enumerated when the mount point is created. 2280 2281If the cache option specifies @samp{inc}, caching is done incrementally 2282as and when data is required. 2283Some map types do not support cache mode @samp{all}, in which case @samp{inc} 2284is used whenever @samp{all} is requested. 2285 2286Caching can be entirely disabled by using cache mode @samp{none}. 2287 2288If the cache option specifies @samp{regexp} then the entire map will be 2289enumerated and each key will be treated as an egrep-style regular 2290expression. The order in which a cached map is searched does not 2291correspond to the ordering in the source map so the regular expressions 2292should be mutually exclusive to avoid confusion. 2293 2294Each mount map type has a default cache type, usually @samp{inc}, which 2295can be selected by specifying @samp{mapdefault}. 2296 2297The cache mode for a mount map can only be selected on the command line. 2298Starting @i{Amd} with the command: 2299 2300@example 2301amd /homes hesiod.homes -cache:=inc 2302@end example 2303 2304will cause @samp{/homes} to be automounted using the @dfn{Hesiod} name 2305server with local incremental caching of all succesfully resolved names. 2306 2307All cached data is forgotten whenever @i{Amd} receives a @samp{SIGHUP} 2308signal and, if cache @samp{all} mode was selected, the cache will be 2309reloaded. This can be used to inform @i{Amd} that a map has been 2310updated. In addition, whenever a cache lookup fails and @i{Amd} needs 2311to examine a map, the map's modify time is examined. If the cache is 2312out of date with respect to the map then it is flushed as if a 2313@samp{SIGHUP} had been received. 2314 2315An additional option (@samp{sync}) may be specified to force @i{Amd} to 2316check the map's modify time whenever a cached entry is being used. For 2317example, an incremental, synchronised cache would be created by the 2318following command: 2319 2320@example 2321amd /homes hesiod.homes -cache:=inc,sync 2322@end example 2323 2324@item fs 2325specifies the name of the mount map to use for the new mount point. 2326 2327Arguably this should have been specified with the @code{$@{rfs@}} option but 2328we are now stuck with it due to historical accident. 2329 2330@c %If the string @samp{.} is used then the same map is used; 2331@c %in addition the lookup prefix is set to the name of the mount point followed 2332@c %by a slash @samp{/}. 2333@c %This is the same as specifying @samp{fs:=\$@{map@};pref:=\$@{key@}/}. 2334@c 2335 2336@item pref 2337alters the name that is looked up in the mount map. If 2338@code{$@{pref@}}, the @dfn{prefix}, is non-null then it is prepended to 2339the name requested by the kernel @dfn{before} the map is searched. 2340@end table 2341 2342The server @samp{dylan.doc.ic.ac.uk} has two user disks: 2343@samp{/dev/dsk/2s0} and @samp{/dev/dsk/5s0}. These are accessed as 2344@samp{/home/dylan/dk2} and @samp{/home/dylan/dk5} respectively. Since 2345@samp{/home} is already an automount point, this naming is achieved with 2346the following map entries:@refill 2347 2348@example 2349dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 2350dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 2351dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0 2352@end example 2353 2354@node Direct Automount Filesystem, Union Filesystem, Automount Filesystem, Filesystem Types 2355@comment node-name, next, previous, up 2356@section Direct Automount Filesystem (@samp{type:=direct}) 2357@cindex Direct automount filesystem 2358@cindex How to start a direct automount point 2359@cindex direct, filesystem type 2360@cindex Filesystem type; direct 2361 2362The @dfn{direct} filesystem is almost identical to the automount 2363filesystem. Instead of appearing to be a directory of mount points, it 2364appears as a symbolic link to a mounted filesystem. The mount is done 2365at the time the link is accessed. @xref{Automount Filesystem} for a 2366list of required options. 2367 2368Direct automount points are created by specifying the @samp{direct} 2369filesystem type on the command line: 2370 2371@example 2372amd ... /usr/man auto.direct -type:=direct 2373@end example 2374 2375where @samp{auto.direct} would contain an entry such as: 2376 2377@example 2378usr/man -type:=nfs;rfs:=/usr/man \ 2379 rhost:=man-server1 rhost:=man-server2 2380@end example 2381 2382In this example, @samp{man-server1} and @samp{man-server2} are file 2383servers which export copies of the manual pages. Note that the key 2384which is looked up is the name of the automount point without the 2385leading @samp{/}. 2386 2387@node Union Filesystem, Error Filesystem, Direct Automount Filesystem, Filesystem Types 2388@comment node-name, next, previous, up 2389@section Union Filesystem (@samp{type:=union}) 2390@cindex Union filesystem 2391@cindex union, filesystem type 2392@cindex Filesystem type; union 2393 2394The @dfn{union} filesystem type allows the contents of several 2395directories to be merged and made visible in a single directory. This 2396can be used to overcome one of the major limitations of the Unix mount 2397mechanism which only allows complete directories to be mounted. 2398 2399For example, supposing @file{/tmp} and @file{/var/tmp} were to be merged 2400into a new directory called @file{/mtmp}, with files in @file{/var/tmp} 2401taking precedence. The following command could be used to achieve this 2402effect: 2403 2404@example 2405amd ... /mtmp union:/tmp:/var/tmp -type:=union 2406@end example 2407 2408Currently, the unioned directories must @emph{not} be automounted. That 2409would cause a deadlock. This seriously limits the current usefulness of 2410this filesystem type and the problem will be addressed in a future 2411release of @i{Amd}. 2412 2413Files created in the union directory are actually created in the last 2414named directory. This is done by creating a wildcard entry which points 2415to the correct directory. The wildcard entry is visible if the union 2416directory is listed, so allowing you to see which directory has 2417priority. 2418 2419The files visible in the union directory are computed at the time 2420@i{Amd} is started, and are not kept uptodate with respect to the 2421underlying directories. Similarly, if a link is removed, for example 2422with the @samp{rm} command, it will be lost forever. 2423 2424@node Error Filesystem, Top-level Filesystem, Union Filesystem, Filesystem Types 2425@comment node-name, next, previous, up 2426@section Error Filesystem (@samp{type:=error}) 2427@cindex Error filesystem 2428@cindex error, filesystem type 2429@cindex Filesystem type; error 2430 2431The @dfn{error} filesystem type is used internally as a catch-all in 2432the case where none of the other filesystems was selected, or some other 2433error occurred. 2434Lookups and mounts always fail with ``No such file or directory''. 2435All other operations trivially succeed. 2436 2437The error filesystem is not directly accessible. 2438 2439@node Top-level Filesystem, Root Filesystem, Error Filesystem, Filesystem Types 2440@comment node-name, next, previous, up 2441@section Top-level Filesystem (@samp{type:=toplvl}) 2442@cindex Top level filesystem 2443@cindex toplvl, filesystem type 2444@cindex Filesystem type; toplvl 2445 2446The @dfn{toplvl} filesystems is derived from the @samp{auto} filesystem 2447and is used to mount the top-level automount nodes. Requests of this 2448type are automatically generated from the command line arguments and 2449can also be passed in by using the ``-M'' option of the @dfn{Amq} command. 2450 2451@node Root Filesystem, Inheritance Filesystem, Top-level Filesystem, Filesystem Types 2452@comment node-name, next, previous, up 2453@section Root Filesystem 2454@cindex Root filesystem 2455@cindex root, filesystem type 2456@cindex Filesystem type; root 2457 2458The @dfn{root} (@samp{type:=root}) filesystem type acts as an internal 2459placeholder onto which @i{Amd} can pin @samp{toplvl} mounts. Only one 2460node of this type need ever exist and one is created automatically 2461during startup. The effect of creating a second root node is undefined. 2462 2463@node Inheritance Filesystem, , Root Filesystem, Filesystem Types 2464@comment node-name, next, previous, up 2465@section Inheritance Filesystem 2466@cindex Inheritance filesystem 2467@cindex Nodes generated on a restart 2468@cindex inherit, filesystem type 2469@cindex Filesystem type; inherit 2470 2471The @dfn{inheritance} (@samp{type:=inherit}) filesystem is not directly 2472accessible. Instead, internal mount nodes of this type are 2473automatically generated when @i{Amd} is started with the ``-r'' option. 2474At this time the system mount table is scanned to locate any filesystems 2475which are already mounted. If any reference to these filesystems is 2476made through @i{Amd} then instead of attempting to mount it, @i{Amd} 2477simulates the mount and @dfn{inherits} the filesystem. This allows a 2478new version of @i{Amd} to be installed on a live system simply by 2479killing the old daemon with @code{SIGTERM} and starting the new one.@refill 2480 2481This filesystem type is not generally visible externally, but it is 2482possible that the output from @samp{amq -m} may list @samp{inherit} as 2483the filesystem type. This happens when an inherit operation cannot 2484be completed for some reason, usually because a fileserver is down. 2485 2486@node Run-time Administration, FSinfo, Filesystem Types, Top 2487@comment node-name, next, previous, up 2488@chapter Run-time Administration 2489@cindex Run-time administration 2490@cindex Amq command 2491 2492@menu 2493* Starting Amd:: 2494* Stopping Amd:: 2495* Controlling Amd:: 2496@end menu 2497 2498@node Starting Amd, Stopping Amd, Run-time Administration, Run-time Administration 2499@comment node-name, next, previous, up 2500@section Starting @i{Amd} 2501@cindex Starting Amd 2502@cindex Additions to /etc/rc.local 2503@cindex /etc/rc.local additions 2504@cindex /etc/amd.start 2505 2506@i{Amd} is best started from @samp{/etc/rc.local}: 2507 2508@example 2509if [ -f /etc/amd.start ]; then 2510 sh /etc/amd.start; (echo -n ' amd') >/dev/console 2511fi 2512@end example 2513 2514@noindent 2515The shell script, @samp{amd.start}, contains: 2516 2517@example 2518#!/bin/sh - 2519PATH=/etc:/bin:/usr/bin:/usr/ucb:$PATH export PATH 2520 2521# 2522# Either name of logfile or "syslog" 2523# 2524LOGFILE=syslog 2525#LOGFILE=/var/log/amd 2526 2527# 2528# Figure out whether domain name is in host name 2529# If the hostname is just the machine name then 2530# pass in the name of the local domain so that the 2531# hostnames in the map are domain stripped correctly. 2532# 2533case `hostname` in 2534*.*) dmn= ;; 2535*) dmn='-d doc.ic.ac.uk' 2536esac 2537 2538# 2539# Zap earlier log file 2540# 2541case "$LOGFILE" in 2542*/*) 2543 mv "$LOGFILE" "$LOGFILE"- 2544 > "$LOGFILE" 2545 ;; 2546syslog) 2547 : nothing 2548 ;; 2549esac 2550 2551cd /usr/sbin 2552# 2553# -r restart 2554# -d dmn local domain 2555# -w wait wait between unmount attempts 2556# -l log logfile or "syslog" 2557# 2558eval ./amd -r $dmn -w 240 -l "$LOGFILE" \ 2559 /homes amd.homes -cache:=inc \ 2560 /home amd.home -cache:=inc \ 2561 /vol amd.vol -cache:=inc \ 2562 /n amd.net -cache:=inc 2563@end example 2564 2565If the list of automount points and maps is contained in a file or NIS map 2566it is easily incorporated onto the command line: 2567 2568@example 2569... 2570eval ./amd -r $dmn -w 240 -l "$LOGFILE" `ypcat -k auto.master` 2571@end example 2572 2573@node Stopping Amd, Controlling Amd, Starting Amd, Run-time Administration 2574@comment node-name, next, previous, up 2575@section Stopping @i{Amd} 2576@cindex Stopping Amd 2577@cindex SIGTERM signal 2578@cindex SIGINT signal 2579 2580@i{Amd} stops in response to two signals. 2581 2582@table @samp 2583@item SIGTERM 2584causes the top-level automount points to be unmounted and then @i{Amd} 2585to exit. Any automounted filesystems are left mounted. They can be 2586recovered by restarting @i{Amd} with the ``-r'' command line option.@refill 2587 2588@item SIGINT 2589causes @i{Amd} to attempt to unmount any filesystems which it has 2590automounted, in addition to the actions of @samp{SIGTERM}. This signal 2591is primarly used for debugging.@refill 2592@end table 2593 2594Actions taken for other signals are undefined. 2595 2596@node Controlling Amd, , Stopping Amd, Run-time Administration 2597@comment node-name, next, previous, up 2598@section Controlling @i{Amd} 2599@cindex Controlling Amd 2600@cindex Discovering what is going on at run-time 2601@cindex Listing currently mounted filesystems 2602 2603It is sometimes desirable or necessary to exercise external control 2604over some of @i{Amd}'s internal state. To support this requirement, 2605@i{Amd} implements an RPC interface which is used by the @dfn{Amq} program. 2606A variety of information is available. 2607 2608@i{Amq} generally applies an operation, specified by a single letter option, 2609to a list of mount points. The default operation is to obtain statistics 2610about each mount point. This is similar to the output shown above 2611but includes information about the number and type of accesses to each 2612mount point. 2613 2614@menu 2615* Amq default:: Default command behaviour. 2616* Amq -f option:: Flushing the map cache. 2617* Amq -h option:: Controlling a non-local host. 2618* Amq -m option:: Obtaining mount statistics. 2619* Amq -M-option:: Mounting a volume. 2620* Amq -s option:: Obtaining global statistics. 2621* Amq -u option:: Forcing volumes to time out. 2622* Amq -v option:: Version information. 2623* Other Amq options:: Three other special options. 2624@end menu 2625 2626@node Amq default, Amq -f option, Controlling Amd, Controlling Amd 2627@comment node-name, next, previous, up 2628@subsection @i{Amq} default information 2629 2630With no arguments, @dfn{Amq} obtains a brief list of all existing 2631mounts created by @i{Amd}. This is different from the list displayed by 2632@b{df}(1) since the latter only includes system mount points. 2633 2634@noindent 2635The output from this option includes the following information: 2636 2637@itemize @bullet 2638@item 2639the automount point, 2640@item 2641the filesystem type, 2642@item 2643the mount map or mount information, 2644@item 2645the internal, or system mount point. 2646@end itemize 2647 2648@noindent 2649For example: 2650 2651@example 2652/ root "root" sky:(pid75) 2653/homes toplvl /usr/local/etc/amd.homes /homes 2654/home toplvl /usr/local/etc/amd.home /home 2655/homes/jsp nfs charm:/home/charm /a/charm/home/charm/jsp 2656/homes/phjk nfs toytown:/home/toytown /a/toytown/home/toytown/ai/phjk 2657@end example 2658 2659@noindent 2660If an argument is given then statistics for that volume name will 2661be output. For example: 2662 2663@example 2664What Uid Getattr Lookup RdDir RdLnk Statfs Mounted@@ 2665/homes 0 1196 512 22 0 30 90/09/14 12:32:55 2666/homes/jsp 0 0 0 0 1180 0 90/10/13 12:56:58 2667@end example 2668 2669@table @code 2670@item What 2671the volume name. 2672 2673@item Uid 2674ignored. 2675 2676@item Getattr 2677the count of NFS @dfn{getattr} requests on this node. This should only be 2678non-zero for directory nodes. 2679 2680@item Lookup 2681the count of NFS @dfn{lookup} requests on this node. This should only be 2682non-zero for directory nodes. 2683 2684@item RdDir 2685the count of NFS @dfn{readdir} requests on this node. This should only 2686be non-zero for directory nodes. 2687 2688@item RdLnk 2689the count of NFS @dfn{readlink} requests on this node. This should be 2690zero for directory nodes. 2691 2692@item Statfs 2693the could of NFS @dfn{statfs} requests on this node. This should only 2694be non-zero for top-level automount points. 2695 2696@item Mounted@@ 2697the date and time the volume name was first referenced. 2698@end table 2699 2700@node Amq -f option, Amq -h option, Amq default, Controlling Amd 2701@comment node-name, next, previous, up 2702@subsection @i{Amq} -f option 2703@cindex Flushing the map cache 2704@cindex Map cache, flushing 2705 2706The ``-f'' option causes @i{Amd} to flush the internal mount map cache. 2707This is useful for Hesiod maps since @i{Amd} will not automatically 2708notice when they have been updated. The map cache can also be 2709synchronised with the map source by using the @samp{sync} option 2710(@pxref{Automount Filesystem}).@refill 2711 2712@node Amq -h option, Amq -m option, Amq -f option, Controlling Amd 2713@comment node-name, next, previous, up 2714@subsection @i{Amq} -h option 2715@cindex Querying an alternate host 2716 2717By default the local host is used. In an HP-UX cluster the root server 2718is used since that is the only place in the cluster where @i{Amd} will 2719be running. To query @i{Amd} on another host the ``-h'' option should 2720be used. 2721 2722@node Amq -m option, Amq -M-option, Amq -h option, Controlling Amd 2723@comment node-name, next, previous, up 2724@subsection @i{Amq} -m option 2725 2726The ``-m'' option displays similar information about mounted 2727filesystems, rather than automount points. The output includes the 2728following information: 2729 2730@itemize @bullet 2731@item 2732the mount information, 2733@item 2734the mount point, 2735@item 2736the filesystem type, 2737@item 2738the number of references to this filesystem, 2739@item 2740the server hostname, 2741@item 2742the state of the file server, 2743@item 2744any error which has occured. 2745@end itemize 2746 2747For example: 2748 2749@example 2750"root" truth:(pid602) root 1 localhost is up 2751hesiod.home /home toplvl 1 localhost is up 2752hesiod.vol /vol toplvl 1 localhost is up 2753hesiod.homes /homes toplvl 1 localhost is up 2754amy:/home/amy /a/amy/home/amy nfs 5 amy is up 2755swan:/home/swan /a/swan/home/swan nfs 0 swan is up (Permission denied) 2756ex:/home/ex /a/ex/home/ex nfs 0 ex is down 2757@end example 2758 2759When the reference count is zero the filesystem is not mounted but 2760the mount point and server information is still being maintained 2761by @i{Amd}. 2762 2763@node Amq -M-option, Amq -s option, Amq -m option, Controlling Amd 2764@comment node-name, next, previous, up 2765@subsection @i{Amq} -M option 2766 2767The ``-M'' option passes a new map entry to @i{Amd} and waits for it to 2768be evaluated, possibly causing a mount. For example, the following 2769command would cause @samp{/home/toytown} on host @samp{toytown} to be 2770mounted locally on @samp{/mnt/toytown}. 2771 2772@example 2773amq -M '/mnt/toytown type:=nfs;rfs:=/home/toytown;rhost:=toytown;fs:=$@{key@}' 2774@end example 2775 2776@i{Amd} applies some simple security checks before allowing this 2777operation. The check tests whether the incoming request is from a 2778privileged UDP port on the local machine. ``Permission denied'' is 2779returned if the check fails. 2780 2781A future release of @i{Amd} will include code to allow the @b{mount}(8) 2782command to mount automount points: 2783 2784@example 2785mount -t amd /vol hesiod.vol 2786@end example 2787 2788This will then allow @i{Amd} to be controlled from the standard system 2789filesystem mount list. 2790 2791@node Amq -s option, Amq -u option, Amq -M-option, Controlling Amd 2792@comment node-name, next, previous, up 2793@subsection @i{Amq} -s option 2794@cindex Global statistics 2795@cindex Statistics 2796 2797The ``-s'' option displays global statistics. If any other options are specified 2798or any filesystems named then this option is ignored. For example: 2799 2800@example 2801requests stale mount mount unmount 2802deferred fhandles ok failed failed 28031054 1 487 290 7017 2804@end example 2805 2806@table @samp 2807@item Deferred requests 2808are those for which an immediate reply could not be constructed. For 2809example, this would happen if a background mount was required. 2810 2811@item Stale filehandles 2812counts the number of times the kernel passes a stale filehandle to @i{Amd}. 2813Large numbers indicate problems. 2814 2815@item Mount ok 2816counts the number of automounts which were successful. 2817 2818@item Mount failed 2819counts the number of automounts which failed. 2820 2821@item Unmount failed 2822counts the number of times a filesystem could not be unmounted. Very 2823large numbers here indicate that the time between unmount attempts 2824should be increased. 2825@end table 2826 2827@node Amq -u option, Amq -v option, Amq -s option, Controlling Amd 2828@comment node-name, next, previous, up 2829@subsection @i{Amq} -u option 2830@cindex Forcing filesystem to time out 2831@cindex Unmounting a filesystem 2832 2833The ``-u'' option causes the time-to-live interval of the named mount 2834points to be expired, thus causing an unmount attempt. This is the only 2835safe way to unmount an automounted filesystem. It is not possible to 2836unmount a filesystem which has been mounted with the @samp{nounmount} 2837flag. 2838 2839@c The ``-H'' option informs @i{Amd} that the specified mount point has hung - 2840@c as if its keepalive timer had expired. 2841 2842@node Amq -v option, Other Amq options, Amq -u option, Controlling Amd 2843@comment node-name, next, previous, up 2844@subsection @i{Amq} -v option 2845@cindex Version information at run-time 2846 2847The ``-v'' option displays the version of @i{Amd} in a similar way to 2848@i{Amd}'s ``-v'' option. 2849 2850@node Other Amq options, , Amq -v option, Controlling Amd 2851@comment node-name, next, previous, up 2852@subsection Other @i{Amq} options 2853 2854Three other operations are implemented. These modify the state of 2855@i{Amd} as a whole, rather than any particular filesystem. The ``-l'', 2856``-x'' and ``-D'' options have exactly the same effect as @i{Amd}'s 2857corresponding command line options. The ``-l'' option is rejected by 2858@i{Amd} in the current version for obvious security reasons. When 2859@i{Amd} receives a ``-x''flag it limits the log options being modified 2860to those which were not enabled at startup. This prevents a user 2861turning @emph{off} any logging option which was specified at startup, 2862though any which have been turned off since then can still be turned 2863off. The ``-D'' option has a similar behaviour. 2864 2865@node FSinfo, Examples, Run-time Administration, Top 2866@comment node-name, next, previous, up 2867@chapter FSinfo 2868@cindex FSinfo 2869@cindex Filesystem info package 2870 2871@menu 2872* FSinfo Overview:: Introduction to FSinfo. 2873* Using FSinfo:: Basic concepts. 2874* FSinfo Grammar:: Language syntax, semantics and examples. 2875* FSinfo host definitions:: Defining a new host. 2876* FSinfo host attributes:: Definable host attributes. 2877* FSinfo filesystems:: Defining locally attached filesystems. 2878* FSinfo static mounts:: Defining additional static mounts. 2879* FSinfo automount definitions:: 2880* FSinfo command line options:: 2881* FSinfo errors:: 2882@end menu 2883 2884@node FSinfo Overview, Using FSinfo, FSinfo, FSinfo 2885@comment node-name, next, previous, up 2886@section @i{FSinfo} overview 2887@cindex FSinfo overview 2888 2889@i{FSinfo} is a filesystem management tool. It has been designed to 2890work with @i{Amd} to help system administrators keep track of the ever 2891increasing filesystem namespace under their control. 2892 2893The purpose of @i{FSinfo} is to generate all the important standard 2894filesystem data files from a single set of input data. Starting with a 2895single data source guarantees that all the generated files are 2896self-consistent. One of the possible output data formats is a set of 2897@i{Amd} maps which can be used amongst the set of hosts described in the 2898input data. 2899 2900@i{FSinfo} implements a declarative language. This language is 2901specifically designed for describing filesystem namespace and physical 2902layouts. The basic declaration defines a mounted filesystem including 2903its device name, mount point, and all the volumes and access 2904permissions. @i{FSinfo} reads this information and builds an internal 2905map of the entire network of hosts. Using this map, many different data 2906formats can be produced including @file{/etc/fstab}, 2907@file{/etc/exports}, @i{Amd} mount maps and 2908@file{/etc/bootparams}.@refill 2909 2910@node Using FSinfo, FSinfo Grammar, FSinfo Overview, FSinfo 2911@comment node-name, next, previous, up 2912@section Using @i{FSinfo} 2913@cindex Using FSinfo 2914 2915The basic strategy when using @i{FSinfo} is to gather all the 2916information about all disks on all machines into one set of 2917declarations. For each machine being managed, the following data is 2918required: 2919 2920@itemize @bullet 2921@item 2922Hostname 2923@item 2924List of all filesystems and, optionally, their mount points. 2925@item 2926Names of volumes stored on each filesystem. 2927@item 2928NFS export information for each volume. 2929@item 2930The list of static filesystem mounts. 2931@end itemize 2932 2933The following information can also be entered into the same 2934configuration files so that all data can be kept in one place. 2935 2936@itemize @bullet 2937@item 2938List of network interfaces 2939@item 2940IP address of each interface 2941@item 2942Hardware address of each interface 2943@item 2944Dumpset to which each filesystem belongs 2945@item 2946and more @dots{} 2947@end itemize 2948 2949To generate @i{Amd} mount maps, the automount tree must also be defined 2950(@pxref{FSinfo automount definitions}). This will have been designed at 2951the time the volume names were allocated. Some volume names will not be 2952automounted, so @i{FSinfo} needs an explicit list of which volumes 2953should be automounted.@refill 2954 2955Hostnames are required at several places in the @i{FSinfo} language. It 2956is important to stick to either fully qualified names or unqualified 2957names. Using a mixture of the two will inevitably result in confusion. 2958 2959Sometimes volumes need to be referenced which are not defined in the set 2960of hosts being managed with @i{FSinfo}. The required action is to add a 2961dummy set of definitions for the host and volume names required. Since 2962the files generated for those particular hosts will not be used on them, 2963the exact values used is not critical. 2964 2965@node FSinfo Grammar, FSinfo host definitions, Using FSinfo, FSinfo 2966@comment node-name, next, previous, up 2967@section @i{FSinfo} grammar 2968@cindex FSinfo grammar 2969@cindex Grammar, FSinfo 2970 2971@i{FSinfo} has a relatively simple grammar. Distinct syntactic 2972constructs exist for each of the different types of data, though they 2973share a common flavour. Several conventions are used in the grammar 2974fragments below. 2975 2976The notation, @i{list(}@t{xxx}@i{)}, indicates a list of zero or more 2977@t{xxx}'s. The notation, @i{opt(}@t{xxx}@i{)}, indicates zero or one 2978@t{xxx}. Items in double quotes, @i{eg} @t{"host"}, represent input 2979tokens. Items in angle brackets, @i{eg} @var{<hostname>}, represent 2980strings in the input. Strings need not be in double quotes, except to 2981differentiate them from reserved words. Quoted strings may include the 2982usual set of C ``@t{\}'' escape sequences with one exception: a 2983backslash-newline-whitespace sequence is squashed into a single space 2984character. To defeat this feature, put a further backslash at the start 2985of the second line. 2986 2987At the outermost level of the grammar, the input consists of a 2988sequence of host and automount declarations. These declarations are 2989all parsed before they are analyzed. This means they can appear in 2990any order and cyclic host references are possible. 2991 2992@example 2993fsinfo : @i{list(}fsinfo_attr@i{)} ; 2994 2995fsinfo_attr : host | automount ; 2996@end example 2997 2998@menu 2999* FSinfo host definitions:: 3000* FSinfo automount definitions:: 3001@end menu 3002 3003@node FSinfo host definitions, FSinfo host attributes, FSinfo grammar, FSinfo 3004@comment node-name, next, previous, up 3005@section @i{FSinfo} host definitions 3006@cindex FSinfo host definitions 3007@cindex Defining a host, FSinfo 3008 3009A host declaration consists of three parts: a set of machine attribute 3010data, a list of filesystems physically attached to the machine, and a 3011list of additional statically mounted filesystems. 3012 3013@example 3014host : "host" host_data @i{list(}filesystem@i{@i{)}} @i{list(}mount@i{@i{)}} ; 3015@end example 3016 3017Each host must be declared in this way exactly once. Such things as the 3018hardware address, the architecture and operating system types and the 3019cluster name are all specified within the @dfn{host data}. 3020 3021All the disks the machine has should then be described in the @dfn{list 3022of filesystems}. When describing disks, you can specify what 3023@dfn{volname} the disk/partition should have and all such entries are 3024built up into a dictionary which can then be used for building the 3025automounter maps. 3026 3027The @dfn{list of mounts} specifies all the filesystems that should be 3028statically mounted on the machine. 3029 3030@menu 3031* FSinfo host attributes:: 3032* FSinfo filesystems:: 3033* FSinfo static mounts:: 3034@end menu 3035 3036@node FSinfo host attributes, FSinfo filesystems, FSinfo host definitions , FSinfo host definitions 3037@comment node-name, next, previous, up 3038@section @i{FSinfo} host attributes 3039@cindex FSinfo host attributes 3040@cindex Defining host attributes, FSinfo 3041 3042The host data, @dfn{host_data}, always includes the @dfn{hostname}. In 3043addition, several other host attributes can be given. 3044 3045@example 3046host_data : @var{<hostname>} 3047 | "@{" @i{list(}host_attrs@i{)} "@}" @var{<hostname>} 3048 ; 3049 3050host_attrs : host_attr "=" @var{<string>} 3051 | netif 3052 ; 3053 3054host_attr : "config" 3055 | "arch" 3056 | "os" 3057 | "cluster" 3058 ; 3059@end example 3060 3061The @dfn{hostname} is, typically, the fully qualified hostname of the 3062machine. 3063 3064Examples: 3065 3066@example 3067host dylan.doc.ic.ac.uk 3068 3069host @{ 3070 os = hpux 3071 arch = hp300 3072@} dougal.doc.ic.ac.uk 3073@end example 3074 3075The options that can be given as host attributes are shown below. 3076 3077@menu 3078* netif Option: FSinfo host netif: 3079* config Option: FSinfo host config: 3080* arch Option: FSinfo host arch: 3081* os Option: FSinfo host os: 3082* cluster Option: FSinfo host cluster: 3083@end menu 3084 3085@node FSinfo host netif, FSinfo host config, , FSinfo host attributes 3086@comment node-name, next, previous, up 3087@subsection netif Option 3088 3089This defines the set of network interfaces configured on the machine. 3090The interface attributes collected by @i{FSinfo} are the IP address, 3091subnet mask and hardware address. Multiple interfaces may be defined 3092for hosts with several interfaces by an entry for each interface. The 3093values given are sanity checked, but are currently unused for anything 3094else. 3095 3096@example 3097netif : "netif" @var{<string>} "@{" @i{list(}netif_attrs@i{)} "@}" ; 3098 3099netif_attrs : netif_attr "=" @var{<string>} ; 3100 3101netif_attr : "inaddr" | "netmask" | "hwaddr" ; 3102@end example 3103 3104Examples: 3105 3106@example 3107netif ie0 @{ 3108 inaddr = 129.31.81.37 3109 netmask = 0xfffffe00 3110 hwaddr = "08:00:20:01:a6:a5" 3111@} 3112 3113netif ec0 @{ @} 3114@end example 3115 3116@node FSinfo host config, FSinfo host arch, FSinfo host netif, FSinfo host attributes 3117@comment node-name, next, previous, up 3118@subsection config Option 3119@cindex FSinfo config host attribute 3120@cindex config, FSinfo host attribute 3121 3122This option allows you to specify configuration variables for the 3123startup scripts (@file{rc} scripts). A simple string should immediately 3124follow the keyword. 3125 3126Example: 3127 3128@example 3129config "NFS_SERVER=true" 3130config "ZEPHYR=true" 3131@end example 3132 3133This option is currently unsupported. 3134 3135@node FSinfo host arch, FSinfo host os, FSinfo host config, FSinfo host attributes 3136@comment node-name, next, previous, up 3137@subsection arch Option 3138@cindex FSinfo arch host attribute 3139@cindex arch, FSinfo host attribute 3140 3141This defines the architecture of the machine. For example: 3142 3143@example 3144arch = hp300 3145@end example 3146 3147This is intended to be of use when building architecture specific 3148mountmaps, however, the option is currently unsupported. 3149 3150@node FSinfo host os, FSinfo host cluster, FSinfo host arch, FSinfo host attributes 3151@comment node-name, next, previous, up 3152@subsection os Option 3153@cindex FSinfo os host attribute 3154@cindex os, FSinfo host attribute 3155 3156This defines the operating system type of the host. For example: 3157 3158@example 3159os = hpux 3160@end example 3161 3162This information is used when creating the @file{fstab} files, for 3163example in choosing which format to use for the @file{fstab} entries 3164within the file. 3165 3166@node FSinfo host cluster, , FSinfo host os, FSinfo host attributes 3167@comment node-name, next, previous, up 3168@subsection cluster Option 3169@cindex FSinfo cluster host attribute 3170@cindex cluster, FSinfo host attribute 3171 3172This is used for specifying in which cluster the machine belongs. For 3173example: 3174 3175@example 3176cluster = "theory" 3177@end example 3178 3179The cluster is intended to be used when generating the automount maps, 3180although it is currently unsupported. 3181 3182@node FSinfo filesystems, FSinfo static mounts, FSinfo host attributes, FSinfo host definitions 3183@comment node-name, next, previous, up 3184@section @i{FSinfo} filesystems 3185@cindex FSinfo filesystems 3186 3187The list of physically attached filesystems follows the machine 3188attributes. These should define all the filesystems available from this 3189machine, whether exported or not. In addition to the device name, 3190filesystems have several attributes, such as filesystem type, mount 3191options, and @samp{fsck} pass number which are needed to generate 3192@file{fstab} entries. 3193 3194@example 3195filesystem : "fs" @var{<device>} "@{" @i{list(}fs_data@i{)} "@}" ; 3196 3197fs_data : fs_data_attr "=" @var{<string>} 3198 | mount 3199 ; 3200 3201fs_data_attr 3202 : "fstype" | "opts" | "passno" 3203 | "freq" | "dumpset" | "log" 3204 ; 3205@end example 3206 3207Here, @var{<device>} is the device name of the disk (for example, 3208@file{/dev/dsk/2s0}). The device name is used for building the mount 3209maps and for the @file{fstab} file. The attributes that can be 3210specified are shown in the following section. 3211 3212The @i{FSinfo} configuration file for @code{dylan.doc.ic.ac.uk} is listed below. 3213 3214@example 3215host dylan.doc.ic.ac.uk 3216 3217fs /dev/dsk/0s0 @{ 3218 fstype = swap 3219@} 3220 3221fs /dev/dsk/0s0 @{ 3222 fstype = hfs 3223 opts = rw,noquota,grpid 3224 passno = 0; 3225 freq = 1; 3226 mount / @{ @} 3227@} 3228 3229fs /dev/dsk/1s0 @{ 3230 fstype = hfs 3231 opts = defaults 3232 passno = 1; 3233 freq = 1; 3234 mount /usr @{ 3235 local @{ 3236 exportfs "dougal eden dylan zebedee brian" 3237 volname /nfs/hp300/local 3238 @} 3239 @} 3240@} 3241 3242fs /dev/dsk/2s0 @{ 3243 fstype = hfs 3244 opts = defaults 3245 passno = 1; 3246 freq = 1; 3247 mount default @{ 3248 exportfs "toytown_clients hangers_on" 3249 volname /home/dylan/dk2 3250 @} 3251@} 3252 3253fs /dev/dsk/3s0 @{ 3254 fstype = hfs 3255 opts = defaults 3256 passno = 1; 3257 freq = 1; 3258 mount default @{ 3259 exportfs "toytown_clients hangers_on" 3260 volname /home/dylan/dk3 3261 @} 3262@} 3263 3264fs /dev/dsk/5s0 @{ 3265 fstype = hfs 3266 opts = defaults 3267 passno = 1; 3268 freq = 1; 3269 mount default @{ 3270 exportfs "toytown_clients hangers_on" 3271 volname /home/dylan/dk5 3272 @} 3273@} 3274@end example 3275 3276@menu 3277* fstype Option: FSinfo filesystems fstype: 3278* opts Option: FSinfo filesystems opts: 3279* passno Option: FSinfo filesystems passno: 3280* freq Option: FSinfo filesystems freq: 3281* mount Option: FSinfo filesystems mount: 3282* dumpset Option: FSinfo filesystems dumpset: 3283* log Option: FSinfo filesystems log: 3284@end menu 3285 3286@node FSinfo filesystems fstype, FSinfo filesystems opts, , FSinfo filesystems 3287@comment node-name, next, previous, up 3288@subsection fstype Option 3289@cindex FSinfo fstype filesystems option 3290@cindex fstype, FSinfo filesystems option 3291@cindex export, FSinfo special fstype 3292 3293This specifies the type of filesystem being declared and will be placed 3294into the @file{fstab} file as is. The value of this option will be 3295handed to @code{mount} as the filesystem type---it should have such 3296values as @code{4.2}, @code{nfs} or @code{swap}. The value is not 3297examined for correctness. 3298 3299There is one special case. If the filesystem type is specified as 3300@samp{export} then the filesystem information will not be added to the 3301host's @file{fstab} information, but it will still be visible on the 3302network. This is useful for defining hosts which contain referenced 3303volumes but which are not under full control of @i{FSinfo}. 3304 3305Example: 3306 3307@example 3308fstype = swap 3309@end example 3310 3311@node FSinfo filesystems opts, FSinfo filesystems passno,FSinfo filesystems fstype, FSinfo filesystems 3312@comment node-name, next, previous, up 3313@subsection opts Option 3314@cindex FSinfo opts filesystems option 3315@cindex opts, FSinfo filesystems option 3316 3317This defines any options that should be given to @b{mount}(8) in the 3318@file{fstab} file. For example: 3319 3320@example 3321opts = rw,nosuid,grpid 3322@end example 3323 3324@node FSinfo filesystems passno, FSinfo filesystems freq, FSinfo filesystems opts, FSinfo filesystems 3325@comment node-name, next, previous, up 3326@subsection passno Option 3327@cindex FSinfo passno filesystems option 3328@cindex passno, FSinfo filesystems option 3329 3330This defines the @b{fsck}(8) pass number in which to check the 3331filesystem. This value will be placed into the @file{fstab} file. 3332 3333Example: 3334 3335@example 3336passno = 1 3337@end example 3338 3339@node FSinfo filesystems freq, FSinfo filesystems mount, FSinfo filesystems passno, FSinfo filesystems 3340@comment node-name, next, previous, up 3341@subsection freq Option 3342@cindex FSinfo freq filesystems option 3343@cindex freq, FSinfo filesystems option 3344 3345This defines the interval (in days) between dumps. The value is placed 3346as is into the @file{fstab} file. 3347 3348Example: 3349 3350@example 3351freq = 3 3352@end example 3353 3354@node FSinfo filesystems mount, FSinfo filesystems dumpset, FSinfo filesystems freq, FSinfo filesystems 3355@comment node-name, next, previous, up 3356@subsection mount Option 3357@cindex FSinfo mount filesystems option 3358@cindex mount, FSinfo filesystems option 3359@cindex exportfs, FSinfo mount option 3360@cindex volname, FSinfo mount option 3361@cindex sel, FSinfo mount option 3362 3363This defines the mountpoint at which to place the filesystem. If the 3364mountpoint of the filesystem is specified as @code{default}, then the 3365filesystem will be mounted in the automounter's tree under its volume 3366name and the mount will automatically be inherited by the automounter. 3367 3368Following the mountpoint, namespace information for the filesystem may 3369be described. The options that can be given here are @code{exportfs}, 3370@code{volname} and @code{sel}. 3371 3372The format is: 3373 3374@example 3375mount : "mount" vol_tree ; 3376 3377vol_tree : @i{list(}vol_tree_attr@i{)} ; 3378 3379vol_tree_attr 3380 : @var{<string>} "@{" @i{list(}vol_tree_info@i{)} vol_tree "@}" ; 3381 3382vol_tree_info 3383 : "exportfs" @var{<export-data>} 3384 | "volname" @var{<volname>} 3385 | "sel" @var{<selector-list>} 3386 ; 3387@end example 3388 3389Example: 3390 3391@example 3392mount default @{ 3393 exportfs "dylan dougal florence zebedee" 3394 volname /vol/andrew 3395@} 3396@end example 3397 3398In the above example, the filesystem currently being declared will have 3399an entry placed into the @file{exports} file allowing the filesystem to 3400be exported to the machines @code{dylan}, @code{dougal}, @code{florence} 3401and @code{zebedee}. The volume name by which the filesystem will be 3402referred to remotely, is @file{/vol/andrew}. By declaring the 3403mountpoint to be @code{default}, the filesystem will be mounted on the 3404local machine in the automounter tree, where @i{Amd} will automatically 3405inherit the mount as @file{/vol/andrew}.@refill 3406 3407@table @samp 3408@item exportfs 3409a string defining which machines the filesystem may be exported to. 3410This is copied, as is, into the @file{exports} file---no sanity checking 3411is performed on this string.@refill 3412 3413@item volname 3414a string which declares the remote name by which to reference the 3415filesystem. The string is entered into a dictionary and allows you to 3416refer to this filesystem in other places by this volume name.@refill 3417 3418@item sel 3419a string which is placed into the automounter maps as a selector for the 3420filesystem.@refill 3421 3422@end table 3423 3424@node FSinfo filesystems dumpset, FSinfo filesystems log, FSinfo filesystems mount, FSinfo filesystems 3425@comment node-name, next, previous, up 3426@subsection dumpset Option 3427@cindex FSinfo dumpset filesystems option 3428@cindex dumpset, FSinfo filesystems option 3429 3430This provides support for Imperial College's local file backup tools and 3431is not documented further here. 3432 3433@node FSinfo filesystems log, , FSinfo filesystems dumpset, FSinfo filesystems 3434@comment node-name, next, previous, up 3435@subsection log Option 3436@cindex FSinfo log filesystems option 3437@cindex log, FSinfo filesystems option 3438 3439Specifies the log device for the current filesystem. This is ignored if 3440not required by the particular filesystem type. 3441 3442@node FSinfo static mounts, FSinfo automount definitions , FSinfo filesystems, FSinfo host definitions 3443@comment node-name, next, previous, up 3444@section @i{FSinfo} static mounts 3445@cindex FSinfo static mounts 3446@cindex Statically mounts filesystems, FSinfo 3447 3448Each host may also have a number of statically mounted filesystems. For 3449example, the host may be a diskless workstation in which case it will 3450have no @code{fs} declarations. In this case the @code{mount} 3451declaration is used to determine from where its filesystems will be 3452mounted. In addition to being added to the @file{fstab} file, this 3453information can also be used to generate a suitable @file{bootparams} 3454file.@refill 3455 3456@example 3457mount : "mount" @var{<volname>} @i{list(}localinfo@i{)} ; 3458 3459localinfo : localinfo_attr @var{<string>} ; 3460 3461localinfo_attr 3462 : "as" 3463 | "from" 3464 | "fstype" 3465 | "opts" 3466 ; 3467@end example 3468 3469The filesystem specified to be mounted will be searched for in the 3470dictionary of volume names built when scanning the list of hosts' 3471definitions. 3472 3473The attributes have the following semantics: 3474@table @samp 3475@item from @var{machine} 3476mount the filesystem from the machine with the hostname of 3477@dfn{machine}.@refill 3478 3479@item as @var{mountpoint} 3480mount the filesystem locally as the name given, in case this is 3481different from the advertised volume name of the filesystem. 3482 3483@item opts @var{options} 3484native @b{mount}(8) options. 3485 3486@item fstype @var{type} 3487type of filesystem to be mounted. 3488@end table 3489 3490An example: 3491 3492@example 3493mount /export/exec/hp300/local as /usr/local 3494@end example 3495 3496If the mountpoint specified is either @file{/} or @file{swap}, the 3497machine will be considered to be booting off the net and this will be 3498noted for use in generating a @file{bootparams} file for the host which 3499owns the filesystems. 3500 3501@node FSinfo automount definitions, FSinfo Command Line Options, FSinfo static mounts, FSinfo 3502@comment node-name, next, previous, up 3503@section Defining an @i{Amd} Mount Map in @i{FSinfo} 3504@cindex FSinfo automount definitions 3505@cindex Defining an Amd mount map, FSinfo 3506 3507The maps used by @i{Amd} can be constructed from @i{FSinfo} by defining 3508all the automount trees. @i{FSinfo} takes all the definitions found and 3509builds one map for each top level tree. 3510 3511The automount tree is usually defined last. A single automount 3512configuration will usually apply to an entire management domain. One 3513@code{automount} declaration is needed for each @i{Amd} automount point. 3514@i{FSinfo} determines whether the automount point is @dfn{direct} 3515(@pxref{Direct Automount Filesystem}) or @dfn{indirect} 3516(@pxref{Top-level Filesystem}). Direct automount points are 3517distinguished by the fact that there is no underlying 3518@dfn{automount_tree}.@refill 3519 3520@example 3521automount : "automount" opt(auto_opts@i{)} automount_tree ; 3522 3523auto_opts : "opts" @var{<mount-options>} ; 3524 3525automount_tree 3526 : @i{list(}automount_attr@i{)} 3527 ; 3528 3529automount_attr 3530 : @var{<string>} "=" @var{<volname>} 3531 | @var{<string>} "->" @var{<symlink>} 3532 | @var{<string>} "@{" automount_tree "@}" 3533 ; 3534@end example 3535 3536If @var{<mount-options>} is given, then it is the string to be placed in 3537the maps for @i{Amd} for the @code{opts} option. 3538 3539A @dfn{map} is typically a tree of filesystems, for example @file{home} 3540normally contains a tree of filesystems representing other machines in 3541the network. 3542 3543A map can either be given as a name representing an already defined 3544volume name, or it can be a tree. A tree is represented by placing 3545braces after the name. For example, to define a tree @file{/vol}, the 3546following map would be defined: 3547 3548@example 3549automount /vol @{ @} 3550@end example 3551 3552Within a tree, the only items that can appear are more maps. 3553For example: 3554 3555@example 3556automount /vol @{ 3557 andrew @{ @} 3558 X11 @{ @} 3559@} 3560@end example 3561 3562In this case, @i{FSinfo} will look for volumes named @file{/vol/andrew} 3563and @file{/vol/X11} and a map entry will be generated for each. If the 3564volumes are defined more than once, then @i{FSinfo} will generate 3565a series of alternate entries for them in the maps.@refill 3566 3567Instead of a tree, either a link (@var{name} @code{->} 3568@var{destination}) or a reference can be specified (@var{name} @code{=} 3569@var{destination}). A link creates a symbolic link to the string 3570specified, without further processing the entry. A reference will 3571examine the destination filesystem and optimise the reference. For 3572example, to create an entry for @code{njw} in the @file{/homes} map, 3573either of the two forms can be used:@refill 3574 3575@example 3576automount /homes @{ 3577 njw -> /home/dylan/njw 3578@} 3579@end example 3580 3581or 3582 3583@example 3584automount /homes @{ 3585 njw = /home/dylan/njw 3586@} 3587@end example 3588 3589In the first example, when @file{/homes/njw} is referenced from @i{Amd}, 3590a link will be created leading to @file{/home/dylan/njw} and the 3591automounter will be referenced a second time to resolve this filename. 3592The map entry would be: 3593 3594@example 3595njw type:=link;fs:=/home/dylan/njw 3596@end example 3597 3598In the second example, the destination directory is analysed and found 3599to be in the filesystem @file{/home/dylan} which has previously been 3600defined in the maps. Hence the map entry will look like: 3601 3602@example 3603njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw 3604@end example 3605 3606Creating only one symbolic link, and one access to @i{Amd}. 3607 3608@c --------------------------------------------- 3609@node FSinfo Command Line Options, FSinfo errors, FSinfo automount definitions, FSinfo 3610@comment node-name, next, previous, up 3611@section @i{FSinfo} Command Line Options 3612@cindex FSinfo command line options 3613@cindex Command line options, FSinfo 3614 3615@i{FSinfo} is started from the command line by using the command: 3616 3617@example 3618fsinfo [@i{options}] files ... 3619@end example 3620 3621The input to @i{FSinfo} is a single set of definitions of machines and 3622automount maps. If multiple files are given on the command-line, then 3623the files are concatenated together to form the input source. The files 3624are passed individually through the C pre-processor before being parsed. 3625 3626Several options define a prefix for the name of an output file. If the 3627prefix is not specified no output of that type is produced. The suffix 3628used will correspond either to the hostname to which a file belongs, or 3629to the type of output if only one file is produced. Dumpsets and the 3630@file{bootparams} file are in the latter class. To put the output into 3631a subdirectory simply put a @file{/} at the end of the prefix, making 3632sure that the directory has already been made before running 3633@samp{fsinfo}. 3634 3635@menu 3636* -a FSinfo Option:: Amd automount directory: 3637* -b FSinfo Option:: Prefix for bootparams files. 3638* -d FSinfo Option:: Prefix for dumpset data files. 3639* -e FSinfo Option:: Prefix for exports files. 3640* -f FSinfo Option:: Prefix for fstab files. 3641* -h FSinfo Option:: Local hostname. 3642* -m FSinfo Option:: Prefix for automount maps. 3643* -q FSinfo Option:: Ultra quiet mode. 3644* -v FSinfo Option:: Verbose mode. 3645* -I FSinfo Option:: Define new #include directory. 3646* -D-FSinfo Option:: Define macro. 3647* -U FSinfo Option:: Undefine macro. 3648@end menu 3649 3650@node -a FSinfo Option, -b FSinfo Option, FSinfo Command Line Options, FSinfo Command Line Options 3651@comment node-name, next, previous, up 3652@subsection @code{-a} @var{autodir} 3653 3654Specifies the directory name in which to place the automounter's 3655mountpoints. This defaults to @file{/a}. Some sites have the autodir set 3656to be @file{/amd}, and this would be achieved by: 3657 3658@example 3659fsinfo -a /amd ... 3660@end example 3661 3662@node -b FSinfo Option, -d FSinfo Option, -a FSinfo Option, FSinfo Command Line Options 3663@comment node-name, next, previous, up 3664@subsection @code{-b} @var{bootparams} 3665@cindex bootparams, FSinfo prefix 3666 3667This specifies the prefix for the @file{bootparams} filename. If it is 3668not given, then the file will not be generated. The @file{bootparams} 3669file will be constructed for the destination machine and will be placed 3670into a file named @file{bootparams} and prefixed by this string. The 3671file generated contains a list of entries describing each diskless 3672client that can boot from the destination machine. 3673 3674As an example, to create a @file{bootparams} file in the directory 3675@file{generic}, the following would be used: 3676 3677@example 3678fsinfo -b generic/ ... 3679@end example 3680 3681@node -d FSinfo Option, -e FSinfo Option, -b FSinfo Option, FSinfo Command Line Options 3682@comment node-name, next, previous, up 3683@subsection @code{-d} @var{dumpsets} 3684@cindex dumpset, FSinfo prefix 3685 3686This specifies the prefix for the @file{dumpsets} file. If it is not 3687specified, then the file will not be generated. The file will be for 3688the destination machine and will be placed into a filename 3689@file{dumpsets}, prefixed by this string. The @file{dumpsets} file is 3690for use by Imperial College's local backup system. 3691 3692For example, to create a dumpsets file in the directory @file{generic}, 3693then you would use the following: 3694 3695@example 3696fsinfo -d generic/ ... 3697@end example 3698 3699@node -e FSinfo Option, -f FSinfo Option, -d FSinfo Option, FSinfo Command Line Options 3700@comment node-name, next, previous, up 3701@subsection @code{-e} @var{exportfs} 3702@cindex exports, FSinfo prefix 3703 3704Defines the prefix for the @file{exports} files. If it is not given, 3705then the file will not be generated. For each machine defined in the 3706configuration files as having disks, an @file{exports} file is 3707constructed and given a filename determined by the name of the machine, 3708prefixed with this string. If a machine is defined as diskless, then no 3709@file{exports} file will be created for it. The files contain entries 3710for directories on the machine that may be exported to clients. 3711 3712Example: To create the @file{exports} files for each diskful machine 3713and place them into the directory @file{exports}: 3714 3715@example 3716fsinfo -e exports/ ... 3717@end example 3718 3719@node -f FSinfo Option, -h FSinfo Option, -e FSinfo Option, FSinfo Command Line Options 3720@comment node-name, next, previous, up 3721@subsection @code{-f} @var{fstab} 3722@cindex fstab, FSinfo prefix 3723 3724This defines the prefix for the @file{fstab} files. The files will only 3725be created if this prefix is defined. For each machine defined in the 3726configuration files, a @file{fstab} file is created with the filename 3727determined by prefixing this string with the name of the machine. These 3728files contain entries for filesystems and partitions to mount at boot 3729time. 3730 3731Example, to create the files in the directory @file{fstabs}: 3732 3733@example 3734fsinfo -f fstabs/ ... 3735@end example 3736 3737@node -h FSinfo Option, -m FSinfo Option, -f FSinfo Option, FSinfo Command Line Options 3738@comment node-name, next, previous, up 3739@subsection @code{-h} @var{hostname} 3740@cindex hostname, FSinfo command line option 3741 3742Defines the hostname of the destination machine to process for. If this 3743is not specified, it defaults to the local machine name, as returned by 3744@b{gethostname}(2). 3745 3746Example: 3747 3748@example 3749fsinfo -h dylan.doc.ic.ac.uk ... 3750@end example 3751 3752@node -m FSinfo Option, -q FSinfo Option, -h FSinfo Option, FSinfo Command Line Options 3753@comment node-name, next, previous, up 3754@subsection @code{-m} @var{mount-maps} 3755@cindex maps, FSinfo command line option 3756 3757Defines the prefix for the automounter files. The maps will only be 3758produced if this prefix is defined. The mount maps suitable for the 3759network defined by the configuration files will be placed into files 3760with names calculated by prefixing this string to the name of each map. 3761 3762For example, to create the automounter maps and place them in the 3763directory @file{automaps}: 3764 3765@example 3766fsinfo -m automaps/ ... 3767@end example 3768 3769@node -q FSinfo Option, -v FSinfo Option, -m FSinfo Option, FSinfo Command Line Options 3770@comment node-name, next, previous, up 3771@subsection @code{-q} 3772@cindex quiet, FSinfo command line option 3773 3774Selects quiet mode. @i{FSinfo} suppress the ``running commentary'' and 3775only outputs any error messages which are generated. 3776 3777@node -v FSinfo Option, -D-FSinfo Option, -q FSinfo Option, FSinfo Command Line Options 3778@comment node-name, next, previous, up 3779@subsection @code{-v} 3780@cindex verbose, FSinfo command line option 3781 3782Selects verbose mode. When this is activated, the program will display 3783more messages, and display all the information discovered when 3784performing the semantic analysis phase. Each verbose message is output 3785to @file{stdout} on a line starting with a @samp{#} character. 3786 3787@node -D-FSinfo Option, -I FSinfo Option, -v FSinfo Option, FSinfo Command Line Options 3788@comment node-name, next, previous, up 3789@subsection @code{-D} @var{name[=defn]} 3790 3791Defines a symbol @dfn{name} for the preprocessor when reading the 3792configuration files. Equivalent to @code{#define} directive. 3793 3794@node -I FSinfo Option, -U FSinfo Option, -D-FSinfo Option, FSinfo Command Line Options 3795@comment node-name, next, previous, up 3796@subsection @code{-I} @var{directory} 3797 3798This option is passed into the preprocessor for the configuration files. 3799It specifies directories in which to find include files 3800 3801@node -U FSinfo Option, , -I FSinfo Option, FSinfo Command Line Options 3802@comment node-name, next, previous, up 3803@subsection @code{-U} @var{name} 3804 3805Removes any initial definition of the symbol @dfn{name}. Inverse of the 3806@code{-D} option. 3807 3808@node FSinfo errors, , FSinfo command line options, FSinfo 3809@comment node-name, next, previous, up 3810@section Errors produced by @i{FSinfo} 3811@cindex FSinfo error messages 3812 3813The following table documents the errors and warnings which @i{FSinfo} may produce. 3814 3815@table @t 3816 3817@item can't open @var{filename} for writing 3818Occurs if any errors are encountered when opening an output file.@refill 3819 3820@item unknown host attribute 3821Occurs if an unrecognised keyword is used when defining a host.@refill 3822 3823@item unknown filesystem attribute 3824Occurs if an unrecognised keyword is used when defining a host's 3825filesystems.@refill 3826 3827@item not allowed '/' in a directory name 3828When reading the configuration input, if there is a filesystem 3829definition which contains a pathname with multiple directories for any 3830part of the mountpoint element, and it is not a single absolute path, 3831then this message will be produced by the parser.@refill 3832 3833@item unknown directory attribute 3834If an unknown keyword is found while reading the definition of a hosts's 3835filesystem mount option. 3836 3837@item unknown mount attribute 3838Occurs if an unrecognised keyword is found while parsing the list of 3839static mounts.@refill 3840 3841@item " expected 3842Occurs if an unescaped newline is found in a quoted string. 3843 3844@item unknown \ sequence 3845Occurs if an unknown escape sequence is found inside a string. Within a 3846string, you can give the standard C escape sequences for strings, such 3847as newlines and tab characters.@refill 3848 3849@item @var{filename}: cannot open for reading 3850If a file specified on the command line as containing configuration data 3851could not be opened.@refill 3852 3853@item end of file within comment 3854A comment was unterminated before the end of one of the configuration 3855files. 3856 3857@item host field "@var{field-name}" already set 3858If duplicate definitions are given for any of the fields with a host 3859definition. 3860 3861@item duplicate host @var{hostname}! 3862If a host has more than one definition. 3863 3864@item netif field @var{field-name} already set 3865Occurs if you attempt to define an attribute of an interface more than 3866once. 3867 3868@item malformed IP dotted quad: @var{address} 3869If the Internet address of an interface is incorrectly specified. An 3870Internet address definition is handled to @b{inet_addr}(3N) to see if it 3871can cope. If not, then this message will be displayed. 3872 3873@item malformed netmask: @var{netmask} 3874If the netmask cannot be decoded as though it were a hexadecimal number, 3875then this message will be displayed. It will typically be caused by 3876incorrect characters in the @var{netmask} value.@refill 3877 3878@item fs field "@var{field-name}" already set 3879Occurs when multiple definitions are given for one of the attributes of a 3880host's filesystem. 3881 3882@item mount tree field "@var{field-name}" already set 3883Occurs when the @var{field-name} is defined more than once during the 3884definition of a filesystems mountpoint. 3885 3886@item mount field "@var{field-name}" already set 3887Occurs when a static mount has multiple definitions of the same field. 3888 3889@item no disk mounts on @var{hostname} 3890If there are no static mounts, nor local disk mounts specified for a 3891machine, this message will be displayed. 3892 3893@item @var{host}:@var{device} needs field "@var{field-name}" 3894Occurs when a filesystem is missing a required field. @var{field-name} could 3895be one of @code{fstype}, @code{opts}, @code{passno} or 3896@code{mount}.@refill 3897 3898@item @var{filesystem} has a volname but no exportfs data 3899Occurs when a volume name is declared for a file system, but the string 3900specifying what machines the filesystem can be exported to is 3901missing. 3902 3903@item sub-directory @var{directory} of @var{directory-tree} starts with '/' 3904Within the filesystem specification for a host, if an element 3905@var{directory} of the mountpoint begins with a @samp{/} and it is not 3906the start of the tree.@refill 3907 3908@item @var{host}:@var{device} has no mount point 3909Occurs if the @samp{mount} option is not specified for a host's 3910filesystem.@refill 3911 3912@item @var{host}:@var{device} has more than one mount point 3913Occurs if the mount option for a host's filesystem specifies multiple 3914trees at which to place the mountpoint.@refill 3915 3916@item no volname given for @var{host}:@var{device} 3917Occurs when a filesystem is defined to be mounted on @file{default}, but 3918no volume name is given for the file system, then the mountpoint cannot 3919be determined.@refill 3920 3921@item @var{host}:mount field specified for swap partition 3922Occurs if a mountpoint is given for a filesystem whose type is declared 3923to be @code{swap}.@refill 3924 3925@item ambiguous mount: @var{volume} is a replicated filesystem 3926If several filesystems are declared as having the same volume name, they 3927will be considered replicated filesystems. To mount a replicated 3928filesystem statically, a specific host will need to be named, to say 3929which particular copy to try and mount, else this error will 3930result.@refill 3931 3932@item cannot determine localname since volname @var{volume} is not uniquely defined 3933If a volume is replicated and an attempt is made to mount the filesystem 3934statically without specifying a local mountpoint, @i{FSinfo} cannot 3935calculate a mountpoint, as the desired pathname would be 3936ambiguous.@refill 3937 3938@item volname @var{volume} is unknown 3939Occurs if an attempt is made to mount or reference a volume name which 3940has not been declared during the host filesystem definitions.@refill 3941 3942@item volname @var{volume} not exported from @var{machine} 3943Occurs if you attempt to mount the volume @var{volume} from a machine 3944which has not declared itself to have such a filesystem 3945available.@refill 3946 3947@item network booting requires both root and swap areas 3948Occurs if a machine has mount declarations for either the root partition 3949or the swap area, but not both. You cannot define a machine to only 3950partially boot via the network.@refill 3951 3952@item unknown volname @var{volume} automounted @i{[} on <name> @i{]} 3953Occurs if @var{volume} is used in a definition of an automount map but the volume 3954name has not been declared during the host filesystem definitions.@refill 3955 3956@item not allowed '/' in a directory name 3957Occurs when a pathname with multiple directory elements is specified as 3958the name for an automounter tree. A tree should only have one name at 3959each level. 3960 3961@item @var{device} has duplicate exportfs data 3962Produced if the @samp{exportfs} option is used multiple times within the 3963same branch of a filesytem definition. For example, if you attempt to 3964set the @samp{exportfs} data at different levels of the mountpoint 3965directory tree.@refill 3966 3967@item sub-directory of @var{directory-tree} is named "default" 3968@samp{default} is a keyword used to specify if a mountpoint should be 3969automatically calculated by @i{FSinfo}. If you attempt to specify a 3970directory name as this, it will use the filename of @file{default} but 3971will produce this warning.@refill 3972 3973@item pass number for @var{host}:@var{device} is non-zero 3974Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 3975or @samp{export} and the @b{fsck}(8) pass number is set. Swap devices should not be 3976fsck'd. @xref{FSinfo filesystems fstype}@refill 3977 3978@item dump frequency for @var{host}:@var{device} is non-zero 3979Occurs if @var{device} has its @samp{fstype} declared to be @samp{swap} 3980or @samp{export} and the @samp{dump} option is set to a value greater 3981than zero. Swap devices should not be dumped.@refill 3982 3983@end table 3984 3985@node Examples, Internals, FSinfo, Top 3986@comment node-name, next, previous, up 3987@chapter Examples 3988 3989@menu 3990* User Filesystems:: 3991* Home Directories:: 3992* Architecture Sharing:: 3993* Wildcard names:: 3994* rwho servers:: 3995* /vol:: 3996@end menu 3997 3998@node User Filesystems, Home Directories, Examples, Examples 3999@comment node-name, next, previous, up 4000@section User Filesystems 4001@cindex User filesystems 4002@cindex Mounting user filesystems 4003 4004With more than one fileserver, the directories most frequently 4005cross-mounted are those containing user home directories. A common 4006convention used at Imperial College is to mount the user disks under 4007@t{/home/}@i{machine}. 4008 4009Typically, the @samp{/etc/fstab} file contained a long list of entries 4010such as: 4011 4012@example 4013@i{machine}:/home/@i{machine} /home/@i{machine} nfs ... 4014@end example 4015 4016for each fileserver on the network. 4017 4018There are numerous problems with this system. The mount list can become 4019quite large and some of the machines may be down when a system is 4020booted. When a new fileserver is installed, @samp{/etc/fstab} must be 4021updated on every machine, the mount directory created and the filesystem 4022mounted. 4023 4024In many environments most people use the same few workstations, but 4025it is convenient to go to a colleague's machine and access your own 4026files. When a server goes down, it can cause a process on a client 4027machine to hang. By minimising the mounted filesystems to only include 4028those actively being used, there is less chance that a filesystem will 4029be mounted when a server goes down. 4030 4031The following is a short extract from a map taken from a research fileserver 4032at Imperial College. 4033 4034Note the entry for @samp{localhost} which is used for users such as 4035the operator (@samp{opr}) who have a home directory on most machine as 4036@samp{/home/localhost/opr}. 4037 4038@example 4039/defaults opts:=rw,intr,grpid,nosuid 4040charm host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 4041 host==$@{key@};type:=ufs;dev:=/dev/xd0g 4042# 4043... 4044 4045# 4046localhost type:=link;fs:=$@{host@} 4047... 4048# 4049# dylan has two user disks so have a 4050# top directory in which to mount them. 4051# 4052dylan type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4053# 4054dylan/dk2 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 4055 host==dylan;type:=ufs;dev:=/dev/dsk/2s0 4056# 4057dylan/dk5 host!=dylan;type:=nfs;rhost:=dylan;rfs:=/home/$@{key@} \ 4058 host==dylan;type:=ufs;dev:=/dev/dsk/5s0 4059... 4060# 4061toytown host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 4062 host==$@{key@};type:=ufs;dev:=/dev/xy1g 4063... 4064# 4065zebedee host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} \ 4066 host==$@{key@};type:=ufs;dev:=/dev/dsk/1s0 4067# 4068# Just for access... 4069# 4070gould type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4071gould/staff host!=gould;type:=nfs;rhost:=gould;rfs:=/home/$@{key@} 4072# 4073gummo host!=$@{key@};type:=nfs;rhost:=$@{key@};rfs:=/home/$@{key@} 4074... 4075@end example 4076 4077This map is shared by most of the machines listed so on those 4078systems any of the user disks is accessible via a consistent name. 4079@i{Amd} is started with the following command 4080 4081@example 4082amd /home amd.home 4083@end example 4084 4085Note that when mounting a remote filesystem, the @dfn{automounted} 4086mount point is referenced, so that the filesystem will be mounted if 4087it is not yet (at the time the remote @samp{mountd} obtains the file handle). 4088 4089@node Home Directories, Architecture Sharing, User Filesystems, Examples 4090@comment node-name, next, previous, up 4091@section Home Directories 4092@cindex Home directories 4093@cindex Example of mounting home directories 4094@cindex Mount home directories 4095 4096One convention for home directories is to locate them in @samp{/homes} 4097so user @samp{jsp}'s home directory is @samp{/homes/jsp}. With more 4098than a single fileserver it is convenient to spread user files across 4099several machines. All that is required is a mount-map which converts 4100login names to an automounted directory. 4101 4102Such a map might be started by the command: 4103 4104@example 4105amd /homes amd.homes 4106@end example 4107 4108where the map @samp{amd.homes} contained the entries: 4109 4110@example 4111/defaults type:=link # All the entries are of type:=link 4112jsp fs:=/home/charm/jsp 4113njw fs:=/home/dylan/dk5/njw 4114... 4115phjk fs:=/home/toytown/ai/phjk 4116sjv fs:=/home/ganymede/sjv 4117@end example 4118 4119Whenever a login name is accessed in @samp{/homes} a symbolic link 4120appears pointing to the real location of that user's home directory. In 4121this example, @samp{/homes/jsp} would appear to be a symbolic link 4122pointing to @samp{/home/charm/jsp}. Of course, @samp{/home} would also 4123be an automount point. 4124 4125This system causes an extra level of symbolic links to be used. 4126Although that turns out to be relatively inexpensive, an alternative is 4127to directly mount the required filesystems in the @samp{/homes} 4128map. The required map is simple, but long, and its creation is best automated. 4129The entry for @samp{jsp} could be: 4130 4131@example 4132jsp -sublink:=$@{key@};rfs:=/home/charm \ 4133 host==charm;type:=ufs;dev:=/dev/xd0g \ 4134 host!=charm;type:=nfs;rhost:=charm 4135@end example 4136 4137This map can become quite big if it contains a large number of entries. 4138By combining two other features of @i{Amd} it can be greatly simplified. 4139 4140First the UFS partitions should be mounted under the control of 4141@samp{/etc/fstab}, taking care that they are mounted in the same place 4142that @i{Amd} would have automounted them. In most cases this would be 4143something like @samp{/a/@dfn{host}/home/@dfn{host}} and 4144@samp{/etc/fstab} on host @samp{charm} would have a line:@refill 4145 4146@example 4147/dev/xy0g /a/charm/home/charm 4.2 rw,nosuid,grpid 1 5 4148@end example 4149 4150The map can then be changed to: 4151 4152@example 4153/defaults type:=nfs;sublink:=$@{key@};opts:=rw,intr,nosuid,grpid 4154jsp rhost:=charm;rfs:=/home/charm 4155njw rhost:=dylan;rfs:=/home/dylan/dk5 4156... 4157phjk rhost:=toytown;rfs:=/home/toytown;sublink:=ai/$@{key@} 4158sjv rhost:=ganymede;rfs:=/home/ganymede 4159@end example 4160 4161This map operates as usual on a remote machine (@i{ie} @code{$@{host@}} 4162not equal to @code{$@{rhost@}}). On the machine where the filesystem is 4163stored (@i{ie} @code{$@{host@}} equal to @code{$@{rhost@}}), @i{Amd} 4164will construct a local filesystem mount point which corresponds to the 4165name of the locally mounted UFS partition. If @i{Amd} is started with 4166the ``-r'' option then instead of attempting an NFS mount, @i{Amd} will 4167simply inherit the UFS mount (@pxref{Inheritance Filesystem}). If 4168``-r'' is not used then a loopback NFS mount will be made. This type of 4169mount is known to cause a deadlock on many systems. 4170 4171@node Architecture Sharing, Wildcard Names, Home Directories, Examples 4172@comment node-name, next, previous, up 4173@section Architecture Sharing 4174@cindex Architecture sharing 4175@cindex Sharing a fileserver between architectures 4176@cindex Architecture dependent volumes 4177 4178@c %At the moment some of the research machines have sets of software 4179@c %mounted in @samp{/vol}. This contains subdirectories for \TeX, 4180@c %system sources, local sources, prolog libraries and so on. 4181Often a filesystem will be shared by machines of different architectures. 4182Separate trees can be maintained for the executable images for each 4183architecture, but it may be more convenient to have a shared tree, 4184with distinct subdirectories. 4185 4186A shared tree might have the following structure on the fileserver (called 4187@samp{fserver} in the example): 4188 4189@example 4190local/tex 4191local/tex/fonts 4192local/tex/lib 4193local/tex/bin 4194local/tex/bin/sun3 4195local/tex/bin/sun4 4196local/tex/bin/hp9000 4197... 4198@end example 4199 4200In this example, the subdirectories of @samp{local/tex/bin} should be 4201hidden when accessed via the automount point (conventionally @samp{/vol}). 4202A mount-map for @samp{/vol} to achieve this would look like: 4203 4204@example 4205/defaults sublink:=$@{/key@};rhost:=fserver;type:=link 4206tex type:=auto;fs:=$@{map@};pref:=$@{key@}/ 4207tex/fonts host!=fserver;type:=nfs;rfs:=/vol/tex \ 4208 host==fserver;fs:=/usr/local/tex 4209tex/lib host!=fserver;type:=nfs;rfs:=/vol/tex \ 4210 host==fserver;fs:=/usr/local/tex 4211tex/bin -sublink:=$@{/key@}/$@{arch@} host!=fserver;type:=nfs;rfs:=/vol/tex \ 4212 host:=fserver;fs:=/usr/local/tex 4213@end example 4214 4215When @samp{/vol/tex/bin} is referenced, the current machine architecture 4216is automatically appended to the path by the @code{$@{sublink@}} 4217variable. This means that users can have @samp{/vol/tex/bin} in their 4218@samp{PATH} without concern for architecture dependencies. 4219 4220@node Wildcard Names, rwho servers, Architecture Sharing, Examples 4221@comment node-name, next, previous, up 4222@section Wildcard names & Replicated Servers 4223 4224By using the wildcard facility, @i{Amd} can @dfn{overlay} an existing 4225directory with additional entries. 4226The system files are usually mounted under @samp{/usr}. If instead 4227@i{Amd} is mounted on @samp{/usr}, additional 4228names can be overlayed to augment or replace names in the ``master'' @samp{/usr}. 4229A map to do this would have the form: 4230 4231@example 4232local type:=auto;fs:=local-map 4233share type:=auto;fs:=share-map 4234* -type:=nfs;rfs:=/export/exec/$@{arch@};sublink:="$@{key@}" \ 4235 rhost:=fserv1 rhost:=fserv2 rhost:=fserv3 4236@end example 4237 4238Note that the assignment to @code{$@{sublink@}} is surrounded by double 4239quotes to prevent the incoming key from causing the map to be 4240misinterpreted. This map has the effect of directing any access to 4241@samp{/usr/local} or @samp{/usr/share} to another automount point. 4242 4243In this example, it is assumed that the @samp{/usr} files are replicated 4244on three fileservers: @samp{fserv1}, @samp{fserv2} and @samp{fserv3}. 4245For any references other than to @samp{local} and @samp{share} one of 4246the servers is used and a symbolic link to 4247@t{$@{autodir@}/$@{rhost@}/export/exec/$@{arch@}/@i{whatever}} is 4248returned once an appropriate filesystem has been mounted.@refill 4249 4250@node rwho servers, /vol, Wildcard Names, Examples 4251@comment node-name, next, previous, up 4252@section @samp{rwho} servers 4253@cindex rwho servers 4254@cindex Architecture specific mounts 4255@cindex Example of architecture specific mounts 4256 4257The @samp{/usr/spool/rwho} directory is a good candidate for automounting. 4258For efficiency reasons it is best to capture the rwho data on a small 4259number of machines and then mount that information onto a large number 4260of clients. The data written into the rwho files is byte order dependent 4261so only servers with the correct byte ordering can be used by a client: 4262 4263@example 4264/defaults type:=nfs 4265usr/spool/rwho -byte==little;rfs:=/usr/spool/rwho \ 4266 rhost:=vaxA rhost:=vaxB \ 4267 || -rfs:=/usr/spool/rwho \ 4268 rhost:=sun4 rhost:=hp300 4269@end example 4270 4271@node /vol, , rwho servers, Examples 4272@comment node-name, next, previous, up 4273@section @samp{/vol} 4274@cindex /vol 4275@cindex Catch-all mount point 4276@cindex Generic volume name 4277 4278@samp{/vol} is used as a catch-all for volumes which do not have other 4279conventional names. 4280 4281Below is part of the @samp{/vol} map for the domain @samp{doc.ic.ac.uk}. 4282The @samp{r+d} tree is used for new or experimental software that needs 4283to be available everywhere without installing it on all the fileservers. 4284Users wishing to try out the new software then simply include 4285@samp{/vol/r+d/@{bin,ucb@}} in their path.@refill 4286 4287The main tree resides on one host @samp{gould.doc.ic.ac.uk}, which has 4288different @samp{bin}, @samp{etc}, @samp{lib} and @samp{ucb} 4289sub-directories for each machine architecture. For example, 4290@samp{/vol/r+d/bin} for a Sun-4 would be stored in the sub-directory 4291@samp{bin/sun4} of the filesystem @samp{/usr/r+d}. When it was accessed 4292a symbolic link pointing to @samp{/a/gould/usr/r+d/bin/sun4} would be 4293returned.@refill 4294 4295@example 4296/defaults type:=nfs;opts:=rw,grpid,nosuid,intr,soft 4297wp -opts:=rw,grpid,nosuid;rhost:=charm \ 4298 host==charm;type:=link;fs:=/usr/local/wp \ 4299 host!=charm;type:=nfs;rfs:=/vol/wp 4300... 4301# 4302src -opts:=rw,grpid,nosuid;rhost:=charm \ 4303 host==charm;type:=link;fs:=/usr/src \ 4304 host!=charm;type:=nfs;rfs:=/vol/src 4305# 4306r+d type:=auto;fs:=$@{map@};pref:=r+d/ 4307# per architecture bin,etc,lib&ucb... 4308r+d/bin rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 4309r+d/etc rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 4310r+d/include rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 4311r+d/lib rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 4312r+d/man rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 4313r+d/src rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@} 4314r+d/ucb rhost:=gould.doc.ic.ac.uk;rfs:=/usr/r+d;sublink:=$@{/key@}/$@{arch@} 4315# hades pictures 4316pictures -opts:=rw,grpid,nosuid;rhost:=thpfs \ 4317 host==thpfs;type:=link;fs:=/nbsd/pictures \ 4318 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=pictures 4319# hades tools 4320hades -opts:=rw,grpid,nosuid;rhost:=thpfs \ 4321 host==thpfs;type:=link;fs:=/nbsd/hades \ 4322 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=hades 4323# bsd tools for hp. 4324bsd -opts:=rw,grpid,nosuid;arch==hp9000;rhost:=thpfs \ 4325 host==thpfs;type:=link;fs:=/nbsd/bsd \ 4326 host!=thpfs;type:=nfs;rfs:=/nbsd;sublink:=bsd 4327@end example 4328 4329@node Internals, Acknowledgements & Trademarks, Examples, Top 4330@comment node-name, next, previous, up 4331@chapter Internals 4332 4333@menu 4334* Log Messages:: 4335@end menu 4336 4337@node Log Messages, , Internals, Internals 4338@comment node-name, next, previous, up 4339@section Log Messages 4340 4341In the following sections a brief explanation is given of some of the 4342log messages made by @i{Amd}. Where the message is in @samp{typewriter} 4343font, it corresponds exactly to the message produced by @i{Amd}. Words 4344in @dfn{italic} are replaced by an appropriate string. Variables, 4345@code{$@{var@}}, indicate that the value of the appropriate variable is 4346output. 4347 4348Log messages are either sent direct to a file, 4349or logged via the @b{syslog}(3) mechanism. 4350Messages are logged with facility @samp{LOG_DAEMON} when using @b{syslog}(3). 4351In either case, entries in the file are of the form: 4352@example 4353@i{date-string} @i{hostname} @t{amd[}@i{pid}@t{]} @i{message} 4354@end example 4355 4356@menu 4357* Fatal errors:: 4358* Info messages:: 4359@end menu 4360 4361@node Fatal errors, Info messages, Log Messages, Log Messages 4362@comment node-name, next, previous, up 4363@subsection Fatal errors 4364 4365@i{Amd} attempts to deal with unusual events. Whenever it is not 4366possible to deal with such an error, @i{Amd} will log an appropriate 4367message and, if it cannot possibly continue, will either exit or abort. 4368These messages are selected by @samp{-x fatal} on the command line. 4369When @b{syslog}(3) is being used, they are logged with level 4370@samp{LOG_FATAL}. Even if @i{Amd} continues to operate it is likely to 4371remain in a precarious state and should be restarted at the earliest 4372opportunity. 4373 4374@table @asis 4375@item @t{Attempting to inherit not-a-filesystem} 4376The prototype mount point created during a filesystem restart did not 4377contain a reference to the restarted filesystem. This erorr ``should 4378never happen''. 4379 4380@item @t{Can't bind to domain "@i{NIS-domain}"} 4381A specific NIS domain was requested on the command line, but no server 4382for that domain is available on the local net. 4383 4384@item @t{Can't determine IP address of this host (@i{hostname})} 4385When @i{Amd} starts it determines its own IP address. If this lookup 4386fails then @i{Amd} cannot continue. The hostname it looks up is that 4387obtained returned by @b{gethostname}(2) system call. 4388 4389@item @t{Can't find root file handle for @i{automount point}} 4390@i{Amd} creates its own file handles for the automount points. When it 4391mounts itself as a server, it must pass these file handles to the local 4392kernel. If the filehandle is not obtainable the mount point is ignored. 4393This error ``should never happen''. 4394 4395@item @t{Must be root to mount filesystems (euid = @i{euid})} 4396To prevent embarrassment, @i{Amd} makes sure it has appropriate system 4397privileges. This amounts to having an euid of 0. The check is made 4398after argument processing complete to give non-root users a chance to 4399access the ``-v'' option. 4400 4401@item @t{No work to do - quitting} 4402No automount points were given on the command line and so there is no 4403work to do. 4404 4405@item @t{Out of memory in realloc} 4406While attempting to realloc some memory, the memory space available to 4407@i{Amd} was exhausted. This is an unrecoverable error. 4408 4409@item @t{Out of memory} 4410While attempting to malloc some memory, the memory space available to 4411@i{Amd} was exhausted. This is an unrecoverable error. 4412 4413@item @t{cannot create rpc/udp service} 4414Either the NFS or AMQ endpoint could not be created. 4415 4416@item @t{gethostname:} @i{description} 4417The @b{gethostname}(2) system call failed during startup. 4418 4419@item @t{host name is not set} 4420The @b{gethostname}(2) system call returned a zero length host name. 4421This can happen if @i{Amd} is started in single user mode just after 4422booting the system. 4423 4424@item @t{ifs_match called!} 4425An internal error occurred while restarting a pre-mounted filesystem. 4426This error ``should never happen''. 4427 4428@item @t{mount_afs:} @i{description} 4429An error occured while @i{Amd} was mounting itself. 4430 4431@item @t{run_rpc failed} 4432Somehow the main NFS server loop failed. This error ``should never 4433happen''. 4434 4435@item @t{unable to free rpc arguments in amqprog_1} 4436The incoming arguments to the AMQ server could not be free'ed. 4437 4438@item @t{unable to free rpc arguments in nfs_program_1} 4439The incoming arguments to the NFS server could not be free'ed. 4440 4441@item @t{unable to register (AMQ_PROGRAM, AMQ_VERSION, udp)} 4442The AMQ server could not be registered with the local portmapper or the 4443internal RPC dispatcher. 4444 4445@item @t{unable to register (NFS_PROGRAM, NFS_VERSION, 0)} 4446The NFS server could not be registered with the internal RPC dispatcher. 4447 4448@end table 4449 4450@node Info messages, , Fatal errors, Log Messages 4451@comment node-name, next, previous, up 4452@subsection Info messages 4453 4454@i{Amd} generates information messages to record state changes. These 4455messages are selected by @samp{-x info} on the command line. When 4456@b{syslog}(3) is being used, they are logged with level @samp{LOG_INFO}. 4457 4458The messages listed below can be generated and are in a format suitable 4459for simple statistical analysis. @dfn{mount-info} is the string 4460that is displayed by @dfn{Amq} in its mount information column and 4461placed in the system mount table. 4462 4463@table @asis 4464@item @t{mount of "@t{$@{@i{path}@}}" on @t{$@{@i{fs}@}} timed out} 4465Attempts to mount a filesystem for the given automount point have failed 4466to complete within 30 seconds. 4467 4468@item @t{"@t{$@{@i{path}@}}" forcibly timed out} 4469An automount point has been timed out by the @i{Amq} command. 4470 4471@item @t{restarting @i{mount-info} on @t{$@{@i{fs}@}}} 4472A pre-mounted file system has been noted. 4473 4474@item @t{"@t{$@{@i{path}@}}" has timed out} 4475No access to the automount point has been made within the timeout 4476period. 4477 4478@item @t{file server @t{$@{@i{rhost}@}} is down - timeout of "@t{$@{@i{path}@}}" ignored} 4479An automount point has timed out, but the corresponding file server is 4480known to be down. This message is only produced once for each mount 4481point for which the server is down. 4482 4483@item @t{Re-synchronizing cache for map @t{$@{@i{map}@}}} 4484The named map has been modified and the internal cache is being re-synchronized. 4485 4486@item @t{Filehandle denied for "@t{$@{@i{rhost}@}}:@t{$@{@i{rfs}@}}"} 4487The mount daemon refused to return a file handle for the requested filesystem. 4488 4489@item @t{Filehandle error for "$@{@i{rhost}@}:$@{@i{rfs}@}":} @i{description} 4490The mount daemon gave some other error for the requested filesystem. 4491 4492@item @t{file server @t{$@{@i{rhost}@}} type nfs starts up} 4493A new NFS file server has been referenced and is known to be up. 4494 4495@item @t{file server @t{$@{@i{rhost}@}} type nfs starts down} 4496A new NFS file server has been referenced and is known to be down. 4497 4498@item @t{file server @t{$@{@i{rhost}@}} type nfs is up} 4499An NFS file server that was previously down is now up. 4500 4501@item @t{file server @t{$@{@i{rhost}@}} type nfs is down} 4502An NFS file server that was previously up is now down. 4503 4504@item @t{Finishing with status @i{exit-status}} 4505@i{Amd} is about to exit with the given exit status. 4506 4507@item @t{@i{mount-info} mounted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}}} 4508A new file system has been mounted. 4509 4510@item @t{@i{mount-info} restarted fstype @t{$@{@i{type}@}} on @t{$@{@i{fs}@}}} 4511@i{Amd} is using a pre-mounted filesystem to satisfy a mount request. 4512 4513@item @t{@i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}}} 4514A file system has been unmounted. 4515 4516@item @t{@i{mount-info} unmounted fstype @t{$@{@i{type}@}} from @t{$@{@i{fs}@}} link @t{$@{@i{fs}@}}/@t{$@{@i{sublink}@}}} 4517A file system of which only a sub-directory was in use has been unmounted. 4518 4519@end table 4520 4521@node Acknowledgements & Trademarks, Index, Internals, Top 4522@comment node-name, next, previous, up 4523@unnumbered Acknowledgements & Trademarks 4524 4525Thanks to the Formal Methods Group at Imperial College for 4526suffering patiently while @i{Amd} was being developed on their machines. 4527 4528Thanks to the many people who have helped with the development of 4529@i{Amd}, especially Piete Brooks at the Cambridge University Computing 4530Lab for many hours of testing, experimentation and discussion. 4531 4532@itemize @bullet 4533@item 4534@b{DEC}, @b{VAX} and @b{Ultrix} are registered trademarks of Digital 4535Equipment Corporation. 4536@item 4537@b{AIX} and @b{IBM} are registered trademarks of International Business 4538Machines Corporation. 4539@item 4540@b{Sun}, @b{NFS} and @b{SunOS} are registered trademarks of Sun 4541Microsystems, Inc. 4542@item 4543@b{Unix} is a registered trademark of AT&T Unix Systems Laboratories 4544in the USA and other countries. 4545@end itemize 4546 4547@node Index, Intro, Acknowledgements & Trademarks, Top 4548@comment node-name, next, previous, up 4549@unnumbered Index 4550 4551@printindex cp 4552 4553@contents 4554@bye 4555