From: Harlan Stenn Date: Mon, 3 Dec 2012 02:51:53 +0000 (+0000) Subject: autogen doc cleanup X-Git-Tag: NTP_4_2_7P330~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a4bcc7140521dcf45e7045a723e81ea74a7cec3e;p=thirdparty%2Fntp.git autogen doc cleanup bk: 50bc13c9VPjmA7d27vp9CEh7UWOE8A --- diff --git a/.point-changed-filelist b/.point-changed-filelist index fbae6e9e0..540b613e8 100644 --- a/.point-changed-filelist +++ b/.point-changed-filelist @@ -1,11 +1,17 @@ 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 diff --git a/ChangeLog b/ChangeLog index 7e72c3739..e8b691e28 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* autogen doc cleanup (4.2.7p329) 2012/12/01 Released by Harlan Stenn * [Bug 2278] ACTS flag3 mismatch between code and driver18.html. * Use an enum for the ACTS state table. diff --git a/ntpd/Makefile.am b/ntpd/Makefile.am index e2ce293d0..280eb975f 100644 --- a/ntpd/Makefile.am +++ b/ntpd/Makefile.am @@ -29,7 +29,7 @@ CHECK_SAVECONFIG= 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 @@ -37,7 +37,7 @@ endif # 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 @@ -54,7 +54,7 @@ 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. # @@ -66,15 +66,15 @@ vphack_after: # 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) @@ -115,6 +115,10 @@ CLEANFILES = \ 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 \ @@ -123,11 +127,15 @@ EXTRA_DIST = \ 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 \ @@ -141,7 +149,17 @@ EXTRA_DIST = \ ### 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 \ @@ -153,13 +171,16 @@ noinst_DATA = \ $(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) @@ -178,7 +199,7 @@ ntpd_SOURCES = \ ntpd-opts.c \ ntpd-opts.h \ $(NULL) - + ntpdsim_SOURCES = \ $(ntpd_SOURCES) \ ntp_prio_q.c \ @@ -263,14 +284,14 @@ $(srcdir)/keyword-gen-utd: $(srcdir)/keyword-gen.c $(srcdir)/ntp_parser.h $(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 @@ -300,6 +321,26 @@ ntpd.$(NTPD_MS): $(srcdir)/ntpd.$(MANTAGFMT).in $(top_builddir)/config.status ### +$(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 @@ -325,7 +366,7 @@ ntp.conf.5: $(srcdir)/ntp.conf.$(MANTAGFMT).in $(top_builddir)/config.status ### $(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+ @@ -334,7 +375,7 @@ $(srcdir)/ntp.keys.man.in: $(srcdir)/ntp.keys.5man $(top_srcdir)/sntp/scripts/ma ### $(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+ @@ -350,7 +391,7 @@ ntp.keys.5: $(srcdir)/ntp.keys.$(MANTAGFMT).in $(top_builddir)/config.status $(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 $@ @@ -375,7 +416,7 @@ $(top_srcdir)/sntp/scm-rev: 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 diff --git a/ntpd/invoke-ntp.conf.menu b/ntpd/invoke-ntp.conf.menu new file mode 100644 index 000000000..dc43bf80f --- /dev/null +++ b/ntpd/invoke-ntp.conf.menu @@ -0,0 +1 @@ +* ntp.conf Invocation:: Invoking ntp.conf diff --git a/ntpd/invoke-ntp.conf.texi b/ntpd/invoke-ntp.conf.texi new file mode 100644 index 000000000..3231873c4 --- /dev/null +++ b/ntpd/invoke-ntp.conf.texi @@ -0,0 +1,3816 @@ +@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, . + +@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_}. @code{} 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. diff --git a/ntpd/invoke-ntp.keys.menu b/ntpd/invoke-ntp.keys.menu new file mode 100644 index 000000000..8f9c376de --- /dev/null +++ b/ntpd/invoke-ntp.keys.menu @@ -0,0 +1 @@ +* ntp.keys Invocation:: Invoking ntp.keys diff --git a/ntpd/invoke-ntp.keys.texi b/ntpd/invoke-ntp.keys.texi new file mode 100644 index 000000000..e370191db --- /dev/null +++ b/ntpd/invoke-ntp.keys.texi @@ -0,0 +1,208 @@ +@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, . + +@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_}. @code{} 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. diff --git a/ntpd/ntp.conf.html b/ntpd/ntp.conf.html new file mode 100644 index 000000000..943ed8beb --- /dev/null +++ b/ntpd/ntp.conf.html @@ -0,0 +1,3762 @@ + + +NTP Configuration File User's Manual + + + + + + + + + +

NTP Configuration File User's Manual

+
+ +

+Next: , +Previous: (dir), +Up: (dir) + +
+ +

NTP's Configuration File User Manual

+ +

This document describes the configuration file for the NTP Project's +ntpd program. + +

This document applies to version {No value for `VERSION'} of ntp.conf. + +

+

Short Contents

+ +
+ + + +
+ + +

+ + +
+ + +

Description

+ +

The behavior of ntpd can be changed by a configuration file, +by default ntp.conf. + +

+ + +

+ + +
+ +

Invoking ntp.conf

+ +

+ +

The +ntp.conf +configuration file is read at initial startup by the +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 +-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: +

    +
  • .Sx +Authentication +Support +
  • .Sx +Monitoring +Support +
  • .Sx +Access +Control +Support +
  • .Sx +Automatic +NTP +Configuration +Options +
  • .Sx +Reference +Clock +Support +
  • .Sx +Miscellaneous +Options +
+ +

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 +-4 qualifier preceding +the host name forces DNS resolution to the IPv4 namespace, +while a +-6 qualifier forces DNS resolution to the IPv6 namespace. +See IPv6 references for the +equivalent classes for that address family. +

+
‘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 +
‘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 +
‘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 +
‘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 + +

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 +) +. +

+
‘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. +
‘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. +
‘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. +
‘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. + +

Options: +

+
‘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 +. +
‘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. +
‘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 +ntpd(1ntpdmdoc) +is started with the +-q option. +
‘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. +
‘Cm’
‘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). +
‘Cm’
Marks the server as unused, except for display purposes. +The server is discarded by the selection algroithm. +
‘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. +
‘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. +
‘Cm’
Specifies the version number to be used for outgoing NTP +packets. +Versions 1-4 are the choices, with version 4 the +default. + +

.Ss +Auxiliary +Commands +

+
‘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 +. +
‘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 +. +
‘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 +. + +

.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 +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 +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +utility programs. + +

When +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 +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 +ntpdc(1ntpdcmdoc) +utility, while the +.Ic +controlkey +command selects the key used as the password for the +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 +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 +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 +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 +ntpq(1ntpqmdoc) +and +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 +

+
‘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. +
‘Ic’
Specifies the key identifier to use with the +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. +
‘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: +
+
‘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. +
‘Cm’
Specifies the location of the optional GQ parameters file. +This +overrides the link +.Pa +ntpkey_gq_ +Ns +Ar +hostname +in the keys directory. +
‘Cm’
Specifies the location of the required host key file. +This overrides +the link +.Pa +ntpkey_key_ +Ns +Ar +hostname +in the keys directory. +
‘Cm’
Specifies the location of the optional IFF parameters file.This +overrides the link +.Pa +ntpkey_iff_ +Ns +Ar +hostname +in the keys directory. +
‘Cm’
Specifies the location of the optional leapsecond file. +This overrides the link +.Pa +ntpkey_leap +in the keys directory. +
‘Cm’
Specifies the location of the optional MV parameters file. +This +overrides the link +.Pa +ntpkey_mv_ +Ns +Ar +hostname +in the keys directory. +
‘Cm’
Specifies the password to decrypt files containing private keys and +identity parameters. +This is required only if these files have been +encrypted. +
‘Cm’
Specifies the location of the random seed file used by the OpenSSL +library. +The defaults are described in the main text above. +
‘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. + +

.It +Ic +keys +Ar +keyfile +Specifies the complete path and location of the MD5 key file +containing the keys and key identifiers used by +ntpd(1ntpdmdoc), +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +when operating with symmetric key cryptography. +This is the same operation as the +-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 +ntpdc(1ntpdcmdoc) +utility program, which uses a +proprietary protocol specific to this implementation of +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 +ntpq(1ntpqmdoc) +and +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. + +

.Ss +Error +Codes +The following error codes are reported via the NTP control +and monitoring protocol trap mechanism. +

+
‘101’
.Pq +bad +field +format +or +length +The packet has invalid version, length or format. +
‘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. +
‘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. +
‘104’
.Pq +bad +or +missing +public +key +The public key is missing, has incorrect format or is an unsupported type. +
‘105’
.Pq +unsupported +digest +type +The server requires an unsupported digest/signature scheme. +
‘106’
.Pq +mismatched +digest +types +Not used. +
‘107’
.Pq +bad +signature +length +The signature length does not match the current public key. +
‘108’
.Pq +signature +not +verified +The message fails the signature check. +It could be bogus or signed by a +different private key. +
‘109’
.Pq +certificate +not +verified +The certificate is invalid or signed with the wrong key. +
‘110’
.Pq +certificate +not +verified +The certificate is not yet valid or has expired or the signature could not +be verified. +
‘111’
.Pq +bad +or +missing +cookie +The cookie is missing, corrupted or bogus. +
‘112’
.Pq +bad +or +missing +leapseconds +table +The leapseconds table is missing, corrupted or bogus. +
‘113’
.Pq +bad +or +missing +certificate +The certificate is missing, corrupted or bogus. +
‘114’
.Pq +bad +or +missing +identity +The identity key is missing, corrupt or bogus. + +

.Sh +Monitoring +Support +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 +cron(8) +jobs, the data can be +automatically summarized and archived for retrospective analysis. +.Ss +Monitoring +Commands +

+
‘Ic’
Enables writing of statistics records. +Currently, four kinds of +.Ar +name +statistics are supported. +
+
‘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. +

‘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. +

‘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. +

‘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. +

‘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. +

‘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. +

+
‘Time’
Time in hours since the system was last rebooted. +
‘Packets’
Total number of packets received. +
‘Packets’
Number of packets received in response to previous packets sent +
‘Current’
Number of packets matching the current NTP version. +
‘Previous’
Number of packets matching the previous NTP version. +
‘Bad’
Number of packets matching neither NTP version. +
‘Access’
Number of packets denied access for any reason. +
‘Bad’
Number of packets with invalid length, format or port number. +
‘Bad’
Number of packets not verified as authentic. +
‘Rate’
Number of packets discarded due to rate limitation. + +

.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 +ntpdc(1ntpdcmdoc) +program running at a remote location. +

+
‘Cm’
This is the type of the statistics records, as shown in the +.Cm +statistics +command. +
‘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 +: +
+
‘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. +
‘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 +. +
‘Cm’
This part is reflects individual elements of a file set. +It is +generated according to the type of a file set. + +

.It +Cm +type +Ar +typename +A file generation set is characterized by its type. +The following +types are supported: +

+
‘Cm’
The file set is actually a single plain file. +
‘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 +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 +ntpd(1ntpdmdoc) +server process. +
‘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 +. +
‘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 +. +
‘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. +
‘Cm’
One generation file element is generated per year. +The filename +suffix consists of a dot and a 4 digit year number. +
‘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 +. + +

.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. + +

.Sh +Access +Control +Support +The +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 +

+
‘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. +
‘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: +
+
‘Cm’
Deny packets of all kinds, including +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +queries. +
‘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. +
‘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 +ntpd(1ntpdmdoc). +Thus, monitoring is always active as +long as there is a restriction entry with the +.Cm +limited +flag. +
‘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. +
‘Cm’
Deny +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +queries which attempt to modify the state of the +server (i.e., run time reconfiguration). +Queries which return +information are permitted. +
‘Cm’
Deny +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +queries. +Time service is not affected. +
‘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. +
‘Cm’
Deny all packets except +ntpq(1ntpqmdoc) +and +ntpdc(1ntpdcmdoc) +queries. +
‘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. +
‘Cm’
Deny service unless the packet is cryptographically authenticated. +
‘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. +
‘Cm’
Deny packets that do not match the current NTP version. + +

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). + +

.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 +ntpd(1ntpdmdoc) +continuously and run either +ntpdate(8) +or +ntpd(1ntpdmdoc) +-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 +ntpd(1ntpdmdoc) +-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 +

+
‘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: +

+
‘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. +
‘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. +
‘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. +
‘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. +
‘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. + +

.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. + +

.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, +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 +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 +

+
‘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: +
+
‘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. +
‘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. +
‘Cm’
‘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. + +

.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 +ntpdc(1ntpdcmdoc) +program. +The options are interpreted as +follows: +

+
‘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 +) +. +
‘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 +) +. +
‘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. +
‘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. +
‘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. +
‘Cm’
‘Cm’
‘Cm’
‘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 +. + +

.Sh +Miscellaneous +Options +

+
‘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. +
‘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. +
‘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 +-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 +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. +

‘Xo’
.Oo +.Cm +auth +| +Cm +bclient +| +.Cm +calibrate +| +Cm +kernel +| +.Cm +monitor +| +Cm +ntp +| +.Cm +pps +| +Cm +stats +.Oc +.Xc +
‘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 +ntpdc(1ntpdcmdoc) +utility program. +
+
‘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 +. +
‘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 +. +
‘Cm’
Enables the calibrate feature for reference clocks. +The default for +this flag is +.Ic +disable +. +
‘Cm’
Enables the kernel time discipline, if available. +The default for this +flag is +.Ic +enable +if support is available, otherwise +.Ic +disable +. +
‘Cm’
Enables the monitoring facility. +See the +ntpdc(1ntpdcmdoc) +program +and the +.Ic +monlist +command or further information. +The +default for this flag is +.Ic +enable +. +
‘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 +. +
‘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 +. +
‘Cm’
Enables the statistics facility. +See the +.Sx +Monitoring +Options +section for further information. +The default for this flag is +.Ic +disable +. + +

.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 +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 +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 +syslog(3) +priority mask, +.Ql ++ +adds and +.Ql +- +removes +messages. +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 +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 +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 +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: +

+
‘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. +
‘Cm’
The argument becomes the new value for the dispersion increase rate, +normally .000015 s/s. +
‘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. +
‘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. +
‘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. +
‘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. +
‘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. + +

.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. + +

This section was generated by AutoGen, +using the agtexi-cmd template and the option descriptions for the ntp.conf program. +This software is released under the NTP license, <http://ntp.org/license>. + +

+ +
+ + +

+Next: , +Up: ntp.conf Invocation + +
+ +

ntp.conf help/usage (--help)

+ +

+This is the automatically generated usage text for ntp.conf. + +

The text printed is the same whether selected with the help option +(--help) or the more-help option (--more-help). more-help will print +the usage text by passing it through a pager program. +more-help is disabled on platforms without a working +fork(2) function. The PAGER environment variable is +used to select the program, defaulting to more. Both will exit +with a status code of 0. + + 

                                                                                                                   ntp.conf is unavailable - no --help
+
+
+ + +

+Next: , +Previous: ntp.conf usage, +Up: ntp.conf Invocation + +
+ +

presetting/configuring ntp.conf

+ +

Any option that is not marked as not presettable may be preset by +loading values from environment variables named NTP.CONF and NTP.CONF_<OPTION_NAME>. <OPTION_NAME> must be one of +the options listed above in upper case and segmented with underscores. +The 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: + +

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: + +

+
‘version’
Only print the version. This is the default. +
‘copyright’
Name the copyright usage licensing terms. +
‘verbose’
Print the full copyright usage licensing terms. +
+ +
+ + +

+Next: , +Previous: ntp.conf config, +Up: ntp.conf Invocation + +
+ +

ntp.conf exit status

+ +

One of the following exit values will be returned: +

+
‘0 (EXIT_SUCCESS)’
Successful program execution. +
‘1 (EXIT_FAILURE)’
The operation failed or the command syntax was not valid. +
+
+ + +

+Next: , +Previous: ntp.conf exit status, +Up: ntp.conf Invocation + +
+ +

ntp.conf Files

+ +
+
‘Pa’
the default name of the configuration file +
‘Pa’
private MD5 keys +
‘Pa’
RSA private key +
‘Pa’
RSA public key +
‘Pa’
Diffie-Hellman agreement parameters + +
+ + +

+Next: , +Previous: ntp.conf Files, +Up: ntp.conf Invocation + +
+ +

ntp.conf See Also

+ +

.Sh +SEE +ALSO +ntpd(1ntpdmdoc), +ntpdc(1ntpdcmdoc), +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 +

+ + +

+Next: , +Previous: ntp.conf See Also, +Up: ntp.conf Invocation + +
+ +

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. +

+ + +

+Previous: ntp.conf Bugs, +Up: ntp.conf Invocation + +
+ +

ntp.conf Notes

+ +

This document is derived from FreeBSD. + + + diff --git a/ntpd/ntp.conf.texi b/ntpd/ntp.conf.texi new file mode 100644 index 000000000..db79f4d18 --- /dev/null +++ b/ntpd/ntp.conf.texi @@ -0,0 +1,48 @@ +\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 diff --git a/ntpd/ntp.keys.def b/ntpd/ntp.keys.def index 5f9a9545f..9429f095a 100644 --- a/ntpd/ntp.keys.def +++ b/ntpd/ntp.keys.def @@ -8,7 +8,8 @@ autogen definitions options; // 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 @@ -18,16 +19,13 @@ doc-section = { 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 @@ -37,7 +35,7 @@ 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 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 @@ -48,57 +46,51 @@ Key entries use a fixed format of the form .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 diff --git a/ntpd/ntp.keys.html b/ntpd/ntp.keys.html new file mode 100644 index 000000000..80a8b3b91 --- /dev/null +++ b/ntpd/ntp.keys.html @@ -0,0 +1,67 @@ + + +NTP Symmetric Key + + + + + + + + + +

NTP Symmetric Key

+
+ +

+Next: , +Previous: (dir), +Up: (dir) + +
+ +

NTP's Symmetric Key File User Manual

+ +

This document describes the symmetric key file for the NTP Project's +ntpd program. + +

This document applies to version {No value for `VERSION'} of ntp.keys. + +

+

Short Contents

+ +
+ + + +
+ + +

+ + +
+ + +

Description

+ +

The name and location of the symmetric key file for ntpd can +be specified in a configuration file, by default /etc/ntp.keys. + + + diff --git a/ntpd/ntp.keys.texi b/ntpd/ntp.keys.texi new file mode 100644 index 000000000..723c955d8 --- /dev/null +++ b/ntpd/ntp.keys.texi @@ -0,0 +1,48 @@ +\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 diff --git a/sntp/ag-tpl/agman-file.tpl b/sntp/ag-tpl/agman-file.tpl new file mode 100644 index 000000000..b2d15e1f1 --- /dev/null +++ b/sntp/ag-tpl/agman-file.tpl @@ -0,0 +1,86 @@ +[+: -*- 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 :+] diff --git a/sntp/ag-tpl/agmdoc-file.tpl b/sntp/ag-tpl/agmdoc-file.tpl new file mode 100644 index 000000000..9e5fc0bf8 --- /dev/null +++ b/sntp/ag-tpl/agmdoc-file.tpl @@ -0,0 +1,73 @@ +[+: -*- 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 :+] diff --git a/sntp/ag-tpl/cmd-doc.tlib b/sntp/ag-tpl/cmd-doc.tlib new file mode 100644 index 000000000..bcd858c37 --- /dev/null +++ b/sntp/ag-tpl/cmd-doc.tlib @@ -0,0 +1,1003 @@ +[+: -*- 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) :+]_\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 \:+]