1AMD.CONF(5) File Formats Manual AMD.CONF(5)
2
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 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 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 Section, parameter names and their values are case sensitive.
29 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 Any line beginning with a pound sign (#) is ignored, as are lines con‐
39 taining only whitespace.
40 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 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 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 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 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 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 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 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 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 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 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 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 /defaults \
145 wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \
146 wire!=slip-net;opts:=intr,rsize=8192,wsize=8192
147 Deprecated form: selectors_on_default
149 Parameters applicable to the global section only
152 arch (string, default to compiled in value)
153 Same as the -A option to Amd. Allows you to override the value
154 of the arch Amd variable.
155 auto_attrcache (numeric, default=0)
158 Specify in seconds (or units of 0.1 seconds, depending on the
159 OS), what is the (kernel-side) NFS attribute cache timeout for
160 @i{Amd}'s own automount points. A value of 0 is supposed to
161 turn off attribute caching, meaning that @i{Amd} will be con‐
162 sulted via a kernel-RPC each time someone stat()'s the mount
163 point (which could be abused as a denial-of-service attack).
164 Warning: some OSs are incapable of turning off the NFS attribute
165 cache reliably. On such systems, Amd may not work reliably
166 under heavy load. See the README.attrcache document in the Am-
167 utils distribution for more details.
168 auto_dir (string, default=/a)
171 Same as the -a option to Amd. This sets the private directory
172 where Amd will create sub-directories for its real mount points.
173 cache_duration (numeric, default=300)
176 Same as the -c option to Amd. Sets the duration in seconds that
177 looked-up or mounted map entries remain in the cache.
178 cluster (string, default no cluster)
181 Same as the -C option to Amd. Specifies the alternate HP-UX
182 cluster to use.
183 debug_mtab_file (string, default=/tmp/mnttab)
186 Path to mtab file that is used by Amd to store a list of mounted
187 file systems during debug-mtab mode. This option only applies
188 to systems that store mtab information on disk.
189 debug_options (string, default no debug options)
193 Same as the -D option to Amd. Specify any debugging
194 options for Amd. Works only if am-utils was configured
195 for debugging using the --enable-debug option. The "mem"
196 option, as well as all other options, can be turned on
197 via --enable-debug=mem. Otherwise debugging options are
198 ignored. Options are comma delimited, and can be pre‐
199 ceded by the string "no" to negate their meaning. You
200 can get the list of supported debugging options by run‐
201 ning Amd -H. Possible values are:
202 all all options
204 amq register for amq
205 daemon enter daemon mode
206 fork fork server
207 full program trace
208 hrtime print high resolution time stamps (only if syslog(3) is not used)
209 info info service specific debugging (hesiod, nis, etc.)
210 mem trace memory allocations
211 mtab use local "./mtab" file
212 readdir show browsable_dirs progress
213 str debug string munging
214 test full debug but no daemon
215 trace trace protocol and NFS mount arguments
216 xdrtrace trace XDR routines
217 dismount_interval (numeric, default=120)
220 Same as the -w option to Amd. Specify in seconds, the
221 time between attempts to dismount file systems that have
222 exceeded their cached times.
223 domain_strip (boolean, default=yes)
226 If "yes," then the domain name part referred to by
227 ${rhost} is stripped off. This is useful to keep logs
228 and smaller. If "no," then the domain name part is left
229 changed. This is useful when using multiple domains with
230 the same maps (as you may have hosts whose domain-
231 stripped name is identical).
232 exec_map_timeout (numeric, default=10)
235 The timeout in seconds that Amd will wait for an exe‐
236 cutable map program before an answer is returned from
237 that program (or script). This value should be set to as
238 small as possible while still allowing normal replies to
239 be returned before the timer expires, because during the
240 time that the executable map program is queried, Amd is
241 essentially waiting and is thus not responding to any
242 other queries.
243 forced_unmounts (boolean, default=no)
246 If set to "yes," and the client OS supports forced or
247 lazy unmounts, then Amd will attempt to use them if it
248 gets any of three serious error conditions when trying to
249 unmount an existing mount point or mount on top of one:
250 EIO, ESTALE, or EBUSY.
251 This could be useful to recover from serious conditions
253 such as hardware failure of mounted disks, or NFS servers
254 which are down permanently, were migrated, or changed
255 their IP address. Only "type:=toplvl" mounts hung with
256 EBUSY are forcibly unmounted using this option, which is
257 useful to recover from a hung Amd).
258 full_os (string, default to compiled in value)
261 The full name of the operating system, along with its
262 version. Allows you to override the compiled-in full
263 name and version of the operating system. Useful when
264 the compiled-in name is not desired. For example, the
265 full operating system name on linux comes up as
266 ``linux'', but you can override it to ``linux-2.2.5.''
267 fully_qualified_hosts (string, default=no)
270 If "yes," Amd will perform RPC authentication using
271 fully-qualified host names. This is necessary for some
272 systems, and especially when performing cross-domain
273 mounting. For this function to work, the Amd variable
274 ${hostd} is used, requiring that ${domain} not be null.
275 hesiod_base (string, default=automount)
278 Specify the base name for hesiod maps.
279 karch (string, default to karch of the system)
282 Same as the -k option to Amd. Allows you to override the
283 kernel-architecture of your system. Useful for example
284 on Sun (Sparc) machines, where you can build one Amd
285 binary, and run it on multiple machines, yet you want
286 each one to get the correct karch variable set (for exam‐
287 ple, sun4c, sun4m, sun4u, etc.) Note that if not speci‐
288 fied, Amd will use uname(3) to figure out the kernel
289 architecture of the machine.
290 ldap_base (string, default not set)
293 Specify the base name for LDAP. This often includes
294 LDAP-specific values such as country and organization.
295 ldap_cache_maxmem (numeric, default=131072)
298 Specify the maximum memory Amd should use to cache LDAP
299 entries.
300 ldap_cache_seconds (numeric, default=0)
303 Specify the number of seconds to keep entries in the
304 cache.
305 ldap_hostports (string, default not set)
308 Specify the LDAP host and port values.
309 ldap_proto_version (numeric, default=2)
312 Specify the version of the LDAP protocol to use.
313 local_domain (string, default no sub-domain)
316 Same as the -d option to Amd. Specify the local domain
317 name. If this option is not given the domain name is
318 determined from the hostname, by removing the first com‐
319 ponent of the fully-qualified host name.
320 localhost_address (string, default to localhost or 127.0.0.1)
323 Specify the name or IP address for Amd to use when con‐
324 necting the sockets for the local NFS server and the RPC
325 server. This defaults to 127.0.0.1 or whatever the host
326 reports as its local address. This parameter is useful
327 on hosts with multiple addresses where you want to force
328 Amd to connect to a specific address.
329 log_file (string, default=/dev/stderr)
332 Same as the -l option to Amd. Specify a file name to log
333 Amd events to. If the string /dev/stderr is specified,
334 Amd will send its events to the standard error file
335 descriptor. If the string syslog is given, Amd will
336 record its events with the system logger syslogd(8). The
337 default syslog facility used is LOG_DAEMON. If you wish
338 to change it, append its name to the log file name,
339 delimited by a single colon. For example, if logfile is
340 the string syslog:local7 then Amd will log messages via
341 syslog(3) using the LOG_LOCAL7 facility (if it exists on
342 the system).
343 log_options (string, default no logging options)
346 Same as the -x option to Amd. Specify any logging
347 options for Amd. Options are comma delimited, and can be
348 preceded by the string "no" to negate their meaning. The
349 "debug" logging option is only available if am-utils was
350 configured with --enable-debug. You can get the list of
351 supported debugging and logging options by running amd
352 -H. Possible values are:
353 all all messages
355 debug debug messages
356 error non-fatal system errors
357 fatal fatal errors
358 info information
359 map map errors
360 stats additional statistical information
361 user non-fatal user errors
362 warn warnings
363 warning warnings
364 map_reload_interval (numeric, default=3600)
367 The number of seconds that Amd will wait before it checks
368 to see if any maps have changed at their source (NIS
369 servers, LDAP servers, files, etc.). Amd will reload
370 only those maps that have changed.
371 nfs_allow_any_interface (string, default=no)
374 Normally Amd accepts local NFS packets only from
375 127.0.0.1. If this parameter is set to "yes" then Amd
376 will accept local NFS packets from any local interface;
377 this is useful on hosts that may have multiple interfaces
378 where the system is forced to send all outgoing packets
379 (even those bound to the same host) via an address other
380 than 127.0.0.1.
381 nfs_allow_insecure_port (string, default=no)
384 Normally Amd will refuse requests coming from unprivi‐
385 leged ports (i.e. ports >= 1024 on Unix systems), so
386 that only privileged users and the kernel can send NFS
387 requests to it. However, some kernels (certain versions
388 of Darwin, MacOS X, and Linux) have bugs that cause them
389 to use unprivileged ports in certain situations, which
390 causes Amd to stop dead in its tracks. This parameter
391 allows Amd to operate normally even on such systems, at
392 the expense of a slight decrease in the security of its
393 operations. If you see messages like "ignoring request
394 from foo:1234, port not reserved" in your Amd log, try
395 enabling this parameter and give it another go.
396 nfs_proto (string, default to trying version tcp then udp)
399 By default, Amd tries TCP and then UDP. This option
400 forces the overall NFS protocol used to TCP or UDP. It
401 overrides what is in the Amd maps, and is useful when Amd
402 is compiled with NFSv3 support that may not be stable.
403 With this option you can turn off the complete usage of
404 NFSv3 dynamically (without having to recompile Amd) until
405 such time as NFSv3 support is desired again.
406 nfs_retransmit_counter (numeric, default=11)
409 Same as the retransmit part of the -t timeout.retransmit
410 option to Amd. Specifies the number of NFS retransmis‐
411 sions that the kernel will use to communicate with Amd.
412 nfs_retransmit_counter_udp (numeric, default=11)
415 Same as the nfs_retransmit_counter option, but for all
416 UDP mounts only.
417 nfs_retransmit_counter_tcp (numeric, default=11)
420 Same as the nfs_retransmit_counter option, but for all
421 TCP mounts only.
422 nfs_retransmit_counter_toplvl (numeric, default=11)
425 Same as the nfs_retransmit_counter option, but only for
426 Amd's top-level UDP mounts.
427 nfs_retry_interval (numeric, default=8)
430 Same as the timeout part of the -t timeout.retransmit
431 option to Amd. Specifies the NFS timeout interval, in
432 tenths of seconds, between NFS/RPC retries (for UDP and
433 TCP). This is the value that the kernel will use to com‐
434 municate with Amd.
435 Amd relies on the kernel RPC retransmit mechanism to
437 trigger mount retries. The values of the nfs_retrans‐
438 mit_counter and the nfs_retry_interval parameters change
439 the overall retry interval. Too long an interval gives
440 poor interactive response; too short an interval causes
441 excessive retries.
442 nfs_retry_interval_udp (numeric, default=8)
445 Same as the nfs_retry_interval option, but for all UDP
446 mounts only.
447 nfs_retry_interval_tcp (numeric, default=8)
450 Same as the nfs_retry_interval option, but for all TCP
451 mounts only.
452 nfs_retry_interval_toplvl (numeric, default=8)
455 Same as the nfs_retry_interval option, but only for Amd's
456 top-level UDP mounts.
457 nfs_vers (numeric, default to trying version 3 then 2)
460 By default, Amd tries version 3 and then version 2. This
461 option forces the overall NFS protocol used to version 3
462 or 2. It overrides what is in the Amd maps, and is use‐
463 ful when Amd is compiled with NFSv3 support that may not
464 be stable. With this option you can turn off the com‐
465 plete usage of NFSv3 dynamically (without having to
466 recompile Amd) until such time as NFSv3 support is
467 desired again.
468 nis_domain (string, default to local NIS domain name)
471 Same as the -y option to Amd. Specify an alternative NIS
472 domain from which to fetch the NIS maps. The default is
473 the system domain name. This option is ignored if NIS
474 support is not available.
475 normalize_hostnames (boolean, default=no)
478 Same as the -n option to Amd. If "yes," then the name
479 refereed to by ${rhost} is normalized relative to the
480 host database before being used. The effect is to trans‐
481 late aliases into ``official'' names.
482 normalize_slashes (boolean, default=yes)
485 If "yes," then Amd will condense all multiple ``/''
487 (slash) characters into one and remove all trailing
488 slashes. If "no," then Amd will not touch strings that
489 may contain repeated or trailing slashes. The latter is
490 sometimes useful with SMB mounts, which often require
491 multiple slash characters in pathnames.
492 os (string, default to compiled in value)
495 Same as the -O option to Amd. Allows you to override the
496 compiled-in name of the operating system. Useful when
497 the built-in name is not desired for backward compatibil‐
498 ity reasons. For example, if the build in name is
499 ``sunos5'', you can override it to ``sos5'', and use
500 older maps which were written with the latter in mind.
501 osver (string, default to compiled in value)
504 Same as the -o option to Amd. Overrides the compiled-in
505 version number of the operating system. Useful when the
506 built in version is not desired for backward compatibil‐
507 ity reasons. For example, if the build in version is
508 ``2.5.1'', you can override it to ``5.5.1'', and use
509 older maps that were written with the latter in mind.
510 pid_file (string, default=/dev/stdout)
513 Specify a file to store the process ID of the running
514 daemon into. If not specified, Amd will print its
515 process id onto the standard output. Useful for killing
516 Amd after it had run. Note that the PID of a running Amd
517 can also be retrieved via amq -p. This file is used only
518 if the print_pid option is on.
519 plock (boolean, default=yes)
522 Same as the -S option to Amd. If "yes," lock the running
523 executable pages of Amd into memory. To improve Amd's
524 performance, systems that support the plock(3) or mlock‐
525 all(2) call can lock the Amd process into memory. This
526 way there is less chance it the operating system will
527 schedule, page out, and swap the Amd process as needed.
528 This improves Amd's performance, at the cost of reserving
529 the memory used by the Amd process (making it unavailable
530 for other processes).
531 portmap_program (numeric, default=300019)
534 Specify an alternate Port-mapper RPC program number,
535 other than the official number. This is useful when run‐
536 ning multiple Amd processes. For example, you can run
537 another Amd in "test" mode, without affecting the primary
538 Amd process in any way. For safety reasons, the alter‐
539 nate program numbers that can be specified must be in the
540 range 300019-300029, inclusive. Amq has an option -P
541 which can be used to specify an alternate program number
542 of an Amd to contact. In this way, amq can fully control
543 any number of Amd processes running on the same host.
544 preferred_amq_port (numeric, default=0)
547 Specify an alternate Port-mapper RPC port number for
548 Amd's Amq service. This is used for both UDP and TCP.
549 Setting this value to 0 (or not defining it) will cause
550 Amd to select an arbitrary port number. Setting the Amq
551 RPC service port to a specific number is useful in fire‐
552 walled or NAT'ed environments, where you need to know
553 which port Amd will listen on.
554 print_pid (boolean, default=no)
557 Same as the -p option to Amd. If "yes," Amd will print
558 its process ID upon starting.
559 print_version (boolean, default=no)
562 Same as the -v option to Amd, but the version prints and
563 Amd continues to run. If "yes," Amd will print its ver‐
564 sion information string, which includes some configura‐
565 tion and compilation values.
566 restart_mounts (boolean, default=no)
569 Same as the -r option to Amd. If "yes" Amd will scan the
570 mount table to determine which file systems are currently
571 mounted. Whenever one of these would have been auto-
572 mounted, Amd inherits it.
573 show_statfs_entries (boolean), default=no)
576 If "yes," then all maps which are browsable will also
577 show the number of entries (keys) they have when "df"
578 runs. (This is accomplished by returning non-zero values
579 to the statfs(2) system call).
580 truncate_log (boolean), default=no)
583 If "yes," then the log file (if it is a regular file),
584 will be truncated upon startup.
585 unmount_on_exit (boolean), default=no)
588 If "yes," then Amd will attempt to unmount all file sys‐
589 tems which it knows about. Normally Amd leaves all (esp.
590 NFS) mounted file systems intact. Note that Amd does not
591 know about file systems mounted before it starts up,
592 unless the restart_mounts option or -r flag are used.
593 use_tcpwrappers (boolean), default=yes)
596 If "yes," then Amd will use the tcpd/librwap tcpwrappers
597 library (if available) to control access to Amd via the
598 /etc/hosts.allow and /etc/hosts.deny files.
599 vendor (string, default to compiled in value)
602 The name of the vendor of the operating system. Over‐
603 rides the compiled-in vendor name. Useful when the com‐
604 piled-in name is not desired. For example, most Intel
605 based systems set the vendor name to ``unknown'', but you
606 can set it to ``redhat.''
607 Parameters applicable to regular map sections
610 map_name (string, must be specified)
611 Name of the map where the keys are located.
612 tag (string, default no tag)
615 Each map entry in the configuration file can be tagged.
616 If no tag is specified, that map section will always be
617 processed by Amd. If it is specified, then Amd will
618 process the map if the -T option was given to Amd, and
619 the value given to that command-line option matches that
620 in the map section.
621
624 Here is a real Amd configuration file I use daily.
625 # GLOBAL OPTIONS SECTION
627 [ global ]
628 normalize_hostnames = no
629 print_pid = no
630 restart_mounts = yes
631 auto_dir = /n
632 log_file = /var/log/amd
633 log_options = all
634 #debug_options = all
635 plock = no
636 selectors_in_defaults = yes
637 # config.guess picks up "sunos5" and I don't want to edit my maps yet
638 os = sos5
639 # if you print_version after setting up "os," it will show it.
640 print_version = no
641 map_type = file
642 search_path = /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib
643 browsable_dirs = yes
644 # DEFINE AN AMD MOUNT POINT
646 [ /u ]
647 map_name = amd.u
648 [ /proj ]
650 map_name = amd.proj
651 [ /src ]
653 map_name = amd.src
654 [ /misc ]
656 map_name = amd.misc
657 [ /import ]
659 map_name = amd.import
660 [ /tftpboot/.amd ]
662 tag = tftpboot
663 map_name = amd.tftpboot
664
666 amd(8), amq(8), ctl-amd(8), hosts_access(5).
667 ``am-utils'' info(1) entry.
669 Linux NFS and Automounter Administration by Erez Zadok, ISBN
671 0-7821-2739-8, (Sybex, 2001).
672 http://www.am-utils.org
674 Amd - The 4.4 BSD Automounter
676
678 Erez Zadok <ezk@cs.sunysb.edu>, Computer Science Department,
679 Stony Brook University, Stony Brook, New York, USA.
680 Other authors and contributors to am-utils are listed in the
682 AUTHORS file distributed with am-utils.
683 7 August 1997 AMD.CONF(5)