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