NAME¶
ntp.conf - NTP server configuration file
SYNOPSIS¶
ntp.conf
DESCRIPTION¶
Ordinarily,
ntpd reads the
ntp.conf configuration file at startup
time in order to determine the synchronization sources and operating modes. It
is also possible to specify a working, although limited, configuration
entirely on the command line, obviating the need for a configuration file.
This may be particularly useful when the local host is to be configured as a
broadcast/multicast client, with all peers being determined by listening to
broadcasts at run time.
Usually, the configuration file is installed in the
/etc directory, but
could be installed elsewhere (see the -c
conffile 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. Optional
arguments are delimited by [ ] in the following descriptions, while
alternatives are separated by |. The notation [ ... ] means an optional,
indefinite repetition of the last item before the [ ... ].
Following is a description of the configuration commands in NTPv4. There are two
classes of commands, configuration commands that configure an association with
a remote server, peer or reference clock, and auxiliary commands that specify
environmental variables that control various related operations.
Configuration Commands¶
The various modes are determined by the command keyword and 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). The options that can be used with these commands are listed
below.
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. 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.
There are three types of associations: persistent, preemptable and ephemeral.
Persistent associations are mobilized by a configuration command and never
demobilized. Preemptable associations, which are new to NTPv4, are mobilized
by a configuration command which includes the
prempt flag and are
demobilized by timeout or error. Ephemeral associations are mobilized upon
arrival of designated messages and demobilized by timeout or error.
- server address [options ...]
- peer address [options ...]
- broadcast address [options ...]
- manycastclient address [options
...]
- These four 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 a IP address in dotted-quad notation. Additional
information on association behavior can be found in the Association
Management page.
- server
- For type s and r addresses (only), this command normally
mobilizes a persistent client mode association with the specified remote
server or local reference clock. If the preempt flag is specified, a
preemptable association is mobilized instead. In client mode the client
clock can synchronize to the remote server or local reference clock, but
the remote server can never be synchronized to the client clock. This
command should NOT be used for type b or m addresses.
- 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.
- 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 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 broadcastclient or multicastclient commands
below.
- manycastclient
- For type m addresses (only), this command mobilizes a
preemptable manycast client mode association for the multicast group
address specified. In this mode a specific address must be supplied which
matches the address used on the 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 manycastclient command specifies that the host 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.
Command Options¶
- autokey
- All packets sent to and received from the server or peer
are to include authentication fields encrypted using the autokey scheme
described in the Authentication Options page. This option is valid with
all commands.
- 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
calldelay command to allow additional time for a modem or ISDN call
to complete. This option is valid with only the server command and
is a recommended option with this command when the maxpoll option
is 11 or greater.
- 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 and second packets can be changed
with the calldelay command to allow additional time for a modem or
ISDN call to complete. This option is valid with only the server
command and is a recommended option with this command.
- key key
- All packets sent to and received from the server or peer
are to include authentication fields encrypted using the specified key
identifier with values from 1 to 65534, inclusive. The default is to
include no encryption field. This option is valid with all commands.
- minpoll minpoll, maxpoll
maxpoll
- These options specify the minimum and maximum poll
intervals for NTP messages, in seconds as a power of two. The maximum poll
interval defaults to 10 (1,024 s), but can be increased by the 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 minpoll option to a
lower limit of 4 (16 s). These option are valid only with the
server and peer commands.
- mode option
- Pass the option to a reference clock driver, where
option is an integer in the range from 0 to 255, inclusive. This
option is valid only with type r addresses.
- noselect
- Marks the server as unused, except for display purposes.
The server is discarded by the selection algorithm. This option is valid
only with the server and peer commands.
- preempt
- Specifies the association as preemptable rather than the
default persistent. This option is valied only with the server
command.
- 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 Mitigation Rules and the prefer
Keyword page for further information. This option is valid only with the
server and peer commands.
- true
- Force the association to assume truechimer status; that is,
always survive the selection and clustering algorithms. This option can be
used with any association, but is most useful for reference clocks with
large jitter on the serial port and precision pulse-per-second (PPS)
signals. Caution: this option defeats the algorithms designed to cast out
falsetickers and can allow these sources to set the system clock. This
option is valid only with the server and peer commands.
- ttl ttl
- This option is used only with broadcast server and manycast
client modes. It specifies the time-to-live ttl to use on broadcast
server and multicast server and the maximum 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.
- version version
- Specifies the version number to be used for outgoing NTP
packets. Versions 1-4 are the choices, with version 4 the default. This
option is valid only with the server, peer and
broadcast commands.
- xleave
- Operate in interleaved mode (symmetric and broadcast modes
only). (see NTP Interleaved Modes)
Auxiliary Commands¶
- broadcastclient [novolley]
- This command enables reception of broadcast server messages
to any local interface (type b) address. Ordinarily, 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, after which it continues in listen-only mode. If the
novolley keyword is present, the exchange is not used and the value
specified in the broadcastdelay command is used or, if the
broadcastdelay command is not used, the default 4.0 ms. 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 the Authentication Options page. Note that
the novolley keyword is incompatible with public key
authentication.
- manycastserver address [...]
- This command enables reception of manycast client messages
to the multicast group address(es) (type m) specified. At least one
address is required. 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 the Authentication Options
page.
- multicastclient 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
the Authentication Options page.
Authentication Commands¶
- autokey [logsec]
- Specifies the interval between regenerations of the session
key list used with the autokey feature. 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.
- revoke [logsec]
- Specifies the interval between recomputations of the
private value used with the autokey feature, which ordinarily requires an
expensive public- key computation. The default value is 12 (65,536 s or
about 18 hours). For poll intervals above the specified interval, a new
private value will be recomputed for every message sent.
Miscellaneous Options¶
- driftfile driftfile
- This command specifies the name of the file use to record
the frequency offset of the local clock oscillator. If the file exists, it
is read at startup in order to set the initial frequency offset and then
updated once per hour with the current frequency offset computed by the
daemon. If the file does not exist or this command is not given, the
initial frequency offset is assumed to be zero. In this case, it may take
some hours for the frequency to stabilize and the residual timing errors
to subside.
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 must have write permission for the directory the
drift file is located in, and that file system links, symbolic or
otherwise, should be avoided.
- enable [auth | bclient | calibrate | kernel | monitor |
ntp | pps | stats]
- disable [auth | bclient | calibrate | kernel | monitor |
ntp | pps | stats]
- Provides a way to enable or disable various server options.
Flags not mentioned are unaffected. Note that all of these flags can be
controlled remotely using the ntpdc utility program.
- 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 enable.
- bclient
- Enables the server to listen for a message from a broadcast
or multicast server, as in the multicastclient command with default
address. The default for this flag is disable.
- calibrate
- Enables the calibrate feature for reference clocks. The
default for this flag is disable.
- kernel
- Enables the kernel time discipline, if available. The
default for this flag is enable if support is available, otherwise
disable.
- monitor
- Enables the monitoring facility. See the ntpdc
program and the monlist command or further information. The default
for this flag is enable.
- 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 enable.
- pps
- Enables the pulse-per-second (PPS) signal when frequency
and time is disciplined by the precision time kernel modifications. See
the A Kernel Model for Precision Timekeeping page for further information.
The default for this flag is disable.
- stats
- Enables the statistics facility. See the Monitoring Options
page for further information. The default for this flag is disable.
- includefile includefile
- This command allows additional configuration commands to be
included from a separate file. Include files may be nested to a depth of
five; upon reaching the end of any include file, command processing
resumes in the previous configuration file. This option is useful for
sites that run ntpd on multiple hosts, with (mostly) common options
(e.g., a restriction list).
- interface [listen | ignore | drop]
[ all | ipv4 | ipv6 | wildcard | name |
address[/prefixlen]]
- This command controls which network addresses ntpd
opens, and whether input is dropped without processing. The first
parameter determines the action for addresses which match the second
parameter. That parameter specifies a class of addresses, or a specific
interface name, or an address. In the address case, prefixlen
determines how many bits must match for this rule to apply. ignore
prevents opening matching addresses, drop causes ntpd to
open the address and drop all received packets without examination.
Multiple interface commands can be used. The last rule which
matches a particular address determines the action for it.
interface commands are disabled if any -I,
--interface, -L, or --novirtualips command-line
options are used. If none of those options are used and no
interface actions are specified in the configuration file, all
available network addresses are opened. The nic command is an alias
for interface.
FILES¶
/etc/ntp.conf
NOTES¶
Note that this manual page shows only the most important configuration commands.
The full documentation (see below) contains more details.
BUGS¶
The syntax checking is not picky; some combinations of ridiculous and even
hilarious options and modes may not be detected.
SEE ALSO¶
ntpd(8)
The complete documentation can be found at
/usr/share/doc/ntp-doc/html/ntpd.html#cfg in the package ntp-doc.