usr.sbin/dntpd/dntpd.8

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