Penguin
Annotated edit history of ntpd(1) version 3, including all changes. View license author blame.
Rev Author # Line
3 IanMcDonald 1 <verbatim>
1 perry 2 NAME
3 IanMcDonald 3 ntpd - Network Time Protocol (NTP) daemon.
4
1 perry 5 SYNOPSIS
3 IanMcDonald 6 ntpd [ -aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ]
7 [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority ] [ -r
8 broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ] [ -v
9 variable ] [ -V variable ]
1 perry 10
11
3 IanMcDonald 12 DESCRIPTION
13 ntpd is an operating system daemon which sets and maintains the system
14 time-of-day in synchronism with Internet standard time servers. Ntpd
15 is a complete implementation of the Network Time Protocol (NTP) version
16 4 but also retains compatibility with version 3, as defined by RFC-1305
17 and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively.
18 ntpd does most computations in 64-bit floating point arithmetic and
19 does relatively clumsy 64-bit fixed point operations only when neces‐
20 sary to preserve the ultimate precision, about 232 picoseconds. While
21 the ultimate precision, is not achievable with ordinary workstations
22 and networks of today, it may be required with future nanosecond CPU
23 clocks and gigabit LANs.
1 perry 24
3 IanMcDonald 25 The daemon can operate in any of several modes, including symmetric
26 active/passive, client/server broadcast/multicast and manycast. A
27 broadcast/multicast or manycast client can discover remote servers,
28 compute server-client propagation delay correction factors and config‐
29 ure itself automatically. This makes it possible to deploy a fleet of
30 workstations without specifying configuration details specific to the
31 local environment.
1 perry 32
3 IanMcDonald 33 Ordinarily, ntpd reads the ntp.conf configuration file at startup time
34 in order to determine the synchronization sources and operating modes.
35 It is also possible to specify a working, although limited configura‐
36 tion entirely on the command line, obviating the need for a configura‐
37 tion file. This may be particularly appropriate when the local host is
38 to be configured as a broadcast/multicast client or manycast client,
39 with all peers being determined by listening to broadcasts at run time.
1 perry 40
3 IanMcDonald 41 If NetInfo support is built into ntpd then ntpd will attempt to read
42 its configuration from the NetInfo if the default ntp.conf file cannot
43 be read and no file is specified by the -c option.
1 perry 44
3 IanMcDonald 45 Various internal ntpd variables can be displayed and configuration
46 options altered while the daemon is running using the ntpq and ntpd
47 utility programs.
1 perry 48
3 IanMcDonald 49 When ntpd starts it looks at the value of umask, and if it is zero ntpd
50 will set the umask to 0222.
1 perry 51
3 IanMcDonald 52 OPTIONS
53 -a Enable authentication mode (default).
1 perry 54
3 IanMcDonald 55 -A Disable authentication mode.
1 perry 56
3 IanMcDonald 57 -b Synchronize using NTP broadcast messages.
1 perry 58
3 IanMcDonald 59 -c conffile
60 Specify the name and path of the configuration file.
1 perry 61
3 IanMcDonald 62 -d Specify debugging mode. This flag may occur multiple times,
63 with each occurrence indicating greater detail of display.
1 perry 64
3 IanMcDonald 65 -D level
66 Specify debugging level directly.
1 perry 67
3 IanMcDonald 68 -f driftfile
69 Specify the name and path of the drift file.
1 perry 70
3 IanMcDonald 71 -g Normally, the daemon exits if the offset exceeds a 1000s sanity
72 limit. This option overrides this limit and allows the time to
73 be set to an value without restriction.
1 perry 74
3 IanMcDonald 75 -i jaildir
76 Chroot the server to the directory jaildir. This option also
77 implies that the server attempts to drop root privileges at
78 startup (otherwise, chroot gives very little additional secu‐
79 rity), and it is only available if the OS supports to run the
80 server without full root privileges. You may need to also spec‐
81 ify a -u option.
1 perry 82
3 IanMcDonald 83 -k keyfile
84 Specify the name and path of the file containing the NTP authen‐
85 tication keys.
1 perry 86
3 IanMcDonald 87 -l logfile
88 Specify the name and path of the log file. The default is the
89 system log facility.
1 perry 90
3 IanMcDonald 91 -L Do not listen to virtual IPs. The default is to listen.
1 perry 92
3 IanMcDonald 93 -m Synchronize using NTP multicast messages on the IP multicast
94 group address 224.0.1.1 (requires multicast kernel).
1 perry 95
3 IanMcDonald 96 -n Don’t fork, i.e. run in the foreground.
1 perry 97
3 IanMcDonald 98 -N To the extent permitted by the operating system, run the ntpd at
99 the highest priority.
1 perry 100
3 IanMcDonald 101 -p pidfile
102 Specify the name and path to record the daemon’s process ID.
1 perry 103
3 IanMcDonald 104 -P Override the priority limit set by the operating system. Not
105 recommended for sissies.
1 perry 106
3 IanMcDonald 107 -q Exit the ntpd just after the first time the clock is set. This
108 behavior mimics that of the ntpdate program, which is to be
109 retired. The -g and -x options can be used with this option.
110 Note: The kernel time discipline is disabled with this option.
1 perry 111
3 IanMcDonald 112 -r broadcastdelay
113 Specify the default propagation delay from the broadcast/multi‐
114 cast server and this computer. This is necessary only if the
115 delay cannot be computed automatically by the protocol.
1 perry 116
3 IanMcDonald 117 -s statsdir
118 Specify the directory path for files created by the statistics
119 facility.
1 perry 120
3 IanMcDonald 121 -t key Add a key number to the trusted key list.
1 perry 122
3 IanMcDonald 123 -u user[:group]
124 Specify a user, and optionally a group, to switch to.
1 perry 125
3 IanMcDonald 126 -v variable
1 perry 127
3 IanMcDonald 128 -V variable
129 Add a system variable listed by default.
1 perry 130
3 IanMcDonald 131 -x Ordinarily, if the time is to be adjusted more than 128 ms, it
132 is stepped, not gradually slewed. This option forces the time
133 to be slewed in all cases. Note: Since the slew rate is limited
134 to 0.5 ms/s, each second of adjustment requires an amortization
135 interval of 2000 s. Thus an adjustment of many seconds can take
136 hours or days to amortize.
1 perry 137
3 IanMcDonald 138 THE CONFIGURATION FILE
139 The ntpd configuration file is read at initial startup in order to
140 specify the synchronization sources, modes and other related informa‐
141 tion. Usually, it is installed in the /etc directory, but could be
142 installed elsewhere (see the -c conffile command line option). The
143 file format is similar to other Unix configuration files - comments
144 begin with a # character and extend to the end of the line; blank lines
145 are ignored. Configuration commands consist of an initial keyword fol‐
146 lowed by a list of arguments, some of which may be optionally separated
147 by whitespace. Commands may not be continued over multiple lines.
148 Arguments may be host names, host addresses written in numeric dotted-
149 quad form, integers, floating point numbers (when specifying times in
150 seconds) and text strings. Optional arguments are delimited by [ ] in
151 the following descriptions, while alternatives are separated by |. The
152 notation [ ... ] means an optional, indefinite repetition of the last
153 item before the [ ... ].
1 perry 154
3 IanMcDonald 155 While there is a rich set of options available, the only required
156 option is one or more of the server, peer, broadcast or manycastclient
157 commands.
1 perry 158
3 IanMcDonald 159 Following is a description of the NTPv4 configuration commands. These
160 commands have the same basic functions as in NTPv3 and in some cases
161 new functions and new operands. The various modes are determined by
162 the command keyword and the type of the required IP address. Addresses
163 are classed by type as (s) a remote server or peer (IP class A, B and
164 C), (b) the broadcast address of a local interface, (m) a multicast
165 address (IP class D), or (r) a reference clock address (127.127.x.x).
166 Note that, while autokey and burst modes are supported by these com‐
167 mands, their effect in some weird mode combinations can be meaningless
168 or even destructive.
1 perry 169
3 IanMcDonald 170 peer address
171 [autokey | key key] [burst] [version version] [prefer] [minpoll
172 minpoll] [maxpoll maxpoll]
1 perry 173
3 IanMcDonald 174 For type s addresses (only), this operates as the current peer command
175 which mobilizes a persistent symmetric-active mode association, except
176 that additional modes are available. This command should NOT be used
177 for type b, m or r addresses.
1 perry 178
3 IanMcDonald 179 The peer command specifies that the local server is to operate in sym‐
180 metric active mode with the remote server. In this mode, the local
181 server can be synchronized to the remote server and, in addition, the
182 remote server can be synchronized by the local server. This is useful
183 in a network of servers where, depending on various failure scenarios
184 either the local or remote server may be the better source of time.
1 perry 185
3 IanMcDonald 186 server address
187 [autokey | key key] [burst] [version version] [prefer] [minpoll
188 minpoll] [maxpoll maxpoll]
1 perry 189
3 IanMcDonald 190 For type s and r addresses, this operates as the NTPv3 server command
191 which mobilizes a persistent client mode association. The server com‐
192 mand specifies that the local server is to operate in client mode with
193 the specified remote server. In this mode, the local server can be
194 synchronized to the remote server, but the remote server can never be
195 synchronized to the local server.
1 perry 196
3 IanMcDonald 197 broadcast address
198 [autokey | key key] [burst] [version version] [minpoll minpoll]
199 [maxpoll maxpoll] [ttl ttl]
1 perry 200
3 IanMcDonald 201 For type b and m addresses (only), this operates as the current NTPv3
202 broadcast command, which mobilizes a persistent broadcast mode associa‐
203 tion, except that additional modes are available. Multiple commands
204 can be used to specify multiple local broadcast interface (subnets)
205 and/or multiple multicast groups. Note that local broadcast messages
206 go only to the interface associated with the subnet specified but mul‐
207 ticast messages go to all interfaces. In the current implementation,
208 the source address used for these messages is the Unix host default
209 address.
1 perry 210
3 IanMcDonald 211 In broadcast mode, the local server sends periodic broadcast messages
212 to a client population at the address specified, which is usually the
213 broadcast address on (one of) the local network(s) or a multicast
214 address assigned to NTP. The IANA has assigned the multicast group
215 address 224.0.1.1 exclusively to NTP, but other nonconflicting
216 addresses can be used to contain the messages within administrative
217 boundaries. Ordinarily, this specification applies only to the local
218 server operating as a sender; for operation as a broadcast client, see
219 the broadcastclient or multicastclient commands below.
1 perry 220
3 IanMcDonald 221 manycastclient address
222 [autokey | key key] [burst] [version version] [minpoll minpoll]
223 [maxpoll maxpoll] [ttl ttl]
1 perry 224
3 IanMcDonald 225 For type m addresses (only), this mobilizes a manycast client-mod asso‐
226 ciation for the multicast address specified. In this case specific
227 address must be supplied which matches the address used on th manycast‐
228 server command for the designated manycast servers. The NT multicast
229 address 224.0.1.1 assigned by the IANA should NOT be used unless spe‐
230 cific means are taken to avoid spraying large areas of th Internet with
231 these messages and causing a possibly massive implosion o replies at
232 the sender
1 perry 233
3 IanMcDonald 234 The manycast command specifies that the local server is to operate i
235 client mode with the remote server that are discovered as the result o
236 broadcast/multicast messages. The client broadcasts a request message
237 to the group address associated with the specified address an specifi‐
238 cally enabled servers respond to these messages. The client selects
239 the servers providing the best time and continues as with the server
240 command. The remaining servers are discarded as if never heard
1 perry 241
3 IanMcDonald 242 These four commands specify the time server name or address to be use
243 and the mode in which to operate. The address can be either a DNS name
244 or a IP address in dotted-quad notation. Additional information on
245 association behaviour can be found in the Association Management page
1 perry 246
3 IanMcDonald 247 autokey
248 All packets sent to the address are to include authentication
249 field encrypted using the autokey scheme.
1 perry 250
3 IanMcDonald 251 burst At each poll interval, send a burst of eight packets spaced,
252 instead of the usual one.
1 perry 253
3 IanMcDonald 254 key key
255 All packets sent to the address are to include authentication
256 field encrypted using the specified key identifier, which is an
257 unsigned 32-bit integer less than 65536. The default is to
258 include no encryption field.
1 perry 259
3 IanMcDonald 260 version version
261 Specifies the version number to be used for outgoing NTP pack‐
262 ets. Versions 1-4 are the choices, with version 4 the default.
1 perry 263
3 IanMcDonald 264 prefer Marks the server as preferred. All other things being equal,
265 this host will be chosen for synchronization among a set of cor‐
266 rectly operating hosts. See the Mitigation Rules and the prefer
267 Keyword page for further information
1 perry 268
3 IanMcDonald 269 ttl ttl
270 This option is used only with broadcast mode. It specifies the
271 time-to-live ttl to use on multicast packets. Selection of the
272 proper value, which defaults to 127, is something of a black art
273 and must be coordinated with the network administrator.
1 perry 274
3 IanMcDonald 275 minpoll minpoll maxpoll maxpoll
276 These options specify the minimum and maximum polling intervals
277 for NTP messages. The values are interpreted as dual logarithms
278 (2 ^ x). The default range is 6 (2^6 = 64 s) to 10 (2^10 = 1024
279 s). The allowable range is 4 (16 s) to 17 (36.4 h).
1 perry 280
3 IanMcDonald 281 broadcastclient
282 This command directs the local server to listen for and respond
283 to broadcast messages received on any local interface. Upon
284 hearing a broadcast message for the first time, the local server
285 measures the nominal network delay using a brief client/server
286 exchange with the remote server, then enters the broadcastclient
287 mode, in which it listens for and synchronizes to succeeding
288 broadcast messages. Note that, in order to avoid accidental or
289 malicious disruption in this mode, both the local and remote
290 servers should operate using authentication and the same trusted
291 key and key identifiers.
1 perry 292
3 IanMcDonald 293 multicastclient
294 [address] [...] This command directs the local server to listen
295 for multicast messages at the group address(es) of these global
296 network. The default address is that assigned by the Number
297 Czar to NTP (224.0.1.1). This command operates in the same way
298 as the broadcastclient command, but uses IP multicasting. Sup‐
299 port for this command requires a multicast kernel.
1 perry 300
3 IanMcDonald 301 driftfile driftfile
302 This command specifies the name of the file use to record the
303 frequency offset of the local clock oscillator. If the file
304 exists, it is read at startup in order to set the initial fre‐
305 quency offset and then updated once per hour with the current
306 frequency offset computed by the daemon. If the file does not
307 exist or this command is not given, the initial frequency offset
308 is assume zero. In this case, it may take some hours for the
309 frequency to stabilize and the residual timing errors to sub‐
310 side.
1 perry 311
3 IanMcDonald 312 The file format consists of a single line containing a single floating
313 point number, which records the frequency offset measured in parts-per-
314 million (PPM). The file is updated by first writing the current drift
315 value into a temporary file and then renaming this file to replace the
316 old version. This implies that ntpd must have write permission for the
317 directory the drift file is located in, and that file system links,
318 symbolic or otherwise, should be avoided.
1 perry 319
3 IanMcDonald 320 manycastserver address [...]
321 This command directs the local server to listen for and respond
322 to broadcast messages received on any local interface, and in
323 addition enables the server to respond to client mode messages
324 to the multicast group address(es) (type m) specified. At least
325 one address is required, but the NTP multicast address 224.0.1.1
326 assigned by the IANA should NOT be used, unless specific means
327 are taken to limit the span of the reply and avoid a possible
328 massive implosion at the original sender.
1 perry 329
3 IanMcDonald 330 revoke [logsec]
331 Specifies the interval between recomputations of the private
332 value used with the autokey feature, which ordinarily requires
333 an expensive public- key computation. The default value is 12
334 (65,536 s or about 18 hours). For poll intervals above the
335 specified interval, a new private value will be recomputed for
336 every message sent.
1 perry 337
3 IanMcDonald 338 autokey [logsec]
339 Specifies the interval between regenerations of the session key
340 list used with the autokey feature. Note that the size of the
341 key list for each association depends on this interval and the
342 current poll interval. The default value is 12 (4096 s or about
343 1.1 hours). For poll intervals above the specified interval, a
344 session key list with a single entry will be regenerated for
345 every message sent.
1 perry 346
3 IanMcDonald 347 enable [auth | bclient | kernel | monitor | ntp | stats]
1 perry 348
3 IanMcDonald 349 disable [auth | bclient | kernel | monitor | ntp | stats]
350 Provides a way to enable or disable various server options.
351 Flags not mentioned are unaffected. Note that all of these
352 flags can be controlled remotely using the ntpdc utility pro‐
353 gram.
1 perry 354
3 IanMcDonald 355 auth Enables the server to synchronize with unconfigured peers only
356 if the peer has been correctly authenticated using a trusted key
357 and key identifier. The default for this flag is enable.
1 perry 358
3 IanMcDonald 359 bclient
360 When enabled, this is identical to the broadcastclient command.
361 The default for this flag is disable.
1 perry 362
3 IanMcDonald 363 kernel Enables the precision-time kernel support for the ntp_adjtime()
364 system call, if implemented. Ordinarily, support for this rou‐
365 tine is detected automatically when the NTP daemon is compiled,
366 so it is not necessary for the user to worry about this flag.
367 It flag is provided primarily so that this support can be dis‐
368 abled during kernel development.
1 perry 369
3 IanMcDonald 370 monitor
371 Enables the monitoring facility. See the ntpdc program and the
372 monlist command or further information. The default for this
373 flag is enable.
1 perry 374
3 IanMcDonald 375 ntp Enables the server to adjust its local clock by means of NTP.
376 If disabled, the local clock free-runs at its intrinsic time and
377 frequency offset. This flag is useful in case the local clock
378 is controlled by some other device or protocol and NTP is used
379 only to provide synchronization to other clients In this case,
380 the local clock driver can be used to provide this function and
381 also certain time variables for error estimates and leap-indica‐
382 tors. The default for this flag is enable.
1 perry 383
3 IanMcDonald 384 stats Enables the statistics facility. The default for this flag is
385 enable.
1 perry 386
3 IanMcDonald 387 FILES
388 /etc/ntp.conf
389 - the default name of the configuration file
1 perry 390
3 IanMcDonald 391 /etc/ntp.drift
392 - the default name of the drift file
1 perry 393
3 IanMcDonald 394 /etc/ntp.key
395 - the default name of the key file
1 perry 396
3 IanMcDonald 397 BUGS
398 Ntpd has gotten rather fat. While not huge, it has gotten larger than
399 might be desirable for an elevated-priority daemon running on a work‐
400 station, particularly since many of the fancy features which consume
401 the space were designed more with a busy primary server, rather than a
402 high stratum workstation, in mind.
1 perry 403
3 IanMcDonald 404 AUTHOR
405 David L. Mills <mills@udel.edu>. Manpage abstracted from the html doc‐
406 umentation by Peter Breuer <ptb@it.uc3m.es>.
407 </verbatim>
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.