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