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