BIND 10 trac3274, updated. 41328ae3ce0eddddc4bb7c3752ba22b476c1bbf2 [3274] DHCPv6 sections about client classification in User's Guide added
BIND 10 source code commits
bind10-changes at lists.isc.org
Tue Feb 4 13:03:43 UTC 2014
The branch, trac3274 has been updated
via 41328ae3ce0eddddc4bb7c3752ba22b476c1bbf2 (commit)
via d52f14789d9dc775b3a7f8da71dcd923affb2168 (commit)
from b6f93473fc3c57fa2e74f223ddd1a65cd7f6238d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 41328ae3ce0eddddc4bb7c3752ba22b476c1bbf2
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Tue Feb 4 14:03:30 2014 +0100
[3274] DHCPv6 sections about client classification in User's Guide added
commit d52f14789d9dc775b3a7f8da71dcd923affb2168
Author: Tomek Mrugalski <tomasz at isc.org>
Date: Tue Feb 4 13:54:01 2014 +0100
[3274] DHCPv4 section of User's Guide written
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 167 ++++++++++++++++++++++++++++++++++++++++++--
src/bin/dhcp4/dhcp4.dox | 6 ++
src/bin/dhcp6/dhcp6.dox | 6 ++
3 files changed, 173 insertions(+), 6 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 88425e2..b2acd63 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -39,7 +39,7 @@
servers with development managed by Internet Systems Consortium (ISC).
It includes DNS libraries, modular components for controlling
authoritative and recursive DNS servers, and experimental DHCPv4
- and DHCPv6 servers.
+ and DHCPv6 servers (codenamed Kea).
</para>
<para>
This is the reference guide for BIND 10 version &__VERSION__;.
@@ -3523,7 +3523,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
clients. Even though principles of both DHCPv4 and DHCPv6 are
somewhat similar, these are two radically different
protocols. BIND 10 offers two server implementations, one for DHCPv4
- and one for DHCPv6.</para>
+ and one for DHCPv6. The DHCP part of the BIND 10 project is codenamed
+ Kea. The DHCPv4 component is colloquially referred to as Kea4 and its
+ DHCPv6 is called Kea6.</para>
<para>This chapter covers those parts of BIND 10 that are common to
both servers. DHCPv4-specific details are covered in <xref linkend="dhcp4"/>,
while those details specific to DHCPv6 are described in <xref linkend="dhcp6"/>
@@ -3803,7 +3805,7 @@ Dhcp4/subnet4 [] list (default)
</section>
<section id="dhcp4-address-config">
- <title>Configuration of Address Pools</title>
+ <title>Configuration of IPv4 Address Pools</title>
<para>
The essential role of DHCPv4 server is address assignment. The server
has to be configured with at least one subnet and one pool of dynamic
@@ -4383,7 +4385,87 @@ Dhcp4/subnet4 [] list (default)
e.g. "123" - would then be assigned to the uint16 field in the "container" option.
</para>
</section>
- </section>
+
+ <section id="dhcp4-client-classifier">
+ <title>Client Classification in DHCPv4</title>
+ <note>
+ <para>
+ 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. It is envisaged that the majority of client classification
+ extensions will be using hooks extensions.
+ </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 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
+ incoming packet has vendor class identifier option (60). If it has, content
+ of that option 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 class "docsis3.0".
+ </para>
+
+ <para>It is envisaged that the client classification will be used for changing
+ 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 are only two mechanisms that are taking
+ advantage of client classification: specific processing for cable modems and
+ subnet selection.</para>
+
+ <para>
+ For clients that belong to the docsis3.0 class, the siaddr field is set to
+ the value of next-server (if specified in a subnet). If there is
+ 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 external hook
+ library that will be dedicated to cable modems.
+ </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: cable modem itself, which should be handled 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="dhcp4-subnet-class"/>.
+ </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 certains subnets
+ only to clients that belong to a given subnet. For details on client
+ classes, see <xref linkend="dhcp4-client-classifier"/>. This is an
+ extension of a previous example from <xref linkend="dhcp4-address-config"/>.
+ 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
+ managed by the Dhcp4 server. Only clients belonging to client class
+ docsis3.0 are allowed to use this subnet. Such a configuration can be
+ achieved in the following way:
+ <screen>
+> <userinput>config add Dhcp4/subnet4</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/subnet "192.0.2.0/24"</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/pool [ "192.0.2.10 - 192.0.2.20" ]</userinput>
+> <userinput>config set Dhcp4/subnet4[0]/client-class "docsis3.0"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>
+ Care should be taken with client classification as it is easy to prevent
+ clients that do not meet class criteria to be denied any service altogether.
+ </para>
+ </section>
+
+ </section> <!-- end of configuring DHCPv4 server section with many subsections -->
+
<section id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
<para>
@@ -4401,6 +4483,7 @@ Dhcp4/subnet4 [] list (default)
</para>
</section>
+
<section id="dhcp4-next-server">
<title>Next server (siaddr)</title>
<para>In some cases, clients want to obtain configuration from the TFTP server.
@@ -4467,6 +4550,8 @@ Dhcp4/subnet4 [] list (default)
<listitem>
<simpara><ulink url="http://tools.ietf.org/html/rfc3046">RFC 3046</ulink>:
Relay Agent Information option is supported.</simpara>
+ </listitem>
+ <listitem>
<simpara><ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>:
Server by default sends back client-id option. That capability may be
disabled. See <xref linkend="dhcp4-echo-client-id"/> for details.
@@ -4773,7 +4858,7 @@ Dhcp6/subnet6/ list
</para>
</section>
- <section>
+ <section id="dhcp6-address-config">
<title>Subnet and Address Pool</title>
<para>
The essential role of a DHCPv6 server is address assignment. For this,
@@ -5277,7 +5362,7 @@ should include options from the isc option space:
</section>
<section id="dhcp6-config-subnets">
- <title>Subnet Selection</title>
+ <title>IPv6 Subnet Selection</title>
<para>
The DHCPv6 server may receive requests from local (connected to the
same subnet as the server) and remote (connecting via relays) clients.
@@ -5365,6 +5450,76 @@ should include options from the isc option space:
</para>
</section>
+ <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.
+ </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 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
+ incoming packet has vendor class option (16). If it has, content
+ of that option 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 class "docsis3.0".
+ </para>
+
+ <para>It is envisaged that the client classification will be used for changing
+ 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>
+
+ <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: cable modem itself, which should be handled 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"/>.
+ </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 certains subnets
+ only to clients that belong to a given subnet. For details on client
+ classes, see <xref linkend="dhcp6-client-classifier"/>. This is an
+ extension of a previous example from <xref linkend="dhcp6-address-config"/>.
+
+ Let's assume that the server is connected to a network segment that uses
+ the 2001:db8:1::/64 prefix. The Administrator of that network has
+ decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are
+ going to be managed by the Dhcp6 server. Only clients belonging to the
+ eRouter1.0 client class are allowed to use that pool. Such a
+ configuration can be achieved in the following way:
+
+ <screen>
+> <userinput>config add Dhcp6/subnet6</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/subnet "2001:db8:1::/64"</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/pool [ "2001:db8:1::0 - 2001:db8:1::ffff" ]</userinput>
+> <userinput>config set Dhcp6/subnet6[0]/client-class "eRouter1.0"</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>
+ Care should be taken with client classification as it is easy to prevent
+ clients that do not meet class criteria to be denied any service altogether.
+ </para>
+ </section>
+
</section>
<section id="dhcp6-serverid">
diff --git a/src/bin/dhcp4/dhcp4.dox b/src/bin/dhcp4/dhcp4.dox
index aa43ee3..5182f73 100644
--- a/src/bin/dhcp4/dhcp4.dox
+++ b/src/bin/dhcp4/dhcp4.dox
@@ -185,6 +185,12 @@ library. See ticket #3275. The class specific behavior is:
Aforementioned modifications are conducted in @ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing.
+It is possible to define class restrictions in subnet, so a given subnet is only
+accessible to clients that belong to a given class. That is implemented as isc::dhcp::Pkt4::classes_
+being passed in isc::dhcp::Dhcpv4Srv::selectSubnet() to isc::dhcp::CfgMgr::getSubnet4().
+Currently this capability is usable, but the number of scenarios it supports is
+limited.
+
@section dhcpv4Other Other DHCPv4 topics
For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
diff --git a/src/bin/dhcp6/dhcp6.dox b/src/bin/dhcp6/dhcp6.dox
index c722472..3eb6994 100644
--- a/src/bin/dhcp6/dhcp6.dox
+++ b/src/bin/dhcp6/dhcp6.dox
@@ -217,6 +217,12 @@ Currently there is no class behaviour coded in DHCPv6, hence no v6 equivalent of
@ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing. Should any need for such a code arise,
it will be conducted in an external hooks library.
+It is possible to define class restrictions in subnet, so a given subnet is only
+accessible to clients that belong to a given class. That is implemented as isc::dhcp::Pkt4::classes_
+being passed in isc::dhcp::Dhcpv4Srv::selectSubnet() to isc::dhcp::CfgMgr::getSubnet4().
+Currently this capability is usable, but the number of scenarios it supports is
+limited.
+
@section dhcpv6Other Other DHCPv6 topics
For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
More information about the bind10-changes
mailing list