 |
|
|
| |
1 \input texinfo @c -*-texinfo-*-
2 @c
3 @c Copyright (c) 1997-2005 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$
42 @c
43 @setfilename am-utils.info
44
45 @include version.texi
46
47 @c info directory entry
48 @dircategory Administration
49 @direntry
50 * Am-utils: (am-utils). The Amd automounter suite of utilities
51 @end direntry
52
53 @settitle Am-utils (4.4BSD Automounter Utilities)
54 @setchapternewpage odd
55
56 @titlepage
57 @title Am-utils (4.4BSD Automounter Utilities)
58 @subtitle For version @value{VERSION}, @value{UPDATED}
59
60 @author Erez Zadok
61 (Originally by Jan-Simon Pendry and Nick Williams)
62
63 @page
64 Copyright @copyright{} 1997-2005 Erez Zadok
65 @*
66 Copyright @copyright{} 1989 Jan-Simon Pendry
67 @*
68 Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine
69 @*
70 Copyright @copyright{} 1989 The Regents of the University of California.
71 @sp
72 All Rights Reserved.
73 @vskip 1ex
74 Permission to copy this document, or any portion of it, as
75 necessary for use of this software is granted provided this
76 copyright notice and statement of permission are included.
77 @end titlepage
78 @page
79
80 @c Define a new index for options.
81 @syncodeindex pg cp
82 @syncodeindex vr cp
83
84 @ifinfo
85
86 @c ################################################################
87 @node Top, License, , (DIR)
88
89 @b{Am-utils (4.4BSD Automounter Utilities) User Manual}
90 @*
91 For version @value{VERSION}, @value{UPDATED}
92
93 @b{Erez Zadok}
94 @*
95 (Originally by Jan-Simon Pendry and Nick Williams)
96
97 Copyright @copyright{} 1997-2005 Erez Zadok
98 @*
99 Copyright @copyright{} 1989 Jan-Simon Pendry
100 @*
101 Copyright @copyright{} 1989 Imperial College of Science, Technology & Medicine
102 @*
103 Copyright @copyright{} 1989 The Regents of the University of California.
104 @*
105 All Rights Reserved.
106
107 Permission to copy this document, or any portion of it, as
108 necessary for use of this software is granted provided this
109 copyright notice and statement of permission are included.
110
111 Am-utils is the 4.4BSD Automounter Tool Suite, which includes the Amd
112 automounter, the Amq query and control program, the Hlfsd daemon, and
113 other tools. This Info file describes how to use and understand the
114 tools within Am-utils.
115 @end ifinfo
116
117 @menu
118 * License:: Explains the terms and conditions for using
119 and distributing Am-utils.
120 * Distrib:: How to get the latest Am-utils distribution.
121 * AddInfo:: How to get additional information.
122 * Intro:: An introduction to Automounting concepts.
123 * History:: History of am-utils' development.
124 * Overview:: An overview of Amd.
125 * Supported Platforms:: Machines and Systems supported by Amd.
126 * Mount Maps:: Details of mount maps.
127 * Amd Command Line Options:: All the Amd command line options explained.
128 * Filesystem Types:: The different mount types supported by Amd.
129 * Amd Configuration File:: The amd.conf file syntax and meaning.
130 * Run-time Administration:: How to start, stop and control Amd.
131 * FSinfo:: The FSinfo filesystem management tool.
132 * Hlfsd:: The Home-Link Filesystem server.
133 * Assorted Tools:: Other tools which come with am-utils.
134 * Examples:: Some examples showing how Amd might be used.
135 * Internals:: Implementation details.
136 * Acknowledgments & Trademarks:: Legal Notes.
137
138 Indexes
139 * Index:: An item for each concept.
140 @end menu
141
142 @iftex
143 @unnumbered Preface
144
145 This manual documents the use of the 4.4BSD automounter tool suite,
146 which includes @i{Amd}, @i{Amq}, @i{Hlfsd}, and other programs. This is
147 primarily a reference manual. While no tutorial exists, there are
148 examples available. @xref{Examples}.
149
150 This manual comes in two forms: the published form and the Info form.
151 The Info form is for on-line perusal with the INFO program which is
152 distributed along with GNU texinfo package (a version of which is
153 available for GNU Emacs).@footnote{GNU packages can be found in
154 @url{ftp://ftp.gnu.org/pub/gnu/}.} Both forms contain substantially
155 the same text and are generated from a common source file, which is
156 distributed with the @i{Am-utils} source.
157 @end iftex
158
159 @c ################################################################
160 @node License, Distrib, Top, Top
161 @unnumbered License
162 @cindex License Information
163
164 @i{Am-utils} is not in the public domain; it is copyrighted and there are
165 restrictions on its distribution.
166
167 Redistribution and use in source and binary forms, with or without
168 modification, are permitted provided that the following conditions are
169 met:
170
171 @enumerate
172
173 @item
174 Redistributions of source code must retain the above copyright notice,
175 this list of conditions and the following disclaimer.
176
177 @item
178 Redistributions in binary form must reproduce the above copyright
179 notice, this list of conditions and the following disclaimer in the
180 documentation and/or other materials provided with the distribution.
181
182 @item
183 All advertising materials mentioning features or use of this software
184 must display the following acknowledgment:
185
186 @cartouche
187 ``This product includes software developed by the University of
188 California, Berkeley and its contributors, as well as the Trustees of
189 Columbia University.''
190 @end cartouche
191
192 @item
193 Neither the name of the University nor the names of its contributors may
194 be used to endorse or promote products derived from this software
195 without specific prior written permission.
196
197 @end enumerate
198
199 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
200 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
201 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
202 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS
203 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
204 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
205 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
206 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
207 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
208 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
209 THE POSSIBILITY OF SUCH DAMAGE.
210
211 @c ################################################################
212 @node Distrib, AddInfo, License, Top
213 @unnumbered Source Distribution
214 @cindex Source code distribution
215 @cindex Obtaining the source code
216
217 The @i{Am-utils} home page is located in
218 @example
219 @url{http://www.am-utils.org/}
220 @end example
221
222 You can get the latest distribution version of @i{Am-utils} from
223 @example
224 @url{ftp://ftp.am-utils.org/pub/am-utils/am-utils.tar.gz}
225 @end example
226
227 Additional alpha, beta, and release distributions are available in
228 @example
229 @url{ftp://ftp.am-utils.org/pub/am-utils/}.
230 @end example
231
232 Revision 5.2 was part of the 4.3BSD Reno distribution.
233
234 Revision 5.3bsdnet, a late alpha version of 5.3, was part
235 of the BSD network version 2 distribution
236
237 Revision 6.0 was made independently by
238 @email{ezk@@cs.columbia.edu,Erez Zadok} at the Computer Science
239 Department of @uref{http://www.cs.columbia.edu/,Columbia University},
240 as part of his
241 @uref{http://www.fsl.cs.sunysb.edu/docs/zadok-thesis-proposal/,PhD
242 thesis work}. Am-utils (especially version 6.1) continues to be
243 developed and maintained at the
244 @uref{http://www.cs.sunysb.edu/,Computer Science Department} of
245 @uref{http://www.stonybrook.edu/,Stony Brook University}, as a service
246 to the user community.
247
248
249 @xref{History}, for more details.
250
251 @c ################################################################
252 @node AddInfo, Intro, Distrib, Top
253 @unnumbered Getting Additional Information
254 @cindex Getting Additional Information
255
256 @unnumberedsec Bug Reports
257 @cindex Bug reports
258
259 Before reporting a bug, see if it is a known one in the
260 @uref{http://www.am-utils.org/docs/am-utils/BUGS.txt,bugs} file.
261
262 If you find a problem and hopefully you can reproduce it, please
263 describe it in detail and
264 @uref{https://bugzilla.filesystems.org/,submit a bug report} via
265 @uref{http://www.bugzilla.org/,Bugzilla}. Alternatively, you can send
266 your bug report to @email{am-utils@@am-utils.org} quoting the details
267 of the release and your configuration. These details can be obtained
268 by running the command @samp{amd -v}. It would greatly help if you
269 could provide a reproducible procedure for detecting the bug you are
270 reporting.
271
272 Providing working patches is highly encouraged. Every patch
273 incorporated, however small, will get its author an honorable mention in
274 the @uref{http://www.am-utils.org/docs/am-utils/AUTHORS.txt,authors
275 file}.
276
277 @unnumberedsec Mailing Lists
278 @cindex Mailing lists
279
280 There are several mailing lists for people interested in keeping up-to-date
281 with developments.
282
283 @c ###############
284
285 @enumerate
286
287 @item
288 The users mailing list, @samp{am-utils} is for
289
290 @itemize @minus
291 @item
292 announcements of alpha and beta releases of am-utils
293 @item
294 reporting of bugs and patches
295 @item
296 discussions of new features for am-utils
297 @item
298 implementation and porting issues
299 @end itemize
300
301 To subscribe, visit
302 @url{http://lists.am-utils.org/mailman/listinfo/am-utils}. After
303 subscribing, you can post a message to this list at
304 @email{am-utils@@am-utils.org}. To avoid as much spam as
305 possible, only subscribers to this list may post to it.
306
307 Subscribers of @samp{am-utils} are most helpful if they have the time
308 and resources to test new and development versions of amd, on as many
309 different platforms as possible. They should also be prepared to
310 learn and use the GNU Autoconf, Automake, and Libtool packages, as
311 needed; and of course, become familiar with the complex code in the
312 am-utils package. In other words, subscribers on this list should
313 hopefully be able to contribute meaningfully to the development of
314 amd.
315
316 Note that this @samp{am-utils} list used to be called @samp{amd-dev}
317 before January 1st, 2004. Please use the new name, @samp{am-utils}.
318
319 @item
320 The announcements mailing list, @samp{am-utils-announce} is for
321 announcements only (mostly new releases). To subscribe, visit
322 @url{http://lists.am-utils.org/mailman/listinfo/am-utils-announce}.
323 This list is read-only: only am-utils developers may post to it.
324
325 @item
326 We distribute nightly CVS snapshots in
327 @url{ftp://ftp.am-utils.org/pub/am-utils/snapshots/daily/}. If you
328 like to get email notices of commits to the am-utils CVS repository,
329 subscribe to the CVS logs mailing list, @samp{am-utils-cvs} at
330 @url{http://lists.am-utils.org/mailman/listinfo/am-utils-cvs}.
331
332 @item
333 The older list which was used to user discussions, @samp{amd-workers},
334 is defunct as of January 2004. (Its last address was
335 @email{amd-workers@@majordomo.glue.umd.edu}.) Don't use
336 @samp{amd-workers}: use the newer, more active @samp{am-utils} list.
337
338 @item
339 For completeness, there's a developers-only closed list called
340 @samp{am-utils-developers@@am-utils.org}.
341
342 @end enumerate
343
344 @unnumberedsec Am-utils Book
345 @cindex Am-utils book
346 @cindex Amd book
347 @cindex Automounter book
348 @cindex book
349
350 @email{ezk@@cs.sunysb.edu,Erez Zadok} wrote a
351 @uref{http://www.fsl.cs.sunysb.edu/docs/amd-book/,book}, titled @i{Linux NFS and
352 Automounter Administration}, ISBN 0-7821-2739-8, (Sybex, 2001). The
353 book is full of details and examples that go beyond what this manual
354 has. The book also covers NFS in great detail. Although the book is
355 geared toward Linux users, it is general enough for any Unix
356 administrator and contains specific sections for non-Linux systems.
357
358 @c ################################################################
359 @node Intro, History, AddInfo, Top
360 @unnumbered Introduction
361 @cindex Introduction
362
363 An @dfn{automounter} maintains a cache of mounted filesystems.
364 Filesystems are mounted on demand when they are first referenced,
365 and unmounted after a period of inactivity.
366
367 @i{Amd} may be used as a replacement for Sun's automounter. The choice
368 of which filesystem to mount can be controlled dynamically with
369 @dfn{selectors}. Selectors allow decisions of the form ``hostname is
370 @var{this},'' or ``architecture is not @var{that}.'' Selectors may be
371 combined arbitrarily. @i{Amd} also supports a variety of filesystem
372 types, including NFS, UFS and the novel @dfn{program} filesystem. The
373 combination of selectors and multiple filesystem types allows identical
374 configuration files to be used on all machines thus reducing the
375 administrative overhead.
376
377 @i{Amd} ensures that it will not hang if a remote server goes down.
378 Moreover, @i{Amd} can determine when a remote server has become
379 inaccessible and then mount replacement filesystems as and when they
380 become available.
381
382 @i{Amd} contains no proprietary source code and has been ported to
383 numerous flavors of Unix.
384
385 @c ################################################################
386 @node History, Overview, Intro, Top
387 @unnumbered History
388 @cindex History
389
390 The @i{Amd} package has been without an official maintainer since 1992.
391 Several people have stepped in to maintain it unofficially. Most
392 notable were the `upl' (Unofficial Patch Level) releases of @i{Amd},
393 created by me (@email{ezk@@cs.sunysb.edu,Erez Zadok}), and available from
394 @url{ftp://ftp.am-utils.org/pub/amd/}. The last such unofficial
395 release was `upl102'.
396
397 Through the process of patching and aging, it was becoming more and more
398 apparent that @i{Amd} was in much need of revitalizing. Maintaining
399 @i{Amd} had become a difficult task. I took it upon myself to cleanup
400 the code, so that it would be easier to port to new platforms, add new
401 features, keep up with the many new feature requests, and deal with the
402 never ending stream of bug reports.
403
404 I have been working on such a release of @i{Amd} on and off since
405 January of 1996. The new suite of tools is currently named "am-utils"
406 (AutoMounter Utilities), in line with GNU naming conventions, befitting
407 the contents of the package. In October of 1996 I had received enough
408 offers to help me with this task that I decided to make a mailing list
409 for this group of people. Around the same time, @i{Amd} had become a
410 necessary part of my PhD thesis work, resulting in more work performed
411 on am-utils.
412
413 Am-utils version 6.0 was numbered with a major new release number to
414 distinguish it from the last official release of @i{Amd} (5.x). Many
415 new features have been added such as a GNU @code{configure} system, NFS
416 Version 3, a run-time configuration file (`amd.conf'), many new ports,
417 more scripts and programs, as well as numerous bug fixes. Another
418 reason for the new major release number was to alert users of am-utils
419 that user-visible interfaces may have changed. In order to make @i{Amd}
420 work well for the next 10 years, and be easier to maintain, it was
421 necessary to remove old or unused features, change various syntax files,
422 etc. However, great care was taken to ensure the maximum possible
423 backwards compatibility.
424
425 Am-utils version 6.1 has autofs support for Linux and Solaris 2.5+ as
426 @i{the} major new feature, in addition to several other minor new
427 features. The autofs support is completely transparent to the
428 end-user, aside from the fact that @code{/bin/pwd} now always returns
429 the correct amd-ified path. The administrator can easily switch
430 between NFS and autofs mounts by changing one parameter in
431 @code{amd.conf}. Autofs support and maintenance was developed in
432 conjunction with @email{ionut@@badula.org,Ion Badulescu}.
433
434 @c ################################################################
435 @node Overview, Supported Platforms, History, Top
436 @chapter Overview
437
438 @i{Amd} maintains a cache of mounted filesystems. Filesystems are
439 @dfn{demand-mounted} when they are first referenced, and unmounted after
440 a period of inactivity. @i{Amd} may be used as a replacement for Sun's
441 @b{automount}(8) program. It contains no proprietary source code and
442 has been ported to numerous flavors of Unix. @xref{Supported
443 Platforms}.@refill
444
445 @i{Amd} was designed as the basis for experimenting with filesystem
446 layout and management. Although @i{Amd} has many direct applications it
447 is loaded with additional features which have little practical use. At
448 some point the infrequently used components may be removed to streamline
449 the production system.
450
451 @i{Amd} supports the notion of @dfn{replicated} filesystems by evaluating
452 each member of a list of possible filesystem locations one by one.
453 @i{Amd} checks that each cached mapping remains valid. Should a mapping be
454 lost -- such as happens when a fileserver goes down -- @i{Amd} automatically
455 selects a replacement should one be available.
456
457 @menu
458 * Fundamentals::
459 * Filesystems and Volumes::
460 * Volume Naming::
461 * Volume Binding::
462 * Operational Principles::
463 * Mounting a Volume::
464 * Automatic Unmounting::
465 * Keep-alives::
466 * Non-blocking Operation::
467 @end menu
468
469 @node Fundamentals, Filesystems and Volumes, Overview, Overview
470 @comment node-name, next, previous, up
471 @section Fundamentals
472 @cindex Automounter fundamentals
473
474 The fundamental concept behind @i{Amd} is the ability to separate the
475 name used to refer to a file from the name used to refer to its physical
476 storage location. This allows the same files to be accessed with the
477 same name regardless of where in the network the name is used. This is
478 very different from placing @file{/n/hostname} in front of the pathname
479 since that includes location dependent information which may change if
480 files are moved to another machine.
481
482 By placing the required mappings in a centrally administered database,
483 filesystems can be re-organized without requiring changes to
484 configuration files, shell scripts and so on.
485
486 @node Filesystems and Volumes, Volume Naming, Fundamentals, Overview
487 @comment node-name, next, previous, up
488 @section Filesystems and Volumes
489 @cindex Filesystem
490 @cindex Volume
491 @cindex Fileserver
492 @cindex sublink
493
494 @i{Amd} views the world as a set of fileservers, each containing one or
495 more filesystems where each filesystem contains one or more
496 @dfn{volumes}. Here the term @dfn{volume} is used to refer to a
497 coherent set of files such as a user's home directory or a @TeX{}
498 distribution.@refill
499
500 In order to access the contents of a volume, @i{Amd} must be told in
501 which filesystem the volume resides and which host owns the filesystem.
502 By default the host is assumed to be local and the volume is assumed to
503 be the entire filesystem. If a filesystem contains more than one
504 volume, then a @dfn{sublink} is used to refer to the sub-directory
505 within the filesystem where the volume can be found.
506
507 @node Volume Naming, Volume Binding, Filesystems and Volumes, Overview
508 @comment node-name, next, previous, up
509 @section Volume Naming
510 @cindex Volume names
511 @cindex Network-wide naming
512 @cindex Replicated volumes
513 @cindex Duplicated volumes
514 @cindex Replacement volumes
515
516 Volume names are defined to be unique across the entire network. A
517 volume name is the pathname to the volume's root as known by the users
518 of that volume. Since this name uniquely identifies the volume
519 contents, all volumes can be named and accessed from each host, subject
520 to administrative controls.
521
522 Volumes may be replicated or duplicated. Replicated volumes contain
523 identical copies of the same data and reside at two or more locations in
524 the network. Each of the replicated volumes can be used
525 interchangeably. Duplicated volumes each have the same name but contain
526 different, though functionally identical, data. For example,
527 @samp{/vol/tex} might be the name of a @TeX{} distribution which varied
528 for each machine architecture.@refill
529
530 @i{Amd} provides facilities to take advantage of both replicated and
531 duplicated volumes. Configuration options allow a single set of
532 configuration data to be shared across an entire network by taking
533 advantage of replicated and duplicated volumes.
534
535 @i{Amd} can take advantage of replacement volumes by mounting them as
536 required should an active fileserver become unavailable.
537
538 @node Volume Binding, Operational Principles, Volume Naming, Overview
539 @comment node-name, next, previous, up
540 @section Volume Binding
541 @cindex Volume binding
542 @cindex Unix namespace
543 @cindex Namespace
544 @cindex Binding names to filesystems
545
546 Unix implements a namespace of hierarchically mounted filesystems. Two
547 forms of binding between names and files are provided. A @dfn{hard
548 link} completes the binding when the name is added to the filesystem. A
549 @dfn{soft link} delays the binding until the name is accessed. An
550 @dfn{automounter} adds a further form in which the binding of name to
551 filesystem is delayed until the name is accessed.@refill
552
553 The target volume, in its general form, is a tuple (host, filesystem,
554 sublink) which can be used to name the physical location of any volume
555 in the network.
556
557 When a target is referenced, @i{Amd} ignores the sublink element and
558 determines whether the required filesystem is already mounted. This is
559 done by computing the local mount point for the filesystem and checking
560 for an existing filesystem mounted at the same place. If such a
561 filesystem already exists then it is assumed to be functionally
562 identical to the target filesystem. By default there is a one-to-one
563 mapping between the pair (host, filesystem) and the local mount point so
564 this assumption is valid.
565
566 @node Operational Principles, Mounting a Volume, Volume Binding, Overview
567 @comment node-name, next, previous, up
568 @section Operational Principles
569 @cindex Operational principles
570
571 @i{Amd} operates by introducing new mount points into the namespace.
572 These are called @dfn{automount} points. The kernel sees these
573 automount points as NFS filesystems being served by @i{Amd}. Having
574 attached itself to the namespace, @i{Amd} is now able to control the
575 view the rest of the system has of those mount points. RPC calls are
576 received from the kernel one at a time.
577
578 When a @dfn{lookup} call is received @i{Amd} checks whether the name is
579 already known. If it is not, the required volume is mounted. A
580 symbolic link pointing to the volume root is then returned. Once the
581 symbolic link is returned, the kernel will send all other requests
582 direct to the mounted filesystem.
583
584 If a volume is not yet mounted, @i{Amd} consults a configuration
585 @dfn{mount-map} corresponding to the automount point. @i{Amd} then
586 makes a runtime decision on what and where to mount a filesystem based
587 on the information obtained from the map.
588
589 @i{Amd} does not implement all the NFS requests; only those relevant
590 to name binding such as @dfn{lookup}, @dfn{readlink} and @dfn{readdir}.
591 Some other calls are also implemented but most simply return an error
592 code; for example @dfn{mkdir} always returns ``read-only filesystem''.
593
594 @node Mounting a Volume, Automatic Unmounting, Operational Principles, Overview
595 @comment node-name, next, previous, up
596 @section Mounting a Volume
597 @cindex Mounting a volume
598 @cindex Location lists
599 @cindex Alternate locations
600 @cindex Mount retries
601 @cindex Background mounts
602
603 Each automount point has a corresponding mount map. The mount map
604 contains a list of key--value pairs. The key is the name of the volume
605 to be mounted. The value is a list of locations describing where the
606 filesystem is stored in the network. In the source for the map the
607 value would look like
608
609 @display
610 location1 location2 @dots{} locationN
611 @end display
612
613 @i{Amd} examines each location in turn. Each location may contain
614 @dfn{selectors} which control whether @i{Amd} can use that location.
615 For example, the location may be restricted to use by certain hosts.
616 Those locations which cannot be used are ignored.
617
618 @i{Amd} attempts to mount the filesystem described by each remaining
619 location until a mount succeeds or @i{Amd} can no longer proceed. The
620 latter can occur in three ways:
621
622 @itemize @bullet
623 @item
624 If none of the locations could be used, or if all of the locations
625 caused an error, then the last error is returned.
626
627 @item
628 If a location could be used but was being mounted in the background then
629 @i{Amd} marks that mount as being ``in progress'' and continues with
630 the next request; no reply is sent to the kernel.
631
632 @item
633 Lastly, one or more of the mounts may have been @dfn{deferred}. A mount
634 is deferred if extra information is required before the mount can
635 proceed. When the information becomes available the mount will take
636 place, but in the mean time no reply is sent to the kernel. If the
637 mount is deferred, @i{Amd} continues to try any remaining locations.
638 @end itemize
639
640 Once a volume has been mounted, @i{Amd} establishes a @dfn{volume
641 mapping} which is used to satisfy subsequent requests.@refill
642
643 @node Automatic Unmounting, Keep-alives, Mounting a Volume, Overview
644 @comment node-name, next, previous, up
645 @section Automatic Unmounting
646
647 To avoid an ever increasing number of filesystem mounts, @i{Amd} removes
648 volume mappings which have not been used recently. A time-to-live
649 interval is associated with each mapping and when that expires the
650 mapping is removed. When the last reference to a filesystem is removed,
651 that filesystem is unmounted. If the unmount fails, for example the
652 filesystem is still busy, the mapping is re-instated and its
653 time-to-live interval is extended. The global default for this grace
654 period is controlled by the @code{-w} command-line option (@pxref{-w
655 Option, -w}) or the @i{amd.conf} parameter @samp{dismount_interval}
656 (@pxref{dismount_interval Parameter}). It is also possible to set this
657 value on a per-mount basis (@pxref{opts Option, opts, opts}).
658
659 Filesystems can be forcefully timed out using the @i{Amq} command.
660 @xref{Run-time Administration}. Note that on new enough systems that
661 support forced unmounts, such as Linux, @i{Amd} can try to use the
662 @b{umount2}(2) system call to force the unmount, if the regular
663 @b{umount}(2) system call failed in a way that indicates that the
664 mount point is hung or stale. @xref{forced_unmounts Parameter}.
665
666 @node Keep-alives, Non-blocking Operation, Automatic Unmounting, Overview
667 @comment node-name, next, previous, up
668 @section Keep-alives
669 @cindex Keep-alives
670 @cindex Server crashes
671 @cindex NFS ping
672
673 Use of some filesystem types requires the presence of a server on
674 another machine. If a machine crashes then it is of no concern to
675 processes on that machine that the filesystem is unavailable. However,
676 to processes on a remote host using that machine as a fileserver this
677 event is important. This situation is most widely recognized when an
678 NFS server crashes and the behavior observed on client machines is that
679 more and more processes hang. In order to provide the possibility of
680 recovery, @i{Amd} implements a @dfn{keep-alive} interval timer for some
681 filesystem types. Currently only NFS makes use of this service.
682
683 The basis of the NFS keep-alive implementation is the observation that
684 most sites maintain replicated copies of common system data such as
685 manual pages, most or all programs, system source code and so on. If
686 one of those servers goes down it would be reasonable to mount one of
687 the others as a replacement.
688
689 The first part of the process is to keep track of which fileservers are
690 up and which are down. @i{Amd} does this by sending RPC requests to the
691 servers' NFS @code{NullProc} and checking whether a reply is returned.
692 While the server state is uncertain the requests are re-transmitted at
693 three second intervals and if no reply is received after four attempts
694 the server is marked down. If a reply is received the fileserver is
695 marked up and stays in that state for 30 seconds at which time another
696 NFS ping is sent. This interval is configurable and can even be
697 turned off using the @i{ping} option. @xref{opts Option}.
698
699 Once a fileserver is marked down, requests continue to be sent every 30
700 seconds in order to determine when the fileserver comes back up. During
701 this time any reference through @i{Amd} to the filesystems on that
702 server fail with the error ``Operation would block''. If a replacement
703 volume is available then it will be mounted, otherwise the error is
704 returned to the user.
705
706 @c @i{Amd} keeps track of which servers are up and which are down.
707 @c It does this by sending RPC requests to the servers' NFS {\sc NullProc} and
708 @c checking whether a reply is returned. If no replies are received after a
709 @c short period, @i{Amd} marks the fileserver @dfn{down}.
710 @c RPC requests continue to be sent so that it will notice when a fileserver
711 @c comes back up.
712 @c ICMP echo packets \cite{rfc:icmp} are not used because it is the availability
713 @c of the NFS service that is important, not the existence of a base kernel.
714 @c Whenever a reference to a fileserver which is down is made via @i{Amd}, an alternate
715 @c filesystem is mounted if one is available.
716 @c
717 Although this action does not protect user files, which are unique on
718 the network, or processes which do not access files via @i{Amd} or
719 already have open files on the hung filesystem, it can prevent most new
720 processes from hanging.
721 @c
722 @c With a suitable combination of filesystem management and mount-maps,
723 @c machines can be protected against most server downtime. This can be
724 @c enhanced by allocating boot-servers dynamically which allows a diskless
725 @c workstation to be quickly restarted if necessary. Once the root filesystem
726 @c is mounted, @i{Amd} can be started and allowed to mount the remainder of
727 @c the filesystem from whichever fileservers are available.
728
729 @node Non-blocking Operation, , Keep-alives, Overview
730 @comment node-name, next, previous, up
731 @section Non-blocking Operation
732 @cindex Non-blocking operation
733 @cindex Multiple-threaded server
734 @cindex RPC retries
735
736 Since there is only one instance of @i{Amd} for each automount point,
737 and usually only one instance on each machine, it is important that it
738 is always available to service kernel calls. @i{Amd} goes to great
739 lengths to ensure that it does not block in a system call. As a last
740 resort @i{Amd} will fork before it attempts a system call that may block
741 indefinitely, such as mounting an NFS filesystem. Other tasks such as
742 obtaining filehandle information for an NFS filesystem, are done using a
743 purpose built non-blocking RPC library which is integrated with
744 @i{Amd}'s task scheduler. This library is also used to implement NFS
745 keep-alives (@pxref{Keep-alives}).
746
747 Whenever a mount is deferred or backgrounded, @i{Amd} must wait for it
748 to complete before replying to the kernel. However, this would cause
749 @i{Amd} to block waiting for a reply to be constructed. Rather than do
750 this, @i{Amd} simply @dfn{drops} the call under the assumption that the
751 kernel RPC mechanism will automatically retry the request.
752
753 @c ################################################################
754 @node Supported Platforms, Mount Maps, Overview, Top
755 @comment node-name, next, previous, up
756 @chapter Supported Platforms
757 @cindex Supported Platforms
758 @cindex shared libraries
759 @cindex NFS V.3 support
760
761 @i{Am-utils} has been ported to a wide variety of machines and operating
762 systems. @i{Am-utils}'s code works for little-endian and big-endian
763 machines, as well as 32 bit and 64 bit architectures. Furthermore, when
764 @i{Am-utils} ports to an Operating System on one architecture, it is generally
765 readily portable to the same Operating System on all platforms on which
766 it is available.
767
768 See the @file{INSTALL} in the distribution for more specific details on
769 building and/or configuring for some systems.
770
771 @c ################################################################
772 @node Mount Maps, Amd Command Line Options, Supported Platforms, Top
773 @comment node-name, next, previous, up
774 @chapter Mount Maps
775 @cindex Mount maps
776 @cindex Automounter configuration maps
777 @cindex Mount information
778
779 @i{Amd} has no built-in knowledge of machines or filesystems.
780 External @dfn{mount-maps} are used to provide the required information.
781 Specifically, @i{Amd} needs to know when and under what conditions it
782 should mount filesystems.
783
784 The map entry corresponding to the requested name contains a list of
785 possible locations from which to resolve the request. Each location
786 specifies filesystem type, information required by that filesystem (for
787 example the block special device in the case of UFS), and some
788 information describing where to mount the filesystem (@pxref{fs Option}). A
789 location may also contain @dfn{selectors} (@pxref{Selectors}).@refill
790
791 @menu
792 * Map Types::
793 * Key Lookup::
794 * Location Format::
795 @end menu
796
797 @node Map Types, Key Lookup, Mount Maps, Mount Maps
798 @comment node-name, next, previous, up
799 @section Map Types
800 @cindex Mount map types
801 @cindex Map types
802 @cindex Configuration map types
803 @cindex Types of mount map
804 @cindex Types of configuration map
805 @cindex Determining the map type
806
807 A mount-map provides the run-time configuration information to @i{Amd}.
808 Maps can be implemented in many ways. Some of the forms supported by
809 @i{Amd} are regular files, ndbm databases, NIS maps, the @dfn{Hesiod}
810 name server, and even the password file.
811
812 A mount-map @dfn{name} is a sequence of characters. When an automount
813 point is created a handle on the mount-map is obtained. For each map
814 type configured, @i{Amd} attempts to reference the map of the
815 appropriate type. If a map is found, @i{Amd} notes the type for future
816 use and deletes the reference, for example closing any open file
817 descriptors. The available maps are configured when @i{Amd} is built
818 and can be displayed by running the command @samp{amd -v}.
819
820 When using an @i{Amd} configuration file (@pxref{Amd Configuration File})
821 and the keyword @samp{map_type} (@pxref{map_type Parameter}), you may
822 force the map used to any type.
823
824 By default, @i{Amd} caches data in a mode dependent on the type of map.
825 This is the same as specifying @samp{cache:=mapdefault} and selects a
826 suitable default cache mode depending on the map type. The individual
827 defaults are described below. The @var{cache} option can be specified
828 on automount points to alter the caching behavior (@pxref{Automount
829 Filesystem}).@refill
830
831 The following map types have been implemented, though some are not
832 available on all machines. Run the command @samp{amd -v} to obtain a
833 list of map types configured on your machine.
834
835 @menu
836 * File maps::
837 * ndbm maps::
838 * NIS maps::
839 * NIS+ maps::
840 * Hesiod maps::
841 * Password maps::
842 * Union maps::
843 * LDAP maps::
844 * Executable maps::
845 @end menu
846
847 @c ----------------------------------------------------------------
848 @node File maps, ndbm maps, Map Types, Map Types
849 @comment node-name, next, previous, up
850 @subsection File maps
851 @cindex File maps
852 @cindex Flat file maps
853 @cindex File map syntactic conventions
854
855 When @i{Amd} searches a file for a map entry it does a simple scan of
856 the file and supports both comments and continuation lines.
857
858 Continuation lines are indicated by a backslash character (@samp{\}) as
859 the last character of a line in the file. The backslash, newline character
860 @emph{and any leading white space on the following line} are discarded. A maximum
861 line length of 2047 characters is enforced after continuation lines are read
862 but before comments are stripped. Each line must end with
863 a newline character; that is newlines are terminators, not separators.
864 The following examples illustrate this:
865
866 @example
867 key valA valB; \
868 valC
869 @end example
870
871 specifies @emph{three} locations, and is identical to
872
873 @example
874 key valA valB; valC
875 @end example
876
877 However,
878
879 @example
880 key valA valB;\
881 valC
882 @end example
883
884 specifies only @emph{two} locations, and is identical to
885
886 @example
887 key valA valB;valC
888 @end example
889
890 After a complete line has been read from the file, including
891 continuations, @i{Amd} determines whether there is a comment on the
892 line. A comment begins with a hash (``@samp{#}'') character and
893 continues to the end of the line. There is no way to escape or change
894 the comment lead-in character.
895
896 Note that continuation lines and comment support @dfn{only} apply to
897 file maps, or ndbm maps built with the @code{mk-amd-map} program.
898
899 When caching is enabled, file maps have a default cache mode of
900 @code{all} (@pxref{Automount Filesystem}).
901
902 @c ----------------------------------------------------------------
903 @node ndbm maps, NIS maps, File maps, Map Types
904 @comment node-name, next, previous, up
905 @subsection ndbm maps
906 @cindex ndbm maps
907
908 An ndbm map may be used as a fast access form of a file map. The program,
909 @code{mk-amd-map}, converts a normal map file into an ndbm database.
910 This program supports the same continuation and comment conventions that
911 are provided for file maps. Note that ndbm format files may @emph{not}
912 be sharable across machine architectures. The notion of speed generally
913 only applies to large maps; a small map, less than a single disk block,
914 is almost certainly better implemented as a file map.
915
916 ndbm maps have a default cache mode of @samp{all}
917 (@pxref{Automount Filesystem}).
918
919 @c ----------------------------------------------------------------
920 @node NIS maps, NIS+ maps, ndbm maps, Map Types
921 @comment node-name, next, previous, up
922 @subsection NIS maps
923 @cindex NIS (YP) maps
924
925 When using NIS (formerly YP), an @i{Amd} map is implemented directly
926 by the underlying NIS map. Comments and continuation lines are
927 @emph{not} supported in the automounter and must be stripped when
928 constructing the NIS server's database.
929
930 NIS maps have a default cache mode of @code{all} (@pxref{Automount
931 Filesystem}).
932
933 The following rule illustrates what could be added to your NIS @file{Makefile},
934 in this case causing the @file{amd.home} map to be rebuilt:
935 @example
936 $(YPTSDIR)/amd.home.time: $(ETCDIR)/amd.home
937 -@@sed -e "s/#.*$$//" -e "/^$$/d" $(ETCDIR)/amd.home | \
938 awk '@{ \
939 for (i = 1; i <= NF; i++) \
940 if (i == NF) @{ \
941 if (substr($$i, length($$i), 1) == "\\") \
942 printf("%s", substr($$i, 1, length($$i) - 1)); \
943 else \
944 printf("%s\n", $$i); \
945 @} \
946 else \
947 printf("%s ", $$i); \
948 @}' | \
949 $(MAKEDBM) - $(YPDBDIR)/amd.home; \
950 touch $(YPTSDIR)/amd.home.time; \
951 echo "updated amd.home"; \
952 if [ ! $(NOPUSH) ]; then \
953 $(YPPUSH) amd.home; \
954 echo "pushed amd.home"; \
955 else \
956 : ; \
957 fi
958 @end example
959
960 Here @code{$(YPTSDIR)} contains the time stamp files, and
961 @code{$(YPDBDIR)} contains the dbm format NIS files.
962
963 @c ----------------------------------------------------------------
964 @node NIS+ maps, Hesiod maps, NIS maps, Map Types
965 @comment node-name, next, previous, up
966 @subsection NIS+ maps
967 @cindex NIS+ maps
968
969 NIS+ maps do not support cache mode @samp{all} and, when caching is
970 enabled, have a default cache mode of @samp{inc}.
971
972 XXX: FILL IN WITH AN EXAMPLE.
973
974 @c ----------------------------------------------------------------
975 @node Hesiod maps, Password maps, NIS+ maps, Map Types
976 @comment node-name, next, previous, up
977 @subsection Hesiod maps
978 @cindex Hesiod maps
979
980 When the map name begins with the string @samp{hesiod.} lookups are made
981 using the @dfn{Hesiod} name server. The string following the dot is
982 used as a name qualifier and is prepended with the key being located.
983 The entire string is then resolved in the @code{automount} context, or
984 the @i{amd.conf} parameter @samp{hesiod_base} (@pxref{hesiod_base
985 Parameter}). For example, if the key is @samp{jsp} and map name is
986 @samp{hesiod.homes} then @dfn{Hesiod} is asked to resolve
987 @samp{jsp.homes.automount}.
988
989 Hesiod maps do not support cache mode @samp{all} and, when caching is
990 enabled, have a default cache mode of @samp{inc} (@pxref{Automount
991 Filesystem}).
992
993 The following is an example of a @dfn{Hesiod} map entry:
994
995 @example
996 jsp.homes.automount HS TXT "rfs:=/home/charm;rhost:=charm;sublink:=jsp"
997 njw.homes.automount HS TXT "rfs:=/home/dylan/dk2;rhost:=dylan;sublink:=njw"
998 @end example
999
1000 @c ----------------------------------------------------------------
1001 @node Password maps, Union maps, Hesiod maps, Map Types
1002 @comment node-name, next, previous, up
1003 @subsection Password maps
1004 @cindex Password file maps
1005 @cindex /etc/passwd maps
1006 @cindex User maps, automatic generation
1007 @cindex Automatic generation of user maps
1008 @cindex Using the password file as a map
1009
1010 The password map support is unlike the four previous map types. When
1011 the map name is the string @file{/etc/passwd} @i{Amd} can lookup a user
1012 name in the password file and re-arrange the home directory field to
1013 produce a usable map entry.
1014
1015 @i{Amd} assumes the home directory has the format
1016 `@t{/}@i{anydir}@t{/}@i{dom1}@t{/../}@i{domN}@t{/}@i{login}'.
1017 @c @footnote{This interpretation is not necessarily exactly what you want.}
1018 It breaks this string into a map entry where @code{$@{rfs@}} has the
1019 value `@t{/}@i{anydir}@t{/}@i{domN}', @code{$@{rhost@}} has the value
1020 `@i{domN}@t{.}@i{...}@t{.}@i{dom1}', and @code{$@{sublink@}} has the
1021 value @i{login}.@refill
1022
1023 Thus if the password file entry was
1024
1025 @example
1026 /home/achilles/jsp
1027 @end example
1028
1029 the map entry used by @i{Amd} would be
1030
1031 @example
1032 rfs:=/home/achilles;rhost:=achilles;sublink:=jsp
1033 @end example
1034
1035 Similarly, if the password file entry was
1036
1037 @example
1038 /home/cc/sugar/mjh
1039 @end example
1040
1041 the map entry used by @i{Amd} would be
1042
1043 @example
1044 rfs:=/home/sugar;rhost:=sugar.cc;sublink:=jsp
1045 @end example
1046
1047 @c ----------------------------------------------------------------
1048 @node Union maps, LDAP maps, Password maps, Map Types
1049 @comment node-name, next, previous, up
1050 @subsection Union maps
1051 @cindex Union file maps
1052
1053 The union map support is provided specifically for use with the union
1054 filesystem, @pxref{Union Filesystem}.
1055
1056 It is identified by the string @samp{union:} which is followed by a
1057 colon separated list of directories. The directories are read in order,
1058 and the names of all entries are recorded in the map cache. Later
1059 directories take precedence over earlier ones. The union filesystem
1060 type then uses the map cache to determine the union of the names in all
1061 the directories.
1062
1063 @c ----------------------------------------------------------------
1064 @node LDAP maps, Executable maps, Union maps, Map Types
1065 @comment node-name, next, previous, up
1066 @subsection LDAP maps
1067 @cindex LDAP maps
1068 @cindex Lightweight Directory Access Protocol
1069
1070 LDAP (Lightweight Directory Access Protocol) maps do not support cache
1071 mode @samp{all} and, when caching is enabled, have a default cache mode
1072 of @samp{inc}.
1073
1074 For example, an @i{Amd} map @samp{amd.home} that looks as follows:
1075
1076 @example
1077 /defaults opts:=rw,intr;type:=link
1078
1079 zing -rhost:=shekel \
1080 host==shekel \
1081 host!=shekel;type:=nfs
1082 @end example
1083 @noindent
1084 when converted to LDAP (@pxref{amd2ldif}), will result in the following
1085 LDAP database:
1086 @example
1087 $ amd2ldif amd.home CUCS < amd.home
1088 dn: cn=amdmap timestamp, CUCS
1089 cn : amdmap timestamp
1090 objectClass : amdmapTimestamp
1091 amdmapTimestamp: 873071363
1092
1093 dn: cn=amdmap amd.home[/defaults], CUCS
1094 cn : amdmap amd.home[/defaults]
1095 objectClass : amdmap
1096 amdmapName : amd.home
1097 amdmapKey : /defaults
1098 amdmapValue : opts:=rw,intr;type:=link
1099
1100 dn: cn=amdmap amd.home[], CUCS
1101 cn : amdmap amd.home[]
1102 objectClass : amdmap
1103 amdmapName : amd.home
1104 amdmapKey :
1105 amdmapValue :
1106
1107 dn: cn=amdmap amd.home[zing], CUCS
1108 cn : amdmap amd.home[zing]
1109 objectClass : amdmap
1110 amdmapName : amd.home
1111 amdmapKey : zing
1112 amdmapValue : -rhost:=shekel host==shekel host!=shekel;type:=nfs
1113 @end example
1114
1115 @c ----------------------------------------------------------------
1116 @node Executable maps, , LDAP maps, Map Types
1117 @comment node-name, next, previous, up
1118 @subsection Executable maps
1119 @cindex Executable maps
1120
1121 An executable map is a dynamic map in which the keys and values for
1122 the maps are generated on the fly by a program or script. The program
1123 is expected to take a single parameter argument which is the key to
1124 lookup. If the key is found, the program should print on stdout the
1125 key-value pair that were found; if the key was not found, nothing
1126 should be printed out. Below is an sample of such a map script:
1127
1128 @example
1129 #!/bin/sh
1130 # execuatable map example
1131 case "$1" in
1132 "/defaults" )
1133 echo "/defaults type:=nfs;rfs:=filer"
1134 ;;
1135 "a" )
1136 echo "a type:=nfs;fs:=/tmp"
1137 ;;
1138 "b" )
1139 echo "b type:=link;fs:=/usr/local"
1140 ;;
1141 * ) # no match, echo nothing
1142 ;;
1143 esac
1144 @end example
1145
1146 @xref{exec_map_timeout Parameter}.
1147
1148 @c ----------------------------------------------------------------
1149 @c subsection Gdbm
1150 @c ----------------------------------------------------------------
1151 @node Key Lookup, Location Format, Map Types, Mount Maps
1152 @comment node-name, next, previous, up
1153 @section How keys are looked up
1154 @cindex Key lookup
1155 @cindex Map lookup
1156 @cindex Looking up keys
1157 @cindex How keys are looked up
1158 @cindex Wildcards in maps
1159
1160 The key is located in the map whose type was determined when the
1161 automount point was first created. In general the key is a pathname
1162 component. In some circumstances this may be modified by variable
1163 expansion (@pxref{Variable Expansion}) and prefixing. If the automount
1164 point has a prefix, specified by the @var{pref} option, then that is
1165 prepended to the search key before the map is searched.
1166
1167 If the map cache is a @samp{regexp} cache then the key is treated as an
1168 egrep-style regular expression, otherwise a normal string comparison is
1169 made.
1170
1171 If the key cannot be found then a @dfn{wildcard} match is attempted.
1172 @i{Amd} repeatedly strips the basename from the key, appends @samp{/*} and
1173 attempts a lookup. Finally, @i{Amd} attempts to locate the special key @samp{*}.
1174
1175 For example, the following sequence would be checked if @file{home/dylan/dk2} was
1176 being located:
1177
1178 @example
1179 home/dylan/dk2
1180 home/dylan/*
1181 home/*
1182 *
1183 @end example
1184
1185 At any point when a wildcard is found, @i{Amd} proceeds as if an exact
1186 match had been found and the value field is then used to resolve the
1187 mount request, otherwise an error code is propagated back to the kernel.
1188 (@pxref{Filesystem Types}).@refill
1189
1190 @node Location Format, , Key Lookup, Mount Maps
1191 @comment node-name, next, previous, up
1192 @section Location Format
1193 @cindex Location format
1194 @cindex Map entry format
1195 @cindex How locations are parsed
1196
1197 The value field from the lookup provides the information required to
1198 mount a filesystem. The information is parsed according to the syntax
1199 shown below.
1200
1201 @display
1202 @i{location-list}:
1203 @i{location-selection}
1204 @i{location-list} @i{white-space} @t{||} @i{white-space} @i{location-selection}
1205 @i{location-selection}:
1206 @i{location}
1207 @i{location-selection} @i{white-space} @i{location}
1208 @i{location}:
1209 @i{location-info}
1210 @t{-}@i{location-info}
1211 @t{-}
1212 @i{location-info}:
1213 @i{sel-or-opt}
1214 @i{location-info}@t{;}@i{sel-or-opt}
1215 @t{;}
1216 @i{sel-or-opt}:
1217 @i{selection}
1218 @i{opt-ass}
1219 @i{selection}:
1220 selector@t{==}@i{value}
1221 selector@t{!=}@i{value}
1222 @i{opt-ass}:
1223 option@t{:=}@i{value}
1224 @i{white-space}:
1225 space
1226 tab
1227 @end display
1228
1229 Note that unquoted whitespace is not allowed in a location description.
1230 White space is only allowed, and is mandatory, where shown with non-terminal
1231 @i{white-space}.
1232
1233 A @dfn{location-selection} is a list of possible volumes with which to
1234 satisfy the request. Each @dfn{location-selection} is tried
1235 sequentially, until either one succeeds or all fail. This, by the
1236 way, is different from the historically documented behavior, which
1237 claimed (falsely, at least for last 3 years) that @i{Amd} would
1238 attempt to mount all @dfn{location-selection}s in parallel and the
1239 first one to succeed would be used.
1240
1241 @dfn{location-selection}s are optionally separated by the @samp{||}
1242 operator. The effect of this operator is to prevent use of
1243 location-selections to its right if any of the location-selections on
1244 its left were selected, whether or not any of them were successfully
1245 mounted (@pxref{Selectors}).@refill
1246
1247 The location-selection, and singleton @dfn{location-list},
1248 @samp{type:=ufs;dev:=/dev/xd1g} would inform @i{Amd} to mount a UFS
1249 filesystem from the block special device @file{/dev/xd1g}.
1250
1251 The @dfn{sel-or-opt} component is either the name of an option required
1252 by a specific filesystem, or it is the name of a built-in, predefined
1253 selector such as the architecture type. The value may be quoted with
1254 double quotes @samp{"}, for example
1255 @samp{type:="ufs";dev:="/dev/xd1g"}. These quotes are stripped when the
1256 value is parsed and there is no way to get a double quote into a value
1257 field. Double quotes are used to get white space into a value field,
1258 which is needed for the program filesystem (@pxref{Program Filesystem}).@refill
1259
1260 @menu
1261 * Map Defaults::
1262 * Variable Expansion::
1263 * Selectors::
1264 * Map Options::
1265 @end menu
1266
1267 @node Map Defaults, Variable Expansion, Location Format, Location Format
1268 @comment node-name, next, previous, up
1269 @subsection Map Defaults
1270 @cindex Map defaults
1271 @cindex How to set default map parameters
1272 @cindex Setting default map parameters
1273
1274 A location beginning with a dash @samp{-} is used to specify default
1275 values for subsequent locations. Any previously specified defaults in
1276 the location-list are discarded. The default string can be empty in
1277 which case no defaults apply.
1278
1279 The location @samp{-fs:=/mnt;opts:=ro} would set the local mount point
1280 to @file{/mnt} and cause mounts to be read-only by default. Defaults
1281 specified this way are appended to, and so override, any global map
1282 defaults given with @samp{/defaults}).
1283
1284 @c
1285 @c A @samp{/defaults} value @dfn{gdef} and a location list
1286 @c \begin{quote}
1287 @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$
1288 @c \end{quote}
1289 @c is equivalent to
1290 @c \begin{quote}
1291 @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$
1292 @c \end{quote}
1293 @c which is equivalent to
1294 @c \begin{quote}
1295 @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$