usr.sbin/dntpd/dntpd.8

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