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