From: Marcin Siodelski Date: Mon, 9 Apr 2018 14:50:53 +0000 (+0200) Subject: [5374] Some corrections in the new client classification text of User Guide. X-Git-Tag: trac5458a_base~14^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=422df21fb6682b21b1a5afb74f88d298ef780bcd;p=thirdparty%2Fkea.git [5374] Some corrections in the new client classification text of User Guide. --- diff --git a/doc/guide/classify.xml b/doc/guide/classify.xml index 06e7beebf6..4e800f327f 100644 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@ -29,8 +29,8 @@ - At the opposite some clients can be grouped into a client class for - instance to get a common option. + Conversely, different clients can be grouped into a client class to get a + common option. @@ -38,7 +38,7 @@ serveral ways: - Implicitely using a vendor class option or another builtin condition. + Implicitly, using a vendor class option or another builtin condition. Using an expression which evaluates to true. @@ -55,10 +55,8 @@ It is envisaged that client classification will be used for changing the behavior of almost any part of the DHCP message - processing, including the assignment of leases from different - pools, the assignment of different options (or different values - of the same options) etc. In the current release of the software - however, there are only five mechanisms that take advantage of + processing. In the current release of the software however, + there are only five mechanisms that take advantage of client classification: subnet selection, pool selection, definition of DHCPv4 private (codes 224-254) and code 43 options, assignment of different options and, for DHCPv4 cable @@ -76,11 +74,11 @@ Vendor class options are processed. - Classes with matching expressions and not marked for later - evaluation are processed in the order they are defined in the - configuration: the boolean expression is evaluated and when it - returns true ("match") the incoming packet is associated to the - class. + Classes with matching expressions and not marked for later ("on + request") evaluation are processed in the order they are defined + in the configuration: the boolean expression is evaluated and + when it returns true ("match") the incoming packet is associated + to the class. If a private or code 43 DHCPv4 option is received, decoding it @@ -89,7 +87,7 @@ Choose a subnet, possibly based on the class information when - some subnets are guarded. More exactly: When choosing a subnet, + some subnets are guarded. More precisely: when choosing a subnet, the server will iterate over all of the subnets that are feasible given the information found in the packet (client address, relay address etc). It will use the first subnet it @@ -111,14 +109,13 @@ class. - If needed resources from pools are assigned, possibly based on the + If needed, resources from pools are assigned, possibly based on the class information when some pools are reserved to class members. - Process required evaluation in the order classes are required - which uses the reverse precedence of option data: first shared - network, after the subnet and to finish pools assigned resources - belongs too. + Evaluate classes marked as "required" in the order in which they + are listed as required: first shared network, then the subnet + and to finally pools assigned resources belong too. Assign options, again possibly based on the class information @@ -133,15 +130,15 @@ Beginning with Kea 1.4.0 release, client classes follow the order in which they are specified in the configuration - (vs. alphabetical order in previous versions), or for required - classes the order they are required. + (vs. alphabetical order in previous releases). Required classes + follow the order in which they are required. - When determining which options to include in the response the + When determining which options to include in the response, the server will examine the union of options from all of the - assigned classes. In the case two or more classes include the + assigned classes. In case when two or more classes include the same option, the value from the first class examined will be used, and classes are examined in the order they were associated so ALL is always the first class and matching required classes @@ -182,16 +179,17 @@ packet will belong to class "VENDOR_CLASS_docsis3.0". - Other examples are the ALL class what all incoming packets - belongs to, and the KNOWN class. By convention builtin classes - names begin with all caps. + Other examples are: the ALL class which all incoming packets + belong to, and the KNOWN class assigned when host reservations exist + for the particular client. By convention, builtin classes' names + begin with all capital letters. Currently recognized builtin class names are ALL and KNOWN and prefixes VENDOR_CLASS_, AFTER_ and EXTERNAL_. The AFTER_ prefix is a provision for a not yet written hook, the EXTERNAL_ prefix can be freely used: builtin classes are implicitly defined so - never raise warnings because they do not appear in the configuration. + never raise warnings if they do not appear in the configuration. @@ -236,7 +234,7 @@ Dependencies between classes are checked too: for instance forward dependencies are rejected when the configuration is parsed: - an expression can only depends on already defined classes (including + an expression can only depend on already defined classes (including builtin classes) and which are evaluated in a previous or the same evaluation phase. This does not apply to the KNOWN class. @@ -798,7 +796,8 @@ concatenation of the strings subnet, shared-network or pools are known but output option processing not yet done. The only-if-required flag, false by default, allows to perform the evaluation of the test expression only - when it was required, i.e. in a require-client-classes list. + when it was required, i.e. in a require-client-classes list of the + selected subnet, shared-network or pool. diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 7fed462b7b..2429651262 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2061,10 +2061,8 @@ It is merely echoed by the server In certain cases it is useful to differentiate between different types of clients and treat them accordingly. It is envisaged that client classification will be used for changing the behavior of almost any part of - the DHCP message processing, including the assignment of leases from different - pools, the assignment of different options (or different values of the same - options) etc. In the current release of the software however, there are - only some mechanisms that take advantage of client classification: + the DHCP message processing. In the current release of the software however, + there are only some mechanisms that take advantage of client classification: private options and option 43 deferred unpacking, subnet selection, pool selection, assignment of different options, and, for cable modems, there are specific options for use with the TFTP server address and the boot file field. @@ -2111,7 +2109,7 @@ It is merely echoed by the server on examining the values in the vendor class options or existence of a host reservation. Information from these options is extracted and a class name is constructed from it and added to - the class list for the packet. The second allows you to specify an expression + the class list for the packet. The second allows for specifying an expression that is evaluated for each packet. If the result is true the packet is a member of the class. @@ -2256,31 +2254,33 @@ It is merely echoed by the server
- Required classification + Required Classification - In some cases it is useful to limit the scope of class. - Two devices are available to perform evaluation of test - expressions so assignment when it was required. + In some cases it is useful to limit the scope of a class to + a shared-network, subnet or pool. There are two parameters + which are used to limit the scope of the class by instructing + the server to perform evaluation of test expressions when + required. The first one is the per-class only-if-required flag which is false by default. When it is set to true the test expression of the class is not - evaluated at the reception of a new incoming ticket but - later and only if the class evaluation is required. + evaluated at the reception of the incoming packet but later and + only if the class evaluation is required. The second is the require-client-classes which takes a list of class names and is valid in shared-network, subnet and pool scope. Classes in these lists are marked as - required and evaluated - after resource assignment and before output option processing. + required and evaluated after selection of this specific + shared-network/subnet/pool and before output option processing. - In this example a class is assigned to the incoming packet + In this example, a class is assigned to the incoming packet when the specified subnet is used. @@ -2307,17 +2307,17 @@ It is merely echoed by the server - Required evaluation can be used to express complex dependencies - including for instance subnet membership, and to reverse the + Required evaluation can be used to express complex dependencies, + for example, subnet membership. It can also be used to reverse the precedence: if you set an option-data in a subnet it takes precedence over an option-data in a class. When you move the - option-data to a (only-if) required class and require it in - the subnet a class evaluted or set before takes precedence. + option-data to a required class and require it in + the subnet, a class evaluted earlier may take precedence. Required evaluation is also available at shared-network and - pool levels. The order required classes are considered is + pool levels. The order in which required classes are considered is: shared-network, subnet and pool, i.e. the opposite order option-data are processed. diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 9a671c2def..50c59aefed 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -1921,10 +1921,8 @@ should include options from the isc option space: In certain cases it is useful to differentiate between different types of clients and treat them accordingly. It is envisaged that client classification will be used for changing the behavior of almost any part of - the DHCP message processing, including the assignment of leases from different - pools, the assignment of different options (or different values of the same - options) etc. In the current release of the software however, there are - only some mechanisms that take advantage of client classification: + the DHCP message processing. In the current release of the software however, + there are only some mechanisms that take advantage of client classification: subnet selection, pool selection, and assignment of different options. @@ -1970,7 +1968,7 @@ should include options from the isc option space: on examining the values in the vendor class options or existence of a host reservation. Information from these options is extracted and a class name is constructed from it and added to - the class list for the packet. The second allows you to specify an expression + the class list for the packet. The second allows for specifying an expression that is evaluated for each packet. If the result is true the packet is a member of the class. @@ -2049,29 +2047,31 @@ should include options from the isc option space:
Required classification - In some cases it is useful to limit the scope of class. - Two devices are available to perform evaluation of test - expressions so assignment when it was required. + In some cases it is useful to limit the scope of a class to + a shared-network, subnet or pool. There are two parameters + which are used to limit the scope of the class by instructing + the server to perform evaluation of test expressions when + required. The first one is the per-class only-if-required flag which is false by default. When it is set to true the test expression of the class is not - evaluated at the reception of a new incoming ticket but - later and only if the class evaluation is required. + evaluated at the reception of the incoming packet but later and + only if the class evaluation is required. The second is the require-client-classes which takes a list of class names and is valid in shared-network, subnet and pool scope. Classes in these lists are marked as - required and evaluated - after resource assignment and before output option processing. + required and evaluated after selection of this specific + shared-network/subnet/pool and before output option processing. - In this example a class is assigned to the incoming packet + In this example, a class is assigned to the incoming packet when the specified subnet is used. @@ -2102,19 +2102,19 @@ should include options from the isc option space: - Required evaluation can be used to express complex dependencies - including for instance subnet membership, and to reverse the + Required evaluation can be used to express complex dependencies, + for example, subnet membership. It can also be used to reverse the precedence: if you set an option-data in a subnet it takes precedence over an option-data in a class. When you move the - option-data to a (only-if) required class and require it in - the subnet a class evaluted or set before takes precedence. + option-data to a required class and require it in + the subnet, a class evaluted earlier may take precedence. Required evaluation is also available at shared-network and - pool/pd-pool levels. The order required classes are considered is - shared-network, subnet and (pd-)pool, i.e. the opposite order - option-data are processed. + pool/pd-pool levels. The order in which required classes are + considered is: shared-network, subnet and (pd-)pool, i.e. + the opposite order option-data are processed.