|
|
@@ -11,60 +11,67 @@
|
|
|
<title>Client Classification Overview</title>
|
|
|
<para>
|
|
|
In certain cases it is useful to differentiate between different
|
|
|
- types of clients and treat them accordingly. There are many reasons
|
|
|
- why one might want to treat clients different some common reasons
|
|
|
- include:
|
|
|
+ types of clients and treat them accordingly. Common reasons include:
|
|
|
<itemizedlist>
|
|
|
<listitem><para>
|
|
|
- The clients represent different pieces of topology, for example a cable
|
|
|
- modem vs the clients behind that modem.
|
|
|
+ The clients represent different pieces of topology, e.g. a cable
|
|
|
+ modem is different to the clients behind that modem.
|
|
|
</para></listitem>
|
|
|
<listitem><para>
|
|
|
- The clients have different behavior, for example a smart phone vs a lapttop
|
|
|
- vs a desktop.
|
|
|
+ The clients have different behavior, e.g.a smart phone behaves
|
|
|
+ differently to a lapttop.
|
|
|
</para></listitem>
|
|
|
<listitem><para>
|
|
|
- The clients require different values for some options, for example a docsis3.0
|
|
|
- cable modem vs a docsis2.0 cable modem.
|
|
|
+ The clients require different values for some options, e.g. a docsis3.0
|
|
|
+ cable modem requires different settings to docsis2.0 cable modem.
|
|
|
</para></listitem>
|
|
|
</itemizedlist>
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
It is envisaged that client classification will be used for changing the
|
|
|
- behavior of almost any part of the DHCP message processing, including assigning
|
|
|
- leases from different pools, assigning different options (or different values of
|
|
|
- the same options) etc. For now, there are only three mechanisms that take
|
|
|
- advantage of client classification: subnet selection, assigning different
|
|
|
- options and for DHCPv4 cable modems there are specific options for use with
|
|
|
+ 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 three
|
|
|
+ mechanisms that take
|
|
|
+ advantage of client classification: subnet selection, 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 three steps. The first step
|
|
|
- is to assess an incoming packet and assign it to zero or more classes. The
|
|
|
- second step is to choose a subnet, possibly based on the class information.
|
|
|
- The third step is to assign options again possibly based on the class
|
|
|
- information.
|
|
|
+ The process of doing classification is conducted in three steps:
|
|
|
+ <orderedlist>
|
|
|
+ <listitem><para>
|
|
|
+ Assess an incoming packet and assign it to zero or more classes.
|
|
|
+ </para></listitem>
|
|
|
+ <listitem><para>
|
|
|
+ Choose a subnet, possibly based on the class information.
|
|
|
+ </para></listitem>
|
|
|
+ <listitem><para>
|
|
|
+ Assign options, again possibly based on the class information.
|
|
|
+ </para></listitem>
|
|
|
+ </orderedlist>
|
|
|
</para>
|
|
|
|
|
|
<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 the case two
|
|
|
- or more classes include an option the value from the first class will be used.
|
|
|
- Similarly if two or more classes are associated with a subnet the first subnet
|
|
|
- will be used. In the future the processing order of the various classes may
|
|
|
- be specified but for now it is being left unspecified and may change in
|
|
|
- future releases.
|
|
|
+ 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 same option, the value from the first class examined will
|
|
|
+ be used. Similarly if two or more classes are associated with a subnet, the
|
|
|
+ first class examined will be used. In the future the processing order of the
|
|
|
+ various classes may be specified but for now it is being left unspecified and
|
|
|
+ may change in future releases.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- For example imagine two classes. Class "foo" defines values for an NTP server
|
|
|
+ As an example, imagine two 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.
|
|
|
+ server will choose only one of the values for the reply: the class from which the
|
|
|
+ value is obtained is unspecified.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -72,23 +79,12 @@
|
|
|
on examining the values in the vendor class options. 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
|
|
|
- that is evaluated for each packet. If the result is true the packet is
|
|
|
+ that is evaluated for each packet. If the result is true, the packet is
|
|
|
a member of the class.
|
|
|
</para>
|
|
|
|
|
|
<note>
|
|
|
<para>
|
|
|
- The power of the expressions in the classification step is deliberately
|
|
|
- limited in order to minimize the amount of time required to process each
|
|
|
- expression. The expression for each class must be executed on each packet,
|
|
|
- if they are overly complex or time consuming they may impact the performance
|
|
|
- of the server. If you need complex or time consuming expressions you
|
|
|
- should write a hook to perform the necessary work.
|
|
|
- </para>
|
|
|
- </note>
|
|
|
-
|
|
|
- <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.
|
|
|
</para>
|
|
|
@@ -101,9 +97,9 @@
|
|
|
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_" then it is interpreted
|
|
|
+ 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 as a result the packet will belong to
|
|
|
+ value "docsis3.0" and so the packet will belong to
|
|
|
class "VENDOR_CLASS_docsis3.0".
|
|
|
</para>
|
|
|
</section>
|
|
|
@@ -112,7 +108,7 @@
|
|
|
<title>Using Expressions In Classification</title>
|
|
|
<para>
|
|
|
The expression portion of classification contains operators and values.
|
|
|
- Values are currently strings and operators take a string or strings and
|
|
|
+ All values are currently strings and 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
|
|
|
@@ -137,7 +133,7 @@
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- The expressions are a work in progress and the supported operators and
|
|
|
+ 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 it is expected the basic mechanisms will
|
|
|
remain the same.
|
|
|
@@ -166,20 +162,22 @@
|
|
|
</tbody>
|
|
|
</tgroup>
|
|
|
</table>
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
Hex 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>
|
|
|
|
|
|
<para>
|
|
|
- Option extracts the value of the given option from the incoming packet. If the
|
|
|
- packet doesn't contain the option it returns an empty string. The string can
|
|
|
- be presented as text or hex with the ".text" or ".hex" modifiers. In both
|
|
|
- cases only the payload is presented the type code and length fields aren't
|
|
|
- included.
|
|
|
+ Integers in the expression are converted to strings
|
|
|
+ when the expression is read into Kea.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ "option[code]" extracts the value of the option with the given code
|
|
|
+ from the incoming packet. If the packet doesn't contain the option, it
|
|
|
+ returns the empty string. The string can be presented as text or hex
|
|
|
+ with the ".text" or ".hex" modifiers. In both cases only the payload
|
|
|
+ is presented; the type code and length fields are not included.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -202,21 +200,28 @@
|
|
|
</tbody>
|
|
|
</tgroup>
|
|
|
</table>
|
|
|
- </para>
|
|
|
|
|
|
- <para>
|
|
|
- The substring operator substring(value, start, length) accepts both positive and
|
|
|
- negative values for the starting position and the length. For start a value of
|
|
|
+ The substring operator "substring(value, start, length)" accepts both positive and
|
|
|
+ negative values for the starting position and the length. For "start", a value of
|
|
|
0 is the first byte in the string while -1 is the last byte. If the starting
|
|
|
- point is outside of the original string an empty string is returned. Length
|
|
|
+ point is outside of the original string an empty string is returned. "length"
|
|
|
is the number of bytes to extract. A negative number means to count towards
|
|
|
- the beginning of the string but doesn't include the byte pointed to by start.
|
|
|
+ the beginning of the string but doesn't include the byte pointed to by "start".
|
|
|
The special value "all" means to return all bytes from start to the end of the
|
|
|
string. If length is longer than the remaining portion of the string then
|
|
|
the entire remaining portion is returned.
|
|
|
</para>
|
|
|
</section>
|
|
|
|
|
|
+ <note>
|
|
|
+ <para>
|
|
|
+ The expression for each class is executed on each packet received.
|
|
|
+ If the expressions are overly complex, the time taken to execute
|
|
|
+ them may impact the performance of the server. If you need
|
|
|
+ complex or time consuming expressions you should write a <link
|
|
|
+ linkend='hooks-libraries'>hook</link> to perform the necessary work.
|
|
|
+ </para> </note>
|
|
|
+
|
|
|
<section id="classification-configuring">
|
|
|
<title>Configuring Classes</title>
|
|
|
<para>
|
|
|
@@ -239,29 +244,22 @@
|
|
|
<para>
|
|
|
<screen>
|
|
|
"Dhcp4": {
|
|
|
- "subnet4": [
|
|
|
- {
|
|
|
- "subnet": "192.0.2.0/24",
|
|
|
- "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
|
|
|
- "client-class": "Client_foo"
|
|
|
- }
|
|
|
- ],
|
|
|
- "client-class": [
|
|
|
-<userinput>
|
|
|
+ "client-class": [<userinput>
|
|
|
{
|
|
|
"name": "Client_foo",
|
|
|
"test": "substring(option[61].text,0,3) == 'foo'",
|
|
|
"option-data": [
|
|
|
{
|
|
|
- "name": "doamin-name-servers",
|
|
|
+ "name": "domain-name-servers",
|
|
|
"code": 6,
|
|
|
"space": "dhcp4",
|
|
|
"csv-format": true,
|
|
|
"data": "192.0.2.1, 192.0.2.2"
|
|
|
}
|
|
|
]
|
|
|
- }
|
|
|
-</userinput>
|
|
|
+ },
|
|
|
+ ...
|
|
|
+ ],</userinput>
|
|
|
...
|
|
|
}</screen>
|
|
|
</para>
|
|
|
@@ -269,8 +267,8 @@
|
|
|
<para>
|
|
|
In this example the class named "Client_foo" is defined. It is comprised
|
|
|
of all clients who's client ids (option 61) start with the string "foo".
|
|
|
- They will be given an address from 192.0.2.10 to 192.0.2.20 and 192.0.2.1
|
|
|
- and 192.0.2.2 as their domain name servers.
|
|
|
+ Members of this class will be given 192.0.2.1 and 192.0.2.2 as their domain name
|
|
|
+ servers.
|
|
|
</para>
|
|
|
</section>
|
|
|
|
|
|
@@ -278,9 +276,7 @@
|
|
|
<title>Configuring Subnets With Class Information</title>
|
|
|
<para>
|
|
|
In certain cases it beneficial to restrict access to certain subnets
|
|
|
- only to clients that belong to a given subnet. For details on client
|
|
|
- classes, see <xref linkend="classification-using-vendor"/> and
|
|
|
- <xref linkend="classification-using-expressions"/>
|
|
|
+ only to clients that belong to a given class.
|
|
|
Let's assume that the server is connected to a network segment that uses
|
|
|
the 192.0.2.0/24 prefix. The Administrator of that network has decided
|
|
|
that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
|
|
|
@@ -289,29 +285,29 @@
|
|
|
configuration can be achieved in the following way:
|
|
|
<screen>
|
|
|
"Dhcp4": {
|
|
|
- "subnet4": [
|
|
|
-<userinput>
|
|
|
- {
|
|
|
- "subnet": "192.0.2.0/24",
|
|
|
- "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
|
|
|
- "client-class": "Client_foo"
|
|
|
- }
|
|
|
-</userinput>
|
|
|
- ],
|
|
|
"client-class": [
|
|
|
{
|
|
|
"name": "Client_foo",
|
|
|
"test": "substring(option[61].text,0,3) == 'foo'",
|
|
|
"option-data": [
|
|
|
{
|
|
|
- "name": "doamin-name-servers",
|
|
|
+ "name": "domain-name-servers",
|
|
|
"code": 6,
|
|
|
"space": "dhcp4",
|
|
|
"csv-format": true,
|
|
|
"data": "192.0.2.1, 192.0.2.2"
|
|
|
}
|
|
|
]
|
|
|
+ },
|
|
|
+ ...
|
|
|
+ ],<userinput>
|
|
|
+ "subnet4": [
|
|
|
+ {
|
|
|
+ "subnet": "192.0.2.0/24",
|
|
|
+ "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
|
|
|
+ "client-class": "Client_foo"
|
|
|
}
|
|
|
+ ]</userinput>,
|
|
|
...
|
|
|
}</screen>
|
|
|
</para>
|
|
|
@@ -321,12 +317,13 @@
|
|
|
<title>Using Classes</title>
|
|
|
<para>
|
|
|
Currently classes can be used for two functions. They can supply options
|
|
|
- to the members class and they can choose a subnet for the members of the class.
|
|
|
+ to the members of the class and they can be used to choose a subnet from which an
|
|
|
+ address will be assigned to the class member.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- When supplying options class options defined as part of the class definition
|
|
|
- are considred "class globals". They will override any global options that
|
|
|
+ When supplying options, options defined as part of the class definition
|
|
|
+ are considered "class globals". They will override any global options that
|
|
|
may be defined and in turn will be overridden by any options defined for an
|
|
|
individual subnet.
|
|
|
</para>
|
Stephen Morris