--- src/usr.sbin/dntpd/dntpd.8 2008/01/19 19:11:53 1.17 +++ src/usr.sbin/dntpd/dntpd.8 2008/01/19 19:41:33 1.18 @@ -53,13 +53,16 @@ The .Nm daemon will synchronize the system clock to one or more external NTP time -sources. By default an initial coarse offset correction will be made if -time is off by greater than 2 minutes. Additional sliding offset -corrections will be made if necessary. Once sufficient information is -obtained, -.Nm -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 +sources. +By default an initial coarse offset correction will be made if +time is off by greater than 2 minutes. +Additional sliding offset corrections will be made if necessary. +Once sufficient information is obtained, +.Nm +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. .Pp @@ -67,10 +70,11 @@ By default .Nm will load its configuration from .Pa /etc/dntpd.conf -and run as a daemon (background itself). If you re-execute -the binary it will automatically kill the currently running +and run as a daemon (background itself). +If you re-execute the binary it will automatically kill the currently running .Nm -daemon. If you run +daemon. +If you run .Nm with the -Q option any currently running daemon will be killed and no new daemon will be started. @@ -78,46 +82,56 @@ no new daemon will be started. The following command line options are available: .Bl -tag -width Fl .It Fl d -Run in debug mode. Implies +Run in debug mode. +Implies .Fl F , .Fl l Ar 99 , and .Fl f Ar /dev/null -and logs to stderr instead of syslog. The normal client code is run and -time corrections will be made. +and logs to stderr instead of syslog. +The normal client code is run and time corrections will be made. .It Fl n -No-update mode. No actual update is made any time the client would +No-update mode. +No actual update is made any time the client would otherwise normally update the system frequency or offset. .It Fl q -Quiet mode. Implies a logging level of 0. +Quiet mode. +Implies a logging level of 0. .It Fl s -Issue a coarse offset correction on startup. Normally a coarse offset +Issue a coarse offset correction on startup. +Normally a coarse offset correction is only made when the time differential is greater than 2 -minutes. This option will cause the initial offset correction to be -a coarse correction regardless. Note that the system will still not make +minutes. +This option will cause the initial offset correction to be +a coarse correction regardless. +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. .It Fl t -Test mode. Implies +Test mode. +Implies .Fl F , .Fl l Ar 99 , .Fl n , and .Fl f Ar /dev/null -and logs to stderr instead of syslog. A single linear regression is +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. +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. .It Fl F -Run in the foreground. Unlike debug mode, this option will still log -to syslog. +Run in the foreground. +Unlike debug mode, this option will still log to syslog. .It Fl S Do not set the time immediately on startup (default). .It Fl Q Terminate any running background daemon and exit. .It Fl f Ar config_file -Specify the configuration file. The default is +Specify the configuration file. +The default is .Pa /etc/dntpd.conf . .It Fl i Ar insane_deviation Specify how much deviation is allowed in calculated offsets, in seconds. @@ -128,84 +142,102 @@ The default deviation allowed is a fairl Note that offset errors due to internet packet latency can exceed 25ms (0.025). .It Fl l Ar 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 level's -3 and 4 increase the amount of debugging information logged. +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. .It Fl T Ar nominal_poll -Set the nominal polling interval, in seconds. This is the interval used -while the client is in acquisition mode. +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). .It Fl L Ar maximum_poll -Set the maximum polling interval, in seconds. This is the interval used +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). .It 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 +Specify targets in addition to the ones listed in the config file. +Note that certain options +.Fl ( d , t ) +disable the config file, and you can specify a configuration file of .Pa /dev/null if you want to disable it otherwise. .El .Sh IMPLEMENTATION NOTES .Nm runs two linear regressions for each target against the uncorrected system -time. The two linear regressions are staggered so the second one is stable +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 overriding the first if the target changes sufficiently to invalidate the first's correlation. .Pp The linear regression is a line-fitting algorithm which allows us to -calculate a running Y-intercept, slope, and correlation factor. The +calculate 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 +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. .Pp -A standard deviation is calculated for offset corrections. A standard +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. .Nm 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 +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. .Pp In order to make a frequency correction a minimum of 8 samples and a correlation \(>= 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 system +made each sampling period. +Frequency corrections do not 'jump' the system time or otherwise cause fine-time computations to be inaccurate and thus can pretty much be made at will. .Pp In order to make an offset correction a minimum of 4 samples is required and the standard deviation must be less than \(14 the current calculated -offset error. The system typically applies offset corrections slowly over -time. The algorithm will make an offset correction whenever these standards +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 corrections being made once time has been frequency-corrected. .Nm 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 +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). .Pp .Nm -maintains an operations mode for each target. An initial 6 samples are taken +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 +increased to 30 minutes. +Note that long intervals are required to get good correlations from internet time sources. .Pp 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 +(e.g., 5 minutes). +Once re-acquired .Nm 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. @@ -213,7 +245,8 @@ acquisition mode depending on how long t If the system clock is naturally off-frequency .Nm will be forced to make several offset corrections before it gets enough data -to make a frequency correction. Once the frequency has been corrected +to make a frequency correction. +Once the frequency has been corrected .Nm can typically 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 @@ -221,8 +254,8 @@ offset corrections should be significant .Pp It will take up to 30 seconds for .Nm -to make the initial coarse offset correction. It can take anywhere from -5 minutes to 3 hours for +to make the initial coarse offset correction. +It can take anywhere from 5 minutes to 3 hours for .Nm to make the initial frequency correction, depending on the time source. Internet time sources require long delays between samples to get a high @@ -230,13 +263,15 @@ quality correlation in order to issue a .Pp 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 +20ms with each other. +If you specify multiple targets and run in debug or a high-logging mode you may observe this issue. .Sh MULTIPLE SERVERS AND DNS ROUND ROBINS -Multiple servers may be specified in the configuration file. Pool domains +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 +connect to several different targets within the pool. +Your DNS server must rotate IPs for this to work properly (all .Ux name servers will rotate IPs). .Nm @@ -256,7 +291,9 @@ can take upwards of an hour to cycle. The .Pa /etc/dntpd.conf file contains a list of servers in the 'server ' format, one -per line. Any information after a '#' is assumed to be a comment. Any +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. .Pp @@ -276,7 +313,8 @@ operational. .It Pa /var/run/dntpd.pid When started as a daemon, .Nm -stores its pid in this file. When terminating a running +stores its pid in this file. +When terminating a running .Nm this file is used to obtain the pid. .Pp @@ -289,7 +327,8 @@ The command first appeared in .Dx 1.3 . .Sh AUTHORS -This program was written by Matthew Dillon. +This program was written by +.An Matthew Dillon . .Sh BUGS An algorithm is needed to deal with time sources with packet-latency-based offset errors.