This document describes the configuration file for the NTP Project's
ntpd program.
This document applies to version 4.2.8p10 of ntp.conf.
The behavior of ntpd can be changed by a configuration file,
by default ntp.conf.
The
ntp.conf
configuration file is read at initial startup by the
ntpd(1ntpdmdoc)
daemon in order to specify the synchronization sources,
modes and other related information.
Usually, it is installed in the
/etc
directory,
but could be installed elsewhere
(see the daemon's
-c
command line option).
The file format is similar to other unix configuration files. Comments begin with a # character and extend to the end of the line; blank lines are ignored. Configuration commands consist of an initial keyword followed by a list of arguments, some of which may be optional, separated by whitespace. Commands may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric, dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings.
The rest of this page describes the configuration and control options. The "Notes on Configuring NTP and Setting up an NTP Subnet" page (available as part of the HTML documentation provided in /usr/share/doc/ntp) contains an extended discussion of these options. In addition to the discussion of general Configuration Options, there are sections describing the following supported functionality and the options used to control it:
Following these is a section describing
Miscellaneous Options.
While there is a rich set of options available,
the only required option is one or more
pool,
server,
peer,
broadcast
or
manycastclient
commands.
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.
The various modes are determined by the command keyword and the type of the required IP address. Addresses are classed by type as (s) a remote server or peer (IPv4 class A, B and C), (b) the broadcast address of a local interface, (m) a multicast address (IPv4 class D), or (r) a reference clock address (127.127.x.x). Note that only those options applicable to each command are listed below. Use of options not listed may not be caught as an error, but may result in some weird and even destructive behavior.
If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
is detected, support for the IPv6 address family is generated
in addition to the default support of the IPv4 address family.
In a few cases, including the
reslist
billboard generated
by
ntpq(1ntpqmdoc)
or
ntpdc(1ntpdcmdoc),
IPv6 addresses are automatically generated.
IPv6 addresses can be identified by the presence of colons
:
in the address field.
IPv6 addresses can be used almost everywhere where
IPv4 addresses can be used,
with the exception of reference clock addresses,
which are always IPv4.
Note that in contexts where a host name is expected, a
-4
qualifier preceding
the host name forces DNS resolution to the IPv4 namespace,
while a
-6
qualifier forces DNS resolution to the IPv6 namespace.
See IPv6 references for the
equivalent classes for that address family.
pool address [burst] [iburst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]server address [key key | autokey] [burst] [iburst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll] [true]peer address [key key | autokey] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll] [true] [xleave]broadcast address [key key | autokey] [version version] [prefer] [minpoll minpoll] [ttl ttl] [xleave]manycastclient address [key key | autokey] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]These five commands specify the time server name or address to be used and the mode in which to operate. The 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 "Association Management" page (available as part of the HTML documentation provided in /usr/share/doc/ntp).
poolserverpeerbroadcastbroadcastclient
or
multicastclient
commands
below.
manycastclientmanycastserver
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
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
address
and specifically enabled
servers respond to these messages.
The client selects the servers
providing the best time and continues as with the
server
command.
The remaining servers are discarded as if never
heard.
Options:
autokeyburstcalldelay
command to allow
additional time for a modem or ISDN call to complete.
This is designed to improve timekeeping quality
with the
server
command and s addresses.
iburstcalldelay
command to allow
additional time for a modem or ISDN call to complete.
This is designed to speed the initial synchronization
acquisition with the
server
command and s addresses and when
ntpd(1ntpdmdoc)
is started with the
-q
option.
key keyminpoll minpollmaxpoll maxpollmaxpoll
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
minpoll
option to a lower limit of 4 (16 s).
noselectpreempttrueprefertruettl ttlversion versionxleavepeer
and
broadcast
modes only, this flag enables interleave mode.
broadcastclientmanycastserver address ...multicastclient address ...mdnstries numbermdnstries
times.
After all,
ntpd
may be starting before mDNS.
The default value for
mdnstries
is 5.
Authentication support allows the NTP client to verify that the server is in fact known and trusted and not an intruder intending accidentally or on purpose to masquerade as that server. The NTPv3 specification RFC-1305 defines a scheme which provides cryptographic authentication of received NTP packets. Originally, this was done using the Data Encryption Standard (DES) algorithm operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by the RSA Message Digest 5 (MD5) algorithm using a private key, commonly called keyed-MD5. Either algorithm computes a message digest, or one-way hash, which can be used to verify the server has the correct private key and key identifier.
NTPv4 retains the NTPv3 scheme, properly described as symmetric key cryptography and, in addition, provides a new Autokey scheme based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on a private value which is generated by each server and never revealed. With Autokey all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, which can be provided by commercial services or produced by utility programs in the OpenSSL software library or the NTPv4 distribution.
While the algorithms for symmetric key cryptography are included in the NTPv4 distribution, public key cryptography requires the OpenSSL software library to be installed before building the NTP distribution. Directions for doing that are on the Building and Installing the Distribution page.
Authentication is configured separately for each association
using the
key
or
autokey
subcommand on the
peer,
server,
broadcast
and
manycastclient
configuration commands as described in
Configuration Options
page.
The authentication
options described below specify the locations of the key files,
if other than default, which symmetric keys are trusted
and the interval between various operations, if other than default.
Authentication is always enabled, although ineffective if not configured as described below. If a NTP packet arrives including a message authentication code (MAC), it is accepted only if it passes all cryptographic checks. The checks require correct key ID, key value and message digest. If the packet has been modified in any way or replayed by an intruder, it will fail one or more of these checks and be discarded. Furthermore, the Autokey scheme requires a preliminary protocol exchange to obtain the server certificate, verify its credentials and initialize the protocol
The
auth
flag controls whether new associations or
remote configuration commands require cryptographic authentication.
This flag can be set or reset by the
enable
and
disable
commands and also by remote
configuration commands sent by a
ntpdc(1ntpdcmdoc)
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
auth
flag disabled invites a significant vulnerability
where a rogue hacker can
masquerade as a falseticker and seriously
disrupt system timekeeping.
It is
important to note that this flag has no purpose
other than to allow or disallow
a new association in response to new broadcast
and symmetric active messages
and remote configuration commands and, in particular,
the flag has no effect on
the authentication process itself.
An attractive alternative where multicast support is available is manycast mode, in which clients periodically troll for servers as described in the Automatic NTP Configuration Options page. Either symmetric key or public key cryptographic authentication can be used in this mode. The principle advantage of manycast mode is that potential servers need not be configured in advance, since the client finds them during regular operation, and the configuration files for all clients can be identical.
The security model and protocol schemes for
both symmetric key and public key
cryptography are summarized below;
further details are in the briefings, papers
and reports at the NTP project page linked from
http://www.ntp.org/.
The original RFC-1305 specification allows any one of possibly
65,534 keys, each distinguished by a 32-bit key identifier, to
authenticate an association.
The servers and clients involved must
agree on the key and key identifier to
authenticate NTP packets.
Keys and
related information are specified in a key
file, usually called
ntp.keys,
which must be distributed and stored using
secure means beyond the scope of the NTP protocol itself.
Besides the keys used
for ordinary NTP associations,
additional keys can be used as passwords for the
ntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
utility programs.
When
ntpd(1ntpdmdoc)
is first started, it reads the key file specified in the
keys
configuration command and installs the keys
in the key cache.
However,
individual keys must be activated with the
trusted
command before use.
This
allows, for instance, the installation of possibly
several batches of keys and
then activating or deactivating each batch
remotely using
ntpdc(1ntpdcmdoc).
This also provides a revocation capability that can be used
if a key becomes compromised.
The
requestkey
command selects the key used as the password for the
ntpdc(1ntpdcmdoc)
utility, while the
controlkey
command selects the key used as the password for the
ntpq(1ntpqmdoc)
utility.
NTPv4 supports the original NTPv3 symmetric key scheme described in RFC-1305 and in addition the Autokey protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using MD5 message digests and verifies the source with digital signatures and any of several digest/signature schemes. Optional identity schemes described on the Identity Schemes page and based on cryptographic challenge/response algorithms are also available. Using all of these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks.
The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. Most modes use a special cookie which can be computed independently by the client and server, but encrypted in transmission. All modes use in addition a variant of the S-KEY scheme, in which a pseudo-random key list is generated and used in reverse order. These schemes are described along with an executive summary, current status, briefing slides and reading list on the Autonomous Authentication page.
The specific cryptographic environment used by Autokey servers
and clients is determined by a set of files
and soft links generated by the
ntp-keygen(1ntpkeygenmdoc)
program.
This includes a required host key file,
required certificate file and optional sign key file,
leapsecond file and identity scheme files.
The
digest/signature scheme is specified in the X.509 certificate
along with the matching sign key.
There are several schemes
available in the OpenSSL software library, each identified
by a specific string such as
md5WithRSAEncryption,
which stands for the MD5 message digest with RSA
encryption scheme.
The current NTP distribution supports
all the schemes in the OpenSSL library, including
those based on RSA and DSA digital signatures.
NTP secure groups can be used to define cryptographic compartments and security hierarchies. It is important that every host in the group be able to construct a certificate trail to one or more trusted hosts in the same group. Each group host runs the Autokey protocol to obtain the certificates for all hosts along the trail to one or more trusted hosts. This requires the configuration file in all hosts to be engineered so that, even under anticipated failure conditions, the NTP subnet will form such that every group host can find a trail to at least one trusted host.
It is important to note that Autokey does not use DNS to resolve addresses, since DNS can't be completely trusted until the name servers have synchronized clocks. The cryptographic name used by Autokey to bind the host identity credentials and cryptographic values must be independent of interface, network and any other naming convention. The name appears in the host certificate in either or both the subject and issuer fields, so protection against DNS compromise is essential.
By convention, the name of an Autokey host is the name returned
by the Unix
gethostname(2)
system call or equivalent in other systems.
By the system design
model, there are no provisions to allow alternate names or aliases.
However, this is not to say that DNS aliases, different names
for each interface, etc., are constrained in any way.
It is also important to note that Autokey verifies authenticity using the host name, network address and public keys, all of which are bound together by the protocol specifically to deflect masquerade attacks. For this reason Autokey includes the source and 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.
A specific combination of authentication scheme (none, symmetric key, public key) and identity scheme is called a cryptotype, although not all combinations are compatible. There may be management configurations where the clients, servers and peers may not all support the same cryptotypes. A secure NTPv4 subnet can be configured in many ways while keeping in mind the principles explained above and in this section. Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice.
The cryptotype of an association is determined at the time
of mobilization, either at configuration time or some time
later when a message of appropriate cryptotype arrives.
When mobilized by a
server
or
peer
configuration command and no
key
or
autokey
subcommands are present, the association is not
authenticated; if the
key
subcommand is present, the association is authenticated
using the symmetric key ID specified; if the
autokey
subcommand is present, the association is authenticated
using Autokey.
When multiple identity schemes are supported in the Autokey protocol, the first message exchange determines which one is used. The client request message contains bits corresponding to which schemes it has available. The server response message contains bits corresponding to which schemes it has available. Both server and client match the received bits with their own and select a common scheme.
Following the principle that time is a public value, a server responds to any client packet that matches its cryptotype capabilities. Thus, a server receiving an unauthenticated packet will respond with an unauthenticated packet, while the same server receiving a packet of a cryptotype it supports will respond with packets of that cryptotype. However, unconfigured broadcast or manycast client associations or symmetric passive associations will not be mobilized unless the server supports a cryptotype compatible with the first packet received. By default, unauthenticated associations will not be mobilized unless overridden in a decidedly dangerous way.
Some examples may help to reduce confusion.
Client Alice has no specific cryptotype selected.
Server Bob has both a symmetric key file and minimal Autokey files.
Alice's unauthenticated messages arrive at Bob, who replies with
unauthenticated messages.
Cathy has a copy of Bob's symmetric
key file and has selected key ID 4 in messages to Bob.
Bob verifies the message with his key ID 4.
If it's the
same key and the message is verified, Bob sends Cathy a reply
authenticated with that key.
If verification fails,
Bob sends Cathy a thing called a crypto-NAK, which tells her
something broke.
She can see the evidence using the
ntpq(1ntpqmdoc)
program.
Denise has rolled her own host key and certificate. She also uses one of the identity schemes as Bob. She sends the first Autokey message to Bob and they both dance the protocol authentication and identity steps. If all comes out okay, Denise and Bob continue as described above.
It should be clear from the above that Bob can support all the girls at the same time, as long as he has compatible authentication and identity credentials. Now, Bob can act just like the girls in his own choice of servers; he can run multiple configured associations with multiple different servers (or the same server, although that might not be useful). But, wise security policy might preclude some cryptotype combinations; for instance, running an identity scheme with one server and no authentication with another might not be wise.
The cryptographic values used by the Autokey protocol are
incorporated as a set of files generated by the
ntp-keygen(1ntpkeygenmdoc)
utility program, including symmetric key, host key and
public certificate files, as well as sign key, identity parameters
and leapseconds files.
Alternatively, host and sign keys and
certificate files can be generated by the OpenSSL utilities
and certificates can be imported from public certificate
authorities.
Note that symmetric keys are necessary for the
ntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
utility programs.
The remaining files are necessary only for the
Autokey protocol.
Certificates imported from OpenSSL or public certificate
authorities have certian limitations.
The certificate should be in ASN.1 syntax, X.509 Version 3
format and encoded in PEM, which is the same format
used by OpenSSL.
The overall length of the certificate encoded
in ASN.1 must not exceed 1024 bytes.
The subject distinguished
name field (CN) is the fully qualified name of the host
on which it is used; the remaining subject fields are ignored.
The certificate extension fields must not contain either
a subject key identifier or a issuer key identifier field;
however, an extended key usage field for a trusted host must
contain the value
trustRoot;.
Other extension fields are ignored.
autokey [logsec]controlkey keyntpq(1ntpqmdoc)
utility, which uses the standard
protocol defined in RFC-1305.
The
key
argument is
the key identifier for a trusted key, where the value can be in the
range 1 to 65,534, inclusive.
crypto [cert file] [leap file] [randfile file] [host file] [sign file] [gq file] [gqpar file] [iffpar file] [mvpar file] [pw password]keysdir
command or default
/usr/local/etc.
Following are the subcommands:
cert filegqpar filehost fileiffpar fileleap filemvpar filepw passwordrandfile filesign filekeys keyfilentpd(1ntpdmdoc),
ntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
when operating with symmetric key cryptography.
This is the same operation as the
-k
command line option.
keysdir pathrequestkey keyntpdc(1ntpdcmdoc)
utility program, which uses a
proprietary protocol specific to this implementation of
ntpd(1ntpdmdoc).
The
key
argument is a key identifier
for the trusted key, where the value can be in the range 1 to
65,534, inclusive.
revoke logsectrustedkey key ...ntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
programs.
The authentication procedures require that both the local
and remote servers share the same key and key identifier for this
purpose, although different keys can be used with different
servers.
The
key
arguments are 32-bit unsigned
integers with values from 1 to 65,534.
The following error codes are reported via the NTP control and monitoring protocol trap mechanism.
ntpd(1ntpdmdoc)
includes a comprehensive monitoring facility suitable
for continuous, long term recording of server and client
timekeeping performance.
See the
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
./scripts
directory of the source code distribution.
Using
these facilities and
unix
cron(8)
jobs, the data can be
automatically summarized and archived for retrospective analysis.
statistics name ...clockstatsclockstats:
49213 525.624 127.127.4.1 93 226 00:08:29.606 D
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.
cryptostatscryptostats:
49213 525.624 127.127.4.1 message
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
Authentication Options
section for further information.
loopstatsloopstats:
50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
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.
peerstatspeerstats:
48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
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.
rawstatsrawstats:
50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
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.
sysstatssysstats:
50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
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.
360008196509546567179351254010147statsdir directory_pathfilegen
filename prefix to be modified for file generation sets, which
is useful for handling statistics logs.
filegen name [file filename] [type typename] [link | nolink] [enable | disable]Note that this command can be sent from the
ntpdc(1ntpdcmdoc)
program running at a remote location.
namestatistics
command.
file filenameprefix,
filename
and
suffix:
prefixfilenamesuffixtype typenamenonepidntpd(1ntpdmdoc)
server incarnations.
The set member filename is built by appending a
.
to concatenated
prefix
and
filename
strings, and
appending the decimal representation of the process ID of the
ntpd(1ntpdmdoc)
server process.
dayYYYYMMdd.
YYYY
is a 4-digit year number (e.g., 1992).
MM
is a two digit month number.
dd
is a two digit day number.
Thus, all information written at 10 December 1992 would end up
in a file named
prefix
filename.19921210.
weekW,
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 .
monthyearagea,
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
enable;
output is prevented by specifying
disable.
link | nolinklink
and disabled using
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
C,
and the pid of the
ntpd(1ntpdmdoc)
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.
enable | disableThe
ntpd(1ntpdmdoc)
daemon implements a general purpose address/mask based restriction
list.
The list contains address/match entries sorted first
by increasing address values and and then by increasing mask values.
A match occurs when the bitwise AND of the mask and the packet
source address is equal to the bitwise AND of the mask and
address in the list.
The list is searched in order with the
last match found defining the restriction flags associated
with the entry.
Additional information and examples can be found in the
"Notes on Configuring NTP and Setting up a NTP Subnet"
page
(available as part of the HTML documentation
provided in
/usr/share/doc/ntp).
The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone time servers. Later the facility was expanded to deflect cryptographic and clogging attacks. While this facility may be useful for keeping unwanted or broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. Source address based restrictions are easily circumvented by a determined cracker.
Clients can be denied service because they are explicitly
included in the restrict list created by the
restrict
command
or implicitly as the result of cryptographic or rate limit
violations.
Cryptographic violations include certificate
or identity verification failure; rate limit violations generally
result from defective NTP implementations that send packets
at abusive rates.
Some violations cause denied service
only for the offending packet, others cause denied service
for a timed period and others cause the denied service for
an 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.
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
noserve
or
notrust
flag of the matching restrict list entry is set,
the code is "DENY"; if the
limited
flag is set and the rate limit
is exceeded, the code is "RATE".
Finally, if a cryptographic violation occurs, the code is "CRYP".
A client receiving a KoD performs a set of sanity checks to minimize security exposure, then updates the stratum and reference identifier peer variables, sets the access denied (TEST4) bit in the peer flash variable and sends a message to the log. As long as the TEST4 bit is set, the client will send no further packets to the server. The only way at present to recover from this condition is to restart the protocol at both the client and server. This happens automatically at the client when the association times out. It will happen at the server only if the server operator cooperates.
discard [average avg] [minimum min] [monitor prob]limited
facility which protects the server from
client abuse.
The
average
subcommand specifies the minimum average packet
spacing, while the
minimum
subcommand specifies the minimum packet spacing.
Packets that violate these minima are discarded
and a kiss-o'-death packet returned if enabled.
The default
minimum average and minimum are 5 and 2, respectively.
The
monitor
subcommand specifies the probability of discard
for packets that overflow the rate-control window.
restrict address [mask mask] [flag ...]255.255.255.255,
meaning that the
address
is treated as the address of an individual host.
A default entry (address
0.0.0.0,
mask
0.0.0.0)
is always included and is always the first entry in the list.
Note that text string
default,
with no mask option, may
be used to indicate the default entry.
In the current implementation,
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:
ignorentpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
queries.
kodlimiteddiscard
command.
A history of clients is kept using the
monitoring capability of
ntpd(1ntpdmdoc).
Thus, monitoring is always active as
long as there is a restriction entry with the
limited
flag.
lowpriotrapnomodifyntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
queries which attempt to modify the state of the
server (i.e., run time reconfiguration).
Queries which return
information are permitted.
noqueryntpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
queries.
Time service is not affected.
nopeerpool
associations, so if you want to use servers from a
pool
directive and also want to use
nopeer
by default, you'll want a
restrict source ... line as well that does
nopeer
directive.
noserventpq(1ntpqmdoc)
and
ntpdc(1ntpdcmdoc)
queries.
notrapntpq(1ntpqmdoc)
control message
protocol which is intended for use by remote event logging programs.
notrustntpportntpport
and
non-ntpport
may
be specified.
The
ntpport
is considered more specific and
is sorted later in the list.
versionDefault 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).
Manycasting is a automatic discovery and configuration paradigm new to NTPv4. It is intended as a means for a multicast client to troll the nearby network neighborhood to find cooperating manycast servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each manycast client mobilizes client associations with some number of the "best" of the nearby manycast servers, yet automatically reconfigures to sustain this number of servers should one or another fail.
Note that the manycasting paradigm does not coincide with the anycast paradigm described in RFC-1546, which is designed to find a single server from a clique of servers providing the same service. The manycast paradigm is designed to find a plurality of redundant servers satisfying defined optimality criteria.
Manycasting can be used with either symmetric key
or public key cryptography.
The public key infrastructure (PKI)
offers the best protection against compromised keys
and is generally considered stronger, at least with relatively
large key sizes.
It is implemented using the Autokey protocol and
the OpenSSL cryptographic library available from
http://www.openssl.org/.
The library can also be used with other NTPv4 modes
as well and is highly recommended, especially for broadcast modes.
A persistent manycast client association is configured
using the
manycastclient
command, which is similar to the
server
command but with a multicast (IPv4 class
D
or IPv6 prefix
FF)
group address.
The IANA has designated IPv4 address 224.1.1.1
and IPv6 address FF05::101 (site local) for NTP.
When more servers are needed, it broadcasts manycast
client messages to this address at the minimum feasible rate
and minimum feasible time-to-live (TTL) hops, depending
on how many servers have already been found.
There can be as many manycast client associations
as different group address, each one serving as a template
for a future ephemeral unicast client/server association.
Manycast servers configured with the
manycastserver
command listen on the specified group address for manycast
client messages.
Note the distinction between manycast client,
which actively broadcasts messages, and manycast server,
which passively responds to them.
If a manycast server is
in scope of the current TTL and is itself synchronized
to a valid source and operating at a stratum level equal
to or lower than the manycast client, it replies to the
manycast client message with an ordinary unicast server message.
The manycast client receiving this message mobilizes an ephemeral client/server association according to the matching manycast client template, but only if cryptographically authenticated and the server stratum is less than or equal to the client stratum. Authentication is explicitly required and either symmetric key or public key (Autokey) can be used. Then, the client polls the server at its unicast address in burst mode in order to reliably set the host clock and validate the source. This normally results in a volley of eight client/server at 2-s intervals during which both the synchronization and cryptographic protocols run concurrently. Following the volley, the client runs the NTP intersection and clustering algorithms, which act to discard all but the "best" associations according to stratum and synchronization distance. The surviving associations then continue in ordinary client/server mode.
The manycast client polling strategy is designed to reduce
as much as possible the volume of manycast client messages
and the effects of implosion due to near-simultaneous
arrival of manycast server messages.
The strategy is determined by the
manycastclient,
tos
and
ttl
configuration commands.
The manycast poll interval is
normally eight times the system poll interval,
which starts out at the
minpoll
value specified in the
manycastclient,
command and, under normal circumstances, increments to the
maxpolll
value specified in this command.
Initially, the TTL is
set at the minimum hops specified by the
ttl
command.
At each retransmission the TTL is increased until reaching
the maximum hops specified by this command or a sufficient
number client associations have been found.
Further retransmissions use the same TTL.
The quality and reliability of the suite of associations
discovered by the manycast client is determined by the NTP
mitigation algorithms and the
minclock
and
minsane
values specified in the
tos
configuration command.
At least
minsane
candidate servers must be available and the mitigation
algorithms produce at least
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,
minsane
defaults to 1 and
minclock
defaults to 3.
For manycast service
minsane
should be explicitly set to 4, assuming at least that
number of servers are available.
If at least
minclock
servers are found, the manycast poll interval is immediately
set to eight times
maxpoll.
If less than
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
maxpoll.
Further transmissions use the same poll interval and
TTL values.
Note that while all this is going on,
each client/server association found is operating normally
it the system poll interval.
Administratively scoped multicast boundaries are normally
specified by the network router configuration and,
in the case of IPv6, the link/site scope prefix.
By default, the increment for TTL hops is 32 starting
from 31; however, the
ttl
configuration command can be
used to modify the values to match the scope rules.
It is often useful to narrow the range of acceptable
servers which can be found by manycast client associations.
Because manycast servers respond only when the client
stratum is equal to or greater than the server stratum,
primary (stratum 1) servers fill find only primary servers
in TTL range, which is probably the most common objective.
However, unless configured otherwise, all manycast clients
in TTL range will eventually find all primary servers
in TTL range, which is probably not the most common
objective in large networks.
The
tos
command can be used to modify this behavior.
Servers with stratum below
floor
or above
ceiling
specified in the
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
minclock.
The above actions occur for each manycast client message,
which repeats at the designated poll interval.
However, once the ephemeral client association is mobilized,
subsequent manycast server replies are discarded,
since that would result in a duplicate association.
If during a poll interval the number of client associations
falls below
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
maxpoll
is 12 (4,096 s).
It is possible and frequently useful to configure a host
as both manycast client and manycast server.
A number of hosts configured this way and sharing a common
group address will automatically organize themselves
in an optimum configuration based on stratum and
synchronization distance.
For example, consider an NTP
subnet of two primary servers and a hundred or more
dependent clients.
With two exceptions, all servers
and clients have identical configuration files including both
multicastclient
and
multicastserver
commands using, for instance, multicast group address
239.1.1.1.
The only exception is that each primary server
configuration file must include commands for the primary
reference source such as a GPS receiver.
The remaining configuration files for all secondary
servers and clients have the same contents, except for the
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
floor
value is set to the intended stratum number.
Thus, all stratum 3 configuration files are identical,
all stratum 4 files are identical and so forth.
Once operations have stabilized in this scenario, the primary servers will find the primary reference source and each other, since they both operate at the same stratum (1), but not with any secondary server or client, since these operate at a higher stratum. The secondary servers will find the servers at the same stratum level. If one of the primary servers loses its GPS receiver, it will continue to operate as a client and other clients will time out the corresponding association and re-associate accordingly.
Some administrators prefer to avoid running
ntpd(1ntpdmdoc)
continuously and run either
sntp(1sntpmdoc)
or
ntpd(1ntpdmdoc)
-q
as a cron job.
In either case the servers must be
configured in advance and the program fails if none are
available when the cron job runs.
A really slick
application of manycast is with
ntpd(1ntpdmdoc)
-q.
The program wakes up, scans the local landscape looking
for the usual suspects, selects the best from among
the rascals, sets the clock and then departs.
Servers do not have to be configured in advance and
all clients throughout the network can have the same
configuration file.
Each time a manycast client sends a client mode packet to a multicast group address, all manycast servers in scope generate a reply including the host name and status word. The manycast clients then run the Autokey protocol, which collects and verifies all certificates involved. Following the burst interval all but three survivors are cast off, but the certificates remain in the local cache. It often happens that several complete signing trails from the client to the primary servers are collected in this way.
About once an hour or less often if the poll interval exceeds this, the client regenerates the Autokey key list. This is in general transparent in client/server mode. However, about once per day the server private value used to generate cookies is refreshed along with all manycast client associations. In this case all cryptographic values including certificates is refreshed. If a new certificate has been generated since the last refresh epoch, it will automatically revoke all prior certificates that happen to be in the certificate cache. At the same time, the manycast scheme starts all over from the beginning and the expanding ring shrinks to the minimum and increments from there while collecting all servers in scope.
tos [bcpollbstep gate]tos [ceiling ceiling | cohort { 0 | 1 } | floor floor | minclock minclock | minsane minsane]ceiling ceilingceiling
will be discarded if there are at least
minclock
peers remaining.
This value defaults to 15, but can be changed
to any number from 1 to 15.
cohort {0 | 1}floor floorfloor
will be discarded if there are at least
minclock
peers remaining.
This value defaults to 1, but can be changed
to any number from 1 to 15.
minclock minclockminclock
associations remain.
This value defaults to 3,
but can be changed to any number from 1 to the number of
configured sources.
minsane minsaneminsane
should be at least 4 in order to detect and discard
a single falseticker.
ttl hop ...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 "Reference Clock Drivers" page (available as part of the HTML documentation provided in /usr/share/doc/ntp). Additional information can be found in the pages linked there, including the "Debugging Hints for Reference Clock Drivers" and "How To Write a Reference Clock Driver" pages (available as part of the HTML documentation provided in /usr/share/doc/ntp). In addition, support for a PPS signal is available as described in the "Pulse-per-second (PPS) Signal Interfacing" page (available as part of the HTML documentation provided in /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 "Line Disciplines and Streams Drivers" page (available as part of the HTML documentation provided in /usr/share/doc/ntp).
A reference clock will generally (though not always) be a radio timecode receiver which is synchronized to a source of standard time such as the services offered by the NRC in Canada and NIST and USNO in the US. The interface between the computer and the timecode receiver is device dependent, but is usually a serial port. A device driver specific to each reference clock must be selected and compiled in the distribution; however, most common radio, satellite and modem clocks are included by default. Note that an attempt to configure a reference clock when the driver has not been compiled or the hardware port has not been appropriately configured results in a scalding remark to the system log file, but is otherwise non hazardous.
For the purposes of configuration,
ntpd(1ntpdmdoc)
treats
reference clocks in a manner analogous to normal NTP peers as much
as possible.
Reference clocks are identified by a syntactically
correct but invalid IP address, in order to distinguish them from
normal NTP peers.
Reference clock addresses are of the form
127.127.t.u,
where
t
is an integer
denoting the clock type and
u
indicates the unit
number in the range 0-3.
While it may seem overkill, it is in fact
sometimes useful to configure multiple reference clocks of the same
type, in which case the unit numbers must be unique.
The
server
command is used to configure a reference
clock, where the
address
argument in that command
is the clock address.
The
key,
version
and
ttl
options are not used for reference clock support.
The
mode
option is added for reference clock support, as
described below.
The
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
"Mitigation Rules and the prefer Keyword"
(available as part of the HTML documentation
provided in
/usr/share/doc/ntp)
page.
The
minpoll
and
maxpoll
options have
meaning only for selected clock drivers.
See the individual clock
driver document pages for additional information.
The
fudge
command is used to provide additional
information for individual clock drivers and normally follows
immediately after the
server
command.
The
address
argument specifies the clock address.
The
refid
and
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
fudge
command as well.
The stratum number of a reference clock is by default zero.
Since the
ntpd(1ntpdmdoc)
daemon adds one to the stratum of each
peer, a primary server ordinarily displays an external stratum of
one.
In order to provide engineered backups, it is often useful to
specify the reference clock stratum as greater than zero.
The
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
refid
option is used for this purpose.
Except where noted,
these options apply to all clock drivers.
server 127.127.t.u [prefer] [mode int] [minpoll int] [maxpoll int]prefermode intminpoll intmaxpoll intminpoll
and
maxpoll
default to 6 (64 s).
For modem reference clocks,
minpoll
defaults to 10 (17.1 m) and
maxpoll
defaults to 14 (4.5 h).
The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
fudge 127.127.t.u [time1 sec] [time2 sec] [stratum int] [refid string] [mode int] [flag1 0 | 1] [flag2 0 | 1] [flag3 0 | 1] [flag4 0 | 1]server
command which configures the driver.
Note that the same capability
is possible at run time using the
ntpdc(1ntpdcmdoc)
program.
The options are interpreted as
follows:
time1 secenable
command described in
Miscellaneous Options
page and operates as described in the
"Reference Clock Drivers"
page
(available as part of the HTML documentation
provided in
/usr/share/doc/ntp).
time2 secsstratum intrefid stringmode intflag1 0 | 1flag2 0 | 1flag3 0 | 1flag4 0 | 1flag4
is used to enable recording monitoring
data to the
clockstats
file configured with the
filegen
command.
Further information on the
filegen
command can be found in
Monitoring Options.
broadcastdelay secondscalldelay delaydriftfile driftfile-f
command line option.
If the file exists, it is read at
startup in order to set the initial frequency and then updated once per
hour with the current frequency computed by the daemon.
If the file name is
specified, but the file itself does not exist, the starts with an initial
frequency of zero and creates the file when writing it for the first time.
If this command is not given, the daemon will always start with an initial
frequency of zero.
The file format consists of a single line containing a single
floating point number, which records the frequency offset measured
in parts-per-million (PPM).
The file is updated by first writing
the current drift value into a temporary file and then renaming
this file to replace the old version.
This implies that
ntpd(1ntpdmdoc)
must have write permission for the directory the
drift file is located in, and that file system links, symbolic or
otherwise, should be avoided.
dscp valueenable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]disable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]ntpdc(1ntpdcmdoc)
utility program.
authenable.
bclientmulticastclient
command with default
address.
The default for this flag is
disable.
calibratedisable.
kernelenable
if support is available, otherwise
disable.
mode7ntpdc(1ntpdcmdoc)
program.
The default for this flag is disable.
This flag is excluded from runtime configuration using
ntpq(1ntpqmdoc).
The
ntpq(1ntpqmdoc)
program provides the same capabilities as
ntpdc(1ntpdcmdoc)
using standard mode 6 requests.
monitorntpdc(1ntpdcmdoc)
program
and the
monlist
command or further information.
The
default for this flag is
enable.
ntpenable.
peer_clear_digest_earlyntpd(1ntpdmdoc)
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
peerstats
file for evidence of any of these attacks.
The
default for this flag is
enable.
statsdisable.
unpeer_crypto_earlyntpd(1ntpdmdoc)
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
peerstats
file for evidence of any of these attacks.
The
default for this flag is
enable.
unpeer_crypto_nak_earlyntpd(1ntpdmdoc)
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
peerstats
file for evidence of any of these attacks.
The
default for this flag is
enable.
unpeer_digest_earlyntpd(1ntpdmdoc)
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
peerstats
file for evidence of any of these attacks.
The
default for this flag is
enable.
includefile includefilentpd(1ntpdmdoc)
on multiple hosts, with (mostly) common options (e.g., a
restriction list).
leapsmearinterval secondsntpd(1ntpdmdoc)
was built with the
--enable-leap-smear
option to the
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.
logconfig configkeywordsyslog(3)
facility or the alternate
logfile
log file.
By default, all output is turned on.
All
configkeyword
keywords can be prefixed with
=,
+
and
-,
where
=
sets the
syslog(3)
priority mask,
+
adds and
-
removes
messages.
syslog(3)
messages can be controlled in four
classes
(clock, peer, sys and sync).
Within these classes four types of messages can be
controlled: informational messages
(info),
event messages
(events),
statistics messages
(statistics)
and
status messages
(status).
Configuration keywords are formed by concatenating the message class with
the event class.
The
all
prefix can be used instead of a message class.
A
message class may also be followed by the
all
keyword to enable/disable all
messages of the respective message class.
Thus, a minimal log configuration
could look like this:
logconfig =syncstatus +sysevents
This would just list the synchronizations state of
ntpd(1ntpdmdoc)
and the major system events.
For a simple reference server, the
following minimum message configuration could be useful:
logconfig =syncall +clockall
This configuration will list all clock information and
synchronization information.
All other events and messages about
peers, system events and so on is suppressed.
logfile logfilesyslog(3)
facility.
This is the same operation as the
-l
command line option.
setvar variable [default]name=value
is followed by the
default
keyword, the
variable will be listed as part of the default system variables
(rv command)).
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
setvar
mechanism.
There are three special variables that contain the names
of all variable of the same group.
The
sys_var_list
holds
the names of all system variables.
The
peer_var_list
holds
the names of all peer variables and the
clock_var_list
holds the names of the reference clock variables.
tinker [allan allan | dispersion dispersion | freq freq | huffpuff huffpuff | panic panic | step step | stepback stepback | stepfwd stepfwd | stepout stepout]The variables operate as follows:
allan allandispersion dispersionfreq freqhuffpuff huffpuffpanic panicstep stepstepback stepbackstepfwd stepfwdstepout stepoutrlimit [memlock Nmegabytes | stacksize N4kPages filenum Nfiledescriptors]memlock Nmegabytes-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".
stacksize N4kPagesmlockall()
function.
Defaults to 50 4k pages (200 4k pages in OpenBSD).
filenum Nfiledescriptorstrap host_address [port port_number] [interface interface_address]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.
hop ...This section was generated by AutoGen,
using the agtexi-cmd template and the option descriptions for the ntp.conf program.
This software is released under the NTP license, <http://ntp.org/license>.
ntpd(1ntpdmdoc),
ntpdc(1ntpdcmdoc),
ntpq(1ntpqmdoc)
In addition to the manual pages provided,
comprehensive documentation is available on the world wide web
at
http://www.ntp.org/.
A snapshot of this documentation is available in HTML format in
/usr/share/doc/ntp.
David L. Mills, Network Time Protocol (Version 4), RFC5905
The syntax checking is not picky; some combinations of ridiculous and even hilarious options and modes may not be detected.
The ntpkey_host files are really digital certificates. These should be obtained via secure directory services when they become universally available.
This document was derived from FreeBSD.