From: Suzanne Goldlust Date: Wed, 2 Jan 2019 20:37:30 +0000 (-0500) Subject: Update classify.xml through line 590; no additional edits because this section is... X-Git-Tag: 481-remote-subnet4-set-inconsistent-work-when-id-subnet-is-duplicated_base~49 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f4b43b77f4da50d1aa13ca2efe288bc9e5c62ab1;p=thirdparty%2Fkea.git Update classify.xml through line 590; no additional edits because this section is about to be completely rewritten --- diff --git a/doc/guide/classify.xml b/doc/guide/classify.xml index 595d17b5ea..59cc8b659d 100644 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@ -3,7 +3,7 @@ - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - file, you can obtain one at http://mozilla.org/MPL/2.0/. --> @@ -18,27 +18,27 @@ The clients represent different pieces of topology, e.g. a cable - modem is different to the clients behind that modem. + modem is not the same as the clients behind that modem. The clients have different behavior, e.g. a smart phone behaves - differently to a laptop. + differently than a laptop. The clients require different values for some options, e.g. a docsis3.0 - cable modem requires different settings to docsis2.0 cable modem. + cable modem requires different settings from a docsis2.0 cable modem. - Conversely, different clients can be grouped into a client class to get a - common option. + To make management easier, different clients can be grouped into a client class to receive + common options. An incoming packet can be associated with a client class in - serveral ways: + several ways: Implicitly, using a vendor class option or another builtin condition. @@ -58,17 +58,17 @@ It is envisaged that client classification will be used for changing the behavior of almost any part of the DHCP message - processing. In the current release of the software however, - there are only five mechanisms that take advantage of + processing. + There are currently 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 + options, assignment of different options, and, for DHCPv4 cable modems, the setting of specific options for use with the TFTP server address and the boot file field. - The process of doing classification is conducted in several steps: + The classification process is conducted in several steps: The ALL class is associated with the incoming packet. @@ -80,56 +80,56 @@ Classes with matching expressions and not marked for later ("on request" or depending on the KNOWN/UNKNOWN builtin classes) 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 + configuration; the boolean expression is evaluated and, if it + returns true ("match"), the incoming packet is associated with the class. - If a private or code 43 DHCPv4 option is received, decoding it - following its client class or global (or for option 43 last + If a private or code 43 DHCPv4 option is received, it is decoded + following its client class or global (or, for option 43, last resort) definition. - Choose a subnet, possibly based on the class information when - some subnets are guarded. More precisely: when choosing a subnet, - the server will iterate over all of the subnets that are + A subnet is chosen, possibly based on the class information when + some subnets are reserved. More precisely: when choosing a subnet, + the server iterates 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 - finds that either doesn't have a class associated with it or - that has a class which matches one of the packet's classes. + address, relay address, etc). It uses the first subnet it + finds that either doesn't have a class associated with it, or + has a class which matches one of the packet's classes. - Host reservations are looked for. If an identifier from the + The server looks for host reservations. If an identifier from the incoming packet matches a host reservation in the subnet or shared network, the packet is associated with the KNOWN class and all classes of the host reservation. If a reservation is not - found, the packet is assigned to UNKNOWN class. + found, the packet is assigned to the UNKNOWN class. - Classes with matching expressions using directly or indirectly + Classes with matching expressions - directly or indirectly using the KNOWN/UNKNOWN builtin classes 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. The determination whether there is a reservation - for a given client is made after a subnet is selected. As such, it + request") evaluation - are processed in the order they are defined + in the configuration; the boolean expression is evaluated and, + if it returns true ("match"), the incoming packet is associated + with the class. After a subnet is selected, the server determines whether there is a reservation + for a given client. Therefore, it is not possible to use KNOWN/UNKNOWN classes to select a shared network or a subnet. If needed, addresses and prefixes from pools are assigned, possibly based on the class information when some pools are - reserved to class members. + reserved for class members. - 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. + Classes marked as "required" are evaluated in the order in which they + are listed: first the shared network, then the subnet, + and finally the pools that assigned resources belong to. - Assign options, again possibly based on the class information - in order classes were associated with the incoming packet. - For DHCPv4 private and code 43 options this includes class local + Options are assigned, again possibly based on the class information + in the order that classes were associated with the incoming packet. + For DHCPv4 private and code 43 options, this includes class local option definitions. @@ -137,39 +137,39 @@ - Beginning with Kea 1.4.0 release, client classes follow the order + Client classes in Kea follow the order in which they are specified in the configuration - (vs. alphabetical order in previous releases). Required classes + (vs. alphabetical order). Required classes follow the order in which they are required. When determining which options to include in the response, the - server will examine the union of options from all of 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 + server examines the union of options from all of the + assigned classes. If two or more classes include the + same option, the value from the first class examined is + used; classes are examined in the order they were associated, so ALL is always the first class and matching required classes are last. As an example, imagine that an incoming packet matches two - classes. Class "foo" defines values for an NTP server (option - 42 in DHCPv4) and an SMTP server (option 69 in DHCPv4) while + classes. Class "foo" defines values for an NTP server (option + 42 in DHCPv4) and an SMTP server (option 69 in DHCPv4), while class "bar" defines values for an NTP server and a POP3 server - (option 70 in DHCPv4). The server will examine the three - options NTP, SMTP and POP3 and return any of them that the - client requested. As the NTP server was defined twice the - server will choose only one of the values for the reply: the + (option 70 in DHCPv4). The server examines the three + options - NTP, SMTP, and POP3 - and returns any that the + client requested. As the NTP server was defined twice, the + server chooses only one of the values for the reply; the class from which the value is obtained is unspecified. Care should be taken with client classification as it is easy for - clients that do not meet class criteria to be denied any service altogether. + clients that do not meet any class criteria to be denied service altogether. @@ -177,50 +177,50 @@
Builtin Client Classes - Some classes are builtin so do not need to be defined. The main + Some classes are builtin, so they do not need to be defined. The main example uses Vendor Class information: 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 will - send this option with value "docsis3.0" and so the - packet will belong to class "VENDOR_CLASS_docsis3.0". + interpreted as a class. For example, modern cable modems + send this option with value "docsis3.0", so the + packet belongs to class "VENDOR_CLASS_docsis3.0". The "HA_" prefix is used by the High Availability hooks library to designate certain servers to process DHCP packets as a result of load balancing. The class name is constructed by prepending the "HA_" prefix to the name of the server - which should process the DHCP packet. This server will use appropriate - pool or subnet to allocate IP addresses (and/or prefixes) from, based on + which should process the DHCP packet. This server will use an appropriate + pool or subnet to allocate IP addresses (and/or prefixes), based on the assigned client classes. The details can be found in . - 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 + Other examples are: the ALL class, which all incoming packets + belong to, and the KNOWN class, assigned when host reservations exist + for a particular client. By convention, builtin classes' names begin with all capital letters. Currently recognized builtin class names are ALL, KNOWN - and UNKNOWN, and prefixes VENDOR_CLASS_, HA_, 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 if they + and UNKNOWN, and prefixes VENDOR_CLASS_, HA_, AFTER_, and + EXTERNAL_. Although the AFTER_ prefix is a provision for an as-yet-unwritten + hook, the EXTERNAL_ prefix can be freely used; builtin + classes are implicitly defined so they never raise warnings if they do not appear in the configuration.
- Using Expressions In Classification + Using Expressions in Classification The expression portion of classification contains operators and - values. All values are currently strings and operators take a + values. All values are currently strings; operators take a string or strings and return another string. When all the - operations have completed the result should be a value of - "true" or "false". The packet belongs to + operations have completed, the result should be a value of + "true" or "false". The packet belongs to the class (and the class name is added to the list of classes) if the result is "true". Expressions are written in standard format and can be nested. @@ -230,10 +230,10 @@ Expressions are pre-processed during the parsing of the configuration file and converted to an internal representation. This allows certain types of errors to be caught - and logged during parsing. Examples of these errors include an - incorrect number or types of arguments to an operator. The - evaluation code will also check for this class of error and - generally throw an exception, though this should not occur in a + and logged during parsing. Examples of these errors include an + incorrect number or type of argument to an operator. The + evaluation code also checks for this class of error and + generally throws an exception, though this should not occur in a normally functioning system. @@ -244,17 +244,10 @@ - Expressions are a work in progress and the supported operators and - values are limited. The expectation is that additional operators and values - will be added over time, however the basic mechanisms will - remain the same. - - - - Dependencies between classes are checked too: for instance + Dependencies between classes are also checked. For instance, forward dependencies are rejected when the configuration is - parsed: an expression can only depend on already defined classes - (including builtin classes) and which are evaluated in a + parsed; an expression can only depend on already-defined classes + (including builtin classes) which are evaluated in a previous or the same evaluation phase. This does not apply to the KNOWN or UNKNOWN classes. @@ -298,7 +291,7 @@ Integer literal 123 '123' - A 32 bit unsigned integer value + A 32-bit unsigned integer value @@ -396,7 +389,7 @@ pkt.len 513 The length of a DHCP packet (UDP header field), expressed - as a 32 bit unsigned integer. + as a 32-bit unsigned integer. Hardware address in DHCPv4 packet @@ -441,32 +434,32 @@ The value of the siaddr field of the DHCPv4 packet (IPv4 address, 4 bytes) - Message Type in DHCPv4 packet + Message type in DHCPv4 packet pkt4.msgtype 1 The value of the message type field in the DHCPv4 - packet (expressed as a 32 bit unsigned integer). + packet (expressed as a 32-bit unsigned integer). Transaction ID (xid) in DHCPv4 packet pkt4.transid 12345 The value of the transaction id in the DHCPv4 - packet (expressed as a 32 bit unsigned integer). + packet (expressed as a 32-bit unsigned integer). - Message Type in DHCPv6 packet + Message type in DHCPv6 packet pkt6.msgtype 1 The value of the message type field in the DHCPv6 - packet (expressed as a 32 bit unsigned integer). + packet (expressed as a 32-bit unsigned integer). Transaction ID in DHCPv6 packet pkt6.transid 12345 The value of the transaction id in the DHCPv6 - packet (expressed as a 32 bit unsigned integer). + packet (expressed as a 32-bit unsigned integer). @@ -559,24 +552,24 @@ - Hexadecimal strings are converted into a string as expected. The starting "0X" or - "0x" is removed and if the string is an odd number of characters a + Hexadecimal strings are converted into a string as expected. The starting "0X" or + "0x" is removed, and if the string is an odd number of characters a "0" is prepended to it. IP addresses are converted into strings of length 4 or 16. IPv4, IPv6, - and IPv4 embedded IPv6 (e.g., IPv4 mapped IPv6) addresses are supported. + and IPv4-embedded IPv6 (e.g., IPv4-mapped IPv6) addresses are supported. - Integers in an expression are converted to 32 bit unsigned integers and - are represented as four-byte strings. For example 123 is represented as + Integers in an expression are converted to 32-bit unsigned integers and + are represented as four-byte strings; for example, 123 is represented as 0x0000007b. All expressions that return numeric values use 32-bit - unsigned integers, even if the field in the packet is smaller. In general + unsigned integers, even if the field in the packet is smaller. In general, it is easier to use decimal notation to represent integers, but it is also possible to use hex notation. When using hex notation to represent an - integer care should be taken to make sure the value is represented as 32 + integer, care should be taken to make sure the value is represented as 32 bits, e.g. use 0x00000001 instead of 0x1 or 0x01. Also, make sure the value is specified in network order, e.g. 1 is represented as 0x00000001. @@ -585,20 +578,20 @@ "option[code].hex" extracts the value of the option with the code "code" from the incoming packet. If the packet doesn't contain the option, it - returns the empty string. The string is presented as a byte string of - the option payload without the type code or length fields. + returns an empty string. The string is presented as a byte string of + the option payload, without the type code or length fields. - "option[code].exists" checks if an option with the code "code" is present + "option[code].exists" checks whether an option with the code "code" is present in the incoming packet. It can be used with empty options. - "member('foobar')" checks if the packet belongs to the client - class "foobar". To avoid dependency loops the configuration file - parser checks if client classes were already defined or are - built-in, i.e., beginning by "VENDOR_CLASS_", + "member('foobar')" checks whether the packet belongs to the client + class "foobar". To avoid dependency loops, the configuration file + parser verifies whether client classes were already defined or are + builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the to come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN", "UNKNOWN"etc.