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