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