1AMD.CONF(5) File Formats Manual AMD.CONF(5)
2
3
4
6 amd.conf - Amd configuration file
7
9 amd.conf
10
12 The amd.conf file is the configuration file for Amd, as part of the am-
13 utils suite.
14
15 amd.conf contains runtime configuration information for the Amd auto‐
16 mounter program.
17
19 The file consists of sections and parameters. A section begins with
20 the name of the section in square brackets and continues until the next
21 section begins or the end the file is reached. Sections contain param‐
22 eters of the form 'name = value'.
23
24 The file is line-based - that is, each newline-terminated line repre‐
25 sents either a comment, a section name or a parameter. No line-contin‐
26 uation syntax is available.
27
28 Section, parameter names and their values are case sensitive.
29
30 Only the first equals sign in a parameter is significant. Whitespace
31 before or after the first equals sign is discarded. Leading, trailing
32 and internal whitespace in section and parameter names is irrelevant.
33 Leading and trailing whitespace in a parameter value is discarded.
34 Internal whitespace within a parameter value is not allowed, unless the
35 whole parameter value is quoted with double quotes as in 'name = "some
36 value"'.
37
38 Any line beginning with a pound sign (#) is ignored, as are lines con‐
39 taining only whitespace.
40
41 The values following the equals sign in parameters are all either a
42 string (no quotes needed if string does not include spaces) or a bool‐
43 ean, which may be given as yes/no. Case is significant in all values.
44 Some items such as cache timeouts are numeric.
45
47 The [global] section
48 Parameters in this section either apply to Amd as a whole, or to all
49 other regular map sections which follow. There should be only one
50 global section defined in one configuration file.
51
52 It is highly recommended that this section be specified first in the
53 configuration file. If it is not, then regular map sections which pre‐
54 cede it will not use global values defined later.
55
56
57 Regular [/map] sections
58 Parameters in regular (non-global) sections apply to a single map
59 entry. For example, if the map section [/homes] is defined, then all
60 parameters following it will be applied to the /homes Amd-managed mount
61 point.
62
64 Parameters common to all sections
65 These parameters can be specified either in the global or a map spe‐
66 cific section. Entries specified in a map-specific section override
67 the default value or one defined in the global section. If such a
68 common parameter is specified only in the global section, it is appli‐
69 cable to all regular map sections that follow.
70
71 browsable_dirs (string, default=no)
72 If "yes," then Amd's top-level mount points will be browsable to
73 readdir(3) calls. This means you could run for example ls(1)
74 and see what keys are available to mount in that directory. Not
75 all entries are made visible to readdir(3): the "/default"
76 entry, wildcard entries, and those with a "/" in them are not
77 included. If you specify "full" to this option, all but
78 "/default" will be visible. Note that if you run a command
79 which will attempt to stat(2) the entries, such as often done by
80 "ls -l" or "ls -F," Amd will attempt to mount every entry in
81 that map. This is often called a ``mount storm.''
82
83
84 map_defaults (string, default to empty)
85 This option sets a string to be used as the map's /defaults
86 entry, overriding any /defaults specified in the map. This
87 allows local users to override map defaults without modifying
88 maps globally.
89
90
91 map_options (string, default no options)
92 This option is the same as specifying map options on the command
93 line to Amd, such as "cache:=all".
94
95
96 map_type (string, default search all map types)
97 If specified, Amd will initialize the map only for the type
98 given. This is useful to avoid the default map search type used
99 by Amd which takes longer and can have undesired side-effects
100 such as initializing NIS even if not used. Possible values are
101
102 exec executable maps
103 file plain files
104 hesiod Hesiod name service from MIT
105 ldap Lightweight Directory Access Protocol
106 ndbm (New) dbm style hash files
107 nis Network Information Services (version 2)
108 nisplus Network Information Services Plus (version 3)
109 passwd local password files
110 union union maps
111
112
113 mount_type (string, default=nfs)
114 All Amd mount types default to NFS. That is, Amd is an NFS
115 server on the map mount points, for the local host it is running
116 on. If "autofs" is specified, Amd will be an autofs server for
117 those mount points.
118
119
120 autofs_use_lofs (string, default=yes)
121 When set to "yes" and using Autofs, Amd will use lofs-type
122 (loopback) mounts for type:=link mounts. This has the advantage
123 of mounting in place, and users get to the see the same pathname
124 that they chdir'ed into. If this option is set to "no," then
125 Amd will use symlinks instead: that code is more tested, but
126 negates autofs's big advantage of in-place mounts.
127
128
129 search_path (string, default no search path)
130 This provides a (colon-delimited) search path for file maps.
131 Using a search path, sites can allow for local map customiza‐
132 tions and overrides, and can distributed maps in several loca‐
133 tions as needed.
134
135
136 selectors_in_defaults (boolean, default=no)
137 If "yes," then the /defaults entry of maps will search for and
138 process any selectors before setting defaults for all other keys
139 in that map. Useful when you want to set different options for
140 a complete map based on some parameters. For example, you may
141 want to better the NFS performance over slow slip-based networks
142 as follows:
143
144 /defaults \
145 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \
146 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192
147
148 Deprecated form: selectors_on_default
149
150
151 sun_map_syntax (boolean, default=no)
152 If "yes," then Amd will parse the map according to the Sun Auto‐
153 mount syntax.
154
155
156 Parameters applicable to the global section only
157 arch (string, default to compiled in value)
158 Same as the -A option to Amd. Allows you to override the value
159 of the arch Amd variable.
160
161
162 auto_attrcache (numeric, default=0)
163 Specify in seconds (or units of 0.1 seconds, depending on the
164 OS), what is the (kernel-side) NFS attribute cache timeout for
165 @i{Amd}'s own automount points. A value of 0 is supposed to
166 turn off attribute caching, meaning that @i{Amd} will be con‐
167 sulted via a kernel-RPC each time someone stat()'s the mount
168 point (which could be abused as a denial-of-service attack).
169 Warning: some OSs are incapable of turning off the NFS attribute
170 cache reliably. On such systems, Amd may not work reliably
171 under heavy load. See the README.attrcache document in the Am-
172 utils distribution for more details.
173
174
175 auto_dir (string, default=/a)
176 Same as the -a option to Amd. This sets the private directory
177 where Amd will create sub-directories for its real mount points.
178
179
180 cache_duration (numeric, default=300)
181 Same as the -c option to Amd. Sets the duration in seconds that
182 looked-up or mounted map entries remain in the cache.
183
184
185 cluster (string, default no cluster)
186 Same as the -C option to Amd. Specifies the alternate HP-UX
187 cluster to use.
188
189
190 debug_mtab_file (string, default=/tmp/mnttab)
191 Path to mtab file that is used by Amd to store a list of mounted
192 file systems during debug-mtab mode. This option only applies
193 to systems that store mtab information on disk.
194
195
196
197 debug_options (string, default no debug options)
198 Same as the -D option to Amd. Specify any debugging
199 options for Amd. Works only if am-utils was configured
200 for debugging using the --enable-debug option. The "mem"
201 option, as well as all other options, can be turned on
202 via --enable-debug=mem. Otherwise debugging options are
203 ignored. Options are comma delimited, and can be pre‐
204 ceded by the string "no" to negate their meaning. You
205 can get the list of supported debugging options by run‐
206 ning Amd -H. Possible values are:
207
208 all all options (excludes hrtime and mtab)
209 defaults "sensible" default options (all--excluding hrtime, mtab, and xdrtrace)
210 test full debug options plus mtab,nodaemon,nofork,noamq
211 amq register for amq
212 daemon enter daemon mode
213 fork fork server
214 full program trace
215 hrtime print high resolution time stamps (only if syslog(3) is not used)
216 info info service specific debugging (hesiod, nis, etc.)
217 mem trace memory allocations
218 mtab use local "/tmp/mtab" file
219 readdir show browsable_dirs progress
220 str debug string munging
221 trace trace protocol and NFS mount arguments
222 xdrtrace trace XDR routines
223
224
225 dismount_interval (numeric, default=120)
226 Same as the -w option to Amd. Specify in seconds, the
227 time between attempts to dismount file systems that have
228 exceeded their cached times.
229
230
231 domain_strip (boolean, default=yes)
232 If "yes," then the domain name part referred to by
233 ${rhost} is stripped off. This is useful to keep logs
234 and smaller. If "no," then the domain name part is left
235 changed. This is useful when using multiple domains with
236 the same maps (as you may have hosts whose domain-
237 stripped name is identical).
238
239
240 exec_map_timeout (numeric, default=10)
241 The timeout in seconds that Amd will wait for an exe‐
242 cutable map program before an answer is returned from
243 that program (or script). This value should be set to as
244 small as possible while still allowing normal replies to
245 be returned before the timer expires, because during the
246 time that the executable map program is queried, Amd is
247 essentially waiting and is thus not responding to any
248 other queries.
249
250
251 forced_unmounts (boolean, default=no)
252 If set to "yes," and the client OS supports forced or
253 lazy unmounts, then Amd will attempt to use them if it
254 gets any of three serious error conditions when trying to
255 unmount an existing mount point or mount on top of one:
256 EIO, ESTALE, or EBUSY.
257
258 This could be useful to recover from serious conditions
259 such as hardware failure of mounted disks, or NFS servers
260 which are down permanently, were migrated, or changed
261 their IP address. Only "type:=toplvl" mounts hung with
262 EBUSY are forcibly unmounted using this option, which is
263 useful to recover from a hung Amd).
264
265
266 full_os (string, default to compiled in value)
267 The full name of the operating system, along with its
268 version. Allows you to override the compiled-in full
269 name and version of the operating system. Useful when
270 the compiled-in name is not desired. For example, the
271 full operating system name on linux comes up as
272 ``linux'', but you can override it to ``linux-2.2.5.''
273
274
275 fully_qualified_hosts (string, default=no)
276 If "yes," Amd will perform RPC authentication using
277 fully-qualified host names. This is necessary for some
278 systems, and especially when performing cross-domain
279 mounting. For this function to work, the Amd variable
280 ${hostd} is used, requiring that ${domain} not be null.
281
282
283 hesiod_base (string, default=automount)
284 Specify the base name for hesiod maps.
285
286
287 karch (string, default to karch of the system)
288 Same as the -k option to Amd. Allows you to override the
289 kernel-architecture of your system. Useful for example
290 on Sun (Sparc) machines, where you can build one Amd
291 binary, and run it on multiple machines, yet you want
292 each one to get the correct karch variable set (for exam‐
293 ple, sun4c, sun4m, sun4u, etc.) Note that if not speci‐
294 fied, Amd will use uname(3) to figure out the kernel
295 architecture of the machine.
296
297
298 ldap_base (string, default not set)
299 Specify the base name for LDAP. This often includes
300 LDAP-specific values such as country and organization.
301
302
303 ldap_cache_maxmem (numeric, default=131072)
304 Specify the maximum memory Amd should use to cache LDAP
305 entries.
306
307
308 ldap_cache_seconds (numeric, default=0)
309 Specify the number of seconds to keep entries in the
310 cache.
311
312
313 ldap_hostports (string, default not set)
314 Specify the LDAP host and port values.
315
316
317 ldap_proto_version (numeric, default=2)
318 Specify the version of the LDAP protocol to use.
319
320
321 local_domain (string, default no sub-domain)
322 Same as the -d option to Amd. Specify the local domain
323 name. If this option is not given the domain name is
324 determined from the hostname, by removing the first com‐
325 ponent of the fully-qualified host name.
326
327
328 localhost_address (string, default to localhost or 127.0.0.1)
329 Specify the name or IP address for Amd to use when con‐
330 necting the sockets for the local NFS server and the RPC
331 server. This defaults to 127.0.0.1 or whatever the host
332 reports as its local address. This parameter is useful
333 on hosts with multiple addresses where you want to force
334 Amd to connect to a specific address.
335
336
337 log_file (string, default=/dev/stderr)
338 Same as the -l option to Amd. Specify a file name to log
339 Amd events to. If the string /dev/stderr is specified,
340 Amd will send its events to the standard error file
341 descriptor. If the string syslog is given, Amd will
342 record its events with the system logger syslogd(8). The
343 default syslog facility used is LOG_DAEMON. If you wish
344 to change it, append its name to the log file name,
345 delimited by a single colon. For example, if logfile is
346 the string syslog:local7 then Amd will log messages via
347 syslog(3) using the LOG_LOCAL7 facility (if it exists on
348 the system).
349
350
351 log_options (string, default=defaults)
352 Same as the -x option to Amd. Specify any logging
353 options for Amd. Options are comma delimited, and can be
354 preceded by the string "no" to negate their meaning. The
355 "debug" logging option is only available if am-utils was
356 configured with --enable-debug. You can get the list of
357 supported debugging and logging options by running amd
358 -H. Possible values are:
359
360 all all messages
361 defaults default messages (fatal,error,user,warning,info)
362 debug debug messages
363 error non-fatal system errors (cannot be turned off)
364 fatal fatal errors (cannot be turned off)
365 info information
366 map map errors
367 stats additional statistical information
368 user non-fatal user errors
369 warn warnings
370 warning warnings
371
372
373 map_reload_interval (numeric, default=3600)
374 The number of seconds that Amd will wait before it checks
375 to see if any maps have changed at their source (NIS
376 servers, LDAP servers, files, etc.). Amd will reload
377 only those maps that have changed.
378
379
380 nfs_allow_any_interface (string, default=no)
381 Normally Amd accepts local NFS packets only from
382 127.0.0.1. If this parameter is set to "yes" then Amd
383 will accept local NFS packets from any local interface;
384 this is useful on hosts that may have multiple interfaces
385 where the system is forced to send all outgoing packets
386 (even those bound to the same host) via an address other
387 than 127.0.0.1.
388
389
390 nfs_allow_insecure_port (string, default=no)
391 Normally Amd will refuse requests coming from unprivi‐
392 leged ports (i.e. ports >= 1024 on Unix systems), so
393 that only privileged users and the kernel can send NFS
394 requests to it. However, some kernels (certain versions
395 of Darwin, MacOS X, and Linux) have bugs that cause them
396 to use unprivileged ports in certain situations, which
397 causes Amd to stop dead in its tracks. This parameter
398 allows Amd to operate normally even on such systems, at
399 the expense of a slight decrease in the security of its
400 operations. If you see messages like "ignoring request
401 from foo:1234, port not reserved" in your Amd log, try
402 enabling this parameter and give it another go.
403
404
405 nfs_proto (string, default to trying version tcp then udp)
406 By default, Amd tries TCP and then UDP. This option
407 forces the overall NFS protocol used to TCP or UDP. It
408 overrides what is in the Amd maps, and is useful when Amd
409 is compiled with NFSv3 support that may not be stable.
410 With this option you can turn off the complete usage of
411 NFSv3 dynamically (without having to recompile Amd) until
412 such time as NFSv3 support is desired again.
413
414
415 nfs_retransmit_counter (numeric, default=11)
416 Same as the retransmit part of the -t timeout.retransmit
417 option to Amd. Specifies the number of NFS retransmis‐
418 sions that the kernel will use to communicate with Amd.
419
420
421 nfs_retransmit_counter_udp (numeric, default=11)
422 Same as the nfs_retransmit_counter option, but for all
423 UDP mounts only.
424
425
426 nfs_retransmit_counter_tcp (numeric, default=11)
427 Same as the nfs_retransmit_counter option, but for all
428 TCP mounts only.
429
430
431 nfs_retransmit_counter_toplvl (numeric, default=11)
432 Same as the nfs_retransmit_counter option, but only for
433 Amd's top-level UDP mounts.
434
435
436 nfs_retry_interval (numeric, default=8)
437 Same as the timeout part of the -t timeout.retransmit
438 option to Amd. Specifies the NFS timeout interval, in
439 tenths of seconds, between NFS/RPC retries (for UDP and
440 TCP). This is the value that the kernel will use to com‐
441 municate with Amd.
442
443 Amd relies on the kernel RPC retransmit mechanism to
444 trigger mount retries. The values of the nfs_retrans‐
445 mit_counter and the nfs_retry_interval parameters change
446 the overall retry interval. Too long an interval gives
447 poor interactive response; too short an interval causes
448 excessive retries.
449
450
451 nfs_retry_interval_udp (numeric, default=8)
452 Same as the nfs_retry_interval option, but for all UDP
453 mounts only.
454
455
456 nfs_retry_interval_tcp (numeric, default=8)
457 Same as the nfs_retry_interval option, but for all TCP
458 mounts only.
459
460
461 nfs_retry_interval_toplvl (numeric, default=8)
462 Same as the nfs_retry_interval option, but only for Amd's
463 top-level UDP mounts.
464
465
466 nfs_vers (numeric, default to trying version 3 then 2)
467 By default, Amd tries version 3 and then version 2. This
468 option forces the overall NFS protocol used to version 3
469 or 2. It overrides what is in the Amd maps, and is use‐
470 ful when Amd is compiled with NFSv3 support that may not
471 be stable. With this option you can turn off the com‐
472 plete usage of NFSv3 dynamically (without having to
473 recompile Amd) until such time as NFSv3 support is
474 desired again.
475
476
477 nis_domain (string, default to local NIS domain name)
478 Same as the -y option to Amd. Specify an alternative NIS
479 domain from which to fetch the NIS maps. The default is
480 the system domain name. This option is ignored if NIS
481 support is not available.
482
483
484 normalize_hostnames (boolean, default=no)
485 Same as the -n option to Amd. If "yes," then the name
486 refereed to by ${rhost} is normalized relative to the
487 host database before being used. The effect is to trans‐
488 late aliases into ``official'' names.
489
490
491 normalize_slashes (boolean, default=yes)
492
493 If "yes," then Amd will condense all multiple ``/''
494 (slash) characters into one and remove all trailing
495 slashes. If "no," then Amd will not touch strings that
496 may contain repeated or trailing slashes. The latter is
497 sometimes useful with SMB mounts, which often require
498 multiple slash characters in pathnames.
499
500
501 os (string, default to compiled in value)
502 Same as the -O option to Amd. Allows you to override the
503 compiled-in name of the operating system. Useful when
504 the built-in name is not desired for backward compatibil‐
505 ity reasons. For example, if the build in name is
506 ``sunos5'', you can override it to ``sos5'', and use
507 older maps which were written with the latter in mind.
508
509
510 osver (string, default to compiled in value)
511 Same as the -o option to Amd. Overrides the compiled-in
512 version number of the operating system. Useful when the
513 built in version is not desired for backward compatibil‐
514 ity reasons. For example, if the build in version is
515 ``2.5.1'', you can override it to ``5.5.1'', and use
516 older maps that were written with the latter in mind.
517
518
519 pid_file (string, default=/dev/stdout)
520 Specify a file to store the process ID of the running
521 daemon into. If not specified, Amd will print its
522 process id onto the standard output. Useful for killing
523 Amd after it had run. Note that the PID of a running Amd
524 can also be retrieved via amq -p. This file is used only
525 if the print_pid option is on.
526
527
528 plock (boolean, default=yes)
529 Same as the -S option to Amd. If "yes," lock the running
530 executable pages of Amd into memory. To improve Amd's
531 performance, systems that support the plock(3) or mlock‐
532 all(2) call can lock the Amd process into memory. This
533 way there is less chance it the operating system will
534 schedule, page out, and swap the Amd process as needed.
535 This improves Amd's performance, at the cost of reserving
536 the memory used by the Amd process (making it unavailable
537 for other processes).
538
539
540 portmap_program (numeric, default=300019)
541 Specify an alternate Port-mapper RPC program number,
542 other than the official number. This is useful when run‐
543 ning multiple Amd processes. For example, you can run
544 another Amd in "test" mode, without affecting the primary
545 Amd process in any way. For safety reasons, the alter‐
546 nate program numbers that can be specified must be in the
547 range 300019-300029, inclusive. Amq has an option -P
548 which can be used to specify an alternate program number
549 of an Amd to contact. In this way, amq can fully control
550 any number of Amd processes running on the same host.
551
552
553 preferred_amq_port (numeric, default=0)
554 Specify an alternate Port-mapper RPC port number for
555 Amd's Amq service. This is used for both UDP and TCP.
556 Setting this value to 0 (or not defining it) will cause
557 Amd to select an arbitrary port number. Setting the Amq
558 RPC service port to a specific number is useful in fire‐
559 walled or NAT'ed environments, where you need to know
560 which port Amd will listen on.
561
562
563 print_pid (boolean, default=no)
564 Same as the -p option to Amd. If "yes," Amd will print
565 its process ID upon starting.
566
567
568 print_version (boolean, default=no)
569 Same as the -v option to Amd, but the version prints and
570 Amd continues to run. If "yes," Amd will print its ver‐
571 sion information string, which includes some configura‐
572 tion and compilation values.
573
574
575 restart_mounts (boolean, default=no)
576 Same as the -r option to Amd. If "yes" Amd will scan the
577 mount table to determine which file systems are currently
578 mounted. Whenever one of these would have been auto-
579 mounted, Amd inherits it.
580
581
582 show_statfs_entries (boolean), default=no)
583 If "yes," then all maps which are browsable will also
584 show the number of entries (keys) they have when "df"
585 runs. (This is accomplished by returning non-zero values
586 to the statfs(2) system call).
587
588
589 truncate_log (boolean), default=no)
590 If "yes," then the log file (if it is a regular file),
591 will be truncated upon startup.
592
593
594 unmount_on_exit (boolean), default=no)
595 If "yes," then Amd will attempt to unmount all file sys‐
596 tems which it knows about. Normally Amd leaves all (esp.
597 NFS) mounted file systems intact. Note that Amd does not
598 know about file systems mounted before it starts up,
599 unless the restart_mounts option or -r flag are used.
600
601
602 use_tcpwrappers (boolean), default=yes)
603 If "yes," then Amd will use the tcpd/librwap tcpwrappers
604 library (if available) to control access to Amd via the
605 /etc/hosts.allow and /etc/hosts.deny files.
606
607
608 vendor (string, default to compiled in value)
609 The name of the vendor of the operating system. Over‐
610 rides the compiled-in vendor name. Useful when the com‐
611 piled-in name is not desired. For example, most Intel
612 based systems set the vendor name to ``unknown'', but you
613 can set it to ``redhat.''
614
615
616 Parameters applicable to regular map sections
617 map_name (string, must be specified)
618 Name of the map where the keys are located.
619
620
621 tag (string, default no tag)
622 Each map entry in the configuration file can be tagged.
623 If no tag is specified, that map section will always be
624 processed by Amd. If it is specified, then Amd will
625 process the map if the -T option was given to Amd, and
626 the value given to that command-line option matches that
627 in the map section.
628
629
631 Here is a real Amd configuration file I use daily.
632
633 # GLOBAL OPTIONS SECTION
634 [ global ]
635 normalize_hostnames = no
636 print_pid = no
637 restart_mounts = yes
638 auto_dir = /n
639 log_file = /var/log/amd
640 log_options = all
641 #debug_options = all
642 plock = no
643 selectors_in_defaults = yes
644 # config.guess picks up "sunos5" and I don't want to edit my maps yet
645 os = sos5
646 # if you print_version after setting up "os," it will show it.
647 print_version = no
648 map_type = file
649 search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib
650 browsable_dirs = yes
651
652 # DEFINE AN AMD MOUNT POINT
653 [ /u ]
654 map_name = amd.u
655
656 [ /proj ]
657 map_name = amd.proj
658
659 [ /src ]
660 map_name = amd.src
661
662 [ /misc ]
663 map_name = amd.misc
664
665 [ /import ]
666 map_name = amd.import
667
668 [ /tftpboot/.amd ]
669 tag = tftpboot
670 map_name = amd.tftpboot
671
673 amd(8), amq(8), ctl-amd(8), automount(8), hosts_access(5).
674
675 ``am-utils'' info(1) entry.
676
677 Linux NFS and Automounter Administration by Erez Zadok, ISBN
678 0-7821-2739-8, (Sybex, 2001).
679
680 http://www.am-utils.org
681
682 Amd - The 4.4 BSD Automounter
683
685 Erez Zadok <ezk@cs.sunysb.edu>, Computer Science Department,
686 Stony Brook University, Stony Brook, New York, USA.
687
688 Other authors and contributors to am-utils are listed in the
689 AUTHORS file distributed with am-utils.
690
691
692
693 7 August 1997 AMD.CONF(5)