mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-03 15:35:17 +00:00
Code Issues Releases Wiki Activity

Update classify.xml through line 590; no additional edits because this section is about to be completely rewritten

Browse Source
This commit is contained in:
Suzanne Goldlust
2019-01-02 15:37:30 -05:00
committed by Tomek Mrugalski
parent 5813fa1ca0
commit f4b43b77f4
1 changed files with 95 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
doc/guide/classify.xml
View File

@@ -3,7 +3,7 @@
- -
- This Source Code Form is subject to the terms of the Mozilla Public - 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 - 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 --> <!-- Converted by db4-upgrade version 1.1 -->
@@ -18,27 +18,27 @@
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
The clients represent different pieces of topology, e.g. a cable 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> </para></listitem>
<listitem><para> <listitem><para>
The clients have different behavior, e.g. a smart phone behaves The clients have different behavior, e.g. a smart phone behaves
differently to a laptop. differently than a laptop.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
The clients require different values for some options, e.g. a docsis3.0 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> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
Conversely, different clients can be grouped into a client class to get a To make management easier, different clients can be grouped into a client class to receive
common option. common options.
</para> </para>
<para> <para>
An incoming packet can be associated with a client class in An incoming packet can be associated with a client class in
serveral ways: several ways:
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
Implicitly, using a vendor class option or another builtin condition. Implicitly, using a vendor class option or another builtin condition.
@@ -58,17 +58,17 @@
<para> <para>
It is envisaged that client classification will be used for It is envisaged that client classification will be used for
changing the behavior of almost any part of the DHCP message changing the behavior of almost any part of the DHCP message
processing. In the current release of the software however, processing.
there are only five mechanisms that take advantage of There are currently five mechanisms that take advantage of
client classification: subnet selection, pool selection, client classification: subnet selection, pool selection,
definition of DHCPv4 private (codes 224-254) and code 43 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 modems, the setting of specific options for use with the TFTP
server address and the boot file field. server address and the boot file field.
</para> </para>
<para> <para>
The process of doing classification is conducted in several steps: The classification process is conducted in several steps:
<orderedlist> <orderedlist>
<listitem><para> <listitem><para>
The ALL class is associated with the incoming packet. The ALL class is associated with the incoming packet.
@@ -80,56 +80,56 @@
Classes with matching expressions and not marked for later ("on Classes with matching expressions and not marked for later ("on
request" or depending on the KNOWN/UNKNOWN builtin classes) request" or depending on the KNOWN/UNKNOWN builtin classes)
evaluation are processed in the order they are defined in the evaluation are processed in the order they are defined in the
configuration: the boolean expression is evaluated and when it configuration; the boolean expression is evaluated and, if it
returns true ("match") the incoming packet is associated to the returns true ("match"), the incoming packet is associated with the
class. class.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
If a private or code 43 DHCPv4 option is received, decoding it If a private or code 43 DHCPv4 option is received, it is decoded
following its client class or global (or for option 43 last following its client class or global (or, for option 43, last
resort) definition. resort) definition.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Choose a subnet, possibly based on the class information when A subnet is chosen, possibly based on the class information when
some subnets are guarded. More precisely: when choosing a subnet, some subnets are reserved. More precisely: when choosing a subnet,
the server will iterate over all of the subnets that are the server iterates over all of the subnets that are
feasible given the information found in the packet (client feasible given the information found in the packet (client
address, relay address etc). It will use the first subnet it address, relay address, etc). It uses the first subnet it
finds that either doesn't have a class associated with it or finds that either doesn't have a class associated with it, or
that has a class which matches one of the packet's classes. has a class which matches one of the packet's classes.
</para></listitem> </para></listitem>
<listitem><para> <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 incoming packet matches a host reservation in the subnet or
shared network, the packet is associated with the KNOWN class shared network, the packet is associated with the KNOWN class
and all classes of the host reservation. If a reservation is not 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> </para></listitem>
<listitem><para> <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 the KNOWN/UNKNOWN builtin classes and not marked for later ("on
request") evaluation are processed in the order they are defined request") evaluation - are processed in the order they are defined
in the configuration: the boolean expression is evaluated and in the configuration; the boolean expression is evaluated and,
when it returns true ("match") the incoming packet is associated if it returns true ("match"), the incoming packet is associated
to the class. The determination whether there is a reservation with the class. After a subnet is selected, the server determines whether there is a reservation
for a given client is made after a subnet is selected. As such, it for a given client. Therefore, it
is not possible to use KNOWN/UNKNOWN classes to select a shared is not possible to use KNOWN/UNKNOWN classes to select a shared
network or a subnet. network or a subnet.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
If needed, addresses and prefixes from pools are assigned, If needed, addresses and prefixes from pools are assigned,
possibly based on the class information when some pools are possibly based on the class information when some pools are
reserved to class members. reserved for class members.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Evaluate classes marked as "required" in the order in which they Classes marked as "required" are evaluated in the order in which they
are listed as required: first shared network, then the subnet are listed: first the shared network, then the subnet,
and to finally pools assigned resources belong too. and finally the pools that assigned resources belong to.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Assign options, again possibly based on the class information Options are assigned, again possibly based on the class information
in order classes were associated with the incoming packet. in the order that classes were associated with the incoming packet.
For DHCPv4 private and code 43 options this includes class local For DHCPv4 private and code 43 options, this includes class local
option definitions. option definitions.
</para></listitem> </para></listitem>
</orderedlist> </orderedlist>
@@ -137,39 +137,39 @@
<note> <note>
<para> <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 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. follow the order in which they are required.
</para> </para>
</note> </note>
<para> <para>
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 server examines the union of options from all of the
assigned classes. In case when two or more classes include the assigned classes. If two or more classes include the
same option, the value from the first class examined will be same option, the value from the first class examined is
used, and classes are examined in the order they were associated used; classes are examined in the order they were associated,
so ALL is always the first class and matching required classes so ALL is always the first class and matching required classes
are last. are last.
</para> </para>
<para> <para>
As an example, imagine that an incoming packet matches two As an example, imagine that an incoming packet matches two
classes. Class "foo" defines values for an NTP server (option classes. Class "foo" defines values for an NTP server (option
42 in DHCPv4) and an SMTP server (option 69 in DHCPv4) while 42 in DHCPv4) and an SMTP server (option 69 in DHCPv4), while
class "bar" defines values for an NTP server and a POP3 server class "bar" defines values for an NTP server and a POP3 server
(option 70 in DHCPv4). The server will examine the three (option 70 in DHCPv4). The server examines the three
options NTP, SMTP and POP3 and return any of them that the options - NTP, SMTP, and POP3 - and returns any that the
client requested. As the NTP server was defined twice the client requested. As the NTP server was defined twice, the
server will choose only one of the values for the reply: the server chooses only one of the values for the reply; the
class from which the value is obtained is unspecified. class from which the value is obtained is unspecified.
</para> </para>
<note> <note>
<para> <para>
Care should be taken with client classification as it is easy for 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> </para>
</note> </note>
</section> </section>
@@ -177,50 +177,50 @@
<section xml:id="classification-using-vendor"> <section xml:id="classification-using-vendor">
<title>Builtin Client Classes</title> <title>Builtin Client Classes</title>
<para> <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 example uses Vendor Class information: The server checks whether
an incoming DHCPv4 packet includes the vendor class identifier an incoming DHCPv4 packet includes the vendor class identifier
option (60) or an incoming DHCPv6 packet includes the vendor option (60) or an incoming DHCPv6 packet includes the vendor
class option (16). If it does, the content of that option is class option (16). If it does, the content of that option is
prepended with &quot;VENDOR_CLASS_&quot; and the result is prepended with &quot;VENDOR_CLASS_&quot; and the result is
interpreted as a class. For example, modern cable modems will interpreted as a class. For example, modern cable modems
send this option with value &quot;docsis3.0&quot; and so the send this option with value &quot;docsis3.0&quot;, so the
packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;. packet belongs to class &quot;VENDOR_CLASS_docsis3.0&quot;.
</para> </para>
<para>The &quot;HA_&quot; prefix is used by the High Availability <para>The &quot;HA_&quot; prefix is used by the High Availability
hooks library to designate certain servers to process DHCP packets hooks library to designate certain servers to process DHCP packets
as a result of load balancing. The class name is constructed by as a result of load balancing. The class name is constructed by
prepending the &quot;HA_&quot; prefix to the name of the server prepending the &quot;HA_&quot; prefix to the name of the server
which should process the DHCP packet. This server will use appropriate which should process the DHCP packet. This server will use an appropriate
pool or subnet to allocate IP addresses (and/or prefixes) from, based on pool or subnet to allocate IP addresses (and/or prefixes), based on
the assigned client classes. The details can be found in the assigned client classes. The details can be found in
<xref linkend="high-availability-library"/>.</para> <xref linkend="high-availability-library"/>.</para>
<para>Other examples are: the ALL class which all incoming packets <para>Other examples are: the ALL class, which all incoming packets
belong to, and the KNOWN class assigned when host reservations exist belong to, and the KNOWN class, assigned when host reservations exist
for the particular client. By convention, builtin classes' names for a particular client. By convention, builtin classes' names
begin with all capital letters. begin with all capital letters.
</para> </para>
<para>Currently recognized builtin class names are ALL, KNOWN <para>Currently recognized builtin class names are ALL, KNOWN
and UNKNOWN, and prefixes VENDOR_CLASS_, HA_, AFTER_ and and UNKNOWN, and prefixes VENDOR_CLASS_, HA_, AFTER_, and
EXTERNAL_. The AFTER_ prefix is a provision for a not yet EXTERNAL_. Although the AFTER_ prefix is a provision for an as-yet-unwritten
written hook, the EXTERNAL_ prefix can be freely used: builtin hook, the EXTERNAL_ prefix can be freely used; builtin
classes are implicitly defined so never raise warnings if they classes are implicitly defined so they never raise warnings if they
do not appear in the configuration. do not appear in the configuration.
</para> </para>
</section> </section>
<section xml:id="classification-using-expressions"> <section xml:id="classification-using-expressions">
<title>Using Expressions In Classification</title> <title>Using Expressions in Classification</title>
<para> <para>
The expression portion of classification contains operators and 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 string or strings and return another string. When all the
operations have completed the result should be a value of operations have completed, the result should be a value of
&quot;true&quot; or &quot;false&quot;. The packet belongs to &quot;true&quot; or &quot;false&quot;. The packet belongs to
the class (and the class name is added to the list of classes) the class (and the class name is added to the list of classes)
if the result is &quot;true&quot;. Expressions are written in if the result is &quot;true&quot;. Expressions are written in
standard format and can be nested. standard format and can be nested.
@@ -230,10 +230,10 @@
Expressions are pre-processed during the parsing of the Expressions are pre-processed during the parsing of the
configuration file and converted to an internal configuration file and converted to an internal
representation. This allows certain types of errors to be caught representation. This allows certain types of errors to be caught
and logged during parsing. Examples of these errors include an and logged during parsing. Examples of these errors include an
incorrect number or types of arguments to an operator. The incorrect number or type of argument to an operator. The
evaluation code will also check for this class of error and evaluation code also checks for this class of error and
generally throw an exception, though this should not occur in a generally throws an exception, though this should not occur in a
normally functioning system. normally functioning system.
</para> </para>
@@ -244,17 +244,10 @@
</para> </para>
<para> <para>
Expressions are a work in progress and the supported operators and Dependencies between classes are also checked. For instance,
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
forward dependencies are rejected when the configuration is forward dependencies are rejected when the configuration is
parsed: an expression can only depend on already defined classes parsed; an expression can only depend on already-defined classes
(including builtin classes) and which are evaluated in a (including builtin classes) which are evaluated in a
previous or the same evaluation phase. This does not apply to previous or the same evaluation phase. This does not apply to
the KNOWN or UNKNOWN classes. the KNOWN or UNKNOWN classes.
</para> </para>
@@ -298,7 +291,7 @@
<entry>Integer literal</entry> <entry>Integer literal</entry>
<entry>123</entry> <entry>123</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/> <row/>
<row> <row>
@@ -396,7 +389,7 @@
<entry>pkt.len</entry> <entry>pkt.len</entry>
<entry>513</entry> <entry>513</entry>
<entry>The length of a DHCP packet (UDP header field), expressed <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>
<row> <row>
<entry>Hardware address in DHCPv4 packet</entry> <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> <entry>The value of the siaddr field of the DHCPv4 packet (IPv4 address, 4 bytes)</entry>
</row> </row>
<row> <row>
<entry>Message Type in DHCPv4 packet</entry> <entry>Message type in DHCPv4 packet</entry>
<entry>pkt4.msgtype</entry> <entry>pkt4.msgtype</entry>
<entry>1</entry> <entry>1</entry>
<entry>The value of the message type field in the DHCPv4 <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>
<row> <row>
<entry>Transaction ID (xid) in DHCPv4 packet</entry> <entry>Transaction ID (xid) in DHCPv4 packet</entry>
<entry>pkt4.transid</entry> <entry>pkt4.transid</entry>
<entry>12345</entry> <entry>12345</entry>
<entry>The value of the transaction id in the DHCPv4 <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>
<row> <row>
<entry>Message Type in DHCPv6 packet</entry> <entry>Message type in DHCPv6 packet</entry>
<entry>pkt6.msgtype</entry> <entry>pkt6.msgtype</entry>
<entry>1</entry> <entry>1</entry>
<entry>The value of the message type field in the DHCPv6 <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>
<row> <row>
<entry>Transaction ID in DHCPv6 packet</entry> <entry>Transaction ID in DHCPv6 packet</entry>
<entry>pkt6.transid</entry> <entry>pkt6.transid</entry>
<entry>12345</entry> <entry>12345</entry>
<entry>The value of the transaction id in the DHCPv6 <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>
<row> <row>
@@ -559,24 +552,24 @@
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
Hexadecimal strings are converted into a string as expected. The starting "0X" or 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 "0x" is removed, and if the string is an odd number of characters a
"0" is prepended to it. "0" is prepended to it.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
IP addresses are converted into strings of length 4 or 16. IPv4, IPv6, 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> </para></listitem>
<listitem><para> <listitem><para>
Integers in an expression are converted to 32 bit unsigned integers and Integers in an expression are converted to 32-bit unsigned integers and
are represented as four-byte strings. For example 123 is represented as are represented as four-byte strings; for example, 123 is represented as
0x0000007b. All expressions that return numeric values use 32-bit 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 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 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 bits, e.g. use 0x00000001 instead of 0x1 or 0x01. Also, make
sure the value is specified in network order, e.g. 1 is sure the value is specified in network order, e.g. 1 is
represented as 0x00000001. represented as 0x00000001.
@@ -585,20 +578,20 @@
<listitem><para> <listitem><para>
"option[code].hex" extracts the value of the option with the code "code" "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 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 returns an empty string. The string is presented as a byte string of
the option payload without the type code or length fields. the option payload, without the type code or length fields.
</para></listitem> </para></listitem>
<listitem><para> <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. in the incoming packet. It can be used with empty options.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
"member('foobar')" checks if the packet belongs to the client "member('foobar')" checks whether the packet belongs to the client
class "foobar". To avoid dependency loops the configuration file class "foobar". To avoid dependency loops, the configuration file
parser checks if client classes were already defined or are parser verifies whether client classes were already defined or are
built-in, i.e., beginning by &quot;VENDOR_CLASS_&quot;, builtin, i.e., beginning by &quot;VENDOR_CLASS_&quot;,
&quot;AFTER__&quot; (for the to come "after" hook) and &quot;AFTER__&quot; (for the to come "after" hook) and
&quot;EXTERNAL_&quot; or equal to &quot;ALL&quot;, &quot;KNOWN&quot;, &quot;EXTERNAL_&quot; or equal to &quot;ALL&quot;, &quot;KNOWN&quot;,
&quot;UNKNOWN&quot;etc. &quot;UNKNOWN&quot;etc.