1 files changed, 1328 insertions, 879 deletions

diff --git a/usr.sbin/ntp/doc/ntp.conf.5 b/usr.sbin/ntp/doc/ntp.conf.5
index f638a084eec66..4aafe79aa824f 100644
--- a/usr.sbin/ntp/doc/ntp.conf.5
+++ b/usr.sbin/ntp/doc/ntp.conf.5
@@ -1,7 +1,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 13, 2000
+.Dd May 17, 2006
 .Dt NTP.CONF 5
 .Os
 .Sh NAME
@@ -52,7 +52,7 @@ and text strings.
 .Pp
 The rest of this page describes the configuration and control options.
 The
-.Qq "Notes on Configuring NTP and Setting up a NTP Subnet"
+.Qq Notes on Configuring NTP and Setting up a NTP Subnet
 page
 (available as part of the HTML documentation
 provided in
@@ -70,7 +70,11 @@ and the options used to control it:
 .It
 .Sx Access Control Support
 .It
+.Sx Automatic NTP Configuration Options
+.It
 .Sx Reference Clock Support
+.It
+.Sx Miscellaneous Options
 .El
 .Pp
 Following these is a section describing
@@ -97,14 +101,37 @@ that control various related operations.
 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 (IP class A, B and C), (b) the
-broadcast address of a local interface, (m) a multicast address (IP
+(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.
+.Pp
+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.
+.Pp
+Note that in contexts where a host name is expected, a
+.Fl 4
+qualifier preceding
+the host name forces DNS resolution to the IPv4 namespace,
+while a
+.Fl 6
+qualifier forces DNS resolution to the IPv6 namespace.
+See IPv6 references for the
+equivalent classes for that address family.
 .Bl -tag -width indent
 .It Xo Ic server Ar address
 .Op Cm key Ar key \&| Cm autokey
@@ -146,8 +173,11 @@ The
 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.
+.Qq Association Management
+page
+(available as part of the HTML documentation
+provided in
+.Pa /usr/share/doc/ntp ) .
 .Bl -tag -width indent
 .It Ic server
 For type s and r addresses, this command mobilizes a persistent
@@ -187,7 +217,8 @@ messages to a client population at the
 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 224.0.1.1 exclusively to
+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
@@ -239,32 +270,27 @@ include authentication fields encrypted using the autokey scheme
 described in
 .Sx Authentication Options .
 .It Cm burst
-when the server is reachable and at each poll interval, send a
-burst of eight packets instead of the usual one packet.
-The spacing
-between the first and the second packets is about 16s to allow a
-modem call to complete, while the spacing between the remaining
-packets is about 2s.
-This is designed to improve timekeeping
-quality with the
+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.
+command and s addresses.
 .It Cm iburst
-When the server is unreachable and at each poll interval, send
-a burst of eight packets instead of the usual one.
-As long as the
-server is unreachable, the spacing between packets is about 16s to
-allow a modem call to complete.
-Once the server is reachable, the
-spacing between packets is about 2s.
-This is designed to speed the
-initial synchronization acquisition with the
+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
 .Xr ntpd 8
-is started
-with the
+is started with the
 .Fl q
 option.
 .It Cm key Ar key
@@ -287,23 +313,29 @@ 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).
+.It Cm noselect
+Marks the server as unused, except for display purposes.
+The server is discarded by the selection algroithm.
 .It Cm prefer
 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 for further
-information.
+.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.
 .It Cm ttl Ar ttl
 This option is used only with broadcast server and manycast
 client modes.
 It specifies the time-to-live
-.Cm ttl
+.Ar ttl
 to
 use on broadcast server and multicast server and the maximum
-.Cm ttl
+.Ar ttl
 for the expanding ring search with manycast
 client packets.
 Selection of the proper value, which defaults to
@@ -368,40 +400,66 @@ 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 augmented by the RSA Message Digest
+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.
 .Pp
-NTPv4 retains the NTPv3 schemes, 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.
+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.
+.Pp
+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.
 .Pp
 Authentication is configured separately for each association
 using the
 .Cm key
 or
 .Cm autokey
-subcommands on the
+subcommand on the
 .Ic peer ,
 .Ic server ,
 .Ic broadcast
 and
 .Ic manycastclient
-commands as described in
-.Sx Configuration Options .
+configuration commands as described in
+.Sx Configuration Options
+page.
 The authentication
-options described below specify the suite of keys, select the key
-for each configured association and manage the configuration
-operations.
+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.
+.Pp
+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
 .Pp
 The
 .Cm auth
@@ -411,7 +469,7 @@ This flag can be set or reset by the
 .Ic enable
 and
 .Ic disable
-configuration commands and also by remote
+commands and also by remote
 configuration commands sent by a
 .Xr ntpdc 8
 program running in
@@ -419,64 +477,59 @@ 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 schemes.
-If
-this flag is disabled, these operations are effective even if not
-cryptographic authenticated.
-It should be understood that operating
-in the latter mode invites a significant vulnerability where a
-rogue hacker can seriously disrupt client timekeeping.
-.Pp
-In networks with firewalls and large numbers of broadcast
-clients it may be acceptable to disable authentication, since that
-avoids key distribution and simplifies network maintenance.
-However, when the configuration file contains host names, or when a
-server or client is configured remotely, host names are resolved
-using the DNS and a separate name resolution process.
-In order to
-protect against bogus name server messages, name resolution
-messages are authenticated using an internally generated key which
-is normally invisible to the user.
-However, if cryptographic
-support is disabled, the name resolution process will fail.
-This
-can be avoided either by specifying IP addresses instead of host
-names, which is generally inadvisable, or by enabling the flag for
-name resolution and disabled it once the name resolution process is
-complete.
+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.
 .Pp
 An attractive alternative where multicast support is available
-is manycast mode, in which clients periodically troll for servers.
-Cryptographic authentication in this mode uses public-key schemes
-as described below.
-The principle advantage of this 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.
-.Pp
-In addition to the default symmetric-key cryptographic support,
-support for public-key cryptography is available if the requisite
-.Sy rsaref20
-software distribution has been installed before
-building the distribution.
-Public-key cryptography provides secure
-authentication of servers without compromising accuracy and
-stability.
-The security model and protocol schemes for both
-symmetric-key and public-key cryptography are described below.
-.Ss Symmetric-Key Scheme
+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.
+.Pp
+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 their messages.
-Keys and related information are specified in a key file, usually
-called
+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 should be exchanged and stored
-using secure procedures beyond the scope of the NTP protocol
-itself.
-Besides the keys used for ordinary NTP associations,
+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
 .Xr ntpq 8
 and
@@ -485,289 +538,231 @@ utility programs.
 .Pp
 When
 .Xr ntpd 8
-is first started, it reads the key file
-specified in the
+is first started, it reads the key file specified in the
 .Ic keys
-command and installs the keys in the
-key cache.
-However, the keys must be activated with the
+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
+command before use. This
+allows, for instance, the installation of possibly
+several batches of keys and
+then activating or deactivating each batch
+remotely using
 .Xr ntpdc 8 .
-This also provides a revocation capability that can
-be used if a key becomes compromised.
-The
+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
 .Xr ntpdc 8
 utility, while the
 .Ic controlkey
-command selects the key used
-as the password for the
+command selects the key used as the password for the
 .Xr ntpq 8
 utility.
-.Ss Public-Key Scheme
-The original NTPv3 authentication scheme described in RFC-1305
-continues to be supported; however, in NTPv4 an additional
-authentication scheme called Autokey is available.
-It uses MD5
-message digest, RSA public-key signature and Diffie-Hellman key
-agreement algorithms available from several sources, but not
-included in the NTPv4 software distribution.
-In order to be
-effective, the
-.Sy rsaref20
-package must be installed as
-described in the
-.Pa README.rsa
-file.
-Once installed, the
-configure and build process automatically detects it and compiles
-the routines required.
-The Autokey scheme has several modes of
-operation corresponding to the various NTP modes supported.
-RSA
-signatures with timestamps are used in all modes to verify the
-source of cryptographic values.
-All modes use a special cookie
-which can be computed independently by the client and server.
-In
-symmetric modes the cookie is constructed using the Diffie-Hellman
-key agreement algorithm.
-In other modes the cookie is constructed
-from the IP addresses and a private value known only to the server.
-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.
+.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.
+.Pp
+\." The cryptographic means necessary for all Autokey operations
+\." is provided by the OpenSSL software library.
+\." This library is available from http://www.openssl.org/
+\." and can be installed using the procedures outlined
+\." in the Building and Installing the Distribution page. Once installed,
+\." the configure and build
+\." process automatically detects the library and links
+\." the library routines required.
+.Pp
+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, in the
-.Qq "Autonomous Authentication"
+current status, briefing slides and reading list on the
+.Sx Autonomous Authentication
 page.
 .Pp
-The cryptographic values used by the Autokey scheme are
-incorporated as a set of files generated by the
-.Xr ntp-genkeys 8
-program, including the
-symmetric private keys, public/private key pair, and the agreement
-parameters.
-See the
-.Xr ntp.keys 5
-page for a description of
-the formats of these files.
-They contain cryptographic values
-generated by the algorithms of the
-.Sy rsaref20
-package and
-are in printable ASCII format.
-All file names include the
-timestamp, in NTP seconds, following the default names given below.
-Since the file data are derived from random values seeded by the
-system clock and the file name includes the timestamp, every
-generation produces a different file and different file name.
+The specific cryptographic environment used by Autokey servers
+and clients is determined by a set of files
+and soft links generated by the
+.Xr ntp-keygen 8
+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.
 .Pp
-The
-.Pa ntp.keys
-file contains the DES/MD5 private keys.
-It
-must be distributed by secure means to other servers and clients
-sharing the same security compartment and made visible only to
-root.
-While this file is not used with the Autokey scheme, it is
-needed to authenticate some remote configuration commands used by
-the
-.Xr ntpdc 8 ,
-.Xr ntpq 8
-utilities.
-The
-.Pa ntpkey
-file
-contains the RSA private key.
-It is useful only to the machine that
-generated it and never shared with any other daemon or application
-program, so must be made visible only to root.
+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.
 .Pp
-The
-.Pa ntp_dh
-file contains the agreement parameters,
-which are used only in symmetric (active and passive) modes.
-It is
-necessary that both peers beginning a symmetric-mode association
-share the same parameters, but it does not matter which
-.Pa ntp_dh
-file generates them.
-If one of the peers contains
-the parameters, the other peer obtains them using the Autokey
-protocol.
-If both peers contain the parameters, the most recent
-copy is used by both peers.
-If a peer does not have the parameters,
-they will be requested by all associations, either configured or
-not; but, none of the associations can proceed until one of them
-has received the parameters.
-Once loaded, the parameters can be
-provided on request to other clients and servers.
-The
-.Pa ntp_dh
-file can be also be distributed using insecure
-means, since the data are public values.
+By convention, the name of an Autokey host is the name returned
+by the Unix
+.Xr 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.
 .Pp
-The
-.Pa ntpkey_ Ns Ar host
-file contains the RSA public
-key, where
-.Ar host
-is the name of the host.
-Each host
-must have its own
-.Pa ntpkey_ Ns Ar host
-file, which is
-normally provided to other hosts using the Autokey protocol.
-Each
+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.
+.Pp
+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
-association requires the public
-key associated with the particular server or peer to be loaded
-either directly from a local file or indirectly from the server
-using the Autokey protocol.
-These files can be widely distributed
-and stored using insecure means, since the data are public
-values.
-.Pp
-The optional
-.Pa ntpkey_certif_ Ns Ar host
-file contains
-the PKI certificate for the host.
-This provides a binding between
-the host hame and RSA public key.
-In the current implementation the
-certificate is obtained by a client, if present, but the contents
-are ignored.
-.Pp
-Due to the widespread use of interface-specific naming, the host
-names used in configured and mobilized associations are determined
-by the
-.Ux
-.Xr gethostname 3
-library routine.
-Both the
-.Xr ntp-genkeys 8
-program and the Autokey protocol derive the
-name of the public key file using the name returned by this
-routine.
-While every server and client is required to load their
-own public and private keys, the public keys for each client or
-peer association can be obtained from the server or peer using the
-Autokey protocol.
-Note however, that at the current stage of
-development the authenticity of the server or peer and the
-cryptographic binding of the server name, address and public key is
-not yet established by a certificate authority or web of trust.
-.Ss Leapseconds Table
-The NIST provides a table showing the epoch for all historic
-occasions of leap second insertion since 1972.
-The leapsecond table
-shows each epoch of insertion along with the offset of
-International Atomic Time (TAI) with respect to Coordinated
-Universal Time (UTC), as disseminated by NTP.
-The table can be
-obtained directly from NIST national time servers using
-FTP as the ASCII file
-.Pa pub/leap-seconds .
-.Pp
-While not strictly a security function, the Autokey scheme
-provides means to securely retrieve the leapsecond table from a
-server or peer.
-Servers load the leapsecond table directly from the
-file specified in the
-.Ic crypto
-command, while clients can
-load the table indirectly from the servers using the Autokey
-protocol.
-Once loaded, the table can be provided on request to
-other clients and servers.
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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
-All key files are installed by default in
-.Pa /usr/local/etc ,
-which is normally in a shared file system
-in NFS-mounted networks and avoids installing them in each machine
-separately.
-The default can be overridden by the
-.Ic keysdir
-configuration command.
-However, this is not a good place to install
-the private key file, since each machine needs its own file.
-A
-suitable place to install it is in
-.Pa /etc ,
-which is normally
-not in a shared file system.
-.Pp
-The recommended practice is to keep the timestamp extensions
-when installing a file and to install a link from the default name
-(without the timestamp extension) to the actual file.
-This allows
-new file generations to be activated simply by changing the link.
-However,
-.Xr ntpd 8
-parses the link name when present to extract
-the extension value and sends it along with the public key and host
-name when requested.
-This allows clients to verify that the file
-and generation time are always current.
-However, the actual
-location of each file can be overridden by the
-.Ic crypto
-configuration command.
-.Pp
-All cryptographic keys and related parameters should be
-regenerated on a periodic and automatic basis, like once per month.
-The
-.Xr ntp-genkeys 8
-program uses the same timestamp extension
-for all files generated at one time, so each generation is distinct
-and can be readily recognized in monitoring data.
-While a
-public/private key pair must be generated by every server and
-client, the public keys and agreement parameters do not need to be
-explicitly copied to all machines in the same security compartment,
-since they can be obtained automatically using the Autokey
-protocol.
-However, it is necessary that all primary servers have
-the same agreement parameter file.
-The recommended way to do this
-is for one of the primary servers to generate that file and then
-copy it to the other primary servers in the same compartment using
-the
-.Ux
-.Xr rdist 1
-command.
-Future versions of the Autokey
-protocol are to contain provisions for an agreement protocol to do
-this automatically.
-.Pp
-Servers and clients can make a new generation in the following
-way.
-All machines have loaded the old generation at startup and are
-operating normally.
-At designated intervals, each machine generates
-a new public/private key pair and makes links from the default file
-names to the new file names.
-The
-.Xr ntpd 8
-is then restarted
-and loads the new generation, with result clients no longer can
-authenticate correctly.
-The Autokey protocol is designed so that
-after a few minutes the clients time out and restart the protocol
-from the beginning, with result the new generation is loaded and
-operation continues as before.
-A similar procedure can be used for
-the agreement parameter file, but in this case precautions must be
-take to be sure that all machines with this file have the same
-copy.
+The cryptographic values used by the Autokey protocol are
+incorporated as a set of files generated by the
+.Xr ntp-keygen 8
+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
+.Xr ntpq 8
+and
+.Xr ntpdc 8
+utility programs. The remaining files are necessary only for the
+Autokey protocol.
+.Pp
+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
 .Bl -tag -width indent
 .It Ic autokey Op Ar logsec
@@ -789,63 +784,92 @@ The
 .Ar key
 argument is
 the key identifier for a trusted key, where the value can be in the
-range 1 to 65534, inclusive.
+range 1 to 65,534, inclusive.
 .It Xo Ic crypto
-.Op Cm flags Ar flags
-.Op Cm privatekey Ar file
-.Op Cm publickey Ar file
-.Op Cm dhparms Ar file
+.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 NTP daemon build process be
-configured with the RSA library.
-This command activates public-key
-cryptography and loads the required RSA private and public key
-files and the optional Diffie-Hellman agreement parameter file, if
-present.
-If one or more files are left unspecified, the default
-names are used as described below.
-Following are the
-subcommands:
+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:
 .Bl -tag -width indent
-.It Cm privatekey Ar file
-Specifies the location of the RSA private key file, which
-otherwise defaults to
-.Pa /usr/local/etc/ntpkey .
-.It Cm publickey Ar file
-Specifies the location of the RSA public key file, which
-otherwise defaults to
-.Pa /usr/local/etc/ntpkey_ Ns Ar host ,
-where
-.Ar host
-is the name of the generating machine.
-.It Cm dhparms Ar file
-Specifies the location of the Diffie-Hellman parameters file,
-which otherwise defaults to
-.Pa /usr/local/etc/ntpkey_dh .
+.It Cm cert Ar file
+Specifies the location of the required host public certificate file.
+This overrides the link
+.Pa ntpkey_cert_ Ns Ar hostname
+in the keys directory.
+.It Cm gqpar Ar file
+Specifies the location of the optional GQ parameters file. This
+overrides the link
+.Pa ntpkey_gq_ Ns Ar hostname
+in the keys directory.
+.It Cm host Ar file
+Specifies the location of the required host key file. This overrides
+the link
+.Pa ntpkey_key_ Ns Ar hostname
+in the keys directory.
+.It Cm iffpar Ar file
+Specifies the location of the optional IFF parameters file.This
+overrides the link
+.Pa ntpkey_iff_ Ns Ar hostname
+in the keys directory.
 .It Cm leap Ar file
-Specifies the location of the leapsecond table file, which
-otherwise defaults to
-.Pa /usr/local/etc/ntpkey_leap .
+Specifies the location of the optional leapsecond file.
+This overrides the link
+.Pa ntpkey_leap
+in the keys directory.
+.It Cm mvpar Ar file
+Specifies the location of the optional MV parameters file. This
+overrides the link
+.Pa ntpkey_mv_ Ns Ar hostname
+in the keys directory.
+.It Cm pw Ar password
+Specifies the password to decrypt files containing private keys and
+identity parameters. This is required only if these files have been
+encrypted.
+.It Cm randfile Ar file
+Specifies the location of the random seed file used by the OpenSSL
+library. The defaults are described in the main text above.
+.It Cm sign Ar file
+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.
 .El
 .It Ic keys Ar keyfile
-Specifies the location of the DES/MD5 private key file
+Specifies the complete path and location of the MD5 key file
 containing the keys and key identifiers used by
 .Xr ntpd 8 ,
 .Xr ntpq 8
 and
-.Xr ntpdc 8
-when operating in symmetric-key
-mode.
+.Xr ntpdc
+when operating with symmetric key cryptography.
+This is the same operation as the
+.Fl k
+command line option.
 .It Ic keysdir Ar path
-This command requires the NTP daemon build process be
-configured with the RSA library.
-It specifies the default directory
-path for the private key file, agreement parameters file and one or
-more public key files.
-The default when this command does not
-appear in the configuration file is
-.Pa /usr/local/etc .
+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
 .Xr ntpdc 8
@@ -856,7 +880,7 @@ The
 .Ar key
 argument is a key identifier
 for the trusted key, where the value can be in the range 1 to
-65534, inclusive.
+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
@@ -870,7 +894,7 @@ 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,
+purposes of authenticating peers with symmetric key cryptography,
 as well as keys used by the
 .Xr ntpq 8
 and
@@ -885,6 +909,57 @@ The
 arguments are 32-bit unsigned
 integers with values from 1 to 65,534.
 .El
+.Ss Error Codes
+The following error codes are reported via the NTP control
+and monitoring protocol trap mechanism.
+.Bl -tag -width indent
+.It 101
+.Pq bad field format or length
+The packet has invalid version, length or format.
+.It 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.
+.It 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.
+.It 104
+.Pq bad or missing public key
+The public key is missing, has incorrect format or is an unsupported type.
+.It 105
+.Pq unsupported digest type
+The server requires an unsupported digest/signature scheme.
+.It 106
+.Pq mismatched digest types
+Not used.
+.It 107
+.Pq bad signature length
+The signature length does not match the current public key.
+.It 108
+.Pq signature not verified
+The message fails the signature check. It could be bogus or signed by a
+different private key.
+.It 109
+.Pq certificate not verified
+The certificate is invalid or signed with the wrong key.
+.It 110
+.Pq certificate not verified
+The certificate is not yet valid or has expired or the signature could not
+be verified.
+.It 111
+.Pq bad or missing cookie
+The cookie is missing, corrupted or bogus.
+.It 112
+.Pq bad or missing leapseconds table
+The leapseconds table is missing, corrupted or bogus.
+.It 113
+.Pq bad or missing certificate
+The certificate is missing, corrupted or bogus.
+.It 114
+.Pq bad or missing identity
+The identity key is missing, corrupt or bogus.
+.El
 .Sh Monitoring Support
 .Xr ntpd 8
 includes a comprehensive monitoring facility suitable
@@ -913,13 +988,46 @@ Currently, four kinds of
 .Ar name
 statistics are supported.
 .Bl -tag -width indent
+.It Cm clockstats
+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
+.Pp
+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.
+.It Cm cryptostats
+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
+.Pp
+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.
 .It Cm loopstats
 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 loopstats:
+the file generation set named
+.Cm loopstats :
 .Bd -literal
-50935 75440.031 0.000006019 13.778190 0.000351733 0.013380 6
+50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
 .Ed
 .Pp
 The first two fields show the date (Modified Julian Day) and
@@ -935,9 +1043,10 @@ 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 peerstats:
+generation set named
+.Cm peerstats :
 .Bd -literal
-48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
+48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
 .Ed
 .Pp
 The first two fields show the date (Modified Julian Day) and
@@ -947,29 +1056,8 @@ 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 three fields show the offset, delay and RMS jitter, all in
-seconds.
-.It Cm clockstats
-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 clockstats:
-.Bd -literal
-49213 525.624 127.127.4.1 93 226 00:08:29.606 D
-.Ed
-.Pp
-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.
+The final four fields show the offset,
+delay, dispersion and RMS jitter, all in seconds.
 .It Cm rawstats
 Enables recording of raw-timestamp statistics information.
 This
@@ -977,10 +1065,12 @@ 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 rawstats:
+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
+.Pp
 The first two fields show the date (Modified Julian Day) and
 time (seconds and fraction past UTC midnight).
 The next two fields
@@ -991,232 +1081,243 @@ 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.
+.It Cm sysstats
+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
+.Pp
+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.
+.Bl -tag -width indent
+.It Time since restart Cm 36000
+Time in hours since the system was last rebooted.
+.It Packets received Cm 81965
+Total number of packets received.
+.It Packets processed Cm 0
+Number of packets received in response to previous packets sent
+.It Current version Cm 9546
+Number of packets matching the current NTP version.
+.It Previous version Cm 56
+Number of packets matching the previous NTP version.
+.It Bad version Cm 71793
+Number of packets matching neither NTP version.
+.It Access denied Cm 512
+Number of packets denied access for any reason.
+.It Bad length or format Cm 540
+Number of packets with invalid length, format or port number.
+.It Bad authentication Cm 10
+Number of packets not verified as authentic.
+.It Rate exceeded Cm 147
+Number of packets discarded due to rate limitation.
 .El
-.It Ic statsdir Ar directory_path
+.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)
-.Ic filegen
-filename prefix to be modified for file
-generation sets, which is useful for handling statistics logs.
-.It Xo Ic filegen Ar name
+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 \&| Cm nolink
-.Op Cm enable \&| Cm disable
+.Op Cm link | nolink
+.Op Cm enable | disable
 .Xc
-Configures setting of generation file set
-.Ar name .
-Generation file sets provide a means for handling files that are
+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
-.Xr ntpd 8 .
-(Most important: they can be removed to
-free space for new data produced.)
+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.)
+.Pp
 Note that this command can be sent from the
 .Xr ntpdc 8
 program running at a remote location.
 .Bl -tag -width indent
-.It Ar name
+.It Cm name
 This is the type of the statistics records, as shown in the
-.Ic statistics
+.Cm statistics
 command.
 .It Cm file Ar filename
-This is the file name for the statistics records.
-Filenames of
-set members are built from three concatenated elements
-prefix, filename and
-suffix:
+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 :
 .Bl -tag -width indent
-.It prefix
-This is a constant filename path.
-It is not subject to
+.It Cm prefix
+This is a constant filename path. It is not subject to
 modifications via the
-.Ic 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
-.Cm loopstats
+.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
-.Cm peerstats
-generation can be
-configured using the
-.Ic statsdir
+.Ar peerstats
+generation can be configured using the
+.Ar statsdir
 option explained above.
-.It filename
+.It Cm filename
 This string is directly concatenated to the prefix mentioned
 above (no intervening
-.Ql /
-(slash)).
-This can be modified
-using the
-.Ar file
-argument to the
-.Ic filegen
-statement.
-No
-.Ql \&..
-elements are allowed in this component to prevent
-filenames referring to parts outside the file system hierarchy
-denoted by prefix.
-.It suffix
-This part is reflects individual elements of a file set.
-It is
+.Ql / ) .
+This can be modified using
+the file argument to the
+.Ar filegen
+statement. No .. elements are
+allowed in this component to prevent filenames referring to
+parts outside the filesystem hierarchy denoted by
+.Ar prefix .
+.It Cm suffix
+This part is reflects individual elements of a file set. It is
 generated according to the type of a file set.
 .El
 .It Cm type Ar typename
-A file generation set is characterized by its type.
-The
-following types are supported:
+A file generation set is characterized by its type. The following
+types are supported:
 .Bl -tag -width indent
-.It none
+.It Cm none
 The file set is actually a single plain file.
-.It pid
-One element of file set is used per incarnation of a
-.Xr ntpd 8
-server.
-This type does not perform any changes to
-file set members during runtime, however it provides an easy way of
+.It Cm pid
+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
 .Xr ntpd 8
-server
-incarnations.
-The set member filename is built by appending a
+server incarnations. The set member filename is built by appending a
 .Ql \&.
-(dot) to concatenated prefix and filename
-strings, and appending the decimal representation of the process ID
-of the
+to concatenated
+.Ar prefix
+and
+.Ar filename
+strings, and
+appending the decimal representation of the process ID of the
 .Xr ntpd 8
 server process.
-.It day
-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
+.It Cm day
+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 \&.
-(dot) and a day
-specification in the form
-.Ar YYYYMMdd .
-.Ar YYYY
-is a 4-digit year
-number (e.g., 1992).
-.Ar MM
+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.
-.Ar dd
+.Cm dd
 is a two digit day number.
-Thus, all information
-written at 10 December 1992 would end up in a file named
-.Sm off
-.Pa Ar prefix / Ar filename / 19921210 .
-.Sm on
-.It week
+Thus, all information written at 10 December 1992 would end up
+in a file named
+.Ar prefix
+.Ar filename Ns .19921210 .
+.It Cm week
 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
-Ql W ,
-and a 2-digit
-week number.
-For example, information from January, 10th 1992 would
-end up in a file with suffix
-.Pa .1992W1 .
-.It month
-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.
-.It year
-One generation file element is generated per year.
-The filename
+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 .
+.It Cm month
+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.
+.It Cm year
+One generation file element is generated per year. The filename
 suffix consists of a dot and a 4 digit year number.
-.It age
+.It Cm age
 This type of file generation sets changes to a new element of
-the file set every 24 hours of server operation.
-The filename
+the file set every 24 hours of server operation. The filename
 suffix consists of a dot, the letter
-.Ql 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.
+.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
-.Ic enable ;
+.Cm enable ;
 output is prevented by specifying
-.Ic disable .
+.Cm disable .
 .El
-.It Cm link \&| Cm 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
+.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
-.Cm 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
-.Ql C ,
-and the pid
-of the
-.Xr ntpd 8
-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.
+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.
 .El
 .El
 .Sh Access Control Support
+The
 .Xr ntpd 8
-implements a general purpose address-and-mask based
-restriction list.
-The list is sorted by address and by mask, and
-the list is searched in this order for matches, with the last match
-found defining the restriction flags associated with the incoming
-packets.
-The source address of incoming packets is used for the
-match, with the 32- bit address being and'ed with the mask
-associated with the restriction entry and then compared with the
-entry's address (which has also been and'ed with the mask) to look
-for a match.
+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.
+.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 ) .
 .Pp
-The restriction facility was implemented in conformance with the
-access policies for the original NSFnet backbone time servers.
-While this facility may be otherwise useful for keeping unwanted or
-broken remote time servers from affecting your own, it should not
-be considered an alternative to the standard NTP authentication
-facility.
+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.
+.Pp
+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.
@@ -1225,58 +1326,76 @@ 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 packet.
-If the
-.Cm kod
-flag is set and either service is denied or the client
-limit is exceeded, the server returns the packet and sets the
-leap bits unsynchronized, stratum zero and the ASCII string "DENY"
-in the reference source identifier field.
+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 kod
-flag
-is not set, the server simply drops the packet.
-.Pp
-A client or peer receiving a kiss-of-death packet performs a set
-of sanity checks to minimize security exposure.
-If this is the
-first packet received from the server, the client assumes an access
-denied condition at the server.
-It updates the stratum and
-reference identifier peer variables and sets the access denied
-(test 4) bit in the peer flash variable.
-If this bit is set, the
-client sends no packets to the server.
-If this is not the first
-packet, the client assumes a client limit condition at the server,
-but does not update the peer variables.
-In either case, a message
-is sent to the system log.
+.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".
+.Pp
+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
 .Bl -tag -width indent
-.It Xo Ic restrict numeric_address
-.Op Cm mask Ar numeric_mask
+.It Xo Ic discard
+.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.
+.It Xo Ic restrict address
+.Op Cm mask Ar mask
 .Op Ar flag ...
 .Xc
 The
-.Ar numeric_address
-argument, expressed in
-dotted-quad form, is the address of a host or network.
-The
-.Cm mask ,
-also expressed in dotted-quad form,
-defaults to 255.255.255.255, meaning that the
-.Ar numeric_address
-is treated as the address of an
-individual host.
-A default entry (address 0.0.0.0, mask
-0.0.0.0) is always included and, given the sort algorithm,
-is always the first entry in the list.
-Note that, while
-.Ar numeric_address
-is normally given in dotted-quad
-format, the text string
-.Ql default ,
+.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,
@@ -1294,29 +1413,26 @@ reconfiguration of the server.
 One or more of the following flags
 may be specified:
 .Bl -tag -width indent
-.It Cm kod
-If access is denied, send a kiss-of-death packet.
 .It Cm ignore
-Ignore all packets from hosts which match this entry.
-If this
-flag is specified neither queries nor time server polls will be
-responded to.
-.It Cm noquery
-Ignore all NTP mode 6 and 7 packets (i.e., information queries
-and configuration requests) from the source.
-Time service is not
-affected.
-.It Cm nomodify
-Ignore all NTP mode 6 and 7 packets which attempt to modify the
-state of the server (i.e., run time reconfiguration).
-Queries which
-return information are permitted.
-.It Cm notrap
-Decline to provide mode 6 control message trap service to
-matching hosts.
-The trap service is a subsystem of the mode 6
-control message protocol which is intended for use by remote event
-logging programs.
+Deny packets of all kinds, including
+.Xr ntpq 8
+and
+.Xr ntpdc 8
+queries.
+.It Cm kod
+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.
+.It Cm limited
+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
+.Xr ntpd 8 .
+Thus, monitoring is always active as
+long as there is a restriction entry with the
+.Cm limited
+flag.
 .It Cm lowpriotrap
 Declare traps set by matching hosts to be low priority.
 The
@@ -1327,45 +1443,36 @@ 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.
-.It Cm noserve
-Ignore NTP packets whose mode is other than 6 or 7.
-In effect,
-time service is denied, though queries may still be permitted.
+.It Cm nomodify
+Deny
+.Xr ntpq 8
+and
+.Xr ntpdc 8
+queries which attempt to modify the state of the
+server (i.e., run time reconfiguration). Queries which return
+information are permitted.
+.It Cm noquery
+Deny
+.Xr ntpq 8
+and
+.Xr ntpdc 8
+queries. Time service is not affected.
 .It Cm nopeer
-Provide stateless time service to polling hosts, but do not
-allocate peer memory resources to these hosts even if they
-otherwise might be considered useful as future synchronization
-partners.
-.It Cm notrust
-Treat these hosts normally in other respects, but never use
-them as synchronization sources.
-.It Cm limited
-These hosts are subject to limitation of number of clients from
-the same net.
-Net in this context refers to the IP notion of net
-(class A, class B, class C, etc.).
-Only the first
-.Va client_limit
-hosts that have shown up at the server and
-that have been active during the last
-.Va client_limit_period
-seconds are accepted.
-Requests from other clients from the same net
-are rejected.
-Only time request packets are taken into account.
-Query packets sent by the
+Deny packets which would result in mobilizing a new association. This
+includes broadcast and symmetric active packets when a configured
+association does not exist.
+.It Cm noserve
+Deny all packets except
 .Xr ntpq 8
 and
 .Xr ntpdc 8
-programs
-are not subject to these limits.
-A history of clients is kept using
-the monitoring capability of
-.Xr ntpd 8 .
-Thus, monitoring is
-always active as long as there is a restriction entry with the
-.Cm limited
-flag.
+queries.
+.It Cm notrap
+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.
+.It Cm notrust
+Deny service unless the packet is cryptographically authenticated.
 .It Cm ntpport
 This is actually a match algorithm modifier, rather than a
 restriction flag.
@@ -1383,35 +1490,360 @@ The
 is considered more specific and
 is sorted later in the list.
 .It Cm version
-Ignore these hosts if not the current NTP version.
+Deny packets that do not match the current NTP version.
 .El
 .Pp
-Default restriction list entries, with the flags
-.Cm ignore ,
-.Cm interface ,
-.Cm 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).
-.It Ic clientlimit Ar limit
-Set the
-.Va client_limit
-variable, which limits the number
-of simultaneous access-controlled clients.
-The default value for
-this variable is 3.
-.It Ic clientperiod Ar period
-Set the
-.Va client_limit_period
-variable, which specifies
-the number of seconds after which a client is considered inactive
-and thus no longer is counted for client limit restriction.
-The
-default value for this variable is 3600 seconds.
+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).
+.El
+.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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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 .
+.Pp
+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).
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+Some administrators prefer to avoid running
+.Xr ntpd 8
+continuously and run either
+.Xr ntpdate 8
+or
+.Xr ntpd 8
+.Fl 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
+.Xr ntpd 8
+.Fl 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.
+.Pp
+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
+.Bl -tag -width indent
+.It Xo Ic tos
+.Oo
+.Cm ceiling Ar ceiling |
+.Cm cohort { 0 | 1 } |
+.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:
+.Bl -tag -width indent
+.It Cm ceiling Ar ceiling
+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.
+.It Cm cohort Bro 0 | 1 Brc
+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.
+.It Cm floor Ar floor
+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.
+.It Cm minclock Ar minclock
+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.
+.It Cm minsane Ar minsane
+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.
+.El
+.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.
 .El
 .Sh Reference Clock Support
 The NTP Version 4 daemon supports some three dozen different radio,
@@ -1419,28 +1851,37 @@ 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"
+.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"
+.Qq Debugging Hints for Reference Clock Drivers
 and
-.Qq "How To Write a Reference Clock Driver"
-pages.
+.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.
+.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.
+.Qq Line Disciplines and Streams Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa /usr/share/doc/ntp ) .
 .Pp
 A reference clock will generally (though not always) be a radio
 timecode receiver which is synchronized to a source of standard
@@ -1505,7 +1946,10 @@ 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"
+.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
@@ -1579,9 +2023,12 @@ 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 for further
-information.
+.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.
 .It Cm mode Ar int
 Specifies a mode number which is interpreted in a
 device-specific fashion.
@@ -1656,15 +2103,21 @@ It takes the form of an argument to the
 command described in
 .Sx Miscellaneous Options
 page and operates as described in the
-.Qq "Reference Clock Drivers"
-page.
+.Qq Reference Clock Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa /usr/share/doc/ntp ) .
 .It Cm time2 Ar secs
 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.
+.Qq Reference Clock Drivers
+page
+(available as part of the HTML documentation
+provided in
+.Pa /usr/share/doc/ntp ) .
 .It Cm stratum Ar int
 Specifies the stratum number assigned to the driver, an integer
 between 0 and 15.
@@ -1706,6 +2159,7 @@ command can be found in
 .Sx Monitoring Options .
 .El
 .El
+.El
 .Sh Miscellaneous Options
 .Bl -tag -width indent
 .It Ic broadcastdelay Ar seconds
@@ -1723,18 +2177,22 @@ 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.
+.It Ic calldelay Ar delay
+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.
 .It Ic driftfile Ar driftfile
-This command specifies the name of the file used to record the
-frequency offset of the local clock oscillator.
-If the file exists,
-it is read at startup in order to set the initial frequency offset
-and then updated once per hour with the current frequency offset
-computed by the daemon.
-If the file does not exist or this command
-is not given, the initial frequency offset is assumed zero.
-In this
-case, it may take some hours for the frequency to stabilize and the
-residual timing errors to subside.
+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
+.Fl f
+command linke 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.
 .Pp
 The file format consists of a single line containing a single
 floating point number, which records the frequency offset measured
@@ -1752,7 +2210,7 @@ otherwise, should be avoided.
 .Cm auth | Cm bclient |
 .Cm calibrate | Cm kernel |
 .Cm monitor | Cm ntp |
-.Cm stats
+.Cm pps | Cm stats
 .Oc
 .Xc
 .It Xo Ic disable
@@ -1760,7 +2218,7 @@ otherwise, should be avoided.
 .Cm auth | Cm bclient |
 .Cm calibrate | Cm kernel |
 .Cm monitor | Cm ntp |
-.Cm stats
+.Cm pps | Cm stats
 .Oc
 .Xc
 Provides a way to enable or disable various server options.
@@ -1770,38 +2228,28 @@ can be controlled remotely using the
 .Xr ntpdc 8
 utility program.
 .Bl -tag -width indent
+.It Cm auth
+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 .
 .It Cm bclient
-When enabled, this is identical to the
-.Ic broadcastclient
-command.
-The default for this flag is
+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 .
 .It Cm calibrate
-Enables the calibration facility, which automatically adjusts
-the
-.Ic time1
-values for each clock driver to display the same
-offset as the currently selected source or kernel discipline
-signal.
-See the
-.Qq "Reference Clock Drivers"
-page
-for further information.
-The default for this flag is
+Enables the calibrate feature for reference clocks. The default for
+this flag is
 .Ic disable .
 .It Cm kernel
-Enables the precision-time kernel support for the
-.Xr adjtime 2
-system call, if implemented.
-Ordinarily,
-support for this routine is detected automatically when the NTP
-daemon is compiled, so it is not necessary for the user to worry
-about this flag.
-It is provided primarily so that this support
-can be disabled during kernel development.
-The default for this
+Enables the kernel time discipline, if available. The default for this
 flag is
-.Ic enable .
+.Ic enable
+if support is available, otherwise
+.Ic disable .
 .It Cm monitor
 Enables the monitoring facility.
 See the
@@ -1814,29 +2262,37 @@ The
 default for this flag is
 .Ic enable .
 .It Cm ntp
-Enables the server to adjust its local clock by means of NTP.
-If disabled, the local clock free-runs at its intrinsic time and
-frequency offset.
-This flag is useful in case the local clock is
-controlled by some other device or protocol and NTP is used only to
-provide synchronization to other clients.
-In this case, the local
-clock driver can be used to provide this function and also certain
-time variables for error estimates and leap-indicators.
-See the
-.Qq "Reference Clock Drivers"
-page for further
-information.
-The default for this flag is
+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 .
+.It Cm pps
+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 .
 .It Cm stats
 Enables the statistics facility.
 See the
-.Qq "Monitoring Options"
-page for further information.
+.Sx Monitoring Options
+section for further information.
 The default for this flag is
-.Ic enable .
+.Ic disable .
 .El
+.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
+.Xr ntpd 8
+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
@@ -1873,33 +2329,33 @@ and
 .Cm sync
 .Pc .
 Within these classes four types of messages can be
-controlled.
-Informational messages
-.Pq Cm info
-control configuration
-information.
-Event messages
-.Pq Cm events
-control logging of
-events (reachability, synchronization, alarm conditions).
-Statistical output is controlled with the
+controlled: informational messages
+.Po
+.Cm info
+.Pc ,
+event messages
+.Po
+.Cm events
+.Pc ,
+statistics messages
+.Po
 .Cm statistics
-keyword.
-The final message group is the status messages.
-This
-describes mainly the synchronizations status.
-Configuration
-keywords are formed by concatenating the message class with the
-event class.
-The
+.Pc
+and
+status messages
+.Po
+.Cm status
+.Pc .
+.Pp
+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
+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:
+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
@@ -1921,7 +2377,7 @@ peers, system events and so on is suppressed.
 This command specifies the location of an alternate log file to
 be used instead of the default system
 .Xr syslog 3
-facility.
+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
@@ -1962,13 +2418,13 @@ the names of all peer variables and the
 holds the names of the reference clock variables.
 .It Xo Ic tinker
 .Oo
-.Cm step Ar step |
-.Cm panic Ar panic |
-.Cm dispersion Ar dispersion |
-.Cm stepout Ar stepout |
-.Cm minpoll Ar minpoll |
 .Cm allan Ar allan |
-.Cm huffpuff Ar huffpuff
+.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
@@ -1988,47 +2444,21 @@ for them.
 Emphasis added: twisters are on their own and can expect
 no help from the support group.
 .Pp
-All arguments are in floating point seconds or seconds per
-second.
-The
-.Ar minpoll
-argument is an integer in seconds to
-the power of two.
 The variables operate as follows:
 .Bl -tag -width indent
-.It Cm step Ar step
-The argument becomes the new value for the step threshold,
-normally 0.128 s.
-If set to zero, step adjustments will never
-occur.
-In general, if the intent is only to avoid step adjustments,
-the step threshold should be left alone and the
-.Fl x
-command
-line option be used instead.
-.It Cm panic Ar panic
-The argument becomes the new value for 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.
-.It Cm dispersion Ar dispersion
-The argument becomes the new value for the dispersion increase
-rate, normally .000015.
-.It Cm stepout Ar stepout
-The argument becomes the new value for the watchdog timeout,
-normally 900 s.
-.It Cm minpoll Ar minpoll
-The argument becomes the new value for the minimum poll
-interval used when configuring multicast client, manycast client
-and , symmetric passive mode association.
-The value defaults to 6
-(64 s) and has a lower limit of 4 (16 s).
 .It Cm allan Ar allan
 The argument becomes the new value for the minimum Allan
 intercept, which is a parameter of the PLL/FLL clock discipline
 algorithm.
-The value defaults to 1024 s, which is also the lower
+The value in log2 seconds defaults to 7 (1024 s), which is also the lower
 limit.
+.It Cm dispersion Ar dispersion
+The argument becomes the new value for the dispersion increase rate,
+normally .000015 s/s.
+.It Cm freq Ar freq
+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.
 .It Cm huffpuff Ar huffpuff
 The argument becomes the new value for the experimental
 huff-n'-puff filter span, which determines the most recent interval
@@ -2038,6 +2468,20 @@ The lower limit is
 There
 is no default, since the filter is not enabled unless this command
 is given.
+.It Cm panic Ar panic
+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.
+.It Cm step Ar step
+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.
+.It Cm stepout Ar stepout
+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.
 .El
 .It Xo Ic trap Ar host_address
 .Op Cm port Ar port_number
@@ -2060,6 +2504,11 @@ 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.
 .El
 .Sh FILES
 .Bl -tag -width /etc/ntp.drift -compact