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