[ntpsec commit] Another step towards propervfactoring of the configuration documentation.
Eric S. Raymond
esr at ntpsec.org
Sun Oct 11 00:57:15 UTC 2015
Module: ntpsec
Branch: master
Commit: 06f9489bf96f0530e7c49c8922d1c7b39489deac
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=06f9489bf96f0530e7c49c8922d1c7b39489deac
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Sat Oct 10 20:11:53 2015 -0400
Another step towards propervfactoring of the configuration documentation.
---
docs/assoc-commands.txt | 79 +++++++++++++++++++++++++++++++++++++++++++
docs/assoc-options.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
docs/confopt.txt | 77 +-----------------------------------------
ntpd/ntp.conf.txt | 74 +---------------------------------------
4 files changed, 171 insertions(+), 149 deletions(-)
diff --git a/docs/assoc-commands.txt b/docs/assoc-commands.txt
new file mode 100644
index 0000000..9286e39
--- /dev/null
+++ b/docs/assoc-commands.txt
@@ -0,0 +1,79 @@
+// 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.
+
+`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_]::
+`peer` _address_ [`key` _key_ | `autokey`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_] [`xleave`]::
+`broadcast` _address_ [`key` _key_ | `autokey`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`ttl` _ttl_] [`xleave`]::
+`manycastclient` _address_ [`key` _key_ | `autokey`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_] [`ttl` _ttl_] [`preempt`]::
+`unpeer` ['address' | 'associd']::
+ These six commands specify the time server name or address to be used
+ and the mode in which to operate. The _address_ can be either a DNS
+ name or an IP address in dotted-quad notation.
+
+`pool`::
+ For type s addresses, this command mobilizes a persistent client mode
+ association with a number of remote servers. In this mode the local
+ clock can synchronized to the remote server, but the remote server can
+ never be synchronized to the local clock.
+
+`server`::
+ For type s and r addresses, this command mobilizes a persistent client
+ mode association with the specified remote server or local radio
+ clock. In this mode the local clock can synchronized to the remote
+ server, but the remote server can never be synchronized to the local
+ clock. This command should _not_ be used for type b or m addresses.
+
+`peer`::
+ For type s addresses (only), this command mobilizes a persistent
+ symmetric-active mode association with the specified remote peer. In
+ this mode the local clock can be synchronized to the remote peer or
+ the remote peer can be synchronized to the local clock. This is useful
+ in a network of servers where, depending on various failure scenarios,
+ either the local or remote peer may be the better source of time. This
+ command should NOT be used for type b, m or r addresses.
+
+`broadcast`::
+ For type b and m addresses (only), this command mobilizes a persistent
+ broadcast mode association. Multiple commands can be used to specify
+ multiple local broadcast interfaces (subnets) and/or multiple
+ multicast groups. Note that local broadcast messages go only to the
+ interface associated with the subnet specified, but multicast messages
+ go to all interfaces. In broadcast mode the local server sends
+ periodic broadcast messages to a client population at the _address_
+ specified, which is usually the broadcast address on (one of) the
+ local network(s) or a multicast address assigned to NTP. The IANA has
+ assigned the multicast group address IPv4 224.0.1.1 and IPv6 ff05::101
+ (site local) exclusively to NTP, but other nonconflicting addresses
+ can be used to contain the messages within administrative boundaries.
+ Ordinarily, this specification applies only to the local server
+ operating as a sender; for operation as a broadcast client, see the
+ _broadcastclient_ or _multicastclient_ commands below.
+
+`manycastclient`::
+ For type m addresses (only), this command mobilizes a manycast client
+ mode association for the multicast address specified. In this case a
+ specific address must be supplied which matches the address used on
+ the _manycastserver_ command for the designated manycast servers. The
+ NTP multicast address 224.0.1.1 assigned by the IANA should NOT be
+ used, unless specific means are taken to avoid spraying large areas of
+ the Internet with these messages and causing a possibly massive
+ implosion of replies at the sender. The _manycastserver_ command
+ specifies that the local server is to operate in client mode with the
+ remote servers that are discovered as the result of
+ broadcast/multicast messages. The client broadcasts a request message
+ to the group address associated with the specified _address_ and
+ specifically enabled servers respond to these messages. The client
+ selects the servers providing the best time and continues as with the
+ _server_ command. The remaining servers are discarded as if never
+ heard.
+
+`unpeer`::
+ This command removes a previously configured association. An address
+ or association ID can be used to identify the association. Either an
+ IP address or DNS name can be used. This command is most useful when
+ supplied via `{ntpq}` runtime configuration commands `:config` and
+ `config-from-file`.
+
+// end
diff --git a/docs/assoc-options.txt b/docs/assoc-options.txt
new file mode 100644
index 0000000..c1f8273
--- /dev/null
+++ b/docs/assoc-options.txt
@@ -0,0 +1,90 @@
+// Association options - included twice.
+
+`autokey`::
+ All packets sent to and received from the server or peer are to
+ include authentication fields encrypted using the autokey scheme
+ described on the "Authentication Options" page.
+
+`burst`::
+ when the server is reachable, send a burst of eight packets instead of
+ the usual one. The packet spacing is normally 2 s; however, the
+ spacing between the first and second packets can be changed with the
+ calldelay command to allow additional time for a modem or ISDN call to
+ complete. This is designed to improve timekeeping quality with the
+ `server` command and s addresses.
+
+`iburst`::
+ When the server is unreachable, send a burst of eight packets instead
+ of the usual one. The packet spacing is normally 2 s; however, the
+ spacing between the first two packets can be changed with the
+ calldelay command to allow additional time for a modem or ISDN call to
+ complete. This is designed to speed the initial synchronization
+ acquisition with the `server` command and s addresses and when
+ {ntpdman} is started with the `-q` option.
+
+// Uncomment this when and if autokey works.
+//`ident` 'group'::
+// Specify the group name for the association. See the "Autokey
+// Public-Key Authentication" page for further information.
+
+`key` _key_::
+ All packets sent to and received from the server or peer are to
+ include authentication fields encrypted using the specified _key_
+ identifier with values from 1 to 65534, inclusive. The default is to
+ include no encryption field.
+
+`minpoll` _minpoll_::
+`maxpoll` _maxpoll_::
+ These options specify the minimum and maximum poll intervals for NTP
+ messages, as a power of 2 in seconds. The maximum poll interval
+ defaults to 10 (1,024 s), but can be increased by the _maxpoll_ option
+ to an upper limit of 17 (36.4 h). The minimum poll interval defaults
+ to 6 (64 s), but can be decreased by the _minpoll_ option to a lower
+ limit of 4 (16 s).
+
+`mode` 'option'::
+ Pass the `option` to a reference clock driver, where `option` is an
+ integer in the range from 0 to 255, inclusive. This option is valid
+ only with type r addresses.
+
+`noselect`::
+ Marks the server as unused, except for display purposes. The server is
+ discarded by the selection algroithm.
+
+`preempt`::
+ Specifies the association as preemptable rather than the default
+ persistent. This option is ignored with the `broadcast` command and is
+ most useful with the `manycastclient` and `pool` commands.
+
+`prefer`::
+ Marks the server 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
+ for further information.
+
+`ttl` _ttl_::
+ This option is used only with broadcast server and manycast client
+ modes. It specifies the time-to-live _ttl_ to use on broadcast server
+ and multicast server and the maximum _ttl_ for the expanding ring
+ search with manycast client packets. Selection of the proper value,
+ which defaults to 127, is something of a black art and should be
+ coordinated with the network administrator.
+
+`true`::
+ Mark the association to assume truechimer status; that is, always
+ survive the selection and clustering algorithms. This option can be
+ used with any association, but is most useful for reference clocks
+ with large jitter on the serial port and precision pulse-per-second
+ (PPS) signals. Caution: this option defeats the algorithms designed to
+ cast out falsetickers and can allow these sources to set the system
+ clock. This option is valid only with the `server` and `peer` commands.
+
+`version` _version_::
+ Specifies the version number to be used for outgoing NTP packets.
+ Versions 1-4 are the choices, with version 4 the default.
+
+`xleave`::
+ Operate in interleaved mode (symmetric and broadcast modes only).
+ Further information is on the "NTP Interleaved Modes" page.
+
+// end
diff --git a/docs/confopt.txt b/docs/confopt.txt
index b29668a..699f438 100644
--- a/docs/confopt.txt
+++ b/docs/confopt.txt
@@ -66,82 +66,7 @@ include::assoc-commands.txt[]
[[option]]
== Server Command Options ==
-`autokey`::
- Send and receive packets authenticated by the Autokey scheme described
- on the link:autokey.html[Autokey Public Key Authentication] page. This
- option is mutually exclusive with the `key` option.
-`burst`::
- When the server is reachable, send a burst of packets instead of the
- usual one. This option is valid only with the `server` command and
- type s addresses. It is a recommended option when the `maxpoll` option
- is greater than 10 (1024 s). Additional information about this option
- is on the link:poll.html[Poll Program] page.
-`iburst`::
- When the server is unreachable, send a burst of packets instead of the
- usual one. This option is valid only with the `server` command and
- type `s` addresses. It is a recommended option with this command.
- Additional information about this option is on the link:poll.html[Poll
- Program] page.
-`ident` 'group'::
- Specify the group name for the association. See the
- link:autokey.html[Autokey Public-Key Authentication] page for further
- information.
-`key` 'key'::
- Send and receive packets authenticated by the symmetric key scheme
- described in the link:authentic.html[Authentication Support] page. The
- 'key' specifies the key identifier with values from 1 to 65534,
- inclusive. This option is mutually exclusive with the `autokey`
- option.
-`minpoll` 'minpoll'::
-`maxpoll` 'maxpoll'::
- 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 `maxpoll` option
- to an upper limit of 17 (36 hr). The minimum poll interval defaults to
- 6 (64 s), but can be decreased by the `minpoll` option to a lower
- limit of 3 (8 s). Additional information about this option is on the
- link:poll.html[Poll Program] page.
-`mode` 'option'::
- Pass the `option` to a reference clock driver, where `option` is an
- integer in the range from 0 to 255, inclusive. This option is valid
- only with type r addresses.
-`noselect`::
- Marks the server or peer to be ignored by the selection algorithm as
- unreachable, but visible to the monitoring program. This option is
- valid only with the `server` and `peer` commands.
-`preempt`::
- Specifies the association as preemptable rather than the default
- persistent. This option is ignored with the `broadcast` command and is
- most useful with the `manycastclient` and `pool` commands.
-`prefer`::
- Mark the server 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. This option is valid only with
- the `server` and `peer` commands.
-`true`::
- Mark the association to assume truechimer status; that is, always
- survive the selection and clustering algorithms. This option can be
- used with any association, but is most useful for reference clocks
- with large jitter on the serial port and precision pulse-per-second
- (PPS) signals. Caution: this option defeats the algorithms designed to
- cast out falsetickers and can allow these sources to set the system
- clock. This option is valid only with the `server` and `peer`
- commands.
-`ttl` 'ttl'::
- This option specifies the time-to-live 'ttl' for the `broadcast`
- command and the maximum 'ttl' for the expanding ring search used by
- the `manycastclient` command. Selection of the proper value, which
- defaults to 127, is something of a black art and should be coordinated
- with the network administrator. This option is invalid with type r
- addresses.
-`version` 'version'::
- Specifies the version number to be used for outgoing NTP packets.
- Versions 1-4 are the choices, with version 4 the default.
-`xleave`::
- Operate in interleaved mode (symmetric and broadcast modes only).
- Further information is on the link:xleave.html[NTP Interleaved Modes]
- page.
+include::assoc-options.txt[]
[[aux]]
== Auxiliary Commands ==
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index bb25a7b..402b9d6 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -86,79 +86,7 @@ include::../docs/assoc-commands.txt[]
=== Association Options ===
-`autokey`::
- All packets sent to and received from the server or peer are to
- include authentication fields encrypted using the autokey scheme
- described in 'Authentication Options'.
-
-`burst`::
- when the server is reachable, send a burst of eight packets instead of
- the usual one. The packet spacing is normally 2 s; however, the
- spacing between the first and second packets can be changed with the
- calldelay command to allow additional time for a modem or ISDN call to
- complete. This is designed to improve timekeeping quality with the
- `server` command and s addresses.
-
-`iburst`::
- When the server is unreachable, send a burst of eight packets instead
- of the usual one. The packet spacing is normally 2 s; however, the
- spacing between the first two packets can be changed with the
- calldelay command to allow additional time for a modem or ISDN call to
- complete. This is designed to speed the initial synchronization
- acquisition with the `server` command and s addresses and when
- {ntpdman} is started with the `-q` option.
-
-// Uncomment this when and if autokey works.
-//`ident` 'group'::
-// Specify the group name for the association. See the "Autokey
-// Public-Key Authentication" page for further information.
-
-`key` _key_::
- All packets sent to and received from the server or peer are to
- include authentication fields encrypted using the specified _key_
- identifier with values from 1 to 65534, inclusive. The default is to
- include no encryption field.
-
-`minpoll` _minpoll_::
-`maxpoll` _maxpoll_::
- These options specify the minimum and maximum poll intervals for NTP
- messages, as a power of 2 in seconds. The maximum poll interval
- defaults to 10 (1,024 s), but can be increased by the _maxpoll_ option
- to an upper limit of 17 (36.4 h). The minimum poll interval defaults
- to 6 (64 s), but can be decreased by the _minpoll_ option to a lower
- limit of 4 (16 s).
-
-`noselect`::
- Marks the server as unused, except for display purposes. The server is
- discarded by the selection algroithm.
-
-`preempt`::
- Specifies the association as preemptable rather than the default
- persistent. This option is ignored with the `broadcast` command and is
- most useful with the `manycastclient` and `pool` commands.
-
-`prefer`::
- Marks the server 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.
-
-`ttl` _ttl_::
- This option is used only with broadcast server and manycast client
- modes. It specifies the time-to-live _ttl_ to use on broadcast server
- and multicast server and the maximum _ttl_ for the expanding ring
- search with manycast client packets. Selection of the proper value,
- which defaults to 127, is something of a black art and should be
- coordinated with the network administrator.
-
-`version` _version_::
- Specifies the version number to be used for outgoing NTP packets.
- Versions 1-4 are the choices, with version 4 the default.
-
-`xleave`::
- Operate in interleaved mode (symmetric and broadcast modes only).
- Further information is on the "NTP Interleaved Modes" page.
+
=== Auxiliary Commands ===
More information about the vc
mailing list