From e697833976025387ea6e413c47bbc2c11be90fc7 Mon Sep 17 00:00:00 2001 From: Miroslav Lichvar Date: Tue, 20 Apr 2021 09:54:52 +0200 Subject: [PATCH] doc: improve description of allow directive Prefer CIDR notation, clarify use of hostnames and order of allow/deny directives, refer to the accheck command. --- doc/chrony.conf.adoc | 64 +++++++++++++++++++++++--------------------- doc/chronyc.adoc | 14 +++------- 2 files changed, 38 insertions(+), 40 deletions(-) diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc index 117b221..1b9e0ab 100644 --- a/doc/chrony.conf.adoc +++ b/doc/chrony.conf.adoc @@ -1356,28 +1356,21 @@ Examples of the use of the directive are as follows: + ---- allow 1.2.3.4 -allow 1.2 +allow 3.4.5.0/24 allow 3.4.5 -allow 6.7.8/22 -allow 6.7.8.9/22 allow 2001:db8::/32 allow 0/0 allow ::/0 allow ---- + -The first directive allows a node with IPv4 address _1.2.3.4_ to be an NTP -client of this computer. -The second directive allows any node with an IPv4 address of the form _1.2.x.y_ -(with _x_ and _y_ arbitrary) to be an NTP client of this computer. Likewise, -the third directive allows any node with an IPv4 address of the form _3.4.5.x_ -to have client NTP access. The fourth and fifth forms allow access from any -node with an IPv4 address of the form _6.7.8.x_, _6.7.9.x_, _6.7.10.x_ or -_6.7.11.x_ (with _x_ arbitrary), i.e. the value 22 is the number of bits -defining the specified subnet. In the fifth form, the final byte is ignored. -The sixth form is used for IPv6 addresses. The seventh and eighth forms allow -access by any IPv4 and IPv6 node respectively. The ninth forms allows access by -any node (IPv4 or IPv6). +The first directive allows access from an IPv4 address. The second directive +allows access from all computers in an IPv4 subnet specified in the CIDR +notation. The third directive specifies the same subnet using a simpler +notation where the prefix length is determined by the number of dots. The +fourth directive specifies an IPv6 subnet. The fifth and sixth directives allow +access from all IPv4 and IPv6 addresses respectively. The seventh directive +allows access from all addresses (both IPv4 or IPv6). + A second form of the directive, *allow all*, has a greater effect, depending on the ordering of directives in the configuration file. To illustrate the effect, @@ -1385,32 +1378,43 @@ consider the two examples: + ---- allow 1.2.3.4 -deny 1.2.3 -allow 1.2 +deny 1.2.3.0/24 +allow 1.2.0.0/16 ---- + and + ---- allow 1.2.3.4 -deny 1.2.3 -allow all 1.2 +deny 1.2.3.0/24 +allow all 1.2.0.0/16 ---- + In the first example, the effect is the same regardless of what order the three -directives are given in. So the _1.2.x.y_ subnet is allowed access, except for -the _1.2.3.x_ subnet, which is denied access, however the host _1.2.3.4_ is -allowed access. +directives are given in. So the _1.2.0.0/16_ subnet is allowed access, except +for the _1.2.3.0/24_ subnet, which is denied access, however the host _1.2.3.4_ +is allowed access. + -In the second example, the *allow all 1.2* directives overrides the effect of -_any_ previous directive relating to a subnet within the specified subnet. -Within a configuration file this capability is probably rather moot; however, -it is of greater use for reconfiguration at run-time via *chronyc* with the -<> command. +In the second example, the *allow all 1.2.0.0/16* directive overrides the +effect of _any_ previous directive relating to a subnet within the specified +subnet. Within a configuration file this capability is probably rather moot; +however, it is of greater use for reconfiguration at run-time via *chronyc* +with the <> command. + -The directive allows a hostname to be specified instead of an IP address, but -the name must be resolvable when *chronyd* is started (i.e. *chronyd* needs -to be started when the network is already up and DNS is working). +The rules are internally represented as a tree of tables with one level per +four bits of the IPv4 or IPv6 address. The order of the *allow* and *deny* +directives matters if they modify the same records of one table, i.e. if one +subnet is included in the other subnet and their prefix lengths are at the same +level. For example, _1.2.3.0/28_ and _1.2.3.0/29_ are in different tables, but +_1.2.3.0/25_ and _1.2.3.0/28_ are in the same table. The configuration can be +verified for individual addresses with the <> +command in *chronyc*. ++ +A hostname can be specified in the directives instead of the IP address, but +the name must be resolvable when *chronyd* is started, i.e. the network is +already up and DNS is working. If the hostname resolves to multiple addresses, +only the first address (in the order returned by the system resolver) will be +allowed or denied. + Note, if the <> directive is used in the configuration file, each of the computers listed in that directive must allow diff --git a/doc/chronyc.adoc b/doc/chronyc.adoc index c442b48..fbfea41 100644 --- a/doc/chronyc.adoc +++ b/doc/chronyc.adoc @@ -1133,11 +1133,8 @@ The effect of the allow command is identical to the The syntax is illustrated in the following examples: + ---- -allow foo.example.net -allow all 1.2 -allow 3.4.5 -allow 6.7.8/22 -allow 6.7.8.9/22 +allow 1.2.3.4 +allow all 3.4.5.0/24 allow 2001:db8:789a::/48 allow 0/0 allow ::/0 @@ -1152,11 +1149,8 @@ The effect of the allow command is identical to the The syntax is illustrated in the following examples: + ---- -deny foo.example.net -deny all 1.2 -deny 3.4.5 -deny 6.7.8/22 -deny 6.7.8.9/22 +deny 1.2.3.4 +deny all 3.4.5.0/24 deny 2001:db8:789a::/48 deny 0/0 deny ::/0