ba7da032978ef50a1efe38f46de0f64f3efd49ac
[dragonfly.git] / usr.sbin / dntpd / dntpd.8
1 .\" $DragonFly: src/usr.sbin/dntpd/dntpd.8,v 1.11 2007/04/05 12:32:18 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
52 The
53 .Nm
54 daemon will synchronize the system clock to one or more external NTP time
55 sources.  By default an initial coarse offset correction will be made if
56 time is off by greater than 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
68 .Pa /etc/dntpd.conf
69 and run as a daemon (background itself).  If you re-execute
70 the binary it will automatically kill the currently running
71 .Nm
72 daemon.  If you run
73 .Nm
74 with the -Q option any currently running daemon will be killed and
75 no new daemon 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 coarse offset correction on startup.  Normally a coarse offset
94 correction is only made when the time differential is greater than 2
95 minutes.  This option will cause the initial offset correction to be
96 a coarse correction regardless.  Note that the system will still not make
97 a correction unless the offset error is greater than 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 1.  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 .El
142 .Sh IMPLEMENTATION NOTES
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 reached.
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 which 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 .Pp
158 A standard deviation is calculated for offset corrections.  A standard
159 deviation gives us measure of the deviation from the mean of a set of
160 samples.
161 .Nm
162 uses the sum(offset_error) and sum(offset_error^2) method to calculate
163 a running standard deviation.   The offset error relative to the
164 frequency-corrected real time is calculated for each sample.  Note that
165 this differs from the uncorrected offset error that the linear regression
166 uses to calculate the frequency correction.
167 .Pp
168 In order to make a frequency correction a minimum of 8 samples and a
169 correlation \(>= 0.99, or 16 samples and a correlation \(>= 0.96 is required.
170 Once these requirements are met a frequency correction will typically be
171 made each sampling period.  Frequency corrections do not 'jump' the system
172 time or otherwise cause fine-time computations to be inaccurate and thus
173 can pretty much be made at will.
174 .Pp
175 In order to make an offset correction a minimum of 4 samples is required
176 and the standard deviation must be less than \(14 the current calculated
177 offset error.  The system typically applies offset corrections slowly over
178 time.  The algorithm will make an offset correction whenever these standards
179 are met but the fact that the offset error must be greater than 4 times the
180 standard deviation generally results in very few offset corrections being
181 made once time has been frequency-corrected.
182 .Nm
183 will not attempt to make a followup offset correction until the system
184 has completed applying the previous offset correction, as doing so would
185 cause a serious overshoot or undershoot.  It is possible to use a more
186 sophisticated algorithm to take running offset corrections into account
187 but we do not do that (yet).
188 .Pp
189 .Nm
190 maintains an operations mode for each target.  An initial 6 samples are taken
191 at 5 second intervals, after which samples are taken at 5 minute intervals.
192 If the time source is deemed to be good enough (using fairly relaxed
193 correlation and standard deviation comparisons) the polling interval is
194 increased to 30 minutes.  Note that long intervals are required to get good
195 correlations from internet time sources.
196 .Pp
197 If a target stops responding to NTP requests the operations mode goes into a
198 failed state which polls the target at the nominal polling rate
199 (e.g. 5 minutes).  Once re-acquired
200 .Nm
201 will either go back to the 5-second startup mode or to the 5-minute
202 acquisition mode depending on how long the target was in the failed state.
203 .Sh TIME SYNCHRONIZATION ISSUES
204 If the system clock is naturally off-frequency
205 .Nm
206 will be forced to make several offset corrections before it gets enough data
207 to make a frequency correction.  Once the frequency has been corrected
208 .Nm
209 can typically keep the time synchronized to within 1-20 milliseconds depending
210 on the source and both the number of offset corrections and the size of the
211 offset corrections should be significantly reduced.
212 .Pp
213 It will take up to 30 seconds for
214 .Nm
215 to make the initial coarse offset correction.  It can take anywhere from
216 5 minutes to 3 hours for
217 .Nm
218 to make the initial frequency correction, depending on the time source.
219 Internet time sources require long delays between samples to get a high
220 quality correlation in order to issue a frequency correction.
221 .Pp
222 It is difficult to calculate the packet latency for an internet time source
223 and in some cases this can result in time sources which disagree as much as
224 20ms with each other.  If you specify multiple targets and run in
225 debug or a high-logging mode you may observe this issue.
226 .Sh CONFIGURATION FILE
227 The
228 .Pa /etc/dntpd.conf
229 file contains a list of servers in the 'server <servername>' format, one
230 per line.  Any information after a '#' is assumed to be a comment.  Any
231 number of servers may be specified but it is usually wasteful to have more
232 than four.
233 .Sh FILES
234 .Bl -tag -compact
235 .It Pa /var/run/dntpd.pid
236 When started as a daemon,
237 .Nm
238 stores its pid in this file.  When terminating a running
239 .Nm
240 this file is used to obtain the pid.
241 .Pp
242 .It Pa /etc/dntpd.conf
243 The default configuration file.
244 .El
245 .Sh AUTHORS
246 This program was written by Matthew Dillon.
247 .Sh BUGS
248 An algorithm is needed to deal with time sources with packet-latency-based
249 offset errors.
250 .Pp
251 The offset correction needs to be able to operate while a prior offset
252 correction is still in-progress.
253 .Pp
254 We need to record the frequency correction in a file which is then read on
255 startup, to avoid having to recorrect the frequency from scratch every
256 time the system is rebooted.