contrib/amd/scripts/amd.conf.5

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