1
.TH NTP.CONF 5 "2008-04-09" "Debian" "The Network Time Protocol (NTP) Distribution"
3
ntp.conf \- NTP server configuration file
7
Ordinarily, \fBntpd\fR reads the \fIntp.conf\fR configuration file at startup
8
time in order to determine the synchronization sources and operating modes.
9
It is also possible to specify a working, although limited, configuration
10
entirely on the command line, obviating the need for a configuration file.
11
This may be particularly useful when the local host is to be configured as a
12
broadcast/multicast client, with all peers being determined by listening to
13
broadcasts at run time.
15
Usually, the configuration file is installed in the \fI/etc\fR directory, but
16
could be installed elsewhere (see the -c \fIconffile\fR command line option).
17
The file format is similar to other Unix configuration files - comments begin
18
with a # character and extend to the end of the line; blank lines are ignored.
20
Configuration commands consist of an initial keyword followed by a list of
21
arguments, some of which may be optional, separated by whitespace. Commands
22
may not be continued over multiple lines. Arguments may be host names, host
23
addresses written in numeric, dotted-quad form, integers, floating point
24
numbers (when specifying times in seconds) and text strings. Optional
25
arguments are delimited by [ ] in the following descriptions, while
26
alternatives are separated by |. The notation [ ... ] means an optional,
27
indefinite repetition of the last item before the [ ... ].
29
Following is a description of the configuration commands in NTPv4. There are
30
two classes of commands, configuration commands that configure an association
31
with a remote server, peer or reference clock, and auxilliary commands that
32
specify environmental variables that control various related operations.
33
.SS "Configuration Commands"
34
The various modes are determined by the command keyword and the required IP
35
address. Addresses are classed by type as (s) a remote server or peer (IPv4
36
class A, B and C), (b) the broadcast address of a local interface, (m) a
37
multicast address (IPv4 class D), or (r) a reference clock address
38
(127.127.x.x). The options that can be used with these commands are listed
41
If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected,
42
support for the IPv6 address family is generated in addition to the default
43
support of the IPv4 address family. IPv6 addresses can be identified by the
44
presence of colons ":" in the address field. IPv6 addresses can be used
45
almost everywhere where IPv4 addresses can be used, with the exception of
46
reference clock addresses, which are always IPv4. Note that in contexts where
47
a host name is expected, a -4 qualifier preceding the host name forces DNS
48
resolution to the IPv4 namespace, while a -6 qualifier forces DNS resolution
49
to the IPv6 namespace.
51
There are three types of associations: persistent, preemptable and ephemeral.
52
Persistent associations are mobilized by a configuration command and never
53
demobilized. Preemptable associations, which are new to NTPv4, are mobilized
54
by a configuration command which includes the \fBprempt\fR flag and are
55
demobilized by timeout or error. Ephemeral associations are mobilized upon
56
arrival of designated messages and demobilized by timeout or error.
58
.B server \fIaddress\fR [\fIoptions\fR ...]
60
.B peer \fIaddress\fR [\fIoptions\fR ...]
62
.B broadcast \fIaddress\fR [\fIoptions\fR ...]
64
.B manycastclient \fIaddress\fR [\fIoptions\fR ...]
65
These four commands specify the time server name or address to be used and the
66
mode in which to operate. The \fIaddress\fR can be either a DNS name or a IP
67
address in dotted-quad notation. Additional information on association
68
behavior can be found in the Association Management page.
72
For type s and r addresses (only), this command normally mobilizes a
73
persistent client mode association with the specified remote server or local
74
reference clock. If the preempt flag is specified, a preemptable association
75
is mobilized instead. In client mode the client clock can synchronize to the
76
remote server or local reference clock, but the remote server can never be
77
synchronized to the client clock. This command should NOT be used for type b
81
For type s addresses (only), this command mobilizes a persistent
82
symmetric-active mode association with the specified remote peer. In this mode
83
the local clock can be synchronized to the remote peer or the remote peer can
84
be synchronized to the local clock. This is useful in a network of servers
85
where, depending on various failure scenarios, either the local or remote peer
86
may be the better source of time. This command should NOT be used for type b,
90
For type b and m addresses (only), this command mobilizes a persistent
91
broadcast mode association. Multiple commands can be used to specify multiple
92
local broadcast interfaces (subnets) and/or multiple multicast groups. Note
93
that local broadcast messages go only to the interface associated with the
94
subnet specified, but multicast messages go to all interfaces.
96
In broadcast mode the local server sends periodic broadcast messages to a
97
client population at the \fIaddress\fR specified, which is usually the
98
broadcast address on (one of) the local network(s) or a multicast address
99
assigned to NTP. The IANA has assigned the multicast group address IPv4
100
224.0.1.1 and IPv6 ff05::101 (site local) exclusively to NTP, but other
101
nonconflicting addresses can be used to contain the messages within
102
administrative boundaries. Ordinarily, this specification applies only to the
103
local server operating as a sender; for operation as a broadcast client, see
104
the \fBbroadcastclient\fR or \fBmulticastclient\fR commands below.
107
For type m addresses (only), this command mobilizes a preemptable manycast
108
client mode association for the multicast group address specified. In this
109
mode a specific address must be supplied which matches the address used on the
110
manycastserver command for the designated manycast servers. The NTP multicast
111
address 224.0.1.1 assigned by the IANA should NOT be used, unless specific
112
means are taken to avoid spraying large areas of the Internet with these
113
messages and causing a possibly massive implosion of replies at the sender.
115
The \fBmanycastclient\fR command specifies that the host is to operate in
116
client mode with the remote servers that are discovered as the result of
117
broadcast/multicast messages. The client broadcasts a request message to the
118
group address associated with the specified \fIaddress\fR and specifically
119
enabled servers respond to these messages. The client selects the servers
120
providing the best time and continues as with the server command. The
121
remaining servers are discarded as if never heard.
123
.SS "Command Options"
126
All packets sent to and received from the server or peer are to include
127
authentication fields encrypted using the autokey scheme described in the
128
Authentication Options page. This option is valid with all commands.
131
When the server is reachable, send a burst of eight packets instead of the
132
usual one. The packet spacing is normally 2 s; however, the spacing between
133
the first and second packets can be changed with the \fBcalldelay\fR command
134
to allow additional time for a modem or ISDN call to complete. This option is
135
valid with only the \fBserver\fR command and is a recommended option with this
136
command when the \fBmaxpoll\fR option is 11 or greater.
139
When the server is unreachable, send a burst of eight packets instead of the
140
usual one. The packet spacing is normally 2 s; however, the spacing between
141
the first and second packets can be changed with the \fBcalldelay\fR command
142
to allow additional time for a modem or ISDN call to complete. This option is
143
valid with only the \fBserver\fR command and is a recommended option with this
147
All packets sent to and received from the server or peer are to include
148
authentication fields encrypted using the specified key identifier with values
149
from 1 to 65534, inclusive. The default is to include no encryption field.
150
This option is valid with all commands.
152
.B minpoll \fIminpoll\fR, \fBmaxpoll\fR \fImaxpoll\fR
153
These options specify the minimum and maximum poll intervals for NTP messages,
154
in seconds as a power of two. The maximum poll interval defaults to 10 (1,024
155
s), but can be increased by the maxpoll option to an upper limit of 17 (36.4
156
h). The minimum poll interval defaults to 6 (64 s), but can be decreased by
157
the minpoll option to a lower limit of 4 (16 s). These option are valid only
158
with the \fBserver\fR and \fBpeer\fR commands.
161
Marks the server as unused, except for display purposes. The server is
162
discarded by the selection algorithm. This option is valid only with the
163
\fBserver\fR and \fBpeer\fR commands.
166
Specifies the association as preemptable rather than the default persistent.
167
This option is valied only with the \fBserver\fR command.
170
Marks the server as preferred. All other things being equal, this host will
171
be chosen for synchronization among a set of correctly operating hosts. See
172
the Mitigation Rules and the \fBprefer\fR Keyword page for further
173
information. This option is valid only with the \fBserver\fR and \fBpeer\fR
177
Force the association to assume truechimer status; that is, always survive the
178
selection and clustering algorithms. This option can be used with any
179
association, but is most useful for reference clocks with large jitter on the
180
serial port and precision pulse-per-second (PPS) signals. Caution: this
181
option defeats the algorithms designed to cast out falsetickers and can allow
182
these sources to set the system clock. This option is valid only with the
183
\fBserver\fR and \fBpeer\fR commands.
186
This option is used only with broadcast server and manycast client modes. It
187
specifies the time-to-live \fIttl\fR to use on broadcast server and multicast
188
server and the maximum \fIttl\fR for the expanding ring search with manycast
189
client packets. Selection of the proper value, which defaults to 127, is
190
something of a black art and should be coordinated with the network
193
.B version \fIversion\fR
194
Specifies the version number to be used for outgoing NTP packets. Versions
195
1-4 are the choices, with version 4 the default. This option is valid only
196
with the \fBserver\fR, \fBpeer\fR and \fBbroadcast\fR commands.
199
Allows a server/peer to be configured even if it is not reachable at
200
configuration time. It is assumed that at some point in the future the
201
network environment changes so that this server/peer can be reached. This
202
option is useful to configure servers/peers on mobile systems with
203
intermittent network access (e.g. wlan clients).
204
.SS "Auxilliary Commands"
206
.B broadcastclient \fR[\fBnovolley\fR]
207
This command enables reception of broadcast server messages to any local
208
interface (type b) address. Ordinarily, upon receiving a message for the
209
first time, the broadcast client measures the nominal server propagation delay
210
using a brief client/server exchange with the server, after which it continues
211
in listen-only mode. If the \fBnovolley\fR keyword is present, the exchange
212
is not used and the value specified in the \fBbroadcastdelay\fR command is
213
used or, if the \fBbroadcastdelay\fR command is not used, the default 4.0 ms.
214
Note that, in order to avoid accidental or malicious disruption in this mode,
215
both the server and client should operate using symmetric key or public key
216
authentication as described in the Authentication Options page. Note that the
217
\fBnovolley\fR keyword is incompatible with public key authentication.
219
.B manycastserver \fIaddress\fR [...]
220
This command enables reception of manycast client messages to the multicast
221
group address(es) (type m) specified. At least one address is required. The
222
NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used,
223
unless specific means are taken to limit the span of the reply and avoid a
224
possibly massive implosion at the original sender. Note that, in order to
225
avoid accidental or malicious disruption in this mode, both the server and
226
client should operate using symmetric key or public key authentication as
227
described in the Authentication Options page.
229
.B multicastclient \fIaddress\fR [...]
230
This command enables reception of multicast server messages to the multicast
231
group address(es) (type m) specified. Upon receiving a message for the first
232
time, the multicast client measures the nominal server propagation delay using
233
a brief client/server exchange with the server, then enters the broadcast
234
client mode, in which it synchronizes to succeeding multicast messages. Note
235
that, in order to avoid accidental or malicious disruption in this mode, both
236
the server and client should operate using symmetric key or public key
237
authentication as described in the Authentication Options page.
238
.SS "Authentication Commands"
240
.B autokey \fR[\fIlogsec\fR]
241
Specifies the interval between regenerations of the session key list
242
used with the autokey feature. Note that the size of the key list for
243
each association depends on this interval and the current poll interval.
244
The default value is 12 (4096 s or about 1.1 hours). For poll intervals
245
above the specified interval, a session key list with a single entry
246
will be regenerated for every message sent.
248
.B revoke \fR[\fIlogsec\fR]
249
Specifies the interval between recomputations of the private value used
250
with the autokey feature, which ordinarily requires an expensive public-
251
key computation. The default value is 12 (65,536 s or about 18 hours).
252
For poll intervals above the specified interval, a new private value
253
will be recomputed for every message sent.
254
.SS "Miscellaneous Options"
256
.B driftfile \fIdriftfile\fR
257
This command specifies the name of the file use to record the frequency
258
offset of the local clock oscillator. If the file exists, it is read at
259
startup in order to set the initial frequency offset and then updated
260
once per hour with the current frequency offset computed by the daemon.
261
If the file does not exist or this command is not given, the initial
262
frequency offset is assumed to be zero. In this case, it may take some hours
263
for the frequency to stabilize and the residual timing errors to
266
The file format consists of a single line containing a single floating
267
point number, which records the frequency offset measured in
268
parts-per-million (PPM). The file is updated by first writing the
269
current drift value into a temporary file and then renaming this file to
270
replace the old version. This implies that ntpd must have write
271
permission for the directory the drift file is located in, and that file
272
system links, symbolic or otherwise, should be avoided.
274
.B enable \fR[auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]
276
.B disable \fR[auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]
277
Provides a way to enable or disable various server options. Flags not
278
mentioned are unaffected. Note that all of these flags can be
279
controlled remotely using the \fBntpdc\fR utility program.
283
Enables the server to synchronize with unconfigured peers only if the peer has
284
been correctly authenticated using either public key or private key
285
cryptography. The default for this flag is enable.
288
Enables the server to listen for a message from a broadcast or multicast
289
server, as in the \fBmulticastclient\fR command with default address. The
290
default for this flag is disable.
293
Enables the calibrate feature for reference clocks. The default for this flag
297
Enables the kernel time discipline, if available. The default for this flag
298
is enable if support is available, otherwise disable.
301
Enables the monitoring facility. See the \fBntpdc\fR program and the
302
\fBmonlist\fR command or further information. The default for this flag is
306
Enables time and frequency discipline. In effect, this switch opens and
307
closes the feedback loop, which is useful for testing. The default for this
311
Enables the pulse-per-second (PPS) signal when frequency and time is
312
disciplined by the precision time kernel modifications. See the A Kernel
313
Model for Precision Timekeeping page for further information. The default for
314
this flag is disable.
317
Enables the statistics facility. See the Monitoring Options page for further
318
information. The default for this flag is disable.
321
.B includefile \fIincludefile\fR
322
This command allows additional configuration commands to be included from a
323
separate file. Include files may be nested to a depth of five; upon reaching
324
the end of any include file, command processing resumes in the previous
325
configuration file. This option is useful for sites that run \fBntpd\fR on
326
multiple hosts, with (mostly) common options (e.g., a restriction list).
330
Note that this manual page shows only the most important configuration commands.
331
The full documentation (see below) contains more details.
333
The syntax checking is not picky; some combinations of ridiculous and even
334
hilarious options and modes may not be detected.
338
The complete documentation can be found at \fI/usr/share/doc/ntp\-doc/html/ntpd.html#cfg\fR in the package ntp\-doc.
added
removed
debian/man/ntp.conf.5
