diff options
Diffstat (limited to 'html')
| -rw-r--r-- | html/accopt.html | 9 | ||||
| -rw-r--r-- | html/clockopt.html | 18 | ||||
| -rw-r--r-- | html/confopt.html | 31 | ||||
| -rw-r--r-- | html/copyright.html | 5 | ||||
| -rw-r--r-- | html/discipline.html | 37 | ||||
| -rw-r--r-- | html/drivers/driver20.html | 204 | ||||
| -rw-r--r-- | html/drivers/driver29.html | 78 | ||||
| -rw-r--r-- | html/miscopt.html | 33 |
8 files changed, 317 insertions, 98 deletions
diff --git a/html/accopt.html b/html/accopt.html index 4417a8cca20c..4c4ae2f7c5c9 100644 --- a/html/accopt.html +++ b/html/accopt.html @@ -55,8 +55,10 @@ the <a href="accopt.html">Access Control Support</a> page.</p> </dl> </dd> <dt id="restrict"><tt>restrict [-4 | -6] default [ippeerlimit <i>num</i>] - [<i>flag</i>][...]<br> restrict source [ippeerlimit <i>num</i>] - [<i>flag</i>][...]<br> restrict <i>address</i> [mask <i>mask</i>] + [<i>flag</i>][...]</tt></dt> + <dt><tt>restrict source [ippeerlimit <i>num</i>] + [<i>flag</i>][...]</tt></dt> + <dt><tt>restrict <i>address</i> [mask <i>mask</i>] [ippeerlimit <i>num</i>] [<i>flag</i>][...]</tt></dt> <dd>The <tt><i>address</i></tt> argument expressed in IPv4 or IPv6 numeric address form is the address of a host or network. Alternatively, @@ -168,6 +170,9 @@ the <a href="accopt.html">Access Control Support</a> page.</p> UDP port (123). A restrict line containing <tt>ntpport</tt> is considered more specific than one with the same address and mask, but lacking <tt>ntpport</tt>.</dd> + <dt><tt>serverresponse fuzz</tt></dt> + <dd>When reponding to server requests, fuzz the low order bits of + the <tt>reftime</tt>.</dd> <dt><tt>version</tt></dt> <dd>Deny packets that do not match the current NTP version.</dd> </dl> diff --git a/html/clockopt.html b/html/clockopt.html index 0fe4c246776b..2c2d0a8fdfe9 100644 --- a/html/clockopt.html +++ b/html/clockopt.html @@ -10,7 +10,7 @@ <h3>Reference Clock Commands and Options</h3> <img src="pic/stack1a.jpg" alt="gif" align="left">Master Time Facility at the <a href="http://www.eecis.udel.edu/%7emills/lab.html">UDel Internet Research Laboratory</a> <p>Last update: - <!-- #BeginDate format:En2m -->11-Sep-2010 05:55<!-- #EndDate --> + <!-- #BeginDate format:En2m -->26-Sep-2019 06:34<!-- #EndDate --> UTC</p> <br clear="left"> <h4>Related Links</h4> @@ -50,6 +50,22 @@ <dd>Specifies an ASCII string of from one to four characters which defines the reference identifier used by the driver. This string overrides the default identifier ordinarily assigned by the driver itself.</dd> <dt><tt>flag1 flag2 flag3 flag4</tt></dt> <dd>These four flags are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the particular driver. However, by convention <tt>flag4</tt> is used to enable recording monitoring data to the <tt>clockstats</tt> file configured with the <tt>filegen</tt> command. Additional information on the <tt>filegen</tt> command is on the <a href="monopt.html">Monitoring Options</a> page.</dd> + <dt><tt>minjitter <i>secs</i></tt></dt> + <dd>If the source has a jitter that cannot be sensibly estimated, because + it is not statistic jitter, the source will be detected as falseticker + sooner or later. This has been observed e.g. with the serial data of + certain GPS receivers. Enforcing a minimal jitter value avoids a too + low estimation, keeping the clock in the zoo while still detecting + higher jitter. + </dd><dd> Note: this changes the refclock samples and ends up in the + clock dispersion, not the clock jitter, despite being called jitter. To + see the modified values, check the NTP clock variable "filtdisp", not + "jitter". + </dd><dd>The falseticker problem can also be avoided by increasing <tt>tos + mindist</tt>, which extends the intersection interval, but that affects + the root dispersion and is intended for the case of multiple reference + clocks with reliable jitter that do not intersect otherwise. + </dd> </dl> </dd> </dl> diff --git a/html/confopt.html b/html/confopt.html index f214f0f1f07c..a8c06a83da20 100644 --- a/html/confopt.html +++ b/html/confopt.html @@ -13,7 +13,7 @@ Walt Kelly</a> <p>The chicken is getting configuration advice.</p> <p>Last update: - <!-- #BeginDate format:En2m -->24-Jul-2018 07:27<!-- #EndDate --> + <!-- #BeginDate format:En2m -->13-Feb-2020 10:08<!-- #EndDate --> UTC</p> <br clear="left"> <h4>Related Links</h4> @@ -33,12 +33,12 @@ Walt Kelly</a> support for the IPv6 address family is generated in addition to the default IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses can be used, with the exception of reference clock addresses, which are always IPv4. Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p> <h4 id="command">Server Commands</h4> <p>Unless noted otherwise, further information about these commands is on the <a href="assoc.html">Association Management</a> page.</p><dl> - <dt id="server"><tt>server <i>address</i> [options ...]</tt><br> - <tt>peer <i>address</i> [options ...]</tt><br> - <tt>broadcast <i>address</i> [options ...]</tt><br> - <tt>manycastclient <i>address</i> [options ...]</tt><br> - <tt>pool <i>address</i> [options ...]</tt><br> - <tt>unpeer [<i>address</i> | <i>associd</i>]</tt></dt> + <dt id="server"><tt>server <i>address</i> [options ...]</tt></dt> + <dt><tt>peer <i>address</i> [options ...]</tt></dt> + <dt><tt>broadcast <i>address</i> [options ...]</tt></dt> + <dt><tt>manycastclient <i>address</i> [options ...]</tt></dt> + <dt><tt>pool <i>address</i> [options ...]</tt></dt> + <dt><tt>unpeer [<i>address</i> | <i>associd</i>]</tt></dt> <dd>These commands specify the remote server name or address to be used and the mode in which to operate. The <i>address</i> can be either a DNS name or a IPv4 or IPv6 address in standard notation. In general, multiple commands of each type can be used for different server and peer addresses or multicast groups. <dl> <dt><tt>server</tt></dt> @@ -67,8 +67,14 @@ Walt Kelly</a> <dt><tt>ident</tt> <em><tt>group</tt></em></dt> <dd>Specify the group name for the association. See the <a href="autokey.html">Autokey Public-Key Authentication</a> page for further information.</dd> <dt><tt>key</tt> <i><tt>key</tt></i></dt> - <dd>Send and receive packets authenticated by the symmetric key scheme described in the <a href="authentic.html">Authentication Support</a> page. The <i><tt>key</tt></i> specifies the key identifier with values from 1 to 65535, inclusive. This option is mutually exclusive with the <tt>autokey</tt> option.</dd> <dt><tt>minpoll <i>minpoll<br> - </i></tt><tt>maxpoll <i>maxpoll</i></tt></dt> + <dd>Send and receive packets authenticated by the symmetric key scheme + described in the <a href="authentic.html">Authentication Support</a> + page. The <i><tt>key</tt></i> specifies the key identifier with values + from 1 to 65535, inclusive. This option is mutually exclusive with + the <tt>autokey</tt> + option.</dd> + <dt><tt>minpoll <i>minpoll</i></tt></dt> + <dt><tt>maxpoll <i>maxpoll</i></tt></dt> <dd>These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a power of two. The maximum poll interval defaults to 10 (1024 s), but can be increased by the <tt>maxpoll</tt> option to an upper limit of 17 (36 hr). The minimum poll interval defaults to 6 (64 s), but can be decreased by the <tt>minpoll</tt> option to a lower limit of 3 (8 s). Additional information about this option is on the <a href="poll.html">Poll Program</a> page.</dd> <dt><tt>mode <i>option</i></tt></dt> <dd>Pass the <tt><i>option</i></tt> to a reference clock driver, where <tt><i>option</i></tt> is an integer in the range from 0 to 255, inclusive. This option is valid only with type r addresses.</dd> @@ -87,6 +93,13 @@ Walt Kelly</a> outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default.</dd> <dt><tt>xleave</tt></dt> <dd>Operate in interleaved mode (symmetric and broadcast modes only). Further information is on the <a href="xleave.html">NTP Interleaved Modes</a> page.</dd> + <dt><tt>xmtnonce</tt></dt> + <dd>Allowed in the server and pool modes, this flag causes the + client to put a random number nonce in the transmit timestamp of + its outgoing packet. Since the server will reply copying the + incoming transmit timestamp to the outgoing origin timestamp, this + flag provides extra security for the loopback test, at the expense + of the server having no idea what time the client thinks it is.</dd> </dl> <h4 id="aux">Auxiliary Commands</h4> <dl> diff --git a/html/copyright.html b/html/copyright.html index 518435cf768b..93604b7d0368 100644 --- a/html/copyright.html +++ b/html/copyright.html @@ -3,14 +3,13 @@ <head> <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> <title>Copyright Notice</title> -<!-- Changed by: Harlan Stenn, 10-Mar-2014 --> <link href="scripts/style.css" type="text/css" rel="stylesheet"> </head> <body> <h3>Copyright Notice</h3> <img src="pic/sheepb.jpg" alt="jpg" align="left"> "Clone me," says Dolly sheepishly. <p>Last update: - <!-- #BeginDate format:En2m -->2-Jan-2017 11:58<!-- #EndDate --> + <!-- #BeginDate format:En2m -->4-Feb-2020 23:47<!-- #EndDate --> UTC</p> <br clear="left"> </p> @@ -39,7 +38,7 @@ <pre> *********************************************************************** * * -* Copyright (c) Network Time Foundation 2011-2017 * +* Copyright (c) Network Time Foundation 2011-2020 * * * * All Rights Reserved * * * diff --git a/html/discipline.html b/html/discipline.html index 53b60ccf8535..ae8fffcbbf83 100644 --- a/html/discipline.html +++ b/html/discipline.html @@ -4,12 +4,13 @@ <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> <meta name="generator" content="HTML Tidy, see www.w3.org"> <title>Clock Discipline Algorithm</title> +<!-- Changed by: stenn, 03-Jan-2020 --> <link href="scripts/style.css" type="text/css" rel="stylesheet"> </head> <body> <h3>Clock Discipline Algorithm</h3> <p>Last update: - <!-- #BeginDate format:En2m -->10-Mar-2014 05:03<!-- #EndDate --> + <!-- #BeginDate format:En2m -->3-Jan-2020 02:12<!-- #EndDate --> UTC</p> <h4>Table of Contents</h4> <ul> @@ -20,29 +21,29 @@ </ul> <hr> <h4 id="intro">General Overview</h4> -<p>At the heart of the NTP specification and reference implementation is the clock discipline algorithm, which is best described as an adaptive parameter, hybrid phase/frequency-lock feedback loop. It is an intricately crafted algorithm that automatically adapts for optimum performance while minimizing network overhead. Operation is in two modes, phase-lock loop (PLL), which is used at poll intervals below the Allan intercept, by default 2048 s, and frequency-lock loop (FLL), which is used above that.</p> +<p>At the heart of the NTP specification and reference implementation is the clock discipline algorithm, which is best described as an adaptive parameter, hybrid phase/frequency-lock feedback loop. It is an intricately crafted algorithm that automatically adapts for optimum performance while minimizing network overhead. Operation is in two modes, phase-lock loop (PLL), which is used at poll intervals below the Allan intercept, by default 2048 s, and frequency-lock loop (FLL), which is used above that.</p> <div align="center"> <img src="pic/discipline.gif" alt="gif"> <p>Figure 1. Clock Discipline Algorithm</p> </div> <h4 id="pll">Clock Discipline Operations</h4> -<p>A block diagram of the clock discipline is shown in Figure 1. The timestamp of a reference clock or remote server is compared with the timestamp of the system clock, represented as a variable frequency oscillator (VFO), to produce a raw offset sample <em>V<sub>d</sub></em>. Offset samples are processed by the clock filter to produce a filtered update <em>V<sub>s</sub></em>. The loop filter implements a type-2 proportional-integrator controller (PIC). The PIC can minimize errors in both time and frequency using predictors <em>x</em> and <em>y</em>, respectively. The clock adjust process samples these predictors once each second for the daemon discipline or once each tick interrupt for the kernel discipline to produce the system clock update <em>V<sub>c</sub></em>.</p> -<p>In PLL mode the frequency predictor is an integral of the offset over past updates, while the phase predictor is the offset amortized over time in order to avoid setting the clock backward. In FLL mode the phase predictor is not used, while the frequency predictor is similar to the NIST <em>lockclock</em> algorithm. In this algorithm, the frequency predictor is computed as a fraction of the current offset divided by the time since the last update in order to minimize the offset at the next update.</p> -<p>The discipline response in PLL mode is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the wander of the system clock oscillator. The scaled time constant is also used as the poll interval described on the <a href="poll.html">Poll Program</a> page. However, in NTP symmetric mode, each peer manages its own poll interval and the two might not be the same. In such cases either peer uses the minimum of its own poll interval and that of the other peer, which is included in the NTP packet header.</p> +<p>A block diagram of the clock discipline is shown in Figure 1. The timestamp of a reference clock or remote server is compared with the timestamp of the system clock, represented as a variable frequency oscillator (VFO), to produce a raw offset sample <em>V<sub>d</sub></em>. Offset samples are processed by the clock filter to produce a filtered update <em>V<sub>s</sub></em>. The loop filter implements a type-2 proportional-integrator controller (PIC). The PIC can minimize errors in both time and frequency using predictors <em>x</em> and <em>y</em>, respectively. The clock adjust process samples these predictors once each second for the daemon discipline or once each tick interrupt for the kernel discipline to produce the system clock update <em>V<sub>c</sub></em>.</p> +<p>In PLL mode the frequency predictor is an integral of the offset over past updates, while the phase predictor is the offset amortized over time in order to avoid setting the clock backward. In FLL mode the phase predictor is not used, while the frequency predictor is similar to the NIST <em>lockclock</em> algorithm. In this algorithm, the frequency predictor is computed as a fraction of the current offset divided by the time since the last update in order to minimize the offset at the next update.</p> +<p>The discipline response in PLL mode is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the wander of the system clock oscillator. The scaled time constant is also used as the poll interval described on the <a href="poll.html">Poll Program</a> page. However, in NTP symmetric mode, each peer manages its own poll interval and the two might not be the same. In such cases either peer uses the minimum of its own poll interval and that of the other peer, which is included in the NTP packet header.</p> <h4 id="loop">Loop Dynamics</h4> -<p> It is necessary to verify that the clock discipline algorithm is stable and satisfies the Nyquist criterion, which requires that the sampling rate be at least twice the bandwidth. In this case the bandwidth can be approximated by the reciprocal of the time constant. In the NTP specification and reference implementation, time constants and poll intervals are expressed as exponents of 2. By construction, the time constant exponent is five times the poll interval exponent. Thus, the default poll exponent of 6 corresponds to a poll interval of 64 s and a time constant of 2048 s. A change in the poll interval changes the time constant by a corresponding amount.. The Nyquist criterion requires the sample interval to be not more than half the time constant or 1024 s. The clock filter guarantees at least one sample in eight poll intervals, so the sample interval is not more than 512 s. This would be described as oversampling by a factor of two. Finally, the PLL parameters have been chosen for a damping factor of 2, which results in a much faster risetime than with critical damping, but results in modest overshoot of 6 percent.</p> -<p> It is important to understand how the dynamics of the PLL are affected by the time constant and poll interval. At the default poll interval of 64 s and a step offset change of 100 ms, the time response crosses zero in about 50 min and overshoots about 6 ms, as per design. Ordinarily, a step correction would causes a temporary frequency surge of about 5 PPM, which along with the overshoot slowly dissipates over a few hours.</p> -<p>However, the clock state machine used with the discipline algorithm avoids this transient at startup. It does this using a previously saved frequency file, if present, or by measuring the oscillator frequency, if not. It then quickly amortizes the residual offset at startup without affecting the oscillator frequency. In this way the offset error is less than 0.5 ms within 5 min, if the file is present, and within 10 min if not. See the <a href="clock.html">Clock State Machine</a> page for further details.</p> -<p>Since the PLL is linear, the response with different offset step amplitudes and poll intervals has the same characteristic shape, but scaled differently in amplitude and time. The response scales exactly with step amplitude, so that the response to a 10-ms step has the same shape as at 64 s, but with amplitude compressed by one-tenth. The response scales exactly with poll interval, so that response at a poll interval of 8 s has the same shape as at 64 s, but with time compressed by one-eighth.</p> -<p>The optimum time constant, and thus the poll interval, depends on the network time jitter and the oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. For typical Internet paths, the two error characteristics intersect at a point called the <em>Allan intercept</em>, which represents the optimum time constant. With a compromise Allan intercept of 2048 s, the optimum poll interval is about 64 s, which corresponds to a compromise poll exponent of 6. For fast LANs with modern computers, the Allan intercept is somewhat lower at around 512 s, so a compromise poll exponent of 4 (16 s) is appropriate. An intricate, heuristic algorithm is used to manage the actual poll interval within a specified range. Details are on the <a href="poll.html">Poll Program</a> page.</p> -<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congestion. In extreme cases not likely to be encountered in normal operation, the system time can be stepped forward or backward more than 128 ms. Further details are on the <a href="clock.html">Clock State Machine</a> page.</p> +<p> It is necessary to verify that the clock discipline algorithm is stable and satisfies the Nyquist criterion, which requires that the sampling rate be at least twice the bandwidth. In this case the bandwidth can be approximated by the reciprocal of the time constant. In the NTP specification and reference implementation, time constants and poll intervals are expressed as exponents of 2. By construction, the time constant exponent is five times the poll interval exponent. Thus, the default poll exponent of 6 corresponds to a poll interval of 64 s and a time constant of 2048 s. A change in the poll interval changes the time constant by a corresponding amount.. The Nyquist criterion requires the sample interval to be not more than half the time constant or 1024 s. The clock filter guarantees at least one sample in eight poll intervals, so the sample interval is not more than 512 s. This would be described as oversampling by a factor of two. Finally, the PLL parameters have been chosen for a damping factor of 2, which results in a much faster risetime than with critical damping, but results in modest overshoot of 6 percent.</p> +<p> It is important to understand how the dynamics of the PLL are affected by the time constant and poll interval. At the default poll interval of 64 s and a step offset change of 100 ms, the time response crosses zero in about 50 min and overshoots about 6 ms, as per design. Ordinarily, a step correction would causes a temporary frequency surge of about 5 PPM, which along with the overshoot slowly dissipates over a few hours.</p> +<p>However, the clock state machine used with the discipline algorithm avoids this transient at startup. It does this using a previously saved frequency file, if present, or by measuring the oscillator frequency, if not. It then quickly amortizes the residual offset at startup without affecting the oscillator frequency. In this way the offset error is less than 0.5 ms within 5 min, if the file is present, and within 10 min if not. See the <a href="clock.html">Clock State Machine</a> page for further details.</p> +<p>Since the PLL is linear, the response with different offset step amplitudes and poll intervals has the same characteristic shape, but scaled differently in amplitude and time. The response scales exactly with step amplitude, so that the response to a 10-ms step has the same shape as at 64 s, but with amplitude compressed by one-tenth. The response scales exactly with poll interval, so that response at a poll interval of 8 s has the same shape as at 64 s, but with time compressed by one-eighth.</p> +<p>The optimum time constant, and thus the poll interval, depends on the network time jitter and the oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. For typical Internet paths, the two error characteristics intersect at a point called the <em>Allan intercept</em>, which represents the optimum time constant. With a compromise Allan intercept of 2048 s, the optimum poll interval is about 64 s, which corresponds to a compromise poll exponent of 6. For fast LANs with modern computers, the Allan intercept is somewhat lower at around 512 s, so a compromise poll exponent of 4 (16 s) is appropriate. An intricate, heuristic algorithm is used to manage the actual poll interval within a specified range. Details are on the <a href="poll.html">Poll Program</a> page.</p> +<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congestion. In extreme cases not likely to be encountered in normal operation, the system time can be stepped forward or backward more than 128 ms. Further details are on the <a href="clock.html">Clock State Machine</a> page.</p> <h4 id="house">Clock Initialization and Management</h4> -<p>If left running continuously, an NTP client on a fast LAN in a home or office environment can maintain synchronization nominally within one millisecond. When the ambient temperature variations are less than a degree Celsius, the clock oscillator frequency is disciplined to within one part per million (PPM), even when the clock oscillator native frequency offset is 100 PPM or more.</p> -<p> For laptops and portable devices when the power is turned off, the battery backup clock offset error can increase as much as one second per day. When power is restored after several hours or days, the clock offset and oscillator frequency errors must be resolved by the clock discipline algorithm, but this can take several hours without specific provisions.</p> -<p> The provisions described in this section insure that, in all but pathological situations, the startup transient is suppressed to within nominal levels in no more than five minutes after a warm start or ten minutes after a cold start. Following is a summary of these provisions. A detailed discussion of these provisions is on the <a href="clock.html">Clock State Machine</a> page.</p> -<p> The reference implementation measures the clock oscillator frequency and updates a frequency file at intervals of one hour or more, depending on the measured frequency wander. This design is intended to minimize write cycles in NVRAM that might be used in a laptop or portable device. In a warm start, the frequency is initialized from this file, which avoids a possibly lengthy convergence time. In a cold start when no frequency file is available, the reference implementation first measures the oscillator frequency over a five-min interval. This generally results in a residual frequency error less than 1 PPM. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> -<p>In order to reduce the clock offset error at restart, the reference implementation mext disables oscillator frequency discipline and enables clock offset discipline with a small time constant. This is designed to quickly reduce the clock offset error without causing a frequency surge. This configuration is continued for an interval of five-min, after which the clock offset error is usually no more than a millisecond. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> -<p>Another concern at restart is the time necessary for the select and cluster algorithms to refine and validate the initial clock offset estimate. Normally, this takes several updates before setting the system clock. As the default minimum poll interval in most configurations is about one minute, it can take several minutes before setting the system clock. The <tt>iburst</tt> option of the <a href="confopt.html#burst"><tt>server</tt></a> command changes the behavior at restart and is recommended for client/server configurations. When this option is enabled, the client sends a volley of six requests at intervals of two seconds. This usually insures a reliable estimate is available in about ten seconds before setting the clock. Once this initial volley is complete, the procedures described above are executed.</p> -<p>As a result of the above considerations, when a backup source, such as the local clock driver, ACTS modem driver or orphan mode is included in the system configuration, it may happen that one or more of them are selectable before one or more of the regular sources are selectable. When backup sources are included in the configuration, the reference implementation waits an interval of several minutes without regular sources before switching to backup sources. This is generally enough to avoid startup transients due to premature switching to backup sources. The interval can be changed using the <tt>orphanwait</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> +<p>If left running continuously, an NTP client on a fast LAN in a home or office environment can maintain synchronization nominally within one millisecond. When the ambient temperature variations are less than a degree Celsius, the clock oscillator frequency is disciplined to within one part per million (PPM), even when the clock oscillator native frequency offset is 100 PPM or more.</p> +<p> For laptops and portable devices when the power is turned off, the battery backup clock offset error can increase as much as one second per day. When power is restored after several hours or days, the clock offset and oscillator frequency errors must be resolved by the clock discipline algorithm, but this can take several hours without specific provisions.</p> +<p> The provisions described in this section insure that, in all but pathological situations, the startup transient is suppressed to within nominal levels in no more than five minutes after a warm start or ten minutes after a cold start. Following is a summary of these provisions. A detailed discussion of these provisions is on the <a href="clock.html">Clock State Machine</a> page.</p> +<p> The reference implementation measures the clock oscillator frequency and updates a frequency file at intervals of one hour or more, depending on the measured frequency wander. This design is intended to minimize write cycles in NVRAM that might be used in a laptop or portable device. In a warm start, the frequency is initialized from this file, which avoids a possibly lengthy convergence time. In a cold start when no frequency file is available, the reference implementation first measures the oscillator frequency over a five-min interval. This generally results in a residual frequency error less than 1 PPM. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> +<p>In order to reduce the clock offset error at restart, the reference implementation next disables oscillator frequency discipline and enables clock offset discipline with a small time constant. This is designed to quickly reduce the clock offset error without causing a frequency surge. This configuration is continued for an interval of five-min, after which the clock offset error is usually no more than a millisecond. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> +<p>Another concern at restart is the time necessary for the select and cluster algorithms to refine and validate the initial clock offset estimate. Normally, this takes several updates before setting the system clock. As the default minimum poll interval in most configurations is about one minute, it can take several minutes before setting the system clock. The <tt>iburst</tt> option of the <a href="confopt.html#burst"><tt>server</tt></a> command changes the behavior at restart and is recommended for client/server configurations. When this option is enabled, the client sends a volley of six requests at intervals of two seconds. This usually insures a reliable estimate is available in about ten seconds before setting the clock. Once this initial volley is complete, the procedures described above are executed.</p> +<p>As a result of the above considerations, when a backup source, such as the local clock driver, ACTS modem driver or orphan mode is included in the system configuration, it may happen that one or more of them are selectable before one or more of the regular sources are selectable. When backup sources are included in the configuration, the reference implementation waits an interval of several minutes without regular sources before switching to backup sources. This is generally enough to avoid startup transients due to premature switching to backup sources. The interval can be changed using the <tt>orphanwait</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> diff --git a/html/drivers/driver20.html b/html/drivers/driver20.html index 6391e869359f..1c3ac782f768 100644 --- a/html/drivers/driver20.html +++ b/html/drivers/driver20.html @@ -1,7 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"><title>Generic NMEA GPS Receiver</title> - <!-- Changed by: Harlan &, 31-Mar-2014 --> + <!-- Changed by: Pearly &, 04-Feb-2019 --> <link href="scripts/style.css" type="text/css" rel="stylesheet"> <style type="text/css"> table.dlstable { font-size:85%; } @@ -13,7 +13,7 @@ <body> <h3>Generic NMEA GPS Receiver</h3> <p>Last update: - <!-- #BeginDate format:En2m -->31-Mar-2014 03:55<!-- #EndDate --> + <!-- #BeginDate format:En2m -->13-Jan-2020 07:12<!-- #EndDate --> UTC</p> <hr> <h4>Synopsis</h4> @@ -41,6 +41,9 @@ second insertion in UTC. To avoid problems mixing UTC and GPS timescales, the driver disables processing of UTC sentences once <tt>$GPZDG</tt> is received. + <br> + <strong>Caveat:</strong> Please see <a href="#talkerids">Talker + IDs</a> when using non-GPS or multi-system receivers. </p> <p> The driver expects the receiver to be set up to transmit at least one @@ -80,7 +83,14 @@ </tr><tr> <td class="ttf">$GPZDG,GPSTIME,DD,MM,YYYY,AA.BB,V*CS<cr><lf></td> <td>Accord</td> - </tr> + </tr><tr> + </tr><tr> + <td class="ttf">$PGRMF,gpsWk,gpsTow,DATE,UTC,LEAPS,LAT,LAT_REF,LON,LON_REF,TYPE,MODE,SPD,HDOP,TDOP*CS<cr><lf></td> + <td>Garmin</td> + </tr><tr> + <td class="ttf">$PUBX,04,UTC,DATE,utcTow,utcWk,LEAPS,clkBias,clkDrift,tpGran,*CS<cr><lf></td> + <td>UBLOX</td> + </tr> </tbody></table></p> <p><table class="dlstable" border="1"> @@ -91,78 +101,96 @@ </tr> <tr> - <td class="ttf">UTC</td> - <td>Time of day on UTC timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff])</td> + <td class="ttf">ALT</td> + <td>Antenna Altitude</td> </tr><tr> - <td class="ttf">POS_STAT</td> - <td>Position status. (A = Data valid, V = Data invalid)</td> + <td class="ttf">ALT_UNIT</td> + <td>Altitude Units (Metres/Feet)</td> </tr><tr> - <td class="ttf">LAT</td> - <td>Latitude (llll.ll)</td> + <td class="ttf">DATE</td> + <td>Date (ddmmyy)</td> </tr><tr> - <td class="ttf">LAT_REF</td> - <td>Latitude direction. (N = North, S = South)</td> + <td class="ttf">DD</td> + <td>Day of the month (1-31)</td> </tr><tr> - <td class="ttf">LON</td> - <td>Longitude (yyyyy.yy)</td> + <td class="ttf">D_AGE</td> + <td>Age of last DGPS Fix</td> </tr><tr> - <td class="ttf">LON_REF</td> - <td>Longitude direction (E = East, W = West)</td> + <td class="ttf">D_REF</td> + <td>Reference ID of DGPS station</td> </tr><tr> - <td class="ttf">SPD</td> - <td>Speed over ground. (knots) (x.x)</td> + <td class="ttf">FIX_MODE</td> + <td>Position Fix Mode (0 = Invalid, >0 = Valid)</td> </tr><tr> - <td class="ttf">HDG</td> - <td>Heading/track made good (degrees True) (x.x)</td> + <td class="ttf">GEO</td> + <td>Geoid/Elipsoid separation</td> </tr><tr> - <td class="ttf">DATE</td> - <td>Date (ddmmyy)</td> + <td class="ttf">GPSTIME</td> + <td>Time of day on GPS timescale. Hours, minutes and seconds [fraction (opt.)] (hhmmss[.f])</td> </tr><tr> - <td class="ttf">MAG_VAR</td> - <td>Magnetic variation (degrees) (x.x)</td> + <td class="ttf">gpsTow</td> + <td>GPS week time, seconds since start of GPS week (0..604799)</td> </tr><tr> - <td class="ttf">MAG_REF</td> - <td>Magnetic variation (E = East, W = West)</td> + <td class="ttf">gpsWk</td> + <td>Week number in the GPS time scale (may exceed 1024)</td> </tr><tr> - <td class="ttf">FIX_MODE</td> - <td>Position Fix Mode (0 = Invalid, >0 = Valid)</td> + <td class="ttf">G_UNIT</td> + <td>Geoid units (M/F)</td> </tr><tr> - <td class="ttf">SAT_USED</td> - <td>Number of Satellites used in solution</td> + <td class="ttf">HDG</td> + <td>Heading/track made good (degrees True) (x.x)</td> </tr><tr> <td class="ttf">HDOP</td> <td>Horizontal Dilution of Precision</td> </tr><tr> - <td class="ttf">ALT</td> - <td>Antenna Altitude</td> - </tr><tr> - <td class="ttf">ALT_UNIT</td> - <td>Altitude Units (Metres/Feet)</td> + <td class="ttf">LAT</td> + <td>Latitude (llll.ll)</td> </tr><tr> - <td class="ttf">GEO</td> - <td>Geoid/Elipsoid separation</td> + <td class="ttf">LAT_REF</td> + <td>Latitude direction (N = North, S = South)</td> </tr><tr> - <td class="ttf">G_UNIT</td> - <td>Geoid units (M/F)</td> + <td class="ttf">LEAPS</td> + <td>Leap seconds or difference between GPS time scale and UTC</td> </tr><tr> - <td class="ttf">D_AGE</td> - <td>Age of last DGPS Fix</td> + <td class="ttf">LON</td> + <td>Longitude (yyyyy.yy)</td> </tr><tr> - <td class="ttf">D_REF</td> - <td>Reference ID of DGPS station</td> + <td class="ttf">LON_REF</td> + <td>Longitude direction (E = East, W = West)</td> </tr><tr> - <td class="ttf">GPSTIME</td> - <td>Time of day on GPS timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.f])</td> + <td class="ttf">MAG_REF</td> + <td>Magnetic variation (E = East, W = West)</td> </tr><tr> - <td class="ttf">DD</td> - <td>Day of the month (1-31)</td> + <td class="ttf">MAG_VAR</td> + <td>Magnetic variation (degrees) (x.x)</td> </tr><tr> <td class="ttf">MM</td> <td>Month of the year (1-12)</td> </tr><tr> + <td class="ttf">POS_STAT</td> + <td>Position status. (A = Data valid, V = Data invalid)</td> + </tr><tr> + <td class="ttf">SAT_USED</td> + <td>Number of Satellites used in solution</td> + </tr><tr> + <td class="ttf">SPD</td> + <td>Speed over ground. (knots) (x.x)</td> + </tr><tr> + <td class="ttf">UTC</td> + <td>Time of day on UTC timescale. Hours, minutes and seconds [fraction (opt.)] (hhmmss[.fff])</td> + </tr><tr> <td class="ttf">YYYY</td> <td>Year</td> </tr><tr> + <td class="ttf">WEEK</td> + <td>GPS week (0-1023)</td> + </tr><tr> + <td class="ttf">WSEC</td> + <td>Seconds since start of week (0-604799)</td> + </tr><tr> + <td class="ttf">LEAP</td> + <td>GPS leap seconds, that is, seconds ahead of UTC</td> + </tr><tr> <td class="ttf">AA.BB</td> <td>Denotes the signal strength (should be < 05.00)</td> </tr><tr> @@ -181,6 +209,36 @@ </tbody></table></p> + <h4><a name="talkerids"/>NMEA Talker IDs</h4> + + <p> + GNSS receivers use a distinct talker ID for the GNSS they + process. Receivers capable of tracking different systems at the same time + can emit <tt>$GPRMC</tt> (GPS), <tt>$GLRMC</tt> (GLONASS), + <tt>$GARMC</tt> (Galileo), <tt>$GNRMC</tt> (generic/combined) and others + all in one data stream. + </p><p> + The driver supports this to a certain degree by ignoring the + talker ID on the standard sentences RMC, GLL, GGA, ZDA and ZDG. (It + possibly should not do that on the latter, but for now, that's the way + it is.) So whenever <tt>$GPRMC</tt> is mentioned in this document, + substitute any possible talker ID your receiver might emit -- it will + still match. + </p><p> + This approach has a drawback. It is easy to use for single-system + receivers, but it cannot separate the data streams for multi-system + receiver modules. It is therefore undefined which GNSS actually + provides the data, and this can lead to strange behavior. This is + especially true if the different GNSS provide very different signal + quality to the receiver; the driver is not able to cherry-pick the best + source and might actually end up in using the worst available. It is + therefore recommended to set up such a receiver to either use just a + single GNSS (which would defeat its purpose) or to emit only the + combined data, which usually has the <tt>GN</tt> talker ID defined by + the NMEA standard. + <p> + + <h4>The 'mode' byte</h4> <p> @@ -202,7 +260,7 @@ <td align="center">0</td> <td align="center">1</td> <td align="center">1</td> - <td>process <tt>$GPMRC</tt></td> + <td>process <tt>$GPRMC</tt></td> </tr><tr> <td align="center">1</td> <td align="center">2</td> @@ -259,9 +317,14 @@ <td align="center">0x100</td> <td>process <tt>$PGRMF</tt></td> </tr><tr> - <td align="center">9-15</td> + <td align="center">9</td> + <td align="center">512</td> + <td align="center">0x200</td> + <td>process <tt>$PUBX,04</tt></td> + </tr><tr> + <td align="center">10-15</td> <td align="center"></td> - <td align="center">0xFE00</td> + <td align="center">0xFC00</td> <td>reserved - leave 0</td> </tr><tr> <td align="center">16</td> @@ -269,6 +332,24 @@ <td align="center">0x10000</td> <td>Append extra statistics to the clockstats line. Details below.</td> + </tr><tr> + <td align="center">17</td> + <td align="center">131072</td> + <td align="center">0x20000</td> + <td>"Silent PPS" mode. Use the PPS channel (if enabled with + fudge flag 1) to get precise receive time stamps. + Do <em>not</em> set the PPS flag in the clock status, so the + clock is not considered as PPS peer. + </td> + </tr><tr> + <td align="center">18</td> + <td align="center">262144</td> + <td align="center">0x40000</td> + <td>Trust the date delivered via NMEA. Do this only if + you <em>really</em> trust the receiver! + See <a href="#datetrust">below</a>. <strong>Caveat:</strong> + This (hitherto undocumented) bit has moved! + </td> </tr> </tbody></table> @@ -291,7 +372,7 @@ </li></ul> The driver uses 4800 bits per second by default, but faster bitrates can be selected using bits 4 to 6 of the mode field. - <p></p> + </p> <p> <strong>Caveat:</strong> Using higher line speeds does not necessarily @@ -306,6 +387,29 @@ linespeed of 4800 bps or 9600 bps. </p> + <h4><a name="datetrust"/>About distrusting NMEA date stamps</h4> + <p> + Trusting the calendar dates delivered via NMEA is a risky thing, and by + default these dates are handled with a huge dose of skepticism. Many + receivers deliver a correct calendar date for a period of just 1024 weeks, + with a starting point baked somewhere into their firmware. Beyond that, + they warp back to the begin of their era and simply provide wrong date + information. To battle this widely observed effect, the date delivered is + by default reduced to GPS time again and then (re-)mapped according to the + base date, either the implicit value or the value set via "tos basedate". + If the receiver can <em>really</em> be trusted to deliver the right date + (which is not impossible, just more expensive for the manufacturer), then + mode bit 18 can be used to bypass the era mapping. Setting this bit is + not needed under most circumstances, and setting it with an unreliable + receiver can have severe effects. Handle with care. + </p><p> + <strong>Note:</strong> This functionality was available for some time as + undocumented feature, with a different bit value. It was moved in the + process of becoming officially acknowledged to avoid excessive scattering + of the mode bit mask. + </p> + + <h4>Monitor Data</h4> <p>The last GPS sentence that is accepted or rejected is written to the diff --git a/html/drivers/driver29.html b/html/drivers/driver29.html index 4939d8012ce3..0a5659c7f7ab 100644 --- a/html/drivers/driver29.html +++ b/html/drivers/driver29.html @@ -11,7 +11,7 @@ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> <h1><font size="+2">Trimble Palisade and Thunderbolt Receivers</font> <p>Last update: - <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + <!-- #BeginDate format:En2m -->13-Sep-2019 08:07<!-- #EndDate --> UTC</p> <hr> </h1> @@ -69,13 +69,28 @@ </td> <td><b>9600 baud, 8-bits, 1-stop, no parity</b></td> </tr> + <tr> + <td> + <div align="right"> + <tt><font size="+1">Serial I/O (Copernicus II):</font></tt></div> + </td> + <td><b>38400 baud, 8-bits, 1-stop, no parity</b></td> + </tr> </table> <h2><font size="+1">Description</font></h2> The <b>refclock_palisade</b> driver supports <a href="http://www.trimble.com/products/ntp">Trimble Navigation's Palisade Smart Antenna GPS receiver</a>.<br> Additional software and information about the Palisade GPS is available from: <a href="http://www.trimble.com/oem/ntp">http://www.trimble.com/oem/ntp</a>.<br> Latest NTP driver source, executables and documentation is maintained at: <a href="ftp://ftp.trimble.com/pub/ntp">ftp://ftp.trimble.com/pub/ntp</a> - <p>This documentation describes version 7.12 of the GPS Firmware and version 2.46 (July 15, 1999) and later, of the driver source.<br> </p> + <p>This documentation describes version 7.12 of the GPS Firmware and version 2.46 (July 15, 1999) and later, of the driver source.</p> <p>This documentation describes version 1 of the Thunderbolt Receiver Firmware, no tests have been made on further firmwares, please read "Notes on the Thunderbolt Receiver's Firmware" at the end of this documentation for more information.</p> + <p>This driver also supports the following receivers:</p> + <blockquote> + <p>Endrun Technologies Praecis NTP server with GPS</p> + <p>Trimble Acutime Gold smart antenna</p> + <p>Trimble Resolution family</p> + <p>Trimble ACE III</p> + <p>Trimble Copernicus II</p> + </blockquote> <h2><font size="+1">Operating System Compatibility</font></h2> The Palisade driver has been tested on the following software and hardware platforms:<br> <center> @@ -118,7 +133,7 @@ </tr> </table> </center><P> - <b>Attention</b>: Thunderbolt Receiver has not being tested on the previous software and hardware plataforms. + <b>Attention</b>: Other receiver types have not being tested on the previous software and hardware plataforms. <h2><font size="+1">GPS Receiver</font></h2> The Palisade GPS receiver is an 8-channel smart antenna, housing the GPS receiver, antenna and interface in a single unit, and is designed for rooftop deployment in static timing applications. <p>Palisade generates a PPS synchronized to UTC within +/- 100 ns. The Palisade's external event input with 40 nanosecond resolution is utilized by the Palisade NTP driver for asynchronous precision time transfer.</p> @@ -232,7 +247,41 @@ <tt># and set flag2 to turn off event polling.</tt><br> <tt><a href="#flag2">fudge 127.127.29.0 flag2 1</a></tt><br> <tt>#------------------------------------------------------------------------------</tt><br> </p> - Currently the Thunderbolt mode doesn't support event polling, the reasons are explained on the "Notes on the Thunderbolt Receiver's Firmware" section at the end of this documentation. + + <h4>Resolution NTP Configuration file</h4> + <tt>#------------------------------------------------------------------------------</tt> + <p>Configuration without event polling:<br> + <tt>#------------------------------------------------------------------------------</tt><br> + <tt># The Primary reference</tt><br> + <tt>server 127.127.29.0 mode 5 # Trimble Resolution GPS (Stratum 1).</tt><br> + <tt># Set packet delay</tt><br> + <tt><a href="#time1">fudge 127.127.29.0 time1 0.410</a></tt><br> + <tt># and set flag2 to turn off event polling.</tt><br> + <tt><a href="#flag2">fudge 127.127.29.0 flag2 1</a></tt><br> + <tt>#------------------------------------------------------------------------------</tt><br> </p> + + <h4>ACE III NTP Configuration file</h4> + <tt>#------------------------------------------------------------------------------</tt> + <p>Configuration with event polling:<br> + <tt>#------------------------------------------------------------------------------</tt><br> + <tt># The Primary reference</tt><br> + <tt>server 127.127.29.0 mode 6 # Trimble ACE III GPS (Stratum 1).</tt><br> + <tt># Set packet delay</tt><br> + <tt><a href="#time1">fudge 127.127.29.0 time1 0.720</a></tt><br> + <tt>#------------------------------------------------------------------------------</tt><br> </p> + + <h4>Copernicus II NTP Configuration file</h4> + <tt>#------------------------------------------------------------------------------</tt> + <p>Configuration without event polling:<br> + <tt>#------------------------------------------------------------------------------</tt><br> + <tt># The Primary reference</tt><br> + <tt>server 127.127.29.0 mode 7 # Trimble Copernicus II GPS (Stratum 1).</tt><br> + <tt># Set packet delay</tt><br> + <tt><a href="#time1">fudge 127.127.29.0 time1 0.240</a></tt><br> + <tt># and set flag2 to turn off event polling.</tt><br> + <tt><a href="#flag2">fudge 127.127.29.0 flag2 1</a></tt><br> + <tt>#------------------------------------------------------------------------------</tt><br> </p> + Currently the Thunderbolt mode doesn't support event polling, the reasons are explained on the "Notes on the Thunderbolt Receiver's Firmware" section at the end of this documentation. The Resolution and Copernicus II modes require event polling to be disabled whereas the ACE III requires polling to be enabled. <h2><a name="TimeTransfer"></a><font size="+1">Time Transfer and Polling</font></h2> Time transfer to the NTP host is performed via the Palisade's comprehensive time packet output. The time packets are output once per second, and whenever an event timestamp is requested. <p>The driver requests an event time stamp at the end of each polling interval, by pulsing the RTS (request to send) line on the serial port. The Palisade GPS responds with a time stamped event packet.</p> @@ -269,7 +318,16 @@ <h2><font size="+1">Mode Parameter</font></h2> <dl> <dt><tt><font size="+1">mode <i>number</i></font></tt> - <dd>The mode parameter to the server command specifies the specific hardware this driver is for. The default is 0 for a normal Trimble Palisade. The other options are <b>1</b> for an <b>Endrun Praecis</b> in Trimble emulation mode, and <b>2</b> for the <b>Trimble Thunderbolt</b> GPS Disciplined Clock Receiver. + <dd> + The mode parameter to the server command specifies the specific hardware this driver is for. The default is 0 for a normal Trimble Palisade. The other options are: + <blockquote> + <p><b>1</b> for an <b>Endrun Praecis</b> in Trimble emulation mode</p> + <p><b>2</b> for the <b>Trimble Thunderbolt</b> GPS Disciplined Clock Receiver</p> + <p><b>3</b> for the <b>Acutime Gold</b> smart antenna</p> + <p><b>5</b> for <b>Trimble Resolution</b> devices</p> + <p><b>6</b> for the <b>Trimble ACE III</b> board</p> + <p><b>7</b> for the <b>Trimble Copernicus II</b> device</p> + </blockquote> </dl> <h2><font size="+1">DEFINEs</font></h2> The following constants are defined in the driver source code. These defines may be modified to improve performance or adapt to new operating systems.<br> @@ -291,16 +349,16 @@ <td>1 microsecond</td> </tr> <tr> - <td>CURRENT_UTC</td> - <td>Valid GPS - UTC offset</td> - <td>13</td> - </tr> - <tr> <td>SPEED232</td> <td>Host RS-232 baud rate</td> <td>B9600</td> </tr> <tr> + <td>SPEED232COP</td> + <td>Host RS-232 baud rate (Copernicus II mode)</td> + <td>B38400</td> + </tr> + <tr> <td>TRMB_MINPOLL </td> <td>Minimum polling interval</td> <td>5 (32 seconds)</td> diff --git a/html/miscopt.html b/html/miscopt.html index 247f5329040b..f5bce4b44ac3 100644 --- a/html/miscopt.html +++ b/html/miscopt.html @@ -10,7 +10,7 @@ <img src="pic/boom3.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a> <p>We have three, now looking for more.</p> <p>Last update: - <!-- #BeginDate format:En2m -->14-Oct-2017 08:34<!-- #EndDate --> + <!-- #BeginDate format:En2m -->11-Feb-2020 14:00<!-- #EndDate --> UTC</p> <br clear="left"> <h4>Related Links</h4> @@ -63,8 +63,9 @@ <dd>This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run <tt>ntpd</tt> on multiple hosts, with (mostly) common options (e.g., a restriction list).</dd> <dt id="interface"><tt>interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | <i>name</i> | <i>address</i>[/<i>prefixlen</i>]]</tt></dt> <dd>This command controls which network addresses <tt>ntpd</tt> opens, and whether input is dropped without processing. The first parameter determines the action for addresses which match the second parameter. That parameter specifies a class of addresses, or a specific interface name, or an address. In the address case, <tt><i>prefixlen</i></tt> determines how many bits must match for this rule to apply. <tt>ignore</tt> prevents opening matching addresses, <tt>drop</tt> causes <tt>ntpd</tt> to open the address and drop all received packets without examination. Multiple <tt>interface</tt> commands can be used. The last rule which matches a particular address determines the action for it. <tt>interface</tt> commands are disabled if any <a href="ntpd.html#--interface"><tt>-I</tt></a>, <a href="ntpd.html#--interface"><tt>--interface</tt></a>, <a href="ntpd.html#--novirtualips"><tt>-L</tt></a>, or <a href="ntpd.html#--novirtualips"><tt>--novirtualips</tt></a> command-line options are used. If none of those options are used and no <tt>interface</tt> actions are specified in the configuration file, all available network addresses are opened. The <tt>nic</tt> command is an alias for <tt>interface</tt>.</dd> - <dt id="leapfile"><tt>leapfile <i>leapfile</i></tt></dt> - <dd>This command loads the IERS leapseconds file and initializes the leapsecond values for the next leapsecond time, expiration time and TAI offset. The file can be obtained directly from the IERS at <a href="https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list">https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</a> or <a href="ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list">ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</a>.</dd> + <dt id="leapfile"><tt>leapfile <i>leapfile</i> [checkhash|ignorehash]</tt></dt> + <dd>This command loads the IERS leapseconds file and initializes the leapsecond values for the next leapsecond time, expiration time and TAI offset. The file can be obtained directly from the IERS at <a href="https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list">https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</a> or <a href="ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list">ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</a>. + <tt>ignorehash</tt> instructs <tt>ntpd</tt> to ignore the hash signature on the file, <tt>checkhash</tt> (which is the default when omitted) needs a hash line in the file to be valid. Files without any hash signature are lodaed in both cases.</dd> <dd>The <i>leapfile</i> is scanned when <tt>ntpd</tt> processes the <tt>leapfile</tt> directive or when <tt>ntpd</tt> detects that <i>leapfile</i> has changed. <tt>ntpd</tt> checks once a day to see if the <i>leapfile</i> has changed.</dd> <dd>While not strictly a security function, the Autokey protocol provides means to securely retrieve the current or updated leapsecond values from a server.</dd> <dt id="leapsmearinterval"><tt>leapsmearinterval <i>seconds</i></tt></dt> @@ -108,6 +109,24 @@ For the ACTS modem driver (type 18), the arguments consist of a maximum of 10 telephone numbers used to dial USNO, NIST or European time services. For the JJY driver (type 40 mode 100 - 180), the argument is one telephone number used to dial the telephone JJY service. The Hayes command ATDT is normally prepended to the number, which can contain other modem control codes as well.</dd> + <dt id="pollskewlist" + ><tt>pollskewlist</tt> <tt>[</tt><i>poll</i> <i>value</i><tt> + | </tt><i>value</i><tt>]</tt> <tt>...</tt> <tt>[default </tt><i>value</i><tt> + | </tt><i>value</i><tt>]</tt></dt> +<dd>Enable skewing of our poll requests to our servers. +<i>poll</i> +is a number between 3 and 17 inclusive, identifying a specific poll interval. +A poll interval is 2^n seconds in duration, +so a poll value of 3 corresponds to 8 seconds +and +a poll interval of 17 corresponds to +131,072 seconds, or about a day and a half. +The next two numbers must be between 0 and one-half of the poll interval, +inclusive. +The first number specifies how early the poll may start, +while +the second number specifies how late the poll may be delayed. +With no arguments, internally specified default values are chosen.</dd> <dt id="reset"><tt>reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]</tt></dt> <dd>Reset one or more groups of counters maintained by ntpd and exposed by <tt>ntpq</tt> and <tt>ntpdc</tt>.</dd> <dt id="rlimit"><tt>rlimit [memlock <i>Nmegabytes</i> | stacksize <i>N4kPages</i> | filenum <i>Nfiledescriptors</i>]</tt></dt> @@ -147,12 +166,16 @@ <dd>Specifies the stepout threshold in seconds. The default without this command is 300 s. Since this option also affects the training and startup intervals, it should not be set less than the default. Further details are on the <a href="clock.html">Clock State Machine</a> page.</dd> </dl> </dd> - <dt id="tos"><tt>tos [basedate <i>date<i> | bcpollbstep <i>poll-gate</i> | beacon <i>beacon</i> | ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | maxclock <i>maxclock </i>| maxdist <i>maxdist</i> | minclock <i>minclock</i> | mindist <i>mindist </i>| minsane <i>minsane</i> | orphan <i>stratum</i> | orphanwait <em>delay</em>]</tt></dt> + <dt id="tos"><tt>tos [basedate <i>date</i> | bcpollbstep <i>poll-gate</i> | beacon <i>beacon</i> | ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | maxclock <i>maxclock </i>| maxdist <i>maxdist</i> | minclock <i>minclock</i> | mindist <i>mindist </i>| minsane <i>minsane</i> | orphan <i>stratum</i> | orphanwait <em>delay</em>]</tt></dt> <dd>This command alters certain system variables used by the the clock selection and clustering algorithms. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in dynamic server discovery schemes. The options are as follows:</dd> <dd> <dl> <dt><tt>basedate <i>date</i></tt></dt> - <dd>Set NTP era anchor. <tt><i>date</i></tt> is either a date in ISO8601 format (<i>YYYY-MM-DD<i>) or an integer giving the days since 1900-01-01, the start of the NTP epoch. <tt>ntpd</tt> will clamp the system time to an era starting with the begin of this this day (00:00:00Z), covering a range of 2<sup>32</sup> seconds or roughly 136 years. The default is the begin of the UNIX epoch, 1970-01-01.</dd> + <dd>Set NTP and GPS era anchor. <tt><i>date</i></tt> is either a date in ISO8601 format (<i>YYYY-MM-DD</i>) or an integer giving the days since 1900-01-01, the start of the NTP epoch. <tt>ntpd</tt> will clamp the system time to an era starting with the begin of this this day (00:00:00Z), covering a range of 2<sup>32</sup> seconds or roughly 136 years. The lowest accepted value is effectively 1970-01-02.<br> + The GPS era base is the next Sunday on or following the base date, but obviously not before 1980-01-06. GPS time stamps are mapped into the 1024 weeks following the GPS base.<br> + The default value is derived from the repository or build time stamp, minus 11 days. 1970-01-02 was chosen as lower bound so the <em>local</em> time is always after 1970-01-01,00:00. Some systems get into trouble if this is not the case.<p> + <b><u>ATTENTION:</u></b> If the system clock is before the effective (implied or specific) basedate, the system clock will be set to the base date once and immediately when <tt>ntpd</tt> starts. This helps systems that have lost time completely to recover. Though not noticeable under normal conditions, it <em>can</em> happen. Check the logs if starting <tt>ntpd</tt> causes sudden clock moves. + </dd> <dt><tt>bcpollbstep <i>poll-gate</i></tt></dt> <dd>This option will cause the client to delay believing backward time steps from a broadcast server for <tt>bcpollbstep</tt> poll intervals. NTP Broadcast networks are expected to be trusted, and if the server's time gets stepped backwards then it's desireable that the clients follow this change as soon as possible. However, in spite of various protections built-in to the broadcast protocol, it is possible that an attacker could perform a carefully-constructed replay attack and cause clients to erroneously step their clocks backward. If the risk of a successful broadcast replay attack is greater than the risk of the clients being out of sync in the event that there is a backward step on the broadcast time servers, this option may be used to cause the clients to delay beliveving backward time steps until <i>poll-gate</i> consecutive polls have been received. The default is 0, which means the client will accept these steps upon receipt. Any value from 0 to 4 can be specified.</dd> <dt><tt>beacon <i>beacon</i></tt></dt> |