usr.sbin/dntpd/dntpd.8

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