contrib/amd/scripts/amd.conf.5

   1 .\"
   2 .\" Copyright (c) 1997-1999 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.3 1999/03/30 17:23:08 ezk Exp $
  42 .\" $FreeBSD$
  43 .\"
  44 .Dd April 7, 1997
  45 .Dt AMD.CONF 5
  46 .Os
  47 .Sh NAME
  48 .Nm amd.conf
  49 .Nd amd configuration file
  50 .Sh SYNOPSIS
  51 .Nm amd.conf
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 file is the configuration file for amd, as part of the am-utils suite.
  56 .Pp
  57 .Nm
  58 contains runtime configuration information for the
  59 .Nm amd
  60 automounter program.
  61 .Sh FILE FORMAT
  62 The file consists of sections and parameters.  A section begins with the
  63 name of the section in square brackets and continues until the next section
  64 begins or the end of the file is reached.  Sections contain parameters of
  65 the form
  66 .Sq name = value .
  67 .Pp
  68 The file is line-based - that is, each newline-terminated line represents
  69 either a comment, a section name or a parameter.  No line-continuation
  70 syntax is available.
  71 .Pp
  72 Section, parameter names and their values are case sensitive.
  73 .Pp
  74 Only the first equals sign in a parameter is significant.  Whitespace before
  75 or after the first equals sign is discarded.  Leading, trailing and
  76 internal whitespace in section and parameter names is irrelevant.  Leading
  77 and trailing whitespace in a parameter value is discarded.  Internal
  78 whitespace within a parameter value is not allowed, unless the whole
  79 parameter value is quoted with double quotes as in
  80 .So name =
  81 .Qq some value
  82 .Sc .
  83 .Pp
  84 Any line beginning with a pound sign (#) is ignored, as are lines containing
  85 only whitespace.
  86 .Pp
  87 The values following the equals sign in parameters are all either a string
  88 (no quotes needed if string does not include spaces) or a boolean, which may
  89 be given as yes/no.  Case is significant in all values.  Some items such as
  90 cache timeouts are numeric.
  91 .Sh SECTIONS
  92 .Bl -tag -width 4n
  93 .It Nm The [global] section
  94 Parameters in this section either apply to
  95 .Nm amd
  96 as a whole, or to all other regular map sections which follow.  There
  97 should be only one global section defined in one configuration file.
  98 .Pp
  99 It is highly recommended that this section be specified first in the
 100 configuration file.  If it is not, then regular map sections which precede
 101 it will not use global values defined later.
 102 .It Nm Regular [/map] sections
 103 Parameters in regular (non-global) sections apply to a single map entry.
 104 For example, if the map section
 105 .Bq Pa /homes
 106 is defined, then all parameters following it will be applied to the
 107 .Pa /homes
 108 amd-managed mount point.
 109 .El
 110 .Sh PARAMETERS
 111 .Bl -tag -width F1
 112 .It Sy Parameters common to all sections
 113 These parameters can be specified either in the global or a map specific
 114 section.  Entries specified in a map-specific section override the default
 115 value or one defined in the global section.   If such a common parameter is
 116 specified only in the global section, it is applicable to all regular map
 117 sections that follow.
 118 .Bl -tag -width F1
 119 .It Nm browsable_dirs (string, default=no)
 120 If
 121 .Qq yes ,
 122 then amd's top-level mount points will be browsable to
 123 .Xr readdir 3
 124 calls.  This means you could run for example
 125 .Xr ls 1
 126 and see what keys are available to mount in that directory.  Not all entries
 127 are made visible to
 128 .Xr readdir 3 :
 129 the
 130 .Qq Pa /default
 131 entry, wildcardentries, and those with a
 132 .Qq Pa /
 133 in them are not included.  If you specify
 134 .Qq full
 135 to this option, all but
 136 .Qq Pa /default
 137 will be visible.  Note that if you run a command which will attempt to
 138 .Xr stat 2
 139 the entries, such as often done by
 140 .Qq ls -l
 141 or
 142 .Qq ls -F ,
 143 .Nm amd
 144 will attempt to mount
 145 .Em every
 146 entry in that map.  This is often called a
 147 .Em mount storm .
 148 .It Nm map_options (string, default no options)
 149 This option is the same as specifying map options on the command line to
 150 .Nm amd ,
 151 such as
 152 .Ql cache\&:\&=all .
 153 .It Nm map_type (string, default search all map types)
 154 If specified, amd will initialize the map only for the type given.
 155 This is useful to avoid the default map search type used by amd which
 156 takes longer and can have undesired side-effects such as initializing
 157 NIS even if not used.  Possible values are:
 158 .Pp
 159 .Bl -tag -width 10n -compact
 160 .It Nm file
 161 plain files
 162 .It Nm hesiod
 163 Hesiod name service from MIT
 164 .It Nm ldap
 165 Lightweight Directory Access Protocol
 166 .It Nm ndbm
 167 (New) dbm style hash files
 168 .It Nm nis
 169 Network Information Services (version 2)
 170 .It Nm nisplus
 171 Network Information Services Plus (version 3)
 172 .It Nm passwd
 173 local password files
 174 .It Nm union
 175 union maps
 176 .El
 177 .It Nm mount_type (string, default=nfs)
 178 All amd mount types default to
 179 .Tn NFS .
 180 That is,
 181 .Nm amd
 182 is an
 183 .Tn NFS
 184 server on the map mount points, for the local host it is running on.  If
 185 .Qq autofs
 186 is specified, amd will be an autofs server for those mount points.
 187 .It Nm search_path (string, default no search path)
 188 This provides a
 189 .Pq colon-delimited
 190 search path for file maps.  Using a search path, sites can allow for
 191 local map customizations and overrides, and can distributed maps in
 192 several locations as needed.
 193 .El
 194 .It Nm Parameters applicable to the global section only
 195 .Bl -tag -width F1
 196 .It Nm arch (string, default to compiled in value)
 197 Allows you to override the value of the
 198 .Va arch
 199 .Nm amd
 200 variable.
 201 .It Nm auto_dir (string, default=/a)
 202 Same as the
 203 .Fl a
 204 option to
 205 .Nm amd .
 206 This sets the private directory where amd will create sub-directories for its
 207 real mount points.
 208 .It Nm cache_duration (numeric, default=300)
 209 Same as the
 210 .Fl c
 211 option to
 212 .Nm amd .
 213 Sets the duration in seconds that looked up map entries remain in the cache.
 214 .It Nm cluster (string, default no cluster)
 215 Same as the
 216 .Fl C
 217 option to
 218 .Nm amd .
 219 Specifies the alternate
 220 .Tm HP-UX
 221 cluster to use.
 222 .It Nm debug_options (string, default no debug options)
 223 Same as the
 224 .Fl D
 225 option to
 226 .Nm amd .
 227 Specify any debugging options for
 228 .Nm amd .
 229 Works only if am-utils was configured for debugging using the
 230 .Ic --enable-debug option .
 231 The
 232 .Qq mem
 233 option alone can be turned on via
 234 .Ic --enable-debug=mem .
 235 Otherwise debugging options are ignored.  Options are comma delimited, and can
 236 be preceded by the string
 237 .Qq no
 238 to negate their meaning.  You can get the list of supported debugging options
 239 by running
 240 .Nm amd Fl v .
 241 Possible values are:
 242 .Pp
 243 .Bl -tag -width 10n -compact
 244 .It Nm all
 245 all options
 246 .It Nm amq
 247 register for
 248 .Nm amq
 249 .It Nm daemon
 250 enter daemon mode
 251 .It Nm fork
 252 fork server
 253 .It Nm full
 254 program trace
 255 .It Nm info
 256 info service specific debugging
 257 .Pq hesiod, nis, etc.
 258 .It mem
 259 trace memory allocations
 260 .It Nm mtab
 261 use local
 262 .Pa ./mtab
 263 file
 264 .It Nm str
 265 debug string munging
 266 .It Nm test
 267 full debug but no daemon
 268 .It Nm trace
 269 protocol trace
 270 .El
 271 .It Nm dismount_interval (numeric, default=120)
 272 Same as the
 273 .Fl w
 274 option to
 275 .Nm amd .
 276 Specify, in seconds, the time between attempts to dismount file systems that
 277 have exceeded their cached times.
 278 .It Nm fully_qualified_hosts (string, default=no)
 279 If
 280 .Qq yes ,
 281 .Nm Amd
 282 will perform RPC authentication using fully-qualified host names.  This is
 283 necessary for some systems, and especially when performing cross-domain
 284 mounting.  For this function to work, the
 285 .Nm amd
 286 variable
 287 .Va ${hostd}
 288 is used, requiring that
 289 .Va ${domain}
 290 not be null.
 291 .It Nm hesiod_base (string, default=automount)
 292 Specify the base name for hesiod maps.
 293 .It Nm karch (string, default to karch of the system)
 294 Same as the
 295 .Fl k
 296 option to
 297 .Nm amd .
 298 Allows you to override the kernel-architecture of your system.  Useful for
 299 example on Sun
 300 .Pq Sparc
 301 machines, where you can build one
 302 .Nm amd
 303 binary and run it on multiple machines, yet you want each one to get the
 304 correct
 305 .Va karch
 306 variable set
 307 .Pq for example, sun4c, sun4m, sun4u, etc.
 308 Note that if not
 309 specified,
 310 .Nm amd
 311 will use
 312 .Xr uname 3
 313 to figure out the kernel architecture of the machine.
 314 .It Nm ldap_base (string, default not set)
 315 Specify the base name for LDAP.
 316 .It Nm ldap_cache_maxmem (numeric, default=131072)
 317 Specify the maximum memory amd should use to cache LDAP entries.
 318 .It Nm ldap_cache_seconds (numeric, default=0)
 319 Specify the number of seconds to keep entries in the cache.
 320 .It Nm ldap_hostports (string, default not set)
 321 Specify LDAP-specific values such as country and organization.
 322 .It Nm local_domain (string, default no sub-domain)
 323 Same as the
 324 .Fl d
 325 option to
 326 .Nm amd .
 327 Specify the local domain name.  If this option is not given the domain name is
 328 determined from the hostname by removing the first component of the
 329 fully-qualified host name.
 330 .It Nm log_file (string, default=/dev/stderr)
 331 Same as the
 332 .Fl l
 333 option to
 334 .Nm amd .
 335 Specify a file name to log
 336 .Nm amd
 337 events to.  If the string
 338 .Pa /dev/stderr
 339 is specified,
 340 .Nm amd
 341 will send its events to the standard error file descriptor.  IF the string
 342 .Pa syslog
 343 is given,
 344 .Nm amd
 345 will record its events with the system logger
 346 .Xr syslogd 8 .
 347 The default syslog facility used is
 348 .Ev LOG_DAEMON .
 349 If you wish to change it, append its name to the log file name, delimited by a
 350 single colon.  For example, if
 351 .Pa logfile
 352 is the string
 353 .Qq syslog:local7
 354 then
 355 .Nm amd
 356 will log messages via
 357 .Xr syslog 3
 358 using the
 359 .Ev LOG_LOCAL7
 360 facility
 361 .Pq if it exists on the system .
 362 .It Nm log_options (string, default no logging options)
 363 Same as the
 364 .Fl x
 365 option to
 366 .Nm amd .
 367 Specify any logging options for
 368 .Nm amd .
 369 Options are comma delimited, and can be preceded by the string
 370 .Dq no
 371 to negate their meaning.  The
 372 .Dq debug
 373 logging option is only available if
 374 .Nm am-utils
 375 was configured with
 376 .Fl -enable-debug .
 377 You can get the list of supported debugging options by running
 378 .Nm amd Fl v .
 379 Possible values are:
 380 .Pp
 381 .Bl -tag -width 10n -compact
 382 .It Nm all
 383 all messages
 384 .It Nm debug
 385 debug messages
 386 .It Nm error
 387 non-fatal system errors
 388 .It Nm fatal
 389 fatal errors
 390 .It Nm info
 391 information
 392 .It Nm map
 393 map errors
 394 .It Nm stats
 395 additional statistical information
 396 .It Nm user
 397 non-fatal user errors
 398 .It Nm warn
 399 warnings
 400 .It Nm warning
 401 warnings
 402 .El
 403 .It Nm nfs_retransmit_counter (numeric, default=110)
 404 Same as the
 405 .Ic counter
 406 part of the
 407 .Fl t Ar interval.counter
 408 option to
 409 .Nm amd .
 410 Specifies the retransmit counter's value in tenths of seconds.
 411 .It Nm nfs_retry_interval (numeric, default=8)
 412 Same as the
 413 .Ic interval
 414 part of the
 415 .Fl t Ar interval.counter
 416 option to
 417 .Nm amd .
 418 Specifies the interval in tenths of seconds, between NFS/RPC/UDP retries.
 419 .It Nm nis_domain
 420 .Po string, default to local
 421 .Tn NIS
 422 .Pc domain name
 423 Same as the
 424 .Fl y
 425 option to
 426 .Nm amd .
 427 Specify an alternative
 428 .Tn NIS
 429 domain from which to fetch the
 430 .Tn NIS
 431 maps.  The default is the system domain name.  This option is ignored if
 432 .Tn NIS
 433 support is not available.
 434 .It Nm normalize_hostnames (boolean, default=no)
 435 Same as the
 436 .Fl n
 437 option to
 438 .Nm amd .
 439 If
 440 .Dq yes ,
 441 then the name refereed to by
 442 .Va ${rhost}
 443 is normalized relative to the host database before being used.  The effect is
 444 to translate aliases into
 445 .Qq official
 446 names.
 447 .It Nm os (string, default to compiled in value)
 448 Same as the
 449 .Fl O
 450 option to
 451 .Nm amd .
 452 Allows you to override the compiled-in name of the operating
 453 system.  Useful when the built-in name is not desired for backward
 454 compatibility reasons.  For example, if the build in name is
 455 .Dq sunos5 ,
 456 you can override it to
 457 .Dq sos5 ,
 458 and use older maps which were written with the latter in mind.
 459 .It Nm osver (string, default to compiled in value)
 460 Same as the
 461 .Fl o
 462 option to
 463 .Nm amd .
 464 Override the compiled-in version number of the operating
 465 system.  Useful when the built in version is not desired for backward
 466 compatibility reasons.  For example, if the build in version is
 467 .Dq 2.5.1 ,
 468 you can override it to
 469 .Dq 5.5.1 ,
 470 and use older maps that were written with the latter in mind.
 471 .It Nm pid_file (string, default=/dev/stdout)
 472 Specify a file to store the process ID of the running daemon into.  If not
 473 specified,
 474 .Nm amd
 475 will print its process id only the standard output.  Useful for killing
 476 .Nm amd
 477 after it had run.  Note that the PID of a running
 478 .Nm amd
 479 can also be retrieved via
 480 .Nm amq Fl p .
 481 This file is used only if the
 482 .Ar print_pid
 483 option is on.
 484 .It Nm plock (boolean, default=yes)
 485 Same as the
 486 .Fl S
 487 option to
 488 .Nm amd .
 489 If
 490 .Dq yes ,
 491 lock the running executable pages of
 492 .Nm amd
 493 into memory.  To improve
 494 .Nm amd's
 495 performance, systems that support the
 496 .Xr plock 3
 497 call can lock the
 498 .Nm amd
 499 process into memory.  This way there is less chance it that the operating
 500 system will schedule, page out, and swap the
 501 .Nm amd
 502 process as needed.  This improves
 503 .Nm amd's
 504 performance, at the cost of reserving the memory used by the
 505 .Nm amd
 506 process
 507 .Pq making it unavailable for other processes .
 508 .It Nm portmap_program (numeric, default=300019)
 509 Specify an alternate Port-mapper RPC program number, other than the official
 510 number.  This is useful when running multiple
 511 .Nm amd
 512 processes.  For example, you can run another
 513 .Nm amd
 514 in
 515 .Dq test
 516 mode, without affecting the primary
 517 .Nm amd
 518 process in any way.  For safety reasons, the alternate program numbers that
 519 can be specified must be in the range 300019-300029, inclusive.
 520 .Nm amq
 521 has an option
 522 .Fl P
 523 which can be used to specify an alternate program number of an
 524 .Nm amd
 525 to contact.  In this way,
 526 .Nm amq
 527 can fully control any number of
 528 .Nm amd
 529 processes running on the same host.
 530 .It Nm print_pid (boolean, default=no)
 531 Same as the
 532 .Fl p
 533 option to
 534 .Nm amd .
 535 If
 536 .Dq yes ,
 537 .Nm amd
 538 will print its process ID upon starting.
 539 .It Nm print_version (boolean, default=no)
 540 Same as the
 541 .Fl v
 542 option to
 543 .Nm amd ,
 544 but the version prints and
 545 .Nm amd
 546 continues to run.  If
 547 .Dq yes ,
 548 .Nm amd
 549 will print its version information string, which includes some configuration
 550 and compilation values.
 551 .It Nm restart_mounts (boolean, default=no)
 552 Same as the
 553 .Fl r
 554 option to
 555 .Nm amd .
 556 If
 557 .Dq yes ,
 558 .Nm amd
 559 will scan the mount table to determine which file systems are currently
 560 mounted.  Whenever one of these would have been auto-mounted,
 561 .Nm amd
 562 inherits it.
 563 .It Nm selectors_on_default (boolean, default=no)
 564 If
 565 .Dq yes ,
 566 then the
 567 .Pa /default
 568 entry of maps will be looked for and process any selectors before setting
 569 defaults for all other keys in that map.  Useful when you want to set
 570 different options for a complete map based on some parameters.  For example,
 571 you may want to better the
 572 .Tn NFS
 573 performance over slow slip-based networks as
 574 follows:
 575 .Pp
 576 .Bd -literal
 577 /defaults \\
 578     wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \\
 579     wire!=slip-net;opts:=intr,rsize=8192,wsize=8192
 580 .Ed
 581 .It Nm show_statfs_entries (boolean, default=no)
 582 If
 583 .Dq yes ,
 584 then all maps which are browsable will also show the number of entries
 585 .Pq keys
 586 they have when
 587 .Qq df
 588 runs.
 589 .Po This is accomplished by returning non-zero values to the
 590 .Xr statfs 2
 591 .Pc system call .
 592 .It Nm unmount_on_exit (boolean, default=no)
 593 If
 594 .Dq yes ,
 595 then
 596 .Nm amd
 597 will attempt to unmount all file systems which it knows about.  Normally
 598 .Nm amd
 599 leaves all
 600 .Pq esp.
 601 .Tn NFS
 602 mounted filesystems intact.  Note that
 603 .Nm amd
 604 does not know about file systems mounted before it starts up, unless the
 605 .Ar restart_mounts
 606 option or
 607 .Fl r
 608 flag are used.
 609 .El
 610 .It Sy Parameters applicable to regular map sections
 611 .Bl -tag -width F1
 612 .It Nm map_name (string, must be specified)
 613 Name of the map where the keys are located.
 614 .It Nm tag (string, default no tag)
 615 Each map entry in the configuration file can be tagged.  If no tag is
 616 specified, that map section will always be processed by
 617 .Nm amd .
 618 If it is specified, then
 619 .Nm amd
 620 will process the map if the
 621 .Fl T
 622 option was given to
 623 .Nm amd ,
 624 and the value given to that command-line option matches that in the map
 625 section.
 626 .El
 627 .Sh EXAMPLES
 628 Here is a real
 629 .Nm amd
 630 configuration I use daily.
 631 .Bd -literal
 632 # GLOBAL OPTIONS SECTION
 633 [ global ]
 634 normalize_hostnames =    no
 635 print_pid =              no
 636 restart_mounts =         yes
 637 auto_dir =               /n
 638 log_file =               /var/log/amd
 639 log_options =            all
 640 #debug_options =         all
 641 plock =                  no
 642 selectors_on_default =   yes
 643 # config.guess picks up "sunos5" and I don't want to edit my maps yet
 644 os =                     sos5
 645 # if you print_version after setting up "os", it will show it.
 646 print_version =          no
 647 map_type =               file
 648 search_path =            /etc/amdmaps:/usr/lib/amd:/usr/local/AMD/lib
 649 browsable_dirs =         yes
 650
 651 # DEFINE AN AMD MOUNT POINT
 652 [ /u ]
 653 map_name =               amd.u
 654
 655 [ /proj ]
 656 map_name =               amd.proj
 657
 658 [ /src ]
 659 map_name =               amd.src
 660
 661 [ /misc ]
 662 map_name =               amd.misc
 663
 664 [ /import ]
 665 map_name =               amd.import
 666
 667 [ /tftpboot/.amd ]
 668 tag =                    tftpboot
 669 map_name =               amd.tftpboot
 670 .Ed
 671 .Sh SEE ALSO
 672 .Xr amd 8 ,
 673 .Xr amq 8
 674 .Sh AUTHORS
 675 .An Erez Zadok Aq ezk@cs.columbia.edu ,
 676 Department of Computer Science, Columbia University, New York, USA.
 677 .Pp
 678 .An Jan-Simon Pendry Aq jsp@doc.ic.ac.uk ,
 679 Department of Computing, Imperial College, London, UK.
 680 .Pp
 681 .An Other Authors and contributers to am-utils are listed in the
 682 .Nm AUTHORS
 683 file distributed with am-utils.
 684 .Sh HISTORY
 685 The
 686 .Nm amd
 687 utility first appeared in 4.4BSD.