[#3348] Update docs about subnet/pool selection

The change that would have helped the reporter:
- Add paragraph explaining that out-of-network guarded subnets need
  EGRL enabled in order for those guards to properly select subnets.

Other important changes:
- Define class guards. They are referenced in some places in the ARM,
  but never defined.
- Move "unreserved_class" guards before "reserved_class" guards so that
  it is clear that a pool or a subnet is skipped and the allocator takes
  a different path than usual, assumin an iterative allocator.
- Add unguarded subnets and pools and explain that those are available
  to both reserved and unreserved clients.
- Add paragraph explaining that in-subnet reservations don't work when
  the subnet belongs to a shared network.
- Add paragraph explaining that for a subnet to be selected, when
  choosing to do the selection via pools, as the example is structured,
  all of the pools inside the subnets desired to be skipped or selected
  need to be guarded.
- Add missing name to shared network in the JSON config examples.

Less important changes:
- Remove comments about reservation settings. Some were forgotten to be
  removed since new reservation flags are added, but overall they don't
  need to be explained because these sections are not focused on reservations.
- Add curly brackets to make the whole JSON valid and add code-block:: json
  and reindent.

3 files changed, 276 insertions, 194 deletions

diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst
index e7a4218695..3c1c5b7fe9 100644
--- a/doc/sphinx/arm/classify.rst
+++ b/doc/sphinx/arm/classify.rst
@@ -1011,7 +1011,8 @@ In certain cases it is beneficial to restrict access to certain subnets
 only to clients that belong to a given class, using the ``client-classes``
 parameter when defining the subnet.  This parameter may be used to specify
 a list of one or more classes to which clients must belong in order to
-use the subnet.
+use the subnet. This can be referred to as a class guard for the subnet, or in
+other words the subnet is guarded by a client class.
 
 Let's assume that the server is connected to a network segment that uses the
 192.0.2.0/24 prefix. The administrator of that network has decided that
@@ -1099,7 +1100,8 @@ Configuring Pools With Class Information
 Similar to subnets, in certain cases access to certain address or prefix
 pools must be restricted to only clients that belong to at least one of a
 list of one or more classes, using the ``client-classes`` when defining
-the pool.
+the pool. This can be referred to as a class guard for the pool, or in other
+words the pool is guarded by a client class.
 
 Let's assume that the server is connected to a network segment that uses the
 192.0.2.0/24 prefix. The administrator of that network has decided that
diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst
index a45524e805..ba03f0a973 100644
--- a/doc/sphinx/arm/dhcp4-srv.rst
+++ b/doc/sphinx/arm/dhcp4-srv.rst
@@ -5932,55 +5932,67 @@ If the subnet does not belong to a shared network, the subnet
 is not changed once selected.
 
 If the subnet does not belong to a shared network, it is possible to
-use host reservation-based client classification to select an address pool
+use host reservation-based client classification to select a pool
 within the subnet as follows:
 
-::
+.. code-block:: json
 
-    "Dhcp4": {
-        "client-classes": [
-            {
-                "name": "reserved_class"
-            },
-            {
-                "name": "unreserved_class",
-                "test": "not member('reserved_class')"
-            }
-        ],
-        "subnet4": [
-            {
-                "id": 1,
-                "subnet": "192.0.2.0/24",
-                "reservations": [
-                    {
-                        "hw-address": "aa:bb:cc:dd:ee:fe",
-                        "client-classes": [ "reserved_class" ]
-                    }
-                ],
-                "pools": [
-                    {
-                        "pool": "192.0.2.10-192.0.2.20",
-                        "client-classes": [ "reserved_class" ]
-                    },
-                    {
-                        "pool": "192.0.2.30-192.0.2.40",
-                        "client-classes": [ "unreserved_class" ]
-                    }
-                ]
-            }
-        ]
+    {
+        "Dhcp4": {
+            "client-classes": [
+                {
+                    "name": "reserved_class"
+                },
+                {
+                    "name": "unreserved_class",
+                    "test": "not member('reserved_class')"
+                }
+            ],
+            "subnet4": [
+                {
+                    "id": 1,
+                    "subnet": "192.0.2.0/24",
+                    "reservations": [
+                        {
+                            "hw-address": "aa:bb:cc:dd:ee:fe",
+                            "client-classes": [ "unreserved_class" ]
+                        }
+                    ],
+                    "pools": [
+                        {
+                            "pool": "192.0.2.10 - 192.0.2.20",
+                            "client-classes": [ "reserved_class" ]
+                        },
+                        {
+                            "pool": "192.0.2.30 - 192.0.2.40",
+                            "client-classes": [ "reserved_class" ]
+                        },
+                        {
+                            "pool": "192.0.2.50 - 192.0.2.60"
+                        }
+                    ]
+                }
+            ]
+        }
     }
 
-The ``reserved_class`` is declared without the ``test`` parameter because
-it may only be assigned to the client via the host reservation mechanism. The
+``reserved_class`` is declared without the ``test`` parameter because
+it may only be assigned to a client via the host reservation mechanism. The
 second class, ``unreserved_class``, is assigned to clients which do not
-belong to the ``reserved_class``. The first pool within the subnet is only
-used for clients having a reservation for the ``reserved_class``. The
-second pool is used for clients not having such a reservation. The
-configuration snippet includes one host reservation which causes the client
-with the MAC address aa:bb:cc:dd:ee:fe to be assigned to the
-``reserved_class``. Thus, this client will be given an IP address from the
-first address pool.
+belong to the ``reserved_class``.
+
+The first pool with the subnet is used for clients not having such a reservation.
+The second pool is only used for clients having a reservation for ``reserved_class``.
+The third pool is an unrestricted pool for any clients, comprising of both
+``reserved_class`` clients and ``unreserved_class``.
+
+The configuration snippet includes one host reservation which causes the client
+with the MAC address ``aa:bb:cc:dd:ee:fe`` to be assigned to ``reserved_class``.
+Thus, this client will be given an IP address from the second address pool.
+
+Reservations defined on a subnet that belongs to a shared network are not
+visible to an otherwise matching client, so they cannot be used to select pools,
+nor subnets for that matter.
 
 .. _subnet-selection-with-class-reservations4:
 
@@ -5993,76 +6005,104 @@ client belongs to a shared network. In such a case it is possible to use
 classification to select a subnet within this shared network. Consider the
 following example:
 
-::
+.. code-block:: json
 
-    "Dhcp4": {
-        "client-classes": [
-            {
-                "name": "reserved_class"
-            },
-            {
-                "name": "unreserved_class",
-                "test": "not member('reserved_class')"
-            }
-        ],
-        "reservations": [
-            {
-                "hw-address": "aa:bb:cc:dd:ee:fe",
-                "client-classes": [ "reserved_class" ]
-            }
-        ],
-        # It is replaced by the "reservations-global",
-        # "reservations-in-subnet", and "reservations-out-of-pool" parameters.
-        # Specify if the server should look up global reservations.
-        "reservations-global": true,
-        # Specify if the server should look up in-subnet reservations.
-        "reservations-in-subnet": false,
-        # Specify if the server can assume that all reserved addresses
-        # are out-of-pool. It can be ignored because "reservations-in-subnet"
-        # is false, but if specified, it is inherited by "shared-networks"
-        # and "subnet4" levels.
-        # "reservations-out-of-pool": false,
-        "shared-networks": [
-            {
-            "subnet4": [
+    {
+        "Dhcp4": {
+            "client-classes": [
                 {
-                    "id": 1,
-                    "subnet": "192.0.2.0/24",
-                    "pools": [
-                        {
-                            "pool": "192.0.2.10-192.0.2.20",
-                            "client-classes": [ "reserved_class" ]
-                        }
-                    ]
+                    "name": "reserved_class"
                 },
                 {
-                    "id": 2,
-                    "subnet": "192.0.3.0/24",
-                    "pools": [
+                    "name": "unreserved_class",
+                    "test": "not member('reserved_class')"
+                }
+            ],
+            "reservations": [
+                {
+                    "hw-address": "aa:bb:cc:dd:ee:fe",
+                    "client-classes": [ "reserved_class" ]
+                }
+            ],
+            "reservations-global": true,
+            "reservations-in-subnet": false,
+            "shared-networks": [
+                {
+                    "name": "net",
+                    "subnet4": [
                         {
-                            "pool": "192.0.3.10-192.0.3.20",
-                            "client-classes": [ "unreserved_class" ]
+                            "id": 1,
+                            "subnet": "192.0.2.0/24",
+                            "pools": [
+                                {
+                                    "pool": "192.0.2.10-192.0.2.20",
+                                    "client-classes": [ "unreserved_class" ]
+                                },
+                                {
+                                    "pool": "192.0.2.30-192.0.2.40",
+                                    "client-classes": [ "unreserved_class" ]
+                                }
+                            ]
+                        },
+                        {
+                            "id": 2,
+                            "subnet": "192.0.3.0/24",
+                            "pools": [
+                                {
+                                    "pool": "192.0.3.10-192.0.3.20",
+                                    "client-classes": [ "reserved_class" ]
+                                },
+                                {
+                                    "pool": "192.0.3.30-192.0.3.40",
+                                    "client-classes": [ "reserved_class" ]
+                                }
+                            ]
+                        },
+                        {
+                            "id": 3,
+                            "subnet": "192.0.4.0/24",
+                            "pools": [
+                                {
+                                    "pool": "192.0.4.10-192.0.4.20"
+                                },
+                                {
+                                    "pool": "192.0.4.30-192.0.4.40"
+                                }
+                            ]
                         }
                     ]
                 }
             ]
-            }
-        ]
+        }
     }
 
 This is similar to the example described in
 :ref:`pool-selection-with-class-reservations4`. This time, however, there
-are two subnets, each of which has a pool associated with a different
-class. The clients that do not have a reservation for the ``reserved_class``
-are assigned an address from the subnet 192.0.3.0/24. Clients with
-a reservation for the ``reserved_class`` are assigned an address from
-the subnet 192.0.2.0/24. The subnets must belong to the same shared network.
+are three subnets, of which the first two have a pool associated with a different
+class each.
+
+The clients that do not have a reservation for ``reserved_class``
+are assigned an address from the first subnet and when that is filled from
+the third subnet. Clients with a reservation for ``reserved_class`` are assigned
+an address from the second subnet and when that is filled from the third subnet.
+
+The subnets must belong to the same shared network.
+
+For a subnet to be restricted to a certain class, or skipped, all of the pools
+inside that subnet must be guarded by ``reserved_class`` or ``unreserved_class``
+respectively.
+
 In addition, the reservation for the client class must be specified at the
 global scope (global reservation) and ``reservations-global`` must be
 set to ``true``.
 
-In the example above, the ``client-classes`` could also be specified at the
-subnet level rather than the pool level, and would yield the same effect.
+In the example above, the ``client-classes`` configuration parameter could also
+be specified at the subnet level rather than the pool level, and would yield the
+same effect.
+
+If the subnets were defined outside shared networks, and ``client-classes`` were
+specified at the subnet level, then ``early-global-reservations-lookup`` would
+also need to be enabled in order for subnet selection to work.
 
 .. _multiple-reservations-same-ip4:
 
diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst
index 1497145158..d601d3286b 100644
--- a/doc/sphinx/arm/dhcp6-srv.rst
+++ b/doc/sphinx/arm/dhcp6-srv.rst
@@ -5202,55 +5202,67 @@ If the subnet does not belong to a shared network, once selected, the subnet
 is not changed once selected.
 
 If the subnet does not belong to a shared network, it is possible to
-use host reservation-based client classification to select an address pool
+use host-reservation-based client classification to select a pool
 within the subnet as follows:
 
-::
+.. code-block:: json
 
-    "Dhcp6": {
-        "client-classes": [
-            {
-                "name": "reserved_class"
-            },
-            {
-                "name": "unreserved_class",
-                "test": "not member('reserved_class')"
-            }
-        ],
-        "subnet6": [
-            {
-                "id": 1,
-                "subnet": "2001:db8:1::/64",
-                "reservations": [
-                    {
-                        "hw-address": "aa:bb:cc:dd:ee:fe",
-                        "client-classes": [ "reserved_class" ]
-                    }
-                ],
-                "pools": [
-                    {
-                        "pool": "2001:db8:1::10-2001:db8:1::20",
-                        "client-classes": [ "reserved_class" ]
-                    },
-                    {
-                        "pool": "2001:db8:1::30-2001:db8:1::40",
-                        "client-classes": [ "unreserved_class" ]
-                    }
-                ]
-            }
-        ]
+    {
+        "Dhcp6": {
+            "client-classes": [
+                {
+                    "name": "reserved_class"
+                },
+                {
+                    "name": "unreserved_class",
+                    "test": "not member('reserved_class')"
+                }
+            ],
+            "subnet6": [
+                {
+                    "id": 1,
+                    "subnet": "2001:db8:1::/64",
+                    "reservations": [
+                        {
+                            "hw-address": "aa:bb:cc:dd:ee:fe",
+                            "client-classes": [ "reserved_class" ]
+                        }
+                    ],
+                    "pools": [
+                        {
+                            "pool": "2001:db8:1::10 - 2001:db8:1::20",
+                            "client-classes": [ "unreserved_class" ]
+                        },
+                        {
+                            "pool": "2001:db8:1::30 - 2001:db8:1::40",
+                            "client-classes": [ "reserved_class" ]
+                        },
+                        {
+                            "pool": "2001:db8:1::50 - 2001:db8:1::60"
+                        }
+                    ]
+                }
+            ]
+        }
     }
 
-The ``reserved_class`` is declared without the ``test`` parameter because
-it may be only assigned to the client via host reservation mechanism. The
+``reserved_class`` is declared without the ``test`` parameter because
+it may be only assigned to a client via host reservation mechanism. The
 second class, ``unreserved_class``, is assigned to clients which do not
-belong to the ``reserved_class``. The first pool within the subnet is only
-used for clients having a reservation for the ``reserved_class``. The
-second pool is used for clients not having such a reservation. The
-configuration snippet includes one host reservation which causes the client
-with the MAC address aa:bb:cc:dd:ee:fe to be assigned to the
-``reserved_class``. Thus, this client will be given an IP address from the
-first address pool.
+belong to the ``reserved_class``.
+
+The first pool with the subnet is used for clients not having such a reservation.
+The second pool is only used for clients having a reservation for ``reserved_class``.
+The third pool is an unrestricted pool for any clients, comprising of both
+``reserved_class`` clients and ``unreserved_class``.
+
+The configuration snippet includes one host reservation which causes the client
+with the MAC address ``aa:bb:cc:dd:ee:fe`` to be assigned to ``reserved_class``.
+Thus, this client will be given an IP address from the second address pool.
+
+Reservations defined on a subnet that belongs to a shared network are not
+visible to an otherwise matching client, so they cannot be used to select pools,
+nor subnets for that matter.
 
 .. _subnet-selection-with-class-reservations6:
 
@@ -5263,76 +5275,104 @@ client belongs to a shared network. In such a case it is possible to use
 classification to select a subnet within this shared network. Consider the
 following example:
 
-::
+.. code-block:: json
 
-    "Dhcp6": {
-        "client-classes": [
-            {
-                "name": "reserved_class"
-            },
-            {
-                "name": "unreserved_class",
-                "test": "not member('reserved_class')"
-            }
-        ],
-        "reservations": [
-            {
-                "hw-address": "aa:bb:cc:dd:ee:fe",
-                "client-classes": [ "reserved_class" ]
-            }
-        ],
-        # It is replaced by the "reservations-global",
-        # "reservations-in-subnet", and "reservations-out-of-pool" parameters.
-        # Specify if the server should look up global reservations.
-        "reservations-global": true,
-        # Specify if the server should look up in-subnet reservations.
-        "reservations-in-subnet": false,
-        # Specify if the server can assume that all reserved addresses
-        # are out-of-pool. It can be ignored because "reservations-in-subnet"
-        # is false, but if specified, it is inherited by "shared-networks"
-        # and "subnet6" levels.
-        # "reservations-out-of-pool": false,
-        "shared-networks": [
-            {
-            "subnet6": [
+    {
+        "Dhcp6": {
+            "client-classes": [
                 {
-                    "id": 1,
-                    "subnet": "2001:db8:1::/64",
-                    "pools": [
-                        {
-                            "pool": "2001:db8:1::10-2001:db8:1::20",
-                            "client-classes": [ "reserved_class" ]
-                        }
-                    ]
+                    "name": "reserved_class"
                 },
                 {
-                    "id": 2,
-                    "subnet": "2001:db8:2::/64",
-                    "pools": [
+                    "name": "unreserved_class",
+                    "test": "not member('reserved_class')"
+                }
+            ],
+            "reservations": [
+                {
+                    "hw-address": "aa:bb:cc:dd:ee:fe",
+                    "client-classes": [ "reserved_class" ]
+                }
+            ],
+            "reservations-global": true,
+            "reservations-in-subnet": false,
+            "shared-networks": [
+                {
+                    "name": "net",
+                    "subnet6": [
                         {
-                            "pool": "2001:db8:2::10-2001:db8:2::20",
-                            "client-classes": [ "unreserved_class" ]
+                            "id": 1,
+                            "subnet": "2001:db8:1::/64",
+                            "pools": [
+                                {
+                                    "pool": "2001:db8:1::10 - 2001:db8:1::20",
+                                    "client-classes": [ "unreserved_class" ]
+                                },
+                                {
+                                    "pool": "2001:db8:1::30 - 2001:db8:1::40",
+                                    "client-classes": [ "unreserved_class" ]
+                                }
+                            ]
+                        },
+                        {
+                            "id": 2,
+                            "subnet": "2001:db8:2::/64",
+                            "pools": [
+                                {
+                                    "pool": "2001:db8:2::10 - 2001:db8:2::20",
+                                    "client-classes": [ "reserved_class" ]
+                                },
+                                {
+                                    "pool": "2001:db8:2::30 - 2001:db8:2::40",
+                                    "client-classes": [ "reserved_class" ]
+                                }
+                            ]
+                        },
+                        {
+                            "id": 3,
+                            "subnet": "2001:db8:3::/64",
+                            "pools": [
+                                {
+                                    "pool": "2001:db8:3::10 - 2001:db8:3::20"
+                                },
+                                {
+                                    "pool": "2001:db8:3::30 - 2001:db8:3::40"
+                                }
+                            ]
                         }
                     ]
                 }
             ]
-            }
-        ]
+        }
     }
 
 This is similar to the example described in the
 :ref:`pool-selection-with-class-reservations6`. This time, however, there
-are two subnets, each of which has a pool associated with a different
-class. The clients that do not have a reservation for the ``reserved_class``
-are assigned an address from the subnet 2001:db8:2::/64. Clients with
-a reservation for the ``reserved_class`` are assigned an address from
-the subnet 2001:db8:1::/64. The subnets must belong to the same shared network.
+are three subnets, of which the first two have a pool associated with a different
+class each.
+
+The clients that do not have a reservation for ``reserved_class``
+are assigned an address from the first subnet and when that is filled from
+the third subnet. Clients with a reservation for ``reserved_class`` are assigned
+an address from the second subnet and when that is filled from the third subnet.
+
+The subnets must belong to the same shared network.
+
+For a subnet to be restricted to a certain class, or skipped, all of the pools
+inside that subnet must be guarded by ``reserved_class`` or ``unreserved_class``
+respectively.
+
 In addition, the reservation for the client class must be specified at the
 global scope (global reservation) and ``reservations-global`` must be
 set to ``true``.
 
-In the example above, the ``client-classes`` could also be specified at the
-subnet level rather than the pool level, and would yield the same effect.
+In the example above, the ``client-classes`` configuration parameter could also
+be specified at the subnet level rather than the pool level, and would yield the
+same effect.
+
+If the subnets were defined outside shared networks, and ``client-classes`` were
+specified at the subnet level, then ``early-global-reservations-lookup`` would
+also need to be enabled in order for subnet selection to work.
 
 .. _multiple-reservations-same-ip6: