DNTPD(8) BSD System Manager's Manual DNTPD(8)NAMEdntpd — Network time protocol client daemon
SYNOPSISdntpd [-46dnqstFSQ] [-f config_file] [-i insane_deviation] [-l log_level]
[-T nominal_poll] [-L maximum_poll] [targets]
DESCRIPTION
The dntpd daemon will synchronize the system clock to one or more exter‐
nal NTP time sources. By default an initial coarse offset correction
will be made if time is off by greater than 2 minutes. Additional slid‐
ing offset corrections will be made if necessary. Once sufficient infor‐
mation is obtained, dntpd will also correct the clock frequency. Over
the long haul the frequency can usually be corrected to within 2 ppm of
the time source. Offset errors can typically be corrected to within 20
milliseconds, or within 1 millisecond of a low latency time source.
By default dntpd will load its configuration from /etc/dntpd.conf and run
as a daemon (background itself). If you re-execute the binary it will
automatically kill the currently running dntpd daemon. If you run dntpd
with the -Q option any currently running daemon will be killed and no new
daemon will be started.
The following command line options are available:
-4 Forces dntpd to use only IPv4 addresses.
-6 Forces dntpd to use only IPv6 addresses.
-d Run in debug mode. Implies -F, -l 99, and -f /dev/null and
logs to stderr instead of syslog. The normal client code is
run and time corrections will be made.
-n No-update mode. No actual update is made any time the client
would otherwise normally update the system frequency or off‐
set.
-q Quiet mode. Implies a logging level of 0.
-s Issue a coarse offset correction on startup. Normally a
coarse offset correction is only made when the time differen‐
tial is greater than 2 minutes. This option will cause the
initial offset correction to be a coarse correction regard‐
less. Note that the system will still not make a correction
unless the offset error is greater than 4 times the standard
deviation of the queries.
-t Test mode. Implies -F, -l 99, -n, and -f /dev/null and logs
to stderr instead of syslog. A single linear regression is
accumulated at the nominal polling rate and reported until
terminated. No time corrections are made. This option is
meant for testing only. Note that frequency corrections
based on internet time sources typically require a long
(10-30min) polling rate to be well correlated.
-F Run in the foreground. Unlike debug mode, this option will
still log to syslog.
-S Do not set the time immediately on startup (default).
-Q Terminate any running background daemon and exit.
-f config_file
Specify the configuration file. The default is
/etc/dntpd.conf.
-i insane_deviation
Specify how much deviation is allowed in calculated offsets,
in seconds. Fractions may be specified. A quorum of servers
must agree with the one we select as being the best time
source in order for us to select that source. The default
deviation allowed is a fairly expansive 0.5 seconds. Note
that offset errors due to internet packet latency can exceed
25ms (0.025).
-l log_level
Specify the log level. The default is 1. All serious errors
are logged at log level 0. Major time corrections are logged
at log level 1. All time corrections and state changes are
logged at log level 2. Log levels 3 and 4 increase the
amount of debugging information logged.
-T nominal_poll
Set the nominal polling interval, in seconds. This is the
interval used while the client is in acquisition mode. The
default is 300 seconds (5 minutes).
-L maximum_poll
Set the maximum polling interval, in seconds. This is the
interval used while the client is in maintenance mode, after
it believes it has stabilized the system's clock. The
default is 1800 seconds (30 minutes).
targets Specify targets in addition to the ones listed in the config
file. Note that certain options (-d, -t) disable the config
file, and you can specify a configuration file of /dev/null
if you want to disable it otherwise.
IMPLEMENTATION NOTESdntpd runs two linear regressions for each target against the uncorrected
system time. The two linear regressions are staggered so the second one
is stable and can replace the first one once the first's sampling limit
has been reached. The second linear regression is also capable of over‐
riding the first if the target changes sufficiently to invalidate the
first's correlation.
The linear regression is a line-fitting algorithm which allows us to cal‐
culate a running Y-intercept, slope, and correlation factor. The Y-
intercept is currently not used but can be an indication of a shift in
the time source. The slope basically gives us the drift rate which in
turn allows us to correct the frequency. The correlation gives us a
quality indication, with 0 being the worst and ± 1.0 being the best.
A standard deviation is calculated for offset corrections. A standard
deviation gives us measure of the deviation from the mean of a set of
samples. dntpd uses the sum(offset_error) and sum(offset_error^2) method
to calculate a running standard deviation. The offset error relative to
the frequency-corrected real time is calculated for each sample. Note
that this differs from the uncorrected offset error that the linear
regression uses to calculate the frequency correction.
In order to make a frequency correction a minimum of 8 samples and a cor‐
relation ≥ 0.99, or 16 samples and a correlation ≥ 0.96 is required.
Once these requirements are met a frequency correction will typically be
made each sampling period. Frequency corrections do not 'jump' the sys‐
tem time or otherwise cause fine-time computations to be inaccurate and
thus can pretty much be made at will.
In order to make an offset correction a minimum of 4 samples is required
and the standard deviation must be less than ¼ the current calculated
offset error. The system typically applies offset corrections slowly
over time. The algorithm will make an offset correction whenever these
standards are met but the fact that the offset error must be greater than
4 times the standard deviation generally results in very few offset cor‐
rections being made once time has been frequency-corrected. dntpd will
not attempt to make a followup offset correction until the system has
completed applying the previous offset correction, as doing so would
cause a serious overshoot or undershoot. It is possible to use a more
sophisticated algorithm to take running offset corrections into account
but we do not do that (yet).
dntpd maintains an operations mode for each target. An initial 6 samples
are taken at 5 second intervals, after which samples are taken at 5
minute intervals. If the time source is deemed to be good enough (using
fairly relaxed correlation and standard deviation comparisons) the
polling interval is increased to 30 minutes. Note that long intervals
are required to get good correlations from internet time sources.
If a target stops responding to NTP requests the operations mode goes
into a failed state which polls the target at the nominal polling rate
(e.g., 5 minutes). Once re-acquired dntpd will either go back to the
5-second startup mode or to the 5-minute acquisition mode depending on
how long the target was in the failed state.
TIME SYNCHRONIZATION ISSUES
If the system clock is naturally off-frequency dntpd will be forced to
make several offset corrections before it gets enough data to make a fre‐
quency correction. Once the frequency has been corrected dntpd can typi‐
cally keep the time synchronized to within 1-20 milliseconds depending on
the source and both the number of offset corrections and the size of the
offset corrections should be significantly reduced.
It will take up to 30 seconds for dntpd to make the initial coarse offset
correction. It can take anywhere from 5 minutes to 3 hours for dntpd to
make the initial frequency correction, depending on the time source.
Internet time sources require long delays between samples to get a high
quality correlation in order to issue a frequency correction.
It is difficult to calculate the packet latency for an internet time
source and in some cases this can result in time sources which disagree
as much as 20ms with each other. If you specify multiple targets and run
in debug or a high-logging mode you may observe this issue.
MULTIPLE SERVERS AND DNS ROUND ROBINS
Multiple servers may be specified in the configuration file. Pool
domains are supported and the same domain name may be specified several
times to connect to several different targets within the pool. Your DNS
server must rotate IPs for this to work properly (all UNIX name servers
will rotate IPs). dntpd will automatically weed out any duplicate IPs.
When two or more time sources are configured, dntpd will do a quorum-
based sanity check on its best pick and fail the server if its offset
deviates significantly from other servers.
If a server fails, dntpd will relookup its domain name and attempt to
reconnect to it. To avoid overloading servers due to packet routing sna‐
fus, reconnections can take upwards of an hour to cycle.
CONFIGURATION FILE
The /etc/dntpd.conf file contains a list of servers in the 'server
<servername>' format, one per line. Any information after a '#' is
assumed to be a comment. Any number of servers may be specified but it
is usually wasteful to have more than four.
The system will start dntpd at boot if you add the line:
dntpd_enable="YES"
to /etc/rc.conf. dntpd will periodically re-resolve failed DNS queries
and failed servers and may be enabled at boot time even if the network is
not yet operational.
FILES
/var/run/dntpd.pid When started as a daemon, dntpd stores
its pid in this file. When terminating
a running dntpd this file is used to
obtain the pid.
/etc/dntpd.conf The default configuration file.
HISTORY
The dntpd command first appeared in DragonFly 1.3.
AUTHORS
This program was written by Matthew Dillon.
BUGS
An algorithm is needed to deal with time sources with packet-latency-
based offset errors.
The offset correction needs to be able to operate while a prior offset
correction is still in-progress.
We need to record the frequency correction in a file which is then read
on startup, to avoid having to recorrect the frequency from scratch every
time the system is rebooted.
BSD January 6, 2009 BSD
