[#2793] improve vendor option documentation

doc/sphinx/arm/classify.rst

@@ -174,18 +174,24 @@ value is obtained is determined as explained in the previous paragraph.
    clients that do not meet any class criteria to be denied service
    altogether.
 
-.. _classification-using-vendor:
+.. _built-in-client-classes:
 
 Built-in Client Classes
 =======================
 
-Some classes are built-in, so they do not need to be defined.
+Some classes are built-in, so they do not need to be explicitly defined. They
+can be defined if there is a need to associate lease lifetimes, option data,
+etc. with them.
+
 Vendor class information is the primary example: the server checks whether an
 incoming DHCPv4 packet includes the vendor class identifier option (60)
 or an incoming DHCPv6 packet includes the vendor class option (16). If
 it does, the content of that option is prepended with ``VENDOR_CLASS_``
-and the result is interpreted as a class. For example, modern cable
-modems send this option with value ``docsis3.0``, so the packet belongs to
+and the result is interpreted as a class for that packet. The content that is
+considered is the whole class identifier for DHCPv4, and the first vendor class
+data field for DHCPv6. The enterprise number and subsequent vendor class data
+fields are not used for the purpose of classification. For example, modern cable
+modems send such options with value ``docsis3.0``, so the packet belongs to
 class ``VENDOR_CLASS_docsis3.0``.
 
 The ``HA_`` prefix is used by :ischooklib:`libdhcp_ha.so` to

doc/sphinx/arm/dhcp4-srv.rst

@@ -2510,7 +2510,7 @@ The definition used to decode a VSI option is:
 DHCPv4 Vendor-Specific Options
 ------------------------------
 
-Currently there are two option spaces defined for the DHCPv4 daemon:
+Currently there are two option spaces defined for :iscman:`kea-dhcp4`:
 ``dhcp4`` (for the top-level DHCPv4 options) and
 ``"vendor-encapsulated-options-space"``, which is empty by default but in
 which options can be defined. Those options are carried in the
@@ -2646,7 +2646,9 @@ following:
                // Unfortunately, Genexis is a bit unusual in this aspect, because it
                // doesn't send vivso. In this case we need to look into the vendor class
                // (option code 60) and see if there's a specific string that identifies
-               // the device.
+               // the device. Alternatively, one can make use of the automated `VENDOR_CLASS_`
+               // client class and replace "name" and "test" with `"name": "VENDOR_CLASS_HMC1000"`
+               // and no test expression.
                "name": "cpe_genexis",
                "test": "substring(option[60].hex,0,7) == 'HMC1000'",
 
@@ -2692,24 +2694,29 @@ be achieved by adding ``"always-send": true`` to the option data entry. Note
 that in this particular case an option is defined in vendor space 25167. With
 ``always-send`` enabled, the option is sent every time there is a need to deal
 with vendor space 25167.
-This is also how the Kea server can be configured to send multiple vendor
-enterprise numbers and multiple options, specific for each vendor.
+
+This is also how :iscman:`kea-dhcp4` can be configured to send multiple vendor options
+from different vendors, along with each of their specific vendor ID.
 If these options need to be sent by the server regardless of whether the client
 specified any enterprise number, ``"always-send": true`` must be configured
-for the option with code 125 (``vivso-suboptions``) for each enterprise number.
+for the suboptions that will be included in the ``vivso-suboptions`` option (code 125).
 
 ::
 
    "Dhcp4": {
        "option-data": [
+           # Typically DHCPv4 clients will send a Parameter Request List option (code 55) for
+           # vivso-suboptions (code 125), and that is enough for Kea to understand that it needs to
+           # send the option. These options still need to be defined in the configuration, one per
+           # each vendor, but they don't need "always-send" enabled in that case. For misbehaving
+           # clients that to do not explicitly request it, one may alternatively set "always-send"
+           # to true for them as well. This is referring to the following two entries in option-data.
            {
-               "always-send": true,
                "name": "vivso-suboptions",
                "space": "dhcp4",
                "data": "2234"
            },
            {
-               "always-send": true,
                "name": "vivso-suboptions",
                "space": "dhcp4",
                "data": "3561"
@@ -2722,9 +2729,9 @@ for the option with code 125 (``vivso-suboptions``) for each enterprise number.
            },
            {
                "always-send": true,
+               "data": "https://example.com:1234/path",
                "name": "url",
-               "space": "vendor-3561",
-               "data": "https://example.com:1234/path"
+               "space": "vendor-3561"
            }
        ],
        "option-def": [
@@ -2751,10 +2758,11 @@ and ``doc/examples/kea4/vivso.json`` in the Kea sources.
 
 .. note::
 
-   Multiple vendor enterprise numbers are supported by the ``vivso-suboptions``
-   (code 125) option. The option can contain multiple options for each vendor.
+   :iscman:`kea-dhcp4` is able to recognize multiple Vendor Class Identifier
+   options (code 60) with different vendor IDs in the client requests and to
+   send multiple vivso options (code 125) in the responses, one for each vendor.
 
-   Kea honors DOCSIS sub-option 1 (ORO) and adds only requested options
+   :iscman:`kea-dhcp4` honors DOCSIS sub-option 1 (ORO) and adds only requested options
    if this sub-option is present in the client request.
 
    Currently only one vendor is supported for the ``vivco-suboptions``

doc/sphinx/arm/dhcp6-srv.rst

@@ -2282,12 +2282,53 @@ Alternatively, the option can be specified using its code.
 A common configuration is to set the ``always-send`` flag to ``true``, so the
 vendor option is sent even when the client did not specify it in the query.
 
+This is also how :iscman:`kea-dhcp6` can be configured to send multiple vendor options
+from different vendors, along with each of their specific enterprise number.
+If these options need to be sent by the server regardless of whether the client
+specified any enterprise number, ``"always-send": true`` must be configured
+for the suboptions that will be included in the Vendor-Specific Information option (code 17).
+
+.. code-block:: json
+
+    {
+      "Dhcp6": {
+        "option-data": [
+          {
+            "always-send": true,
+            "data": "tagged",
+            "name": "tag",
+            "space": "vendor-2234"
+          },
+          {
+            "always-send": true,
+            "data": "https://example.com:1234/path",
+            "name": "url",
+            "space": "vendor-3561"
+          }
+        ],
+        "option-def": [
+          {
+            "code": 22,
+            "name": "tag",
+            "space": "vendor-2234",
+            "type": "string"
+          },
+          {
+            "code": 11,
+            "name": "url",
+            "space": "vendor-3561",
+            "type": "string"
+          }
+        ]
+      }
+    }
+
 .. note::
 
-   Multiple instances of the ``vendor-class`` (code 16) and
-   ``vendor-opts`` (code 17) options can be
-   specified. Specifying multiple options with different enterprise
-   numbers is supported by Kea.
+   The :iscman:`kea-dhcp6` server is able to recognize multiple Vendor Class
+   options (code 16) with different enterprise numbers in the client requests
+   and to send multiple Vendor-Specific Information options (code 17) in the
+   responses, one for each vendor.
 
 .. _dhcp6-option-spaces:
 

doc/sphinx/arm/hooks-ha.rst

@@ -1040,7 +1040,7 @@ The configuration provided above splits the address range into four pools: two
 pools dedicated to "HA_server1" and two to "HA_server2". Each server can assign
 leases to both phones and laptops. Both groups of devices are assigned addresses
 from different pools. The "HA_server1" and "HA_server2" classes are built-in
-(see :ref:`classification-using-vendor`) and do not need to be declared.
+(see :ref:`built-in-client-classes`) and do not need to be declared.
 They are assigned dynamically by the HA hook library as a result of the
 ``load-balancing`` algorithm. "phones_*" and "laptop_*" evaluate to ``true``
 when the query belongs to a given combination of other classes, e.g. "HA_server1"