fix mandoc(1) warnings in usr.sbin/
[dragonfly.git] / usr.sbin / dntpd / dntpd.8
1 .\" $DragonFly: src/usr.sbin/dntpd/dntpd.8,v 1.19 2008/01/22 19:17:38 swildner Exp $
2 .\"
3 .\" Copyright (c) 2005 The DragonFly Project.  All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to The DragonFly Project
6 .\" by Matthew Dillon <>
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in
16 .\"    the documentation and/or other materials provided with the
17 .\"    distribution.
18 .\" 3. Neither the name of The DragonFly Project nor the names of its
19 .\"    contributors may be used to endorse or promote products derived
20 .\"    from this software without specific, prior written permission.
21 .\"
34 .\"
35 .Dd January 6, 2009
36 .Dt DNTPD 8
37 .Os
38 .Sh NAME
39 .Nm dntpd
40 .Nd Network time protocol client daemon
42 .Nm
43 .Bk -words
44 .Op Fl 46dnqstFSQ
45 .Op Fl f Ar config_file
46 .Op Fl i Ar insane_deviation
47 .Op Fl l Ar log_level
48 .Op Fl T Ar nominal_poll
49 .Op Fl L Ar maximum_poll
50 .Op targets
51 .Ek
53 The
54 .Nm
55 daemon will synchronize the system clock to one or more external NTP time
56 sources.
57 By default an initial coarse offset correction will be made if
58 time is off by greater than 2 minutes.
59 Additional sliding offset corrections will be made if necessary.
60 Once sufficient information is obtained,
61 .Nm
62 will also correct the clock frequency.
63 Over the long haul the frequency can
64 usually be corrected to within 2 ppm of the time source.
65 Offset errors can
66 typically be corrected to within 20 milliseconds, or within 1 millisecond of
67 a low latency time source.
68 .Pp
69 By default
70 .Nm
71 will load its configuration from
72 .Pa /etc/dntpd.conf
73 and run as a daemon (background itself).
74 If you re-execute the binary it will automatically kill the currently running
75 .Nm
76 daemon.
77 If you run
78 .Nm
79 with the -Q option any currently running daemon will be killed and
80 no new daemon will be started.
81 .Pp
82 The following command line options are available:
83 .Bl -tag -width Fl
84 .It Fl 4
85 Forces
86 .Nm
87 to use only IPv4 addresses.
88 .It Fl 6
89 Forces
90 .Nm
91 to use only IPv6 addresses.
92 .It Fl d
93 Run in debug mode.
94 Implies
95 .Fl F ,
96 .Fl l Ar 99 ,
97 and
98 .Fl f Ar /dev/null
99 and logs to stderr instead of syslog.
100 The normal client code is run and time corrections will be made.
101 .It Fl n
102 No-update mode.
103 No actual update is made any time the client would
104 otherwise normally update the system frequency or offset.
105 .It Fl q
106 Quiet mode.
107 Implies a logging level of 0.
108 .It Fl s
109 Issue a coarse offset correction on startup.
110 Normally a coarse offset
111 correction is only made when the time differential is greater than 2
112 minutes.
113 This option will cause the initial offset correction to be
114 a coarse correction regardless.
115 Note that the system will still not make
116 a correction unless the offset error is greater than 4 times the standard
117 deviation of the queries.
118 .It Fl t
119 Test mode.
120 Implies
121 .Fl F ,
122 .Fl l Ar 99 ,
123 .Fl n ,
124 and
125 .Fl f Ar /dev/null
126 and logs to stderr instead of syslog.
127 A single linear regression is
128 accumulated at the nominal polling rate and reported until terminated.
129 No time corrections are made.
130 This option is meant for testing only.
131 Note that frequency corrections based on internet time sources typically
132 require a long (10-30min) polling rate to be well correlated.
133 .It Fl F
134 Run in the foreground.
135 Unlike debug mode, this option will still log to syslog.
136 .It Fl S
137 Do not set the time immediately on startup (default).
138 .It Fl Q
139 Terminate any running background daemon and exit.
140 .It Fl f Ar config_file
141 Specify the configuration file.
142 The default is
143 .Pa /etc/dntpd.conf .
144 .It Fl i Ar insane_deviation
145 Specify how much deviation is allowed in calculated offsets, in seconds.
146 Fractions may be specified.
147 A quorum of servers must agree with the one we select as being the best time
148 source in order for us to select that source.
149 The default deviation allowed is a fairly expansive 0.5 seconds.
150 Note that offset errors due to internet packet latency can
151 exceed 25ms (0.025).
152 .It Fl l Ar log_level
153 Specify the log level.
154 The default is 1.
155 All serious errors are logged at log level 0.
156 Major time corrections are logged at log level 1.
157 All time corrections and state changes are logged at log level 2.
158 Log levels 3 and 4 increase the amount of debugging information logged.
159 .It Fl T Ar nominal_poll
160 Set the nominal polling interval, in seconds.
161 This is the interval used while the client is in acquisition mode.
162 The default is 300 seconds (5 minutes).
163 .It Fl L Ar maximum_poll
164 Set the maximum polling interval, in seconds.
165 This is the interval used
166 while the client is in maintenance mode, after it believes it has
167 stabilized the system's clock.
168 The default is 1800 seconds (30 minutes).
169 .It targets
170 Specify targets in addition to the ones listed in the config file.
171 Note that certain options
172 .Fl ( d , t )
173 disable the config file, and you can specify a configuration file of
174 .Pa /dev/null
175 if you want to disable it otherwise.
176 .El
178 .Nm
179 runs two linear regressions for each target against the uncorrected system
180 time.
181 The two linear regressions are staggered so the second one is stable
182 and can replace the first one once the first's sampling limit has been
183 reached.
184 The second linear regression is also capable of overriding the first if
185 the target changes sufficiently to invalidate the first's correlation.
186 .Pp
187 The linear regression is a line-fitting algorithm which allows us to
188 calculate a running Y-intercept, slope, and correlation factor.
189 The
190 Y-intercept is currently not used but can be an indication of a shift in
191 the time source.
192 The slope basically gives us the drift rate which in
193 turn allows us to correct the frequency.
194 The correlation gives us a
195 quality indication, with 0 being the worst and \(+- 1.0 being the best.
196 .Pp
197 A standard deviation is calculated for offset corrections.
198 A standard
199 deviation gives us measure of the deviation from the mean of a set of
200 samples.
201 .Nm
202 uses the sum(offset_error) and sum(offset_error^2) method to calculate
203 a running standard deviation.
204 The offset error relative to the
205 frequency-corrected real time is calculated for each sample.
206 Note that
207 this differs from the uncorrected offset error that the linear regression
208 uses to calculate the frequency correction.
209 .Pp
210 In order to make a frequency correction a minimum of 8 samples and a
211 correlation \(>= 0.99, or 16 samples and a correlation \(>= 0.96 is required.
212 Once these requirements are met a frequency correction will typically be
213 made each sampling period.
214 Frequency corrections do not 'jump' the system
215 time or otherwise cause fine-time computations to be inaccurate and thus
216 can pretty much be made at will.
217 .Pp
218 In order to make an offset correction a minimum of 4 samples is required
219 and the standard deviation must be less than \(14 the current calculated
220 offset error.
221 The system typically applies offset corrections slowly over
222 time.
223 The algorithm will make an offset correction whenever these standards
224 are met but the fact that the offset error must be greater than 4 times the
225 standard deviation generally results in very few offset corrections being
226 made once time has been frequency-corrected.
227 .Nm
228 will not attempt to make a followup offset correction until the system
229 has completed applying the previous offset correction, as doing so would
230 cause a serious overshoot or undershoot.
231 It is possible to use a more
232 sophisticated algorithm to take running offset corrections into account
233 but we do not do that (yet).
234 .Pp
235 .Nm
236 maintains an operations mode for each target.
237 An initial 6 samples are taken
238 at 5 second intervals, after which samples are taken at 5 minute intervals.
239 If the time source is deemed to be good enough (using fairly relaxed
240 correlation and standard deviation comparisons) the polling interval is
241 increased to 30 minutes.
242 Note that long intervals are required to get good
243 correlations from internet time sources.
244 .Pp
245 If a target stops responding to NTP requests the operations mode goes into a
246 failed state which polls the target at the nominal polling rate
247 (e.g., 5 minutes).
248 Once re-acquired
249 .Nm
250 will either go back to the 5-second startup mode or to the 5-minute
251 acquisition mode depending on how long the target was in the failed state.
253 If the system clock is naturally off-frequency
254 .Nm
255 will be forced to make several offset corrections before it gets enough data
256 to make a frequency correction.
257 Once the frequency has been corrected
258 .Nm
259 can typically keep the time synchronized to within 1-20 milliseconds depending
260 on the source and both the number of offset corrections and the size of the
261 offset corrections should be significantly reduced.
262 .Pp
263 It will take up to 30 seconds for
264 .Nm
265 to make the initial coarse offset correction.
266 It can take anywhere from 5 minutes to 3 hours for
267 .Nm
268 to make the initial frequency correction, depending on the time source.
269 Internet time sources require long delays between samples to get a high
270 quality correlation in order to issue a frequency correction.
271 .Pp
272 It is difficult to calculate the packet latency for an internet time source
273 and in some cases this can result in time sources which disagree as much as
274 20ms with each other.
275 If you specify multiple targets and run in
276 debug or a high-logging mode you may observe this issue.
278 Multiple servers may be specified in the configuration file.
279 Pool domains
280 are supported and the same domain name may be specified several times to
281 connect to several different targets within the pool.
282 Your DNS server must rotate IPs for this to work properly (all
283 .Ux
284 name servers will rotate IPs).
285 .Nm
286 will automatically weed out any duplicate IPs.
287 .Pp
288 When two or more time sources are configured,
289 .Nm
290 will do a quorum-based sanity check on its best pick and fail the server if
291 its offset deviates significantly from other servers.
292 .Pp
293 If a server fails,
294 .Nm
295 will relookup its domain name and attempt to reconnect to it.
296 To avoid overloading servers due to packet routing snafus, reconnections
297 can take upwards of an hour to cycle.
299 The
300 .Pa /etc/dntpd.conf
301 file contains a list of servers in the 'server <servername>' format, one
302 per line.
303 Any information after a '#' is assumed to be a comment.
304 Any
305 number of servers may be specified but it is usually wasteful to have more
306 than four.
307 .Pp
308 The system will start dntpd at boot if you add the line:
309 .Bd -literal
310 dntpd_enable="YES"
311 .Ed
312 .Pp
313 to
314 .Pa /etc/rc.conf .
315 .Nm
316 will periodically re-resolve failed DNS queries and failed servers
317 and may be enabled at boot time even if the network is not yet
318 operational.
319 .Sh FILES
320 .Bl -tag -compact -width ".Pa /var/run/"
321 .It Pa /var/run/
322 When started as a daemon,
323 .Nm
324 stores its pid in this file.
325 When terminating a running
326 .Nm
327 this file is used to obtain the pid.
328 .Pp
329 .It Pa /etc/dntpd.conf
330 The default configuration file.
331 .El
333 The
334 .Nm
335 command first appeared in
336 .Dx 1.3 .
338 This program was written by
339 .An Matthew Dillon .
340 .Sh BUGS
341 An algorithm is needed to deal with time sources with packet-latency-based
342 offset errors.
343 .Pp
344 The offset correction needs to be able to operate while a prior offset
345 correction is still in-progress.
346 .Pp
347 We need to record the frequency correction in a file which is then read on
348 startup, to avoid having to recorrect the frequency from scratch every
349 time the system is rebooted.