Commit 8d87f8f5 authored by Stephen Morris's avatar Stephen Morris
Browse files

[4101] Miscellaneous documentation changes during review

parent 9a50be70
......@@ -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,21 +79,10 @@
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
......@@ -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 &quot;VENDOR_CLASS_&quot; then it is interpreted
option is prepended with &quot;VENDOR_CLASS_&quot; and the result 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
value &quot;docsis3.0&quot; and so the packet will belong to
class &quot;VENDOR_CLASS_docsis3.0&quot;.
</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 &quot;true&quot; or &quot;false&quot;.
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 &quot;0X&quot; or
&quot;0x&quot; is removed and if the string is an odd number of characters a
&quot;0&quot; 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 &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.
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 &quot;class globals&quot;. They will override any global options that
When supplying options, options defined as part of the class definition
are considered &quot;class globals&quot;. 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>
......
......@@ -1547,7 +1547,7 @@ should include options from the isc option space:
<title>Client Classification in DHCPv6</title>
<para>
The DHCPv4 server includes support for client classification. At the
The DHCPv6 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"/>.
......@@ -2664,7 +2664,7 @@ should include options from the isc option space:
from the clients and administrators
frequently use that information to perform certain tasks, like per host
configuration, address reserveration for specific MAC addresses and other.
Unfortunately, DHCPv6 protocol does not provide any completely reliable way
Unfortunately, the DHCPv6 protocol does not provide any completely reliable way
to retrieve that information. To mitigate that issue a number of mechanisms
have been implemented in Kea that attempt to gather that information. Each
of those mechanisms works in certain cases, but may fail in other cases.
......
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