contrib/amd/scripts/amd.conf.5

   1 .\"
   2 .\" Copyright (c) 1997-2006 Erez Zadok
   3 .\" Copyright (c) 1990 Jan-Simon Pendry
   4 .\" Copyright (c) 1990 Imperial College of Science, Technology & Medicine
   5 .\" Copyright (c) 1990 The Regents of the University of California.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This code is derived from software contributed to Berkeley by
   9 .\" Jan-Simon Pendry at Imperial College, London.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. All advertising materials mentioning features or use of this software
  20 .\"    must display the following acknowledgment:
  21 .\"      This product includes software developed by the University of
  22 .\"      California, Berkeley and its contributors.
  23 .\" 4. Neither the name of the University nor the names of its contributors
  24 .\"    may be used to endorse or promote products derived from this software
  25 .\"    without specific prior written permission.
  26 .\"
  27 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  28 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  29 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  30 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  31 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  32 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  33 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  34 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  35 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  36 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  37 .\" SUCH DAMAGE.
  38 .\"
  39 .\"     %W% (Berkeley) %G%
  40 .\"
  41 .\" $Id: amd.conf.5,v 1.39.2.5 2006/04/21 01:12:04 ezk Exp $
  42 .\" $FreeBSD$
  43 .\"
  44 .Dd April 21, 2006
  45 .Dt AMD.CONF 5
  46 .Os
  47 .Sh NAME
  48 .Nm amd.conf
  49 .Nd
  50 .Xr amd 8
  51 configuration file
  52 .Sh SYNOPSIS
  53 .Nm
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 file is the configuration file for
  58 .Xr amd 8 ,
  59 as part of the am-utils suite.
  60 .Pp
  61 The
  62 .Nm
  63 file
  64 contains runtime configuration information for the
  65 .Xr amd 8
  66 automounter program.
  67 .Sh FILE FORMAT
  68 The file consists of sections and parameters.
  69 A section begins with the
  70 name of the section in square brackets and continues until the next section
  71 begins or the end of the file is reached.
  72 Sections contain parameters of the
  73 form
  74 .Dq Ar name No = Ar value .
  75 .Pp
  76 The file is line-based \[em] that is, each newline-terminated line represents
  77 either a comment, a section name or a parameter.
  78 No line-continuation
  79 syntax is available.
  80 .Pp
  81 Section, parameter names and their values are case sensitive.
  82 .Pp
  83 Only the first equals sign in a parameter is significant.
  84 Whitespace before
  85 or after the first equals sign is discarded.
  86 Leading, trailing and
  87 internal whitespace in section and parameter names is irrelevant.
  88 Leading
  89 and trailing whitespace in a parameter value is discarded.
  90 Internal
  91 whitespace within a parameter value is not allowed, unless the whole
  92 parameter value is quoted with double quotes as in
  93 .Dq Ar name No = Qq Li "some\ value" .
  94 .Pp
  95 Any line beginning with a pound sign (#) is ignored, as are lines containing
  96 only whitespace.
  97 .Pp
  98 The values following the equals sign in parameters are all either a string
  99 (no quotes needed if string does not include spaces) or a boolean, which may
 100 be given as
 101 .Dq Li yes/no .
 102 Case is significant in all values.
 103 Some items such as
 104 cache timeouts are numeric.
 105 .Sh SECTIONS
 106 .Ss "The [global] section"
 107 Parameters in this section either apply to
 108 .Nm amd
 109 as a whole, or to all other
 110 regular map sections which follow.
 111 There should be only one global section
 112 defined in one configuration file.
 113 .Pp
 114 It is highly recommended that this section be specified first in the
 115 configuration file.
 116 If it is not, then regular map sections which precede
 117 it will not use global values defined later.
 118 .Ss "Regular [/map] sections"
 119 Parameters in regular (non-global) sections apply to a single map entry.
 120 For example, if the map section
 121 .Bq Pa /homes
 122 is defined, then all parameters following it will be applied to the
 123 .Pa /homes
 124 .Nm amd Ns
 125 -managed mount point.
 126 .Sh PARAMETERS
 127 .Ss "Parameters common to all sections"
 128 These parameters can be specified either in the global or a map specific
 129 section.
 130 Entries specified in a map-specific section override the default
 131 value or one defined in the global section.
 132 If such a common parameter is
 133 specified only in the global section, it is applicable to all regular map
 134 sections that follow.
 135 .Bl -tag -width 4n
 136 .It Va browsable_dirs Pq string, default=no
 137 If
 138 .Dq Li yes ,
 139 then
 140 .Nm amd Ns 's
 141 top-level mount points will be browsable to
 142 .Xr readdir 3
 143 calls.
 144 This means you could run for example
 145 .Xr ls 1
 146 and see what keys are available to mount in that directory.
 147 Not all entries
 148 are made visible to
 149 .Xr readdir 3 :
 150 the
 151 .Dq Li /default
 152 entry, wildcard entries, and those with a
 153 .Ql /
 154 in them are not included.
 155 If you specify
 156 .Dq Li full
 157 to this option, all but
 158 .Dq Li /default
 159 will be visible.
 160 Note that if you run a command which will attempt to
 161 .Xr stat 2
 162 the entries, such as often done by
 163 .Dq Li "ls -l"
 164 or
 165 .Dq Li "ls -F" ,
 166 .Xr amd 8
 167 will attempt to mount
 168 .Em every
 169 entry in that map.
 170 This is often called a
 171 .Dq "mount storm" .
 172 .It Va map_defaults Pq string, default no empty
 173 This option sets a string to be used as the map's /defaults entry,
 174 overriding any /defaults specified in the map.
 175 This allows local users to
 176 override map defaults without modifying maps globally.
 177 .It Va map_options Pq string, default no options
 178 This option is the same as specifying map options on the command line to
 179 .Xr amd 8 ,
 180 such as
 181 .Dq Li "cache:=all" .
 182 .It Va map_type Pq string, default search all map types
 183 If specified,
 184 .Xr amd 8
 185 will initialize the map only for the type given.
 186 This is
 187 useful to avoid the default map search type used by
 188 .Xr amd 8
 189 which takes longer
 190 and can have undesired side-effects such as initializing
 191 .Tn NIS
 192 even if not
 193 used.
 194 Possible values are:
 195 .Pp
 196 .Bl -tag -width ".Cm nisplus" -compact
 197 .It Cm exec
 198 executable maps
 199 .It Cm file
 200 plain files
 201 .It Cm hesiod
 202 Hesiod name service from MIT
 203 .It Cm ldap
 204 Lightweight Directory Access Protocol
 205 .It Cm ndbm
 206 (New) dbm style hash files
 207 .It Cm nis
 208 Network Information Services (version 2)
 209 .It Cm nisplus
 210 Network Information Services Plus (version 3)
 211 .It Cm passwd
 212 local password files
 213 .It Cm union
 214 union maps
 215 .El
 216 .It Va mount_type Pq string, default=nfs
 217 All
 218 .Xr amd 8
 219 mount types default to
 220 .Tn NFS .
 221 That is,
 222 .Xr amd 8
 223 is an
 224 .Tn NFS
 225 server on the
 226 map mount points, for the local host it is running on.
 227 If
 228 .Dq Li autofs
 229 is specified,
 230 .Xr amd 8
 231 will be an autofs server for those mount points.
 232 .It Va autofs_use_lofs Pq string, default=yes
 233 When set to
 234 .Dq Li yes
 235 and using Autofs,
 236 .Xr amd 8
 237 will use lofs-type (loopback) mounts
 238 for type:=link mounts.
 239 This has the advantage of mounting in place, and
 240 users get to the see the same pathname that they chdir'ed into.
 241 If this
 242 option is set to
 243 .Dq Li no ,
 244 then
 245 .Xr amd 8
 246 will use symlinks instead: that code is more
 247 tested, but negates autofs's big advantage of in-place mounts.
 248 .It Va search_path Pq string, default no search path
 249 This provides a (colon-delimited) search path for file maps.
 250 Using a search
 251 path, sites can allow for local map customizations and overrides, and can
 252 query
 253 distributed maps in several locations as needed.
 254 .It Va selectors_in_defaults Pq boolean, default=no
 255 If
 256 .Dq Li yes ,
 257 then the /defaults entry of maps will search for and process any
 258 selectors before setting defaults for all other keys in that map.
 259 Useful
 260 when you want to set different options for a complete map based on some
 261 parameters.
 262 For example, you may want to better the NFS performance over
 263 slow slip-based networks as follows:
 264 .Bd -literal
 265 /defaults \\
 266         wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \\
 267         wire!=slip-net;opts:=intr,rsize=8192,wsize=8192
 268 .Ed
 269 Deprecated form: selectors_on_default
 270 .El
 271 .Ss "Parameters applicable to the global section only"
 272 .Bl -tag -width 4n
 273 .It Va arch Pq string, default to compiled in value
 274 Same as the
 275 .Fl A
 276 option to
 277 .Xr amd 8 .
 278 Allows you to override the value of the
 279 .Va arch
 280 .Xr amd 8
 281 variable.
 282 .It Va auto_attrcache Pq numeric, default=0
 283 Specify in seconds (or units of 0.1 seconds, depending on the OS), what is
 284 the (kernel-side) NFS attribute cache timeout for
 285 .Nm amd Ns 's
 286 own automount
 287 points.
 288 A value of 0 is supposed to turn off attribute caching, meaning
 289 that
 290 .Xr amd 8
 291 will be consulted via a kernel-RPC each time someone stat()'s
 292 the mount point (which could be abused as a denial-of-service attack).
 293 Warning: some OSs are incapable of turning off the NFS attribute cache
 294 reliably.
 295 On such systems,
 296 .Nm amd
 297 may not work reliably under heavy load.
 298 See
 299 the
 300 .Pa README.attrcache
 301 document in the Am-utils distribution for more details.
 302 .It Va auto_dir Pq string, default= Ns Pa /a
 303 Same as the
 304 .Fl a
 305 option to
 306 .Xr amd 8 .
 307 This sets the private directory where
 308 .Nm amd
 309 will create
 310 sub-directories for its real mount points.
 311 .It Va cache_duration Pq numeric, default=300
 312 Same as the
 313 .Fl c
 314 option to
 315 .Xr amd 8 .
 316 Sets the duration in seconds that looked-up or mounted map
 317 entries remain in the cache.
 318 .It Va cluster Pq string, default no cluster
 319 Same as the
 320 .Fl C
 321 option to
 322 .Xr amd 8 .
 323 Specifies the alternate
 324 .Tn HP-UX
 325 cluster to use.
 326 .It Va debug_mtab_file Pq string, default= Ns Pa /tmp/mnttab
 327 Path to mtab file that is used by
 328 .Xr amd 8
 329 to store a list of mounted
 330 file systems during debug-mtab mode.
 331 This option only applies
 332 to systems that store mtab information on disk.
 333 .It Va debug_options Pq string, default no debug options
 334 Same as the
 335 .Fl D
 336 option to
 337 .Xr amd 8 .
 338 Specify any debugging options for
 339 .Xr amd 8 .
 340 Works only if
 341 am-utils was configured for debugging using the
 342 .Fl Fl enable-debug
 343 option.
 344 The
 345 .Cm mem
 346 option alone can be turned on via
 347 .Fl Fl enable-debug Ns = Ns Cm mem .
 348 Otherwise debugging options are ignored.
 349 Options are
 350 comma delimited, and can be preceded by the string
 351 .Dq Li no
 352 to negate their
 353 meaning.
 354 You can get the list of supported debugging options by running
 355 .Nm amd Fl v .
 356 Possible values are:
 357 .Pp
 358 .Bl -tag -width ".Cm xdrtrace" -compact
 359 .It Cm all
 360 all options
 361 .It Cm amq
 362 register for
 363 .Xr amq 8
 364 .It Cm daemon
 365 enter daemon mode
 366 .It Cm fork
 367 fork server
 368 .It Cm full
 369 program trace
 370 .It Cm info
 371 info service specific debugging
 372 (hesiod, nis, etc.)
 373 .It Cm mem
 374 trace memory allocations
 375 .It Cm mtab
 376 use local
 377 .Pa ./mtab
 378 file
 379 .It Cm str
 380 debug string munging
 381 .It Cm test
 382 full debug but no daemon
 383 .It Cm trace
 384 trace protocol and NFS mount arguments
 385 .It Cm xdrtrace
 386 trace XDR routines
 387 .El
 388 .It Va dismount_interval Pq numeric, default=120
 389 Same as the
 390 .Fl w
 391 option to
 392 .Xr amd 8 .
 393 Specify, in seconds, the time between attempts to dismount
 394 file systems that have exceeded their cached times.
 395 .It Va domain_strip Pq boolean, default=yes
 396 If
 397 .Dq Li yes ,
 398 then the domain
 399 name part referred to by ${rhost} is stripped off.
 400 This is
 401 useful to keep logs and smaller.
 402 If
 403 .Dq Li no ,
 404 then the domain name
 405 part is left changed.
 406 This is useful when using multiple domains with
 407 the same maps (as you may have hosts whose domain-stripped name is
 408 identical).
 409 .It Va exec_map_timeout Pq numeric, default=10
 410 The timeout in seconds that
 411 .Xr amd 8
 412 will wait for an executable map program before an answer is returned from
 413 that program (or script).
 414 This value should be set to as small as possible
 415 while still allowing normal replies to be returned before the timer expires,
 416 because during the time that the executable map program is queried,
 417 .Xr amd 8
 418 is essentially waiting and is thus not responding to any other queries.
 419 .It Va forced_unmounts Pq boolean, default=no
 420 If set to
 421 .Dq Li yes ,
 422 and the client OS supports forced or lazy unmounts, then
 423 .Xr amd 8
 424 will attempt to use them if it gets any of three serious error conditions
 425 when trying to unmount an existing mount point or mount on top of one:
 426 .Er EIO , ESTALE ,
 427 or
 428 .Er EBUSY .
 429 .Pp
 430 This could be useful to recover from serious conditions such as hardware
 431 failure of mounted disks, or NFS servers which are down permanently, were
 432 migrated, or changed their IP address.
 433 Only
 434 .Dq Li type:=toplvl
 435 mounts hung with
 436 .Er EBUSY
 437 are forcibly unmounted using this option, which is useful to recover
 438 from a hung
 439 .Xr amd 8 ) .
 440 .It Va full_os Pq string, default to compiled in value
 441 The full name of the operating system, along with its version.
 442 Allows you
 443 to override the compiled-in full name and version of the operating system.
 444 Useful when the compiled-in name is not desired.
 445 For example, the full
 446 operating system name on Linux comes up as
 447 .Dq Li linux ,
 448 but you can override it to
 449 .Dq Li linux-2.2.5 .
 450 .It Va fully_qualified_hosts Pq string, default=no
 451 If
 452 .Dq Li yes ,
 453 .Xr amd 8
 454 will perform RPC authentication using fully-qualified host names.
 455 This is
 456 necessary for some systems, and especially when performing cross-domain
 457 mounting.
 458 For this function to work, the
 459 .Xr amd 8
 460 variable ${hostd} is used, requiring that ${domain} not be null.
 461 .It Va hesiod_base Pq string, default=automount
 462 Specify the base name for hesiod maps.
 463 .It Va karch Pq string, default to karch of the system
 464 Same as the
 465 .Fl k
 466 option to
 467 .Xr amd 8 .
 468 Allows you to override the kernel-architecture of your
 469 system.
 470 Useful for example on Sun (Sparc) machines, where you can build one
 471 .Nm amd
 472 binary and run it on multiple machines, yet you want each one to get
 473 the correct
 474 .Va karch
 475 variable set (for example, sun4c, sun4m, sun4u, etc.)
 476 Note that if not
 477 specified,
 478 .Xr amd 8
 479 will use
 480 .Xr uname 3
 481 to figure out the kernel architecture of
 482 the machine.
 483 .It Va ldap_base Pq string, default not set
 484 Specify the base name for LDAP.
 485 This often includes LDAP-specific
 486 values such as country and organization.
 487 .It Va ldap_cache_maxmem Pq numeric, default=131072
 488 Specify the maximum memory
 489 .Xr amd 8
 490 should use to cache LDAP entries.
 491 .It Va ldap_cache_seconds Pq numeric, default=0
 492 Specify the number of seconds to keep entries in the cache.
 493 .It Va ldap_hostports Pq string, default not set
 494 Specify the LDAP host and port values.
 495 .It Va ldap_proto_version Pq numeric, default=2
 496 Specify the version of the LDAP protocol to use.
 497 .It Va local_domain Pq string, default no sub-domain
 498 Same as the
 499 .Fl d
 500 option to
 501 .Xr amd 8 .
 502 Specify the local domain name.
 503 If this option is not given
 504 the domain name is determined from the hostname by removing the first
 505 component of the fully-qualified host name.
 506 .It Va localhost_address Pq string, default to localhost or 127.0.0.1
 507 Specify the name or IP address for
 508 .Xr amd 8
 509 to use when connecting the sockets
 510 for the local NFS server and the RPC server.
 511 This defaults to 127.0.0.1 or
 512 whatever the host reports as its local address.
 513 This parameter is useful on
 514 hosts with multiple addresses where you want to force
 515 .Xr amd 8
 516 to connect to a
 517 specific address.
 518 .It Va log_file Pq string, default= Ns Pa /dev/stderr
 519 Same as the
 520 .Fl l
 521 option to
 522 .Xr amd 8 .
 523 Specify a file name to log
 524 .Xr amd 8
 525 events to.
 526 If the string
 527 .Pa /dev/stderr
 528 is specified,
 529 .Xr amd 8
 530 will send its events to the standard error file descriptor.
 531 If the string
 532 .Pa syslog
 533 is given,
 534 .Xr amd 8
 535 will record its events with the system logger
 536 .Xr syslogd 8 .
 537 The default syslog facility used is
 538 .Dv LOG_DAEMON .
 539 If you
 540 wish to change it, append its name to the log file name, delimited by a
 541 single colon.
 542 For example, if
 543 .Pa logfile
 544 is the string
 545 .Dq Li syslog:local7
 546 then
 547 .Xr amd 8
 548 will log messages via
 549 .Xr syslog 3
 550 using the
 551 .Dv LOG_LOCAL7
 552 facility (if it exists on the system).
 553 .It Va log_options Pq string, default no logging options
 554 Same as the
 555 .Fl x
 556 option to
 557 .Xr amd 8 .
 558 Specify any logging options for
 559 .Xr amd 8 .
 560 Options are comma
 561 delimited, and can be preceded by the string
 562 .Dq Li no
 563 to negate their meaning.
 564 The
 565 .Dq Li debug
 566 logging option is only available if am-utils was configured with
 567 .Fl Fl enable-debug .
 568 You can get the list of supported debugging and logging
 569 options by running
 570 .Nm amd Fl H .
 571 Possible values are:
 572 .Pp
 573 .Bl -tag -width ".Cm warning" -compact
 574 .It Cm all
 575 all messages
 576 .It Cm debug
 577 debug messages
 578 .It Cm error
 579 non-fatal system errors
 580 .It Cm fatal
 581 fatal errors
 582 .It Cm info
 583 information
 584 .It Cm map
 585 map errors
 586 .It Cm stats
 587 additional statistical information
 588 .It Cm user
 589 non-fatal user errors
 590 .It Cm warn
 591 warnings
 592 .It Cm warning
 593 warnings
 594 .El
 595 .It Va map_reload_interval Pq numeric, default=3600
 596 The number of seconds that
 597 .Xr amd 8
 598 will wait before it checks to see if any maps
 599 have changed at their source (NIS servers, LDAP servers, files, etc.).
 600 .Xr amd 8
 601 will reload only those maps that have changed.
 602 .It Va nfs_allow_any_interface Pq string, default=no
 603 Normally
 604 .Xr amd 8
 605 accepts local NFS packets only from 127.0.0.1.
 606 If this
 607 parameter is set to
 608 .Dq Li yes
 609 then
 610 .Xr amd 8
 611 will accept local NFS packets from any
 612 local interface; this is useful on hosts that may have multiple interfaces
 613 where the system is forced to send all outgoing packets (even those bound to
 614 the same host) via an address other than 127.0.0.1.
 615 .It Va nfs_allow_insecure_port Pq string, default=no
 616 Normally
 617 .Xr amd 8
 618 will refuse requests coming from unprivileged ports (i.e.\&
 619 ports >= 1024 on Unix systems), so that only privileged users and the kernel
 620 can send NFS requests to it.
 621 However, some kernels (certain versions of
 622 Darwin, MacOS X, and Linux) have bugs that cause them to use unprivileged
 623 ports in certain situations, which causes
 624 .Xr amd 8
 625 to stop dead in its tracks.
 626 This parameter allows
 627 .Xr amd 8
 628 to operate normally even on such systems, at the
 629 expense of a slight decrease in the security of its operations.
 630 If you see
 631 messages like
 632 .Dq Li "ignoring request from foo:1234, port not reserved"
 633 in your
 634 .Xr amd 8
 635 log, try enabling this parameter and give it another go.
 636 .It Va nfs_proto Pq string, default to trying version tcp then udp
 637 By default,
 638 .Xr amd 8
 639 tries TCP and then UDP.
 640 This option forces the overall
 641 .Tn NFS
 642 protocol used to TCP or UDP.
 643 It overrides what is in the
 644 .Xr amd 8
 645 maps, and is
 646 useful when
 647 .Nm amd
 648 is compiled with NFSv3 support that may not be stable.
 649 With
 650 this option you can turn off the complete usage of NFSv3 dynamically
 651 (without having to recompile
 652 .Nm amd )
 653 until such time as NFSv3 support is
 654 desired again.
 655 .It Va nfs_retransmit_counter Pq numeric, default=11
 656 Same as the
 657 .Ar retransmit
 658 counter
 659 part of the
 660 .Fl t Ar timeout.retransmit
 661 option to
 662 .Xr amd 8 .
 663 Specifies the number of NFS retransmissions that the kernel will use to
 664 communicate with
 665 .Xr amd 8 .
 666 .It Va nfs_retransmit_counter_udp Pq numeric, default=11
 667 Same as the
 668 .Va nfs_retransmit_counter
 669 option, but for all UDP mounts only.
 670 .It Va nfs_retransmit_counter_tcp Pq numeric, default=11
 671 Same as the
 672 .Va nfs_retransmit_counter
 673 option, but for all TCP mounts only.
 674 .It Va nfs_retransmit_counter_toplvl Pq numeric, default=11
 675 Same as the
 676 .Va nfs_retransmit_counter
 677 option, but only for
 678 .Nm amd Ns 's
 679 top-level UDP mounts.
 680 .It Va nfs_retry_interval Pq numeric, default=8
 681 Same as the
 682 .Ar timeout
 683 interval
 684 part of the
 685 .Fl t Ar timeout.retransmit
 686 option to
 687 .Xr amd 8 .
 688 Specifies the
 689 .Tn NFS
 690 timeout interval, in
 691 .Em tenths
 692 of seconds, between NFS/RPC retries (for UDP and TCP).
 693 This is the value that the kernel will use to
 694 communicate with
 695 .Xr amd 8 .
 696 .Pp
 697 .Xr amd 8
 698 relies on the kernel RPC retransmit mechanism to trigger mount retries.
 699 The values of the
 700 .Va nfs_retransmit_counter
 701 and the
 702 .Va nfs_retry_interval
 703 parameters change the overall retry interval.
 704 Too long an interval gives
 705 poor interactive response; too short an interval causes excessive retries.
 706 .It Va nfs_retry_interval_udp Pq numeric, default=8
 707 Same as the
 708 .Va nfs_retry_interval
 709 option, but for all UDP mounts only.
 710 .It Va nfs_retry_interval_tcp Pq numeric, default=8
 711 Same as the
 712 .It nfs_retry_interval
 713 option, but for all TCP mounts only.
 714 .It Va nfs_retry_interval_toplvl Pq numeric, default=8
 715 Same as the
 716 .It nfs_retry_interval
 717 option, but only for
 718 .Nm amd Ns 's
 719 top-level UDP mounts.
 720 .It Va nfs_vers Pq numeric, default to trying version 3 then 2
 721 By default,
 722 .Xr amd 8
 723 tries version 3 and then version 2.
 724 This option forces the
 725 overall
 726 .Tn NFS
 727 protocol used to version 3 or 2.
 728 It overrides what is in the
 729 .Xr amd 8
 730 maps, and is useful when
 731 .Nm amd
 732 is compiled with NFSv3 support that may not
 733 be stable.
 734 With this option you can turn off the complete usage of NFSv3
 735 dynamically (without having to recompile
 736 .Nm amd )
 737 until such time as NFSv3
 738 support is desired again.
 739 .It Va nis_domain Pq string, default to local Tn NIS domain name
 740 Same as the
 741 .Fl y
 742 option to
 743 .Xr amd 8 .
 744 Specify an alternative
 745 .Tn NIS
 746 domain from which to fetch the
 747 .Tn NIS
 748 maps.
 749 The default is the system domain name.
 750 This option is ignored if
 751 .Tn NIS
 752 support is not available.
 753 .It Va normalize_hostnames Pq boolean, default=no
 754 Same as the
 755 .Fl n
 756 option to
 757 .Xr amd 8 .
 758 If
 759 .Dq Li yes ,
 760 then the name referred to by
 761 .Va ${rhost}
 762 is normalized relative to the host database before being used.
 763 The effect is
 764 to translate aliases into
 765 .Dq official
 766 names.
 767 .It Va normalize_slashes Pq boolean, default=yes
 768 If
 769 .Dq Li yes ,
 770 then
 771 .Xr amd 8
 772 will condense all multiple
 773 .Ql /
 774 (slash) characters into
 775 one and remove all trailing slashes.
 776 If
 777 .Dq Li no ,
 778 then
 779 .Xr amd 8
 780 will not touch
 781 strings that may contain repeated or trailing slashes.
 782 The latter is
 783 sometimes useful with SMB mounts, which often require multiple slash
 784 characters in pathnames.
 785 .It Va os Pq string, default to compiled in value
 786 Same as the
 787 .Fl O
 788 option to
 789 .Xr amd 8 .
 790 Allows you to override the compiled-in name of the operating
 791 system.
 792 Useful when the built-in name is not desired for backward
 793 compatibility reasons.
 794 For example, if the build in name is
 795 .Dq Li sunos5 ,
 796 you can override it to
 797 .Dq Li sos5 ,
 798 and use older maps which were written with the
 799 latter in mind.
 800 .It Va osver Pq string, default to compiled in value
 801 Same as the
 802 .Fl o
 803 option to
 804 .Xr amd 8 .
 805 Overrides the compiled-in version number of the operating
 806 system.
 807 Useful when the built in version is not desired for backward
 808 compatibility reasons.
 809 For example, if the build in version is
 810 .Dq Li 2.5.1 ,
 811 you can override it to
 812 .Dq Li 5.5.1 ,
 813 and use older maps that were written with
 814 the latter in mind.
 815 .It Va pid_file Pq string, default= Ns Pa /dev/stdout
 816 Specify a file to store the process ID of the running daemon into.
 817 If not
 818 specified,
 819 .Xr amd 8
 820 will print its process ID onto the standard output.
 821 Useful
 822 for killing
 823 .Xr amd 8
 824 after it had run.
 825 Note that the PID of a running
 826 .Nm amd
 827 can
 828 also be retrieved via
 829 .Nm amq Fl p .
 830 This file is used only if the
 831 .Va print_pid
 832 option is on.
 833 .It Va plock Pq boolean, default=yes
 834 Same as the
 835 .Fl S
 836 option to
 837 .Xr amd 8 .
 838 If
 839 .Dq Li yes ,
 840 lock the running executable pages of
 841 .Nm amd
 842 into memory.
 843 To improve
 844 .Nm amd Ns 's
 845 performance, systems that support the
 846 .Xr plock 3
 847 or
 848 .Xr mlockall 2
 849 call can lock the
 850 .Nm amd
 851 process into memory.
 852 This way there is less chance that
 853 the operating system will schedule, page out, and swap the
 854 .Nm amd
 855 process as needed.
 856 This improves
 857 .Nm amd Ns 's
 858 performance, at the cost of reserving the
 859 memory used by the
 860 .Nm amd
 861 process (making it unavailable for other processes).
 862 .It Va portmap_program Pq numeric, default=300019
 863 Specify an alternate Port-mapper RPC program number, other than the official
 864 number.
 865 This is useful when running multiple
 866 .Nm amd
 867 processes.
 868 For example,
 869 you can run another
 870 .Xr amd 8
 871 in
 872 .Dq test
 873 mode, without affecting the primary
 874 .Nm amd
 875 process in any way.
 876 For safety reasons, the alternate program numbers that
 877 can be specified must be in the range 300019-300029, inclusive.
 878 The
 879 .Xr amq 8
 880 utility
 881 has an option
 882 .Fl P
 883 which can be used to specify an alternate program number of an
 884 .Nm amd
 885 to contact.
 886 In this way,
 887 .Nm amq
 888 can fully control any number of
 889 .Nm amd
 890 processes running on the same host.
 891 .It Va preferred_amq_port Pq numeric, default=0
 892 Specify an alternate Port-mapper RPC port number for
 893 .Nm amd Ns 's
 894 .Xr amq 8
 895 service.
 896 This is used for both UDP and TCP.
 897 Setting this value to 0 (or
 898 not defining it) will cause
 899 .Xr amd 8
 900 to select an arbitrary port number.
 901 Setting the
 902 .Xr amq 8
 903 RPC service port to a specific number is useful in firewalled or NAT'ed
 904 environments, where you need to know which port
 905 .Xr amd 8
 906 will listen on.
 907 .It Va print_pid Pq boolean, default=no
 908 Same as the
 909 .Fl p
 910 option to
 911 .Xr amd 8 .
 912 If
 913 .Dq Li yes ,
 914 .Nm amd
 915 will print its process ID upon starting.
 916 .It Va print_version Pq boolean, default=no
 917 Same as the
 918 .Fl v
 919 option to
 920 .Xr amd 8 ,
 921 but the version prints and
 922 .Nm amd
 923 continues to run.
 924 If
 925 .Dq Li yes ,
 926 .Nm amd
 927 will print its version information string, which includes some
 928 configuration and compilation values.
 929 .It Va restart_mounts Pq boolean, default=no
 930 Same as the
 931 .Fl r
 932 option to
 933 .Xr amd 8 .
 934 If
 935 .Dq Li yes ,
 936 .Nm amd
 937 will scan the mount table to determine which file systems are currently
 938 mounted.
 939 Whenever one of these would have been auto-mounted,
 940 .Nm amd
 941 inherits it.
 942 .It Va show_statfs_entries Pq boolean, default=no
 943 If
 944 .Dq Li yes ,
 945 then all maps which are browsable will also show the number of
 946 entries (keys) they have when
 947 .Xr df 1
 948 runs.
 949 (This is accomplished by returning
 950 non-zero values to the
 951 .Xr statfs 2
 952 system call.)
 953 .It Va truncate_log Pq boolean, default=no
 954 If
 955 .Dq Li yes ,
 956 then the log file (if it is a regular file), will be truncated
 957 upon startup.
 958 .It Va unmount_on_exit Pq boolean, default=no
 959 If
 960 .Dq Li yes ,
 961 then
 962 .Xr amd 8
 963 will attempt to unmount all file systems which it knows
 964 about.
 965 Normally
 966 .Nm amd
 967 leaves all
 968 (esp.\&
 969 .Tn NFS )
 970 mounted file systems intact.
 971 Note that
 972 .Nm amd
 973 does not know about file systems mounted before it starts up,
 974 unless the
 975 .Va restart_mounts
 976 option or
 977 .Fl r
 978 flag are used.
 979 .It Va use_tcpwrappers Pq boolean, default=yes
 980 If
 981 .Dq Li yes ,
 982 then
 983 .Xr amd 8
 984 will use the tcpd/libwrap tcpwrappers library
 985 (if available) to control
 986 access to
 987 .Nm amd
 988 via the
 989 .Pa /etc/hosts.allow
 990 and
 991 .Pa /etc/hosts.deny
 992 files.
 993 .It Va vendor Pq string, default to compiled in value
 994 The name of the vendor of the operating system.
 995 Overrides the compiled-in
 996 vendor name.
 997 Useful when the compiled-in name is not desired.
 998 For example,
 999 most Intel based systems set the vendor name to
1000 .Dq Li unknown ,
1001 but you can set it to
1002 .Dq Li redhat .
1003 .El
1004 .Ss "Parameters applicable to regular map sections"
1005 .Bl -tag -width 4n
1006 .It Va map_name Pq string, must be specified
1007 Name of the map where the keys are located.
1008 .It Va tag Pq string, default no tag
1009 Each map entry in the configuration file can be tagged.
1010 If no tag is
1011 specified, that map section will always be processed by
1012 .Xr amd 8 .
1013 If it is
1014 specified, then
1015 .Nm amd
1016 will process the map if the
1017 .Fl T
1018 option was given to
1019 .Xr amd 8 ,
1020 and the value given to that command-line option
1021 matches that in the map section.
1022 .El
1023 .Sh EXAMPLES
1024 Here is a real
1025 .Xr amd 8
1026 configuration I use daily.
1027 .Bd -literal
1028 # GLOBAL OPTIONS SECTION
1029 [ global ]
1030 normalize_hostnames =    no
1031 print_pid =              no
1032 restart_mounts =         yes
1033 auto_dir =               /n
1034 log_file =               /var/log/amd
1035 log_options =            all
1036 #debug_options =         all
1037 plock =                  no
1038 selectors_in_defaults =  yes
1039 # config.guess picks up "sunos5" and I don't want to edit my maps yet
1040 os =                     sos5
1041 # if you print_version after setting up "os", it will show it.
1042 print_version =          no
1043 map_type =               file
1044 search_path =            /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib
1045 browsable_dirs =         yes
1046
1047 # DEFINE AN AMD MOUNT POINT
1048 [ /u ]
1049 map_name =               amd.u
1050
1051 [ /proj ]
1052 map_name =               amd.proj
1053
1054 [ /src ]
1055 map_name =               amd.src
1056
1057 [ /misc ]
1058 map_name =               amd.misc
1059
1060 [ /import ]
1061 map_name =               amd.import
1062
1063 [ /tftpboot/.amd ]
1064 tag =                    tftpboot
1065 map_name =               amd.tftpboot
1066 .Ed
1067 .Sh SEE ALSO
1068 .Xr hosts_access 5 ,
1069 .Xr amd 8 ,
1070 .Xr amq 8
1071 .Pp
1072 .Dq am-utils
1073 .Xr info 1
1074 entry.
1075 .Rs
1076 .%A Erez Zadok
1077 .%B "Linux NFS and Automounter Administration"
1078 .%O ISBN 0-7821-2739-8
1079 .%I Sybex
1080 .%D 2001
1081 .Re
1082 .Pp
1083 .Pa http://www.am-utils.org/
1084 .Rs
1085 .%T Amd \- The 4.4 BSD Automounter
1086 .Re
1087 .Sh HISTORY
1088 The
1089 .Xr amd 8
1090 utility first appeared in
1091 .Bx 4.4 .
1092 .Sh AUTHORS
1093 .An Erez Zadok Aq ezk@cs.sunysb.edu ,
1094 Computer Science Department, Stony Brook University, Stony Brook, New York, USA.
1095 .Pp
1096 Other authors and contributors to am-utils are listed in the
1097 .Pa AUTHORS
1098 file distributed with am-utils.