mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 05:55:28 +00:00
Update classify.xml through line 590; no additional edits because this section is about to be completely rewritten
This commit is contained in:
Suzanne Goldlust
committed by
Tomek Mrugalski
Tomek Mrugalski
parent
5813fa1ca0
commit
f4b43b77f4
@@ -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/.
|
||||
-->
|
||||
|
||||
<!-- Converted by db4-upgrade version 1.1 -->
|
||||
@@ -18,27 +18,27 @@
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
The clients have different behavior, e.g. a smart phone behaves
|
||||
differently to a laptop.
|
||||
differently than a laptop.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An incoming packet can be associated with a client class in
|
||||
serveral ways:
|
||||
several ways:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Implicitly, using a vendor class option or another builtin condition.
|
||||
@@ -58,17 +58,17 @@
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The process of doing classification is conducted in several steps:
|
||||
The classification process is conducted in several steps:
|
||||
<orderedlist>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
@@ -137,39 +137,39 @@
|
||||
|
||||
<note>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
@@ -177,50 +177,50 @@
|
||||
<section xml:id="classification-using-vendor">
|
||||
<title>Builtin Client Classes</title>
|
||||
<para>
|
||||
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".
|
||||
</para>
|
||||
|
||||
<para>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
|
||||
<xref linkend="high-availability-library"/>.</para>
|
||||
|
||||
<para>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
|
||||
<para>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.
|
||||
</para>
|
||||
|
||||
<para>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.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="classification-using-expressions">
|
||||
<title>Using Expressions In Classification</title>
|
||||
<title>Using Expressions in Classification</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@@ -244,17 +244,10 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
@@ -298,7 +291,7 @@
|
||||
<entry>Integer literal</entry>
|
||||
<entry>123</entry>
|
||||
<entry>'123'</entry>
|
||||
<entry>A 32 bit unsigned integer value</entry>
|
||||
<entry>A 32-bit unsigned integer value</entry>
|
||||
</row>
|
||||
<row/>
|
||||
<row>
|
||||
@@ -396,7 +389,7 @@
|
||||
<entry>pkt.len</entry>
|
||||
<entry>513</entry>
|
||||
<entry>The length of a DHCP packet (UDP header field), expressed
|
||||
as a 32 bit unsigned integer.</entry>
|
||||
as a 32-bit unsigned integer.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Hardware address in DHCPv4 packet</entry>
|
||||
@@ -441,32 +434,32 @@
|
||||
<entry>The value of the siaddr field of the DHCPv4 packet (IPv4 address, 4 bytes)</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Message Type in DHCPv4 packet</entry>
|
||||
<entry>Message type in DHCPv4 packet</entry>
|
||||
<entry>pkt4.msgtype</entry>
|
||||
<entry>1</entry>
|
||||
<entry>The value of the message type field in the DHCPv4
|
||||
packet (expressed as a 32 bit unsigned integer).</entry>
|
||||
packet (expressed as a 32-bit unsigned integer).</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Transaction ID (xid) in DHCPv4 packet</entry>
|
||||
<entry>pkt4.transid</entry>
|
||||
<entry>12345</entry>
|
||||
<entry>The value of the transaction id in the DHCPv4
|
||||
packet (expressed as a 32 bit unsigned integer).</entry>
|
||||
packet (expressed as a 32-bit unsigned integer).</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Message Type in DHCPv6 packet</entry>
|
||||
<entry>Message type in DHCPv6 packet</entry>
|
||||
<entry>pkt6.msgtype</entry>
|
||||
<entry>1</entry>
|
||||
<entry>The value of the message type field in the DHCPv6
|
||||
packet (expressed as a 32 bit unsigned integer).</entry>
|
||||
packet (expressed as a 32-bit unsigned integer).</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Transaction ID in DHCPv6 packet</entry>
|
||||
<entry>pkt6.transid</entry>
|
||||
<entry>12345</entry>
|
||||
<entry>The value of the transaction id in the DHCPv6
|
||||
packet (expressed as a 32 bit unsigned integer).</entry>
|
||||
packet (expressed as a 32-bit unsigned integer).</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@@ -559,24 +552,24 @@
|
||||
<itemizedlist>
|
||||
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
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.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
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 @@
|
||||
<listitem><para>
|
||||
"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.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
"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.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>
|
||||
"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.
|
||||
|
||||
Reference in New Issue
Block a user