Commit 5914d859 authored by Shawn Routhier's avatar Shawn Routhier
Browse files

[trac4101] Update v4 and v6 pages

Update the v4 and v6 pages to reflect the new classification.
These are shortened versions of the main classification page.

Also update the option description to incude .text and .hex modifiers.
parent df668f61
......@@ -34,10 +34,10 @@
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 two mechanisms that take
advantage of client classification: subnet selection and assigning different
options. For cable modems there are specific options for use with the TFTP
server address and the boot file field.
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
the TFTP server address and the boot file field.
</para>
<para>
......@@ -80,7 +80,7 @@
<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,
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.
......@@ -123,11 +123,17 @@
<para>
Expressions are pre-processed during the parsing of the configuration file
and converted to an internal representation. This allows certain types of
errors (such as incorrect syntax) to be caught and logged. Other errors
(for example mistakes when setting up the values for a substring) won't be
caught and may affect the classification. In general if an expression has
a problem a log message will be emitted at the debug level and the result
will be an empty string.
errors to be caught and logged during parsing. Examples of these errors
include 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 they should not occur in a normally functioning
system.
</para>
<para>
Other issues, for example the starting position of a substring being
outside of the substring or an option not existing in the packet, result
in the operator returning an empty string.
</para>
<para>
......@@ -147,7 +153,7 @@
<thead>
<row>
<entry>Name</entry>
<entry>Example</entry>
<entry>Example</entry>
<entry>Description</entry>
</row>
</thead>
......@@ -155,7 +161,8 @@
<row><entry>String</entry><entry>'example'</entry><entry>A string</entry></row>
<row><entry>Hex String</entry><entry>0XABCD</entry><entry>A hexadecimal string</entry></row>
<row><entry>Integer</entry><entry>123</entry><entry>An integer value</entry></row>
<row><entry>Option</entry><entry>option[code]</entry><entry>The value of the option with code "code" from the packet</entry></row>
<row><entry>Option Text</entry><entry>option[code].text</entry><entry>The value of the option with code "code" from the packet as text</entry></row>
<row><entry>Option Hex</entry><entry>option[code].hex</entry><entry>The value of the option with code "code" from the packet as hex</entry></row>
</tbody>
</tgroup>
</table>
......@@ -169,7 +176,10 @@
<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.
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.
</para>
<para>
......@@ -214,7 +224,7 @@
The name must exist and must be unique amongst all classes. The test
expression and option data are optional.
</para>
<para>
The test expression is a string containing the logical expression used to
determine membership in the class. The entire expression is in double
......@@ -240,7 +250,7 @@
<userinput>
{
"name": "Client_foo",
"test": "substring(option[61],0,3) == 'foo'",
"test": "substring(option[61].text,0,3) == 'foo'",
"option-data": [
{
"name": "doamin-name-servers",
......@@ -291,7 +301,7 @@
"client-class": [
{
"name": "Client_foo",
"test": "substring(option[61],0,3) == 'foo'",
"test": "substring(option[61].text,0,3) == 'foo'",
"option-data": [
{
"name": "doamin-name-servers",
......
......@@ -1558,58 +1558,154 @@ It is merely echoed by the server
<section id="dhcp4-client-classifier">
<title>Client Classification in DHCPv4</title>
<note>
<para>
The DHCPv4 server has been extended to support limited client classification.
Although the current capability is modest, it is expected to be expanded
in the future. However, it is envisaged that the majority of client classification
extensions will be using hooks extensions.
The DHCPv4 server includes support for client classification. At the
current time the capabilities of the classification process are limited
but it is expected they will be expanded in the future. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
</para>
</note>
<para>In certain cases it is useful to differentiate between different
types of clients and treat them differently. The process of doing
classification is conducted in two steps. The first step is to assess an
incoming packet and assign it to zero or more classes. This classification
is currently simple, but is expected to grow in capability soon. Currently
the server checks whether an incoming packet includes the vendor class identifier
option (60). If it does, the content of that option is prepended with
&quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
modern cable modems will send this option with value &quot;docsis3.0&quot;
and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
</para>
<para>It is envisaged that the client classification will be used for changing the
<para>
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 assigning
leases from different pools, assigning different options (or different values of
the same options) etc. For now, there are only two mechanisms that are taking
advantage of client classification: specific processing for cable modems and
subnet selection.</para>
the same options) etc. For now, there are only three mechanisms that are taking
advantage of client classification: subnet seletion, assigning different options,
and for cable modems there are 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.
</para>
<para>
There are two methods of doing classification. The first is automatic and relies
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
a member of the class.
</para>
<para>
Kea can be instructed to limit access to given subnets based on class information.
This is particularly useful for cases where two types of devices share the
same link and are expected to be served from two different subnets. The
primary use case for such a scenario is cable networks. There are two
classes of devices: the cable modem itself, which should be handed a lease
from subnet A and all other devices behind the modem that should get a lease
from subnet B. That segregation is essential to prevent overly curious
users from playing with their cable modems. For details on how to set up
class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
</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.
</para></note>
<section>
<title>Using Vendor Class Information in Classification</title>
<para>
The server checks whether an incoming packet includes the vendor class identifier
option (60). If it does, the content of that option is prepended with
&quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
modern cable modems will send this option with value &quot;docsis3.0&quot;
and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
</para>
<para>
For clients that belong to the VENDOR_CLASS_docsis3.0 class, the siaddr
field is set to the value of next-server (if specified in a subnet). If
there is a boot-file-name option specified, its value is also set in the
file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is
always set to 0.0.0.0. That capability is expected to be moved to
an external hook library that will be dedicated to cable modems.
</para>
</para>
</section>
<para>
Kea can be instructed to limit access to given subnets based on class information.
This is particularly useful for cases where two types of devices share the
same link and are expected to be served from two different subnets. The
primary use case for such a scenario is cable networks. There are two
classes of devices: the cable modem itself, which should be handed a lease
from subnet A and all other devices behind the modem that should get a lease
from subnet B. That segregation is essential to prevent overly curious
users from playing with their cable modems. For details on how to set up
class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
</para>
<section>
<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
return another string. When all the operations have completed
the result should be a value of &quot;true&quot; or &quot;false&quot;.
The packet belongs to
the class (and the class name is added to the list of classes) if the result
is &quot;true&quot;. Expressions are written in standard format and can be nested.
For more information about expressions see
<xref linkend="classification-using-expressions"/>
</para>
</section>
<section>
<title>Configuring Classes</title>
<para>
A class contains three items: a name, a test expression and option data.
The name must exist and must be unique amongst all classes. The test
expression and option data are optional.
</para>
<section id="dhcp4-subnet-class">
<title>Limiting Access to IPv4 Subnet to Certain Classes</title>
<para>
<para>
The test expression is a string containing the logical expression used to
determine membership in the class. The entire expression is in double
quotes.
</para>
<para>
The option data is a list which defines any options that should be assigned
to members of this class.
</para>
<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>
{
"name": "Client_foo",
"test": "substring(option[61].text,0,3) == 'foo'",
"option-data": [
{
"name": "doamin-name-servers",
"code": 6,
"space": "dhcp4",
"csv-format": true,
"data": "192.0.2.1, 192.0.2.2"
}
]
}
</userinput>
...
}</screen>
</para>
<para>
In this example the class named &quot;Client_foo&quot; is defined. It is comprised
of all clients who's client ids (option 61) start with the string &quot;foo&quot;.
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.
</para>
</section>
<section id="dhcp4-subnet-class">
<title>Limiting Access to IPv4 Subnet to Certain Classes</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="dhcp4-client-classifier"/>. This is an
......@@ -1631,13 +1727,8 @@ It is merely echoed by the server
],
...
}</screen>
</para>
<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>
</section>
</para>
</section>
</section>
<section id="dhcp4-ddns-config">
......
......@@ -1545,49 +1545,146 @@ should include options from the isc option space:
<section id="dhcp6-client-classifier">
<title>Client Classification in DHCPv6</title>
<note>
<para>
DHCPv6 server has been extended to support limited client classification.
Although the current capability is modest, it is expected to be expanded
in the future. It is envisaged that the majority of client classification
extensions will be using hooks extensions.
The DHCPv4 server includes support for client classification. At the
current time the capabilities of the classification process are limited
but it is expected they will be expanded in the future. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
</para>
</note>
<para>In certain cases it is useful to differentiate between different types
of clients and treat them differently. The process of doing classification
is conducted in two steps. The first step is to assess an incoming packet and
assign it to zero or more classes. This classification is currently simple,
but is expected to grow in capability soon. Currently the server checks whether
the incoming packet includes vendor class option (16). If it has, the content
of that option is prepended with &quot;VENDOR_CLASS_&quot; then it is interpreted as a
class. For example, modern cable modems will send this option with value
&quot;docsis3.0&quot; and as a result the packet will belong to class
&quot;VENDOR_CLASS_docsis3.0&quot;.
</para>
<para>It is envisaged that the client classification will be used for changing
<para>
In certain cases it is useful to differentiate between different types
of clients and treat them differently. It is envisaged that the client
classification will be used for changing the
behavior of almost any part of the DHCP engine processing, including assigning
leases from different pools, assigning different option (or different values of
the same options) etc. For now, there is only one mechanism that is taking
advantage of client classification: subnet selection.</para>
the same options) etc. For now, there are only two mechanisms that are taking
advantage of client classification: subnet selection and assigning differnet
options.
</para>
<para>
Kea can be instructed to limit access to given subnets based on class information.
This is particularly useful for cases where two types of devices share the
same link and are expected to be served from two different subnets. The
primary use case for such a scenario are cable networks. There are two
classes of devices: the cable modem itself, which should be handed a lease
from subnet A and all other devices behind modems that should get a lease
from subnet B. That segregation is essential to prevent overly curious
users from playing with their cable modems. For details on how to set up
class restrictions on subnets, see <xref linkend="dhcp6-subnet-class"/>.
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.
</para>
</section>
<para>
There are two methods of doing classification. The first is automatic and relies
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
a member of the class.
</para>
<section id="dhcp6-subnet-class">
<title>Limiting access to IPv6 subnet to certain classes</title>
<para>
Kea can be instructed to limit access to given subnets based on class information.
This is particularly useful for cases where two types of devices share the
same link and are expected to be served from two different subnets. The
primary use case for such a scenario is cable networks. There are two
classes of devices: the cable modem itself, which should be handed a lease
from subnet A and all other devices behind the modem that should get a lease
from subnet B. That segregation is essential to prevent overly curious
users from playing with their cable modems. For details on how to set up
class restrictions on subnets, see <xref linkend="dhcp6-subnet-class"/>.
</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.
</para></note>
<section>
<title>Using Vendor Class Information in Classification</title>
<para>
The server checks whether an incoming packet includes the vendor class
option (16). If it does, the content of that option is prepended with
&quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
modern cable modems will send this option with value &quot;docsis3.0&quot;
and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
</para>
</section>
<section>
<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
return another string. When all the operations have completed
the result should be a value of &quot;true&quot; or &quot;false&quot;.
The packet belongs to
the class (and the class name is added to the list of classes) if the result
is &quot;true&quot;. Expressions are written in standard format and can be nested.
For more information about expressions see
<xref linkend="classification-using-expressions"/>
</para>
</section>
<section>
<title>Configuring Classes</title>
<para>
A class contains three items: a name, a test expression and option data.
The name must exist and must be unique amongst all classes. The test
expression and option data are optional.
</para>
<para>
The test expression is a string containing the logical expression used to
determine membership in the class. The entire expression is in double
quotes.
</para>
<para>
The option data is a list which defines any options that should be assigned
to members of this class.
</para>
<para>
<screen>
"Dhcp6": {
"subnet6": [
{
"subnet": "2001:db8:1::/64",
"pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
"client-class": "Client_enterprise"
}
],
"client-class": [
<userinput>
{
"name": "Client_enterprise",
"test": "substring(option[2].hex,0,6) == 0x0002AABBCCDD'",
"option-data": [
{
"name": "dns-servers",
"code": 23,
"space": "dhcp6",
"csv-format": true,
"data": "2001:db8:0::1, 2001:db8:2::1"
}
]
}
</userinput>
...
}</screen>
</para>
<para>
In this example the class named &quot;Client_foo&quot; is defined. It is comprised
of all clients who's client identifiers start with the given hex string (which
would indicate a DUID based on an enterprise id of 0xAABBCCDD).
They will be given an address from 2001:db8:1::0 to 2001:db8:1::FFFF and
2001:db8:0::1 and 2001:db8:2::1 their domain name servers.
</para>
</section>
<section id="dhcp6-subnet-class">
<title>Limiting access to IPv6 subnet to certain classes</title>
<para>
In certain cases it beneficial to restrict access to certain subnets
only to clients that belong to a given class. For details on client
classes, see <xref linkend="dhcp6-client-classifier"/>. This is an
......@@ -1616,15 +1713,10 @@ should include options from the isc option space:
...
}
</screen>
</para>
<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>
</para>
</section>
</section>
<section id="dhcp6-ddns-config">
<title>Configuring DHCPv6 for DDNS</title>
<para>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment