ChangeLog
+ntpd/invoke-ntp.conf.texi
+ntpd/invoke-ntp.keys.texi
ntpd/invoke-ntpd.texi
ntpd/ntp.conf.5man
ntpd/ntp.conf.5mdoc
+ntpd/ntp.conf.html
+ntpd/ntp.conf.texi
ntpd/ntp.conf.man.in
ntpd/ntp.conf.mdoc.in
ntpd/ntp.keys.5man
ntpd/ntp.keys.5mdoc
+ntpd/ntp.keys.html
+ntpd/ntp.keys.texi
ntpd/ntp.keys.man.in
ntpd/ntp.keys.mdoc.in
ntpd/ntpd-opts.c
+* autogen doc cleanup
(4.2.7p329) 2012/12/01 Released by Harlan Stenn <stenn@ntp.org>
* [Bug 2278] ACTS flag3 mismatch between code and driver18.html.
* Use an enum for the ACTS state table.
endif
#
-# VPHACK and VPHACK_AFTER are enabled on non-GNU makes (such as
+# VPHACK and VPHACK_AFTER are enabled on non-GNU makes (such as
# BSD make) to work around issues specific to compiling
# ntp_parser.y into ntp_parser.h and ntp_parser.c in a VPATH
# configuration where we would like (for a change) the output
# as opposed to the build directory. This allows a single
# host of a flock configured with Bison to update ntp_parser.[ch]
# used by the rest.
-#
+#
if VPATH_HACK
VPHACK= vphack
#
# ylwrap script which invokes Bison replaces ntp_parser.h
# symlink with the updated file, when ntp_parser.h changes.
-# vphack_after detects this and copies the updated file to srcdir
+# vphack_after detects this and copies the updated file to srcdir
# and re-creates the ntp_parser.h symlink in its place.
#
# BUILT_SOURCES which should also be in EXTRA_DIST
B_S_DIST= \
- $(srcdir)/ntpd-opts.c \
- $(srcdir)/ntpd-opts.h \
+ $(srcdir)/ntpd-opts.c \
+ $(srcdir)/ntpd-opts.h \
$(NULL)
BUILT_SOURCES= \
- $(VPHACK) \
+ $(VPHACK) \
$(LIBPARSE) \
- ntp_parser.c \
- ntp_parser.h \
+ ntp_parser.c \
+ ntp_parser.h \
$(VPHACK_AFTER) \
$(B_S_DIST) \
$(NULL)
EXTRA_DIST = \
complete.conf.in \
+ invoke-ntp.conf.menu \
+ invoke-ntp.conf.texi \
+ invoke-ntp.keys.menu \
+ invoke-ntp.keys.texi \
invoke-ntpd.menu \
invoke-ntpd.texi \
keyword-gen-utd \
ntp.conf.def \
ntp.conf.man.in \
ntp.conf.mdoc.in \
+ ntp.conf.html \
+ ntp.conf.texi \
ntp.keys.5man \
ntp.keys.5mdoc \
ntp.keys.def \
ntp.keys.man.in \
ntp.keys.mdoc.in \
+ ntp.keys.html \
+ ntp.keys.texi \
ntpd-opts.def \
ntpd.1ntpdman \
ntpd.1ntpdmdoc \
### Y2Kfixes
check_PROGRAMS = @MAKE_CHECK_Y2K@
EXTRA_PROGRAMS = check_y2k keyword-gen ntpd ntpdsim
+
+html_DATA= \
+ $(srcdir)/ntp.conf.html \
+ $(srcdir)/ntp.keys.html \
+ $(NULL)
+
noinst_DATA = \
+ $(srcdir)/invoke-ntp.conf.menu \
+ $(srcdir)/invoke-ntp.conf.texi \
+ $(srcdir)/invoke-ntp.keys.menu \
+ $(srcdir)/invoke-ntp.keys.texi \
$(srcdir)/invoke-ntpd.menu \
$(srcdir)/invoke-ntpd.texi \
$(srcdir)/ntp.conf.man.in \
$(NULL)
noinst_HEADERS = declcond.h
+
+install-data-local: install-html
+
run_ag= cd $(srcdir) && env PATH="$(abs_builddir):$(PATH)" \
autogen -L ../sntp/include -L ../sntp/ag-tpl --writable
std_def_list = \
$(top_srcdir)/sntp/include/debug-opt.def \
- $(top_srcdir)/sntp/include/autogen-version.def \
- $(top_srcdir)/sntp/include/copyright.def \
- $(top_srcdir)/sntp/include/homerc.def \
+ $(top_srcdir)/sntp/include/autogen-version.def \
+ $(top_srcdir)/sntp/include/copyright.def \
+ $(top_srcdir)/sntp/include/homerc.def \
$(top_srcdir)/sntp/include/ntp.lic \
$(top_srcdir)/sntp/include/version.def \
$(NULL)
ntpd-opts.c \
ntpd-opts.h \
$(NULL)
-
+
ntpdsim_SOURCES = \
$(ntpd_SOURCES) \
ntp_prio_q.c \
$(MAKE) $(AM_MAKEFLAGS) k-g-u-submake # avoid explicit dependency
grep diff_ignore_line $(srcdir)/ntp_keyword.h > k-g-u
mv -f k-g-u $@
-
+
$(srcdir)/ntp_keyword.h: $(srcdir)/keyword-gen-utd
@: do-nothing action to avoid default SCCS get
@: .h updated if needed by k-g-u-submake rule
$(srcdir)/ntpd-opts.h: $(srcdir)/ntpd-opts.c
@: do-nothing action to avoid default SCCS get, .h built with .c
-
+
$(srcdir)/ntpd-opts.c: $(srcdir)/ntpd-opts.def $(srcdir)/ntpdbase-opts.def $(std_def_list)
$(run_ag) ntpd-opts.def
###
+$(srcdir)/invoke-ntp.conf.menu: $(srcdir)/invoke-ntp.conf.texi
+ @: do-nothing action to avoid default SCCS get, .menu built with .texi
+
+$(srcdir)/invoke-ntp.conf.texi: $(srcdir)/ntp.conf.def $(std_def_list)
+ $(run_ag) -Tagtexi-cmd.tpl -DLEVEL=section ntp.conf.def
+
+$(srcdir)/invoke-ntp.keys.menu: $(srcdir)/invoke-ntp.keys.texi
+ @: do-nothing action to avoid default SCCS get, .menu built with .texi
+
+$(srcdir)/invoke-ntp.keys.texi: $(srcdir)/ntp.keys.def $(std_def_list)
+ $(run_ag) -Tagtexi-cmd.tpl -DLEVEL=section ntp.keys.def
+
+$(srcdir)/ntp.conf.html: $(srcdir)/ntp.conf.texi $(top_srcdir)/sntp/include/version.texi
+ cd $(srcdir) && ( makeinfo --force --html --no-split -o ntp.conf.html ntp.conf.texi || true )
+
+$(srcdir)/ntp.keys.html: $(srcdir)/ntp.keys.texi $(top_srcdir)/sntp/include/version.texi
+ cd $(srcdir) && ( makeinfo --force --html --no-split -o ntp.keys.html ntp.keys.texi || true )
+
+###
+
$(srcdir)/ntp.conf.5man: $(srcdir)/ntp.conf.def $(std_def_list)
$(run_ag) -DMAN_SECTION=5man -Tagman-cmd.tpl ntp.conf.def
###
$(srcdir)/ntp.keys.5man: $(srcdir)/ntp.keys.def $(std_def_list)
- $(run_ag) -DMAN_SECTION=5man -Tagman-cmd.tpl ntp.keys.def
+ $(run_ag) -DMAN_SECTION=5man -Tagman-file.tpl ntp.keys.def
$(srcdir)/ntp.keys.man.in: $(srcdir)/ntp.keys.5man $(top_srcdir)/sntp/scripts/mansec2subst.sed
sed -f $(top_srcdir)/sntp/scripts/mansec2subst.sed $(srcdir)/ntp.keys.5man > $(srcdir)/ntp.keys.man.in+
###
$(srcdir)/ntp.keys.5mdoc: $(srcdir)/ntp.keys.def $(std_def_list)
- $(run_ag) -DMAN_SECTION=5mdoc -Tagmdoc-cmd.tpl ntp.keys.def
+ $(run_ag) -DMAN_SECTION=5mdoc -Tagmdoc-file.tpl ntp.keys.def
$(srcdir)/ntp.keys.mdoc.in: $(srcdir)/ntp.keys.5mdoc $(top_srcdir)/sntp/scripts/mansec2subst.sed
sed -f $(top_srcdir)/sntp/scripts/mansec2subst.sed $(srcdir)/ntp.keys.5mdoc > $(srcdir)/ntp.keys.mdoc.in+
$(srcdir)/invoke-ntpd.menu: $(srcdir)/invoke-ntpd.texi
@: do-nothing action to avoid default SCCS get, .menu built with .texi
-
+
$(srcdir)/invoke-ntpd.texi: $(srcdir)/ntpd-opts.def $(srcdir)/ntpdbase-opts.def $(std_def_list)
$(run_ag) -Tagtexi-cmd.tpl -DLEVEL=section ntpd-opts.def
$(top_srcdir)/scripts/check--help $@
version.c: $(ntpd_OBJECTS) ../libntp/libntp.a @LIBPARSE@ Makefile $(top_srcdir)/sntp/scm-rev
env CSET=`cat $(top_srcdir)/sntp/scm-rev` $(top_builddir)/scripts/mkver ntpd
-
+
version.o: version.c
env CCACHE_DISABLE=1 $(COMPILE) -c version.c -o version.o
--- /dev/null
+* ntp.conf Invocation:: Invoking ntp.conf
--- /dev/null
+@node ntp.conf Invocation
+@section Invoking ntp.conf
+@pindex ntp.conf
+@cindex Network Time Protocol (NTP) daemon configuration file format
+@ignore
+#
+# EDIT THIS FILE WITH CAUTION (invoke-ntp.conf.texi)
+#
+# It has been AutoGen-ed December 3, 2012 at 12:40:11 AM by AutoGen 5.16.2
+# From the definitions ntp.conf.def
+# and the template file agtexi-cmd.tpl
+@end ignore
+
+
+
+The
+@code{ntp.conf}
+configuration file is read at initial startup by the
+@code{ntpd(1ntpdmdoc)}
+daemon in order to specify the synchronization sources,
+modes and other related information.
+Usually, it is installed in the
+.Pa
+/etc
+directory,
+but could be installed elsewhere
+(see the daemon's
+@code{-c} command line option).
+
+The file format is similar to other
+.Ux
+configuration files.
+Comments begin with a
+.Ql
+#
+character and extend to the end of the line;
+blank lines are ignored.
+Configuration commands consist of an initial keyword
+followed by a list of arguments,
+some of which may be optional, separated by whitespace.
+Commands may not be continued over multiple lines.
+Arguments may be host names,
+host addresses written in numeric, dotted-quad form,
+integers, floating point numbers (when specifying times in seconds)
+and text strings.
+
+The rest of this page describes the configuration and control options.
+The
+.Qq
+Notes
+on
+Configuring
+NTP
+and
+Setting
+up
+a
+NTP
+Subnet
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+contains an extended discussion of these options.
+In addition to the discussion of general
+.Sx
+Configuration
+Options
+,
+there are sections describing the following supported functionality
+and the options used to control it:
+@itemize @bullet
+@item
+.Sx
+Authentication
+Support
+@item
+.Sx
+Monitoring
+Support
+@item
+.Sx
+Access
+Control
+Support
+@item
+.Sx
+Automatic
+NTP
+Configuration
+Options
+@item
+.Sx
+Reference
+Clock
+Support
+@item
+.Sx
+Miscellaneous
+Options
+@end itemize
+
+Following these is a section describing
+.Sx
+Miscellaneous
+Options
+.
+While there is a rich set of options available,
+the only required option is one or more
+.Ic
+server
+,
+.Ic
+peer
+,
+.Ic
+broadcast
+or
+.Ic
+manycastclient
+commands.
+.Sh
+Configuration
+Support
+Following is a description of the configuration commands in
+NTPv4.
+These commands have the same basic functions as in NTPv3 and
+in some cases new functions and new arguments.
+There are two
+classes of commands, configuration commands that configure a
+persistent association with a remote server or peer or reference
+clock, and auxiliary commands that specify environmental variables
+that control various related operations.
+.Ss
+Configuration
+Commands
+The various modes are determined by the command keyword and the
+type of the required IP address.
+Addresses are classed by type as
+(s) a remote server or peer (IPv4 class A, B and C), (b) the
+broadcast address of a local interface, (m) a multicast address (IPv4
+class D), or (r) a reference clock address (127.127.x.x).
+Note that
+only those options applicable to each command are listed below.
+Use
+of options not listed may not be caught as an error, but may result
+in some weird and even destructive behavior.
+
+If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
+is detected, support for the IPv6 address family is generated
+in addition to the default support of the IPv4 address family.
+In a few cases, including the reslist billboard generated
+by ntpdc, IPv6 addresses are automatically generated.
+IPv6 addresses can be identified by the presence of colons
+.Dq
+\&:
+in the address field.
+IPv6 addresses can be used almost everywhere where
+IPv4 addresses can be used,
+with the exception of reference clock addresses,
+which are always IPv4.
+
+Note that in contexts where a host name is expected, a
+@code{-4} qualifier preceding
+the host name forces DNS resolution to the IPv4 namespace,
+while a
+@code{-6} qualifier forces DNS resolution to the IPv6 namespace.
+See IPv6 references for the
+equivalent classes for that address family.
+@table @samp
+@item Xo
+.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+burst
+.Op
+Cm
+iburst
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Xc
+@item Xo
+.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Xc
+@item Xo
+.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+ttl
+Ar
+ttl
+.Xc
+@item Xo
+.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Op
+Cm
+ttl
+Ar
+ttl
+.Xc
+
+@end multitable
+
+These four commands specify the time server name or address to
+be used and the mode in which to operate.
+The
+.Ar
+address
+can be
+either a DNS name or an IP address in dotted-quad notation.
+Additional information on association behavior can be found in the
+.Qq
+Association
+Management
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+@table @samp
+@item Ic
+For type s and r addresses, this command mobilizes a persistent
+client mode association with the specified remote server or local
+radio clock.
+In this mode the local clock can synchronized to the
+remote server, but the remote server can never be synchronized to
+the local clock.
+This command should
+.Em
+not
+be used for type
+b or m addresses.
+@item Ic
+For type s addresses (only), this command mobilizes a
+persistent symmetric-active mode association with the specified
+remote peer.
+In this mode the local clock can be synchronized to
+the remote peer or the remote peer can be synchronized to the local
+clock.
+This is useful in a network of servers where, depending on
+various failure scenarios, either the local or remote peer may be
+the better source of time.
+This command should NOT be used for type
+b, m or r addresses.
+@item Ic
+For type b and m addresses (only), this
+command mobilizes a persistent broadcast mode association.
+Multiple
+commands can be used to specify multiple local broadcast interfaces
+(subnets) and/or multiple multicast groups.
+Note that local
+broadcast messages go only to the interface associated with the
+subnet specified, but multicast messages go to all interfaces.
+In broadcast mode the local server sends periodic broadcast
+messages to a client population at the
+.Ar
+address
+specified, which is usually the broadcast address on (one of) the
+local network(s) or a multicast address assigned to NTP.
+The IANA
+has assigned the multicast group address IPv4 224.0.1.1 and
+IPv6 ff05::101 (site local) exclusively to
+NTP, but other nonconflicting addresses can be used to contain the
+messages within administrative boundaries.
+Ordinarily, this
+specification applies only to the local server operating as a
+sender; for operation as a broadcast client, see the
+.Ic
+broadcastclient
+or
+.Ic
+multicastclient
+commands
+below.
+@item Ic
+For type m addresses (only), this command mobilizes a
+manycast client mode association for the multicast address
+specified.
+In this case a specific address must be supplied which
+matches the address used on the
+.Ic
+manycastserver
+command for
+the designated manycast servers.
+The NTP multicast address
+224.0.1.1 assigned by the IANA should NOT be used, unless specific
+means are taken to avoid spraying large areas of the Internet with
+these messages and causing a possibly massive implosion of replies
+at the sender.
+The
+.Ic
+manycastserver
+command specifies that the local server
+is to operate in client mode with the remote servers that are
+discovered as the result of broadcast/multicast messages.
+The
+client broadcasts a request message to the group address associated
+with the specified
+.Ar
+address
+and specifically enabled
+servers respond to these messages.
+The client selects the servers
+providing the best time and continues as with the
+.Ic
+server
+command.
+The remaining servers are discarded as if never
+heard.
+
+@end multitable
+
+Options:
+@table @samp
+@item Cm
+All packets sent to and received from the server or peer are to
+include authentication fields encrypted using the autokey scheme
+described in
+.Sx
+Authentication
+Options
+.
+@item Cm
+when the server is reachable, send a burst of eight packets
+instead of the usual one.
+The packet spacing is normally 2 s;
+however, the spacing between the first and second packets
+can be changed with the calldelay command to allow
+additional time for a modem or ISDN call to complete.
+This is designed to improve timekeeping quality
+with the
+.Ic
+server
+command and s addresses.
+@item Cm
+When the server is unreachable, send a burst of eight packets
+instead of the usual one.
+The packet spacing is normally 2 s;
+however, the spacing between the first two packets can be
+changed with the calldelay command to allow
+additional time for a modem or ISDN call to complete.
+This is designed to speed the initial synchronization
+acquisition with the
+.Ic
+server
+command and s addresses and when
+@code{ntpd(1ntpdmdoc)}
+is started with the
+@code{-q} option.
+@item Cm
+All packets sent to and received from the server or peer are to
+include authentication fields encrypted using the specified
+.Ar
+key
+identifier with values from 1 to 65534, inclusive.
+The
+default is to include no encryption field.
+@item Cm
+@item Cm
+These options specify the minimum and maximum poll intervals
+for NTP messages, as a power of 2 in seconds
+The maximum poll
+interval defaults to 10 (1,024 s), but can be increased by the
+.Cm
+maxpoll
+option to an upper limit of 17 (36.4 h).
+The
+minimum poll interval defaults to 6 (64 s), but can be decreased by
+the
+.Cm
+minpoll
+option to a lower limit of 4 (16 s).
+@item Cm
+Marks the server as unused, except for display purposes.
+The server is discarded by the selection algroithm.
+@item Cm
+Marks the server as preferred.
+All other things being equal,
+this host will be chosen for synchronization among a set of
+correctly operating hosts.
+See the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+for further information.
+@item Cm
+This option is used only with broadcast server and manycast
+client modes.
+It specifies the time-to-live
+.Ar
+ttl
+to
+use on broadcast server and multicast server and the maximum
+.Ar
+ttl
+for the expanding ring search with manycast
+client packets.
+Selection of the proper value, which defaults to
+127, is something of a black art and should be coordinated with the
+network administrator.
+@item Cm
+Specifies the version number to be used for outgoing NTP
+packets.
+Versions 1-4 are the choices, with version 4 the
+default.
+
+@end multitable
+.Ss
+Auxiliary
+Commands
+@table @samp
+@item Ic
+This command enables reception of broadcast server messages to
+any local interface (type b) address.
+Upon receiving a message for
+the first time, the broadcast client measures the nominal server
+propagation delay using a brief client/server exchange with the
+server, then enters the broadcast client mode, in which it
+synchronizes to succeeding broadcast messages.
+Note that, in order
+to avoid accidental or malicious disruption in this mode, both the
+server and client should operate using symmetric-key or public-key
+authentication as described in
+.Sx
+Authentication
+Options
+.
+@item Ic
+This command enables reception of manycast client messages to
+the multicast group address(es) (type m) specified.
+At least one
+address is required, but the NTP multicast address 224.0.1.1
+assigned by the IANA should NOT be used, unless specific means are
+taken to limit the span of the reply and avoid a possibly massive
+implosion at the original sender.
+Note that, in order to avoid
+accidental or malicious disruption in this mode, both the server
+and client should operate using symmetric-key or public-key
+authentication as described in
+.Sx
+Authentication
+Options
+.
+@item Ic
+This command enables reception of multicast server messages to
+the multicast group address(es) (type m) specified.
+Upon receiving
+a message for the first time, the multicast client measures the
+nominal server propagation delay using a brief client/server
+exchange with the server, then enters the broadcast client mode, in
+which it synchronizes to succeeding multicast messages.
+Note that,
+in order to avoid accidental or malicious disruption in this mode,
+both the server and client should operate using symmetric-key or
+public-key authentication as described in
+.Sx
+Authentication
+Options
+.
+
+@end multitable
+.Sh
+Authentication
+Support
+Authentication support allows the NTP client to verify that the
+server is in fact known and trusted and not an intruder intending
+accidentally or on purpose to masquerade as that server.
+The NTPv3
+specification RFC-1305 defines a scheme which provides
+cryptographic authentication of received NTP packets.
+Originally,
+this was done using the Data Encryption Standard (DES) algorithm
+operating in Cipher Block Chaining (CBC) mode, commonly called
+DES-CBC.
+Subsequently, this was replaced by the RSA Message Digest
+5 (MD5) algorithm using a private key, commonly called keyed-MD5.
+Either algorithm computes a message digest, or one-way hash, which
+can be used to verify the server has the correct private key and
+key identifier.
+
+NTPv4 retains the NTPv3 scheme, properly described as symmetric key
+cryptography and, in addition, provides a new Autokey scheme
+based on public key cryptography.
+Public key cryptography is generally considered more secure
+than symmetric key cryptography, since the security is based
+on a private value which is generated by each server and
+never revealed.
+With Autokey all key distribution and
+management functions involve only public values, which
+considerably simplifies key distribution and storage.
+Public key management is based on X.509 certificates,
+which can be provided by commercial services or
+produced by utility programs in the OpenSSL software library
+or the NTPv4 distribution.
+
+While the algorithms for symmetric key cryptography are
+included in the NTPv4 distribution, public key cryptography
+requires the OpenSSL software library to be installed
+before building the NTP distribution.
+Directions for doing that
+are on the Building and Installing the Distribution page.
+
+Authentication is configured separately for each association
+using the
+.Cm
+key
+or
+.Cm
+autokey
+subcommand on the
+.Ic
+peer
+,
+.Ic
+server
+,
+.Ic
+broadcast
+and
+.Ic
+manycastclient
+configuration commands as described in
+.Sx
+Configuration
+Options
+page.
+The authentication
+options described below specify the locations of the key files,
+if other than default, which symmetric keys are trusted
+and the interval between various operations, if other than default.
+
+Authentication is always enabled,
+although ineffective if not configured as
+described below.
+If a NTP packet arrives
+including a message authentication
+code (MAC), it is accepted only if it
+passes all cryptographic checks.
+The
+checks require correct key ID, key value
+and message digest.
+If the packet has
+been modified in any way or replayed
+by an intruder, it will fail one or more
+of these checks and be discarded.
+Furthermore, the Autokey scheme requires a
+preliminary protocol exchange to obtain
+the server certificate, verify its
+credentials and initialize the protocol
+
+The
+.Cm
+auth
+flag controls whether new associations or
+remote configuration commands require cryptographic authentication.
+This flag can be set or reset by the
+.Ic
+enable
+and
+.Ic
+disable
+commands and also by remote
+configuration commands sent by a
+@code{ntpdc(1ntpdcmdoc)}
+program running in
+another machine.
+If this flag is enabled, which is the default
+case, new broadcast client and symmetric passive associations and
+remote configuration commands must be cryptographically
+authenticated using either symmetric key or public key cryptography.
+If this
+flag is disabled, these operations are effective
+even if not cryptographic
+authenticated.
+It should be understood
+that operating with the
+.Ic
+auth
+flag disabled invites a significant vulnerability
+where a rogue hacker can
+masquerade as a falseticker and seriously
+disrupt system timekeeping.
+It is
+important to note that this flag has no purpose
+other than to allow or disallow
+a new association in response to new broadcast
+and symmetric active messages
+and remote configuration commands and, in particular,
+the flag has no effect on
+the authentication process itself.
+
+An attractive alternative where multicast support is available
+is manycast mode, in which clients periodically troll
+for servers as described in the
+.Sx
+Automatic
+NTP
+Configuration
+Options
+page.
+Either symmetric key or public key
+cryptographic authentication can be used in this mode.
+The principle advantage
+of manycast mode is that potential servers need not be
+configured in advance,
+since the client finds them during regular operation,
+and the configuration
+files for all clients can be identical.
+
+The security model and protocol schemes for
+both symmetric key and public key
+cryptography are summarized below;
+further details are in the briefings, papers
+and reports at the NTP project page linked from
+.Li
+http://www.ntp.org/
+.
+.Ss
+Symmetric-Key
+Cryptography
+The original RFC-1305 specification allows any one of possibly
+65,534 keys, each distinguished by a 32-bit key identifier, to
+authenticate an association.
+The servers and clients involved must
+agree on the key and key identifier to
+authenticate NTP packets.
+Keys and
+related information are specified in a key
+file, usually called
+.Pa
+ntp.keys
+,
+which must be distributed and stored using
+secure means beyond the scope of the NTP protocol itself.
+Besides the keys used
+for ordinary NTP associations,
+additional keys can be used as passwords for the
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+utility programs.
+
+When
+@code{ntpd(1ntpdmdoc)}
+is first started, it reads the key file specified in the
+.Ic
+keys
+configuration command and installs the keys
+in the key cache.
+However,
+individual keys must be activated with the
+.Ic
+trusted
+command before use.
+This
+allows, for instance, the installation of possibly
+several batches of keys and
+then activating or deactivating each batch
+remotely using
+@code{ntpdc(1ntpdcmdoc)}.
+This also provides a revocation capability that can be used
+if a key becomes compromised.
+The
+.Ic
+requestkey
+command selects the key used as the password for the
+@code{ntpdc(1ntpdcmdoc)}
+utility, while the
+.Ic
+controlkey
+command selects the key used as the password for the
+@code{ntpq(1ntpqmdoc)}
+utility.
+.Ss
+Public
+Key
+Cryptography
+NTPv4 supports the original NTPv3 symmetric key scheme
+described in RFC-1305 and in addition the Autokey protocol,
+which is based on public key cryptography.
+The Autokey Version 2 protocol described on the Autokey Protocol
+page verifies packet integrity using MD5 message digests
+and verifies the source with digital signatures and any of several
+digest/signature schemes.
+Optional identity schemes described on the Identity Schemes
+page and based on cryptographic challenge/response algorithms
+are also available.
+Using all of these schemes provides strong security against
+replay with or without modification, spoofing, masquerade
+and most forms of clogging attacks.
+
+The Autokey protocol has several modes of operation
+corresponding to the various NTP modes supported.
+Most modes use a special cookie which can be
+computed independently by the client and server,
+but encrypted in transmission.
+All modes use in addition a variant of the S-KEY scheme,
+in which a pseudo-random key list is generated and used
+in reverse order.
+These schemes are described along with an executive summary,
+current status, briefing slides and reading list on the
+.Sx
+Autonomous
+Authentication
+page.
+
+The specific cryptographic environment used by Autokey servers
+and clients is determined by a set of files
+and soft links generated by the
+@code{ntp-keygen(1ntpkeygenmdoc)}
+program.
+This includes a required host key file,
+required certificate file and optional sign key file,
+leapsecond file and identity scheme files.
+The
+digest/signature scheme is specified in the X.509 certificate
+along with the matching sign key.
+There are several schemes
+available in the OpenSSL software library, each identified
+by a specific string such as
+.Cm
+md5WithRSAEncryption
+,
+which stands for the MD5 message digest with RSA
+encryption scheme.
+The current NTP distribution supports
+all the schemes in the OpenSSL library, including
+those based on RSA and DSA digital signatures.
+
+NTP secure groups can be used to define cryptographic compartments
+and security hierarchies.
+It is important that every host
+in the group be able to construct a certificate trail to one
+or more trusted hosts in the same group.
+Each group
+host runs the Autokey protocol to obtain the certificates
+for all hosts along the trail to one or more trusted hosts.
+This requires the configuration file in all hosts to be
+engineered so that, even under anticipated failure conditions,
+the NTP subnet will form such that every group host can find
+a trail to at least one trusted host.
+.Ss
+Naming
+and
+Addressing
+It is important to note that Autokey does not use DNS to
+resolve addresses, since DNS can't be completely trusted
+until the name servers have synchronized clocks.
+The cryptographic name used by Autokey to bind the host identity
+credentials and cryptographic values must be independent
+of interface, network and any other naming convention.
+The name appears in the host certificate in either or both
+the subject and issuer fields, so protection against
+DNS compromise is essential.
+
+By convention, the name of an Autokey host is the name returned
+by the Unix
+@code{gethostname(2)}
+system call or equivalent in other systems.
+By the system design
+model, there are no provisions to allow alternate names or aliases.
+However, this is not to say that DNS aliases, different names
+for each interface, etc., are constrained in any way.
+
+It is also important to note that Autokey verifies authenticity
+using the host name, network address and public keys,
+all of which are bound together by the protocol specifically
+to deflect masquerade attacks.
+For this reason Autokey
+includes the source and destinatino IP addresses in message digest
+computations and so the same addresses must be available
+at both the server and client.
+For this reason operation
+with network address translation schemes is not possible.
+This reflects the intended robust security model where government
+and corporate NTP servers are operated outside firewall perimeters.
+.Ss
+Operation
+A specific combination of authentication scheme (none,
+symmetric key, public key) and identity scheme is called
+a cryptotype, although not all combinations are compatible.
+There may be management configurations where the clients,
+servers and peers may not all support the same cryptotypes.
+A secure NTPv4 subnet can be configured in many ways while
+keeping in mind the principles explained above and
+in this section.
+Note however that some cryptotype
+combinations may successfully interoperate with each other,
+but may not represent good security practice.
+
+The cryptotype of an association is determined at the time
+of mobilization, either at configuration time or some time
+later when a message of appropriate cryptotype arrives.
+When mobilized by a
+.Ic
+server
+or
+.Ic
+peer
+configuration command and no
+.Ic
+key
+or
+.Ic
+autokey
+subcommands are present, the association is not
+authenticated; if the
+.Ic
+key
+subcommand is present, the association is authenticated
+using the symmetric key ID specified; if the
+.Ic
+autokey
+subcommand is present, the association is authenticated
+using Autokey.
+
+When multiple identity schemes are supported in the Autokey
+protocol, the first message exchange determines which one is used.
+The client request message contains bits corresponding
+to which schemes it has available.
+The server response message
+contains bits corresponding to which schemes it has available.
+Both server and client match the received bits with their own
+and select a common scheme.
+
+Following the principle that time is a public value,
+a server responds to any client packet that matches
+its cryptotype capabilities.
+Thus, a server receiving
+an unauthenticated packet will respond with an unauthenticated
+packet, while the same server receiving a packet of a cryptotype
+it supports will respond with packets of that cryptotype.
+However, unconfigured broadcast or manycast client
+associations or symmetric passive associations will not be
+mobilized unless the server supports a cryptotype compatible
+with the first packet received.
+By default, unauthenticated associations will not be mobilized
+unless overridden in a decidedly dangerous way.
+
+Some examples may help to reduce confusion.
+Client Alice has no specific cryptotype selected.
+Server Bob has both a symmetric key file and minimal Autokey files.
+Alice's unauthenticated messages arrive at Bob, who replies with
+unauthenticated messages.
+Cathy has a copy of Bob's symmetric
+key file and has selected key ID 4 in messages to Bob.
+Bob verifies the message with his key ID 4.
+If it's the
+same key and the message is verified, Bob sends Cathy a reply
+authenticated with that key.
+If verification fails,
+Bob sends Cathy a thing called a crypto-NAK, which tells her
+something broke.
+She can see the evidence using the ntpq program.
+
+Denise has rolled her own host key and certificate.
+She also uses one of the identity schemes as Bob.
+She sends the first Autokey message to Bob and they
+both dance the protocol authentication and identity steps.
+If all comes out okay, Denise and Bob continue as described above.
+
+It should be clear from the above that Bob can support
+all the girls at the same time, as long as he has compatible
+authentication and identity credentials.
+Now, Bob can act just like the girls in his own choice of servers;
+he can run multiple configured associations with multiple different
+servers (or the same server, although that might not be useful).
+But, wise security policy might preclude some cryptotype
+combinations; for instance, running an identity scheme
+with one server and no authentication with another might not be wise.
+.Ss
+Key
+Management
+The cryptographic values used by the Autokey protocol are
+incorporated as a set of files generated by the
+@code{ntp-keygen(1ntpkeygenmdoc)}
+utility program, including symmetric key, host key and
+public certificate files, as well as sign key, identity parameters
+and leapseconds files.
+Alternatively, host and sign keys and
+certificate files can be generated by the OpenSSL utilities
+and certificates can be imported from public certificate
+authorities.
+Note that symmetric keys are necessary for the
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+utility programs.
+The remaining files are necessary only for the
+Autokey protocol.
+
+Certificates imported from OpenSSL or public certificate
+authorities have certian limitations.
+The certificate should be in ASN.1 syntax, X.509 Version 3
+format and encoded in PEM, which is the same format
+used by OpenSSL.
+The overall length of the certificate encoded
+in ASN.1 must not exceed 1024 bytes.
+The subject distinguished
+name field (CN) is the fully qualified name of the host
+on which it is used; the remaining subject fields are ignored.
+The certificate extension fields must not contain either
+a subject key identifier or a issuer key identifier field;
+however, an extended key usage field for a trusted host must
+contain the value
+.Cm
+trustRoot
+;
+.
+Other extension fields are ignored.
+.Ss
+Authentication
+Commands
+@table @samp
+@item Ic
+Specifies the interval between regenerations of the session key
+list used with the Autokey protocol.
+Note that the size of the key
+list for each association depends on this interval and the current
+poll interval.
+The default value is 12 (4096 s or about 1.1 hours).
+For poll intervals above the specified interval, a session key list
+with a single entry will be regenerated for every message
+sent.
+@item Ic
+Specifies the key identifier to use with the
+@code{ntpq(1ntpqmdoc)}
+utility, which uses the standard
+protocol defined in RFC-1305.
+The
+.Ar
+key
+argument is
+the key identifier for a trusted key, where the value can be in the
+range 1 to 65,534, inclusive.
+@item Xo
+.Op
+Cm
+cert
+Ar
+file
+.Op
+Cm
+leap
+Ar
+file
+.Op
+Cm
+randfile
+Ar
+file
+.Op
+Cm
+host
+Ar
+file
+.Op
+Cm
+sign
+Ar
+file
+.Op
+Cm
+gq
+Ar
+file
+.Op
+Cm
+gqpar
+Ar
+file
+.Op
+Cm
+iffpar
+Ar
+file
+.Op
+Cm
+mvpar
+Ar
+file
+.Op
+Cm
+pw
+Ar
+password
+.Xc
+This command requires the OpenSSL library.
+It activates public key
+cryptography, selects the message digest and signature
+encryption scheme and loads the required private and public
+values described above.
+If one or more files are left unspecified,
+the default names are used as described above.
+Unless the complete path and name of the file are specified, the
+location of a file is relative to the keys directory specified
+in the
+.Ic
+keysdir
+command or default
+.Pa
+/usr/local/etc
+.
+Following are the subcommands:
+@table @samp
+@item Cm
+Specifies the location of the required host public certificate file.
+This overrides the link
+.Pa
+ntpkey_cert_
+Ns
+Ar
+hostname
+in the keys directory.
+@item Cm
+Specifies the location of the optional GQ parameters file.
+This
+overrides the link
+.Pa
+ntpkey_gq_
+Ns
+Ar
+hostname
+in the keys directory.
+@item Cm
+Specifies the location of the required host key file.
+This overrides
+the link
+.Pa
+ntpkey_key_
+Ns
+Ar
+hostname
+in the keys directory.
+@item Cm
+Specifies the location of the optional IFF parameters file.This
+overrides the link
+.Pa
+ntpkey_iff_
+Ns
+Ar
+hostname
+in the keys directory.
+@item Cm
+Specifies the location of the optional leapsecond file.
+This overrides the link
+.Pa
+ntpkey_leap
+in the keys directory.
+@item Cm
+Specifies the location of the optional MV parameters file.
+This
+overrides the link
+.Pa
+ntpkey_mv_
+Ns
+Ar
+hostname
+in the keys directory.
+@item Cm
+Specifies the password to decrypt files containing private keys and
+identity parameters.
+This is required only if these files have been
+encrypted.
+@item Cm
+Specifies the location of the random seed file used by the OpenSSL
+library.
+The defaults are described in the main text above.
+@item Cm
+Specifies the location of the optional sign key file.
+This overrides
+the link
+.Pa
+ntpkey_sign_
+Ns
+Ar
+hostname
+in the keys directory.
+If this file is
+not found, the host key is also the sign key.
+
+@end multitable
+.It
+Ic
+keys
+Ar
+keyfile
+Specifies the complete path and location of the MD5 key file
+containing the keys and key identifiers used by
+@code{ntpd(1ntpdmdoc)},
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+when operating with symmetric key cryptography.
+This is the same operation as the
+@code{-k} command line option.
+.It
+Ic
+keysdir
+Ar
+path
+This command specifies the default directory path for
+cryptographic keys, parameters and certificates.
+The default is
+.Pa
+/usr/local/etc/
+.
+.It
+Ic
+requestkey
+Ar
+key
+Specifies the key identifier to use with the
+@code{ntpdc(1ntpdcmdoc)}
+utility program, which uses a
+proprietary protocol specific to this implementation of
+@code{ntpd(1ntpdmdoc)}.
+The
+.Ar
+key
+argument is a key identifier
+for the trusted key, where the value can be in the range 1 to
+65,534, inclusive.
+.It
+Ic
+revoke
+Ar
+logsec
+Specifies the interval between re-randomization of certain
+cryptographic values used by the Autokey scheme, as a power of 2 in
+seconds.
+These values need to be updated frequently in order to
+deflect brute-force attacks on the algorithms of the scheme;
+however, updating some values is a relatively expensive operation.
+The default interval is 16 (65,536 s or about 18 hours).
+For poll
+intervals above the specified interval, the values will be updated
+for every message sent.
+.It
+Ic
+trustedkey
+Ar
+key
+...
+Specifies the key identifiers which are trusted for the
+purposes of authenticating peers with symmetric key cryptography,
+as well as keys used by the
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+programs.
+The authentication procedures require that both the local
+and remote servers share the same key and key identifier for this
+purpose, although different keys can be used with different
+servers.
+The
+.Ar
+key
+arguments are 32-bit unsigned
+integers with values from 1 to 65,534.
+
+@end multitable
+.Ss
+Error
+Codes
+The following error codes are reported via the NTP control
+and monitoring protocol trap mechanism.
+@table @samp
+@item 101
+.Pq
+bad
+field
+format
+or
+length
+The packet has invalid version, length or format.
+@item 102
+.Pq
+bad
+timestamp
+The packet timestamp is the same or older than the most recent received.
+This could be due to a replay or a server clock time step.
+@item 103
+.Pq
+bad
+filestamp
+The packet filestamp is the same or older than the most recent received.
+This could be due to a replay or a key file generation error.
+@item 104
+.Pq
+bad
+or
+missing
+public
+key
+The public key is missing, has incorrect format or is an unsupported type.
+@item 105
+.Pq
+unsupported
+digest
+type
+The server requires an unsupported digest/signature scheme.
+@item 106
+.Pq
+mismatched
+digest
+types
+Not used.
+@item 107
+.Pq
+bad
+signature
+length
+The signature length does not match the current public key.
+@item 108
+.Pq
+signature
+not
+verified
+The message fails the signature check.
+It could be bogus or signed by a
+different private key.
+@item 109
+.Pq
+certificate
+not
+verified
+The certificate is invalid or signed with the wrong key.
+@item 110
+.Pq
+certificate
+not
+verified
+The certificate is not yet valid or has expired or the signature could not
+be verified.
+@item 111
+.Pq
+bad
+or
+missing
+cookie
+The cookie is missing, corrupted or bogus.
+@item 112
+.Pq
+bad
+or
+missing
+leapseconds
+table
+The leapseconds table is missing, corrupted or bogus.
+@item 113
+.Pq
+bad
+or
+missing
+certificate
+The certificate is missing, corrupted or bogus.
+@item 114
+.Pq
+bad
+or
+missing
+identity
+The identity key is missing, corrupt or bogus.
+
+@end multitable
+.Sh
+Monitoring
+Support
+@code{ntpd(1ntpdmdoc)}
+includes a comprehensive monitoring facility suitable
+for continuous, long term recording of server and client
+timekeeping performance.
+See the
+.Ic
+statistics
+command below
+for a listing and example of each type of statistics currently
+supported.
+Statistic files are managed using file generation sets
+and scripts in the
+.Pa
+./scripts
+directory of this distribution.
+Using
+these facilities and
+.Ux
+@code{cron(8)}
+jobs, the data can be
+automatically summarized and archived for retrospective analysis.
+.Ss
+Monitoring
+Commands
+@table @samp
+@item Ic
+Enables writing of statistics records.
+Currently, four kinds of
+.Ar
+name
+statistics are supported.
+@table @samp
+@item Cm
+Enables recording of clock driver statistics information.
+Each update
+received from a clock driver appends a line of the following form to
+the file generation set named
+.Cm
+clockstats
+:
+.Bd
+-literal
+49213 525.624 127.127.4.1 93 226 00:08:29.606 D
+.Ed
+
+The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The next field shows the
+clock address in dotted-quad notation.
+The final field shows the last
+timecode received from the clock in decoded ASCII format, where
+meaningful.
+In some clock drivers a good deal of additional information
+can be gathered and displayed as well.
+See information specific to each
+clock for further details.
+@item Cm
+This option requires the OpenSSL cryptographic software library.
+It
+enables recording of cryptographic public key protocol information.
+Each message received by the protocol module appends a line of the
+following form to the file generation set named
+.Cm
+cryptostats
+:
+.Bd
+-literal
+49213 525.624 127.127.4.1 message
+.Ed
+
+The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The next field shows the peer
+address in dotted-quad notation, The final message field includes the
+message type and certain ancillary information.
+See the
+.Sx
+Authentication
+Options
+section for further information.
+@item Cm
+Enables recording of loop filter statistics information.
+Each
+update of the local clock outputs a line of the following form to
+the file generation set named
+.Cm
+loopstats
+:
+.Bd
+-literal
+50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
+.Ed
+
+The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next five fields
+show time offset (seconds), frequency offset (parts per million -
+PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
+discipline time constant.
+@item Cm
+Enables recording of peer statistics information.
+This includes
+statistics records of all peers of a NTP server and of special
+signals, where present and configured.
+Each valid update appends a
+line of the following form to the current element of a file
+generation set named
+.Cm
+peerstats
+:
+.Bd
+-literal
+48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
+.Ed
+
+The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next two fields
+show the peer address in dotted-quad notation and status,
+respectively.
+The status field is encoded in hex in the format
+described in Appendix A of the NTP specification RFC 1305.
+The final four fields show the offset,
+delay, dispersion and RMS jitter, all in seconds.
+@item Cm
+Enables recording of raw-timestamp statistics information.
+This
+includes statistics records of all peers of a NTP server and of
+special signals, where present and configured.
+Each NTP message
+received from a peer or clock driver appends a line of the
+following form to the file generation set named
+.Cm
+rawstats
+:
+.Bd
+-literal
+50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
+.Ed
+
+The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next two fields
+show the remote peer or clock address followed by the local address
+in dotted-quad notation.
+The final four fields show the originate,
+receive, transmit and final NTP timestamps in order.
+The timestamp
+values are as received and before processing by the various data
+smoothing and mitigation algorithms.
+@item Cm
+Enables recording of ntpd statistics counters on a periodic basis.
+Each
+hour a line of the following form is appended to the file generation
+set named
+.Cm
+sysstats
+:
+.Bd
+-literal
+50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
+.Ed
+
+The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The remaining ten fields show
+the statistics counter values accumulated since the last generated
+line.
+@table @samp
+@item Time
+Time in hours since the system was last rebooted.
+@item Packets
+Total number of packets received.
+@item Packets
+Number of packets received in response to previous packets sent
+@item Current
+Number of packets matching the current NTP version.
+@item Previous
+Number of packets matching the previous NTP version.
+@item Bad
+Number of packets matching neither NTP version.
+@item Access
+Number of packets denied access for any reason.
+@item Bad
+Number of packets with invalid length, format or port number.
+@item Bad
+Number of packets not verified as authentic.
+@item Rate
+Number of packets discarded due to rate limitation.
+
+@end multitable
+.It
+Cm
+statsdir
+Ar
+directory_path
+Indicates the full path of a directory where statistics files
+should be created (see below).
+This keyword allows
+the (otherwise constant)
+.Cm
+filegen
+filename prefix to be modified for file generation sets, which
+is useful for handling statistics logs.
+.It
+Cm
+filegen
+Ar
+name
+Xo
+.Op
+Cm
+file
+Ar
+filename
+.Op
+Cm
+type
+Ar
+typename
+.Op
+Cm
+link
+|
+nolink
+.Op
+Cm
+enable
+|
+disable
+.Xc
+Configures setting of generation file set name.
+Generation
+file sets provide a means for handling files that are
+continuously growing during the lifetime of a server.
+Server statistics are a typical example for such files.
+Generation file sets provide access to a set of files used
+to store the actual data.
+At any time at most one element
+of the set is being written to.
+The type given specifies
+when and how data will be directed to a new element of the set.
+This way, information stored in elements of a file set
+that are currently unused are available for administrational
+operations without the risk of disturbing the operation of ntpd.
+(Most important: they can be removed to free space for new data
+produced.)
+
+Note that this command can be sent from the
+@code{ntpdc(1ntpdcmdoc)}
+program running at a remote location.
+@table @samp
+@item Cm
+This is the type of the statistics records, as shown in the
+.Cm
+statistics
+command.
+@item Cm
+This is the file name for the statistics records.
+Filenames of set
+members are built from three concatenated elements
+.Ar
+Cm
+prefix
+,
+.Ar
+Cm
+filename
+and
+.Ar
+Cm
+suffix
+:
+@table @samp
+@item Cm
+This is a constant filename path.
+It is not subject to
+modifications via the
+.Ar
+filegen
+option.
+It is defined by the
+server, usually specified as a compile-time constant.
+It may,
+however, be configurable for individual file generation sets
+via other commands.
+For example, the prefix used with
+.Ar
+loopstats
+and
+.Ar
+peerstats
+generation can be configured using the
+.Ar
+statsdir
+option explained above.
+@item Cm
+This string is directly concatenated to the prefix mentioned
+above (no intervening
+.Ql
+/
+)
+.
+This can be modified using
+the file argument to the
+.Ar
+filegen
+statement.
+No
+.Pa
+..
+elements are
+allowed in this component to prevent filenames referring to
+parts outside the filesystem hierarchy denoted by
+.Ar
+prefix
+.
+@item Cm
+This part is reflects individual elements of a file set.
+It is
+generated according to the type of a file set.
+
+@end multitable
+.It
+Cm
+type
+Ar
+typename
+A file generation set is characterized by its type.
+The following
+types are supported:
+@table @samp
+@item Cm
+The file set is actually a single plain file.
+@item Cm
+One element of file set is used per incarnation of a ntpd
+server.
+This type does not perform any changes to file set
+members during runtime, however it provides an easy way of
+separating files belonging to different
+@code{ntpd(1ntpdmdoc)}
+server incarnations.
+The set member filename is built by appending a
+.Ql
+\&.
+to concatenated
+.Ar
+prefix
+and
+.Ar
+filename
+strings, and
+appending the decimal representation of the process ID of the
+@code{ntpd(1ntpdmdoc)}
+server process.
+@item Cm
+One file generation set element is created per day.
+A day is
+defined as the period between 00:00 and 24:00 UTC.
+The file set
+member suffix consists of a
+.Ql
+\&.
+and a day specification in
+the form
+.Cm
+YYYYMMdd
+.
+.Cm
+YYYY
+is a 4-digit year number (e.g., 1992).
+.Cm
+MM
+is a two digit month number.
+.Cm
+dd
+is a two digit day number.
+Thus, all information written at 10 December 1992 would end up
+in a file named
+.Ar
+prefix
+.Ar
+filename
+Ns
+.19921210
+.
+@item Cm
+Any file set member contains data related to a certain week of
+a year.
+The term week is defined by computing day-of-year
+modulo 7.
+Elements of such a file generation set are
+distinguished by appending the following suffix to the file set
+filename base: A dot, a 4-digit year number, the letter
+.Cm
+W
+,
+and a 2-digit week number.
+For example, information from January,
+10th 1992 would end up in a file with suffix
+.No
+.
+Ns
+Ar
+1992W1
+.
+@item Cm
+One generation file set element is generated per month.
+The
+file name suffix consists of a dot, a 4-digit year number, and
+a 2-digit month.
+@item Cm
+One generation file element is generated per year.
+The filename
+suffix consists of a dot and a 4 digit year number.
+@item Cm
+This type of file generation sets changes to a new element of
+the file set every 24 hours of server operation.
+The filename
+suffix consists of a dot, the letter
+.Cm
+a
+,
+and an 8-digit number.
+This number is taken to be the number of seconds the server is
+running at the start of the corresponding 24-hour period.
+Information is only written to a file generation by specifying
+.Cm
+enable
+;
+output is prevented by specifying
+.Cm
+disable
+.
+
+@end multitable
+.It
+Cm
+link
+|
+nolink
+It is convenient to be able to access the current element of a file
+generation set by a fixed name.
+This feature is enabled by
+specifying
+.Cm
+link
+and disabled using
+.Cm
+nolink
+.
+If link is specified, a
+hard link from the current file set element to a file without
+suffix is created.
+When there is already a file with this name and
+the number of links of this file is one, it is renamed appending a
+dot, the letter
+.Cm
+C
+,
+and the pid of the ntpd server process.
+When the
+number of links is greater than one, the file is unlinked.
+This
+allows the current file to be accessed by a constant name.
+.It
+Cm
+enable
+\&|
+Cm
+disable
+Enables or disables the recording function.
+
+@end multitable
+
+@end multitable
+
+@end multitable
+.Sh
+Access
+Control
+Support
+The
+@code{ntpd(1ntpdmdoc)}
+daemon implements a general purpose address/mask based restriction
+list.
+The list contains address/match entries sorted first
+by increasing address values and and then by increasing mask values.
+A match occurs when the bitwise AND of the mask and the packet
+source address is equal to the bitwise AND of the mask and
+address in the list.
+The list is searched in order with the
+last match found defining the restriction flags associated
+with the entry.
+Additional information and examples can be found in the
+.Qq
+Notes
+on
+Configuring
+NTP
+and
+Setting
+up
+a
+NTP
+Subnet
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+
+The restriction facility was implemented in conformance
+with the access policies for the original NSFnet backbone
+time servers.
+Later the facility was expanded to deflect
+cryptographic and clogging attacks.
+While this facility may
+be useful for keeping unwanted or broken or malicious clients
+from congesting innocent servers, it should not be considered
+an alternative to the NTP authentication facilities.
+Source address based restrictions are easily circumvented
+by a determined cracker.
+
+Clients can be denied service because they are explicitly
+included in the restrict list created by the restrict command
+or implicitly as the result of cryptographic or rate limit
+violations.
+Cryptographic violations include certificate
+or identity verification failure; rate limit violations generally
+result from defective NTP implementations that send packets
+at abusive rates.
+Some violations cause denied service
+only for the offending packet, others cause denied service
+for a timed period and others cause the denied service for
+an indefinate period.
+When a client or network is denied access
+for an indefinate period, the only way at present to remove
+the restrictions is by restarting the server.
+.Ss
+The
+Kiss-of-Death
+Packet
+Ordinarily, packets denied service are simply dropped with no
+further action except incrementing statistics counters.
+Sometimes a
+more proactive response is needed, such as a server message that
+explicitly requests the client to stop sending and leave a message
+for the system operator.
+A special packet format has been created
+for this purpose called the "kiss-of-death" (KoD) packet.
+KoD packets have the leap bits set unsynchronized and stratum set
+to zero and the reference identifier field set to a four-byte
+ASCII code.
+If the
+.Cm
+noserve
+or
+.Cm
+notrust
+flag of the matching restrict list entry is set,
+the code is "DENY"; if the
+.Cm
+limited
+flag is set and the rate limit
+is exceeded, the code is "RATE".
+Finally, if a cryptographic violation occurs, the code is "CRYP".
+
+A client receiving a KoD performs a set of sanity checks to
+minimize security exposure, then updates the stratum and
+reference identifier peer variables, sets the access
+denied (TEST4) bit in the peer flash variable and sends
+a message to the log.
+As long as the TEST4 bit is set,
+the client will send no further packets to the server.
+The only way at present to recover from this condition is
+to restart the protocol at both the client and server.
+This
+happens automatically at the client when the association times out.
+It will happen at the server only if the server operator cooperates.
+.Ss
+Access
+Control
+Commands
+@table @samp
+@item Xo
+.Op
+Cm
+average
+Ar
+avg
+.Op
+Cm
+minimum
+Ar
+min
+.Op
+Cm
+monitor
+Ar
+prob
+.Xc
+Set the parameters of the
+.Cm
+limited
+facility which protects the server from
+client abuse.
+The
+.Cm
+average
+subcommand specifies the minimum average packet
+spacing, while the
+.Cm
+minimum
+subcommand specifies the minimum packet spacing.
+Packets that violate these minima are discarded
+and a kiss-o'-death packet returned if enabled.
+The default
+minimum average and minimum are 5 and 2, respectively.
+The monitor subcommand specifies the probability of discard
+for packets that overflow the rate-control window.
+@item Xo
+.Op
+Cm
+mask
+Ar
+mask
+.Op
+Ar
+flag
+...
+.Xc
+The
+.Ar
+address
+argument expressed in
+dotted-quad form is the address of a host or network.
+Alternatively, the
+.Ar
+address
+argument can be a valid host DNS name.
+The
+.Ar
+mask
+argument expressed in dotted-quad form defaults to
+.Cm
+255.255.255.255
+,
+meaning that the
+.Ar
+address
+is treated as the address of an individual host.
+A default entry (address
+.Cm
+0.0.0.0
+,
+mask
+.Cm
+0.0.0.0
+)
+is always included and is always the first entry in the list.
+Note that text string
+.Cm
+default
+,
+with no mask option, may
+be used to indicate the default entry.
+In the current implementation,
+.Cm
+flag
+always
+restricts access, i.e., an entry with no flags indicates that free
+access to the server is to be given.
+The flags are not orthogonal,
+in that more restrictive flags will often make less restrictive
+ones redundant.
+The flags can generally be classed into two
+categories, those which restrict time service and those which
+restrict informational queries and attempts to do run-time
+reconfiguration of the server.
+One or more of the following flags
+may be specified:
+@table @samp
+@item Cm
+Deny packets of all kinds, including
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+queries.
+@item Cm
+If this flag is set when an access violation occurs, a kiss-o'-death
+(KoD) packet is sent.
+KoD packets are rate limited to no more than one
+per second.
+If another KoD packet occurs within one second after the
+last one, the packet is dropped.
+@item Cm
+Deny service if the packet spacing violates the lower limits specified
+in the discard command.
+A history of clients is kept using the
+monitoring capability of
+@code{ntpd(1ntpdmdoc)}.
+Thus, monitoring is always active as
+long as there is a restriction entry with the
+.Cm
+limited
+flag.
+@item Cm
+Declare traps set by matching hosts to be low priority.
+The
+number of traps a server can maintain is limited (the current limit
+is 3).
+Traps are usually assigned on a first come, first served
+basis, with later trap requestors being denied service.
+This flag
+modifies the assignment algorithm by allowing low priority traps to
+be overridden by later requests for normal priority traps.
+@item Cm
+Deny
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+queries which attempt to modify the state of the
+server (i.e., run time reconfiguration).
+Queries which return
+information are permitted.
+@item Cm
+Deny
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+queries.
+Time service is not affected.
+@item Cm
+Deny packets which would result in mobilizing a new association.
+This
+includes broadcast and symmetric active packets when a configured
+association does not exist.
+@item Cm
+Deny all packets except
+@code{ntpq(1ntpqmdoc)}
+and
+@code{ntpdc(1ntpdcmdoc)}
+queries.
+@item Cm
+Decline to provide mode 6 control message trap service to matching
+hosts.
+The trap service is a subsystem of the ntpdq control message
+protocol which is intended for use by remote event logging programs.
+@item Cm
+Deny service unless the packet is cryptographically authenticated.
+@item Cm
+This is actually a match algorithm modifier, rather than a
+restriction flag.
+Its presence causes the restriction entry to be
+matched only if the source port in the packet is the standard NTP
+UDP port (123).
+Both
+.Cm
+ntpport
+and
+.Cm
+non-ntpport
+may
+be specified.
+The
+.Cm
+ntpport
+is considered more specific and
+is sorted later in the list.
+@item Cm
+Deny packets that do not match the current NTP version.
+
+@end multitable
+
+Default restriction list entries with the flags ignore, interface,
+ntpport, for each of the local host's interface addresses are
+inserted into the table at startup to prevent the server
+from attempting to synchronize to its own time.
+A default entry is also always present, though if it is
+otherwise unconfigured; no flags are associated
+with the default entry (i.e., everything besides your own
+NTP server is unrestricted).
+
+@end multitable
+.Sh
+Automatic
+NTP
+Configuration
+Options
+.Ss
+Manycasting
+Manycasting is a automatic discovery and configuration paradigm
+new to NTPv4.
+It is intended as a means for a multicast client
+to troll the nearby network neighborhood to find cooperating
+manycast servers, validate them using cryptographic means
+and evaluate their time values with respect to other servers
+that might be lurking in the vicinity.
+The intended result is that each manycast client mobilizes
+client associations with some number of the "best"
+of the nearby manycast servers, yet automatically reconfigures
+to sustain this number of servers should one or another fail.
+
+Note that the manycasting paradigm does not coincide
+with the anycast paradigm described in RFC-1546,
+which is designed to find a single server from a clique
+of servers providing the same service.
+The manycast paradigm is designed to find a plurality
+of redundant servers satisfying defined optimality criteria.
+
+Manycasting can be used with either symmetric key
+or public key cryptography.
+The public key infrastructure (PKI)
+offers the best protection against compromised keys
+and is generally considered stronger, at least with relatively
+large key sizes.
+It is implemented using the Autokey protocol and
+the OpenSSL cryptographic library available from
+.Li
+http://www.openssl.org/
+.
+The library can also be used with other NTPv4 modes
+as well and is highly recommended, especially for broadcast modes.
+
+A persistent manycast client association is configured
+using the manycastclient command, which is similar to the
+server command but with a multicast (IPv4 class
+.Cm
+D
+or IPv6 prefix
+.Cm
+FF
+)
+group address.
+The IANA has designated IPv4 address 224.1.1.1
+and IPv6 address FF05::101 (site local) for NTP.
+When more servers are needed, it broadcasts manycast
+client messages to this address at the minimum feasible rate
+and minimum feasible time-to-live (TTL) hops, depending
+on how many servers have already been found.
+There can be as many manycast client associations
+as different group address, each one serving as a template
+for a future ephemeral unicast client/server association.
+
+Manycast servers configured with the
+.Ic
+manycastserver
+command listen on the specified group address for manycast
+client messages.
+Note the distinction between manycast client,
+which actively broadcasts messages, and manycast server,
+which passively responds to them.
+If a manycast server is
+in scope of the current TTL and is itself synchronized
+to a valid source and operating at a stratum level equal
+to or lower than the manycast client, it replies to the
+manycast client message with an ordinary unicast server message.
+
+The manycast client receiving this message mobilizes
+an ephemeral client/server association according to the
+matching manycast client template, but only if cryptographically
+authenticated and the server stratum is less than or equal
+to the client stratum.
+Authentication is explicitly required
+and either symmetric key or public key (Autokey) can be used.
+Then, the client polls the server at its unicast address
+in burst mode in order to reliably set the host clock
+and validate the source.
+This normally results
+in a volley of eight client/server at 2-s intervals
+during which both the synchronization and cryptographic
+protocols run concurrently.
+Following the volley,
+the client runs the NTP intersection and clustering
+algorithms, which act to discard all but the "best"
+associations according to stratum and synchronization
+distance.
+The surviving associations then continue
+in ordinary client/server mode.
+
+The manycast client polling strategy is designed to reduce
+as much as possible the volume of manycast client messages
+and the effects of implosion due to near-simultaneous
+arrival of manycast server messages.
+The strategy is determined by the
+.Ic
+manycastclient
+,
+.Ic
+tos
+and
+.Ic
+ttl
+configuration commands.
+The manycast poll interval is
+normally eight times the system poll interval,
+which starts out at the
+.Cm
+minpoll
+value specified in the
+.Ic
+manycastclient
+,
+command and, under normal circumstances, increments to the
+.Cm
+maxpolll
+value specified in this command.
+Initially, the TTL is
+set at the minimum hops specified by the ttl command.
+At each retransmission the TTL is increased until reaching
+the maximum hops specified by this command or a sufficient
+number client associations have been found.
+Further retransmissions use the same TTL.
+
+The quality and reliability of the suite of associations
+discovered by the manycast client is determined by the NTP
+mitigation algorithms and the
+.Cm
+minclock
+and
+.Cm
+minsane
+values specified in the
+.Ic
+tos
+configuration command.
+At least
+.Cm
+minsane
+candidate servers must be available and the mitigation
+algorithms produce at least
+.Cm
+minclock
+survivors in order to synchronize the clock.
+Byzantine agreement principles require at least four
+candidates in order to correctly discard a single falseticker.
+For legacy purposes,
+.Cm
+minsane
+defaults to 1 and
+.Cm
+minclock
+defaults to 3.
+For manycast service
+.Cm
+minsane
+should be explicitly set to 4, assuming at least that
+number of servers are available.
+
+If at least
+.Cm
+minclock
+servers are found, the manycast poll interval is immediately
+set to eight times
+.Cm
+maxpoll
+.
+If less than
+.Cm
+minclock
+servers are found when the TTL has reached the maximum hops,
+the manycast poll interval is doubled.
+For each transmission
+after that, the poll interval is doubled again until
+reaching the maximum of eight times
+.Cm
+maxpoll
+.
+Further transmissions use the same poll interval and
+TTL values.
+Note that while all this is going on,
+each client/server association found is operating normally
+it the system poll interval.
+
+Administratively scoped multicast boundaries are normally
+specified by the network router configuration and,
+in the case of IPv6, the link/site scope prefix.
+By default, the increment for TTL hops is 32 starting
+from 31; however, the
+.Ic
+ttl
+configuration command can be
+used to modify the values to match the scope rules.
+
+It is often useful to narrow the range of acceptable
+servers which can be found by manycast client associations.
+Because manycast servers respond only when the client
+stratum is equal to or greater than the server stratum,
+primary (stratum 1) servers fill find only primary servers
+in TTL range, which is probably the most common objective.
+However, unless configured otherwise, all manycast clients
+in TTL range will eventually find all primary servers
+in TTL range, which is probably not the most common
+objective in large networks.
+The
+.Ic
+tos
+command can be used to modify this behavior.
+Servers with stratum below
+.Cm
+floor
+or above
+.Cm
+ceiling
+specified in the
+.Ic
+tos
+command are strongly discouraged during the selection
+process; however, these servers may be temporally
+accepted if the number of servers within TTL range is
+less than
+.Cm
+minclock
+.
+
+The above actions occur for each manycast client message,
+which repeats at the designated poll interval.
+However, once the ephemeral client association is mobilized,
+subsequent manycast server replies are discarded,
+since that would result in a duplicate association.
+If during a poll interval the number of client associations
+falls below
+.Cm
+minclock
+,
+all manycast client prototype associations are reset
+to the initial poll interval and TTL hops and operation
+resumes from the beginning.
+It is important to avoid
+frequent manycast client messages, since each one requires
+all manycast servers in TTL range to respond.
+The result could well be an implosion, either minor or major,
+depending on the number of servers in range.
+The recommended value for
+.Cm
+maxpoll
+is 12 (4,096 s).
+
+It is possible and frequently useful to configure a host
+as both manycast client and manycast server.
+A number of hosts configured this way and sharing a common
+group address will automatically organize themselves
+in an optimum configuration based on stratum and
+synchronization distance.
+For example, consider an NTP
+subnet of two primary servers and a hundred or more
+dependent clients.
+With two exceptions, all servers
+and clients have identical configuration files including both
+.Ic
+multicastclient
+and
+.Ic
+multicastserver
+commands using, for instance, multicast group address
+239.1.1.1.
+The only exception is that each primary server
+configuration file must include commands for the primary
+reference source such as a GPS receiver.
+
+The remaining configuration files for all secondary
+servers and clients have the same contents, except for the
+.Ic
+tos
+command, which is specific for each stratum level.
+For stratum 1 and stratum 2 servers, that command is
+not necessary.
+For stratum 3 and above servers the
+.Cm
+floor
+value is set to the intended stratum number.
+Thus, all stratum 3 configuration files are identical,
+all stratum 4 files are identical and so forth.
+
+Once operations have stabilized in this scenario,
+the primary servers will find the primary reference source
+and each other, since they both operate at the same
+stratum (1), but not with any secondary server or client,
+since these operate at a higher stratum.
+The secondary
+servers will find the servers at the same stratum level.
+If one of the primary servers loses its GPS receiver,
+it will continue to operate as a client and other clients
+will time out the corresponding association and
+re-associate accordingly.
+
+Some administrators prefer to avoid running
+@code{ntpd(1ntpdmdoc)}
+continuously and run either
+@code{ntpdate(8)}
+or
+@code{ntpd(1ntpdmdoc)}
+@code{-q} as a cron job.
+In either case the servers must be
+configured in advance and the program fails if none are
+available when the cron job runs.
+A really slick
+application of manycast is with
+@code{ntpd(1ntpdmdoc)}
+@code{-q}. The program wakes up, scans the local landscape looking
+for the usual suspects, selects the best from among
+the rascals, sets the clock and then departs.
+Servers do not have to be configured in advance and
+all clients throughout the network can have the same
+configuration file.
+.Ss
+Manycast
+Interactions
+with
+Autokey
+Each time a manycast client sends a client mode packet
+to a multicast group address, all manycast servers
+in scope generate a reply including the host name
+and status word.
+The manycast clients then run
+the Autokey protocol, which collects and verifies
+all certificates involved.
+Following the burst interval
+all but three survivors are cast off,
+but the certificates remain in the local cache.
+It often happens that several complete signing trails
+from the client to the primary servers are collected in this way.
+
+About once an hour or less often if the poll interval
+exceeds this, the client regenerates the Autokey key list.
+This is in general transparent in client/server mode.
+However, about once per day the server private value
+used to generate cookies is refreshed along with all
+manycast client associations.
+In this case all
+cryptographic values including certificates is refreshed.
+If a new certificate has been generated since
+the last refresh epoch, it will automatically revoke
+all prior certificates that happen to be in the
+certificate cache.
+At the same time, the manycast
+scheme starts all over from the beginning and
+the expanding ring shrinks to the minimum and increments
+from there while collecting all servers in scope.
+.Ss
+Manycast
+Options
+@table @samp
+@item Xo
+.Oo
+.Cm
+ceiling
+Ar
+ceiling
+|
+.Cm
+cohort
+{
+0.Cm
+floor
+Ar
+floor
+|
+.Cm
+minclock
+Ar
+minclock
+|
+.Cm
+minsane
+Ar
+minsane
+.Oc
+.Xc
+This command affects the clock selection and clustering
+algorithms.
+It can be used to select the quality and
+quantity of peers used to synchronize the system clock
+and is most useful in manycast mode.
+The variables operate
+as follows:
+@table @samp
+@item Cm
+Peers with strata above
+.Cm
+ceiling
+will be discarded if there are at least
+.Cm
+minclock
+peers remaining.
+This value defaults to 15, but can be changed
+to any number from 1 to 15.
+@item Cm
+This is a binary flag which enables (0) or disables (1)
+manycast server replies to manycast clients with the same
+stratum level.
+This is useful to reduce implosions where
+large numbers of clients with the same stratum level
+are present.
+The default is to enable these replies.
+@item Cm
+Peers with strata below
+.Cm
+floor
+will be discarded if there are at least
+.Cm
+minclock
+peers remaining.
+This value defaults to 1, but can be changed
+to any number from 1 to 15.
+@item Cm
+The clustering algorithm repeatedly casts out outlyer
+associations until no more than
+.Cm
+minclock
+associations remain.
+This value defaults to 3,
+but can be changed to any number from 1 to the number of
+configured sources.
+@item Cm
+This is the minimum number of candidates available
+to the clock selection algorithm in order to produce
+one or more truechimers for the clustering algorithm.
+If fewer than this number are available, the clock is
+undisciplined and allowed to run free.
+The default is 1
+for legacy purposes.
+However, according to principles of
+Byzantine agreement,
+.Cm
+minsane
+should be at least 4 in order to detect and discard
+a single falseticker.
+
+@end multitable
+.It
+Cm
+ttl
+Ar
+hop
+...
+This command specifies a list of TTL values in increasing
+order, up to 8 values can be specified.
+In manycast mode these values are used in turn
+in an expanding-ring search.
+The default is eight
+multiples of 32 starting at 31.
+
+@end multitable
+.Sh
+Reference
+Clock
+Support
+The NTP Version 4 daemon supports some three dozen different radio,
+satellite and modem reference clocks plus a special pseudo-clock
+used for backup or when no other clock source is available.
+Detailed descriptions of individual device drivers and options can
+be found in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+Additional information can be found in the pages linked
+there, including the
+.Qq
+Debugging
+Hints
+for
+Reference
+Clock
+Drivers
+and
+.Qq
+How
+To
+Write
+a
+Reference
+Clock
+Driver
+pages
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+In addition, support for a PPS
+signal is available as described in the
+.Qq
+Pulse-per-second
+(PPS)
+Signal
+Interfacing
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+Many
+drivers support special line discipline/streams modules which can
+significantly improve the accuracy using the driver.
+These are
+described in the
+.Qq
+Line
+Disciplines
+and
+Streams
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+
+A reference clock will generally (though not always) be a radio
+timecode receiver which is synchronized to a source of standard
+time such as the services offered by the NRC in Canada and NIST and
+USNO in the US.
+The interface between the computer and the timecode
+receiver is device dependent, but is usually a serial port.
+A
+device driver specific to each reference clock must be selected and
+compiled in the distribution; however, most common radio, satellite
+and modem clocks are included by default.
+Note that an attempt to
+configure a reference clock when the driver has not been compiled
+or the hardware port has not been appropriately configured results
+in a scalding remark to the system log file, but is otherwise non
+hazardous.
+
+For the purposes of configuration,
+@code{ntpd(1ntpdmdoc)}
+treats
+reference clocks in a manner analogous to normal NTP peers as much
+as possible.
+Reference clocks are identified by a syntactically
+correct but invalid IP address, in order to distinguish them from
+normal NTP peers.
+Reference clock addresses are of the form
+.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+,
+.Sm
+on
+where
+.Ar
+t
+is an integer
+denoting the clock type and
+.Ar
+u
+indicates the unit
+number in the range 0-3.
+While it may seem overkill, it is in fact
+sometimes useful to configure multiple reference clocks of the same
+type, in which case the unit numbers must be unique.
+
+The
+.Ic
+server
+command is used to configure a reference
+clock, where the
+.Ar
+address
+argument in that command
+is the clock address.
+The
+.Cm
+key
+,
+.Cm
+version
+and
+.Cm
+ttl
+options are not used for reference clock support.
+The
+.Cm
+mode
+option is added for reference clock support, as
+described below.
+The
+.Cm
+prefer
+option can be useful to
+persuade the server to cherish a reference clock with somewhat more
+enthusiasm than other reference clocks or peers.
+Further
+information on this option can be found in the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+page.
+The
+.Cm
+minpoll
+and
+.Cm
+maxpoll
+options have
+meaning only for selected clock drivers.
+See the individual clock
+driver document pages for additional information.
+
+The
+.Ic
+fudge
+command is used to provide additional
+information for individual clock drivers and normally follows
+immediately after the
+.Ic
+server
+command.
+The
+.Ar
+address
+argument specifies the clock address.
+The
+.Cm
+refid
+and
+.Cm
+stratum
+options can be used to
+override the defaults for the device.
+There are two optional
+device-dependent time offsets and four flags that can be included
+in the
+.Ic
+fudge
+command as well.
+
+The stratum number of a reference clock is by default zero.
+Since the
+@code{ntpd(1ntpdmdoc)}
+daemon adds one to the stratum of each
+peer, a primary server ordinarily displays an external stratum of
+one.
+In order to provide engineered backups, it is often useful to
+specify the reference clock stratum as greater than zero.
+The
+.Cm
+stratum
+option is used for this purpose.
+Also, in cases
+involving both a reference clock and a pulse-per-second (PPS)
+discipline signal, it is useful to specify the reference clock
+identifier as other than the default, depending on the driver.
+The
+.Cm
+refid
+option is used for this purpose.
+Except where noted,
+these options apply to all clock drivers.
+.Ss
+Reference
+Clock
+Commands
+@table @samp
+@item Xo
+.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+.Sm
+on
+.Op
+Cm
+prefer
+.Op
+Cm
+mode
+Ar
+int
+.Op
+Cm
+minpoll
+Ar
+int
+.Op
+Cm
+maxpoll
+Ar
+int
+.Xc
+This command can be used to configure reference clocks in
+special ways.
+The options are interpreted as follows:
+@table @samp
+@item Cm
+Marks the reference clock as preferred.
+All other things being
+equal, this host will be chosen for synchronization among a set of
+correctly operating hosts.
+See the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+for further information.
+@item Cm
+Specifies a mode number which is interpreted in a
+device-specific fashion.
+For instance, it selects a dialing
+protocol in the ACTS driver and a device subtype in the
+parse
+drivers.
+@item Cm
+@item Cm
+These options specify the minimum and maximum polling interval
+for reference clock messages, as a power of 2 in seconds
+For
+most directly connected reference clocks, both
+.Cm
+minpoll
+and
+.Cm
+maxpoll
+default to 6 (64 s).
+For modem reference clocks,
+.Cm
+minpoll
+defaults to 10 (17.1 m) and
+.Cm
+maxpoll
+defaults to 14 (4.5 h).
+The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
+
+@end multitable
+.It
+Xo
+Ic
+fudge
+.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+.Sm
+on
+.Op
+Cm
+time1
+Ar
+sec
+.Op
+Cm
+time2
+Ar
+sec
+.Op
+Cm
+stratum
+Ar
+int
+.Op
+Cm
+refid
+Ar
+string
+.Op
+Cm
+mode
+Ar
+int
+.Op
+Cm
+flag1
+Cm
+0.Op
+Cm
+flag2
+Cm
+0.Op
+Cm
+flag3
+Cm
+0.Op
+Cm
+flag4
+Cm
+0.Xc
+This command can be used to configure reference clocks in
+special ways.
+It must immediately follow the
+.Ic
+server
+command which configures the driver.
+Note that the same capability
+is possible at run time using the
+@code{ntpdc(1ntpdcmdoc)}
+program.
+The options are interpreted as
+follows:
+@table @samp
+@item Cm
+Specifies a constant to be added to the time offset produced by
+the driver, a fixed-point decimal number in seconds.
+This is used
+as a calibration constant to adjust the nominal time offset of a
+particular clock to agree with an external standard, such as a
+precision PPS signal.
+It also provides a way to correct a
+systematic error or bias due to serial port or operating system
+latencies, different cable lengths or receiver internal delay.
+The
+specified offset is in addition to the propagation delay provided
+by other means, such as internal DIPswitches.
+Where a calibration
+for an individual system and driver is available, an approximate
+correction is noted in the driver documentation pages.
+Note: in order to facilitate calibration when more than one
+radio clock or PPS signal is supported, a special calibration
+feature is available.
+It takes the form of an argument to the
+.Ic
+enable
+command described in
+.Sx
+Miscellaneous
+Options
+page and operates as described in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+@item Cm
+Specifies a fixed-point decimal number in seconds, which is
+interpreted in a driver-dependent way.
+See the descriptions of
+specific drivers in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+@item Cm
+Specifies the stratum number assigned to the driver, an integer
+between 0 and 15.
+This number overrides the default stratum number
+ordinarily assigned by the driver itself, usually zero.
+@item Cm
+Specifies an ASCII string of from one to four characters which
+defines the reference identifier used by the driver.
+This string
+overrides the default identifier ordinarily assigned by the driver
+itself.
+@item Cm
+Specifies a mode number which is interpreted in a
+device-specific fashion.
+For instance, it selects a dialing
+protocol in the ACTS driver and a device subtype in the
+parse
+drivers.
+@item Cm
+@item Cm
+@item Cm
+@item Cm
+These four flags are used for customizing the clock driver.
+The
+interpretation of these values, and whether they are used at all,
+is a function of the particular clock driver.
+However, by
+convention
+.Cm
+flag4
+is used to enable recording monitoring
+data to the
+.Cm
+clockstats
+file configured with the
+.Ic
+filegen
+command.
+Further information on the
+.Ic
+filegen
+command can be found in
+.Sx
+Monitoring
+Options
+.
+
+@end multitable
+
+@end multitable
+.Sh
+Miscellaneous
+Options
+@table @samp
+@item Ic
+The broadcast and multicast modes require a special calibration
+to determine the network delay between the local and remote
+servers.
+Ordinarily, this is done automatically by the initial
+protocol exchanges between the client and server.
+In some cases,
+the calibration procedure may fail due to network or server access
+controls, for example.
+This command specifies the default delay to
+be used under these circumstances.
+Typically (for Ethernet), a
+number between 0.003 and 0.007 seconds is appropriate.
+The default
+when this command is not used is 0.004 seconds.
+@item Ic
+This option controls the delay in seconds between the first and second
+packets sent in burst or iburst mode to allow additional time for a modem
+or ISDN call to complete.
+@item Ic
+This command specifies the complete path and name of the file used to
+record the frequency of the local clock oscillator.
+This is the same
+operation as the
+@code{-f} command line option.
+If the file exists, it is read at
+startup in order to set the initial frequency and then updated once per
+hour with the current frequency computed by the daemon.
+If the file name is
+specified, but the file itself does not exist, the starts with an initial
+frequency of zero and creates the file when writing it for the first time.
+If this command is not given, the daemon will always start with an initial
+frequency of zero.
+
+The file format consists of a single line containing a single
+floating point number, which records the frequency offset measured
+in parts-per-million (PPM).
+The file is updated by first writing
+the current drift value into a temporary file and then renaming
+this file to replace the old version.
+This implies that
+@code{ntpd(1ntpdmdoc)}
+must have write permission for the directory the
+drift file is located in, and that file system links, symbolic or
+otherwise, should be avoided.
+@item Xo
+.Oo
+.Cm
+auth
+|
+Cm
+bclient
+|
+.Cm
+calibrate
+|
+Cm
+kernel
+|
+.Cm
+monitor
+|
+Cm
+ntp
+|
+.Cm
+pps
+|
+Cm
+stats
+.Oc
+.Xc
+@item Xo
+.Oo
+.Cm
+auth
+|
+Cm
+bclient
+|
+.Cm
+calibrate
+|
+Cm
+kernel
+|
+.Cm
+monitor
+|
+Cm
+ntp
+|
+.Cm
+pps
+|
+Cm
+stats
+.Oc
+.Xc
+Provides a way to enable or disable various server options.
+Flags not mentioned are unaffected.
+Note that all of these flags
+can be controlled remotely using the
+@code{ntpdc(1ntpdcmdoc)}
+utility program.
+@table @samp
+@item Cm
+Enables the server to synchronize with unconfigured peers only if the
+peer has been correctly authenticated using either public key or
+private key cryptography.
+The default for this flag is
+.Ic
+enable
+.
+@item Cm
+Enables the server to listen for a message from a broadcast or
+multicast server, as in the
+.Ic
+multicastclient
+command with default
+address.
+The default for this flag is
+.Ic
+disable
+.
+@item Cm
+Enables the calibrate feature for reference clocks.
+The default for
+this flag is
+.Ic
+disable
+.
+@item Cm
+Enables the kernel time discipline, if available.
+The default for this
+flag is
+.Ic
+enable
+if support is available, otherwise
+.Ic
+disable
+.
+@item Cm
+Enables the monitoring facility.
+See the
+@code{ntpdc(1ntpdcmdoc)}
+program
+and the
+.Ic
+monlist
+command or further information.
+The
+default for this flag is
+.Ic
+enable
+.
+@item Cm
+Enables time and frequency discipline.
+In effect, this switch opens and
+closes the feedback loop, which is useful for testing.
+The default for
+this flag is
+.Ic
+enable
+.
+@item Cm
+Enables the pulse-per-second (PPS) signal when frequency and time is
+disciplined by the precision time kernel modifications.
+See the
+.Qq
+A
+Kernel
+Model
+for
+Precision
+Timekeeping
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+page for further information.
+The default for this flag is
+.Ic
+disable
+.
+@item Cm
+Enables the statistics facility.
+See the
+.Sx
+Monitoring
+Options
+section for further information.
+The default for this flag is
+.Ic
+disable
+.
+
+@end multitable
+.It
+Ic
+includefile
+Ar
+includefile
+This command allows additional configuration commands
+to be included from a separate file.
+Include files may
+be nested to a depth of five; upon reaching the end of any
+include file, command processing resumes in the previous
+configuration file.
+This option is useful for sites that run
+@code{ntpd(1ntpdmdoc)}
+on multiple hosts, with (mostly) common options (e.g., a
+restriction list).
+.It
+Ic
+logconfig
+Ar
+configkeyword
+This command controls the amount and type of output written to
+the system
+@code{syslog(3)}
+facility or the alternate
+.Ic
+logfile
+log file.
+By default, all output is turned on.
+All
+.Ar
+configkeyword
+keywords can be prefixed with
+.Ql
+=
+,
+.Ql
++
+and
+.Ql
+-
+,
+where
+.Ql
+=
+sets the
+@code{syslog(3)}
+priority mask,
+.Ql
++
+adds and
+.Ql
+-
+removes
+messages.
+@code{syslog(3)}
+messages can be controlled in four
+classes
+.Po
+.Cm
+clock
+,
+.Cm
+peer
+,
+.Cm
+sys
+and
+.Cm
+sync
+.Pc
+.
+Within these classes four types of messages can be
+controlled: informational messages
+.Po
+.Cm
+info
+.Pc
+,
+event messages
+.Po
+.Cm
+events
+.Pc
+,
+statistics messages
+.Po
+.Cm
+statistics
+.Pc
+and
+status messages
+.Po
+.Cm
+status
+.Pc
+.
+
+Configuration keywords are formed by concatenating the message class with
+the event class.
+The
+.Cm
+all
+prefix can be used instead of a message class.
+A
+message class may also be followed by the
+.Cm
+all
+keyword to enable/disable all
+messages of the respective message class.Thus, a minimal log configuration
+could look like this:
+.Bd
+-literal
+logconfig =syncstatus +sysevents
+.Ed
+
+This would just list the synchronizations state of
+@code{ntpd(1ntpdmdoc)}
+and the major system events.
+For a simple reference server, the
+following minimum message configuration could be useful:
+.Bd
+-literal
+logconfig =syncall +clockall
+.Ed
+
+This configuration will list all clock information and
+synchronization information.
+All other events and messages about
+peers, system events and so on is suppressed.
+.It
+Ic
+logfile
+Ar
+logfile
+This command specifies the location of an alternate log file to
+be used instead of the default system
+@code{syslog(3)}
+facility.
+This is the same operation as the -l command line option.
+.It
+Ic
+setvar
+Ar
+variable
+Op
+Cm
+default
+This command adds an additional system variable.
+These
+variables can be used to distribute additional information such as
+the access policy.
+If the variable of the form
+.Sm
+off
+.Va
+name
+=
+Ar
+value
+.Sm
+on
+is followed by the
+.Cm
+default
+keyword, the
+variable will be listed as part of the default system variables
+.Po
+@code{ntpq(1ntpqmdoc)}
+.Ic
+rv
+command
+.Pc
+)
+.
+These additional variables serve
+informational purposes only.
+They are not related to the protocol
+other that they can be listed.
+The known protocol variables will
+always override any variables defined via the
+.Ic
+setvar
+mechanism.
+There are three special variables that contain the names
+of all variable of the same group.
+The
+.Va
+sys_var_list
+holds
+the names of all system variables.
+The
+.Va
+peer_var_list
+holds
+the names of all peer variables and the
+.Va
+clock_var_list
+holds the names of the reference clock variables.
+.It
+Xo
+Ic
+tinker
+.Oo
+.Cm
+allan
+Ar
+allan
+|
+.Cm
+dispersion
+Ar
+dispersion
+|
+.Cm
+freq
+Ar
+freq
+|
+.Cm
+huffpuff
+Ar
+huffpuff
+|
+.Cm
+panic
+Ar
+panic
+|
+.Cm
+step
+Ar
+srep
+|
+.Cm
+stepout
+Ar
+stepout
+.Oc
+.Xc
+This command can be used to alter several system variables in
+very exceptional circumstances.
+It should occur in the
+configuration file before any other configuration options.
+The
+default values of these variables have been carefully optimized for
+a wide range of network speeds and reliability expectations.
+In
+general, they interact in intricate ways that are hard to predict
+and some combinations can result in some very nasty behavior.
+Very
+rarely is it necessary to change the default values; but, some
+folks cannot resist twisting the knobs anyway and this command is
+for them.
+Emphasis added: twisters are on their own and can expect
+no help from the support group.
+
+The variables operate as follows:
+@table @samp
+@item Cm
+The argument becomes the new value for the minimum Allan
+intercept, which is a parameter of the PLL/FLL clock discipline
+algorithm.
+The value in log2 seconds defaults to 7 (1024 s), which is also the lower
+limit.
+@item Cm
+The argument becomes the new value for the dispersion increase rate,
+normally .000015 s/s.
+@item Cm
+The argument becomes the initial value of the frequency offset in
+parts-per-million.
+This overrides the value in the frequency file, if
+present, and avoids the initial training state if it is not.
+@item Cm
+The argument becomes the new value for the experimental
+huff-n'-puff filter span, which determines the most recent interval
+the algorithm will search for a minimum delay.
+The lower limit is
+900 s (15 m), but a more reasonable value is 7200 (2 hours).
+There
+is no default, since the filter is not enabled unless this command
+is given.
+@item Cm
+The argument is the panic threshold, normally 1000 s.
+If set to zero,
+the panic sanity check is disabled and a clock offset of any value will
+be accepted.
+@item Cm
+The argument is the step threshold, which by default is 0.128 s.
+It can
+be set to any positive number in seconds.
+If set to zero, step
+adjustments will never occur.
+Note: The kernel time discipline is
+disabled if the step threshold is set to zero or greater than the
+default.
+@item Cm
+The argument is the stepout timeout, which by default is 900 s.
+It can
+be set to any positive number in seconds.
+If set to zero, the stepout
+pulses will not be suppressed.
+
+@end multitable
+.It
+Xo
+Ic
+trap
+Ar
+host_address
+.Op
+Cm
+port
+Ar
+port_number
+.Op
+Cm
+interface
+Ar
+interface_address
+.Xc
+This command configures a trap receiver at the given host
+address and port number for sending messages with the specified
+local interface address.
+If the port number is unspecified, a value
+of 18447 is used.
+If the interface address is not specified, the
+message is sent with a source address of the local interface the
+message is sent through.
+Note that on a multihomed host the
+interface used may vary from time to time with routing changes.
+
+The trap receiver will generally log event messages and other
+information from the server in a log file.
+While such monitor
+programs may also request their own trap dynamically, configuring a
+trap receiver will ensure that no messages are lost when the server
+is started.
+.It
+Cm
+hop
+Ar
+...
+This command specifies a list of TTL values in increasing order, up to 8
+values can be specified.
+In manycast mode these values are used in turn in
+an expanding-ring search.
+The default is eight multiples of 32 starting at
+31.
+
+@end multitable
+
+This section was generated by @strong{AutoGen},
+using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program.
+This software is released under the NTP license, <http://ntp.org/license>.
+
+@menu
+* ntp.conf usage:: ntp.conf help/usage (@option{--help})
+* ntp.conf config:: presetting/configuring ntp.conf
+* ntp.conf exit status:: exit status
+* ntp.conf Files:: Files
+* ntp.conf See Also:: See Also
+* ntp.conf Bugs:: Bugs
+* ntp.conf Notes:: Notes
+@end menu
+
+@node ntp.conf usage
+@subsection ntp.conf help/usage (@option{--help})
+@cindex ntp.conf help
+
+This is the automatically generated usage text for ntp.conf.
+
+The text printed is the same whether selected with the @code{help} option
+(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
+the usage text by passing it through a pager program.
+@code{more-help} is disabled on platforms without a working
+@code{fork(2)} function. The @code{PAGER} environment variable is
+used to select the program, defaulting to @file{more}. Both will exit
+with a status code of 0.
+
+@exampleindent 0
+@example
+ntp.conf is unavailable - no --help
+@end example
+@exampleindent 4
+
+
+
+@node ntp.conf config
+@subsection presetting/configuring ntp.conf
+
+Any option that is not marked as @i{not presettable} may be preset by
+loading values from environment variables named @code{NTP.CONF} and @code{NTP.CONF_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
+the options listed above in upper case and segmented with underscores.
+The @code{NTP.CONF} variable will be tokenized and parsed like
+the command line. The remaining variables are tested for existence and their
+values are treated like option arguments.
+
+
+The command line options relating to configuration and/or usage help are:
+
+@subsubheading version
+
+Print the program version to standard out, optionally with licensing
+information, then exit 0. The optional argument specifies how much licensing
+detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the
+first letter of the argument is examined:
+
+@table @samp
+@item version
+Only print the version. This is the default.
+@item copyright
+Name the copyright usage licensing terms.
+@item verbose
+Print the full copyright usage licensing terms.
+@end table
+
+@node ntp.conf exit status
+@subsection ntp.conf exit status
+
+One of the following exit values will be returned:
+@table @samp
+@item 0 (EXIT_SUCCESS)
+Successful program execution.
+@item 1 (EXIT_FAILURE)
+The operation failed or the command syntax was not valid.
+@end table
+@node ntp.conf Files
+@subsection ntp.conf Files
+@table @samp
+@item Pa
+the default name of the configuration file
+@item Pa
+private MD5 keys
+@item Pa
+RSA private key
+@item Pa
+RSA public key
+@item Pa
+Diffie-Hellman agreement parameters
+
+@end multitable
+@node ntp.conf See Also
+@subsection ntp.conf See Also
+.Sh
+SEE
+ALSO
+@code{ntpd(1ntpdmdoc)},
+@code{ntpdc(1ntpdcmdoc)},
+@code{ntpq(1ntpqmdoc)}
+
+In addition to the manual pages provided,
+comprehensive documentation is available on the world wide web
+at
+.Li
+http://www.ntp.org/
+.
+A snapshot of this documentation is available in HTML format in
+.Pa
+/usr/share/doc/ntp
+.
+.Rs
+.%A
+David
+L.
+Mills
+.%T
+Network
+Time
+Protocol
+(Version
+4)
+.%O
+RFC5905
+.Re
+@node ntp.conf Bugs
+@subsection ntp.conf Bugs
+The syntax checking is not picky; some combinations of
+ridiculous and even hilarious options and modes may not be
+detected.
+
+The
+.Pa
+ntpkey_
+Ns
+Ar
+host
+files are really digital
+certificates.
+These should be obtained via secure directory
+services when they become universally available.
+@node ntp.conf Notes
+@subsection ntp.conf Notes
+This document is derived from FreeBSD.
--- /dev/null
+* ntp.keys Invocation:: Invoking ntp.keys
--- /dev/null
+@node ntp.keys Invocation
+@section Invoking ntp.keys
+@pindex ntp.keys
+@cindex NTP symmetric key file format
+@ignore
+#
+# EDIT THIS FILE WITH CAUTION (invoke-ntp.keys.texi)
+#
+# It has been AutoGen-ed December 3, 2012 at 12:41:43 AM by AutoGen 5.16.2
+# From the definitions ntp.keys.def
+# and the template file agtexi-cmd.tpl
+@end ignore
+
+
+
+This document describes the format of an NTP symmetric key file.
+For a description of the use of this type of file, see the
+.Qq
+Authentication
+Support
+section of the
+@code{ntp.conf(5)}
+page.
+
+@code{ntpd(8)}
+reads its keys from a file specified using the
+@code{-k} command line option or the
+.Ic
+keys
+statement in the configuration file.
+While key number 0 is fixed by the NTP standard
+(as 56 zero bits)
+and may not be changed,
+one or more keys numbered between 1 and 65534
+may be arbitrarily set in the keys file.
+
+The key file uses the same comment conventions
+as the configuration file.
+Key entries use a fixed format of the form
+
+.D1
+Ar
+keyno
+type
+key
+
+where
+.Ar
+keyno
+is a positive integer (between 1 and 65534),
+.Ar
+type
+is the message digest algorithm,
+and
+.Ar
+key
+is the key itself.
+
+The
+.Ar
+key
+may be given in a format
+controlled by the
+.Ar
+type
+field.
+The
+.Ar
+type
+.Li
+MD5
+is always supported.
+If
+.Li
+ntpd
+was built with the OpenSSL library
+then any digest library supported by that library may be specified.
+However, if compliance with FIPS 140-2 is required the
+.Ar
+type
+must be either
+.Li
+SHA
+or
+.Li
+SHA1
+.
+
+What follows are some key types, and corresponding formats:
+
+@table @samp
+@item Li
+The key is 1 to 16 printable characters terminated by
+an EOL,
+whitespace,
+or
+a
+.Li
+#
+(which is the "start of comment" character).
+
+@item Li
+@item Li
+@item Li
+The key is a hex-encoded ASCII string of 40 characters,
+which is truncated as necessary.
+
+@end multitable
+
+Note that the keys used by the
+@code{ntpq(8)}
+and
+@code{ntpdc(8)}
+programs are checked against passwords
+requested by the programs and entered by hand,
+so it is generally appropriate to specify these keys in ASCII format.
+
+This section was generated by @strong{AutoGen},
+using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.keys} program.
+This software is released under the NTP license, <http://ntp.org/license>.
+
+@menu
+* ntp.keys usage:: ntp.keys help/usage (@option{--help})
+* ntp.keys config:: presetting/configuring ntp.keys
+* ntp.keys exit status:: exit status
+* ntp.keys Files:: Files
+* ntp.keys See Also:: See Also
+* ntp.keys Notes:: Notes
+@end menu
+
+@node ntp.keys usage
+@subsection ntp.keys help/usage (@option{--help})
+@cindex ntp.keys help
+
+This is the automatically generated usage text for ntp.keys.
+
+The text printed is the same whether selected with the @code{help} option
+(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
+the usage text by passing it through a pager program.
+@code{more-help} is disabled on platforms without a working
+@code{fork(2)} function. The @code{PAGER} environment variable is
+used to select the program, defaulting to @file{more}. Both will exit
+with a status code of 0.
+
+@exampleindent 0
+@example
+ntp.keys is unavailable - no --help
+@end example
+@exampleindent 4
+
+
+
+@node ntp.keys config
+@subsection presetting/configuring ntp.keys
+
+Any option that is not marked as @i{not presettable} may be preset by
+loading values from environment variables named @code{NTP.KEYS} and @code{NTP.KEYS_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
+the options listed above in upper case and segmented with underscores.
+The @code{NTP.KEYS} variable will be tokenized and parsed like
+the command line. The remaining variables are tested for existence and their
+values are treated like option arguments.
+
+
+The command line options relating to configuration and/or usage help are:
+
+@subsubheading version
+
+Print the program version to standard out, optionally with licensing
+information, then exit 0. The optional argument specifies how much licensing
+detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the
+first letter of the argument is examined:
+
+@table @samp
+@item version
+Only print the version. This is the default.
+@item copyright
+Name the copyright usage licensing terms.
+@item verbose
+Print the full copyright usage licensing terms.
+@end table
+
+@node ntp.keys exit status
+@subsection ntp.keys exit status
+
+One of the following exit values will be returned:
+@table @samp
+@item 0 (EXIT_SUCCESS)
+Successful program execution.
+@item 1 (EXIT_FAILURE)
+The operation failed or the command syntax was not valid.
+@end table
+@node ntp.keys Files
+@subsection ntp.keys Files
+@table @samp
+@item Pa
+the default name of the configuration file
+
+@end multitable
+@node ntp.keys See Also
+@subsection ntp.keys See Also
+@code{ntp.conf(5)},
+@code{ntpd(1ntpdmdoc)},
+@code{ntpdate(1ntpdatemdoc)},
+@code{ntpdc(1ntpdcmdoc)},
+@code{sntp(1sntpmdoc)}
+@node ntp.keys Notes
+@subsection ntp.keys Notes
+This document is derived from FreeBSD.
--- /dev/null
+<html lang="en">
+<head>
+<title>NTP Configuration File User's Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="NTP Configuration File User's Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="top" href="#Top">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+ pre.display { font-family:inherit }
+ pre.format { font-family:inherit }
+ pre.smalldisplay { font-family:inherit; font-size:smaller }
+ pre.smallformat { font-family:inherit; font-size:smaller }
+ pre.smallexample { font-size:smaller }
+ pre.smalllisp { font-size:smaller }
+ span.sc { font-variant:small-caps }
+ span.roman { font-family:serif; font-weight:normal; }
+ span.sansserif { font-family:sans-serif; font-weight:normal; }
+--></style>
+</head>
+<body>
+<h1 class="settitle">NTP Configuration File User's Manual</h1>
+<div class="node">
+<a name="Top"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-Description">ntp.conf Description</a>,
+Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>,
+Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
+
+</div>
+
+<h2 class="unnumbered">NTP's Configuration File User Manual</h2>
+
+<p>This document describes the configuration file for the NTP Project's
+<code>ntpd</code> program.
+
+ <p>This document applies to version {No value for `VERSION'} of <code>ntp.conf</code>.
+
+ <div class="shortcontents">
+<h2>Short Contents</h2>
+<ul>
+<a href="#Top">NTP's Configuration File User Manual</a>
+</ul>
+</div>
+
+<ul class="menu">
+<li><a accesskey="1" href="#ntp_002econf-Description">ntp.conf Description</a>: Description
+<li><a accesskey="2" href="#sntp-Invocation">sntp Invocation</a>: Invoking sntp
+</ul>
+
+<div class="node">
+<a name="ntp.conf-Description"></a>
+<a name="ntp_002econf-Description"></a>
+<p><hr>
+
+
+</div>
+
+<!-- node-name, next, previous, up -->
+<h3 class="section">Description</h3>
+
+<p>The behavior of <code>ntpd</code> can be changed by a configuration file,
+by default <code>ntp.conf</code>.
+
+<div class="node">
+<a name="ntp.conf-Invocation"></a>
+<a name="ntp_002econf-Invocation"></a>
+<p><hr>
+
+
+</div>
+
+<h3 class="section">Invoking ntp.conf</h3>
+
+<p><a name="index-ntp_002econf-1"></a><a name="index-Network-Time-Protocol-_0028NTP_0029-daemon-configuration-file-format-2"></a>
+
+ <p>The
+<code>ntp.conf</code>
+configuration file is read at initial startup by the
+<code>ntpd(1ntpdmdoc)</code>
+daemon in order to specify the synchronization sources,
+modes and other related information.
+Usually, it is installed in the
+.Pa
+/etc
+directory,
+but could be installed elsewhere
+(see the daemon's
+<code>-c</code> command line option).
+
+ <p>The file format is similar to other
+.Ux
+configuration files.
+Comments begin with a
+.Ql
+#
+character and extend to the end of the line;
+blank lines are ignored.
+Configuration commands consist of an initial keyword
+followed by a list of arguments,
+some of which may be optional, separated by whitespace.
+Commands may not be continued over multiple lines.
+Arguments may be host names,
+host addresses written in numeric, dotted-quad form,
+integers, floating point numbers (when specifying times in seconds)
+and text strings.
+
+ <p>The rest of this page describes the configuration and control options.
+The
+.Qq
+Notes
+on
+Configuring
+NTP
+and
+Setting
+up
+a
+NTP
+Subnet
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+contains an extended discussion of these options.
+In addition to the discussion of general
+.Sx
+Configuration
+Options
+,
+there are sections describing the following supported functionality
+and the options used to control it:
+ <ul>
+<li>.Sx
+Authentication
+Support
+<li>.Sx
+Monitoring
+Support
+<li>.Sx
+Access
+Control
+Support
+<li>.Sx
+Automatic
+NTP
+Configuration
+Options
+<li>.Sx
+Reference
+Clock
+Support
+<li>.Sx
+Miscellaneous
+Options
+</ul>
+
+ <p>Following these is a section describing
+.Sx
+Miscellaneous
+Options
+.
+While there is a rich set of options available,
+the only required option is one or more
+.Ic
+server
+,
+.Ic
+peer
+,
+.Ic
+broadcast
+or
+.Ic
+manycastclient
+commands.
+.Sh
+Configuration
+Support
+Following is a description of the configuration commands in
+NTPv4.
+These commands have the same basic functions as in NTPv3 and
+in some cases new functions and new arguments.
+There are two
+classes of commands, configuration commands that configure a
+persistent association with a remote server or peer or reference
+clock, and auxiliary commands that specify environmental variables
+that control various related operations.
+.Ss
+Configuration
+Commands
+The various modes are determined by the command keyword and the
+type of the required IP address.
+Addresses are classed by type as
+(s) a remote server or peer (IPv4 class A, B and C), (b) the
+broadcast address of a local interface, (m) a multicast address (IPv4
+class D), or (r) a reference clock address (127.127.x.x).
+Note that
+only those options applicable to each command are listed below.
+Use
+of options not listed may not be caught as an error, but may result
+in some weird and even destructive behavior.
+
+ <p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
+is detected, support for the IPv6 address family is generated
+in addition to the default support of the IPv4 address family.
+In a few cases, including the reslist billboard generated
+by ntpdc, IPv6 addresses are automatically generated.
+IPv6 addresses can be identified by the presence of colons
+.Dq
+\&:
+in the address field.
+IPv6 addresses can be used almost everywhere where
+IPv4 addresses can be used,
+with the exception of reference clock addresses,
+which are always IPv4.
+
+ <p>Note that in contexts where a host name is expected, a
+<code>-4</code> qualifier preceding
+the host name forces DNS resolution to the IPv4 namespace,
+while a
+<code>-6</code> qualifier forces DNS resolution to the IPv6 namespace.
+See IPv6 references for the
+equivalent classes for that address family.
+ <dl>
+<dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+burst
+.Op
+Cm
+iburst
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Xc
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Xc
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+ttl
+Ar
+ttl
+.Xc
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+key
+Ar
+key
+\&|
+Cm
+autokey
+.Op
+Cm
+version
+Ar
+version
+.Op
+Cm
+prefer
+.Op
+Cm
+minpoll
+Ar
+minpoll
+.Op
+Cm
+maxpoll
+Ar
+maxpoll
+.Op
+Cm
+ttl
+Ar
+ttl
+.Xc
+
+ <p>These four commands specify the time server name or address to
+be used and the mode in which to operate.
+The
+.Ar
+address
+can be
+either a DNS name or an IP address in dotted-quad notation.
+Additional information on association behavior can be found in the
+.Qq
+Association
+Management
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+ <dl>
+<dt>‘<samp><span class="samp">Ic</span></samp>’<dd>For type s and r addresses, this command mobilizes a persistent
+client mode association with the specified remote server or local
+radio clock.
+In this mode the local clock can synchronized to the
+remote server, but the remote server can never be synchronized to
+the local clock.
+This command should
+.Em
+not
+be used for type
+b or m addresses.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>For type s addresses (only), this command mobilizes a
+persistent symmetric-active mode association with the specified
+remote peer.
+In this mode the local clock can be synchronized to
+the remote peer or the remote peer can be synchronized to the local
+clock.
+This is useful in a network of servers where, depending on
+various failure scenarios, either the local or remote peer may be
+the better source of time.
+This command should NOT be used for type
+b, m or r addresses.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>For type b and m addresses (only), this
+command mobilizes a persistent broadcast mode association.
+Multiple
+commands can be used to specify multiple local broadcast interfaces
+(subnets) and/or multiple multicast groups.
+Note that local
+broadcast messages go only to the interface associated with the
+subnet specified, but multicast messages go to all interfaces.
+In broadcast mode the local server sends periodic broadcast
+messages to a client population at the
+.Ar
+address
+specified, which is usually the broadcast address on (one of) the
+local network(s) or a multicast address assigned to NTP.
+The IANA
+has assigned the multicast group address IPv4 224.0.1.1 and
+IPv6 ff05::101 (site local) exclusively to
+NTP, but other nonconflicting addresses can be used to contain the
+messages within administrative boundaries.
+Ordinarily, this
+specification applies only to the local server operating as a
+sender; for operation as a broadcast client, see the
+.Ic
+broadcastclient
+or
+.Ic
+multicastclient
+commands
+below.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>For type m addresses (only), this command mobilizes a
+manycast client mode association for the multicast address
+specified.
+In this case a specific address must be supplied which
+matches the address used on the
+.Ic
+manycastserver
+command for
+the designated manycast servers.
+The NTP multicast address
+224.0.1.1 assigned by the IANA should NOT be used, unless specific
+means are taken to avoid spraying large areas of the Internet with
+these messages and causing a possibly massive implosion of replies
+at the sender.
+The
+.Ic
+manycastserver
+command specifies that the local server
+is to operate in client mode with the remote servers that are
+discovered as the result of broadcast/multicast messages.
+The
+client broadcasts a request message to the group address associated
+with the specified
+.Ar
+address
+and specifically enabled
+servers respond to these messages.
+The client selects the servers
+providing the best time and continues as with the
+.Ic
+server
+command.
+The remaining servers are discarded as if never
+heard.
+
+ <p>Options:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>All packets sent to and received from the server or peer are to
+include authentication fields encrypted using the autokey scheme
+described in
+.Sx
+Authentication
+Options
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>when the server is reachable, send a burst of eight packets
+instead of the usual one.
+The packet spacing is normally 2 s;
+however, the spacing between the first and second packets
+can be changed with the calldelay command to allow
+additional time for a modem or ISDN call to complete.
+This is designed to improve timekeeping quality
+with the
+.Ic
+server
+command and s addresses.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>When the server is unreachable, send a burst of eight packets
+instead of the usual one.
+The packet spacing is normally 2 s;
+however, the spacing between the first two packets can be
+changed with the calldelay command to allow
+additional time for a modem or ISDN call to complete.
+This is designed to speed the initial synchronization
+acquisition with the
+.Ic
+server
+command and s addresses and when
+<code>ntpd(1ntpdmdoc)</code>
+is started with the
+<code>-q</code> option.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>All packets sent to and received from the server or peer are to
+include authentication fields encrypted using the specified
+.Ar
+key
+identifier with values from 1 to 65534, inclusive.
+The
+default is to include no encryption field.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>These options specify the minimum and maximum poll intervals
+for NTP messages, as a power of 2 in seconds
+The maximum poll
+interval defaults to 10 (1,024 s), but can be increased by the
+.Cm
+maxpoll
+option to an upper limit of 17 (36.4 h).
+The
+minimum poll interval defaults to 6 (64 s), but can be decreased by
+the
+.Cm
+minpoll
+option to a lower limit of 4 (16 s).
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Marks the server as unused, except for display purposes.
+The server is discarded by the selection algroithm.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Marks the server as preferred.
+All other things being equal,
+this host will be chosen for synchronization among a set of
+correctly operating hosts.
+See the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+for further information.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This option is used only with broadcast server and manycast
+client modes.
+It specifies the time-to-live
+.Ar
+ttl
+to
+use on broadcast server and multicast server and the maximum
+.Ar
+ttl
+for the expanding ring search with manycast
+client packets.
+Selection of the proper value, which defaults to
+127, is something of a black art and should be coordinated with the
+network administrator.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the version number to be used for outgoing NTP
+packets.
+Versions 1-4 are the choices, with version 4 the
+default.
+
+ <p>.Ss
+Auxiliary
+Commands
+ <dl>
+<dt>‘<samp><span class="samp">Ic</span></samp>’<dd>This command enables reception of broadcast server messages to
+any local interface (type b) address.
+Upon receiving a message for
+the first time, the broadcast client measures the nominal server
+propagation delay using a brief client/server exchange with the
+server, then enters the broadcast client mode, in which it
+synchronizes to succeeding broadcast messages.
+Note that, in order
+to avoid accidental or malicious disruption in this mode, both the
+server and client should operate using symmetric-key or public-key
+authentication as described in
+.Sx
+Authentication
+Options
+.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>This command enables reception of manycast client messages to
+the multicast group address(es) (type m) specified.
+At least one
+address is required, but the NTP multicast address 224.0.1.1
+assigned by the IANA should NOT be used, unless specific means are
+taken to limit the span of the reply and avoid a possibly massive
+implosion at the original sender.
+Note that, in order to avoid
+accidental or malicious disruption in this mode, both the server
+and client should operate using symmetric-key or public-key
+authentication as described in
+.Sx
+Authentication
+Options
+.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>This command enables reception of multicast server messages to
+the multicast group address(es) (type m) specified.
+Upon receiving
+a message for the first time, the multicast client measures the
+nominal server propagation delay using a brief client/server
+exchange with the server, then enters the broadcast client mode, in
+which it synchronizes to succeeding multicast messages.
+Note that,
+in order to avoid accidental or malicious disruption in this mode,
+both the server and client should operate using symmetric-key or
+public-key authentication as described in
+.Sx
+Authentication
+Options
+.
+
+ <p>.Sh
+Authentication
+Support
+Authentication support allows the NTP client to verify that the
+server is in fact known and trusted and not an intruder intending
+accidentally or on purpose to masquerade as that server.
+The NTPv3
+specification RFC-1305 defines a scheme which provides
+cryptographic authentication of received NTP packets.
+Originally,
+this was done using the Data Encryption Standard (DES) algorithm
+operating in Cipher Block Chaining (CBC) mode, commonly called
+DES-CBC.
+Subsequently, this was replaced by the RSA Message Digest
+5 (MD5) algorithm using a private key, commonly called keyed-MD5.
+Either algorithm computes a message digest, or one-way hash, which
+can be used to verify the server has the correct private key and
+key identifier.
+
+ <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key
+cryptography and, in addition, provides a new Autokey scheme
+based on public key cryptography.
+Public key cryptography is generally considered more secure
+than symmetric key cryptography, since the security is based
+on a private value which is generated by each server and
+never revealed.
+With Autokey all key distribution and
+management functions involve only public values, which
+considerably simplifies key distribution and storage.
+Public key management is based on X.509 certificates,
+which can be provided by commercial services or
+produced by utility programs in the OpenSSL software library
+or the NTPv4 distribution.
+
+ <p>While the algorithms for symmetric key cryptography are
+included in the NTPv4 distribution, public key cryptography
+requires the OpenSSL software library to be installed
+before building the NTP distribution.
+Directions for doing that
+are on the Building and Installing the Distribution page.
+
+ <p>Authentication is configured separately for each association
+using the
+.Cm
+key
+or
+.Cm
+autokey
+subcommand on the
+.Ic
+peer
+,
+.Ic
+server
+,
+.Ic
+broadcast
+and
+.Ic
+manycastclient
+configuration commands as described in
+.Sx
+Configuration
+Options
+page.
+The authentication
+options described below specify the locations of the key files,
+if other than default, which symmetric keys are trusted
+and the interval between various operations, if other than default.
+
+ <p>Authentication is always enabled,
+although ineffective if not configured as
+described below.
+If a NTP packet arrives
+including a message authentication
+code (MAC), it is accepted only if it
+passes all cryptographic checks.
+The
+checks require correct key ID, key value
+and message digest.
+If the packet has
+been modified in any way or replayed
+by an intruder, it will fail one or more
+of these checks and be discarded.
+Furthermore, the Autokey scheme requires a
+preliminary protocol exchange to obtain
+the server certificate, verify its
+credentials and initialize the protocol
+
+ <p>The
+.Cm
+auth
+flag controls whether new associations or
+remote configuration commands require cryptographic authentication.
+This flag can be set or reset by the
+.Ic
+enable
+and
+.Ic
+disable
+commands and also by remote
+configuration commands sent by a
+<code>ntpdc(1ntpdcmdoc)</code>
+program running in
+another machine.
+If this flag is enabled, which is the default
+case, new broadcast client and symmetric passive associations and
+remote configuration commands must be cryptographically
+authenticated using either symmetric key or public key cryptography.
+If this
+flag is disabled, these operations are effective
+even if not cryptographic
+authenticated.
+It should be understood
+that operating with the
+.Ic
+auth
+flag disabled invites a significant vulnerability
+where a rogue hacker can
+masquerade as a falseticker and seriously
+disrupt system timekeeping.
+It is
+important to note that this flag has no purpose
+other than to allow or disallow
+a new association in response to new broadcast
+and symmetric active messages
+and remote configuration commands and, in particular,
+the flag has no effect on
+the authentication process itself.
+
+ <p>An attractive alternative where multicast support is available
+is manycast mode, in which clients periodically troll
+for servers as described in the
+.Sx
+Automatic
+NTP
+Configuration
+Options
+page.
+Either symmetric key or public key
+cryptographic authentication can be used in this mode.
+The principle advantage
+of manycast mode is that potential servers need not be
+configured in advance,
+since the client finds them during regular operation,
+and the configuration
+files for all clients can be identical.
+
+ <p>The security model and protocol schemes for
+both symmetric key and public key
+cryptography are summarized below;
+further details are in the briefings, papers
+and reports at the NTP project page linked from
+.Li
+http://www.ntp.org/
+.
+.Ss
+Symmetric-Key
+Cryptography
+The original RFC-1305 specification allows any one of possibly
+65,534 keys, each distinguished by a 32-bit key identifier, to
+authenticate an association.
+The servers and clients involved must
+agree on the key and key identifier to
+authenticate NTP packets.
+Keys and
+related information are specified in a key
+file, usually called
+.Pa
+ntp.keys
+,
+which must be distributed and stored using
+secure means beyond the scope of the NTP protocol itself.
+Besides the keys used
+for ordinary NTP associations,
+additional keys can be used as passwords for the
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+utility programs.
+
+ <p>When
+<code>ntpd(1ntpdmdoc)</code>
+is first started, it reads the key file specified in the
+.Ic
+keys
+configuration command and installs the keys
+in the key cache.
+However,
+individual keys must be activated with the
+.Ic
+trusted
+command before use.
+This
+allows, for instance, the installation of possibly
+several batches of keys and
+then activating or deactivating each batch
+remotely using
+<code>ntpdc(1ntpdcmdoc)</code>.
+This also provides a revocation capability that can be used
+if a key becomes compromised.
+The
+.Ic
+requestkey
+command selects the key used as the password for the
+<code>ntpdc(1ntpdcmdoc)</code>
+utility, while the
+.Ic
+controlkey
+command selects the key used as the password for the
+<code>ntpq(1ntpqmdoc)</code>
+utility.
+.Ss
+Public
+Key
+Cryptography
+NTPv4 supports the original NTPv3 symmetric key scheme
+described in RFC-1305 and in addition the Autokey protocol,
+which is based on public key cryptography.
+The Autokey Version 2 protocol described on the Autokey Protocol
+page verifies packet integrity using MD5 message digests
+and verifies the source with digital signatures and any of several
+digest/signature schemes.
+Optional identity schemes described on the Identity Schemes
+page and based on cryptographic challenge/response algorithms
+are also available.
+Using all of these schemes provides strong security against
+replay with or without modification, spoofing, masquerade
+and most forms of clogging attacks.
+
+ <p>The Autokey protocol has several modes of operation
+corresponding to the various NTP modes supported.
+Most modes use a special cookie which can be
+computed independently by the client and server,
+but encrypted in transmission.
+All modes use in addition a variant of the S-KEY scheme,
+in which a pseudo-random key list is generated and used
+in reverse order.
+These schemes are described along with an executive summary,
+current status, briefing slides and reading list on the
+.Sx
+Autonomous
+Authentication
+page.
+
+ <p>The specific cryptographic environment used by Autokey servers
+and clients is determined by a set of files
+and soft links generated by the
+<code>ntp-keygen(1ntpkeygenmdoc)</code>
+program.
+This includes a required host key file,
+required certificate file and optional sign key file,
+leapsecond file and identity scheme files.
+The
+digest/signature scheme is specified in the X.509 certificate
+along with the matching sign key.
+There are several schemes
+available in the OpenSSL software library, each identified
+by a specific string such as
+.Cm
+md5WithRSAEncryption
+,
+which stands for the MD5 message digest with RSA
+encryption scheme.
+The current NTP distribution supports
+all the schemes in the OpenSSL library, including
+those based on RSA and DSA digital signatures.
+
+ <p>NTP secure groups can be used to define cryptographic compartments
+and security hierarchies.
+It is important that every host
+in the group be able to construct a certificate trail to one
+or more trusted hosts in the same group.
+Each group
+host runs the Autokey protocol to obtain the certificates
+for all hosts along the trail to one or more trusted hosts.
+This requires the configuration file in all hosts to be
+engineered so that, even under anticipated failure conditions,
+the NTP subnet will form such that every group host can find
+a trail to at least one trusted host.
+.Ss
+Naming
+and
+Addressing
+It is important to note that Autokey does not use DNS to
+resolve addresses, since DNS can't be completely trusted
+until the name servers have synchronized clocks.
+The cryptographic name used by Autokey to bind the host identity
+credentials and cryptographic values must be independent
+of interface, network and any other naming convention.
+The name appears in the host certificate in either or both
+the subject and issuer fields, so protection against
+DNS compromise is essential.
+
+ <p>By convention, the name of an Autokey host is the name returned
+by the Unix
+<code>gethostname(2)</code>
+system call or equivalent in other systems.
+By the system design
+model, there are no provisions to allow alternate names or aliases.
+However, this is not to say that DNS aliases, different names
+for each interface, etc., are constrained in any way.
+
+ <p>It is also important to note that Autokey verifies authenticity
+using the host name, network address and public keys,
+all of which are bound together by the protocol specifically
+to deflect masquerade attacks.
+For this reason Autokey
+includes the source and destinatino IP addresses in message digest
+computations and so the same addresses must be available
+at both the server and client.
+For this reason operation
+with network address translation schemes is not possible.
+This reflects the intended robust security model where government
+and corporate NTP servers are operated outside firewall perimeters.
+.Ss
+Operation
+A specific combination of authentication scheme (none,
+symmetric key, public key) and identity scheme is called
+a cryptotype, although not all combinations are compatible.
+There may be management configurations where the clients,
+servers and peers may not all support the same cryptotypes.
+A secure NTPv4 subnet can be configured in many ways while
+keeping in mind the principles explained above and
+in this section.
+Note however that some cryptotype
+combinations may successfully interoperate with each other,
+but may not represent good security practice.
+
+ <p>The cryptotype of an association is determined at the time
+of mobilization, either at configuration time or some time
+later when a message of appropriate cryptotype arrives.
+When mobilized by a
+.Ic
+server
+or
+.Ic
+peer
+configuration command and no
+.Ic
+key
+or
+.Ic
+autokey
+subcommands are present, the association is not
+authenticated; if the
+.Ic
+key
+subcommand is present, the association is authenticated
+using the symmetric key ID specified; if the
+.Ic
+autokey
+subcommand is present, the association is authenticated
+using Autokey.
+
+ <p>When multiple identity schemes are supported in the Autokey
+protocol, the first message exchange determines which one is used.
+The client request message contains bits corresponding
+to which schemes it has available.
+The server response message
+contains bits corresponding to which schemes it has available.
+Both server and client match the received bits with their own
+and select a common scheme.
+
+ <p>Following the principle that time is a public value,
+a server responds to any client packet that matches
+its cryptotype capabilities.
+Thus, a server receiving
+an unauthenticated packet will respond with an unauthenticated
+packet, while the same server receiving a packet of a cryptotype
+it supports will respond with packets of that cryptotype.
+However, unconfigured broadcast or manycast client
+associations or symmetric passive associations will not be
+mobilized unless the server supports a cryptotype compatible
+with the first packet received.
+By default, unauthenticated associations will not be mobilized
+unless overridden in a decidedly dangerous way.
+
+ <p>Some examples may help to reduce confusion.
+Client Alice has no specific cryptotype selected.
+Server Bob has both a symmetric key file and minimal Autokey files.
+Alice's unauthenticated messages arrive at Bob, who replies with
+unauthenticated messages.
+Cathy has a copy of Bob's symmetric
+key file and has selected key ID 4 in messages to Bob.
+Bob verifies the message with his key ID 4.
+If it's the
+same key and the message is verified, Bob sends Cathy a reply
+authenticated with that key.
+If verification fails,
+Bob sends Cathy a thing called a crypto-NAK, which tells her
+something broke.
+She can see the evidence using the ntpq program.
+
+ <p>Denise has rolled her own host key and certificate.
+She also uses one of the identity schemes as Bob.
+She sends the first Autokey message to Bob and they
+both dance the protocol authentication and identity steps.
+If all comes out okay, Denise and Bob continue as described above.
+
+ <p>It should be clear from the above that Bob can support
+all the girls at the same time, as long as he has compatible
+authentication and identity credentials.
+Now, Bob can act just like the girls in his own choice of servers;
+he can run multiple configured associations with multiple different
+servers (or the same server, although that might not be useful).
+But, wise security policy might preclude some cryptotype
+combinations; for instance, running an identity scheme
+with one server and no authentication with another might not be wise.
+.Ss
+Key
+Management
+The cryptographic values used by the Autokey protocol are
+incorporated as a set of files generated by the
+<code>ntp-keygen(1ntpkeygenmdoc)</code>
+utility program, including symmetric key, host key and
+public certificate files, as well as sign key, identity parameters
+and leapseconds files.
+Alternatively, host and sign keys and
+certificate files can be generated by the OpenSSL utilities
+and certificates can be imported from public certificate
+authorities.
+Note that symmetric keys are necessary for the
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+utility programs.
+The remaining files are necessary only for the
+Autokey protocol.
+
+ <p>Certificates imported from OpenSSL or public certificate
+authorities have certian limitations.
+The certificate should be in ASN.1 syntax, X.509 Version 3
+format and encoded in PEM, which is the same format
+used by OpenSSL.
+The overall length of the certificate encoded
+in ASN.1 must not exceed 1024 bytes.
+The subject distinguished
+name field (CN) is the fully qualified name of the host
+on which it is used; the remaining subject fields are ignored.
+The certificate extension fields must not contain either
+a subject key identifier or a issuer key identifier field;
+however, an extended key usage field for a trusted host must
+contain the value
+.Cm
+trustRoot
+;
+.
+Other extension fields are ignored.
+.Ss
+Authentication
+Commands
+ <dl>
+<dt>‘<samp><span class="samp">Ic</span></samp>’<dd>Specifies the interval between regenerations of the session key
+list used with the Autokey protocol.
+Note that the size of the key
+list for each association depends on this interval and the current
+poll interval.
+The default value is 12 (4096 s or about 1.1 hours).
+For poll intervals above the specified interval, a session key list
+with a single entry will be regenerated for every message
+sent.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>Specifies the key identifier to use with the
+<code>ntpq(1ntpqmdoc)</code>
+utility, which uses the standard
+protocol defined in RFC-1305.
+The
+.Ar
+key
+argument is
+the key identifier for a trusted key, where the value can be in the
+range 1 to 65,534, inclusive.
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+cert
+Ar
+file
+.Op
+Cm
+leap
+Ar
+file
+.Op
+Cm
+randfile
+Ar
+file
+.Op
+Cm
+host
+Ar
+file
+.Op
+Cm
+sign
+Ar
+file
+.Op
+Cm
+gq
+Ar
+file
+.Op
+Cm
+gqpar
+Ar
+file
+.Op
+Cm
+iffpar
+Ar
+file
+.Op
+Cm
+mvpar
+Ar
+file
+.Op
+Cm
+pw
+Ar
+password
+.Xc
+This command requires the OpenSSL library.
+It activates public key
+cryptography, selects the message digest and signature
+encryption scheme and loads the required private and public
+values described above.
+If one or more files are left unspecified,
+the default names are used as described above.
+Unless the complete path and name of the file are specified, the
+location of a file is relative to the keys directory specified
+in the
+.Ic
+keysdir
+command or default
+.Pa
+/usr/local/etc
+.
+Following are the subcommands:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the required host public certificate file.
+This overrides the link
+.Pa
+ntpkey_cert_
+Ns
+Ar
+hostname
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the optional GQ parameters file.
+This
+overrides the link
+.Pa
+ntpkey_gq_
+Ns
+Ar
+hostname
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the required host key file.
+This overrides
+the link
+.Pa
+ntpkey_key_
+Ns
+Ar
+hostname
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the optional IFF parameters file.This
+overrides the link
+.Pa
+ntpkey_iff_
+Ns
+Ar
+hostname
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the optional leapsecond file.
+This overrides the link
+.Pa
+ntpkey_leap
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the optional MV parameters file.
+This
+overrides the link
+.Pa
+ntpkey_mv_
+Ns
+Ar
+hostname
+in the keys directory.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the password to decrypt files containing private keys and
+identity parameters.
+This is required only if these files have been
+encrypted.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the random seed file used by the OpenSSL
+library.
+The defaults are described in the main text above.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the location of the optional sign key file.
+This overrides
+the link
+.Pa
+ntpkey_sign_
+Ns
+Ar
+hostname
+in the keys directory.
+If this file is
+not found, the host key is also the sign key.
+
+ <p>.It
+Ic
+keys
+Ar
+keyfile
+Specifies the complete path and location of the MD5 key file
+containing the keys and key identifiers used by
+<code>ntpd(1ntpdmdoc)</code>,
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+when operating with symmetric key cryptography.
+This is the same operation as the
+<code>-k</code> command line option.
+.It
+Ic
+keysdir
+Ar
+path
+This command specifies the default directory path for
+cryptographic keys, parameters and certificates.
+The default is
+.Pa
+/usr/local/etc/
+.
+.It
+Ic
+requestkey
+Ar
+key
+Specifies the key identifier to use with the
+<code>ntpdc(1ntpdcmdoc)</code>
+utility program, which uses a
+proprietary protocol specific to this implementation of
+<code>ntpd(1ntpdmdoc)</code>.
+The
+.Ar
+key
+argument is a key identifier
+for the trusted key, where the value can be in the range 1 to
+65,534, inclusive.
+.It
+Ic
+revoke
+Ar
+logsec
+Specifies the interval between re-randomization of certain
+cryptographic values used by the Autokey scheme, as a power of 2 in
+seconds.
+These values need to be updated frequently in order to
+deflect brute-force attacks on the algorithms of the scheme;
+however, updating some values is a relatively expensive operation.
+The default interval is 16 (65,536 s or about 18 hours).
+For poll
+intervals above the specified interval, the values will be updated
+for every message sent.
+.It
+Ic
+trustedkey
+Ar
+key
+...
+Specifies the key identifiers which are trusted for the
+purposes of authenticating peers with symmetric key cryptography,
+as well as keys used by the
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+programs.
+The authentication procedures require that both the local
+and remote servers share the same key and key identifier for this
+purpose, although different keys can be used with different
+servers.
+The
+.Ar
+key
+arguments are 32-bit unsigned
+integers with values from 1 to 65,534.
+
+ <p>.Ss
+Error
+Codes
+The following error codes are reported via the NTP control
+and monitoring protocol trap mechanism.
+ <dl>
+<dt>‘<samp><span class="samp">101</span></samp>’<dd>.Pq
+bad
+field
+format
+or
+length
+The packet has invalid version, length or format.
+<br><dt>‘<samp><span class="samp">102</span></samp>’<dd>.Pq
+bad
+timestamp
+The packet timestamp is the same or older than the most recent received.
+This could be due to a replay or a server clock time step.
+<br><dt>‘<samp><span class="samp">103</span></samp>’<dd>.Pq
+bad
+filestamp
+The packet filestamp is the same or older than the most recent received.
+This could be due to a replay or a key file generation error.
+<br><dt>‘<samp><span class="samp">104</span></samp>’<dd>.Pq
+bad
+or
+missing
+public
+key
+The public key is missing, has incorrect format or is an unsupported type.
+<br><dt>‘<samp><span class="samp">105</span></samp>’<dd>.Pq
+unsupported
+digest
+type
+The server requires an unsupported digest/signature scheme.
+<br><dt>‘<samp><span class="samp">106</span></samp>’<dd>.Pq
+mismatched
+digest
+types
+Not used.
+<br><dt>‘<samp><span class="samp">107</span></samp>’<dd>.Pq
+bad
+signature
+length
+The signature length does not match the current public key.
+<br><dt>‘<samp><span class="samp">108</span></samp>’<dd>.Pq
+signature
+not
+verified
+The message fails the signature check.
+It could be bogus or signed by a
+different private key.
+<br><dt>‘<samp><span class="samp">109</span></samp>’<dd>.Pq
+certificate
+not
+verified
+The certificate is invalid or signed with the wrong key.
+<br><dt>‘<samp><span class="samp">110</span></samp>’<dd>.Pq
+certificate
+not
+verified
+The certificate is not yet valid or has expired or the signature could not
+be verified.
+<br><dt>‘<samp><span class="samp">111</span></samp>’<dd>.Pq
+bad
+or
+missing
+cookie
+The cookie is missing, corrupted or bogus.
+<br><dt>‘<samp><span class="samp">112</span></samp>’<dd>.Pq
+bad
+or
+missing
+leapseconds
+table
+The leapseconds table is missing, corrupted or bogus.
+<br><dt>‘<samp><span class="samp">113</span></samp>’<dd>.Pq
+bad
+or
+missing
+certificate
+The certificate is missing, corrupted or bogus.
+<br><dt>‘<samp><span class="samp">114</span></samp>’<dd>.Pq
+bad
+or
+missing
+identity
+The identity key is missing, corrupt or bogus.
+
+ <p>.Sh
+Monitoring
+Support
+<code>ntpd(1ntpdmdoc)</code>
+includes a comprehensive monitoring facility suitable
+for continuous, long term recording of server and client
+timekeeping performance.
+See the
+.Ic
+statistics
+command below
+for a listing and example of each type of statistics currently
+supported.
+Statistic files are managed using file generation sets
+and scripts in the
+.Pa
+./scripts
+directory of this distribution.
+Using
+these facilities and
+.Ux
+<code>cron(8)</code>
+jobs, the data can be
+automatically summarized and archived for retrospective analysis.
+.Ss
+Monitoring
+Commands
+ <dl>
+<dt>‘<samp><span class="samp">Ic</span></samp>’<dd>Enables writing of statistics records.
+Currently, four kinds of
+.Ar
+name
+statistics are supported.
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables recording of clock driver statistics information.
+Each update
+received from a clock driver appends a line of the following form to
+the file generation set named
+.Cm
+clockstats
+:
+.Bd
+-literal
+49213 525.624 127.127.4.1 93 226 00:08:29.606 D
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The next field shows the
+clock address in dotted-quad notation.
+The final field shows the last
+timecode received from the clock in decoded ASCII format, where
+meaningful.
+In some clock drivers a good deal of additional information
+can be gathered and displayed as well.
+See information specific to each
+clock for further details.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This option requires the OpenSSL cryptographic software library.
+It
+enables recording of cryptographic public key protocol information.
+Each message received by the protocol module appends a line of the
+following form to the file generation set named
+.Cm
+cryptostats
+:
+.Bd
+-literal
+49213 525.624 127.127.4.1 message
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The next field shows the peer
+address in dotted-quad notation, The final message field includes the
+message type and certain ancillary information.
+See the
+.Sx
+Authentication
+Options
+section for further information.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables recording of loop filter statistics information.
+Each
+update of the local clock outputs a line of the following form to
+the file generation set named
+.Cm
+loopstats
+:
+.Bd
+-literal
+50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next five fields
+show time offset (seconds), frequency offset (parts per million -
+PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
+discipline time constant.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables recording of peer statistics information.
+This includes
+statistics records of all peers of a NTP server and of special
+signals, where present and configured.
+Each valid update appends a
+line of the following form to the current element of a file
+generation set named
+.Cm
+peerstats
+:
+.Bd
+-literal
+48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next two fields
+show the peer address in dotted-quad notation and status,
+respectively.
+The status field is encoded in hex in the format
+described in Appendix A of the NTP specification RFC 1305.
+The final four fields show the offset,
+delay, dispersion and RMS jitter, all in seconds.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables recording of raw-timestamp statistics information.
+This
+includes statistics records of all peers of a NTP server and of
+special signals, where present and configured.
+Each NTP message
+received from a peer or clock driver appends a line of the
+following form to the file generation set named
+.Cm
+rawstats
+:
+.Bd
+-literal
+50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and
+time (seconds and fraction past UTC midnight).
+The next two fields
+show the remote peer or clock address followed by the local address
+in dotted-quad notation.
+The final four fields show the originate,
+receive, transmit and final NTP timestamps in order.
+The timestamp
+values are as received and before processing by the various data
+smoothing and mitigation algorithms.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables recording of ntpd statistics counters on a periodic basis.
+Each
+hour a line of the following form is appended to the file generation
+set named
+.Cm
+sysstats
+:
+.Bd
+-literal
+50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
+.Ed
+
+ <p>The first two fields show the date (Modified Julian Day) and time
+(seconds and fraction past UTC midnight).
+The remaining ten fields show
+the statistics counter values accumulated since the last generated
+line.
+ <dl>
+<dt>‘<samp><span class="samp">Time</span></samp>’<dd>Time in hours since the system was last rebooted.
+<br><dt>‘<samp><span class="samp">Packets</span></samp>’<dd>Total number of packets received.
+<br><dt>‘<samp><span class="samp">Packets</span></samp>’<dd>Number of packets received in response to previous packets sent
+<br><dt>‘<samp><span class="samp">Current</span></samp>’<dd>Number of packets matching the current NTP version.
+<br><dt>‘<samp><span class="samp">Previous</span></samp>’<dd>Number of packets matching the previous NTP version.
+<br><dt>‘<samp><span class="samp">Bad</span></samp>’<dd>Number of packets matching neither NTP version.
+<br><dt>‘<samp><span class="samp">Access</span></samp>’<dd>Number of packets denied access for any reason.
+<br><dt>‘<samp><span class="samp">Bad</span></samp>’<dd>Number of packets with invalid length, format or port number.
+<br><dt>‘<samp><span class="samp">Bad</span></samp>’<dd>Number of packets not verified as authentic.
+<br><dt>‘<samp><span class="samp">Rate</span></samp>’<dd>Number of packets discarded due to rate limitation.
+
+ <p>.It
+Cm
+statsdir
+Ar
+directory_path
+Indicates the full path of a directory where statistics files
+should be created (see below).
+This keyword allows
+the (otherwise constant)
+.Cm
+filegen
+filename prefix to be modified for file generation sets, which
+is useful for handling statistics logs.
+.It
+Cm
+filegen
+Ar
+name
+Xo
+.Op
+Cm
+file
+Ar
+filename
+.Op
+Cm
+type
+Ar
+typename
+.Op
+Cm
+link
+|
+nolink
+.Op
+Cm
+enable
+|
+disable
+.Xc
+Configures setting of generation file set name.
+Generation
+file sets provide a means for handling files that are
+continuously growing during the lifetime of a server.
+Server statistics are a typical example for such files.
+Generation file sets provide access to a set of files used
+to store the actual data.
+At any time at most one element
+of the set is being written to.
+The type given specifies
+when and how data will be directed to a new element of the set.
+This way, information stored in elements of a file set
+that are currently unused are available for administrational
+operations without the risk of disturbing the operation of ntpd.
+(Most important: they can be removed to free space for new data
+produced.)
+
+ <p>Note that this command can be sent from the
+<code>ntpdc(1ntpdcmdoc)</code>
+program running at a remote location.
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is the type of the statistics records, as shown in the
+.Cm
+statistics
+command.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is the file name for the statistics records.
+Filenames of set
+members are built from three concatenated elements
+.Ar
+Cm
+prefix
+,
+.Ar
+Cm
+filename
+and
+.Ar
+Cm
+suffix
+:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is a constant filename path.
+It is not subject to
+modifications via the
+.Ar
+filegen
+option.
+It is defined by the
+server, usually specified as a compile-time constant.
+It may,
+however, be configurable for individual file generation sets
+via other commands.
+For example, the prefix used with
+.Ar
+loopstats
+and
+.Ar
+peerstats
+generation can be configured using the
+.Ar
+statsdir
+option explained above.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This string is directly concatenated to the prefix mentioned
+above (no intervening
+.Ql
+/
+)
+.
+This can be modified using
+the file argument to the
+.Ar
+filegen
+statement.
+No
+.Pa
+..
+elements are
+allowed in this component to prevent filenames referring to
+parts outside the filesystem hierarchy denoted by
+.Ar
+prefix
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This part is reflects individual elements of a file set.
+It is
+generated according to the type of a file set.
+
+ <p>.It
+Cm
+type
+Ar
+typename
+A file generation set is characterized by its type.
+The following
+types are supported:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The file set is actually a single plain file.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>One element of file set is used per incarnation of a ntpd
+server.
+This type does not perform any changes to file set
+members during runtime, however it provides an easy way of
+separating files belonging to different
+<code>ntpd(1ntpdmdoc)</code>
+server incarnations.
+The set member filename is built by appending a
+.Ql
+\&.
+to concatenated
+.Ar
+prefix
+and
+.Ar
+filename
+strings, and
+appending the decimal representation of the process ID of the
+<code>ntpd(1ntpdmdoc)</code>
+server process.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>One file generation set element is created per day.
+A day is
+defined as the period between 00:00 and 24:00 UTC.
+The file set
+member suffix consists of a
+.Ql
+\&.
+and a day specification in
+the form
+.Cm
+YYYYMMdd
+.
+.Cm
+YYYY
+is a 4-digit year number (e.g., 1992).
+.Cm
+MM
+is a two digit month number.
+.Cm
+dd
+is a two digit day number.
+Thus, all information written at 10 December 1992 would end up
+in a file named
+.Ar
+prefix
+.Ar
+filename
+Ns
+.19921210
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Any file set member contains data related to a certain week of
+a year.
+The term week is defined by computing day-of-year
+modulo 7.
+Elements of such a file generation set are
+distinguished by appending the following suffix to the file set
+filename base: A dot, a 4-digit year number, the letter
+.Cm
+W
+,
+and a 2-digit week number.
+For example, information from January,
+10th 1992 would end up in a file with suffix
+.No
+.
+Ns
+Ar
+1992W1
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>One generation file set element is generated per month.
+The
+file name suffix consists of a dot, a 4-digit year number, and
+a 2-digit month.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>One generation file element is generated per year.
+The filename
+suffix consists of a dot and a 4 digit year number.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This type of file generation sets changes to a new element of
+the file set every 24 hours of server operation.
+The filename
+suffix consists of a dot, the letter
+.Cm
+a
+,
+and an 8-digit number.
+This number is taken to be the number of seconds the server is
+running at the start of the corresponding 24-hour period.
+Information is only written to a file generation by specifying
+.Cm
+enable
+;
+output is prevented by specifying
+.Cm
+disable
+.
+
+ <p>.It
+Cm
+link
+|
+nolink
+It is convenient to be able to access the current element of a file
+generation set by a fixed name.
+This feature is enabled by
+specifying
+.Cm
+link
+and disabled using
+.Cm
+nolink
+.
+If link is specified, a
+hard link from the current file set element to a file without
+suffix is created.
+When there is already a file with this name and
+the number of links of this file is one, it is renamed appending a
+dot, the letter
+.Cm
+C
+,
+and the pid of the ntpd server process.
+When the
+number of links is greater than one, the file is unlinked.
+This
+allows the current file to be accessed by a constant name.
+.It
+Cm
+enable
+\&|
+Cm
+disable
+Enables or disables the recording function.
+
+ <p>.Sh
+Access
+Control
+Support
+The
+<code>ntpd(1ntpdmdoc)</code>
+daemon implements a general purpose address/mask based restriction
+list.
+The list contains address/match entries sorted first
+by increasing address values and and then by increasing mask values.
+A match occurs when the bitwise AND of the mask and the packet
+source address is equal to the bitwise AND of the mask and
+address in the list.
+The list is searched in order with the
+last match found defining the restriction flags associated
+with the entry.
+Additional information and examples can be found in the
+.Qq
+Notes
+on
+Configuring
+NTP
+and
+Setting
+up
+a
+NTP
+Subnet
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+
+ <p>The restriction facility was implemented in conformance
+with the access policies for the original NSFnet backbone
+time servers.
+Later the facility was expanded to deflect
+cryptographic and clogging attacks.
+While this facility may
+be useful for keeping unwanted or broken or malicious clients
+from congesting innocent servers, it should not be considered
+an alternative to the NTP authentication facilities.
+Source address based restrictions are easily circumvented
+by a determined cracker.
+
+ <p>Clients can be denied service because they are explicitly
+included in the restrict list created by the restrict command
+or implicitly as the result of cryptographic or rate limit
+violations.
+Cryptographic violations include certificate
+or identity verification failure; rate limit violations generally
+result from defective NTP implementations that send packets
+at abusive rates.
+Some violations cause denied service
+only for the offending packet, others cause denied service
+for a timed period and others cause the denied service for
+an indefinate period.
+When a client or network is denied access
+for an indefinate period, the only way at present to remove
+the restrictions is by restarting the server.
+.Ss
+The
+Kiss-of-Death
+Packet
+Ordinarily, packets denied service are simply dropped with no
+further action except incrementing statistics counters.
+Sometimes a
+more proactive response is needed, such as a server message that
+explicitly requests the client to stop sending and leave a message
+for the system operator.
+A special packet format has been created
+for this purpose called the "kiss-of-death" (KoD) packet.
+KoD packets have the leap bits set unsynchronized and stratum set
+to zero and the reference identifier field set to a four-byte
+ASCII code.
+If the
+.Cm
+noserve
+or
+.Cm
+notrust
+flag of the matching restrict list entry is set,
+the code is "DENY"; if the
+.Cm
+limited
+flag is set and the rate limit
+is exceeded, the code is "RATE".
+Finally, if a cryptographic violation occurs, the code is "CRYP".
+
+ <p>A client receiving a KoD performs a set of sanity checks to
+minimize security exposure, then updates the stratum and
+reference identifier peer variables, sets the access
+denied (TEST4) bit in the peer flash variable and sends
+a message to the log.
+As long as the TEST4 bit is set,
+the client will send no further packets to the server.
+The only way at present to recover from this condition is
+to restart the protocol at both the client and server.
+This
+happens automatically at the client when the association times out.
+It will happen at the server only if the server operator cooperates.
+.Ss
+Access
+Control
+Commands
+ <dl>
+<dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+average
+Ar
+avg
+.Op
+Cm
+minimum
+Ar
+min
+.Op
+Cm
+monitor
+Ar
+prob
+.Xc
+Set the parameters of the
+.Cm
+limited
+facility which protects the server from
+client abuse.
+The
+.Cm
+average
+subcommand specifies the minimum average packet
+spacing, while the
+.Cm
+minimum
+subcommand specifies the minimum packet spacing.
+Packets that violate these minima are discarded
+and a kiss-o'-death packet returned if enabled.
+The default
+minimum average and minimum are 5 and 2, respectively.
+The monitor subcommand specifies the probability of discard
+for packets that overflow the rate-control window.
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Op
+Cm
+mask
+Ar
+mask
+.Op
+Ar
+flag
+...
+.Xc
+The
+.Ar
+address
+argument expressed in
+dotted-quad form is the address of a host or network.
+Alternatively, the
+.Ar
+address
+argument can be a valid host DNS name.
+The
+.Ar
+mask
+argument expressed in dotted-quad form defaults to
+.Cm
+255.255.255.255
+,
+meaning that the
+.Ar
+address
+is treated as the address of an individual host.
+A default entry (address
+.Cm
+0.0.0.0
+,
+mask
+.Cm
+0.0.0.0
+)
+is always included and is always the first entry in the list.
+Note that text string
+.Cm
+default
+,
+with no mask option, may
+be used to indicate the default entry.
+In the current implementation,
+.Cm
+flag
+always
+restricts access, i.e., an entry with no flags indicates that free
+access to the server is to be given.
+The flags are not orthogonal,
+in that more restrictive flags will often make less restrictive
+ones redundant.
+The flags can generally be classed into two
+categories, those which restrict time service and those which
+restrict informational queries and attempts to do run-time
+reconfiguration of the server.
+One or more of the following flags
+may be specified:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny packets of all kinds, including
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+queries.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>If this flag is set when an access violation occurs, a kiss-o'-death
+(KoD) packet is sent.
+KoD packets are rate limited to no more than one
+per second.
+If another KoD packet occurs within one second after the
+last one, the packet is dropped.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny service if the packet spacing violates the lower limits specified
+in the discard command.
+A history of clients is kept using the
+monitoring capability of
+<code>ntpd(1ntpdmdoc)</code>.
+Thus, monitoring is always active as
+long as there is a restriction entry with the
+.Cm
+limited
+flag.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Declare traps set by matching hosts to be low priority.
+The
+number of traps a server can maintain is limited (the current limit
+is 3).
+Traps are usually assigned on a first come, first served
+basis, with later trap requestors being denied service.
+This flag
+modifies the assignment algorithm by allowing low priority traps to
+be overridden by later requests for normal priority traps.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+queries which attempt to modify the state of the
+server (i.e., run time reconfiguration).
+Queries which return
+information are permitted.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+queries.
+Time service is not affected.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny packets which would result in mobilizing a new association.
+This
+includes broadcast and symmetric active packets when a configured
+association does not exist.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny all packets except
+<code>ntpq(1ntpqmdoc)</code>
+and
+<code>ntpdc(1ntpdcmdoc)</code>
+queries.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Decline to provide mode 6 control message trap service to matching
+hosts.
+The trap service is a subsystem of the ntpdq control message
+protocol which is intended for use by remote event logging programs.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny service unless the packet is cryptographically authenticated.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is actually a match algorithm modifier, rather than a
+restriction flag.
+Its presence causes the restriction entry to be
+matched only if the source port in the packet is the standard NTP
+UDP port (123).
+Both
+.Cm
+ntpport
+and
+.Cm
+non-ntpport
+may
+be specified.
+The
+.Cm
+ntpport
+is considered more specific and
+is sorted later in the list.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Deny packets that do not match the current NTP version.
+
+ <p>Default restriction list entries with the flags ignore, interface,
+ntpport, for each of the local host's interface addresses are
+inserted into the table at startup to prevent the server
+from attempting to synchronize to its own time.
+A default entry is also always present, though if it is
+otherwise unconfigured; no flags are associated
+with the default entry (i.e., everything besides your own
+NTP server is unrestricted).
+
+ <p>.Sh
+Automatic
+NTP
+Configuration
+Options
+.Ss
+Manycasting
+Manycasting is a automatic discovery and configuration paradigm
+new to NTPv4.
+It is intended as a means for a multicast client
+to troll the nearby network neighborhood to find cooperating
+manycast servers, validate them using cryptographic means
+and evaluate their time values with respect to other servers
+that might be lurking in the vicinity.
+The intended result is that each manycast client mobilizes
+client associations with some number of the "best"
+of the nearby manycast servers, yet automatically reconfigures
+to sustain this number of servers should one or another fail.
+
+ <p>Note that the manycasting paradigm does not coincide
+with the anycast paradigm described in RFC-1546,
+which is designed to find a single server from a clique
+of servers providing the same service.
+The manycast paradigm is designed to find a plurality
+of redundant servers satisfying defined optimality criteria.
+
+ <p>Manycasting can be used with either symmetric key
+or public key cryptography.
+The public key infrastructure (PKI)
+offers the best protection against compromised keys
+and is generally considered stronger, at least with relatively
+large key sizes.
+It is implemented using the Autokey protocol and
+the OpenSSL cryptographic library available from
+.Li
+http://www.openssl.org/
+.
+The library can also be used with other NTPv4 modes
+as well and is highly recommended, especially for broadcast modes.
+
+ <p>A persistent manycast client association is configured
+using the manycastclient command, which is similar to the
+server command but with a multicast (IPv4 class
+.Cm
+D
+or IPv6 prefix
+.Cm
+FF
+)
+group address.
+The IANA has designated IPv4 address 224.1.1.1
+and IPv6 address FF05::101 (site local) for NTP.
+When more servers are needed, it broadcasts manycast
+client messages to this address at the minimum feasible rate
+and minimum feasible time-to-live (TTL) hops, depending
+on how many servers have already been found.
+There can be as many manycast client associations
+as different group address, each one serving as a template
+for a future ephemeral unicast client/server association.
+
+ <p>Manycast servers configured with the
+.Ic
+manycastserver
+command listen on the specified group address for manycast
+client messages.
+Note the distinction between manycast client,
+which actively broadcasts messages, and manycast server,
+which passively responds to them.
+If a manycast server is
+in scope of the current TTL and is itself synchronized
+to a valid source and operating at a stratum level equal
+to or lower than the manycast client, it replies to the
+manycast client message with an ordinary unicast server message.
+
+ <p>The manycast client receiving this message mobilizes
+an ephemeral client/server association according to the
+matching manycast client template, but only if cryptographically
+authenticated and the server stratum is less than or equal
+to the client stratum.
+Authentication is explicitly required
+and either symmetric key or public key (Autokey) can be used.
+Then, the client polls the server at its unicast address
+in burst mode in order to reliably set the host clock
+and validate the source.
+This normally results
+in a volley of eight client/server at 2-s intervals
+during which both the synchronization and cryptographic
+protocols run concurrently.
+Following the volley,
+the client runs the NTP intersection and clustering
+algorithms, which act to discard all but the "best"
+associations according to stratum and synchronization
+distance.
+The surviving associations then continue
+in ordinary client/server mode.
+
+ <p>The manycast client polling strategy is designed to reduce
+as much as possible the volume of manycast client messages
+and the effects of implosion due to near-simultaneous
+arrival of manycast server messages.
+The strategy is determined by the
+.Ic
+manycastclient
+,
+.Ic
+tos
+and
+.Ic
+ttl
+configuration commands.
+The manycast poll interval is
+normally eight times the system poll interval,
+which starts out at the
+.Cm
+minpoll
+value specified in the
+.Ic
+manycastclient
+,
+command and, under normal circumstances, increments to the
+.Cm
+maxpolll
+value specified in this command.
+Initially, the TTL is
+set at the minimum hops specified by the ttl command.
+At each retransmission the TTL is increased until reaching
+the maximum hops specified by this command or a sufficient
+number client associations have been found.
+Further retransmissions use the same TTL.
+
+ <p>The quality and reliability of the suite of associations
+discovered by the manycast client is determined by the NTP
+mitigation algorithms and the
+.Cm
+minclock
+and
+.Cm
+minsane
+values specified in the
+.Ic
+tos
+configuration command.
+At least
+.Cm
+minsane
+candidate servers must be available and the mitigation
+algorithms produce at least
+.Cm
+minclock
+survivors in order to synchronize the clock.
+Byzantine agreement principles require at least four
+candidates in order to correctly discard a single falseticker.
+For legacy purposes,
+.Cm
+minsane
+defaults to 1 and
+.Cm
+minclock
+defaults to 3.
+For manycast service
+.Cm
+minsane
+should be explicitly set to 4, assuming at least that
+number of servers are available.
+
+ <p>If at least
+.Cm
+minclock
+servers are found, the manycast poll interval is immediately
+set to eight times
+.Cm
+maxpoll
+.
+If less than
+.Cm
+minclock
+servers are found when the TTL has reached the maximum hops,
+the manycast poll interval is doubled.
+For each transmission
+after that, the poll interval is doubled again until
+reaching the maximum of eight times
+.Cm
+maxpoll
+.
+Further transmissions use the same poll interval and
+TTL values.
+Note that while all this is going on,
+each client/server association found is operating normally
+it the system poll interval.
+
+ <p>Administratively scoped multicast boundaries are normally
+specified by the network router configuration and,
+in the case of IPv6, the link/site scope prefix.
+By default, the increment for TTL hops is 32 starting
+from 31; however, the
+.Ic
+ttl
+configuration command can be
+used to modify the values to match the scope rules.
+
+ <p>It is often useful to narrow the range of acceptable
+servers which can be found by manycast client associations.
+Because manycast servers respond only when the client
+stratum is equal to or greater than the server stratum,
+primary (stratum 1) servers fill find only primary servers
+in TTL range, which is probably the most common objective.
+However, unless configured otherwise, all manycast clients
+in TTL range will eventually find all primary servers
+in TTL range, which is probably not the most common
+objective in large networks.
+The
+.Ic
+tos
+command can be used to modify this behavior.
+Servers with stratum below
+.Cm
+floor
+or above
+.Cm
+ceiling
+specified in the
+.Ic
+tos
+command are strongly discouraged during the selection
+process; however, these servers may be temporally
+accepted if the number of servers within TTL range is
+less than
+.Cm
+minclock
+.
+
+ <p>The above actions occur for each manycast client message,
+which repeats at the designated poll interval.
+However, once the ephemeral client association is mobilized,
+subsequent manycast server replies are discarded,
+since that would result in a duplicate association.
+If during a poll interval the number of client associations
+falls below
+.Cm
+minclock
+,
+all manycast client prototype associations are reset
+to the initial poll interval and TTL hops and operation
+resumes from the beginning.
+It is important to avoid
+frequent manycast client messages, since each one requires
+all manycast servers in TTL range to respond.
+The result could well be an implosion, either minor or major,
+depending on the number of servers in range.
+The recommended value for
+.Cm
+maxpoll
+is 12 (4,096 s).
+
+ <p>It is possible and frequently useful to configure a host
+as both manycast client and manycast server.
+A number of hosts configured this way and sharing a common
+group address will automatically organize themselves
+in an optimum configuration based on stratum and
+synchronization distance.
+For example, consider an NTP
+subnet of two primary servers and a hundred or more
+dependent clients.
+With two exceptions, all servers
+and clients have identical configuration files including both
+.Ic
+multicastclient
+and
+.Ic
+multicastserver
+commands using, for instance, multicast group address
+239.1.1.1.
+The only exception is that each primary server
+configuration file must include commands for the primary
+reference source such as a GPS receiver.
+
+ <p>The remaining configuration files for all secondary
+servers and clients have the same contents, except for the
+.Ic
+tos
+command, which is specific for each stratum level.
+For stratum 1 and stratum 2 servers, that command is
+not necessary.
+For stratum 3 and above servers the
+.Cm
+floor
+value is set to the intended stratum number.
+Thus, all stratum 3 configuration files are identical,
+all stratum 4 files are identical and so forth.
+
+ <p>Once operations have stabilized in this scenario,
+the primary servers will find the primary reference source
+and each other, since they both operate at the same
+stratum (1), but not with any secondary server or client,
+since these operate at a higher stratum.
+The secondary
+servers will find the servers at the same stratum level.
+If one of the primary servers loses its GPS receiver,
+it will continue to operate as a client and other clients
+will time out the corresponding association and
+re-associate accordingly.
+
+ <p>Some administrators prefer to avoid running
+<code>ntpd(1ntpdmdoc)</code>
+continuously and run either
+<code>ntpdate(8)</code>
+or
+<code>ntpd(1ntpdmdoc)</code>
+<code>-q</code> as a cron job.
+In either case the servers must be
+configured in advance and the program fails if none are
+available when the cron job runs.
+A really slick
+application of manycast is with
+<code>ntpd(1ntpdmdoc)</code>
+<code>-q</code>. The program wakes up, scans the local landscape looking
+for the usual suspects, selects the best from among
+the rascals, sets the clock and then departs.
+Servers do not have to be configured in advance and
+all clients throughout the network can have the same
+configuration file.
+.Ss
+Manycast
+Interactions
+with
+Autokey
+Each time a manycast client sends a client mode packet
+to a multicast group address, all manycast servers
+in scope generate a reply including the host name
+and status word.
+The manycast clients then run
+the Autokey protocol, which collects and verifies
+all certificates involved.
+Following the burst interval
+all but three survivors are cast off,
+but the certificates remain in the local cache.
+It often happens that several complete signing trails
+from the client to the primary servers are collected in this way.
+
+ <p>About once an hour or less often if the poll interval
+exceeds this, the client regenerates the Autokey key list.
+This is in general transparent in client/server mode.
+However, about once per day the server private value
+used to generate cookies is refreshed along with all
+manycast client associations.
+In this case all
+cryptographic values including certificates is refreshed.
+If a new certificate has been generated since
+the last refresh epoch, it will automatically revoke
+all prior certificates that happen to be in the
+certificate cache.
+At the same time, the manycast
+scheme starts all over from the beginning and
+the expanding ring shrinks to the minimum and increments
+from there while collecting all servers in scope.
+.Ss
+Manycast
+Options
+ <dl>
+<dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Oo
+.Cm
+ceiling
+Ar
+ceiling
+|
+.Cm
+cohort
+
+ <p>0.Cm
+floor
+Ar
+floor
+|
+.Cm
+minclock
+Ar
+minclock
+|
+.Cm
+minsane
+Ar
+minsane
+.Oc
+.Xc
+This command affects the clock selection and clustering
+algorithms.
+It can be used to select the quality and
+quantity of peers used to synchronize the system clock
+and is most useful in manycast mode.
+The variables operate
+as follows:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Peers with strata above
+.Cm
+ceiling
+will be discarded if there are at least
+.Cm
+minclock
+peers remaining.
+This value defaults to 15, but can be changed
+to any number from 1 to 15.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is a binary flag which enables (0) or disables (1)
+manycast server replies to manycast clients with the same
+stratum level.
+This is useful to reduce implosions where
+large numbers of clients with the same stratum level
+are present.
+The default is to enable these replies.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Peers with strata below
+.Cm
+floor
+will be discarded if there are at least
+.Cm
+minclock
+peers remaining.
+This value defaults to 1, but can be changed
+to any number from 1 to 15.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The clustering algorithm repeatedly casts out outlyer
+associations until no more than
+.Cm
+minclock
+associations remain.
+This value defaults to 3,
+but can be changed to any number from 1 to the number of
+configured sources.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>This is the minimum number of candidates available
+to the clock selection algorithm in order to produce
+one or more truechimers for the clustering algorithm.
+If fewer than this number are available, the clock is
+undisciplined and allowed to run free.
+The default is 1
+for legacy purposes.
+However, according to principles of
+Byzantine agreement,
+.Cm
+minsane
+should be at least 4 in order to detect and discard
+a single falseticker.
+
+ <p>.It
+Cm
+ttl
+Ar
+hop
+...
+This command specifies a list of TTL values in increasing
+order, up to 8 values can be specified.
+In manycast mode these values are used in turn
+in an expanding-ring search.
+The default is eight
+multiples of 32 starting at 31.
+
+ <p>.Sh
+Reference
+Clock
+Support
+The NTP Version 4 daemon supports some three dozen different radio,
+satellite and modem reference clocks plus a special pseudo-clock
+used for backup or when no other clock source is available.
+Detailed descriptions of individual device drivers and options can
+be found in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+Additional information can be found in the pages linked
+there, including the
+.Qq
+Debugging
+Hints
+for
+Reference
+Clock
+Drivers
+and
+.Qq
+How
+To
+Write
+a
+Reference
+Clock
+Driver
+pages
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+In addition, support for a PPS
+signal is available as described in the
+.Qq
+Pulse-per-second
+(PPS)
+Signal
+Interfacing
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+Many
+drivers support special line discipline/streams modules which can
+significantly improve the accuracy using the driver.
+These are
+described in the
+.Qq
+Line
+Disciplines
+and
+Streams
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+
+ <p>A reference clock will generally (though not always) be a radio
+timecode receiver which is synchronized to a source of standard
+time such as the services offered by the NRC in Canada and NIST and
+USNO in the US.
+The interface between the computer and the timecode
+receiver is device dependent, but is usually a serial port.
+A
+device driver specific to each reference clock must be selected and
+compiled in the distribution; however, most common radio, satellite
+and modem clocks are included by default.
+Note that an attempt to
+configure a reference clock when the driver has not been compiled
+or the hardware port has not been appropriately configured results
+in a scalding remark to the system log file, but is otherwise non
+hazardous.
+
+ <p>For the purposes of configuration,
+<code>ntpd(1ntpdmdoc)</code>
+treats
+reference clocks in a manner analogous to normal NTP peers as much
+as possible.
+Reference clocks are identified by a syntactically
+correct but invalid IP address, in order to distinguish them from
+normal NTP peers.
+Reference clock addresses are of the form
+.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+,
+.Sm
+on
+where
+.Ar
+t
+is an integer
+denoting the clock type and
+.Ar
+u
+indicates the unit
+number in the range 0-3.
+While it may seem overkill, it is in fact
+sometimes useful to configure multiple reference clocks of the same
+type, in which case the unit numbers must be unique.
+
+ <p>The
+.Ic
+server
+command is used to configure a reference
+clock, where the
+.Ar
+address
+argument in that command
+is the clock address.
+The
+.Cm
+key
+,
+.Cm
+version
+and
+.Cm
+ttl
+options are not used for reference clock support.
+The
+.Cm
+mode
+option is added for reference clock support, as
+described below.
+The
+.Cm
+prefer
+option can be useful to
+persuade the server to cherish a reference clock with somewhat more
+enthusiasm than other reference clocks or peers.
+Further
+information on this option can be found in the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+page.
+The
+.Cm
+minpoll
+and
+.Cm
+maxpoll
+options have
+meaning only for selected clock drivers.
+See the individual clock
+driver document pages for additional information.
+
+ <p>The
+.Ic
+fudge
+command is used to provide additional
+information for individual clock drivers and normally follows
+immediately after the
+.Ic
+server
+command.
+The
+.Ar
+address
+argument specifies the clock address.
+The
+.Cm
+refid
+and
+.Cm
+stratum
+options can be used to
+override the defaults for the device.
+There are two optional
+device-dependent time offsets and four flags that can be included
+in the
+.Ic
+fudge
+command as well.
+
+ <p>The stratum number of a reference clock is by default zero.
+Since the
+<code>ntpd(1ntpdmdoc)</code>
+daemon adds one to the stratum of each
+peer, a primary server ordinarily displays an external stratum of
+one.
+In order to provide engineered backups, it is often useful to
+specify the reference clock stratum as greater than zero.
+The
+.Cm
+stratum
+option is used for this purpose.
+Also, in cases
+involving both a reference clock and a pulse-per-second (PPS)
+discipline signal, it is useful to specify the reference clock
+identifier as other than the default, depending on the driver.
+The
+.Cm
+refid
+option is used for this purpose.
+Except where noted,
+these options apply to all clock drivers.
+.Ss
+Reference
+Clock
+Commands
+ <dl>
+<dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+.Sm
+on
+.Op
+Cm
+prefer
+.Op
+Cm
+mode
+Ar
+int
+.Op
+Cm
+minpoll
+Ar
+int
+.Op
+Cm
+maxpoll
+Ar
+int
+.Xc
+This command can be used to configure reference clocks in
+special ways.
+The options are interpreted as follows:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Marks the reference clock as preferred.
+All other things being
+equal, this host will be chosen for synchronization among a set of
+correctly operating hosts.
+See the
+.Qq
+Mitigation
+Rules
+and
+the
+prefer
+Keyword
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+for further information.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies a mode number which is interpreted in a
+device-specific fashion.
+For instance, it selects a dialing
+protocol in the ACTS driver and a device subtype in the
+parse
+drivers.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>These options specify the minimum and maximum polling interval
+for reference clock messages, as a power of 2 in seconds
+For
+most directly connected reference clocks, both
+.Cm
+minpoll
+and
+.Cm
+maxpoll
+default to 6 (64 s).
+For modem reference clocks,
+.Cm
+minpoll
+defaults to 10 (17.1 m) and
+.Cm
+maxpoll
+defaults to 14 (4.5 h).
+The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
+
+ <p>.It
+Xo
+Ic
+fudge
+.Sm
+off
+.Li
+127.127.
+Ar
+t
+.
+Ar
+u
+.Sm
+on
+.Op
+Cm
+time1
+Ar
+sec
+.Op
+Cm
+time2
+Ar
+sec
+.Op
+Cm
+stratum
+Ar
+int
+.Op
+Cm
+refid
+Ar
+string
+.Op
+Cm
+mode
+Ar
+int
+.Op
+Cm
+flag1
+Cm
+0.Op
+Cm
+flag2
+Cm
+0.Op
+Cm
+flag3
+Cm
+0.Op
+Cm
+flag4
+Cm
+0.Xc
+This command can be used to configure reference clocks in
+special ways.
+It must immediately follow the
+.Ic
+server
+command which configures the driver.
+Note that the same capability
+is possible at run time using the
+<code>ntpdc(1ntpdcmdoc)</code>
+program.
+The options are interpreted as
+follows:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies a constant to be added to the time offset produced by
+the driver, a fixed-point decimal number in seconds.
+This is used
+as a calibration constant to adjust the nominal time offset of a
+particular clock to agree with an external standard, such as a
+precision PPS signal.
+It also provides a way to correct a
+systematic error or bias due to serial port or operating system
+latencies, different cable lengths or receiver internal delay.
+The
+specified offset is in addition to the propagation delay provided
+by other means, such as internal DIPswitches.
+Where a calibration
+for an individual system and driver is available, an approximate
+correction is noted in the driver documentation pages.
+Note: in order to facilitate calibration when more than one
+radio clock or PPS signal is supported, a special calibration
+feature is available.
+It takes the form of an argument to the
+.Ic
+enable
+command described in
+.Sx
+Miscellaneous
+Options
+page and operates as described in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies a fixed-point decimal number in seconds, which is
+interpreted in a driver-dependent way.
+See the descriptions of
+specific drivers in the
+.Qq
+Reference
+Clock
+Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies the stratum number assigned to the driver, an integer
+between 0 and 15.
+This number overrides the default stratum number
+ordinarily assigned by the driver itself, usually zero.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies an ASCII string of from one to four characters which
+defines the reference identifier used by the driver.
+This string
+overrides the default identifier ordinarily assigned by the driver
+itself.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Specifies a mode number which is interpreted in a
+device-specific fashion.
+For instance, it selects a dialing
+protocol in the ACTS driver and a device subtype in the
+parse
+drivers.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<br><dt>‘<samp><span class="samp">Cm</span></samp>’<br><dt>‘<samp><span class="samp">Cm</span></samp>’<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>These four flags are used for customizing the clock driver.
+The
+interpretation of these values, and whether they are used at all,
+is a function of the particular clock driver.
+However, by
+convention
+.Cm
+flag4
+is used to enable recording monitoring
+data to the
+.Cm
+clockstats
+file configured with the
+.Ic
+filegen
+command.
+Further information on the
+.Ic
+filegen
+command can be found in
+.Sx
+Monitoring
+Options
+.
+
+ <p>.Sh
+Miscellaneous
+Options
+ <dl>
+<dt>‘<samp><span class="samp">Ic</span></samp>’<dd>The broadcast and multicast modes require a special calibration
+to determine the network delay between the local and remote
+servers.
+Ordinarily, this is done automatically by the initial
+protocol exchanges between the client and server.
+In some cases,
+the calibration procedure may fail due to network or server access
+controls, for example.
+This command specifies the default delay to
+be used under these circumstances.
+Typically (for Ethernet), a
+number between 0.003 and 0.007 seconds is appropriate.
+The default
+when this command is not used is 0.004 seconds.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>This option controls the delay in seconds between the first and second
+packets sent in burst or iburst mode to allow additional time for a modem
+or ISDN call to complete.
+<br><dt>‘<samp><span class="samp">Ic</span></samp>’<dd>This command specifies the complete path and name of the file used to
+record the frequency of the local clock oscillator.
+This is the same
+operation as the
+<code>-f</code> command line option.
+If the file exists, it is read at
+startup in order to set the initial frequency and then updated once per
+hour with the current frequency computed by the daemon.
+If the file name is
+specified, but the file itself does not exist, the starts with an initial
+frequency of zero and creates the file when writing it for the first time.
+If this command is not given, the daemon will always start with an initial
+frequency of zero.
+
+ <p>The file format consists of a single line containing a single
+floating point number, which records the frequency offset measured
+in parts-per-million (PPM).
+The file is updated by first writing
+the current drift value into a temporary file and then renaming
+this file to replace the old version.
+This implies that
+<code>ntpd(1ntpdmdoc)</code>
+must have write permission for the directory the
+drift file is located in, and that file system links, symbolic or
+otherwise, should be avoided.
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Oo
+.Cm
+auth
+|
+Cm
+bclient
+|
+.Cm
+calibrate
+|
+Cm
+kernel
+|
+.Cm
+monitor
+|
+Cm
+ntp
+|
+.Cm
+pps
+|
+Cm
+stats
+.Oc
+.Xc
+<br><dt>‘<samp><span class="samp">Xo</span></samp>’<dd>.Oo
+.Cm
+auth
+|
+Cm
+bclient
+|
+.Cm
+calibrate
+|
+Cm
+kernel
+|
+.Cm
+monitor
+|
+Cm
+ntp
+|
+.Cm
+pps
+|
+Cm
+stats
+.Oc
+.Xc
+Provides a way to enable or disable various server options.
+Flags not mentioned are unaffected.
+Note that all of these flags
+can be controlled remotely using the
+<code>ntpdc(1ntpdcmdoc)</code>
+utility program.
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the server to synchronize with unconfigured peers only if the
+peer has been correctly authenticated using either public key or
+private key cryptography.
+The default for this flag is
+.Ic
+enable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the server to listen for a message from a broadcast or
+multicast server, as in the
+.Ic
+multicastclient
+command with default
+address.
+The default for this flag is
+.Ic
+disable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the calibrate feature for reference clocks.
+The default for
+this flag is
+.Ic
+disable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the kernel time discipline, if available.
+The default for this
+flag is
+.Ic
+enable
+if support is available, otherwise
+.Ic
+disable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the monitoring facility.
+See the
+<code>ntpdc(1ntpdcmdoc)</code>
+program
+and the
+.Ic
+monlist
+command or further information.
+The
+default for this flag is
+.Ic
+enable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables time and frequency discipline.
+In effect, this switch opens and
+closes the feedback loop, which is useful for testing.
+The default for
+this flag is
+.Ic
+enable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the pulse-per-second (PPS) signal when frequency and time is
+disciplined by the precision time kernel modifications.
+See the
+.Qq
+A
+Kernel
+Model
+for
+Precision
+Timekeeping
+(available as part of the HTML documentation
+provided in
+.Pa
+/usr/share/doc/ntp
+)
+page for further information.
+The default for this flag is
+.Ic
+disable
+.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>Enables the statistics facility.
+See the
+.Sx
+Monitoring
+Options
+section for further information.
+The default for this flag is
+.Ic
+disable
+.
+
+ <p>.It
+Ic
+includefile
+Ar
+includefile
+This command allows additional configuration commands
+to be included from a separate file.
+Include files may
+be nested to a depth of five; upon reaching the end of any
+include file, command processing resumes in the previous
+configuration file.
+This option is useful for sites that run
+<code>ntpd(1ntpdmdoc)</code>
+on multiple hosts, with (mostly) common options (e.g., a
+restriction list).
+.It
+Ic
+logconfig
+Ar
+configkeyword
+This command controls the amount and type of output written to
+the system
+<code>syslog(3)</code>
+facility or the alternate
+.Ic
+logfile
+log file.
+By default, all output is turned on.
+All
+.Ar
+configkeyword
+keywords can be prefixed with
+.Ql
+=
+,
+.Ql
++
+and
+.Ql
+-
+,
+where
+.Ql
+=
+sets the
+<code>syslog(3)</code>
+priority mask,
+.Ql
++
+adds and
+.Ql
+-
+removes
+messages.
+<code>syslog(3)</code>
+messages can be controlled in four
+classes
+.Po
+.Cm
+clock
+,
+.Cm
+peer
+,
+.Cm
+sys
+and
+.Cm
+sync
+.Pc
+.
+Within these classes four types of messages can be
+controlled: informational messages
+.Po
+.Cm
+info
+.Pc
+,
+event messages
+.Po
+.Cm
+events
+.Pc
+,
+statistics messages
+.Po
+.Cm
+statistics
+.Pc
+and
+status messages
+.Po
+.Cm
+status
+.Pc
+.
+
+ <p>Configuration keywords are formed by concatenating the message class with
+the event class.
+The
+.Cm
+all
+prefix can be used instead of a message class.
+A
+message class may also be followed by the
+.Cm
+all
+keyword to enable/disable all
+messages of the respective message class.Thus, a minimal log configuration
+could look like this:
+.Bd
+-literal
+logconfig =syncstatus +sysevents
+.Ed
+
+ <p>This would just list the synchronizations state of
+<code>ntpd(1ntpdmdoc)</code>
+and the major system events.
+For a simple reference server, the
+following minimum message configuration could be useful:
+.Bd
+-literal
+logconfig =syncall +clockall
+.Ed
+
+ <p>This configuration will list all clock information and
+synchronization information.
+All other events and messages about
+peers, system events and so on is suppressed.
+.It
+Ic
+logfile
+Ar
+logfile
+This command specifies the location of an alternate log file to
+be used instead of the default system
+<code>syslog(3)</code>
+facility.
+This is the same operation as the -l command line option.
+.It
+Ic
+setvar
+Ar
+variable
+Op
+Cm
+default
+This command adds an additional system variable.
+These
+variables can be used to distribute additional information such as
+the access policy.
+If the variable of the form
+.Sm
+off
+.Va
+name
+=
+Ar
+value
+.Sm
+on
+is followed by the
+.Cm
+default
+keyword, the
+variable will be listed as part of the default system variables
+.Po
+<code>ntpq(1ntpqmdoc)</code>
+.Ic
+rv
+command
+.Pc
+)
+.
+These additional variables serve
+informational purposes only.
+They are not related to the protocol
+other that they can be listed.
+The known protocol variables will
+always override any variables defined via the
+.Ic
+setvar
+mechanism.
+There are three special variables that contain the names
+of all variable of the same group.
+The
+.Va
+sys_var_list
+holds
+the names of all system variables.
+The
+.Va
+peer_var_list
+holds
+the names of all peer variables and the
+.Va
+clock_var_list
+holds the names of the reference clock variables.
+.It
+Xo
+Ic
+tinker
+.Oo
+.Cm
+allan
+Ar
+allan
+|
+.Cm
+dispersion
+Ar
+dispersion
+|
+.Cm
+freq
+Ar
+freq
+|
+.Cm
+huffpuff
+Ar
+huffpuff
+|
+.Cm
+panic
+Ar
+panic
+|
+.Cm
+step
+Ar
+srep
+|
+.Cm
+stepout
+Ar
+stepout
+.Oc
+.Xc
+This command can be used to alter several system variables in
+very exceptional circumstances.
+It should occur in the
+configuration file before any other configuration options.
+The
+default values of these variables have been carefully optimized for
+a wide range of network speeds and reliability expectations.
+In
+general, they interact in intricate ways that are hard to predict
+and some combinations can result in some very nasty behavior.
+Very
+rarely is it necessary to change the default values; but, some
+folks cannot resist twisting the knobs anyway and this command is
+for them.
+Emphasis added: twisters are on their own and can expect
+no help from the support group.
+
+ <p>The variables operate as follows:
+ <dl>
+<dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument becomes the new value for the minimum Allan
+intercept, which is a parameter of the PLL/FLL clock discipline
+algorithm.
+The value in log2 seconds defaults to 7 (1024 s), which is also the lower
+limit.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument becomes the new value for the dispersion increase rate,
+normally .000015 s/s.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument becomes the initial value of the frequency offset in
+parts-per-million.
+This overrides the value in the frequency file, if
+present, and avoids the initial training state if it is not.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument becomes the new value for the experimental
+huff-n'-puff filter span, which determines the most recent interval
+the algorithm will search for a minimum delay.
+The lower limit is
+900 s (15 m), but a more reasonable value is 7200 (2 hours).
+There
+is no default, since the filter is not enabled unless this command
+is given.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument is the panic threshold, normally 1000 s.
+If set to zero,
+the panic sanity check is disabled and a clock offset of any value will
+be accepted.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument is the step threshold, which by default is 0.128 s.
+It can
+be set to any positive number in seconds.
+If set to zero, step
+adjustments will never occur.
+Note: The kernel time discipline is
+disabled if the step threshold is set to zero or greater than the
+default.
+<br><dt>‘<samp><span class="samp">Cm</span></samp>’<dd>The argument is the stepout timeout, which by default is 900 s.
+It can
+be set to any positive number in seconds.
+If set to zero, the stepout
+pulses will not be suppressed.
+
+ <p>.It
+Xo
+Ic
+trap
+Ar
+host_address
+.Op
+Cm
+port
+Ar
+port_number
+.Op
+Cm
+interface
+Ar
+interface_address
+.Xc
+This command configures a trap receiver at the given host
+address and port number for sending messages with the specified
+local interface address.
+If the port number is unspecified, a value
+of 18447 is used.
+If the interface address is not specified, the
+message is sent with a source address of the local interface the
+message is sent through.
+Note that on a multihomed host the
+interface used may vary from time to time with routing changes.
+
+ <p>The trap receiver will generally log event messages and other
+information from the server in a log file.
+While such monitor
+programs may also request their own trap dynamically, configuring a
+trap receiver will ensure that no messages are lost when the server
+is started.
+.It
+Cm
+hop
+Ar
+...
+This command specifies a list of TTL values in increasing order, up to 8
+values can be specified.
+In manycast mode these values are used in turn in
+an expanding-ring search.
+The default is eight multiples of 32 starting at
+31.
+
+ <p>This section was generated by <strong>AutoGen</strong>,
+using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program.
+This software is released under the NTP license, <http://ntp.org/license>.
+
+ <ul class="menu">
+<li><a accesskey="1" href="#ntp_002econf-usage">ntp.conf usage</a>: ntp.conf help/usage (<samp><span class="option">--help</span></samp>)
+<li><a accesskey="2" href="#ntp_002econf-config">ntp.conf config</a>: presetting/configuring ntp.conf
+<li><a accesskey="3" href="#ntp_002econf-exit-status">ntp.conf exit status</a>: exit status
+<li><a accesskey="4" href="#ntp_002econf-Files">ntp.conf Files</a>: Files
+<li><a accesskey="5" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also
+<li><a accesskey="6" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs
+<li><a accesskey="7" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes
+</ul>
+
+<div class="node">
+<a name="ntp.conf-usage"></a>
+<a name="ntp_002econf-usage"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-config">ntp.conf config</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf help/usage (<samp><span class="option">--help</span></samp>)</h4>
+
+ <p><a name="index-ntp_002econf-help-3"></a>
+This is the automatically generated usage text for ntp.conf.
+
+ <p>The text printed is the same whether selected with the <code>help</code> option
+(<samp><span class="option">--help</span></samp>) or the <code>more-help</code> option (<samp><span class="option">--more-help</span></samp>). <code>more-help</code> will print
+the usage text by passing it through a pager program.
+<code>more-help</code> is disabled on platforms without a working
+<code>fork(2)</code> function. The <code>PAGER</code> environment variable is
+used to select the program, defaulting to <samp><span class="file">more</span></samp>. Both will exit
+with a status code of 0.
+
+ <pre class="example"> ntp.conf is unavailable - no --help
+</pre>
+ <div class="node">
+<a name="ntp.conf-config"></a>
+<a name="ntp_002econf-config"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-exit-status">ntp.conf exit status</a>,
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-usage">ntp.conf usage</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">presetting/configuring ntp.conf</h4>
+
+ <p>Any option that is not marked as <i>not presettable</i> may be preset by
+loading values from environment variables named <code>NTP.CONF</code> and <code>NTP.CONF_<OPTION_NAME></code>. <code><OPTION_NAME></code> must be one of
+the options listed above in upper case and segmented with underscores.
+The <code>NTP.CONF</code> variable will be tokenized and parsed like
+the command line. The remaining variables are tested for existence and their
+values are treated like option arguments.
+
+ <p>The command line options relating to configuration and/or usage help are:
+
+<h5 class="subsubheading">version</h5>
+
+ <p>Print the program version to standard out, optionally with licensing
+information, then exit 0. The optional argument specifies how much licensing
+detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the
+first letter of the argument is examined:
+
+ <dl>
+<dt>‘<samp><span class="samp">version</span></samp>’<dd>Only print the version. This is the default.
+<br><dt>‘<samp><span class="samp">copyright</span></samp>’<dd>Name the copyright usage licensing terms.
+<br><dt>‘<samp><span class="samp">verbose</span></samp>’<dd>Print the full copyright usage licensing terms.
+</dl>
+
+<div class="node">
+<a name="ntp.conf-exit-status"></a>
+<a name="ntp_002econf-exit-status"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-Files">ntp.conf Files</a>,
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-config">ntp.conf config</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf exit status</h4>
+
+ <p>One of the following exit values will be returned:
+ <dl>
+<dt>‘<samp><span class="samp">0 (EXIT_SUCCESS)</span></samp>’<dd>Successful program execution.
+<br><dt>‘<samp><span class="samp">1 (EXIT_FAILURE)</span></samp>’<dd>The operation failed or the command syntax was not valid.
+</dl>
+ <div class="node">
+<a name="ntp.conf-Files"></a>
+<a name="ntp_002econf-Files"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-See-Also">ntp.conf See Also</a>,
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-exit-status">ntp.conf exit status</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf Files</h4>
+
+ <dl>
+<dt>‘<samp><span class="samp">Pa</span></samp>’<dd>the default name of the configuration file
+<br><dt>‘<samp><span class="samp">Pa</span></samp>’<dd>private MD5 keys
+<br><dt>‘<samp><span class="samp">Pa</span></samp>’<dd>RSA private key
+<br><dt>‘<samp><span class="samp">Pa</span></samp>’<dd>RSA public key
+<br><dt>‘<samp><span class="samp">Pa</span></samp>’<dd>Diffie-Hellman agreement parameters
+
+<div class="node">
+<a name="ntp.conf-See-Also"></a>
+<a name="ntp_002econf-See-Also"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>,
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-Files">ntp.conf Files</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf See Also</h4>
+
+ <p>.Sh
+SEE
+ALSO
+<code>ntpd(1ntpdmdoc)</code>,
+<code>ntpdc(1ntpdcmdoc)</code>,
+<code>ntpq(1ntpqmdoc)</code>
+
+ <p>In addition to the manual pages provided,
+comprehensive documentation is available on the world wide web
+at
+.Li
+http://www.ntp.org/
+.
+A snapshot of this documentation is available in HTML format in
+.Pa
+/usr/share/doc/ntp
+.
+.Rs
+.%A
+David
+L.
+Mills
+.%T
+Network
+Time
+Protocol
+(Version
+4)
+.%O
+RFC5905
+.Re
+<div class="node">
+<a name="ntp.conf-Bugs"></a>
+<a name="ntp_002econf-Bugs"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002econf-Notes">ntp.conf Notes</a>,
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-See-Also">ntp.conf See Also</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf Bugs</h4>
+
+ <p>The syntax checking is not picky; some combinations of
+ridiculous and even hilarious options and modes may not be
+detected.
+
+ <p>The
+.Pa
+ntpkey_
+Ns
+Ar
+host
+files are really digital
+certificates.
+These should be obtained via secure directory
+services when they become universally available.
+<div class="node">
+<a name="ntp.conf-Notes"></a>
+<a name="ntp_002econf-Notes"></a>
+<p><hr>
+Previous: <a rel="previous" accesskey="p" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>,
+Up: <a rel="up" accesskey="u" href="#ntp_002econf-Invocation">ntp.conf Invocation</a>
+
+</div>
+
+<h4 class="subsection">ntp.conf Notes</h4>
+
+ <p>This document is derived from FreeBSD.
+
+</body></html>
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ntp.conf.info
+@settitle NTP Configuration File User's Manual
+@include sntp/include/version.texi
+@paragraphindent 2
+@c %**end of header
+
+@ifinfo
+This file documents the use of the NTP Project's NTP configuration file.
+@end ifinfo
+
+@direntry
+* ntp.conf: (ntp.conf). NTP's configuration file
+@end direntry
+
+@titlepage
+@title NTP's Configuration File User's Manual
+@subtitle ntp.conf, version @value{VERSION}, @value{UPDATED}
+@c @author Max @email{foo@ntp.org}
+@end titlepage
+
+@c @page
+@c @vskip 0pt plus 1filll
+
+@node Top, ntp.conf Description, (dir), (dir)
+@top NTP's Configuration File User Manual
+
+This document describes the configuration file for the NTP Project's
+@code{ntpd} program.
+
+This document applies to version @value{VERSION} of @code{ntp.conf}.
+
+@shortcontents
+
+@menu
+* ntp.conf Description:: Description
+* sntp Invocation:: Invoking sntp
+@end menu
+
+@node ntp.conf Description
+@comment node-name, next, previous, up
+@section Description
+
+The behavior of @code{ntpd} can be changed by a configuration file,
+by default @code{ntp.conf}.
+
+@include invoke-ntp.conf.texi
// to be ntp.keys - the latter is also how autogen produces the output
// file name.
prog-name = "ntp.keys";
-prog-title = "NTP key file format";
+file-path = "/etc/ntp.keys";
+prog-title = "NTP symmetric key file format";
/* explain: Additional information whenever the usage routine is invoked */
explain = <<- _END_EXPLAIN
ds-type = 'DESCRIPTION';
ds-format = 'mdoc';
ds-text = <<- _END_PROG_MDOC_DESCRIP
-This document describes the format of an NTP key file.
+This document describes the format of an NTP symmetric key file.
For a description of the use of this type of file, see the
.Qq Authentication Support
section of the
.Xr ntp.conf 5
page.
.Pp
-In the case of DES, the keys are 56 bits long with,
-depending on type, a parity check on each byte.
-In the case of MD5, the keys are 64 bits (8 bytes).
.Xr ntpd 8
reads its keys from a file specified using the
.Fl k
While key number 0 is fixed by the NTP standard
(as 56 zero bits)
and may not be changed,
-one or more of the keys numbered 1 through 15
+one or more keys numbered between 1 and 65534
may be arbitrarily set in the keys file.
.Pp
The key file uses the same comment conventions
.Pp
where
.Ar keyno
-is a positive integer,
+is a positive integer (between 1 and 65534),
.Ar type
-is a single character which defines the key format,
+is the message digest algorithm,
and
.Ar key
is the key itself.
.Pp
The
.Ar key
-may be given in one of four different formats,
+may be given in a format
controlled by the
.Ar type
-character.
-The four key types, and corresponding formats,
-are listed following.
-.Bl -tag -width X
-.It Li S
-The key is a 64-bit hexadecimal number in the format
-specified in the DES specification;
-that is, the high order seven bits of each octet are used
-to form the 56-bit key
-while the low order bit of each octet is given a value
-such that odd parity is maintained for the octet.
-Leading zeroes must be specified
-(i.e., the key must be exactly 16 hex digits long)
-and odd parity must be maintained.
-Hence a zero key, in standard format, would be given as
-.Ql 0101010101010101 .
-.It Li N
-The key is a 64-bit hexadecimal number in the format
-specified in the NTP standard.
-This is the same as the DES format,
-except the bits in each octet have been rotated one bit right
-so that the parity bit is now the high order bit of the octet.
-Leading zeroes must be specified and odd parity must be maintained.
-A zero key in NTP format would be specified as
-.Ql 8080808080808080 .
-.It Li A
-The key is a 1-to-8 character ASCII string.
-A key is formed from this by using the low order 7 bits
-of each ASCII character in the string,
-with zeroes added on the right
-when necessary to form a full width 56-bit key,
-in the same way that encryption keys are formed from
-.Ux
-passwords.
-.It Li M
-The key is a 1-to-8 character ASCII string,
-using the MD5 authentication scheme.
-Note that both the keys and the authentication schemes (DES or MD5)
-must be identical between a set of peers sharing the same key number.
+field.
+The
+.Ar type
+.Li MD5
+is always supported.
+If
+.Li ntpd
+was built with the OpenSSL library
+then any digest library supported by that library may be specified.
+However, if compliance with FIPS 140-2 is required the
+.Ar type
+must be either
+.Li SHA
+or
+.Li SHA1 .
+.Pp
+What follows are some key types, and corresponding formats:
+.Pp
+.Bl -tag -width RMD160 -compact
+.It Li MD5
+The key is 1 to 16 printable characters terminated by
+an EOL,
+whitespace,
+or
+a
+.Li #
+(which is the "start of comment" character).
+.Pp
+.It Li SHA
+.It Li SHA1
+.It Li RMD160
+The key is a hex-encoded ASCII string of 40 characters,
+which is truncated as necessary.
.El
.Pp
Note that the keys used by the
--- /dev/null
+<html lang="en">
+<head>
+<title>NTP Symmetric Key</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="NTP Symmetric Key">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="top" href="#Top">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+ pre.display { font-family:inherit }
+ pre.format { font-family:inherit }
+ pre.smalldisplay { font-family:inherit; font-size:smaller }
+ pre.smallformat { font-family:inherit; font-size:smaller }
+ pre.smallexample { font-size:smaller }
+ pre.smalllisp { font-size:smaller }
+ span.sc { font-variant:small-caps }
+ span.roman { font-family:serif; font-weight:normal; }
+ span.sansserif { font-family:sans-serif; font-weight:normal; }
+--></style>
+</head>
+<body>
+<h1 class="settitle">NTP Symmetric Key</h1>
+<div class="node">
+<a name="Top"></a>
+<p><hr>
+Next: <a rel="next" accesskey="n" href="#ntp_002ekeys-Description">ntp.keys Description</a>,
+Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>,
+Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
+
+</div>
+
+<h2 class="unnumbered">NTP's Symmetric Key File User Manual</h2>
+
+<p>This document describes the symmetric key file for the NTP Project's
+<code>ntpd</code> program.
+
+ <p>This document applies to version {No value for `VERSION'} of <code>ntp.keys</code>.
+
+ <div class="shortcontents">
+<h2>Short Contents</h2>
+<ul>
+<a href="#Top">NTP's Symmetric Key File User Manual</a>
+</ul>
+</div>
+
+<ul class="menu">
+<li><a accesskey="1" href="#ntp_002ekeys-Description">ntp.keys Description</a>: Description
+<li><a accesskey="2" href="#ntp_002ekeys-Invocation">ntp.keys Invocation</a>: Invoking sntp
+</ul>
+
+<div class="node">
+<a name="ntp.keys-Description"></a>
+<a name="ntp_002ekeys-Description"></a>
+<p><hr>
+
+
+</div>
+
+<!-- node-name, next, previous, up -->
+<h3 class="section">Description</h3>
+
+<p>The name and location of the symmetric key file for <code>ntpd</code> can
+be specified in a configuration file, by default <code>/etc/ntp.keys</code>.
+
+</body></html>
+
--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename ntp.keys.info
+@settitle NTP Symmetric Key
+@include sntp/include/version.texi
+@paragraphindent 2
+@c %**end of header
+
+@ifinfo
+This file documents the NTP Project's NTP Symmetric Key file.
+@end ifinfo
+
+@direntry
+* ntp.keys: (ntp.keys). NTP's Symmetric Key file
+@end direntry
+
+@titlepage
+@title NTP's Symmetric Key File User's Manual
+@subtitle ntp.keys, version @value{VERSION}, @value{UPDATED}
+@c @author Max @email{foo@ntp.org}
+@end titlepage
+
+@c @page
+@c @vskip 0pt plus 1filll
+
+@node Top, ntp.keys Description, (dir), (dir)
+@top NTP's Symmetric Key File User Manual
+
+This document describes the symmetric key file for the NTP Project's
+@code{ntpd} program.
+
+This document applies to version @value{VERSION} of @code{ntp.keys}.
+
+@shortcontents
+
+@menu
+* ntp.keys Description:: Description
+* ntp.keys Invocation:: Invoking sntp
+@end menu
+
+@node ntp.keys Description
+@comment node-name, next, previous, up
+@section Description
+
+The name and location of the symmetric key file for @code{ntpd} can
+be specified in a configuration file, by default @code{/etc/ntp.keys}.
+
+@include invoke-ntp.keys.texi
--- /dev/null
+[+: -*- Mode: nroff -*-
+
+ AutoGen5 template man
+
+## agman-file.tpl -- Template for file man pages
+##
+## Time-stamp: "2011-11-18 07:48:17 bkorb"
+##
+## This file is part of AutoOpts, a companion to AutoGen.
+## AutoOpts is free software.
+## Copyright (c) 1992-2012 Bruce Korb - all rights reserved
+##
+## AutoOpts is available under any one of two licenses. The license
+## in use must be one of these two and the choice is under the control
+## of the user of the license.
+##
+## The GNU Lesser General Public License, version 3 or later
+## See the files "COPYING.lgplv3" and "COPYING.gplv3"
+##
+## The Modified Berkeley Software Distribution License
+## See the file "COPYING.mbsd"
+##
+## These files have the following md5sums:
+##
+## 43b91e8ca915626ed3818ffb1b71248b COPYING.gplv3
+## 06a1a2e4760c90ea5e1dad8dfaac4d39 COPYING.lgplv3
+## 66a5cedaf62c4b2637025f049f9b826f COPYING.mbsd
+
+# Produce a man page for section 1, 5 or 8 commands.
+# Which is selected via: -DMAN_SECTION=n
+# passed to the autogen invocation. "n" may have a suffix, if desired.
+#
+:+][+:
+
+(define head-line (lambda()
+ (sprintf ".TH %s %s \"%s\" \"%s\" \"%s\"\n.\\\"\n"
+ (get "prog-name") man-sect
+ (shell "date '+%d %b %Y'") package-text section-name) ))
+
+(define man-page #t)
+
+:+][+:
+
+INCLUDE "cmd-doc.tlib"
+
+:+]
+.\"
+.SH NAME
+[+: prog-name :+] \- [+: prog-title :+]
+[+:
+
+(out-push-new) :+][+:
+
+INVOKE build-doc :+][+:
+
+ (shell (string-append
+ "fn='" (find-file "mdoc2man") "'\n"
+ "test -f ${fn} || die mdoc2man not found from $PWD\n"
+ "${fn} <<\\_EndOfMdoc_ || die ${fn} failed in $PWD\n"
+ (out-pop #t)
+ "\n_EndOfMdoc_" ))
+
+:+][+:
+
+(out-move (string-append (get "prog-name") "."
+ man-sect)) :+][+: #
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" S Y N O P S I S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-synopsis :+][+:
+ (out-push-new file-name) \:+]
+.SH SYNOPSIS
+.B [+: file-path :+]
+.PP [+:
+
+(if (exist? "explain")
+ (string-append "\n.PP\n"
+ (join "\n.PP\n" (stack "explain"))) ) :+][+:
+
+(out-pop) :+][+:
+
+ENDDEF mk-synopsis
+
+agman-file.tpl ends here :+]
--- /dev/null
+[+: -*- Mode: nroff -*-
+
+ AutoGen5 template mdoc
+
+## agman-file.tpl -- Template for file mdoc pages
+##
+## Time-stamp: "2011-11-18 07:48:29 bkorb"
+##
+## This file is part of AutoOpts, a companion to AutoGen.
+## AutoOpts is free software.
+## AutoOpts is Copyright (c) 1992-2012 by Bruce Korb - all rights reserved
+##
+## AutoOpts is available under any one of two licenses. The license
+## in use must be one of these two and the choice is under the control
+## of the user of the license.
+##
+## The GNU Lesser General Public License, version 3 or later
+## See the files "COPYING.lgplv3" and "COPYING.gplv3"
+##
+## The Modified Berkeley Software Distribution License
+## See the file "COPYING.mbsd"
+##
+## These files have the following md5sums:
+##
+## 43b91e8ca915626ed3818ffb1b71248b COPYING.gplv3
+## 06a1a2e4760c90ea5e1dad8dfaac4d39 COPYING.lgplv3
+## 66a5cedaf62c4b2637025f049f9b826f COPYING.mbsd
+
+# Produce a man page for section 1, 5 or 8 commands.
+# Which is selected via: -DMAN_SECTION=n
+# passed to the autogen invocation. "n" may have a suffix, if desired.
+#
+:+][+:
+
+(define head-line (lambda() (string-append
+ ".Dd " (shell "date '+%B %e %Y' | sed 's/ */ /g'")
+ "\n.Dt " UP-PROG-NAME " " man-sect " " section-name
+ "\n.Os " (shell "uname -sr") "\n") ))
+
+(define man-page #f)
+
+:+][+:
+
+INCLUDE "cmd-doc.tlib"
+
+:+]
+.Sh NAME
+.Nm [+: prog-name :+]
+.Nd [+: prog-title :+]
+[+: INVOKE build-doc :+][+:
+
+(out-move (string-append (get "prog-name") "."
+ man-sect)) :+][+:#
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" S Y N O P S I S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-synopsis :+][+:
+ (out-push-new file-name) \:+]
+.Sh SYNOPSIS
+.Sy [+: file-path :+]
+.Pp [+:
+
+FOR explain "\n.Pp\n" :+][+:
+ explain :+][+:
+ENDFOR :+][+:
+
+(out-pop) :+][+:
+
+ENDDEF mk-synopsis
+
+agmdoc-file.tpl ends here :+]
--- /dev/null
+[+: -*- Mode: nroff -*-
+
+ AutoGen5 template man
+
+# cmd-doc.tlib -- Template for command line man/mdoc pages
+#
+# Time-stamp: "2012-05-12 20:52:33 bkorb"
+#
+# This file is part of AutoOpts, a companion to AutoGen.
+# AutoOpts is free software.
+# Copyright (c) 1992-2012 Bruce Korb - all rights reserved
+#
+# AutoOpts is available under any one of two licenses. The license
+# in use must be one of these two and the choice is under the control
+# of the user of the license.
+#
+# The GNU Lesser General Public License, version 3 or later
+# See the files "COPYING.lgplv3" and "COPYING.gplv3"
+#
+# The Modified Berkeley Software Distribution License
+# See the file "COPYING.mbsd"
+#
+# These files have the following md5sums:
+#
+# 43b91e8ca915626ed3818ffb1b71248b COPYING.gplv3
+# 06a1a2e4760c90ea5e1dad8dfaac4d39 COPYING.lgplv3
+# 66a5cedaf62c4b2637025f049f9b826f COPYING.mbsd
+
+# Produce a man page for section 1, 5, 6 or 8 commands. Which is
+# selected via: -DMAN_SECTION=n. "n" may have a suffix, if desired.
+# These sections have default section names that may be overridden
+# with -DSECTIN_NAME=XX, also passed to the autogen invocation.
+#
+:+][+:
+
+
+ (shell "CLexe=${AGexe%/autogen}/columns")
+
+
+(define down-prog-name (string-downcase! (get "prog-name")))
+(define UP-PROG-NAME (get-up-name "prog-name"))
+
+(define tmp-val (getenv "MAN_SECTION"))
+(define man-sect (if (exist? "cmd-section") (get "cmd-section") "1"))
+(define file-name "")
+(define sect-name "")
+(define macro-name "")
+(define tmp-str "")
+(define fname-line "")
+(define use-flags (exist? "flag.value"))
+(define named-mode (not (or use-flags (exist? "long-opts") )))
+
+(if (defined? 'tmp-val)
+ (if (string? tmp-val)
+ (set! man-sect tmp-val)))
+
+(define section-name
+ (if (=* man-sect "1") "User Commands"
+ (if (=* man-sect "5") "File Formats"
+ (if (=* man-sect "6") "Games"
+ (if (=* man-sect "8") "System Management"
+ (error
+ "the agman-cmd template only produces section 1, 5, 6 and 8 man pages")
+)))))
+(set! tmp-val (getenv "SECTION_NAME"))
+(if (defined? 'tmp-val) (if (string? tmp-val)
+ (set! section-name tmp-val) ))
+
+(define package-text "")
+(define package+version (and (exist? "package") (exist? "version")))
+
+(if (or (exist? "package") (exist? "version")) (begin
+ (set! package-text (string-append
+ (get "package")
+ (if package+version " (" "")
+ (get "version")
+ (if package+version ")" "") ))
+) )
+
+(define name-to-fname (lambda (nm)
+ (string-tr (string-downcase nm) " " "-") ))
+
+(define sect-line-fname (lambda () (begin
+ (out-push-new file-name)
+ (emit (string-append ".Sh \"" sect-name "\"\n"))
+ (string-append "mk-" macro-name) )))
+
+(make-tmp-dir)
+
+(define home-rc-files (exist? "homerc"))
+(define home-rc-text
+ "\nSee \\fBOPTION PRESETS\\fP for configuration files.")
+
+(if (=* man-sect "5") (set! home-rc-files #f))
+(if (=* man-sect "5") (set! home-rc-text ""))
+
+(define environ-init (exist? "environrc"))
+(define environ-text
+ "\nSee \\fBOPTION PRESETS\\fP for configuration environment variables.")
+
+(set! tmp-str (find-file (if man-page "texi2man" "texi2mdoc")))
+(if (not (defined? 'tmp-str))
+ (error (string-append "cannot locate "
+ (if man-page "texi2man" "texi2mdoc"))))
+(shell (string-append "cvt_prog='" tmp-str
+ "'\ntest -x \"$cvt_prog\" || die 'no conversion program'" ))
+
+(define get-cvt (lambda (nm alt-txt)
+ (shell (string-append
+ "{\n${cvt_prog} || die ${cvt_prog} failed in $PWD\n"
+ "} <<\\_EndOfTexiSection_\n"
+ (get nm alt-txt)
+ "\n_EndOfTexiSection_"
+ ))
+))
+
+(emit (head-line))
+(dne ".\\\" ") :+][+:
+
+INCLUDE "tpl-config.tlib" :+][+:#
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" B U I L D D O C
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE build-doc :+][+:
+
+INVOKE doc-sections :+][+:
+INVOKE ao-sections :+][+:
+
+(out-push-new (string-append tmp-dir "/.assemble")) \:+]
+
+cat_n_rm() {
+ test -f ${tmp_dir}/$1 || return 0
+ [+:(. egrep-prog):+] -v '^[ ]*$' ${tmp_dir}/$1
+ rm -f ${tmp_dir}/$1
+}
+
+#.\" Insert these sections first, in the prescribed order
+#
+for f in synopsis description options option-presets
+do cat_n_rm $f ; done
+test -f ${tmp_dir}/name && rm -f ${tmp_dir}/name
+
+#.\" These sections go last, in the prescribed order
+#
+for f in implementation-notes environment files examples exit-status errors \
+ compatibility see-also conforming-to history authors copyright bugs notes
+do cat_n_rm $f ; done > ${tmp_dir}/.fini
+
+#.\" Insert the contents of all remaining files in alphabetic order,
+#.\" except remove any blank lines.
+#
+set XX ${tmp_dir}/* ; shift
+test -f "$1" && cat $* | [+:(. egrep-prog):+] -v '^[ ]*$'
+
+#.\" Now insert the sections we squirreled away for the end.
+#
+cat ${tmp_dir}/.fini
+[+: (out-pop)
+ (shell ". ${tmp_dir}/.assemble") :+][+:
+
+ENDDEF build-doc
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" D O C S E C T I O N S
+.\"
+.\" Emit the files for each section that was provided.
+.\"
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE doc-sections :+][+:
+
+FOR doc-section :+][+:
+
+ CASE
+ (define sec-type (string-upcase (get "ds-type")))
+ (define sec-name (name-to-fname sec-type))
+ (out-push-new (string-append tmp-dir "/" sec-name))
+ (define cvt-fn (find-file (string-append
+ (get "ds-format" "man") "2mdoc")))
+ (if (not (defined? 'cvt-fn))
+ (error (sprintf "Cannot locate converter for %s"
+ (get "ds-format" "man"))))
+ sec-type :+][+:
+ == "" :+][+: (error "unnamed doc-section") :+][+:
+ *==* " " :+].Sh "[+: (. sec-type) :+]"[+:
+ * :+].Sh [+: (. sec-type) :+][+:
+ ESAC :+]
+[+:
+ (shell (string-append
+ "fn='" cvt-fn "'\n"
+ "test -f ${fn} || die ${fn} not found from $PWD\n"
+ "${fn} <<\\_EndOfDocSection_ || die ${fn} failed in $PWD\n"
+ (get "ds-text")
+ "\n_EndOfDocSection_"
+ )) :+][+:
+
+ CASE (. sec-type) :+][+:
+ == FILES :+][+:
+ (if home-rc-files (emit home-rc-text))
+ (set! home-rc-files #f) :+][+:
+
+ == ENVIRONMENT :+][+:
+ (if environ-init (emit environ-text))
+ (set! environ-init #f) :+][+:
+ ESAC :+][+:
+
+ (out-pop)
+ :+][+:
+
+ENDFOR doc-section :+][+:
+
+ENDDEF doc-sections
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" A O S E C T I O N S
+.\"
+.\" Emit the files for the sections that these templates augment,
+.\" replace or conditionally replace
+.\"
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE ao-sections :+][+:
+
+IF (=* man-sect "5") :+][+:
+ELSE :+][+:
+ INVOKE cond-section sec = "OPTIONS" mode = "replace" :+][+:
+ENDIF :+][+:
+INVOKE cond-section sec = "SYNOPSIS" mode = "alt" :+][+:
+INVOKE cond-section sec = "DESCRIPTION" mode = "append" :+][+:
+IF (=* man-sect "5") :+][+:
+ELSE :+][+:
+ INVOKE cond-section sec = "EXIT STATUS" mode = "insert" :+][+:
+ENDIF :+][+:
+INVOKE cond-section sec = "AUTHORS" mode = "alt" :+][+:
+INVOKE cond-section sec = "BUGS" mode = "append" :+][+:
+INVOKE cond-section sec = "NOTES" mode = "append" :+][+:
+
+IF (exist? "copyright") :+][+:
+ INVOKE cond-section sec = "COPYRIGHT" mode = "alt" :+][+:
+ENDIF :+][+:
+
+IF (=* man-sect "5") :+][+:
+ INVOKE cond-section sec = "FILES" mode = "append" :+][+:
+ELIF (or home-rc-files environ-init) :+][+:
+ INVOKE cond-section sec = "OPTION PRESETS" mode = "replace" :+][+:
+
+ IF (. home-rc-files) :+][+:
+ INVOKE cond-section sec = "FILES" mode = "append" :+][+:
+ ENDIF :+][+:
+
+ IF (. environ-init) :+][+:
+ INVOKE cond-section sec = "ENVIRONMENT" mode = "append" :+][+:
+ ENDIF :+][+:
+
+ENDIF :+][+:
+
+ENDDEF ao-sections
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" C O N D I T I O N A L S E C T I O N
+.\"
+.\" Figure out what to do for AutoOpts required sections, depending on "mode"
+.\" In all cases, if the file does not exist, invoke the "mk" macro to create
+.\" a new file. If it does exist, then:
+.\"
+.\" alt Alternate -- emit no text
+.\" replace throw away any pre-existing file.
+.\" append invoke the "append" macro to emit additional text
+.\" insert save the current contents, replacing the .Sh line with .Pp.
+.\" invoke the "mk" macro then emit the saved text
+.\"
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE cond-section :+][+:
+
+ IF
+ (set! sect-name (string-upcase! (string-substitute
+ (get "sec") "-" " " )))
+ (set! macro-name (string-downcase! (string-substitute
+ sect-name " " "-" )))
+ (set! file-name (string-append tmp-dir "/" macro-name))
+
+ (not (access? file-name R_OK)) :+][+:
+
+ INVOKE (sect-line-fname) :+][+:
+ (out-pop) :+][+:
+
+ ELSE file exists :+][+:
+
+ CASE (get "mode") :+][+:
+
+ == replace :+][+:
+ INVOKE (sect-line-fname) :+][+:
+ (out-pop) :+][+:
+
+ == append :+][+:
+ (out-push-add file-name) :+][+:
+ INVOKE (string-append "append-" macro-name) :+][+:
+ (out-pop) :+][+:
+
+ == insert :+][+:
+ (set! fname-line (shellf "sed '1s/.Sh .*/.Pp/' %s" file-name)) :+][+:
+ INVOKE (sect-line-fname) :+][+:
+ (emit fname-line)
+ (out-pop) :+][+:
+
+ # * -- otherwise, do nothing :+][+:
+
+ ESAC :+][+:
+
+ ENDIF file existence/non-existence :+][+:
+ENDDEF cond-section
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - D E S C R I P T I O N
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-description :+][+:
+
+ (if (exist? "prog-man-descrip")
+ (stack-join "\n.Pp\n" "prog-man-descrip")
+ (if (exist? "detail")
+ (stack-join "\n.Pp\n" "detail")
+ "There is no description for this command."
+ ) ) :+]
+[+:
+ INVOKE append-description :+][+:
+
+ENDDEF mk-description
+
+.\" = = = = = APPEND TO IT: :+][+:
+
+DEFINE append-description :+][+:
+
+IF (= (get "main.main-type") "for-each"):+][+:
+
+ CASE main.handler-type :+][+:
+ ~* ^(name|file)|.*text \:+]
+.Pp
+This program will perform its function for every file named on the command
+line or every file named in a list read from stdin. The arguments or input
+names must be pre\-existing files. The input list may contain comments,
+which[+:
+
+ !E \:+]
+.Pp
+This program will perform its function for every command line argument
+or every non\-comment line in a list read from stdin.
+The input list comments[+:
+
+ * :+][+:
+ (error "the 'for-each' main has in invalid handler-type.") :+][+:
+ ESAC \:+]
+ are blank lines or lines beginning with a '[+:
+ ?% comment-char "%s" "#" :+]' character.
+[+:
+
+ENDIF - "main" exists :+][+:
+ENDDEF append-description
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - O P T I O N S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-options
+
+:+][+:
+
+(define opt-arg "")
+(define dis-name "")
+(define opt-name "")
+(define optname-from "A-Z_^")
+(define optname-to "a-z--")
+(define cvt-cmd "")
+(define formatted-doc (exist? "option-doc-format"))
+
+(if formatted-doc (begin
+ (out-push-new)
+ (set! cvt-cmd (string-append (get "option-doc-format") "2mdoc"))
+) )
+
+(if (exist? "preserve-case")
+ (begin
+ (set! optname-from "_^")
+ (set! optname-to "--")
+) )
+
+(define fix-optname (lambda (o_nm) (begin
+ (set! o_nm (string-tr o_nm optname-from optname-to))
+ (set! o_nm (string-substitute o_nm "-" "\\-" ))
+ o_nm )))
+
+(if (exist? "option-info")
+ (string-append ".Pp\n" (get "option-info") "\n") )
+\:+]
+.Bl -tag[+:
+
+FOR flag :+][+:
+ IF (not (exist? "documentation")) :+][+:
+ IF (exist? "aliases") :+][+:
+ INVOKE emit-alias-opt :+][+:
+ ELSE :+][+:
+ INVOKE emit-flag-text :+][+:
+ ENDIF :+][+:
+
+ ELSE :+]
+.Ss "[+: (get-cvt "descrip" "") :+]"[+:
+
+ IF (set! tmp-str (get-cvt "documentation" ""))
+ (> (string-length tmp-str) 3) :+]
+[+: (. tmp-str) :+]
+[+: ENDIF :+][+:
+
+ ENDIF :+][+:
+ENDFOR flag
+
+.\" = = = = = = = = = = = = = = = = =
+.\" help option
+.\" = = = = = = = = = = = = = = = = =
+
+:+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: (get "help-value" "?") :+][+:
+ (if (exist? "long-opts") " , \" \\-\\-help\"") :+][+:
+ ELSE :+][+:
+ (if (exist? "long-opts") "\\-\\-") :+]help[+:
+ ENDIF :+]
+Display usage information and exit.[+:#
+
+.\" = = = = = = = = = = = = = = = = =
+.\" more-help option
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+ IF (not (exist? "no-libopts")) :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% more-help-value "%s" "!" :+][+:
+ IF (exist? "long-opts") :+] , " \-\-more-help"[+: ENDIF :+][+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+: ENDIF :+]more-help[+:
+ ENDIF :+]
+Pass the extended usage information through a pager.[+:
+
+ENDIF no no-libopts
+
+.\" = = = = = = = = = = = = = = = = =
+.\" save and load configuration
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+IF (exist? "homerc") :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% save-opts-value "%s" ">"
+ :+] " [\fIrcfile\fP][+:
+ IF (exist? "long-opts") :+]," " \-\-save-opts" "[=\fIrcfile\fP][+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]save-opts "[=\fIrcfile\fP]"[+:
+ ENDIF :+]
+Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% load-opts-value "%s" "<"
+ :+] " \fIrcfile\fP[+:
+ IF (exist? "long-opts")
+ :+]," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts[+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]load-opts "=\fIrcfile\fP," " \-\-no-load-opts"[+:
+ ENDIF :+]
+Load options from \fIrcfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early,
+out of order.[+:
+ENDIF (exist? "homerc")
+
+.\" = = = = = = = = = = = = = = = = =
+.\" version
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+IF (exist? "version") :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% version-value "%s" "v"
+ :+] " [{\fIv|c|n\fP}][+:
+ IF (exist? "long-opts") :+]," " \-\-version" "[=\fI{v|c|n}\fP][+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]version "[=\fI{v|c|n}\fP]"[+:
+ ENDIF :+]
+Output version of program and exit. The default mode is `v', a simple
+version. The `c' mode will print copyright information and `n' will
+print the full copyright notice.[+:
+ENDIF :+]
+.El
+[+:
+
+(if formatted-doc
+ (shell (string-append
+ "fn='" (find-file cvt-cmd)
+ "'\ntest -f ${fn} || die '" cvt-cmd " not found'\n"
+ "${fn} <<\\_EndOfMdoc_ || die ${fn} failed in $PWD\n"
+ (out-pop #t)
+ "\n_EndOfMdoc_" )) ) :+][+:
+
+ENDDEF mk-options
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - O P T I O N - P R E S E T S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-option-presets \:+]
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from [+:
+ IF (. home-rc-files)
+ :+]configuration ("RC" or ".INI") file(s)[+:
+ IF (. environ-init) :+] and values from
+[+:
+ ENDIF :+][+:
+ ENDIF :+][+:
+ IF (. environ-init) :+]environment variables named:
+.nf
+ \fB[+: (. UP-PROG-NAME) :+]_<option-name>\fP or \fB[+: (. UP-PROG-NAME) :+]\fP
+.fi
+.ad[+:
+ IF (. home-rc-files) :+]
+The environmental presets take precedence (are processed later than)
+the configuration files.[+:
+ ENDIF :+][+:
+ ELSE :+].[+:
+ ENDIF :+][+:
+
+ CASE
+ (define rc-file
+ (get "rcfile" (string-append "." (get "prog-name") "rc")) )
+ (count "homerc") :+][+:
+
+ == "0" :+][+:
+ == "1" :+][+:
+
+ CASE homerc :+][+:
+ ~~ '\.|\$HOME' :+]
+The file "\fI[+: (string-append (get "homerc") "/" rc-file)
+:+]\fP" will be used, if present.[+:
+ * :+]
+The \fIhomerc\fP file is "\fI[+:homerc:+]\fP", unless that is a directory.
+In that case, the file "\fI[+: (. rc-file) :+]\fP"
+is searched for within that directory.[+:
+ ESAC :+][+:
+
+ * :+]
+The \fIhomerc\fP files are [+:
+ FOR homerc ", " :+][+:
+ IF (last-for?) :+]and [+:
+ ENDIF :+]"\fI[+: homerc :+]\fP"[+: ENDFOR :+].
+If any of these are directories, then the file \fI[+: (. rc-file) :+]\fP
+is searched for within those directories.[+:
+ ESAC :+][+:
+
+ENDDEF mk-option-presets
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - E X I T - S T A T U S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-exit-status \:+]
+One of the following exit values will be returned:
+.Bl -tag
+[+:
+(ag-fprintf 0 ".It 0 \" (EXIT_%s)\"\n%s\n"
+ (string->c-name! (string-upcase (get "exit-name[0]" "SUCCESS")))
+ (get-cvt "exit-desc[0]" "Successful program execution.") )
+
+(define need-ex-noinput (exist? "homerc"))
+(define need-ex-software #t)
+
+(ag-fprintf 0 ".It 1 \" (EXIT_%s)\"\n%s\n"
+ (string->c-name! (string-upcase (get "exit-name[1]" "FAILURE")))
+ (get-cvt "exit-desc[1]"
+ "The operation failed or the command syntax was not valid.")) :+][+:
+
+FOR exit-desc (for-from 2) :+][+:
+ (if (= (for-index) 66)
+ (set! need-ex-noinput #f)
+ (if (= (for-index) 70)
+ (set! need-ex-software #f) ))
+
+ (set! tmp-str (get (sprintf "exit-name[%d]" (for-index)) "* unnamed *"))
+ (sprintf ".It %d \" (EXIT_%s)\"\n%s\n"
+ (for-index)
+ (string-upcase (string->c-name! tmp-str))
+ (get-cvt "exit-desc" "")) :+][+:
+ENDFOR exit-desc :+][+:
+(if need-ex-noinput
+ (emit ".It 66 \" (EX_NOINPUT)\"
+A specified configuration file could not be loaded.\n"))
+
+(if need-ex-noinput
+ (emit ".It 70 \" (EX_SOFTWARE)\"
+libopts had an internal operational error. Please report
+it to autogen-users@lists.sourceforge.net. Thank you.\n"))
+
+(if (> (string-length fname-line) 1)
+ (emit fname-line)) :+]
+.El
+[+:
+
+ENDDEF exit-status
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - A U T H O R S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-authors :+][+:
+
+ (define remove-authors #t)
+
+ (set! tmp-val
+ (if (exist? "copyright.author")
+ (stack-join ",\n" "copyright.author")
+ (stack-join ",\n" "copyright.owner") ))
+
+ (if (> (string-length tmp-val) 1)
+ (string-append tmp-val "\n")
+ (delete-file file-name))
+
+ :+][+:
+
+ENDDEF mk-authors
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - B U G S
+.\"
+.\" This section is guaranteed to be the last section in the man page
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-bugs :+][+:
+
+ (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
+ (if (> (string-length tmp-val) 1)
+ (string-append "Please send bug reports to: " tmp-val "\n")
+ (delete-file file-name) )
+ :+][+:
+
+ENDDEF mk-bugs :+][+:
+
+DEFINE append-bugs :+][+:
+
+ (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
+ (if (> (string-length tmp-val) 1)
+ (string-append "Please send bug reports to: " tmp-val "\n") )
+ :+][+:
+
+ENDDEF append-bugs
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - C O P Y R I G H T (+ licensing)
+.\"
+.\" This section is guaranteed to be the last section in the man page
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-copyright \:+]
+Copyright (C) [+: copyright.date :+] [+:
+ (get "copyright.owner" (get "copyright.author" (get "copyright.eaddr")))
+ :+] all rights reserved.
+[+: CASE (get "copyright.type") :+][+:
+ = note :+][+: (get "copyright.text") :+][+:
+ == '' :+]This program has an unspecified license.[+:
+
+ * :+][+:
+ (string-append "This program is released under the terms of "
+ (license-name (get "copyright.type")) ".") :+][+:
+
+ ESAC :+]
+[+:
+ENDDEF mk-copyright
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - N O T E S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-notes \:+]
+This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
+option definitions.
+[+:
+
+ENDDEF mk-notes
+
+.\" = = = = = APPEND TO IT: :+][+:
+
+DEFINE append-notes \:+]
+
+.Pp
+This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
+option definitions.[+:
+
+ENDDEF append-notes
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - E N V I R O N M E N T
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-environment :+][+:
+ INVOKE append-environment :+][+:
+ENDDEF mk-environment
+
+.\" = = = = = APPEND TO IT: :+][+:
+
+DEFINE append-environment :+][+:
+ (. environ-text) :+][+:
+ENDDEF append-environment
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" M K - F I L E S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE mk-files :+][+:
+ INVOKE append-files :+][+:
+ENDDEF mk-files
+
+.\" = = = = = APPEND TO IT: :+][+:
+
+DEFINE append-files :+][+:
+ (. home-rc-text) :+][+:
+ENDDEF append-files
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E M I T A L I A S O P T
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE emit-alias-opt :+]
+.It [+:
+ IF (exist? "value") :+][+:
+ IF (exist? "long-opts") \:+]
+ \-[+:value:+] ", " -\-[+: name :+][+:
+ ELSE \:+]
+ \-[+:value:+][+:
+ ENDIF (exist? "long-opts") :+][+:
+
+ ELSE value does not exist -- named option only :+][+:
+
+ IF (not (exist? "long-opts")) \:+]
+ [+: name :+][+:
+ ELSE \:+]
+ \-\-[+: (. opt-name) :+][+:
+ ENDIF :+][+:
+ ENDIF :+]
+This is an alias for the [+: aliases :+] option.[+:
+ENDDEF emit-alias-opt
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E M I T F L A G T E X T
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE emit-flag-text :+][+:
+
+ (if (exist? "enable")
+ (set! opt-name (string-append (get "enable") "-" (get "name")))
+ (set! opt-name (get "name")) )
+ (if (exist? "disable")
+ (set! dis-name (string-append (get "disable") "-" (get "name")))
+ (set! dis-name "") )
+
+ (set! opt-name (fix-optname opt-name))
+ (if (> (string-length dis-name) 0)
+ (set! dis-name (fix-optname dis-name)) )
+
+ (if (not (exist? "arg-type"))
+ (set! opt-arg "")
+ (set! opt-arg (string-append "\\fI"
+ (fix-optname (if (exist? "arg-name")
+ (get "arg-name")
+ (string-downcase! (get "arg-type")) ))
+ "\\fP" ))
+ )
+
+:+]
+.It [+:
+ IF (exist? "value") :+][+:
+ IF (exist? "long-opts") :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option has a flag value (character) AND
+ * the program uses long options
+ *
+ \:+]
+ \-[+:value:+][+:
+ IF (not (exist? "arg-type")) :+] ", " -\-[+:
+ ELSE :+] " [+:(. opt-arg):+], " \-\-[+:
+ ENDIF :+][+: (. opt-name) :+][+:
+ IF (exist? "arg-type") :+][+:
+ ? arg-optional " [ =" ' "=" '
+ :+][+: (. opt-arg) :+][+:
+ arg-optional " ]" :+][+:
+ ENDIF :+][+:
+ IF (exist? "disable") :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+
+ ELSE :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option has a flag value (character) BUT
+ * the program does _NOT_ use long options
+ *
+ \:+]
+ \-[+:value:+][+:
+ IF (exist? "arg-type") :+][+:
+ arg-optional "[" :+] "[+:(. opt-arg):+][+:
+ arg-optional '"]"' :+][+:
+ ENDIF " :+][+:
+ ENDIF (exist? "long-opts") :+][+:
+
+
+ ELSE value does not exist -- named option only :+][+:
+
+ IF (not (exist? "long-opts")) :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option does not have a flag value (character).
+ * The program does _NOT_ use long options either.
+ * Special magic: All arguments are named options.
+ *
+ \:+]
+ [+: (. opt-name) :+][+:
+ IF (exist? "arg-type") :+] [+:
+ ? arg-optional " [ =" ' "=" '
+ :+][+:(. opt-arg) :+][+:
+ arg-optional "]" :+][+:
+ ENDIF:+][+:
+ IF (exist? "disable") :+], " \fB[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+
+
+ ELSE :+][+:
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option does not have a flag value (character).
+ * The program, instead, only accepts long options.
+ *
+ \:+]
+ \-\-[+: (. opt-name) :+][+:
+
+ IF (exist? "arg-type") :+] "[+: #" :+][+:
+ arg-optional "[" :+]=[+:(. opt-arg):+][+:
+ arg-optional "]" :+]"[+: #" :+][+:
+ ENDIF :+][+:
+
+ IF (exist? "disable")
+ :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+ ENDIF :+][+:
+ ENDIF :+]
+[+: (get-cvt "descrip" "") :+].[+:
+
+ IF (exist? "min") :+]
+This option is required to appear.[+:
+ ENDIF :+][+:
+
+ IF (exist? "max") :+]
+This option may appear [+:
+ IF % max (= "%s" "NOLIMIT")
+ :+]an unlimited number of times[+:ELSE
+ :+]up to [+: max :+] times[+:
+ ENDIF:+].[+:
+ ENDIF:+][+:
+
+ IF (exist? "disable") :+]
+The \fI[+:(. dis-name):+]\fP form will [+:
+ IF (exist? "stack-arg")
+ :+]clear the list of option arguments[+:
+ ELSE :+]disable the option[+:
+ ENDIF :+].[+:
+ ENDIF:+][+:
+
+ IF (exist? "enabled") :+]
+This option is enabled by default.[+:
+ ENDIF :+][+:
+
+ IF (exist? "no-preset") :+]
+This option may not be preset with environment variables
+or in initialization (rc) files.[+:
+ ENDIF :+][+:
+
+ IF (and (exist? "default") named-mode) :+]
+This option is the default option.[+:
+ ENDIF :+][+:
+
+ IF (exist? "equivalence") :+]
+This option is a member of the [+:equivalence:+] class of options.[+:
+ ENDIF :+][+:
+
+ IF (exist? "flags-must") :+]
+This option must appear in combination with the following options:
+[+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+:
+ ENDIF :+][+:
+
+ IF (exist? "flags-cant") :+]
+This option must not appear in combination with any of the following options:
+[+: FOR flags-cant ", " :+][+:flags-cant:+][+:ENDFOR:+].[+:
+ ENDIF :+][+:
+
+
+ IF (~* (get "arg-type") "key|set") :+]
+This option takes a keyword as its argument[+:
+
+ IF (=* (get "arg-type") "set")
+
+:+] list. Each entry turns on or off
+membership bits. The bits are set by name or numeric value and cleared
+by preceding the name or number with an exclamation character ('!').
+They can all be cleared with the magic name \fInone\fR and they can all be set
+with
+.IR all .
+A single option will process a list of these values.[+:
+
+ ELSE
+
+:+]. The argument sets an enumeration value that can
+be tested by comparing them against the option value macro.[+:
+
+ ENDIF
+
+:+]
+The available keywords are:
+.in +4
+.nf
+.na
+[+: (shellf "${CLexe} --indent='' --spread=1 -W50 <<_EOF_\n%s\n_EOF_"
+ (join "\n" (stack "keyword")) ) :+]
+.fi
+or their numeric equivalent.
+.in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+:
+
+ ELIF (=* (get "arg-type") "num") :+]
+This option takes an integer number as its argument.[+:
+
+ IF (exist? "arg-range") :+]
+The value of [+:(. opt-arg):+] is constrained to being:
+.in +4
+.nf
+.na[+:FOR arg_range ", or" :+]
+[+: (shellf "
+range='%s'
+
+case \"X${range}\" in
+X'->'?* )
+ echo \"less than or equal to\" `
+ echo $range | sed 's/->//' ` ;;
+
+X?*'->' )
+ echo \"greater than or equal to\" `
+ echo $range | sed 's/->.*//' ` ;;
+
+X?*'->'?* )
+ echo \"in the range \" `
+ echo $range | sed 's/->/ through /' ` ;;
+
+X?* )
+ echo exactly $range ;;
+
+X* ) echo $range is indeterminate
+esac"
+
+(get "arg-range") )
+:+][+:
+ ENDFOR arg-range :+]
+.fi
+.in -4[+:
+
+ ENDIF arg-range exists :+][+:
+
+ ENDIF arg-type key/set/num :+][+:
+
+ IF (exist? "arg-default") :+]
+The default [+: (. opt-arg) :+] for this option is:
+.ti +4
+ [+: (join " + " (stack "arg-default" )) :+][+:
+ ENDIF :+]
+.sp
+[+:
+ (if (exist? "doc")
+ (get-cvt "doc" "")
+ "This option has not been fully documented." ) :+][+:
+ IF (exist? "deprecated") :+]
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.R[+:
+ ENDIF :+][+:
+
+ENDDEF emit-flag-text
+
+.\" cmd-doc.tlib ends here \:+]
projects / thirdparty / ntp.git / commitdiff
