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