Commit | Line | Data |
---|---|---|
f0da3a1c | 1 | .\" $DragonFly: src/usr.sbin/dntpd/dntpd.8,v 1.19 2008/01/22 19:17:38 swildner Exp $ |
1bf4b486 | 2 | .\" |
d399b893 | 3 | .\" Copyright (c) 2005 The DragonFly Project. All rights reserved. |
1bf4b486 | 4 | .\" |
d399b893 MD |
5 | .\" This code is derived from software contributed to The DragonFly Project |
6 | .\" by Matthew Dillon <dillon@backplane.com> | |
1bf4b486 | 7 | .\" |
d399b893 MD |
8 | .\" Redistribution and use in source and binary forms, with or without |
9 | .\" modification, are permitted provided that the following conditions | |
10 | .\" are met: | |
1bf4b486 | 11 | .\" |
d399b893 MD |
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. | |
1bf4b486 | 21 | .\" |
d399b893 MD |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
23 | .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
24 | .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS | |
25 | .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE | |
26 | .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, | |
27 | .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, | |
28 | .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
29 | .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED | |
30 | .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
31 | .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
32 | .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
1bf4b486 | 34 | .\" |
4d1d74ba | 35 | .Dd January 6, 2009 |
d399b893 MD |
36 | .Dt DNTPD 8 |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm dntpd | |
40 | .Nd Network time protocol client daemon | |
41 | .Sh SYNOPSIS | |
42 | .Nm | |
43 | .Bk -words | |
4d1d74ba | 44 | .Op Fl 46dnqstFSQ |
d399b893 | 45 | .Op Fl f Ar config_file |
5e13edd7 | 46 | .Op Fl i Ar insane_deviation |
d399b893 MD |
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 | |
52 | .Sh DESCRIPTION | |
53 | The | |
54 | .Nm | |
55 | daemon will synchronize the system clock to one or more external NTP time | |
391a1e02 SW |
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, | |
d399b893 | 61 | .Nm |
391a1e02 SW |
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 | |
d399b893 MD |
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 | |
89ef1ab5 | 71 | will load its configuration from |
d399b893 | 72 | .Pa /etc/dntpd.conf |
391a1e02 SW |
73 | and run as a daemon (background itself). |
74 | If you re-execute the binary it will automatically kill the currently running | |
d399b893 | 75 | .Nm |
391a1e02 SW |
76 | daemon. |
77 | If you run | |
d399b893 | 78 | .Nm |
89ef1ab5 MD |
79 | with the -Q option any currently running daemon will be killed and |
80 | no new daemon will be started. | |
d399b893 MD |
81 | .Pp |
82 | The following command line options are available: | |
83 | .Bl -tag -width Fl | |
4d1d74ba MS |
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. | |
d399b893 | 92 | .It Fl d |
391a1e02 SW |
93 | Run in debug mode. |
94 | Implies | |
d399b893 MD |
95 | .Fl F , |
96 | .Fl l Ar 99 , | |
97 | and | |
98 | .Fl f Ar /dev/null | |
391a1e02 SW |
99 | and logs to stderr instead of syslog. |
100 | The normal client code is run and time corrections will be made. | |
d399b893 | 101 | .It Fl n |
391a1e02 SW |
102 | No-update mode. |
103 | No actual update is made any time the client would | |
d399b893 MD |
104 | otherwise normally update the system frequency or offset. |
105 | .It Fl q | |
391a1e02 SW |
106 | Quiet mode. |
107 | Implies a logging level of 0. | |
d399b893 | 108 | .It Fl s |
391a1e02 SW |
109 | Issue a coarse offset correction on startup. |
110 | Normally a coarse offset | |
14d0924e | 111 | correction is only made when the time differential is greater than 2 |
391a1e02 SW |
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 | |
14d0924e | 116 | a correction unless the offset error is greater than 4 times the standard |
d399b893 MD |
117 | deviation of the queries. |
118 | .It Fl t | |
391a1e02 SW |
119 | Test mode. |
120 | Implies | |
d399b893 MD |
121 | .Fl F , |
122 | .Fl l Ar 99 , | |
123 | .Fl n , | |
124 | and | |
125 | .Fl f Ar /dev/null | |
391a1e02 SW |
126 | and logs to stderr instead of syslog. |
127 | A single linear regression is | |
d399b893 | 128 | accumulated at the nominal polling rate and reported until terminated. |
391a1e02 SW |
129 | No time corrections are made. |
130 | This option is meant for testing only. | |
d399b893 | 131 | Note that frequency corrections based on internet time sources typically |
3f5e28f4 | 132 | require a long (10-30min) polling rate to be well correlated. |
d399b893 | 133 | .It Fl F |
391a1e02 SW |
134 | Run in the foreground. |
135 | Unlike debug mode, this option will still log to syslog. | |
d399b893 MD |
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 | |
391a1e02 SW |
141 | Specify the configuration file. |
142 | The default is | |
d399b893 | 143 | .Pa /etc/dntpd.conf . |
5e13edd7 MD |
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). | |
d399b893 | 152 | .It Fl l Ar log_level |
391a1e02 SW |
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. | |
d399b893 | 159 | .It Fl T Ar nominal_poll |
391a1e02 SW |
160 | Set the nominal polling interval, in seconds. |
161 | This is the interval used while the client is in acquisition mode. | |
3f5e28f4 | 162 | The default is 300 seconds (5 minutes). |
d399b893 | 163 | .It Fl L Ar maximum_poll |
391a1e02 SW |
164 | Set the maximum polling interval, in seconds. |
165 | This is the interval used | |
3f5e28f4 | 166 | while the client is in maintenance mode, after it believes it has |
d399b893 MD |
167 | stabilized the system's clock. |
168 | The default is 1800 seconds (30 minutes). | |
169 | .It targets | |
391a1e02 SW |
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 | |
d399b893 MD |
174 | .Pa /dev/null |
175 | if you want to disable it otherwise. | |
14d0924e | 176 | .El |
c2111090 | 177 | .Sh IMPLEMENTATION NOTES |
d399b893 MD |
178 | .Nm |
179 | runs two linear regressions for each target against the uncorrected system | |
391a1e02 SW |
180 | time. |
181 | The two linear regressions are staggered so the second one is stable | |
d399b893 | 182 | and can replace the first one once the first's sampling limit has been |
9ebb2edd | 183 | reached. |
d399b893 | 184 | The second linear regression is also capable of overriding the first if |
1bf4b486 | 185 | the target changes sufficiently to invalidate the first's correlation. |
d399b893 | 186 | .Pp |
1bf4b486 | 187 | The linear regression is a line-fitting algorithm which allows us to |
391a1e02 SW |
188 | calculate a running Y-intercept, slope, and correlation factor. |
189 | The | |
d399b893 | 190 | Y-intercept is currently not used but can be an indication of a shift in |
391a1e02 SW |
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 | |
aa0d550a | 195 | quality indication, with 0 being the worst and \(+- 1.0 being the best. |
d399b893 | 196 | .Pp |
391a1e02 SW |
197 | A standard deviation is calculated for offset corrections. |
198 | A standard | |
1bf4b486 | 199 | deviation gives us measure of the deviation from the mean of a set of |
d399b893 MD |
200 | samples. |
201 | .Nm | |
202 | uses the sum(offset_error) and sum(offset_error^2) method to calculate | |
f0da3a1c | 203 | a running standard deviation. |
391a1e02 SW |
204 | The offset error relative to the |
205 | frequency-corrected real time is calculated for each sample. | |
206 | Note that | |
9ebb2edd MD |
207 | this differs from the uncorrected offset error that the linear regression |
208 | uses to calculate the frequency correction. | |
d399b893 | 209 | .Pp |
9ebb2edd | 210 | In order to make a frequency correction a minimum of 8 samples and a |
aa0d550a | 211 | correlation \(>= 0.99, or 16 samples and a correlation \(>= 0.96 is required. |
9ebb2edd | 212 | Once these requirements are met a frequency correction will typically be |
391a1e02 SW |
213 | made each sampling period. |
214 | Frequency corrections do not 'jump' the system | |
9ebb2edd MD |
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 | |
aa0d550a | 219 | and the standard deviation must be less than \(14 the current calculated |
391a1e02 SW |
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 | |
14d0924e | 224 | are met but the fact that the offset error must be greater than 4 times the |
9ebb2edd MD |
225 | standard deviation generally results in very few offset corrections being |
226 | made once time has been frequency-corrected. | |
d399b893 MD |
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 | |
391a1e02 SW |
230 | cause a serious overshoot or undershoot. |
231 | It is possible to use a more | |
9ebb2edd MD |
232 | sophisticated algorithm to take running offset corrections into account |
233 | but we do not do that (yet). | |
d399b893 MD |
234 | .Pp |
235 | .Nm | |
391a1e02 SW |
236 | maintains an operations mode for each target. |
237 | An initial 6 samples are taken | |
d399b893 | 238 | at 5 second intervals, after which samples are taken at 5 minute intervals. |
9ebb2edd MD |
239 | If the time source is deemed to be good enough (using fairly relaxed |
240 | correlation and standard deviation comparisons) the polling interval is | |
391a1e02 SW |
241 | increased to 30 minutes. |
242 | Note that long intervals are required to get good | |
d399b893 MD |
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 | |
391a1e02 SW |
247 | (e.g., 5 minutes). |
248 | Once re-acquired | |
d399b893 MD |
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. | |
d399b893 MD |
252 | .Sh TIME SYNCHRONIZATION ISSUES |
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 | |
391a1e02 SW |
256 | to make a frequency correction. |
257 | Once the frequency has been corrected | |
d399b893 MD |
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 | |
9ebb2edd | 263 | It will take up to 30 seconds for |
d399b893 | 264 | .Nm |
391a1e02 SW |
265 | to make the initial coarse offset correction. |
266 | It can take anywhere from 5 minutes to 3 hours for | |
d399b893 | 267 | .Nm |
1bf4b486 | 268 | to make the initial frequency correction, depending on the time source. |
d399b893 MD |
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 | |
391a1e02 SW |
274 | 20ms with each other. |
275 | If you specify multiple targets and run in | |
9ebb2edd | 276 | debug or a high-logging mode you may observe this issue. |
5e13edd7 | 277 | .Sh MULTIPLE SERVERS AND DNS ROUND ROBINS |
391a1e02 SW |
278 | Multiple servers may be specified in the configuration file. |
279 | Pool domains | |
5e13edd7 | 280 | are supported and the same domain name may be specified several times to |
391a1e02 SW |
281 | connect to several different targets within the pool. |
282 | Your DNS server must rotate IPs for this to work properly (all | |
5e13edd7 MD |
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. | |
d399b893 MD |
298 | .Sh CONFIGURATION FILE |
299 | The | |
300 | .Pa /etc/dntpd.conf | |
301 | file contains a list of servers in the 'server <servername>' format, one | |
391a1e02 SW |
302 | per line. |
303 | Any information after a '#' is assumed to be a comment. | |
304 | Any | |
d399b893 | 305 | number of servers may be specified but it is usually wasteful to have more |
14d0924e | 306 | than four. |
7838b655 MD |
307 | .Pp |
308 | The system will start dntpd at boot if you add the line: | |
63568417 SW |
309 | .Bd -literal |
310 | dntpd_enable="YES" | |
311 | .Ed | |
312 | .Pp | |
313 | to | |
7838b655 MD |
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. | |
d399b893 | 319 | .Sh FILES |
5a394c59 | 320 | .Bl -tag -compact -width ".Pa /var/run/dntpd.pid" |
d399b893 MD |
321 | .It Pa /var/run/dntpd.pid |
322 | When started as a daemon, | |
323 | .Nm | |
391a1e02 SW |
324 | stores its pid in this file. |
325 | When terminating a running | |
d399b893 MD |
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 | |
34d9e328 SW |
332 | .Sh HISTORY |
333 | The | |
334 | .Nm | |
335 | command first appeared in | |
336 | .Dx 1.3 . | |
d399b893 | 337 | .Sh AUTHORS |
391a1e02 SW |
338 | This program was written by |
339 | .An Matthew Dillon . | |
49781055 SW |
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. |