[ntpsec commit] Factor server and fudge option documentation for refclocks.
Eric S. Raymond
esr at ntpsec.org
Mon Oct 12 23:00:39 UTC 2015
Module: ntpsec
Branch: master
Commit: 756a05edc44ccda754392bf1bab56368f8e31caf
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=756a05edc44ccda754392bf1bab56368f8e31caf
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Mon Oct 12 19:00:31 2015 -0400
Factor server and fudge option documentation for refclocks.
---
docs/clockopt.txt | 68 +---------------------------------
docs/includes/assoc-commands.txt | 2 +-
docs/includes/assoc-options.txt | 2 +-
docs/includes/clock-options.txt | 80 ++++++++++++++++++++++++++++++++++++++++
ntpd/ntp.conf.txt | 79 +--------------------------------------
5 files changed, 85 insertions(+), 146 deletions(-)
diff --git a/docs/clockopt.txt b/docs/clockopt.txt
index fc5370b..7befb27 100644
--- a/docs/clockopt.txt
+++ b/docs/clockopt.txt
@@ -18,7 +18,7 @@ include::includes/clockopt.txt[]
[[addrs]]
== Reference Clock Adddresses ==
-Unless noted otherwise, further information about these ccommands is on
+Unless noted otherwise, further information about these commands is on
the link:refclock.html[Reference Clock Support] page.
Reference clocks are identified by a syntactically correct but invalid
@@ -32,71 +32,7 @@ unit numbers must be unique.
[[cmd]]
== Commands and Options ==
-`server 127.127.`'t'.'u' [`prefer`] [`mode` 'int'] [`minpoll` 'int'] [`maxpoll` 'int']::
- This command can be used to configure reference clocks in special
- ways. The options are interpreted as follows:
- `prefer`;;
- Marks the reference clock as preferred. All other things being
- equal, this host will be chosen for synchronization among a set of
- correctly operating hosts. See the link:prefer.html[Mitigation Rules
- and the `prefer` Keyword] page for further information.
- `mode` 'int';;
- Specifies a mode number which is interpreted in a device-specific
- fashion. For instance, it selects a dialing protocol in the ACTS
- driver and a device subtype in the `parse` drivers.
- `minpoll` 'int';;
- `maxpoll` 'int';;
- These options specify the minimum and maximum polling interval for
- reference clock messages in log~2~ seconds. For most directly
- connected reference clocks, both `minpoll` and `maxpoll` default to
- 6 (64 s). For modem reference clocks, `minpoll` is ordinarily set to
- 10 (about 17 m) and `maxpoll` to 15 (about 9 h). The allowable range
- is 4 (16 s) to 17 (36 h) inclusive.
-`fudge 127.127.`'t'.'u' [`time1` 'sec'] [`time2` 'sec'] [`stratum` 'int'] [`refid` 'string'] [`flag1 0|1`] [`flag2 0|1`] [`flag3 0|1`] [`flag4 0|1`]::
- This command can be used to configure reference clocks in special
- ways. It must immediately follow the `server` command which configures
- the driver. Note that the same capability is possible at run time
- using the link:ntpq.html[`{ntpq}`] program. The options are interpreted as follows:
- `time1` 'sec';;
- Specifies a constant to be added to the time offset produced by the
- driver, a fixed-point decimal number in seconds. This is used as a
- calibration constant to adjust the nominal time offset of a
- particular clock to agree with an external standard, such as a
- precision PPS signal. It also provides a way to correct a systematic
- error or bias due to serial port or operating system latencies,
- different cable lengths or receiver internal delay. The specified
- offset is in addition to the propagation delay provided by other
- means, such as internal DIPswitches. Where a calibration for an
- individual system and driver is available, an approximate correction
- is noted in the driver documentation pages.
- Note: in order to 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 the link:miscopt.html[Miscellaneous Options] page and
- operates as described in the link:refclock.html[Reference Clock
- Support] page.
- `time2` 'secs';;
- Specifies a fixed-point decimal number in seconds, which is
- interpreted in a driver-dependent way. See the descriptions of
- specific drivers in the link:refclock.html[Reference Clock Support]
- page.
- `stratum` 'int';;
- Specifies the stratum number assigned to the driver in the range 0
- to 15, inclusive. This number overrides the default stratum number
- ordinarily assigned by the driver itself, usually zero.
- `refid` 'string';;
- 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.
- `flag1 flag2 flag3 flag4`;;
- 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 `flag4`
- is used to enable recording monitoring data to the `clockstats` file
- configured with the `filegen` command. Additional information on the
- `filegen` command is on the link:monopt.html[Monitoring Options]
- page.
+include::includes/clock-options.txt[]
'''''
diff --git a/docs/includes/assoc-commands.txt b/docs/includes/assoc-commands.txt
index 9286e39..956b8be 100644
--- a/docs/includes/assoc-commands.txt
+++ b/docs/includes/assoc-commands.txt
@@ -1,6 +1,6 @@
// Syntax and usage of association commands. This is included
// twice, one in generating the Web documentation tree and one when
-// generating the munual page describing the daemon config file.
+// generating the manual page describing the daemon config file.
`pool` _address_ [`burst`] [`iburst`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_] [`preempt`]::
`server` _address_ [`key` _key_ | `autokey`] [`burst`] [`iburst`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_]::
diff --git a/docs/includes/assoc-options.txt b/docs/includes/assoc-options.txt
index a58a048..f4fcc40 100644
--- a/docs/includes/assoc-options.txt
+++ b/docs/includes/assoc-options.txt
@@ -1,7 +1,7 @@
// Association options - included twice.
//
// Note, some of these options are described with special refclock
-// semantics on the ntp.conf manual page.
+// semantics in includes/clock-options.txt.
`autokey`::
All packets sent to and received from the server or peer are to
diff --git a/docs/includes/clock-options.txt b/docs/includes/clock-options.txt
new file mode 100644
index 0000000..be5c96e
--- /dev/null
+++ b/docs/includes/clock-options.txt
@@ -0,0 +1,80 @@
+// Options for refclocks. Included twice.
+//
+// This can't be merged with the master description of association
+// options 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
+ ways. The options are interpreted as follows:
+
+ `prefer`;;
+ Marks the reference clock as preferred. All other things being
+ equal, this host will be chosen for synchronization among a set of
+ correctly operating hosts. See the "Mitigation Rules and the prefer
+ Keyword" page (available as part of the HTML documentation provided
+ in `/usr/share/doc/{ntp}`) for further information.
+ `mode` _int_;;
+ Specifies a mode number which is interpreted in a device-specific
+ fashion. For instance, it selects a dialing protocol in the ACTS
+ driver and a device subtype in the parse drivers.
+ `minpoll` _int_; `maxpoll` _int_;;
+ These options specify the minimum and maximum polling interval for
+ reference clock messages, as a power of 2 in seconds. For most
+ directly connected reference clocks, both _minpoll_ and _maxpoll_
+ default to 6 (64 sec). For modem reference clocks, _minpoll_ defaults
+ to 10 (17.1 min) and _maxpoll_ defaults to 14 (4.5 hours). The allowable
+ range is 4 (16 sec) to 17 (36.4 hours) inclusive.
+
+`fudge` _127.127.t_._u_ [`time1` _sec_] [`time2` _sec_] [`stratum` _int_] [`refid` _string_] [`mode` _int_] [`flag1` `0` | `1`] [`flag2` `0` | `1`] [`flag3` `0` | `1`] [`flag4` `0` | `1`]::
+ This command can be used to configure reference clocks in special
+ ways. It must immediately follow the `server` command which configures
+ the driver. Note that the same capability is possible at run time
+ using the {ntpqman} program. The options are interpreted as
+ follows:
+
+ `time1` _sec_;;
+ Specifies a constant to be added to the time offset produced by the
+ driver, a fixed-point decimal number in seconds. This is used as a
+ calibration constant to adjust the nominal time offset of a
+ particular clock to agree with an external standard, such as a
+ precision PPS signal. It also provides a way to correct a systematic
+ error or bias due to serial port or operating system latencies,
+ different cable lengths or receiver internal delay. The specified
+ offset is in addition to the propagation delay provided by other
+ means, such as internal DIPswitches. Where a calibration for an
+ individual system and driver is available, an approximate correction
+ is noted in the driver documentation pages. Note: in order to
+ 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
+ "Reference Clock Drivers" page.
+ `time2` _secs_;;
+ Specifies a fixed-point decimal number in seconds, which is
+ interpreted in a driver-dependent way. See the descriptions of
+ specific drivers in the "Reference Clock Drivers" page.
+ `stratum` _int_;;
+ Specifies the stratum number assigned to the driver, an integer
+ between 0 and 15. This number overrides the default stratum number
+ ordinarily assigned by the driver itself, usually zero.
+ `refid` _string_;;
+ 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.
+ `mode` _int_;;
+ Specifies a mode number which is interpreted in a device-specific
+ fashion. For instance, it selects a dialing protocol in the ACTS
+ driver and a device subtype in the parse drivers.
+ `flag1` `0` | `1`; `flag2` `0` | `1`; `flag3` `0` | `1`; `flag4` `0` | `1`;;
+ 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 clock driver. However, by convention
+ `flag4` is used to enable recording monitoring data to the
+ _clockstats_ file configured with the _filegen_ command. Further
+ information on the _filegen_ command can be found in "Monitoring
+ Options".
+
+//end
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index 374ac36..71753a9 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -235,84 +235,7 @@ 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
- ways. The options are interpreted as follows:
-
- `prefer`;;
- Marks the reference clock as preferred. All other things being
- equal, this host will be chosen for synchronization among a set of
- correctly operating hosts. See the "Mitigation Rules and the prefer
- Keyword" page (available as part of the HTML documentation provided
- in `/usr/share/doc/{ntp}`) for further information.
- `mode` _int_;;
- Specifies a mode number which is interpreted in a device-specific
- fashion. For instance, it selects a dialing protocol in the ACTS
- driver and a device subtype in the parse drivers.
- `minpoll` _int_; `maxpoll` _int_;;
- These options specify the minimum and maximum polling interval for
- reference clock messages, as a power of 2 in seconds For most
- directly connected reference clocks, both _minpoll_ and _maxpoll_
- default to 6 (64 s). For modem reference clocks, _minpoll_ defaults
- to 10 (17.1 m) and _maxpoll_ defaults to 14 (4.5 h). The allowable
- range is 4 (16 s) to 17 (36.4 h) inclusive.
-
-`fudge` _127.127.t_._u_ [`time1` _sec_] [`time2` _sec_] [`stratum` _int_] [`refid` _string_] [`mode` _int_] [`flag1` `0` | `1`] [`flag2` `0` | `1`] [`flag3` `0` | `1`] [`flag4` `0` | `1`]::
- This command can be used to configure reference clocks in special
- ways. It must immediately follow the `server` command which configures
- the driver. Note that the same capability is possible at run time
- using the {ntpqman} program. The options are interpreted as
- follows:
-
- `time1` _sec_;;
- Specifies a constant to be added to the time offset produced by the
- driver, a fixed-point decimal number in seconds. This is used as a
- calibration constant to adjust the nominal time offset of a
- particular clock to agree with an external standard, such as a
- precision PPS signal. It also provides a way to correct a systematic
- error or bias due to serial port or operating system latencies,
- different cable lengths or receiver internal delay. The specified
- offset is in addition to the propagation delay provided by other
- means, such as internal DIPswitches. Where a calibration for an
- individual system and driver is available, an approximate correction
- is noted in the driver documentation pages. Note: in order to
- 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
- "Reference Clock Drivers" page (available as part of the HTML
- documentation provided in `/usr/share/doc/{ntp}`).
- `time2` _secs_;;
- Specifies a fixed-point decimal number in seconds, which is
- interpreted in a driver-dependent way. See the descriptions of
- specific drivers in the "Reference Clock Drivers" page (available as
- part of the HTML documentation provided in `/usr/share/doc/{ntp}`).
- `stratum` _int_;;
- Specifies the stratum number assigned to the driver, an integer
- between 0 and 15. This number overrides the default stratum number
- ordinarily assigned by the driver itself, usually zero.
- `refid` _string_;;
- 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.
- `mode` _int_;;
- Specifies a mode number which is interpreted in a device-specific
- fashion. For instance, it selects a dialing protocol in the ACTS
- driver and a device subtype in the parse drivers.
- `flag1` `0` | `1`; `flag2` `0` | `1`; `flag3` `0` | `1`; `flag4` `0` | `1`;;
- 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 clock driver. However, by convention
- `flag4` is used to enable recording monitoring data to the
- _clockstats_ file configured with the _filegen_ command. Further
- information on the _filegen_ command can be found in "Monitoring
- Options".
+include::../docs/includes/clock-options.txt[]
== Miscellaneous Options ==
More information about the vc
mailing list