3280 lines
100 KiB
Groff
3280 lines
100 KiB
Groff
.Dd August 14 2018
|
|
.Dt NTP_CONF 5 File Formats
|
|
.Os
|
|
.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" It has been AutoGen-ed August 14, 2018 at 08:29:15 AM by AutoGen 5.18.5
|
|
.\" From the definitions ntp.conf.def
|
|
.\" and the template file agmdoc-cmd.tpl
|
|
.Sh NAME
|
|
.Nm ntp.conf
|
|
.Nd Network Time Protocol (NTP) daemon configuration file format
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl \-option\-name
|
|
.Op Fl \-option\-name Ar value
|
|
.Pp
|
|
All arguments must be options.
|
|
.Pp
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
configuration file is read at initial startup by the
|
|
.Xr ntpd 8
|
|
daemon in order to specify the synchronization sources,
|
|
modes and other related information.
|
|
Usually, it is installed in the
|
|
.Pa /etc
|
|
directory,
|
|
but could be installed elsewhere
|
|
(see the daemon's
|
|
.Fl c
|
|
command line option).
|
|
.Pp
|
|
The file format is similar to other
|
|
.Ux
|
|
configuration files.
|
|
Comments begin with a
|
|
.Ql #
|
|
character and extend to the end of the line;
|
|
blank lines are ignored.
|
|
Configuration commands consist of an initial keyword
|
|
followed by a list of arguments,
|
|
some of which may be optional, separated by whitespace.
|
|
Commands may not be continued over multiple lines.
|
|
Arguments may be host names,
|
|
host addresses written in numeric, dotted\-quad form,
|
|
integers, floating point numbers (when specifying times in seconds)
|
|
and text strings.
|
|
.Pp
|
|
The rest of this page describes the configuration and control options.
|
|
The
|
|
.Qq Notes on Configuring NTP and Setting up an NTP Subnet
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp )
|
|
contains an extended discussion of these options.
|
|
In addition to the discussion of general
|
|
.Sx Configuration Options ,
|
|
there are sections describing the following supported functionality
|
|
and the options used to control it:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
.Sx Authentication Support
|
|
.It
|
|
.Sx Monitoring Support
|
|
.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
|
|
.Sx Miscellaneous Options .
|
|
While there is a rich set of options available,
|
|
the only required option is one or more
|
|
.Ic pool ,
|
|
.Ic server ,
|
|
.Ic peer ,
|
|
.Ic broadcast
|
|
or
|
|
.Ic manycastclient
|
|
commands.
|
|
.Sh Configuration Support
|
|
Following is a description of the configuration commands in
|
|
NTPv4.
|
|
These commands have the same basic functions as in NTPv3 and
|
|
in some cases new functions and new arguments.
|
|
There are two
|
|
classes of commands, configuration commands that configure a
|
|
persistent association with a remote server or peer or reference
|
|
clock, and auxiliary commands that specify environmental variables
|
|
that control various related operations.
|
|
.Ss Configuration Commands
|
|
The various modes are determined by the command keyword and the
|
|
type of the required IP address.
|
|
Addresses are classed by type as
|
|
(s) a remote server or peer (IPv4 class A, B and C), (b) the
|
|
broadcast address of a local interface, (m) a multicast address (IPv4
|
|
class D), or (r) a reference clock address (127.127.x.x).
|
|
Note that
|
|
only those options applicable to each command are listed below.
|
|
Use
|
|
of options not listed may not be caught as an error, but may result
|
|
in some weird and even destructive behavior.
|
|
.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
|
|
.Cm reslist
|
|
billboard generated
|
|
by
|
|
.Xr ntpq 8
|
|
or
|
|
.Xr ntpdc 8 ,
|
|
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 pool Ar address
|
|
.Op Cm burst
|
|
.Op Cm iburst
|
|
.Op Cm version Ar version
|
|
.Op Cm prefer
|
|
.Op Cm minpoll Ar minpoll
|
|
.Op Cm maxpoll Ar maxpoll
|
|
.Xc
|
|
.It Xo Ic server Ar address
|
|
.Op Cm key Ar key \&| Cm autokey
|
|
.Op Cm burst
|
|
.Op Cm iburst
|
|
.Op Cm version Ar version
|
|
.Op Cm prefer
|
|
.Op Cm minpoll Ar minpoll
|
|
.Op Cm maxpoll Ar maxpoll
|
|
.Op Cm true
|
|
.Xc
|
|
.It Xo Ic peer Ar address
|
|
.Op Cm key Ar key \&| Cm autokey
|
|
.Op Cm version Ar version
|
|
.Op Cm prefer
|
|
.Op Cm minpoll Ar minpoll
|
|
.Op Cm maxpoll Ar maxpoll
|
|
.Op Cm true
|
|
.Op Cm xleave
|
|
.Xc
|
|
.It Xo Ic broadcast Ar address
|
|
.Op Cm key Ar key \&| Cm autokey
|
|
.Op Cm version Ar version
|
|
.Op Cm prefer
|
|
.Op Cm minpoll Ar minpoll
|
|
.Op Cm ttl Ar ttl
|
|
.Op Cm xleave
|
|
.Xc
|
|
.It Xo Ic manycastclient Ar address
|
|
.Op Cm key Ar key \&| Cm autokey
|
|
.Op Cm version Ar version
|
|
.Op Cm prefer
|
|
.Op Cm minpoll Ar minpoll
|
|
.Op Cm maxpoll Ar maxpoll
|
|
.Op Cm ttl Ar ttl
|
|
.Xc
|
|
.El
|
|
.Pp
|
|
These five commands specify the time server name or address to
|
|
be used and the mode in which to operate.
|
|
The
|
|
.Ar address
|
|
can be
|
|
either a DNS name or an IP address in dotted\-quad notation.
|
|
Additional information on association behavior can be found in the
|
|
.Qq Association Management
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
.Bl -tag -width indent
|
|
.It Ic pool
|
|
For type s addresses, this command mobilizes a persistent
|
|
client mode association with a number of remote servers.
|
|
In this mode the local clock can synchronized to the
|
|
remote server, but the remote server can never be synchronized to
|
|
the local clock.
|
|
.It Ic server
|
|
For type s and r addresses, this command mobilizes a persistent
|
|
client mode association with the specified remote server or local
|
|
radio clock.
|
|
In this mode the local clock can synchronized to the
|
|
remote server, but the remote server can never be synchronized to
|
|
the local clock.
|
|
This command should
|
|
.Em not
|
|
be used for type
|
|
b or m addresses.
|
|
.It Ic peer
|
|
For type s addresses (only), this command mobilizes a
|
|
persistent symmetric\-active mode association with the specified
|
|
remote peer.
|
|
In this mode the local clock can be synchronized to
|
|
the remote peer or the remote peer can be synchronized to the local
|
|
clock.
|
|
This is useful in a network of servers where, depending on
|
|
various failure scenarios, either the local or remote peer may be
|
|
the better source of time.
|
|
This command should NOT be used for type
|
|
b, m or r addresses.
|
|
.It Ic broadcast
|
|
For type b and m addresses (only), this
|
|
command mobilizes a persistent broadcast mode association.
|
|
Multiple
|
|
commands can be used to specify multiple local broadcast interfaces
|
|
(subnets) and/or multiple multicast groups.
|
|
Note that local
|
|
broadcast messages go only to the interface associated with the
|
|
subnet specified, but multicast messages go to all interfaces.
|
|
In broadcast mode the local server sends periodic broadcast
|
|
messages to a client population at the
|
|
.Ar address
|
|
specified, which is usually the broadcast address on (one of) the
|
|
local network(s) or a multicast address assigned to NTP.
|
|
The IANA
|
|
has assigned the multicast group address IPv4 224.0.1.1 and
|
|
IPv6 ff05::101 (site local) exclusively to
|
|
NTP, but other nonconflicting addresses can be used to contain the
|
|
messages within administrative boundaries.
|
|
Ordinarily, this
|
|
specification applies only to the local server operating as a
|
|
sender; for operation as a broadcast client, see the
|
|
.Ic broadcastclient
|
|
or
|
|
.Ic multicastclient
|
|
commands
|
|
below.
|
|
.It Ic manycastclient
|
|
For type m addresses (only), this command mobilizes a
|
|
manycast client mode association for the multicast address
|
|
specified.
|
|
In this case a specific address must be supplied which
|
|
matches the address used on the
|
|
.Ic manycastserver
|
|
command for
|
|
the designated manycast servers.
|
|
The NTP multicast address
|
|
224.0.1.1 assigned by the IANA should NOT be used, unless specific
|
|
means are taken to avoid spraying large areas of the Internet with
|
|
these messages and causing a possibly massive implosion of replies
|
|
at the sender.
|
|
The
|
|
.Ic manycastserver
|
|
command specifies that the local server
|
|
is to operate in client mode with the remote servers that are
|
|
discovered as the result of broadcast/multicast messages.
|
|
The
|
|
client broadcasts a request message to the group address associated
|
|
with the specified
|
|
.Ar address
|
|
and specifically enabled
|
|
servers respond to these messages.
|
|
The client selects the servers
|
|
providing the best time and continues as with the
|
|
.Ic server
|
|
command.
|
|
The remaining servers are discarded as if never
|
|
heard.
|
|
.El
|
|
.Pp
|
|
Options:
|
|
.Bl -tag -width indent
|
|
.It Cm autokey
|
|
All packets sent to and received from the server or peer are to
|
|
include authentication fields encrypted using the autokey scheme
|
|
described in
|
|
.Sx Authentication Options .
|
|
.It Cm burst
|
|
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
|
|
.Ic 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.
|
|
.It Cm iburst
|
|
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
|
|
.Ic 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
|
|
.Fl q
|
|
option.
|
|
.It Cm key Ar key
|
|
All packets sent to and received from the server or peer are to
|
|
include authentication fields encrypted using the specified
|
|
.Ar key
|
|
identifier with values from 1 to 65535, inclusive.
|
|
The
|
|
default is to include no encryption field.
|
|
.It Cm minpoll Ar minpoll
|
|
.It Cm maxpoll Ar maxpoll
|
|
These options specify the minimum and maximum poll intervals
|
|
for NTP messages, as a power of 2 in seconds
|
|
The maximum poll
|
|
interval defaults to 10 (1,024 s), but can be increased by the
|
|
.Cm maxpoll
|
|
option to an upper limit of 17 (36.4 h).
|
|
The
|
|
minimum poll interval defaults to 6 (64 s), but can be decreased by
|
|
the
|
|
.Cm minpoll
|
|
option to a lower limit of 4 (16 s).
|
|
.It Cm noselect
|
|
Marks the server as unused, except for display purposes.
|
|
The server is discarded by the selection algroithm.
|
|
.It Cm preempt
|
|
Says the association can be preempted.
|
|
.It Cm true
|
|
Marks the server as a truechimer.
|
|
Use this option only for testing.
|
|
.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
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp )
|
|
for further information.
|
|
.It Cm true
|
|
Forces the association to always survive the selection and clustering algorithms.
|
|
This option should almost certainly
|
|
.Em only
|
|
be used while testing an association.
|
|
.It Cm ttl Ar ttl
|
|
This option is used only with broadcast server and manycast
|
|
client modes.
|
|
It specifies the time\-to\-live
|
|
.Ar ttl
|
|
to
|
|
use on broadcast server and multicast server and the maximum
|
|
.Ar ttl
|
|
for the expanding ring search with manycast
|
|
client packets.
|
|
Selection of the proper value, which defaults to
|
|
127, is something of a black art and should be coordinated with the
|
|
network administrator.
|
|
.It Cm version Ar version
|
|
Specifies the version number to be used for outgoing NTP
|
|
packets.
|
|
Versions 1\-4 are the choices, with version 4 the
|
|
default.
|
|
.It Cm xleave
|
|
Valid in
|
|
.Cm peer
|
|
and
|
|
.Cm broadcast
|
|
modes only, this flag enables interleave mode.
|
|
.El
|
|
.Ss Auxiliary Commands
|
|
.Bl -tag -width indent
|
|
.It Ic broadcastclient
|
|
This command enables reception of broadcast server messages to
|
|
any local interface (type b) address.
|
|
Upon receiving a message for
|
|
the first time, the broadcast client measures the nominal server
|
|
propagation delay using a brief client/server exchange with the
|
|
server, then enters the broadcast client mode, in which it
|
|
synchronizes to succeeding broadcast messages.
|
|
Note that, in order
|
|
to avoid accidental or malicious disruption in this mode, both the
|
|
server and client should operate using symmetric\-key or public\-key
|
|
authentication as described in
|
|
.Sx Authentication Options .
|
|
.It Ic manycastserver Ar address ...
|
|
This command enables reception of manycast client messages to
|
|
the multicast group address(es) (type m) specified.
|
|
At least one
|
|
address is required, but the NTP multicast address 224.0.1.1
|
|
assigned by the IANA should NOT be used, unless specific means are
|
|
taken to limit the span of the reply and avoid a possibly massive
|
|
implosion at the original sender.
|
|
Note that, in order to avoid
|
|
accidental or malicious disruption in this mode, both the server
|
|
and client should operate using symmetric\-key or public\-key
|
|
authentication as described in
|
|
.Sx Authentication Options .
|
|
.It Ic multicastclient Ar address ...
|
|
This command enables reception of multicast server messages to
|
|
the multicast group address(es) (type m) specified.
|
|
Upon receiving
|
|
a message for the first time, the multicast client measures the
|
|
nominal server propagation delay using a brief client/server
|
|
exchange with the server, then enters the broadcast client mode, in
|
|
which it synchronizes to succeeding multicast messages.
|
|
Note that,
|
|
in order to avoid accidental or malicious disruption in this mode,
|
|
both the server and client should operate using symmetric\-key or
|
|
public\-key authentication as described in
|
|
.Sx Authentication Options .
|
|
.It Ic mdnstries Ar number
|
|
If we are participating in mDNS,
|
|
after we have synched for the first time
|
|
we attempt to register with the mDNS system.
|
|
If that registration attempt fails,
|
|
we try again at one minute intervals for up to
|
|
.Ic mdnstries
|
|
times.
|
|
After all,
|
|
.Ic ntpd
|
|
may be starting before mDNS.
|
|
The default value for
|
|
.Ic mdnstries
|
|
is 5.
|
|
.El
|
|
.Sh Authentication Support
|
|
Authentication support allows the NTP client to verify that the
|
|
server is in fact known and trusted and not an intruder intending
|
|
accidentally or on purpose to masquerade as that server.
|
|
The NTPv3
|
|
specification RFC\-1305 defines a scheme which provides
|
|
cryptographic authentication of received NTP packets.
|
|
Originally,
|
|
this was done using the Data Encryption Standard (DES) algorithm
|
|
operating in Cipher Block Chaining (CBC) mode, commonly called
|
|
DES\-CBC.
|
|
Subsequently, this was replaced by the RSA Message Digest
|
|
5 (MD5) algorithm using a private key, commonly called keyed\-MD5.
|
|
Either algorithm computes a message digest, or one\-way hash, which
|
|
can be used to verify the server has the correct private key and
|
|
key identifier.
|
|
.Pp
|
|
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
|
|
subcommand on the
|
|
.Ic peer ,
|
|
.Ic server ,
|
|
.Ic broadcast
|
|
and
|
|
.Ic manycastclient
|
|
configuration commands as described in
|
|
.Sx Configuration Options
|
|
page.
|
|
The authentication
|
|
options described below specify the locations of the key files,
|
|
if other than default, which symmetric keys are trusted
|
|
and the interval between various operations, if other than default.
|
|
.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
|
|
flag controls whether new associations or
|
|
remote configuration commands require cryptographic authentication.
|
|
This flag can be set or reset by the
|
|
.Ic enable
|
|
and
|
|
.Ic disable
|
|
commands and also by remote
|
|
configuration commands sent by a
|
|
.Xr ntpdc 8
|
|
program running on
|
|
another machine.
|
|
If this flag is enabled, which is the default
|
|
case, new broadcast client and symmetric passive associations and
|
|
remote configuration commands must be cryptographically
|
|
authenticated using either symmetric key or public key cryptography.
|
|
If this
|
|
flag is disabled, these operations are effective
|
|
even if not cryptographic
|
|
authenticated.
|
|
It should be understood
|
|
that operating with the
|
|
.Ic auth
|
|
flag disabled invites a significant vulnerability
|
|
where a rogue hacker can
|
|
masquerade as a falseticker and seriously
|
|
disrupt system timekeeping.
|
|
It is
|
|
important to note that this flag has no purpose
|
|
other than to allow or disallow
|
|
a new association in response to new broadcast
|
|
and symmetric active messages
|
|
and remote configuration commands and, in particular,
|
|
the flag has no effect on
|
|
the authentication process itself.
|
|
.Pp
|
|
An attractive alternative where multicast support is available
|
|
is manycast mode, in which clients periodically troll
|
|
for servers as described in the
|
|
.Sx Automatic NTP Configuration Options
|
|
page.
|
|
Either symmetric key or public key
|
|
cryptographic authentication can be used in this mode.
|
|
The principle advantage
|
|
of manycast mode is that potential servers need not be
|
|
configured in advance,
|
|
since the client finds them during regular operation,
|
|
and the configuration
|
|
files for all clients can be identical.
|
|
.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,535 keys, each distinguished by a 32\-bit key identifier, to
|
|
authenticate an association.
|
|
The servers and clients involved must
|
|
agree on the key and key identifier to
|
|
authenticate NTP packets.
|
|
Keys and
|
|
related information are specified in a key
|
|
file, usually called
|
|
.Pa ntp.keys ,
|
|
which must be distributed and stored using
|
|
secure means beyond the scope of the NTP protocol itself.
|
|
Besides the keys used
|
|
for ordinary NTP associations,
|
|
additional keys can be used as passwords for the
|
|
.Xr ntpq 8
|
|
and
|
|
.Xr ntpdc 8
|
|
utility programs.
|
|
.Pp
|
|
When
|
|
.Xr ntpd 8
|
|
is first started, it reads the key file specified in the
|
|
.Ic keys
|
|
configuration command and installs the keys
|
|
in the key cache.
|
|
However,
|
|
individual keys must be activated with the
|
|
.Ic trusted
|
|
command before use.
|
|
This
|
|
allows, for instance, the installation of possibly
|
|
several batches of keys and
|
|
then activating or deactivating each batch
|
|
remotely using
|
|
.Xr ntpdc 8 .
|
|
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
|
|
.Xr ntpq 8
|
|
utility.
|
|
.Ss Public Key Cryptography
|
|
NTPv4 supports the original NTPv3 symmetric key scheme
|
|
described in RFC\-1305 and in addition the Autokey protocol,
|
|
which is based on public key cryptography.
|
|
The Autokey Version 2 protocol described on the Autokey Protocol
|
|
page verifies packet integrity using MD5 message digests
|
|
and verifies the source with digital signatures and any of several
|
|
digest/signature schemes.
|
|
Optional identity schemes described on the Identity Schemes
|
|
page and based on cryptographic challenge/response algorithms
|
|
are also available.
|
|
Using all of these schemes provides strong security against
|
|
replay with or without modification, spoofing, masquerade
|
|
and most forms of clogging attacks.
|
|
.\" .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 on the
|
|
.Sx Autonomous Authentication
|
|
page.
|
|
.Pp
|
|
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 1ntpkeygenmdoc
|
|
program.
|
|
This includes a required host key file,
|
|
required certificate file and optional sign key file,
|
|
leapsecond file and identity scheme files.
|
|
The
|
|
digest/signature scheme is specified in the X.509 certificate
|
|
along with the matching sign key.
|
|
There are several schemes
|
|
available in the OpenSSL software library, each identified
|
|
by a specific string such as
|
|
.Cm md5WithRSAEncryption ,
|
|
which stands for the MD5 message digest with RSA
|
|
encryption scheme.
|
|
The current NTP distribution supports
|
|
all the schemes in the OpenSSL library, including
|
|
those based on RSA and DSA digital signatures.
|
|
.Pp
|
|
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
|
|
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
|
|
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 destination 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
|
|
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
|
|
.Xr ntpq 8
|
|
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
|
|
The cryptographic values used by the Autokey protocol are
|
|
incorporated as a set of files generated by the
|
|
.Xr ntp\-keygen 1ntpkeygenmdoc
|
|
utility program, including symmetric key, host key and
|
|
public certificate files, as well as sign key, identity parameters
|
|
and leapseconds files.
|
|
Alternatively, host and sign keys and
|
|
certificate files can be generated by the OpenSSL utilities
|
|
and certificates can be imported from public certificate
|
|
authorities.
|
|
Note that symmetric keys are necessary for the
|
|
.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
|
|
Specifies the interval between regenerations of the session key
|
|
list used with the Autokey protocol.
|
|
Note that the size of the key
|
|
list for each association depends on this interval and the current
|
|
poll interval.
|
|
The default value is 12 (4096 s or about 1.1 hours).
|
|
For poll intervals above the specified interval, a session key list
|
|
with a single entry will be regenerated for every message
|
|
sent.
|
|
.It Ic controlkey Ar key
|
|
Specifies the key identifier to use with the
|
|
.Xr ntpq 8
|
|
utility, which uses the standard
|
|
protocol defined in RFC\-1305.
|
|
The
|
|
.Ar key
|
|
argument is
|
|
the key identifier for a trusted key, where the value can be in the
|
|
range 1 to 65,535, inclusive.
|
|
.It Xo Ic crypto
|
|
.Op Cm cert Ar file
|
|
.Op Cm leap Ar file
|
|
.Op Cm randfile Ar file
|
|
.Op Cm host Ar file
|
|
.Op Cm sign Ar file
|
|
.Op Cm gq Ar file
|
|
.Op Cm gqpar Ar file
|
|
.Op Cm iffpar Ar file
|
|
.Op Cm mvpar Ar file
|
|
.Op Cm pw Ar password
|
|
.Xc
|
|
This command requires the OpenSSL library.
|
|
It activates public key
|
|
cryptography, selects the message digest and signature
|
|
encryption scheme and loads the required private and public
|
|
values described above.
|
|
If one or more files are left unspecified,
|
|
the default names are used as described above.
|
|
Unless the complete path and name of the file are specified, the
|
|
location of a file is relative to the keys directory specified
|
|
in the
|
|
.Ic keysdir
|
|
command or default
|
|
.Pa /usr/local/etc .
|
|
Following are the subcommands:
|
|
.Bl -tag -width indent
|
|
.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 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 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 with symmetric key cryptography.
|
|
This is the same operation as the
|
|
.Fl k
|
|
command line option.
|
|
.It Ic keysdir Ar path
|
|
This command specifies the default directory path for
|
|
cryptographic keys, parameters and certificates.
|
|
The default is
|
|
.Pa /usr/local/etc/ .
|
|
.It Ic requestkey Ar key
|
|
Specifies the key identifier to use with the
|
|
.Xr ntpdc 8
|
|
utility program, which uses a
|
|
proprietary protocol specific to this implementation of
|
|
.Xr ntpd 8 .
|
|
The
|
|
.Ar key
|
|
argument is a key identifier
|
|
for the trusted key, where the value can be in the range 1 to
|
|
65,535, inclusive.
|
|
.It Ic revoke Ar logsec
|
|
Specifies the interval between re\-randomization of certain
|
|
cryptographic values used by the Autokey scheme, as a power of 2 in
|
|
seconds.
|
|
These values need to be updated frequently in order to
|
|
deflect brute\-force attacks on the algorithms of the scheme;
|
|
however, updating some values is a relatively expensive operation.
|
|
The default interval is 16 (65,536 s or about 18 hours).
|
|
For poll
|
|
intervals above the specified interval, the values will be updated
|
|
for every message sent.
|
|
.It Ic trustedkey Ar key ...
|
|
Specifies the key identifiers which are trusted for the
|
|
purposes of authenticating peers with symmetric key cryptography,
|
|
as well as keys used by the
|
|
.Xr ntpq 8
|
|
and
|
|
.Xr ntpdc 8
|
|
programs.
|
|
The authentication procedures require that both the local
|
|
and remote servers share the same key and key identifier for this
|
|
purpose, although different keys can be used with different
|
|
servers.
|
|
The
|
|
.Ar key
|
|
arguments are 32\-bit unsigned
|
|
integers with values from 1 to 65,535.
|
|
.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
|
|
for continuous, long term recording of server and client
|
|
timekeeping performance.
|
|
See the
|
|
.Ic statistics
|
|
command below
|
|
for a listing and example of each type of statistics currently
|
|
supported.
|
|
Statistic files are managed using file generation sets
|
|
and scripts in the
|
|
.Pa ./scripts
|
|
directory of the source code distribution.
|
|
Using
|
|
these facilities and
|
|
.Ux
|
|
.Xr cron 8
|
|
jobs, the data can be
|
|
automatically summarized and archived for retrospective analysis.
|
|
.Ss Monitoring Commands
|
|
.Bl -tag -width indent
|
|
.It Ic statistics Ar name ...
|
|
Enables writing of statistics records.
|
|
Currently, eight 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
|
|
.Cm loopstats :
|
|
.Bd -literal
|
|
50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
|
|
.Ed
|
|
.Pp
|
|
The first two fields show the date (Modified Julian Day) and
|
|
time (seconds and fraction past UTC midnight).
|
|
The next five fields
|
|
show time offset (seconds), frequency offset (parts per million \-
|
|
PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
|
|
discipline time constant.
|
|
.It Cm peerstats
|
|
Enables recording of peer statistics information.
|
|
This includes
|
|
statistics records of all peers of a NTP server and of special
|
|
signals, where present and configured.
|
|
Each valid update appends a
|
|
line of the following form to the current element of a file
|
|
generation set named
|
|
.Cm peerstats :
|
|
.Bd -literal
|
|
48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
|
|
.Ed
|
|
.Pp
|
|
The first two fields show the date (Modified Julian Day) and
|
|
time (seconds and fraction past UTC midnight).
|
|
The next two fields
|
|
show the peer address in dotted\-quad notation and status,
|
|
respectively.
|
|
The status field is encoded in hex in the format
|
|
described in Appendix A of the NTP specification RFC 1305.
|
|
The final four fields show the offset,
|
|
delay, dispersion and RMS jitter, all in seconds.
|
|
.It Cm rawstats
|
|
Enables recording of raw\-timestamp statistics information.
|
|
This
|
|
includes statistics records of all peers of a NTP server and of
|
|
special signals, where present and configured.
|
|
Each NTP message
|
|
received from a peer or clock driver appends a line of the
|
|
following form to the file generation set named
|
|
.Cm rawstats :
|
|
.Bd -literal
|
|
50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
|
|
.Ed
|
|
.Pp
|
|
The first two fields show the date (Modified Julian Day) and
|
|
time (seconds and fraction past UTC midnight).
|
|
The next two fields
|
|
show the remote peer or clock address followed by the local address
|
|
in dotted\-quad notation.
|
|
The final four fields show the originate,
|
|
receive, transmit and final NTP timestamps in order.
|
|
The timestamp
|
|
values are as received and before processing by the various data
|
|
smoothing and mitigation algorithms.
|
|
.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 Cm statsdir Ar directory_path
|
|
Indicates the full path of a directory where statistics files
|
|
should be created (see below).
|
|
This keyword allows
|
|
the (otherwise constant)
|
|
.Cm filegen
|
|
filename prefix to be modified for file generation sets, which
|
|
is useful for handling statistics logs.
|
|
.It Cm filegen Ar name Xo
|
|
.Op Cm file Ar filename
|
|
.Op Cm type Ar typename
|
|
.Op Cm link | nolink
|
|
.Op Cm enable | disable
|
|
.Xc
|
|
Configures setting of generation file set name.
|
|
Generation
|
|
file sets provide a means for handling files that are
|
|
continuously growing during the lifetime of a server.
|
|
Server statistics are a typical example for such files.
|
|
Generation file sets provide access to a set of files used
|
|
to store the actual data.
|
|
At any time at most one element
|
|
of the set is being written to.
|
|
The type given specifies
|
|
when and how data will be directed to a new element of the set.
|
|
This way, information stored in elements of a file set
|
|
that are currently unused are available for administrational
|
|
operations without the risk of disturbing the operation of ntpd.
|
|
(Most important: they can be removed to free space for new data
|
|
produced.)
|
|
.Pp
|
|
Note that this command can be sent from the
|
|
.Xr ntpdc 8
|
|
program running at a remote location.
|
|
.Bl -tag -width indent
|
|
.It Cm name
|
|
This is the type of the statistics records, as shown in the
|
|
.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
|
|
.Ar Cm prefix ,
|
|
.Ar Cm filename
|
|
and
|
|
.Ar Cm suffix :
|
|
.Bl -tag -width indent
|
|
.It Cm prefix
|
|
This is a constant filename path.
|
|
It is not subject to
|
|
modifications via the
|
|
.Ar filegen
|
|
option.
|
|
It is defined by the
|
|
server, usually specified as a compile\-time constant.
|
|
It may,
|
|
however, be configurable for individual file generation sets
|
|
via other commands.
|
|
For example, the prefix used with
|
|
.Ar loopstats
|
|
and
|
|
.Ar peerstats
|
|
generation can be configured using the
|
|
.Ar statsdir
|
|
option explained above.
|
|
.It Cm filename
|
|
This string is directly concatenated to the prefix mentioned
|
|
above (no intervening
|
|
.Ql / ) .
|
|
This can be modified using
|
|
the file argument to the
|
|
.Ar filegen
|
|
statement.
|
|
No
|
|
.Pa ..
|
|
elements are
|
|
allowed in this component to prevent filenames referring to
|
|
parts outside the filesystem hierarchy denoted by
|
|
.Ar prefix .
|
|
.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:
|
|
.Bl -tag -width indent
|
|
.It Cm none
|
|
The file set is actually a single plain file.
|
|
.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
|
|
.Ql \&.
|
|
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 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 \&.
|
|
and a day specification in
|
|
the form
|
|
.Cm YYYYMMdd .
|
|
.Cm YYYY
|
|
is a 4\-digit year number (e.g., 1992).
|
|
.Cm MM
|
|
is a two digit month number.
|
|
.Cm dd
|
|
is a two digit day number.
|
|
Thus, all information written at 10 December 1992 would end up
|
|
in a file named
|
|
.Ar prefix
|
|
.Ar filename Ns .19921210 .
|
|
.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
|
|
.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 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
|
|
suffix consists of a dot, the letter
|
|
.Cm a ,
|
|
and an 8\-digit number.
|
|
This number is taken to be the number of seconds the server is
|
|
running at the start of the corresponding 24\-hour period.
|
|
Information is only written to a file generation by specifying
|
|
.Cm enable ;
|
|
output is prevented by specifying
|
|
.Cm disable .
|
|
.El
|
|
.It Cm link | nolink
|
|
It is convenient to be able to access the current element of a file
|
|
generation set by a fixed name.
|
|
This feature is enabled by
|
|
specifying
|
|
.Cm link
|
|
and disabled using
|
|
.Cm nolink .
|
|
If link is specified, a
|
|
hard link from the current file set element to a file without
|
|
suffix is created.
|
|
When there is already a file with this name and
|
|
the number of links of this file is one, it is renamed appending a
|
|
dot, the letter
|
|
.Cm C ,
|
|
and the pid of the
|
|
.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.
|
|
.It Cm enable \&| Cm disable
|
|
Enables or disables the recording function.
|
|
.El
|
|
.El
|
|
.El
|
|
.Sh Access Control Support
|
|
The
|
|
.Xr ntpd 8
|
|
daemon implements a general purpose address/mask based restriction
|
|
list.
|
|
The list contains address/match entries sorted first
|
|
by increasing address values and and then by increasing mask values.
|
|
A match occurs when the bitwise AND of the mask and the packet
|
|
source address is equal to the bitwise AND of the mask and
|
|
address in the list.
|
|
The list is searched in order with the
|
|
last match found defining the restriction flags associated
|
|
with the entry.
|
|
Additional information and examples can be found in the
|
|
.Qq Notes on Configuring NTP and Setting up a NTP Subnet
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
.Pp
|
|
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
|
|
.Ic 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 indefinite period.
|
|
When a client or network is denied access
|
|
for an indefinite period, the only way at present to remove
|
|
the restrictions is by restarting the server.
|
|
.Ss The Kiss\-of\-Death Packet
|
|
Ordinarily, packets denied service are simply dropped with no
|
|
further action except incrementing statistics counters.
|
|
Sometimes a
|
|
more proactive response is needed, such as a server message that
|
|
explicitly requests the client to stop sending and leave a message
|
|
for the system operator.
|
|
A special packet format has been created
|
|
for this purpose called the "kiss\-of\-death" (KoD) packet.
|
|
KoD packets have the leap bits set unsynchronized and stratum set
|
|
to zero and the reference identifier field set to a four\-byte
|
|
ASCII code.
|
|
If the
|
|
.Cm noserve
|
|
or
|
|
.Cm notrust
|
|
flag of the matching restrict list entry is set,
|
|
the code is "DENY"; if the
|
|
.Cm limited
|
|
flag is set and the rate limit
|
|
is exceeded, the code is "RATE".
|
|
Finally, if a cryptographic violation occurs, the code is "CRYP".
|
|
.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 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
|
|
.Ic 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 Cm ippeerlimit Ar int
|
|
.Op Ar flag ...
|
|
.Xc
|
|
The
|
|
.Ar address
|
|
argument expressed in
|
|
dotted\-quad form is the address of a host or network.
|
|
Alternatively, the
|
|
.Ar address
|
|
argument can be a valid host DNS name.
|
|
The
|
|
.Ar mask
|
|
argument expressed in dotted\-quad form defaults to
|
|
.Cm 255.255.255.255 ,
|
|
meaning that the
|
|
.Ar address
|
|
is treated as the address of an individual host.
|
|
A default entry (address
|
|
.Cm 0.0.0.0 ,
|
|
mask
|
|
.Cm 0.0.0.0 )
|
|
is always included and is always the first entry in the list.
|
|
Note that text string
|
|
.Cm default ,
|
|
with no mask option, may
|
|
be used to indicate the default entry.
|
|
The
|
|
.Cm ippeerlimit
|
|
directive limits the number of peer requests for each IP to
|
|
.Ar int ,
|
|
where a value of \-1 means "unlimited", the current default.
|
|
A value of 0 means "none".
|
|
There would usually be at most 1 peering request per IP,
|
|
but if the remote peering requests are behind a proxy
|
|
there could well be more than 1 per IP.
|
|
In the current implementation,
|
|
.Cm flag
|
|
always
|
|
restricts access, i.e., an entry with no flags indicates that free
|
|
access to the server is to be given.
|
|
The flags are not orthogonal,
|
|
in that more restrictive flags will often make less restrictive
|
|
ones redundant.
|
|
The flags can generally be classed into two
|
|
categories, those which restrict time service and those which
|
|
restrict informational queries and attempts to do run\-time
|
|
reconfiguration of the server.
|
|
One or more of the following flags
|
|
may be specified:
|
|
.Bl -tag -width indent
|
|
.It Cm ignore
|
|
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
|
|
.Ic 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
|
|
number of traps a server can maintain is limited (the current limit
|
|
is 3).
|
|
Traps are usually assigned on a first come, first served
|
|
basis, with later trap requestors being denied service.
|
|
This flag
|
|
modifies the assignment algorithm by allowing low priority traps to
|
|
be overridden by later requests for normal priority traps.
|
|
.It Cm noepeer
|
|
Deny ephemeral peer requests,
|
|
even if they come from an authenticated source.
|
|
Note that the ability to use a symmetric key for authentication may be restricted to
|
|
one or more IPs or subnets via the third field of the
|
|
.Pa ntp.keys
|
|
file.
|
|
This restriction is not enabled by default,
|
|
to maintain backward compatability.
|
|
Expect
|
|
.Cm noepeer
|
|
to become the default in ntp\-4.4.
|
|
.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
|
|
Deny unauthenticated packets which would result in mobilizing a new association.
|
|
This includes
|
|
broadcast and symmetric active packets
|
|
when a configured association does not exist.
|
|
It also includes
|
|
.Cm pool
|
|
associations, so if you want to use servers from a
|
|
.Cm pool
|
|
directive and also want to use
|
|
.Cm nopeer
|
|
by default, you'll want a
|
|
.Cm "restrict source ..."
|
|
line as well that does
|
|
.Em not
|
|
include the
|
|
.Cm nopeer
|
|
directive.
|
|
.It Cm noserve
|
|
Deny all packets except
|
|
.Xr ntpq 8
|
|
and
|
|
.Xr ntpdc 8
|
|
queries.
|
|
.It Cm notrap
|
|
Decline to provide mode 6 control message trap service to matching
|
|
hosts.
|
|
The trap service is a subsystem of the
|
|
.Xr ntpq 8
|
|
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.
|
|
Its presence causes the restriction entry to be
|
|
matched only if the source port in the packet is the standard NTP
|
|
UDP port (123).
|
|
Both
|
|
.Cm ntpport
|
|
and
|
|
.Cm non\-ntpport
|
|
may
|
|
be specified.
|
|
The
|
|
.Cm ntpport
|
|
is considered more specific and
|
|
is sorted later in the list.
|
|
.It Cm version
|
|
Deny packets that do not match the current NTP version.
|
|
.El
|
|
.Pp
|
|
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
|
|
.Ic manycastclient
|
|
command, which is similar to the
|
|
.Ic 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
|
|
.Ic 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 sntp 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 Broadcast Options
|
|
.Bl -tag -width indent
|
|
.It Xo Ic tos
|
|
.Oo
|
|
.Cm bcpollbstep Ar gate
|
|
.Oc
|
|
.Xc
|
|
This command provides a way to delay,
|
|
by the specified number of broadcast poll intervals,
|
|
believing backward time steps from a broadcast server.
|
|
Broadcast time networks are expected to be trusted.
|
|
In the event a broadcast server's time is stepped backwards,
|
|
there is clear benefit to having the clients notice this change
|
|
as soon as possible.
|
|
Attacks such as replay attacks can happen, however,
|
|
and even though there are a number of protections built in to
|
|
broadcast mode, attempts to perform a replay attack are possible.
|
|
This value defaults to 0, but can be changed
|
|
to any number of poll intervals between 0 and 4.
|
|
.El
|
|
.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 outlier
|
|
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,
|
|
satellite and modem reference clocks plus a special pseudo\-clock
|
|
used for backup or when no other clock source is available.
|
|
Detailed descriptions of individual device drivers and options can
|
|
be found in the
|
|
.Qq Reference Clock Drivers
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
Additional information can be found in the pages linked
|
|
there, including the
|
|
.Qq Debugging Hints for Reference Clock Drivers
|
|
and
|
|
.Qq How To Write a Reference Clock Driver
|
|
pages
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
In addition, support for a PPS
|
|
signal is available as described in the
|
|
.Qq Pulse\-per\-second (PPS) Signal Interfacing
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
Many
|
|
drivers support special line discipline/streams modules which can
|
|
significantly improve the accuracy using the driver.
|
|
These are
|
|
described in the
|
|
.Qq Line Disciplines and Streams Drivers
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
.Pp
|
|
A reference clock will generally (though not always) be a radio
|
|
timecode receiver which is synchronized to a source of standard
|
|
time such as the services offered by the NRC in Canada and NIST and
|
|
USNO in the US.
|
|
The interface between the computer and the timecode
|
|
receiver is device dependent, but is usually a serial port.
|
|
A
|
|
device driver specific to each reference clock must be selected and
|
|
compiled in the distribution; however, most common radio, satellite
|
|
and modem clocks are included by default.
|
|
Note that an attempt to
|
|
configure a reference clock when the driver has not been compiled
|
|
or the hardware port has not been appropriately configured results
|
|
in a scalding remark to the system log file, but is otherwise non
|
|
hazardous.
|
|
.Pp
|
|
For the purposes of configuration,
|
|
.Xr ntpd 8
|
|
treats
|
|
reference clocks in a manner analogous to normal NTP peers as much
|
|
as possible.
|
|
Reference clocks are identified by a syntactically
|
|
correct but invalid IP address, in order to distinguish them from
|
|
normal NTP peers.
|
|
Reference clock addresses are of the form
|
|
.Sm off
|
|
.Li 127.127. Ar t . Ar u ,
|
|
.Sm on
|
|
where
|
|
.Ar t
|
|
is an integer
|
|
denoting the clock type and
|
|
.Ar u
|
|
indicates the unit
|
|
number in the range 0\-3.
|
|
While it may seem overkill, it is in fact
|
|
sometimes useful to configure multiple reference clocks of the same
|
|
type, in which case the unit numbers must be unique.
|
|
.Pp
|
|
The
|
|
.Ic server
|
|
command is used to configure a reference
|
|
clock, where the
|
|
.Ar address
|
|
argument in that command
|
|
is the clock address.
|
|
The
|
|
.Cm key ,
|
|
.Cm version
|
|
and
|
|
.Cm ttl
|
|
options are not used for reference clock support.
|
|
The
|
|
.Cm mode
|
|
option is added for reference clock support, as
|
|
described below.
|
|
The
|
|
.Cm prefer
|
|
option can be useful to
|
|
persuade the server to cherish a reference clock with somewhat more
|
|
enthusiasm than other reference clocks or peers.
|
|
Further
|
|
information on this option can be found in the
|
|
.Qq Mitigation Rules and the prefer Keyword
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp )
|
|
page.
|
|
The
|
|
.Cm minpoll
|
|
and
|
|
.Cm maxpoll
|
|
options have
|
|
meaning only for selected clock drivers.
|
|
See the individual clock
|
|
driver document pages for additional information.
|
|
.Pp
|
|
The
|
|
.Ic fudge
|
|
command is used to provide additional
|
|
information for individual clock drivers and normally follows
|
|
immediately after the
|
|
.Ic server
|
|
command.
|
|
The
|
|
.Ar address
|
|
argument specifies the clock address.
|
|
The
|
|
.Cm refid
|
|
and
|
|
.Cm stratum
|
|
options can be used to
|
|
override the defaults for the device.
|
|
There are two optional
|
|
device\-dependent time offsets and four flags that can be included
|
|
in the
|
|
.Ic fudge
|
|
command as well.
|
|
.Pp
|
|
The stratum number of a reference clock is by default zero.
|
|
Since the
|
|
.Xr ntpd 8
|
|
daemon adds one to the stratum of each
|
|
peer, a primary server ordinarily displays an external stratum of
|
|
one.
|
|
In order to provide engineered backups, it is often useful to
|
|
specify the reference clock stratum as greater than zero.
|
|
The
|
|
.Cm stratum
|
|
option is used for this purpose.
|
|
Also, in cases
|
|
involving both a reference clock and a pulse\-per\-second (PPS)
|
|
discipline signal, it is useful to specify the reference clock
|
|
identifier as other than the default, depending on the driver.
|
|
The
|
|
.Cm refid
|
|
option is used for this purpose.
|
|
Except where noted,
|
|
these options apply to all clock drivers.
|
|
.Ss Reference Clock Commands
|
|
.Bl -tag -width indent
|
|
.It Xo Ic server
|
|
.Sm off
|
|
.Li 127.127. Ar t . Ar u
|
|
.Sm on
|
|
.Op Cm prefer
|
|
.Op Cm mode Ar int
|
|
.Op Cm minpoll Ar int
|
|
.Op Cm maxpoll Ar int
|
|
.Xc
|
|
This command can be used to configure reference clocks in
|
|
special ways.
|
|
The options are interpreted as follows:
|
|
.Bl -tag -width indent
|
|
.It Cm prefer
|
|
Marks the reference clock as preferred.
|
|
All other things being
|
|
equal, this host will be chosen for synchronization among a set of
|
|
correctly operating hosts.
|
|
See the
|
|
.Qq Mitigation Rules and the prefer Keyword
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp )
|
|
for further information.
|
|
.It Cm mode Ar int
|
|
Specifies a mode number which is interpreted in a
|
|
device\-specific fashion.
|
|
For instance, it selects a dialing
|
|
protocol in the ACTS driver and a device subtype in the
|
|
parse
|
|
drivers.
|
|
.It Cm minpoll Ar int
|
|
.It Cm maxpoll Ar int
|
|
These options specify the minimum and maximum polling interval
|
|
for reference clock messages, as a power of 2 in seconds
|
|
For
|
|
most directly connected reference clocks, both
|
|
.Cm minpoll
|
|
and
|
|
.Cm maxpoll
|
|
default to 6 (64 s).
|
|
For modem reference clocks,
|
|
.Cm minpoll
|
|
defaults to 10 (17.1 m) and
|
|
.Cm maxpoll
|
|
defaults to 14 (4.5 h).
|
|
The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
|
|
.El
|
|
.It Xo Ic fudge
|
|
.Sm off
|
|
.Li 127.127. Ar t . Ar u
|
|
.Sm on
|
|
.Op Cm time1 Ar sec
|
|
.Op Cm time2 Ar sec
|
|
.Op Cm stratum Ar int
|
|
.Op Cm refid Ar string
|
|
.Op Cm mode Ar int
|
|
.Op Cm flag1 Cm 0 \&| Cm 1
|
|
.Op Cm flag2 Cm 0 \&| Cm 1
|
|
.Op Cm flag3 Cm 0 \&| Cm 1
|
|
.Op Cm flag4 Cm 0 \&| Cm 1
|
|
.Xc
|
|
This command can be used to configure reference clocks in
|
|
special ways.
|
|
It must immediately follow the
|
|
.Ic server
|
|
command which configures the driver.
|
|
Note that the same capability
|
|
is possible at run time using the
|
|
.Xr ntpdc 8
|
|
program.
|
|
The options are interpreted as
|
|
follows:
|
|
.Bl -tag -width indent
|
|
.It Cm time1 Ar sec
|
|
Specifies a constant to be added to the time offset produced by
|
|
the driver, a fixed\-point decimal number in seconds.
|
|
This is used
|
|
as a calibration constant to adjust the nominal time offset of a
|
|
particular clock to agree with an external standard, such as a
|
|
precision PPS signal.
|
|
It also provides a way to correct a
|
|
systematic error or bias due to serial port or operating system
|
|
latencies, different cable lengths or receiver internal delay.
|
|
The
|
|
specified offset is in addition to the propagation delay provided
|
|
by other means, such as internal DIPswitches.
|
|
Where a calibration
|
|
for an individual system and driver is available, an approximate
|
|
correction is noted in the driver documentation pages.
|
|
Note: in order to facilitate calibration when more than one
|
|
radio clock or PPS signal is supported, a special calibration
|
|
feature is available.
|
|
It takes the form of an argument to the
|
|
.Ic enable
|
|
command described in
|
|
.Sx Miscellaneous Options
|
|
page and operates as described in the
|
|
.Qq Reference Clock Drivers
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
.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
|
|
(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.
|
|
This number overrides the default stratum number
|
|
ordinarily assigned by the driver itself, usually zero.
|
|
.It Cm refid Ar string
|
|
Specifies an ASCII string of from one to four characters which
|
|
defines the reference identifier used by the driver.
|
|
This string
|
|
overrides the default identifier ordinarily assigned by the driver
|
|
itself.
|
|
.It Cm mode Ar int
|
|
Specifies a mode number which is interpreted in a
|
|
device\-specific fashion.
|
|
For instance, it selects a dialing
|
|
protocol in the ACTS driver and a device subtype in the
|
|
parse
|
|
drivers.
|
|
.It Cm flag1 Cm 0 \&| Cm 1
|
|
.It Cm flag2 Cm 0 \&| Cm 1
|
|
.It Cm flag3 Cm 0 \&| Cm 1
|
|
.It Cm flag4 Cm 0 \&| Cm 1
|
|
These four flags are used for customizing the clock driver.
|
|
The
|
|
interpretation of these values, and whether they are used at all,
|
|
is a function of the particular clock driver.
|
|
However, by
|
|
convention
|
|
.Cm flag4
|
|
is used to enable recording monitoring
|
|
data to the
|
|
.Cm clockstats
|
|
file configured with the
|
|
.Ic filegen
|
|
command.
|
|
Further information on the
|
|
.Ic filegen
|
|
command can be found in
|
|
.Sx Monitoring Options .
|
|
.El
|
|
.El
|
|
.Sh Miscellaneous Options
|
|
.Bl -tag -width indent
|
|
.It Ic broadcastdelay Ar seconds
|
|
The broadcast and multicast modes require a special calibration
|
|
to determine the network delay between the local and remote
|
|
servers.
|
|
Ordinarily, this is done automatically by the initial
|
|
protocol exchanges between the client and server.
|
|
In some cases,
|
|
the calibration procedure may fail due to network or server access
|
|
controls, for example.
|
|
This command specifies the default delay to
|
|
be used under these circumstances.
|
|
Typically (for Ethernet), a
|
|
number between 0.003 and 0.007 seconds is appropriate.
|
|
The default
|
|
when this command is not used is 0.004 seconds.
|
|
.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 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 line option.
|
|
If the file exists, it is read at
|
|
startup in order to set the initial frequency and then updated once per
|
|
hour with the current frequency computed by the daemon.
|
|
If the file name is
|
|
specified, but the file itself does not exist, the starts with an initial
|
|
frequency of zero and creates the file when writing it for the first time.
|
|
If this command is not given, the daemon will always start with an initial
|
|
frequency of zero.
|
|
.Pp
|
|
The file format consists of a single line containing a single
|
|
floating point number, which records the frequency offset measured
|
|
in parts\-per\-million (PPM).
|
|
The file is updated by first writing
|
|
the current drift value into a temporary file and then renaming
|
|
this file to replace the old version.
|
|
This implies that
|
|
.Xr ntpd 8
|
|
must have write permission for the directory the
|
|
drift file is located in, and that file system links, symbolic or
|
|
otherwise, should be avoided.
|
|
.It Ic dscp Ar value
|
|
This option specifies the Differentiated Services Control Point (DSCP) value,
|
|
a 6\-bit code.
|
|
The default value is 46, signifying Expedited Forwarding.
|
|
.It Xo Ic enable
|
|
.Oo
|
|
.Cm auth | Cm bclient |
|
|
.Cm calibrate | Cm kernel |
|
|
.Cm mode7 | Cm monitor |
|
|
.Cm ntp | Cm stats |
|
|
.Cm peer_clear_digest_early |
|
|
.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
|
|
.Oc
|
|
.Xc
|
|
.It Xo Ic disable
|
|
.Oo
|
|
.Cm auth | Cm bclient |
|
|
.Cm calibrate | Cm kernel |
|
|
.Cm mode7 | Cm monitor |
|
|
.Cm ntp | Cm stats |
|
|
.Cm peer_clear_digest_early |
|
|
.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
|
|
.Oc
|
|
.Xc
|
|
Provides a way to enable or disable various server options.
|
|
Flags not mentioned are unaffected.
|
|
Note that all of these flags
|
|
can be controlled remotely using the
|
|
.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
|
|
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 calibrate feature for reference clocks.
|
|
The default for
|
|
this flag is
|
|
.Ic disable .
|
|
.It Cm kernel
|
|
Enables the kernel time discipline, if available.
|
|
The default for this
|
|
flag is
|
|
.Ic enable
|
|
if support is available, otherwise
|
|
.Ic disable .
|
|
.It Cm mode7
|
|
Enables processing of NTP mode 7 implementation\-specific requests
|
|
which are used by the deprecated
|
|
.Xr ntpdc 8
|
|
program.
|
|
The default for this flag is disable.
|
|
This flag is excluded from runtime configuration using
|
|
.Xr ntpq 8 .
|
|
The
|
|
.Xr ntpq 8
|
|
program provides the same capabilities as
|
|
.Xr ntpdc 8
|
|
using standard mode 6 requests.
|
|
.It Cm monitor
|
|
Enables the monitoring facility.
|
|
See the
|
|
.Xr ntpdc 8
|
|
program
|
|
and the
|
|
.Ic monlist
|
|
command or further information.
|
|
The
|
|
default for this flag is
|
|
.Ic enable .
|
|
.It Cm ntp
|
|
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 peer_clear_digest_early
|
|
By default, if
|
|
.Xr ntpd 8
|
|
is using autokey and it
|
|
receives a crypto\-NAK packet that
|
|
passes the duplicate packet and origin timestamp checks
|
|
the peer variables are immediately cleared.
|
|
While this is generally a feature
|
|
as it allows for quick recovery if a server key has changed,
|
|
a properly forged and appropriately delivered crypto\-NAK packet
|
|
can be used in a DoS attack.
|
|
If you have active noticable problems with this type of DoS attack
|
|
then you should consider
|
|
disabling this option.
|
|
You can check your
|
|
.Cm peerstats
|
|
file for evidence of any of these attacks.
|
|
The
|
|
default for this flag is
|
|
.Ic enable .
|
|
.It Cm stats
|
|
Enables the statistics facility.
|
|
See the
|
|
.Sx Monitoring Options
|
|
section for further information.
|
|
The default for this flag is
|
|
.Ic disable .
|
|
.It Cm unpeer_crypto_early
|
|
By default, if
|
|
.Xr ntpd 8
|
|
receives an autokey packet that fails TEST9,
|
|
a crypto failure,
|
|
the association is immediately cleared.
|
|
This is almost certainly a feature,
|
|
but if, in spite of the current recommendation of not using autokey,
|
|
you are
|
|
.B still
|
|
using autokey
|
|
.B and
|
|
you are seeing this sort of DoS attack
|
|
disabling this flag will delay
|
|
tearing down the association until the reachability counter
|
|
becomes zero.
|
|
You can check your
|
|
.Cm peerstats
|
|
file for evidence of any of these attacks.
|
|
The
|
|
default for this flag is
|
|
.Ic enable .
|
|
.It Cm unpeer_crypto_nak_early
|
|
By default, if
|
|
.Xr ntpd 8
|
|
receives a crypto\-NAK packet that
|
|
passes the duplicate packet and origin timestamp checks
|
|
the association is immediately cleared.
|
|
While this is generally a feature
|
|
as it allows for quick recovery if a server key has changed,
|
|
a properly forged and appropriately delivered crypto\-NAK packet
|
|
can be used in a DoS attack.
|
|
If you have active noticable problems with this type of DoS attack
|
|
then you should consider
|
|
disabling this option.
|
|
You can check your
|
|
.Cm peerstats
|
|
file for evidence of any of these attacks.
|
|
The
|
|
default for this flag is
|
|
.Ic enable .
|
|
.It Cm unpeer_digest_early
|
|
By default, if
|
|
.Xr ntpd 8
|
|
receives what should be an authenticated packet
|
|
that passes other packet sanity checks but
|
|
contains an invalid digest
|
|
the association is immediately cleared.
|
|
While this is generally a feature
|
|
as it allows for quick recovery,
|
|
if this type of packet is carefully forged and sent
|
|
during an appropriate window it can be used for a DoS attack.
|
|
If you have active noticable problems with this type of DoS attack
|
|
then you should consider
|
|
disabling this option.
|
|
You can check your
|
|
.Cm peerstats
|
|
file for evidence of any of these attacks.
|
|
The
|
|
default for this flag is
|
|
.Ic enable .
|
|
.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 Xo Ic interface
|
|
.Oo
|
|
.Cm listen | Cm ignore | Cm drop
|
|
.Oc
|
|
.Oo
|
|
.Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
|
|
.Ar name | Ar address
|
|
.Oo Cm / Ar prefixlen
|
|
.Oc
|
|
.Oc
|
|
.Xc
|
|
The
|
|
.Cm interface
|
|
directive controls which network addresses
|
|
.Xr ntpd 8
|
|
opens, and whether input is dropped without processing.
|
|
The first parameter determines the action for addresses
|
|
which match the second parameter.
|
|
The second parameter specifies a class of addresses,
|
|
or a specific interface name,
|
|
or an address.
|
|
In the address case,
|
|
.Ar prefixlen
|
|
determines how many bits must match for this rule to apply.
|
|
.Cm ignore
|
|
prevents opening matching addresses,
|
|
.Cm drop
|
|
causes
|
|
.Xr ntpd 8
|
|
to open the address and drop all received packets without examination.
|
|
Multiple
|
|
.Cm interface
|
|
directives can be used.
|
|
The last rule which matches a particular address determines the action for it.
|
|
.Cm interface
|
|
directives are disabled if any
|
|
.Fl I ,
|
|
.Fl \-interface ,
|
|
.Fl L ,
|
|
or
|
|
.Fl \-novirtualips
|
|
command\-line options are specified in the configuration file,
|
|
all available network addresses are opened.
|
|
The
|
|
.Cm nic
|
|
directive is an alias for
|
|
.Cm interface .
|
|
.It Ic leapfile Ar leapfile
|
|
This command loads the IERS leapseconds file and initializes the
|
|
leapsecond values for the next leapsecond event, leapfile expiration
|
|
time, and TAI offset.
|
|
The file can be obtained directly from the IERS at
|
|
.Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list
|
|
or
|
|
.Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list .
|
|
The
|
|
.Cm leapfile
|
|
is scanned when
|
|
.Xr ntpd 8
|
|
processes the
|
|
.Cm leapfile directive or when
|
|
.Cm ntpd detects that the
|
|
.Ar leapfile
|
|
has changed.
|
|
.Cm ntpd
|
|
checks once a day to see if the
|
|
.Ar leapfile
|
|
has changed.
|
|
The
|
|
.Xr update\-leap 1update_leapmdoc
|
|
script can be run to see if the
|
|
.Ar leapfile
|
|
should be updated.
|
|
.It Ic leapsmearinterval Ar seconds
|
|
This EXPERIMENTAL option is only available if
|
|
.Xr ntpd 8
|
|
was built with the
|
|
.Cm \-\-enable\-leap\-smear
|
|
option to the
|
|
.Cm configure
|
|
script.
|
|
It specifies the interval over which a leap second correction will be applied.
|
|
Recommended values for this option are between
|
|
7200 (2 hours) and 86400 (24 hours).
|
|
.Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS!
|
|
See http://bugs.ntp.org/2855 for more information.
|
|
.It Ic logconfig Ar configkeyword
|
|
This command controls the amount and type of output written to
|
|
the system
|
|
.Xr syslog 3
|
|
facility or the alternate
|
|
.Ic logfile
|
|
log file.
|
|
By default, all output is turned on.
|
|
All
|
|
.Ar configkeyword
|
|
keywords can be prefixed with
|
|
.Ql = ,
|
|
.Ql +
|
|
and
|
|
.Ql \- ,
|
|
where
|
|
.Ql =
|
|
sets the
|
|
.Xr syslog 3
|
|
priority mask,
|
|
.Ql +
|
|
adds and
|
|
.Ql \-
|
|
removes
|
|
messages.
|
|
.Xr syslog 3
|
|
messages can be controlled in four
|
|
classes
|
|
.Po
|
|
.Cm clock ,
|
|
.Cm peer ,
|
|
.Cm sys
|
|
and
|
|
.Cm sync
|
|
.Pc .
|
|
Within these classes four types of messages can be
|
|
controlled: informational messages
|
|
.Po
|
|
.Cm info
|
|
.Pc ,
|
|
event messages
|
|
.Po
|
|
.Cm events
|
|
.Pc ,
|
|
statistics messages
|
|
.Po
|
|
.Cm statistics
|
|
.Pc
|
|
and
|
|
status messages
|
|
.Po
|
|
.Cm status
|
|
.Pc .
|
|
.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
|
|
.Cm all
|
|
keyword to enable/disable all
|
|
messages of the respective message class.
|
|
Thus, a minimal log configuration
|
|
could look like this:
|
|
.Bd -literal
|
|
logconfig =syncstatus +sysevents
|
|
.Ed
|
|
.Pp
|
|
This would just list the synchronizations state of
|
|
.Xr ntpd 8
|
|
and the major system events.
|
|
For a simple reference server, the
|
|
following minimum message configuration could be useful:
|
|
.Bd -literal
|
|
logconfig =syncall +clockall
|
|
.Ed
|
|
.Pp
|
|
This configuration will list all clock information and
|
|
synchronization information.
|
|
All other events and messages about
|
|
peers, system events and so on is suppressed.
|
|
.It Ic logfile Ar logfile
|
|
This command specifies the location of an alternate log file to
|
|
be used instead of the default system
|
|
.Xr syslog 3
|
|
facility.
|
|
This is the same operation as the
|
|
.Fl l
|
|
command line option.
|
|
.It Xo Ic mru
|
|
.Oo
|
|
.Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
|
|
.Cm mindepth Ar count | Cm maxage Ar seconds |
|
|
.Cm initialloc Ar count | Cm initmem Ar kilobytes |
|
|
.Cm incalloc Ar count | Cm incmem Ar kilobytes
|
|
.Oc
|
|
.Xc
|
|
Controls size limite of the monitoring facility's Most Recently Used
|
|
(MRU) list
|
|
of client addresses, which is also used by the
|
|
rate control facility.
|
|
.Bl -tag -width indent
|
|
.It Ic maxdepth Ar count
|
|
.It Ic maxmem Ar kilobytes
|
|
Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
|
|
The acutal limit will be up to
|
|
.Cm incalloc
|
|
entries or
|
|
.Cm incmem
|
|
kilobytes larger.
|
|
As with all of the
|
|
.Cm mru
|
|
options offered in units of entries or kilobytes, if both
|
|
.Cm maxdepth
|
|
and
|
|
.Cm maxmem are used, the last one used controls.
|
|
The default is 1024 kilobytes.
|
|
.It Cm mindepth Ar count
|
|
Lower limit on the MRU list size.
|
|
When the MRU list has fewer than
|
|
.Cm mindepth
|
|
entries, existing entries are never removed to make room for newer ones,
|
|
regardless of their age.
|
|
The default is 600 entries.
|
|
.It Cm maxage Ar seconds
|
|
Once the MRU list has
|
|
.Cm mindepth
|
|
entries and an additional client is to ba added to the list,
|
|
if the oldest entry was updated more than
|
|
.Cm maxage
|
|
seconds ago, that entry is removed and its storage is reused.
|
|
If the oldest entry was updated more recently the MRU list is grown,
|
|
subject to
|
|
.Cm maxdepth / moxmem .
|
|
The default is 64 seconds.
|
|
.It Cm initalloc Ar count
|
|
.It Cm initmem Ar kilobytes
|
|
Initial memory allocation at the time the monitoringfacility is first enabled,
|
|
in terms of the number of entries or kilobytes.
|
|
The default is 4 kilobytes.
|
|
.It Cm incalloc Ar count
|
|
.It Cm incmem Ar kilobytes
|
|
Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
|
|
The default is 4 kilobytes.
|
|
.El
|
|
.It Ic nonvolatile Ar threshold
|
|
Specify the
|
|
.Ar threshold
|
|
delta in seconds before an hourly change to the
|
|
.Cm driftfile
|
|
(frequency file) will be written, with a default value of 1e\-7 (0.1 PPM).
|
|
The frequency file is inspected each hour.
|
|
If the difference between the current frequency and the last value written
|
|
exceeds the threshold, the file is written and the
|
|
.Cm threshold
|
|
becomes the new threshold value.
|
|
If the threshold is not exceeeded, it is reduced by half.
|
|
This is intended to reduce the number of file writes
|
|
for embedded systems with nonvolatile memory.
|
|
.It Ic phone Ar dial ...
|
|
This command is used in conjunction with
|
|
the ACTS modem driver (type 18)
|
|
or the JJY driver (type 40, mode 100 \- 180).
|
|
For the ACTS modem driver (type 18), the arguments consist of
|
|
a maximum of 10 telephone numbers used to dial USNO, NIST, or European
|
|
time service.
|
|
For the JJY driver (type 40 mode 100 \- 180), the argument is
|
|
one telephone number used to dial the telephone JJY service.
|
|
The Hayes command ATDT is normally prepended to the number.
|
|
The number can contain other modem control codes as well.
|
|
.It Xo Ic reset
|
|
.Oo
|
|
.Ic allpeers
|
|
.Oc
|
|
.Oo
|
|
.Ic auth
|
|
.Oc
|
|
.Oo
|
|
.Ic ctl
|
|
.Oc
|
|
.Oo
|
|
.Ic io
|
|
.Oc
|
|
.Oo
|
|
.Ic mem
|
|
.Oc
|
|
.Oo
|
|
.Ic sys
|
|
.Oc
|
|
.Oo
|
|
.Ic timer
|
|
.Oc
|
|
.Xc
|
|
Reset one or more groups of counters maintained by
|
|
.Cm ntpd
|
|
and exposed by
|
|
.Cm ntpq
|
|
and
|
|
.Cm ntpdc .
|
|
.It Xo Ic rlimit
|
|
.Oo
|
|
.Cm memlock Ar Nmegabytes |
|
|
.Cm stacksize Ar N4kPages
|
|
.Cm filenum Ar Nfiledescriptors
|
|
.Oc
|
|
.Xc
|
|
.Bl -tag -width indent
|
|
.It Cm memlock Ar Nmegabytes
|
|
Specify the number of megabytes of memory that should be
|
|
allocated and locked.
|
|
Probably only available under Linux, this option may be useful
|
|
when dropping root (the
|
|
.Fl i
|
|
option).
|
|
The default is 32 megabytes on non\-Linux machines, and \-1 under Linux.
|
|
-1 means "do not lock the process into memory".
|
|
0 means "lock whatever memory the process wants into memory".
|
|
.It Cm stacksize Ar N4kPages
|
|
Specifies the maximum size of the process stack on systems with the
|
|
.Fn mlockall
|
|
function.
|
|
Defaults to 50 4k pages (200 4k pages in OpenBSD).
|
|
.It Cm filenum Ar Nfiledescriptors
|
|
Specifies the maximum number of file descriptors ntpd may have open at once.
|
|
Defaults to the system default.
|
|
.El
|
|
.It Ic saveconfigdir Ar directory_path
|
|
Specify the directory in which to write configuration snapshots
|
|
requested with
|
|
.Cm ntpq 's
|
|
.Cm saveconfig
|
|
command.
|
|
If
|
|
.Cm saveconfigdir
|
|
does not appear in the configuration file,
|
|
.Cm saveconfig
|
|
requests are rejected by
|
|
.Cm ntpd .
|
|
.It Ic saveconfig Ar filename
|
|
Write the current configuration, including any runtime
|
|
modifications given with
|
|
.Cm :config
|
|
or
|
|
.Cm config\-from\-file
|
|
to the
|
|
.Cm ntpd
|
|
host's
|
|
.Ar filename
|
|
in the
|
|
.Cm saveconfigdir .
|
|
This command will be rejected unless the
|
|
.Cm saveconfigdir
|
|
directive appears in
|
|
.Cm ntpd 's
|
|
configuration file.
|
|
.Ar filename
|
|
can use
|
|
.Xr strftime 3
|
|
format directives to substitute the current date and time,
|
|
for example,
|
|
.Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf .
|
|
The filename used is stored in the system variable
|
|
.Cm savedconfig .
|
|
Authentication is required.
|
|
.It Ic setvar Ar variable Op Cm default
|
|
This command adds an additional system variable.
|
|
These
|
|
variables can be used to distribute additional information such as
|
|
the access policy.
|
|
If the variable of the form
|
|
.Sm off
|
|
.Va name = Ar value
|
|
.Sm on
|
|
is followed by the
|
|
.Cm default
|
|
keyword, the
|
|
variable will be listed as part of the default system variables
|
|
.Po
|
|
.Xr ntpq 8
|
|
.Ic rv
|
|
command
|
|
.Pc ) .
|
|
These additional variables serve
|
|
informational purposes only.
|
|
They are not related to the protocol
|
|
other that they can be listed.
|
|
The known protocol variables will
|
|
always override any variables defined via the
|
|
.Ic setvar
|
|
mechanism.
|
|
There are three special variables that contain the names
|
|
of all variable of the same group.
|
|
The
|
|
.Va sys_var_list
|
|
holds
|
|
the names of all system variables.
|
|
The
|
|
.Va peer_var_list
|
|
holds
|
|
the names of all peer variables and the
|
|
.Va clock_var_list
|
|
holds the names of the reference clock variables.
|
|
.It Cm sysinfo
|
|
Display operational summary.
|
|
.It Cm sysstats
|
|
Show statistics counters maintained in the protocol module.
|
|
.It Xo Ic tinker
|
|
.Oo
|
|
.Cm allan Ar allan |
|
|
.Cm dispersion Ar dispersion |
|
|
.Cm freq Ar freq |
|
|
.Cm huffpuff Ar huffpuff |
|
|
.Cm panic Ar panic |
|
|
.Cm step Ar step |
|
|
.Cm stepback Ar stepback |
|
|
.Cm stepfwd Ar stepfwd |
|
|
.Cm stepout Ar stepout
|
|
.Oc
|
|
.Xc
|
|
This command can be used to alter several system variables in
|
|
very exceptional circumstances.
|
|
It should occur in the
|
|
configuration file before any other configuration options.
|
|
The
|
|
default values of these variables have been carefully optimized for
|
|
a wide range of network speeds and reliability expectations.
|
|
In
|
|
general, they interact in intricate ways that are hard to predict
|
|
and some combinations can result in some very nasty behavior.
|
|
Very
|
|
rarely is it necessary to change the default values; but, some
|
|
folks cannot resist twisting the knobs anyway and this command is
|
|
for them.
|
|
Emphasis added: twisters are on their own and can expect
|
|
no help from the support group.
|
|
.Pp
|
|
The variables operate as follows:
|
|
.Bl -tag -width indent
|
|
.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 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
|
|
the algorithm will search for a minimum delay.
|
|
The lower limit is
|
|
900 s (15 m), but a more reasonable value is 7200 (2 hours).
|
|
There
|
|
is no default, since the filter is not enabled unless this command
|
|
is given.
|
|
.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 stepback Ar stepback
|
|
The argument is the step threshold for the backward direction,
|
|
which by default is 0.128 s.
|
|
It can
|
|
be set to any positive number in seconds.
|
|
If both the forward and backward step thresholds are set to zero, step
|
|
adjustments will never occur.
|
|
Note: The kernel time discipline is
|
|
disabled if
|
|
each direction of step threshold are either
|
|
set to zero or greater than .5 second.
|
|
.It Cm stepfwd Ar stepfwd
|
|
As for stepback, but for the forward direction.
|
|
.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 Cm writevar Ar assocID\ name = value [,...]
|
|
Write (create or update) the specified variables.
|
|
If the
|
|
.Cm assocID
|
|
is zero, the variablea re from the
|
|
system variables
|
|
name space, otherwise they are from the
|
|
peer variables
|
|
name space.
|
|
The
|
|
.Cm assocID
|
|
is required, as the same name can occur in both name spaces.
|
|
.It Xo Ic trap Ar host_address
|
|
.Op Cm port Ar port_number
|
|
.Op Cm interface Ar interface_address
|
|
.Xc
|
|
This command configures a trap receiver at the given host
|
|
address and port number for sending messages with the specified
|
|
local interface address.
|
|
If the port number is unspecified, a value
|
|
of 18447 is used.
|
|
If the interface address is not specified, the
|
|
message is sent with a source address of the local interface the
|
|
message is sent through.
|
|
Note that on a multihomed host the
|
|
interface used may vary from time to time with routing changes.
|
|
.It Cm ttl Ar hop ...
|
|
This command specifies a list of TTL values in increasing order.
|
|
Up to 8 values can be specified.
|
|
In
|
|
.Cm manycast
|
|
mode these values are used in\-turn in an expanding\-ring search.
|
|
The default is eight multiples of 32 starting at 31.
|
|
.Pp
|
|
The trap receiver will generally log event messages and other
|
|
information from the server in a log file.
|
|
While such monitor
|
|
programs may also request their own trap dynamically, configuring a
|
|
trap receiver will ensure that no messages are lost when the server
|
|
is started.
|
|
.It Cm hop Ar ...
|
|
This command specifies a list of TTL values in increasing order, up to 8
|
|
values can be specified.
|
|
In manycast mode these values are used in turn in
|
|
an expanding\-ring search.
|
|
The default is eight multiples of 32 starting at
|
|
31.
|
|
.El
|
|
.Sh "OPTIONS"
|
|
.Bl -tag
|
|
.It Fl \-help
|
|
Display usage information and exit.
|
|
.It Fl \-more\-help
|
|
Pass the extended usage information through a pager.
|
|
.It Fl \-version Op Brq Ar v|c|n
|
|
Output version of program and exit. The default mode is `v', a simple
|
|
version. The `c' mode will print copyright information and `n' will
|
|
print the full copyright notice.
|
|
.El
|
|
.Sh "OPTION PRESETS"
|
|
Any option that is not marked as \fInot presettable\fP may be preset
|
|
by loading values from environment variables named:
|
|
.nf
|
|
\fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP
|
|
.fi
|
|
.ad
|
|
.Sh "ENVIRONMENT"
|
|
See \fBOPTION PRESETS\fP for configuration environment variables.
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/ntp.drift -compact
|
|
.It Pa /etc/ntp.conf
|
|
the default name of the configuration file
|
|
.It Pa ntp.keys
|
|
private MD5 keys
|
|
.It Pa ntpkey
|
|
RSA private key
|
|
.It Pa ntpkey_ Ns Ar host
|
|
RSA public key
|
|
.It Pa ntp_dh
|
|
Diffie\-Hellman agreement parameters
|
|
.El
|
|
.Sh "EXIT STATUS"
|
|
One of the following exit values will be returned:
|
|
.Bl -tag
|
|
.It 0 " (EXIT_SUCCESS)"
|
|
Successful program execution.
|
|
.It 1 " (EXIT_FAILURE)"
|
|
The operation failed or the command syntax was not valid.
|
|
.It 70 " (EX_SOFTWARE)"
|
|
libopts had an internal operational error. Please report
|
|
it to autogen\-users@lists.sourceforge.net. Thank you.
|
|
.El
|
|
.Sh "SEE ALSO"
|
|
.Xr ntpd 8 ,
|
|
.Xr ntpdc 8 ,
|
|
.Xr ntpq 8
|
|
.Pp
|
|
In addition to the manual pages provided,
|
|
comprehensive documentation is available on the world wide web
|
|
at
|
|
.Li http://www.ntp.org/ .
|
|
A snapshot of this documentation is available in HTML format in
|
|
.Pa /usr/share/doc/ntp .
|
|
.Rs
|
|
.%A David L. Mills
|
|
.%T Network Time Protocol (Version 4)
|
|
.%O RFC5905
|
|
.Re
|
|
.Sh "AUTHORS"
|
|
The University of Delaware and Network Time Foundation
|
|
.Sh "COPYRIGHT"
|
|
Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
|
|
This program is released under the terms of the NTP license, <http://ntp.org/license>.
|
|
.Sh BUGS
|
|
The syntax checking is not picky; some combinations of
|
|
ridiculous and even hilarious options and modes may not be
|
|
detected.
|
|
.Pp
|
|
The
|
|
.Pa ntpkey_ Ns Ar host
|
|
files are really digital
|
|
certificates.
|
|
These should be obtained via secure directory
|
|
services when they become universally available.
|
|
.Pp
|
|
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
|
|
.Sh NOTES
|
|
This document was derived from FreeBSD.
|
|
.Pp
|
|
This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP
|
|
option definitions.
|