[ntpsec commit] Another docunentation-refactoring step, access commands this time.
Eric S. Raymond
esr at ntpsec.org
Mon Oct 12 00:08:44 UTC 2015
Module: ntpsec
Branch: master
Commit: 8f4582f9d4e29fd2351e3a2af790e6f1c93110b5
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=8f4582f9d4e29fd2351e3a2af790e6f1c93110b5
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Sun Oct 11 20:08:01 2015 -0400
Another docunentation-refactoring step, access commands this time.
---
docs/access-commands.txt | 117 +++++++++++++++++++++++++++++++++++++++++++++
docs/accopt.txt | 121 +----------------------------------------------
ntpd/ntp.conf.txt | 91 +----------------------------------
3 files changed, 119 insertions(+), 210 deletions(-)
diff --git a/docs/access-commands.txt b/docs/access-commands.txt
new file mode 100644
index 0000000..5725f9e
--- /dev/null
+++ b/docs/access-commands.txt
@@ -0,0 +1,117 @@
+// Access control commands. Is included twice.
+
+`discard` [`average` _avg_] [`minimum` _min_] [`monitor` _prob_]::
+ Set the parameters of the `limited` facility which protects the server
+ from client abuse. The `average` subcommand specifies the minimum
+ average packet spacing, while the `minimum` subcommand specifies the
+ minimum packet spacing. Packets that violate these minima are
+ discarded and a kiss-o'-death packet returned if enabled. The default
+ minimum average and minimum are 5 and 2, respectively. The monitor
+ subcommand specifies the probability of discard for packets that
+ overflow the rate-control window. The options are:
+ `average` 'avg';;
+ Specify the minimum average interpacket spacing (minimum average
+ headway time) in log~2~ s with default 3.
+ `minimum` 'min';;
+ Specify the minimum interpacket spacing (guard time) in seconds with
+ default 2.
+ `monitor`;;
+ Specify the probability of being recorded for packets that overflow
+ the MRU list size limit set by `mru maxmem` or `mru maxdepth`. This
+ is a performance optimization for servers with aggregate arrivals of
+ 1000 packets per second or more.
+
+`restrict` _address_ [`mask` _mask_] [`flag` `...`]::
+ The _address_ argument expressed in dotted-quad form is the address of
+ a host or network. Alternatively, the _address_ argument can be a
+ valid host DNS name. The _mask_ argument expressed in dotted-quad form
+ defaults to `255.255.255.255`, meaning that the _address_ is treated
+ as the address of an individual host. A default entry (address
+ `0.0.0.0`, mask `0.0.0.0`) is always included and is always the first
+ entry in the list. Note that text string _default_, with no mask
+ option, may be used to indicate the default entry. In the current
+ implementation, _flag_ always restricts access, i.e., an entry with no
+ flags indicates that free access to the server is to be given. The
+ flags are not orthogonal, in that more restrictive flags will often
+ make less restrictive ones redundant. The flags can generally be
+ classed into two categories, those which restrict time service and
+ those which restrict informational queries and attempts to do run-time
+ reconfiguration of the server. One or more of the following flags may
+ be specified:
++
+--
+ `flake`;;
+ Discard received NTP packets with probability 0.1; that is, on
+ average drop one packet in ten. This is for testing and amusement.
+ The name comes from Bob Braden's _flakeway_, which once did a
+ similar thing for early Internet testing.
+ `ignore`;;
+ Deny packets of all kinds, including {ntpqman} queries.
+ `kod`;;
+ If this flag is set when an access violation occurs, a kiss-o'-death
+ (KoD) packet is sent. KoD packets are rate limited to no more than
+ one per second. If another KoD packet occurs within one second after
+ the last one, the packet is dropped.
+ `limited`;;
+ Deny service if the packet spacing violates the lower limits
+ specified in the discard command. A history of clients is kept using
+ the monitoring capability of {ntpdman}. Thus, monitoring is
+ always active as long as there is a restriction entry with
+ the limited flag.
+ `lowpriotrap`;;
+ Declare traps set by matching hosts to be low priority. The number
+ of traps a server can maintain is limited (the current limit is 3).
+ Traps are usually assigned on a first come, first served basis, with
+ later trap requestors being denied service. This flag modifies the
+ assignment algorithm by allowing low priority traps to be overridden
+ by later requests for normal priority traps.
+// `mssntp`;;
+// Enable Microsoft Windows MS-SNTP authentication using Active
+// Directory services. *Note: Potential users should be aware that
+// these services involve a TCP connection to another process that
+// could potentially block, denying services to other users. Therefore,
+// this flag should be used only for a dedicated server with no clients
+// other than MS-SNTP.*
+ `nomodify`;;
+ Deny {ntpqman} queries which attempt
+ to modify the state of the server (i.e., run time reconfiguration).
+ Queries which return information are permitted.
+ `noquery`;;
+ Deny {ntpqman} queries. Time service is not affected.
+ `nopeer`;;
+ Deny packets which would result in mobilizing a new association.
+ This includes broadcast and symmetric active packets when a
+ configured association does not exist. It also includes _pool_
+ associations, so if you want to use servers from a `pool` directive
+ and also want to use `nopeer` by default, you'll want a `restrict
+ source ...` line as well that does
+ `not`;;
+ include the `nopeer` directive.
+ `noserve`;;
+ Deny all packets except {ntpqman} and queries.
+ `notrap`;;
+ Decline to provide mode 6 control message trap service to matching
+ hosts. The trap service is a subsystem of the {ntpq} control message
+ protocol which is intended for use by remote event logging programs.
+ `notrust`;;
+ Deny service unless the packet is cryptographically authenticated.
+ `ntpport`;;
+ This is actually a match algorithm modifier, rather than a
+ restriction flag. Its presence causes the restriction entry to be
+ matched only if the source port in the packet is the standard NTP
+ UDP port (123). Both `ntpport` and `non-ntpport` may be specified.
+ The `ntpport` is considered more specific and is sorted later in the
+ list.
+ `version`;;
+ Deny packets that do not match the current NTP version.
+--
++
+Default restriction list entries with the flags ignore, interface,
+ntpport, for each of the local host's interface addresses are inserted
+into the table at startup to prevent the server from attempting to
+synchronize to its own time. A default entry is also always present,
+though if it is otherwise unconfigured; no flags are associated with
+the default entry (i.e., everything besides your own NTP server is
+unrestricted).
+
+// end
diff --git a/docs/accopt.txt b/docs/accopt.txt
index 7526b92..39ec50f 100644
--- a/docs/accopt.txt
+++ b/docs/accopt.txt
@@ -21,126 +21,7 @@ include::includes/accopt.txt[]
Unless noted otherwise, further information about these ccommands is on
the link:accopt.html[Access Control Support] page.
-`discard` [ `average` 'avg' ][ `minimum` 'min' ] [ `monitor` 'prob' ]::
- Set the parameters of the rate control facility which protects the
- server from client abuse. If the `limited` flag is present in the ACL,
- packets that violate these limits are discarded. If, in addition, the
- `kod` flag is present, a kiss-o'-death packet is returned. See the
- link:rate.html[Rate Management] page for further information. The
- options are:
- `average` 'avg';;
- Specify the minimum average interpacket spacing (minimum average
- headway time) in log~2~ s with default 3.
- `minimum` 'min';;
- Specify the minimum interpacket spacing (guard time) in seconds with
- default 2.
- `monitor`;;
- Specify the probability of being recorded for packets that overflow
- the MRU list size limit set by `mru maxmem` or `mru maxdepth`. This
- is a performance optimization for servers with aggregate arrivals of
- 1000 packets per second or more.
-`restrict default` ['flag'][...]
-`restrict source` ['flag'][...]
-`restrict address` [`mask` 'mask'] ['flag'][...]`::
- The `address` argument expressed in dotted-quad form is the address of
- a host or network. Alternatively, the `address` argument can be a
- valid host DNS name. The `mask` argument expressed in IPv4 or IPv6
- numeric address form defaults to all mask bits on, meaning that the
- `address` is treated as the address of an individual host. A default
- entry (address 0.0.0.0, mask 0.0.0.0 for IPv4 and address pass:[::]
- mask pass[::] for
- IPv6) is always the first entry in the list. `restrict default`,
- with no mask option, modifies both IPv4 and IPv6 default entries.
- `restrict source` configures a template restriction automatically
- added at runtime for each association, whether configured, ephemeral,
- or preemptible, and removed when the association is demobilized.
-
- Some flags have the effect to deny service, some have the effect to
- enable service and some are conditioned by other flags. The flags. are
- not orthogonal, in that more restrictive flags will often make less
- restrictive ones redundant. The flags that deny service are classed in
- two categories, those that restrict time service and those that
- restrict informational queries and attempts to do run-time
- reconfiguration of the server. One or more of the following flags may
- be specified:
- `flake`;;
- Discard received NTP packets with probability 0.1; that is, on
- average drop one packet in ten. This is for testing and amusement.
- The name comes from Bob Braden's _flakeway_, which once did a
- similar thing for early Internet testing.
- `ignore`;;
- Deny packets of all kinds, including `{ntpq}` queries.
- `kod`;;
- Send a kiss-o'-death (KoD) packet if the `limited` flag is present
- and a packet violates the rate limits established by the `discard`
- command. KoD packets are themselves rate limited for each source
- address separately. If the `kod` flag is used in a restriction which
- does not have the `limited` flag, no KoD responses will result.
- `limited`;;
- Deny time service if the packet violates the rate limits established
- by the `discard` command. This does not apply to `{ntpq}`
- queries.
- `lowpriotrap`;;
- Declare traps set by matching hosts to be low priority. The number
- of traps a server can maintain is limited (the current limit is 3).
- Traps are usually assigned on a first come, first served basis, with
- later trap requestors being denied service. This flag modifies the
- assignment algorithm by allowing low priority traps to be overridden
- by later requests for normal priority traps.
- `mssntp`;;
- Enable Microsoft Windows MS-SNTP authentication using Active
- Directory services. *Note: Potential users should be aware that
- these services involve a TCP connection to another process that
- could potentially block, denying services to other users. Therefore,
- this flag should be used only for a dedicated server with no clients
- other than MS-SNTP.*
- `nomodify`;;
- Deny `{ntpq}` queries which attempt to modify the state of
- the server (i.e., run time reconfiguration). Queries which return
- information are permitted.
- `noquery`;;
- Deny `{ntpq}` queries. Time service is not affected.
- `nopeer`;;
- Deny packets that might mobilize an association unless
- authenticated. This includes broadcast, symmetric-active and
- manycast server packets when a configured association does not
- exist. It also includes `pool` associations, so if you want to use
- servers from a `pool` directive and also want to use `nopeer` by
- default, you'll want a `"restrict source ..."` line as well that
- does _not_ include the `nopeer` directive. Note that this flag does
- not apply to packets that do not attempt to mobilize an association.
- `noserve`;;
- Deny all packets except `{ntpq}` queries.
- `notrap`;;
- Decline to provide mode 6 control message trap service to matching
- hosts. The trap service is a subsystem of the `{ntpq}` control
- message protocol which is intended for use by remote event logging
- programs.
- `notrust`;;
- Deny packets that are not cryptographically authenticated. Note
- carefully how this flag interacts with the `auth` option of the
- `enable` and `disable` commands. If `auth` is enabled, which is the
- default, authentication is required for all packets that might
- mobilize an association. If `auth` is disabled, but the `notrust`
- flag is not present, an association can be mobilized whether or not
- authenticated. If `auth` is disabled, but the `notrust` flag is
- present, authentication is required only for the specified
- address/mask range.
- `ntpport`;;
- This is actually a match algorithm modifier, rather than a
- restriction flag. Its presence causes the restriction entry to be
- matched only if the source port in the packet is the standard NTP
- UDP port (123). A restrict line containing `ntpport` is considered
- more specific than one with the same address and mask, but lacking
- `ntpport`.
- `version`;;
- Deny packets that do not match the current NTP version.
- Default restriction list entries with the flags `ignore, ntpport`, for
- each of the local host's interface addresses are inserted into the
- table at startup to prevent the server from attempting to synchronize
- to its own time. A default entry is also always present, though if it
- is otherwise unconfigured; no flags are associated with the default
- entry (i.e., everything besides your own NTP server is unrestricted).
+include::../docs/access-commands.txt[]
'''''
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index 347143c..32a6110 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -172,96 +172,7 @@ server operator cooperates.
== Access Control Commands ==
-`discard` [`average` _avg_] [`minimum` _min_] [`monitor` _prob_]::
- Set the parameters of the `limited` facility which protects the server
- from client abuse. The `average` subcommand specifies the minimum
- average packet spacing, while the `minimum` subcommand specifies the
- minimum packet spacing. Packets that violate these minima are
- discarded and a kiss-o'-death packet returned if enabled. The default
- minimum average and minimum are 5 and 2, respectively. The monitor
- subcommand specifies the probability of discard for packets that
- overflow the rate-control window.
-
-`restrict` _address_ [`mask` _mask_] [`flag` `...`]::
- The _address_ argument expressed in dotted-quad form is the address of
- a host or network. Alternatively, the _address_ argument can be a
- valid host DNS name. The _mask_ argument expressed in dotted-quad form
- defaults to `255.255.255.255`, meaning that the _address_ is treated
- as the address of an individual host. A default entry (address
- `0.0.0.0`, mask `0.0.0.0`) is always included and is always the first
- entry in the list. Note that text string _default_, with no mask
- option, may be used to indicate the default entry. In the current
- implementation, _flag_ always restricts access, i.e., an entry with no
- flags indicates that free access to the server is to be given. The
- flags are not orthogonal, in that more restrictive flags will often
- make less restrictive ones redundant. The flags can generally be
- classed into two categories, those which restrict time service and
- those which restrict informational queries and attempts to do run-time
- reconfiguration of the server. One or more of the following flags may
- be specified:
-+
---
- `ignore`;;
- Deny packets of all kinds, including {ntpqman} queries.
- `kod`;;
- If this flag is set when an access violation occurs, a kiss-o'-death
- (KoD) packet is sent. KoD packets are rate limited to no more than
- one per second. If another KoD packet occurs within one second after
- the last one, the packet is dropped.
- `limited`;;
- Deny service if the packet spacing violates the lower limits
- specified in the discard command. A history of clients is kept using
- the monitoring capability of {ntpdman}. Thus, monitoring is
- always active as long as there is a restriction entry with
- the limited flag.
- `lowpriotrap`;;
- Declare traps set by matching hosts to be low priority. The number
- of traps a server can maintain is limited (the current limit is 3).
- Traps are usually assigned on a first come, first served basis, with
- later trap requestors being denied service. This flag modifies the
- assignment algorithm by allowing low priority traps to be overridden
- by later requests for normal priority traps.
- `nomodify`;;
- Deny {ntpqman} queries which attempt
- to modify the state of the server (i.e., run time reconfiguration).
- Queries which return information are permitted.
- `noquery`;;
- Deny {ntpqman} queries. Time service is not affected.
- `nopeer`;;
- Deny packets which would result in mobilizing a new association.
- This includes broadcast and symmetric active packets when a
- configured association does not exist. It also includes _pool_
- associations, so if you want to use servers from a `pool` directive
- and also want to use `nopeer` by default, you'll want a `restrict
- source ...` line as well that does
- `not`;;
- include the `nopeer` directive.
- `noserve`;;
- Deny all packets except {ntpqman} and queries.
- `notrap`;;
- Decline to provide mode 6 control message trap service to matching
- hosts. The trap service is a subsystem of the {ntpq} control message
- protocol which is intended for use by remote event logging programs.
- `notrust`;;
- Deny service unless the packet is cryptographically authenticated.
- `ntpport`;;
- This is actually a match algorithm modifier, rather than a
- restriction flag. Its presence causes the restriction entry to be
- matched only if the source port in the packet is the standard NTP
- UDP port (123). Both `ntpport` and `non-ntpport` may be specified.
- The `ntpport` is considered more specific and is sorted later in the
- list.
- `version`;;
- Deny packets that do not match the current NTP version.
---
-+
-Default restriction list entries with the flags ignore, interface,
-ntpport, for each of the local host's interface addresses are inserted
-into the table at startup to prevent the server from attempting to
-synchronize to its own time. A default entry is also always present,
-though if it is otherwise unconfigured; no flags are associated with
-the default entry (i.e., everything besides your own NTP server is
-unrestricted).
+include::../docs/access-commands.txt[]
== Automatic NTP Configuration Options ==
More information about the vc
mailing list