Commit eb383384 authored by Eric S. Raymond's avatar Eric S. Raymond

Merge the ntp.conf theory of operation of refclocks back to the web docs.

parent fbf30669
// Association options - included twice.
//
// Note, some of these options are described with special refclock
// semantics on the ntp.conf manual page.
`autokey`::
All packets sent to and received from the server or peer are to
......
......@@ -21,9 +21,12 @@ include::includes/audio.txt[]
[[intro]]
== Introduction ==
{project-shortname} supports almost four dozen satellite, radio and telephone
modem reference clocks plus several audio devices for instrumentation
signals. A general description of the reference clock support is on this
{project-shortname} supports a large numberr of satellite, radio and
telephone modem reference clocks plus several audio devices for
instrumentation signals.plus a special pseudo-clock used for backup or
when no other clock source is available.
A general description of the reference clock support is on this
page. Additional information about each reference clock driver can be
found via links from this page. Additional information is on the
link:rdebug.html[Debugging Hints for Reference Clock Drivers] and
......@@ -46,12 +49,15 @@ declining under pressure from GPS technology.
A device driver specific to each reference clock must be compiled in
the distribution; however, most common GPS, radio, satellite and
telephone modem clocks are included by default and are activated by
configuration commands.
configuration commands. Note that an attempt to configure a reference
clock when the driver has not been compiled or the hardware port has
not been appropriately configured results in a scalding remark to the
system log file, but is otherwise non hazardous.
Reference clocks are supported in the same way as ordinary NTP clients
and use the same filter, select, cluster and combine algorithms. Drivers
have addresses in the form 127.127._t.u_, where _t_ is the driver type
and _u_ is a unit number in the range 0-3 to distinguish multiple
and _u_ is a unit number to distinguish multiple
instances of the same driver. The connection to the computer is device
dependent, usually a serial port, parallel port or special bus
peripheral, but some can work directly from an audio codec or sound
......@@ -60,20 +66,32 @@ name used by the driver to the particular device name.
The `server` command is used to configure a reference clock. Only the
`mode`, `minpoll`, `maxpoll`, and `prefer` options are supported for
reference clocks, as described on the link:clockopt.html[Reference Clock
Commands] page. The `prefer` option is discussed on the
link:prefer.html[Mitigation Rules and the `prefer` Keyword] page. Some
of these options have meaning only for selected clock drivers.
The `fudge` command can be used to provide additional information for
individual drivers and normally follows immediately after the `server`
command. The reference clock stratum is by default 0, so that the server
stratum appears to clients as 1. The `stratum` option can be used to set
the stratum to any value in the range 0 through 15. The `refid` option
can be used to change the reference identifier, as might in the case
when the driver is disciplined by a pulse-per-second (PPS) source. The
device-dependent `mode`, `time` and `flag` options can provide
additional driver customization.
reference clocks, as described on the link:clockopt.html[Reference
Clock Commands] page. The `prefer` option can be useful to persuade
the server to cherish a reference clock with somewhat more enthusiasm
than other reference clocks or peers. It is further discussed on the
link:prefer.html[Mitigation Rules and the `prefer` Keyword] page. The
`minpoll` and `maxpoll` options have meaning only for selected clock
drivers.
The `fudge` command is used to provide additional information for
individual clock drivers and normally follows immediately after the
`server` command. The `address` argument specifies the clock address.
The `refid` and `stratum` options can be used to override the defaults
for the device. There are two optional device-dependent time offsets and
four flags that can be included in the `fudge` command as well.
The stratum number of a reference clock is by default zero. Since the
{ntpdman} daemon adds one to the stratum of each peer, a primary
server ordinarily displays an external stratum of one. In order to
provide engineered backups, it is often useful to specify the reference
clock stratum as greater than zero. The stratum option is used for this
purpose. Also, in cases involving both a reference clock and a
pulse-per-second (PPS) discipline signal, it is useful to specify the
reference clock identifier as other than the default, depending on the
driver. The refid option is used for this purpose. Except where noted,
these options apply to all clock drivers.
[[spec]]
== Special Considerations ==
......
......@@ -178,8 +178,9 @@ include::../docs/access-commands.txt[]
=== Manycasting ===
For a detailed description of manycast operation, see the "Servery
Discovery" page in the web documentation.
For a detailed description of manycast operation, see the "Server
Discovery" page (available as part of the HTML documentation provided
in `/usr/share/doc/{ntp}`).
=== Manycast Options ===
......@@ -224,79 +225,16 @@ Discovery" page in the web documentation.
== Reference Clock Support ==
The NTP daemon supports some two dozen different radio,
satellite and modem reference clocks plus a special pseudo-clock used
for backup or when no other clock source is available. Detailed
descriptions of individual device drivers and options can be found in
the "Reference Clock Drivers" page (available as part of the HTML
documentation provided in `/usr/share/doc/{ntp}`). Additional information
can be found in the pages linked there, including the "Debugging Hints
for Reference Clock Drivers" and "How To Write a Reference Clock Driver"
pages (available as part of the HTML documentation provided in
`/usr/share/doc/{ntp}`). In addition, support for a PPS signal is
available as described in the "Pulse-per-second (PPS) Signal
Interfacing" page (available as part of the HTML documentation provided
in `/usr/share/doc/{ntp}`). Many drivers support special line
discipline/streams modules which can significantly improve the accuracy
using the driver. These are described in the "Line Disciplines and
Streams Drivers" page (available as part of the HTML documentation
provided in `/usr/share/doc/{ntp}`).
A reference clock will generally (though not always) be a radio timecode
receiver which is synchronized to a source of standard time such as the
services offered by the NRC in Canada and NIST and USNO in the US. The
interface between the computer and the timecode receiver is device
dependent, but is usually a serial port. A device driver specific to
each reference clock must be selected and compiled in the distribution;
however, most common radio, satellite and modem clocks are included by
default. Note that an attempt to configure a reference clock when the
driver has not been compiled or the hardware port has not been
appropriately configured results in a scalding remark to the system log
file, but is otherwise non hazardous.
For the purposes of configuration, {ntpdman} treats reference
clocks in a manner analogous to normal NTP peers as much as possible.
Reference clocks are identified by a syntactically correct but invalid
IP address, in order to distinguish them from normal NTP peers.
Reference clock addresses are of the form 127.127.t_._u_, where _t_ is
an integer denoting the clock type and _u_ indicates the unit number.
While it may seem overkill, it is in fact sometimes
useful to configure multiple reference clocks of the same type, in which
case the unit numbers must be unique.
The `server` command is used to configure a reference clock, where the
_address_ argument in that command is the clock address. The `key`,
`version` and `ttl` options are not used for reference clock support.
The `mode` option is added for reference clock support, as described
below. The `prefer` option can be useful to persuade the server to
cherish a reference clock with somewhat more enthusiasm than other
reference clocks or peers. Further information on this option can be
found in the "Mitigation Rules and the prefer Keyword" (available as
part of the HTML documentation provided in `/usr/share/doc/{ntp}`) page.
The `minpoll` and `maxpoll` options have meaning only for selected clock
drivers. See the individual clock driver document pages for additional
information.
The `fudge` command is used to provide additional information for
individual clock drivers and normally follows immediately after the
`server` command. The `address` argument specifies the clock address.
The `refid` and `stratum` options can be used to override the defaults
for the device. There are two optional device-dependent time offsets and
four flags that can be included in the `fudge` command as well.
The stratum number of a reference clock is by default zero. Since the
{ntpdman} daemon adds one to the stratum of each peer, a primary
server ordinarily displays an external stratum of one. In order to
provide engineered backups, it is often useful to specify the reference
clock stratum as greater than zero. The stratum option is used for this
purpose. Also, in cases involving both a reference clock and a
pulse-per-second (PPS) discipline signal, it is useful to specify the
reference clock identifier as other than the default, depending on the
driver. The refid option is used for this purpose. Except where noted,
these options apply to all clock drivers.
For a detailed description of reference-clock configuration, see the
"Reference Clock Drivers" page (available as part of the HTML
documentation provided in `/usr/share/doc/{ntp}`).
== Reference Clock Commands
// This can't be merged with the master description of association
// options (included above) because the cited options have different
// and more specific semantics when used with refclocks.
`server` _127.127.t_._u_ [`prefer`] [`mode` _int_] [`minpoll` _int_]
[`maxpoll` _int_]::
This command can be used to configure reference clocks in special
......@@ -342,10 +280,9 @@ these options apply to all clock drivers.
facilitate calibration when more than one radio clock or PPS signal
is supported, a special calibration feature is available. It takes
the form of an argument to the `enable` command described in
"Miscellaneous` Options" page and operates as described in the
"Miscellaneous Options" page and operates as described in the
"Reference Clock Drivers" page (available as part of the HTML
documentation provided in `/usr/share/doc/{ntp}`).
//FIXME: page reference may be invalid
`time2` _secs_;;
Specifies a fixed-point decimal number in seconds, which is
interpreted in a driver-dependent way. See the descriptions of
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment