docs/57926: amd.conf.5 poorly format as it has both man(7) and mdoc(7)
Kazuo Horikawa
horikawa at FreeBSD.org
Mon Oct 13 02:40:22 UTC 2003
The following reply was made to PR docs/57926; it has been noted by GNATS.
From: Kazuo Horikawa <horikawa at FreeBSD.org>
To: FreeBSD-gnats-submit at freebsd.org
Cc:
Subject: Re: docs/57926: amd.conf.5 poorly format as it has both man(7) and
mdoc(7)
Date: Sun, 12 Oct 2003 20:27:23 -0600 (MDT)
Please use the following diff instead.
It contains diffs appeared on the vendor branch that are
not included in the previous diff or revision 1.14
(e.g., descriptions of "full_os" and "vendor" parameters).
--- amd.conf.5.bak Sun Oct 12 18:37:36 2003
+++ amd.conf.5 Sun Oct 12 20:21:44 2003
@@ -121,56 +121,99 @@
calls. This means you could run for example
.Xr ls 1
and see what keys are available to mount in that directory. Not all entries
-are made visible to readdir(3): the "/default" entry, wildcard
-entries, and those with a "/" in them are not included. If you specify
-"full" to this option, all but "/default" will be visible.
+are made visible to
+.Xr readdir 3 :
+the
+.Qq Pa /default
+entry, wildcard entries, and those with a
+.Qq Pa /
+in them are not included.
+If you specify
+.Qq full
+to this option, all but
+.Qq Pa /default
+will be visible.
Note that if you run a command which will attempt to
-.BR stat (2)
-the entries, such as often done by "ls -l" or "ls -F", amd will attempt to
-mount
-.I every
-entry in that map. This is often called a ``mount storm''.
-
-.TP
-.BR map_options " (string, default no options)"
+.Xr stat 2
+the entries, such as often done by
+.Qq ls -l
+or
+.Qq ls -F ,
+.Nm amd
+will attempt to mount
+.Em every
+entry in that map.
+This is often called a
+.Em mount storm .
+.It Ic map_options Xo
+(string, default no options)
+.Xc
This option is the same as specifying map options on the command line to
-amd, such as "cache:=all".
-
-.TP
-.BR map_type " (string, default search all map types)"
-If specified, amd will initialize the map only for the type given. This is
+.Nm amd ,
+such as
+.Ql cache\&:\&=all .
+.It Ic map_type Xo
+(string, default search all map types)
+.Xc
+If specified, amd will initialize the map only for the type given.
+This is
useful to avoid the default map search type used by amd which takes longer
and can have undesired side-effects such as initializing NIS even if not
-used. Possible values are
-
-.nf
-\fBfile\fR plain files
-\fBhesiod\fR Hesiod name service from MIT
-\fBldap\fR Lightweight Directory Access Protocol
-\fBndbm\fR (New) dbm style hash files
-\fBnis\fR Network Information Services (version 2)
-\fBnisplus\fR Network Information Services Plus (version 3)
-\fBpasswd\fR local password files
-\fBunion\fR union maps
-.fi
-
-.TP
-.BR mount_type " (string, default=nfs)"
-All amd mount types must be NFS. That is, amd is an NFS server on the
-map mount points, for the local host it is running on. If "autofs" is
-specified, amd will log an error and convert it to NFS.
-
-.TP
-.BR search_path " (string, default no search path)"
-This provides a (colon-delimited) search path for file maps. Using a search
+used.
+Possible values are
+.Pp
+.Bl -tag -width "nisplus" -compact
+.It Ic file
+plain files
+.It Ic hesiod
+Hesiod name service from MIT
+.It Ic ldap
+Lightweight Directory Access Protocol
+.It Ic ndbm
+(New) dbm style hash files
+.It Ic nis
+Network Information Services (version 2)
+.It Ic nisplus
+Network Information Services Plus (version 3)
+.It Ic passwd
+local password files
+.It Ic union
+union maps
+.El
+.It Ic mount_type Xo
+(string, default=nfs)
+.Xc
+All
+.Nm amd
+mount types must be
+.Tn NFS .
+That is,
+.Nm amd
+is an
+.Tn NFS
+server on the
+map mount points, for the local host it is running on.
+If
+.Qq autofs
+is specified,
+.Nm amd
+will log an error and convert it to
+.Tn NFS .
+.It Ic search_path Xo
+(string, default no search path)
+.Xc
+This provides a
+(colon-delimited)
+search path for file maps.
+Using a search
path, sites can allow for local map customizations and overrides, and can
distributed maps in several locations as needed.
-
-.\" **************************************************************************
-.SS Parameters applicable to the global section only
-
-.TP
-.BR arch " (string, default to compiled in value)"
+.El
+.Ss "Parameters applicable to the global section only"
+.Bl -tag -width 4n
+.It Ic arch Xo
+(string, default to compiled in value)
+.Xc
Allows you to override the value of the
.Va arch
.Nm amd
@@ -226,7 +269,7 @@
.Nm amd Fl v .
Possible values are:
.Pp
-.Bl -tag -width "daemon" -compact
+.Bl -tag -width "xdrtrace" -compact
.It Ic all
all options
.It Ic amq
@@ -247,12 +290,18 @@
use local
.Pa ./mtab
file
+.It Ic readdir
+show browsable_dirs progress
.It Ic str
debug string munging
.It Ic test
full debug but no daemon
.It Ic trace
-protocol trace
+RPC protocol trace and
+.Tn NFS
+mount arguments
+.It Ic xdrtrace
+trace XDR routines
.El
.It Ic dismount_interval Xo
(numeric, default=120)
@@ -263,6 +312,19 @@
.Nm amd .
Specify, in seconds, the time between attempts to dismount file systems that
have exceeded their cached times.
+.It Ic full_os Xo
+(string, default to compiled in value)
+.Xc
+The full name of the operating system, along with its version.
+Allows you
+to override the compiled-in full name and version of the operating system.
+Useful when the compiled-in name is not desired.
+For example, the full
+operating system name on linux comes up as
+.Qq linux ,
+but you can override
+it to
+.Qq linux-2.2.5 .
.It Ic fully_qualified_hosts Xo
(string, default=no)
.Xc
@@ -309,6 +371,8 @@
(string, default not set)
.Xc
Specify the base name for LDAP.
+This often includes LDAP-specific
+values such as country and organization.
.It Ic ldap_cache_maxmem Xo
(numeric, default=131072)
.Xc
@@ -320,7 +384,7 @@
.It Ic ldap_hostports Xo
(string, default not set)
.Xc
-Specify LDAP-specific values such as country and organization.
+Specify the LDAP host and port values.
.It Ic local_domain Xo
(string, default no sub-domain)
.Xc
@@ -393,6 +457,10 @@
non-fatal system errors
.It Ic fatal
fatal errors
+.It Ic hrtime
+print high resolution time stamps (only if
+.Xr syslog 3
+is not used)
.It Ic info
information
.It Ic map
@@ -410,7 +478,7 @@
(numeric, default=110)
.Xc
Same as the
-.Ic counter
+.Ar counter
part of the
.Fl t Ar interval.counter
option to
@@ -420,97 +488,162 @@
(numeric, default=8)
.Xc
Same as the
-.B \-x
-option to amd. Specify any logging options for amd. Options are comma
-delimited, and can be preceded by the string "no" to negate their meaning.
-The "debug" logging option is only available if am-utils was configured with
---enable-debug. You can get the list of supported debugging and logging
-options by running amd \-H. Possible values are:
-
-.nf
-\fBall\fR all messages
-\fBdebug\fR debug messages
-\fBerror\fR non-fatal system errors
-\fBfatal\fR fatal errors
-\fBinfo\fR information
-\fBmap\fR map errors
-\fBstats\fR additional statistical information
-\fBuser\fR non-fatal user errors
-\fBwarn\fR warnings
-\fBwarning\fR warnings
-.fi
-
-.TP
-.BR nfs_vers " (numeric, default to trying version 3 then 2)"
-By default, amd tries version 3 and then version 2. This option forces the
-overall NFS protocol used to version 3 or 2. It overrides what is in the
+.Fl x
+option to
+.Nm amd .
+Specify any logging options for
+.Nm amd .
+Options are comma
+delimited, and can be preceded by the string
+.Qq no
+to negate their meaning.
+The
+.Qq debug
+logging option is only available if am-utils was configured with
+--enable-debug.
+You can get the list of supported debugging and logging
+options by running
+.Nm amd Fl H .
+Possible values are:
+.Pp
+.Bl -tag -width "warning" -compact
+.It Ic all
+all messages
+.It Ic debug
+debug messages
+.It Ic error
+non-fatal system errors
+.It Ic fatal
+fatal errors
+.It Ic info
+information
+.It Ic map
+map errors
+.It Ic stats
+additional statistical information
+.It Ic user
+non-fatal user errors
+.It Ic warn
+warnings
+.It Ic warning
+warnings
+.El
+.It Ic nfs_vers Xo
+(numeric, default to trying version 3 then 2)
+.Xc
+By default,
+.Nm amd
+tries version 3 and then version 2.
+This option forces the
+overall
+.Tn NFS
+protocol used to version 3 or 2.
+It overrides what is in the
amd maps, and is useful when amd is compiled with NFSv3 support that may not
-be stable. With this option you can turn off the complete usage of NFSv3
+be stable.
+With this option you can turn off the complete usage of NFSv3
dynamically (without having to recompile amd) until such time as NFSv3
support is desired again.
-
-.TP
-.BR nfs_retransmit_counter " (numeric, default=11)"
+.It Ic nfs_retransmit_counter Xo
+(numeric, default=11)
+.Xc
Same as the
-.I retransmit
+.Ar retransmit
part of the
-.BI \-t " timeout.retransmit"
-option to amd.
-Specifies the number of NFS retransmissions that the kernel will use to
-communicate with amd.
-
-.TP
-.BR nfs_retry_interval " (numeric, default=8)"
+.Fl t Ar timeout.retransmit
+option to
+.Nm amd .
+Specifies the number of
+.Tn NFS
+retransmissions that the kernel will use to
+communicate with
+.Nm amd .
+.It Ic nfs_retry_interval Xo
+(numeric, default=8)
+.Xc
Same as the
-.I timeout
+.Ar timeout
part of the
-.BI \-t " timeout.retransmit"
-option to amd. Specifies the NFS timeout interval, in
-.I tenths
-of seconds, between NFS/RPC retries (for UDP only).
+.Fl t Ar timeout.retransmit
+option to
+.Nm amd .
+Specifies the
+.Tn NFS
+timeout interval, in
+.Em tenths
+of seconds, between NFS/RPC
+retries (for UDP only).
This is the value that the kernel will use to
-communicate with amd.
-
-Amd relies on the kernel RPC retransmit mechanism to trigger mount retries.
+communicate with
+.Nm amd .
+.Pp
+.Nm Amd
+relies on the kernel RPC retransmit mechanism to trigger mount retries.
The values of the
-.B nfs_retransmit_counter
+.Ar nfs_retransmit_counter
and the
-.B nfs_retry_interval
-parameters change the overall retry interval. Too long an interval gives
+.Ar nfs_retry_interval
+parameters change the overall retry interval.
+Too long an interval gives
poor interactive response; too short an interval causes excessive retries.
-
-.TP
-.BR nfs_proto " (string, default to trying version tcp then udp)"
-By default, amd tries TCP and then UDP. This option forces the overall NFS
-protocol used to TCP or UDP. It overrides what is in the amd maps, and is
-useful when amd is compiled with NFSv3 support that may not be stable. With
+.It Ic nfs_proto Xo
+(string, default to trying version tcp then udp)
+.Xc
+By default,
+.Nm amd
+tries TCP and then UDP.
+This option forces the overall
+.Tn NFS
+protocol used to TCP or UDP.
+It overrides what is in the amd maps, and is
+useful when amd is compiled with NFSv3 support that may not be stable.
+With
this option you can turn off the complete usage of NFSv3 dynamically
(without having to recompile amd) until such time as NFSv3 support is
desired again.
-
-.TP
-.BR nis_domain " (string, default to local NIS domain name)"
-Same as the
-.B \-y
-option to amd. Specify an alternative NIS domain from which to fetch the
-NIS maps. The default is the system domain name. This option is ignored if
-NIS support is not available.
-
-.TP
-.BR normalize_hostnames " (boolean, default=no)"
-Same as the
-.B \-n
-option to amd. If "yes", then the name refereed to by ${rhost} is
-normalized relative to the host database before being used. The effect is
-to translate aliases into ``official'' names.
-
-.TP
-.BR os " (string, default to compiled in value)"
-Same as the
-.B \-O
-option to amd. Allows you to override the compiled-in name of the operating
-system. Useful when the built-in name is not desired for backward
-compatibility reasons. For example, if the build in name is
+.It Ic nis_domain Xo
+(string, default to local NIS domain name)
+.Xc
+Same as the
+.Fl y
+option to
+.Nm amd .
+Specify an alternative
+.Tn NIS
+domain from which to fetch the
+.Tn NIS
+maps.
+The default is the system domain name.
+This option is ignored if
+.Tn NIS
+support is not available.
+.It Ic normalize_hostnames Xo
+(boolean, default=no)
+.Xc
+Same as the
+.Fl n
+option to
+.Nm amd .
+If
+.Qq yes ,
+then the name refereed to by
+.Va ${rhost}
+is normalized relative to the host database before being used.
+The effect is
+to translate aliases into
+.Qq official
+names.
+.It Ic os Xo
+(string, default to compiled in value)
+.Xc
+Same as the
+.Fl O
+option to
+.Nm amd .
+Allows you to override the compiled-in name of the operating system.
+Useful when the built-in name is not desired for backward
+compatibility reasons.
+For example, if the build in name is
.Dq sunos5 ,
you can override it to
.Dq sos5 ,
@@ -633,13 +766,13 @@
mounted. Whenever one of these would have been auto-mounted,
.Nm amd
inherits it.
-.It Ic selectors_on_default Xo
+.It Ic selectors_in_default Xo
(boolean, default=no)
.Xc
If
.Dq yes ,
then the
-.Pa /default
+.Pa /defaults
entry of maps will be looked for and process any selectors before setting
defaults for all other keys in that map. Useful when you want to set
different options for a complete map based on some parameters. For example,
@@ -653,6 +786,7 @@
wire==slip-net;opts:=intr,rsize=1024,wsize=1024 \\
wire!=slip-net;opts:=intr,rsize=8192,wsize=8192
.Ed
+Deprecated form: selectors_on_default
.It Ic show_statfs_entries Xo
(boolean, default=no)
.Xc
@@ -685,6 +819,17 @@
option or
.Fl r
flag are used.
+.It Ic vendor Xo
+(string, default to compiled in value)
+.Xc
+The name of the vendor of the operating system.
+Overrides the compiled-in vendor name.
+Useful when the compiled-in name is not desired.
+For example,
+most Intel based systems set the vendor name to
+.Qq unknown ,
+but you can set it to
+.Qq redhat .
.El
.Ss "Parameters applicable to regular map sections"
.Bl -tag -width 4n
@@ -722,7 +867,7 @@
log_options = all
#debug_options = all
plock = no
-selectors_on_default = yes
+selectors_in_default = yes
# config.guess picks up "sunos5" and I don't want to edit my maps yet
os = sos5
# if you print_version after setting up "os", it will show it.
More information about the freebsd-doc
mailing list