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