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

[master] Merge branch 'trac2642'

Browse Source
This commit is contained in:
Stephen Morris
2013-01-23 10:26:10 +00:00
parent ffa68930da 7bed043f81
commit e5faeb5fa8
1 changed files with 397 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

682
doc/guide/bind10-guide.xml
View File

@@ -740,6 +740,15 @@ as a dependency earlier -->
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>--with-dhcp-mysql</term>
<listitem>
<simpara>Enable MySQL support for BIND 10 DHCP. For notes on configuring
and building DHCP with MySQL see <xref linkend="dhcp-install-configure">.</xref>
</simpara>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
@@ -761,9 +770,7 @@ as a dependency earlier -->
dependencies. dependencies.
</para> </para>
<note>
<para>For notes on configuring and building DHCPv6 with MySQL see <xref linkend="dhcp6-install">.</xref></para>
</note>
</section> </section>
<section> <section>
@@ -3317,9 +3324,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</chapter> </chapter>
<chapter id="dhcp4"> <chapter id="dhcp">
<title>DHCPv4 Server</title> <title>DHCP</title>
<para>Dynamic Host Configuration Protocol for IPv4 (DHCP or <para>The Dynamic Host Configuration Protocol for IPv4 (DHCP or
DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6) DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
are protocols that allow one node (server) to provision are protocols that allow one node (server) to provision
configuration parameters to many hosts and devices (clients). To configuration parameters to many hosts and devices (clients). To
@@ -3327,57 +3334,113 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
be deployed that facilitate communication between servers and be deployed that facilitate communication between servers and
clients. Even though principles of both DHCPv4 and DHCPv6 are clients. Even though principles of both DHCPv4 and DHCPv6 are
somewhat similar, these are two radically different somewhat similar, these are two radically different
protocols. BIND 10 offers server implementations for both DHCPv4 protocols. BIND 10 offers two server implementations, one for DHCPv4
and DHCPv6. This chapter is about DHCP for IPv4. For a description and one for DHCPv6.</para>
of the DHCPv6 server, see <xref linkend="dhcp6"/>.</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"/>,
<para>The DHCPv4 server component is currently under intense while those details specific to DHCPv6 are described in <xref linkend="dhcp6"/>
development. You may want to check out <ulink </para>
url="http://bind10.isc.org/wiki/Kea">BIND 10 DHCP (Kea) wiki</ulink>
and recent posts on <ulink <section id="dhcp-install-configure">
url="https://lists.isc.org/mailman/listinfo/bind10-dev">BIND 10 <title>DHCP Database Installation and Configuration</title>
developers mailing list</ulink>.</para>
<para>The DHCPv4 and DHCPv6 components in BIND 10 architecture are
internally code named <quote>Kea</quote>.</para>
<note>
<para> <para>
As of January 2013, the DHCPv4 component is a work in progress. BIND 10 DHCP stores its leases in a lease database. The software has been written in
That means that while it is capable of performing DHCP configuration, a way that makes it possible to choose which database product should be used to
it is not fully functional. The server is able to offer, store the lease information. At present, only support for MySQL is provided, and that support must
assign, renew, release and reuse expired leases, but some of the be explicitly included when BIND 10 is built. This section covers the building of
options are not configurable yet. In particular Router option is hardcoded. BIND 10 with MySQL and the creation of the lease database.
This means that the server is not really usable in actual deployments
yet. See <xref linkend="dhcp4-limit"/> for a detailed description.
</para> </para>
</note> <section>
<title>Install MySQL</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
</para>
</section>
<section>
<title>Build and Install BIND 10</title>
<para>
Build and install BIND 10 as described in <xref linkend="installation"/>, with
the following modification: to enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), specify the location of the
MySQL configuration program "mysql_config" with the "--with-mysql-config" switch,
i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
...if MySQL was installed in the default location, or:
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
...if not.
</para>
</section>
<section id="dhcp-database-create">
<title>Create MySQL Database and BIND 10 User</title>
<para>
The next task is to create both the lease database and the user under which the servers will
access it. A number of steps are required:
</para>
<para>
1. Log into MySQL as "root":
<screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
:<userinput/>
mysql></screen>
</para>
<para>
2. Create the database:
<screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
... <replaceable>database-name</replaceable> is the name you have chosen for the database.
</para>
<para>
3. Create the database tables:
<screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
mysql> <userinput>SOURCE <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
</para>
<para>
4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
<screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
</para>
<para>
5. Exit MySQL:
<screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
</para>
</section>
</section>
<section id="dhcp4-usage"> </chapter>
<title>DHCPv4 Server Usage</title>
<para>BIND 10 has provided the DHCPv4 server component since December <chapter id="dhcp4">
2011. It is current experimental implementation and is not fully functional <title>The DHCPv4 Server</title>
yet. It is mature enough to conduct tests in lab environment, but it has
significant limitations. See <xref linkend="dhcp4-limit"/> for <section id="dhcp4-start-stop">
details. <title>Starting and Stopping the DHCPv4 Server</title>
</para>
<para> <para>
<command>b10-dhcp4</command> is a BIND 10 component and is being <command>b10-dhcp4</command> is the BIND 10 DHCPv4 server and, like other
run under BIND 10 framework. To add a DHCPv4 process to the set of running parts of BIND 10, is configured through the <command>bindctl</command>
BIND 10 services, you can use following commands in <command>bindctl</command>: program.
<screen>&gt; <userinput>config add Boss/components b10-dhcp4</userinput> </para>
<para>
After starting BIND 10 and entering bindctl, the first step
in configuring the server is to add it to the list of running BIND 10 services.
<screen>
&gt; <userinput>config add Boss/components b10-dhcp4</userinput>
&gt; <userinput>config set Boss/components/b10-dhcp4/kind dispensable</userinput> &gt; <userinput>config set Boss/components/b10-dhcp4/kind dispensable</userinput>
&gt; <userinput>config commit</userinput></screen></para> &gt; <userinput>config commit</userinput>
</screen>
<para> </para>
To stop running <command>b10-dhcp4</command>, please use the <para>
following command: To remove <command>b10-dhcp4</command> from the set of running services,
<screen>&gt; <userinput>config remove Boss/components b10-dhcp4</userinput> the <command>b10-dhcp4</command> is removed from list of Boss components:
&gt; <userinput>config commit</userinput></screen></para> <screen>
&gt; <userinput>config remove Boss/components b10-dhcp4</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para> <para>
During start-up the server will detect available network interfaces On start-up, the server will detect available network interfaces
and will attempt to open UDP sockets on all interfaces that and will attempt to open UDP sockets on all interfaces that
are up, running, are not loopback, and have IPv4 address are up, running, are not loopback, and have IPv4 address
assigned. assigned.
@@ -3392,23 +3455,29 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</section> </section>
<section id="dhcp4-config"> <section id="dhcp4-configuration">
<title>DHCPv4 Server Configuration</title> <title>Configuring the DHCPv4 Server</title>
<para> <para>
Once the server is started, it can be configured. To view the Once the server is started, it can be configured. To view the
current configuration, use the following command in <command>bindctl</command>: current configuration, use the following command in <command>bindctl</command>:
<screen> <screen>
&gt; <userinput>config show Dhcp4</userinput></screen> &gt; <userinput>config show Dhcp4</userinput></screen>
When starting Dhcp4 daemon for the first time, the default configuration When starting the DHCPv4 daemon for the first time, the default configuration
will be available. It will look similar to this: will be available. It will look similar to this:
<screen> <screen>
&gt; <userinput>config show Dhcp4</userinput> &gt; <userinput>config show Dhcp4</userinput>
Dhcp4/interface/ list (default) Dhcp4/interface/ list (default)
Dhcp4/renew-timer 1000 integer (default) Dhcp4/renew-timer 1000 integer (default)
Dhcp4/rebind-timer 2000 integer (default) Dhcp4/rebind-timer 2000 integer (default)
Dhcp4/preferred-lifetime 3000 integer (default) Dhcp4/valid-lifetime 4000 integer (default)
Dhcp4/valid-lifetime 4000 integer (default) Dhcp4/option-data [] list (default)
Dhcp4/subnet4 [] list (default)</screen> Dhcp4/lease-database/type "memfile" string (default)
Dhcp4/lease-database/name "" string (default)
Dhcp4/lease-database/user "" string (default)
Dhcp4/lease-database/host "" string (default)
Dhcp4/lease-database/password "" string (default)
Dhcp4/subnet4 [] list (default)
</screen>
</para> </para>
<para> <para>
@@ -3423,6 +3492,69 @@ Dhcp4/subnet4 [] list (default)</screen>
per-subnet basis. per-subnet basis.
</para> </para>
<section>
<title>Database Configuration</title>
<para>
All leases issued by the server are stored in the lease database. Currently,
the only supported database is MySQL
<footnote>
<para>
The server comes with an in-memory database ("memfile") configured as the default
database. This is used for internal testing and is not supported. In addition,
it does not store lease information on disk: lease information will be lost if the
server is restarted.
</para>
</footnote>, and so the server must be configured to
access the correct database with the appropriate credentials.
</para>
<note>
<para>
Database access information must be configured for the DHCPv4 server, even if
it has already been configured for the DHCPv6 server. The servers store their
information independently, so each server can use a separate
database or both servers can use the same database.
</para>
</note>
<para>
Database configuration is controlled through the Dhcp4/lease-database parameters.
The type of the database must be set to MySQL (although the string entered is "mysql"):
<screen>
&gt; <userinput>config set Dhcp4/lease-database/type "mysql"</userinput>
</screen>
Next, the name of the database is to hold the leases must be set: this is the
name used when the lease database was created (see <xref linkend="dhcp-database-create"/>).
<screen>
&gt; <userinput>config set Dhcp4/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
</screen>
If the database is located on a different system to the DHCPv4 server, the
database host name must also be specified (although note that this configuration
may have a severe impact on server performance):
<screen>
&gt; <userinput>config set Dhcp4/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
</screen>
The usual state of affairs will be to have the database on the same machine as the
DHCPv4 server. In this case, set the value to the empty string (this is the default):
<screen>
&gt; <userinput>config set Dhcp4/lease-database/host ""</userinput>
</screen>
</para>
<para>
Finally, the credentials of the account under which the server will access the database
should be set:
<screen>
&gt; <userinput>config set Dhcp4/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
&gt; <userinput>config set Dhcp4/lease-database/password "<replaceable>password</replaceable>"</userinput>
</screen>
If there is no password to the account, set the password to the empty string "". (This is also the default.)
</para>
<note>
<para>The password is echoed when entered and is stored in clear text in the BIND 10 configuration
database. Improved password security will be added in a future version of BIND 10 DHCP</para>
</note>
</section>
<section id="dhcp4-address-config">
<title>Configuration of Address Pools</title>
<para> <para>
The essential role of DHCPv4 server is address assignment. The server 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 has to be configured with at least one subnet and one pool of dynamic
@@ -3462,7 +3594,7 @@ Dhcp4/subnet4 [] list (default)</screen>
&gt; <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput> &gt; <userinput>config set Dhcp4/subnet4[1]/pool [ "192.0.3.0/24" ]</userinput>
&gt; <userinput>config commit</userinput></screen> &gt; <userinput>config commit</userinput></screen>
Arrays are counted from 0. subnet[0] refers to the subnet defined in the Arrays are counted from 0. subnet[0] refers to the subnet defined in the
previous example. The <command>config add Dhcp4/subnet4</command> adds previous example. The <command>config add Dhcp4/subnet4</command> command adds
another (second) subnet. It can be referred to as another (second) subnet. It can be referred to as
<command>Dhcp4/subnet4[1]</command>. In this example, we allow server to <command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
dynamically assign all addresses available in the whole subnet. dynamically assign all addresses available in the whole subnet.
@@ -3474,23 +3606,9 @@ Dhcp4/subnet4 [] list (default)</screen>
address) and the last (typically broadcast address) address from that pool. address) and the last (typically broadcast address) address from that pool.
In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and In the aforementioned example of pool 192.0.3.0/24, both 192.0.3.0 and
192.0.3.255 addresses may be assigned as well. This may be invalid in some 192.0.3.255 addresses may be assigned as well. This may be invalid in some
network configurations. If you want to avoid this, please use min-max notation. network configurations. If you want to avoid this, please use the "min-max" notation.
</para>
<para>
Note: Although configuration is now accepted, some parts of it is not internally used
by they server yet. Address pools are used, but option definitons are not.
The only way to alter some options (e.g. Router Option or DNS servers and Domain name)
is to modify source code. To do so, please edit
src/bin/dhcp6/dhcp4_srv.cc file, modify the following parameters and
recompile:
<screen>
const std::string HARDCODED_GATEWAY = "192.0.2.1";
const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";</screen>
Lease database and configuration support is planned for end of 2012.
</para> </para>
</section>
</section> </section>
<section id="dhcp4-serverid"> <section id="dhcp4-serverid">
@@ -3514,36 +3632,44 @@ const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";</screen>
</section> </section>
<section id="dhcp4-std"> <section id="dhcp4-std">
<title>Supported standards</title> <title>Supported Standards</title>
<para>The following standards and draft standards are currently <para>The following standards and draft standards are currently
supported:</para> supported:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara>RFC2131: Supported messages are DISCOVER, OFFER, <simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
REQUEST, ACK, NAK, RELEASE.</simpara> REQUEST, RELEASE, ACK, and NAK.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>RFC2132: Supported options are: PAD (0), <simpara><ulink url="http://tools.ietf.org/html/rfc2132">RFC 2132</ulink>: Supported options are: PAD (0),
END(255), Message Type(53), DHCP Server Identifier (54), END(255), Message Type(53), DHCP Server Identifier (54),
Domain Name (15), DNS Servers (6), IP Address Lease Time Domain Name (15), DNS Servers (6), IP Address Lease Time
(51), Subnet mask (1), and Routers (3).</simpara> (51), Subnet mask (1), and Routers (3).</simpara>
</listitem> </listitem>
<listitem>
<simpara>RFC6842: Server responses include client-id option
if client sent it in its message.</simpara>
</listitem>
</itemizedlist> </itemizedlist>
</section> </section>
<section id="dhcp4-limit"> <section id="dhcp4-limit">
<title>DHCPv4 Server Limitations</title> <title>DHCPv4 Server Limitations</title>
<para>These are the current limitations of the DHCPv4 server <para>These are the current limitations of the DHCPv4 server
software. Most of them are reflections of the early stage of software. Most of them are reflections of the current stage of
development and should be treated as <quote>not implemented development and should be treated as <quote>not implemented
yet</quote>, rather than actual limitations.</para> yet</quote>, rather than actual limitations.</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara>During initial IPv4 node configuration, the <para>
On startup, the DHCPv4 server does not get the full configuration from
BIND 10. To remedy this, after starting BIND 10, modify any parameter
and commit the changes, e.g.
<screen>
&gt; <userinput>config show Dhcp4/renew-timer</userinput>
Dhcp4/renew-timer 1000 integer (default)
&gt; <userinput>config set Dhcp4/renew-timer 1001</userinput>
&gt; <userinput>config commit</userinput></screen>
</para>
</listitem>
<listitem>
<simpara>During the initial IPv4 node configuration, the
server is expected to send packets to a node that does not server is expected to send packets to a node that does not
have IPv4 address assigned yet. The server requires have IPv4 address assigned yet. The server requires
certain tricks (or hacks) to transmit such packets. This certain tricks (or hacks) to transmit such packets. This
@@ -3551,184 +3677,91 @@ const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";</screen>
relayed traffic only (that is, normal point to point relayed traffic only (that is, normal point to point
communication).</simpara> communication).</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>Upon start, the server will open sockets on all <simpara>Upon start, the server will open sockets on all
interfaces that are not loopback, are up and running and interfaces that are not loopback, are up and running and
have IPv4 address.</simpara> have IPv4 address.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>PRL (Parameter Request List, a list of options <simpara>The DHCPv4 server does not support
requested by a client) is currently ignored and server BOOTP. That is a design choice and the limitation is
assigns DNS SERVER and DOMAIN NAME options.</simpara>
</listitem>
<listitem>
<simpara><command>b10-dhcp4</command> does not support
BOOTP. That is a design choice. This limitation is
permanent. If you have legacy nodes that can't use DHCP and permanent. If you have legacy nodes that can't use DHCP and
require BOOTP support, please use the latest version of ISC DHCP require BOOTP support, please use the latest version of ISC DHCP,
via <ulink url="http://www.isc.org/software/dhcp"/>.</simpara> available from <ulink url="http://www.isc.org/software/dhcp"/>.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>Interface detection is currently working on Linux <simpara>Interface detection is currently working on Linux
only. See <xref linkend="iface-detect"/> for details.</simpara> only. See <xref linkend="iface-detect"/> for details.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara><command>b10-dhcp4</command> does not verify that <simpara>The DHCPv4 server does not verify that
assigned address is unused. According to RFC2131, the assigned address is unused. According to <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>, the
allocating server should verify that address is no used by allocating server should verify that address is not used by
sending ICMP echo request.</simpara> sending ICMP echo request.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>Address rebinding (REQUEST/Rebinding), confirmation <simpara>Address rebinding (REBIND) and duplication report (DECLINE)
(CONFIRM) and duplication report (DECLINE) are not supported are not supported yet.</simpara>
yet.</simpara>
</listitem>
<listitem>
<simpara>DNS Update is not supported yet.</simpara>
</listitem>
<listitem>
<simpara>-v (verbose) command line option is currently
the default, and cannot be disabled.</simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
</chapter> </chapter>
<chapter id="dhcp6"> <chapter id="dhcp6">
<title>DHCPv6 Server</title> <title>The DHCPv6 Server</title>
<para>The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is
specified in RFC3315. BIND 10 provides a DHCPv6 server implementation
that is described in this chapter. For a description of the DHCPv4
server implementation, see <xref linkend="dhcp4"/>.
</para>
<para>The DHCPv6 server component is currently under intense <section id="dhcp6-start-stop">
development. You may want to check out <ulink <title>Starting and Stopping the DHCPv6 Server</title>
url="http://bind10.isc.org/wiki/Kea">BIND 10 DHCP (Kea) wiki</ulink>
and recent posts on <ulink
url="https://lists.isc.org/mailman/listinfo/bind10-dev">BIND 10
developers mailing list</ulink>.</para>
<note>
<para> <para>
As of November 2012, the DHCPv6 component is partially functioning, <command>b10-dhcp6</command> is the BIND 10 DHCPv6 server and, like other
having the following capabilities: parts of BIND 10, is configured through the <command>bindctl</command>
program.
</para> </para>
<itemizedlist>
<listitem>
<simpara>DHCPv6 server able to allocate leases (but not renew them).</simpara>
</listitem>
<listitem>
<simpara>Some configuration available through the BIND 10 configuration mechanism.</simpara>
</listitem>
<listitem>
<simpara>Lease storage in a MySQL database.</simpara>
</listitem>
</itemizedlist>
</note>
<section id="dhcp6-install">
<title>DHCPv6 Server Build and Installation</title>
<para> <para>
DHCPv6 is part of the BIND 10 suite of programs and is built as part of After starting BIND 10 and starting <command>bindctl</command>, the first step
the build of BIND 10. With the use of MySQL, some additional in configuring the server is to add <command>b10-dhcp6</command> to the list of running BIND 10 services.
installation steps are needed: <screen>
</para> &gt; <userinput>config add Boss/components b10-dhcp6</userinput>
<section>
<title>Install MySQL</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
</para>
</section>
<section>
<title>Build and Install BIND 10</title>
<para>
Build and install BIND 10 as described in <xref linkend="installation"/>, with
the following modification: to enable the MySQL database code, the
"configure" step (see <xref linkend="configure"/>), specify the location of the
MySQL configuration program "mysql_config" with the "--with-mysql-config" switch,
i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
...if MySQL was installed in the default location, or:
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>&lt;path-to-mysql_config&gt;</replaceable></userinput></screen>
...if not.
</para>
</section>
<section>
<title>Create MySQL Database and BIND 10 User</title>
<para>
The next task is to create both the DHCPv6 lease database and the user under which the DHCPv6 server will
access it. Although the intention is to have the name of the database and the user configurable,
at the moment they are hard-coded as "kea", as is the associated password. ("kea" is an internal
code name for BIND 10 DHCP.) There are a number of steps required:
</para>
<para>
1. Log into MySQL as "root":
<screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
:<userinput/>
mysql></screen>
</para>
<para>
2. Create the database:
<screen>mysql> <userinput>CREATE DATABASE kea;</userinput></screen>
</para>
<para>
3. Create the database tables:
<screen>mysql> <userinput>CONNECT kea;</userinput>
mysql> <userinput>SOURCE <replaceable>&lt;path-to-bind10&gt;</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
</para>
<para>
4. Create the user under which BIND 10 will access the database and grant it access to the database tables:
<screen>mysql> <userinput>CREATE USER 'kea'@'localhost' IDENTIFIED BY 'kea';</userinput>
mysql> <userinput>GRANT ALL ON kea.* TO 'kea'@'localhost';</userinput></screen>
</para>
<para>
5. Exit MySQL:
<screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
</para>
</section>
</section>
<section id="dhcp6-usage">
<title>DHCPv6 Server Usage</title>
<para>
<command>b10-dhcp6</command> is a BIND 10 component and is being
run under BIND 10 framework. To add a DHCPv6 process to the set of running
BIND 10 services, you can use following commands in <command>bindctl</command>:
<screen>&gt; <userinput>config add Boss/components b10-dhcp6</userinput>
&gt; <userinput>config set Boss/components/b10-dhcp6/kind dispensable</userinput> &gt; <userinput>config set Boss/components/b10-dhcp6/kind dispensable</userinput>
&gt; <userinput>config commit</userinput></screen> &gt; <userinput>config commit</userinput>
</screen>
</para> </para>
<para>
<para> To remove <command>b10-dhcp6</command> from the set of running services,
To stop running <command>b10-dhcp6</command>, use the the <command>b10-dhcp4</command> is removed from list of Boss components:
following command: <screen>
<screen>&gt; <userinput>config remove Boss/components b10-dhcp6</userinput> &gt; <userinput>config remove Boss/components b10-dhcp6</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para>
To change one of the parameters, simply follow
the usual <command>bindctl</command> procedure. For example, to make the
leases longer, change their valid-lifetime parameter:
<screen>
&gt; <userinput>config set Dhcp6/valid-lifetime 7200</userinput>
&gt; <userinput>config commit</userinput></screen> &gt; <userinput>config commit</userinput></screen>
</para> Please note that most Dhcp6 parameters are of global scope
and apply to all defined subnets, unless they are overridden on a
per-subnet basis.
</para>
<para> <para>
During start-up the server will detect available network interfaces During start-up the server will detect available network interfaces
and will attempt to open UDP sockets on all interfaces that and will attempt to open UDP sockets on all interfaces that
are up, running, are not loopback, are multicast-capable, and are up, running, are not loopback, are multicast-capable, and
have IPv6 address assigned. It will then listen to incoming traffic. The have IPv6 address assigned. It will then listen to incoming traffic.
currently supported client messages are SOLICIT and REQUEST. The server
will respond to them with ADVERTISE and REPLY, respectively.
</para>
<para>
Since the DHCPv6 server opens privileged ports, it requires root
access. Make sure you run this daemon as root.
</para> </para>
</section> </section>
<section id="dhcp6-config"> <section id="dhcp6-configuration">
<title>DHCPv6 Server Configuration</title> <title>DHCPv6 Server Configuration</title>
<para> <para>
Once the server has been started, it can be configured. To view the Once the server has been started, it can be configured. To view the
@@ -3736,16 +3769,22 @@ $</screen>
<screen>&gt; <userinput>config show Dhcp6</userinput></screen> <screen>&gt; <userinput>config show Dhcp6</userinput></screen>
When starting the Dhcp6 daemon for the first time, the default configuration When starting the Dhcp6 daemon for the first time, the default configuration
will be available. It will look similar to this: will be available. It will look similar to this:
<screen> <screen>
&gt; <userinput>config show Dhcp6</userinput> &gt; <userinput>config show Dhcp6</userinput>
Dhcp6/interface "eth0" string (default) Dhcp6/interface/ list (default)
Dhcp6/renew-timer 1000 integer (default) Dhcp6/renew-timer 1000 integer (default)
Dhcp6/rebind-timer 2000 integer (default) Dhcp6/rebind-timer 2000 integer (default)
Dhcp6/preferred-lifetime 3000 integer (default) Dhcp6/preferred-lifetime 3000 integer (default)
Dhcp6/valid-lifetime 4000 integer (default) Dhcp6/valid-lifetime 4000 integer (default)
Dhcp6/subnet6 [] list (default)</screen> Dhcp6/option-data [] list (default)
Dhcp6/lease-database/type "memfile" string (default)
Dhcp6/lease-database/name "" string (default)
Dhcp6/lease-database/user "" string (default)
Dhcp6/lease-database/host "" string (default)
Dhcp6/lease-database/password "" string (default)
Dhcp6/subnet6/ list
</screen>
</para> </para>
<para> <para>
To change one of the parameters, simply follow To change one of the parameters, simply follow
the usual <command>bindctl</command> procedure. For example, to make the the usual <command>bindctl</command> procedure. For example, to make the
@@ -3757,7 +3796,77 @@ Dhcp6/subnet6 [] list (default)</screen>
and apply to all defined subnets, unless they are overridden on a and apply to all defined subnets, unless they are overridden on a
per-subnet basis. per-subnet basis.
</para> </para>
<note>
<para>
With this version of BIND 10, there are a number of known limitations
and problems in the DHCPv6 server. See <xref linkend="dhcp6-limit"/>.
</para>
</note>
<section>
<title>Database Configuration</title>
<para>
All leases issued by the server are stored in the lease database. Currently,
the only supported database is MySQL
<footnote>
<para>
The server comes with an in-memory database ("memfile") configured as the default
database. This is used for internal testing and is not supported. In addition,
it does not store lease information on disk: lease information will be lost if the
server is restarted.
</para>
</footnote>, and so the server must be configured to
access the correct database with the appropriate credentials.
</para>
<note>
<para>
Database access information must be configured for the DHCPv6 server, even if
it has already been configured for the DHCPv4 server. The servers store their
information independently, so each server can use a separate
database or both servers can use the same database.
</para>
</note>
<para>
Database configuration is controlled through the Dhcp6/lease-database parameters.
The type of the database must be set to MySQL (although the string entered is "mysql"):
<screen>
&gt; <userinput>config set Dhcp6/lease-database/type "mysql"</userinput>
</screen>
Next, the name of the database is to hold the leases must be set: this is the
name used when the lease database was created (see <xref linkend="dhcp-database-create"/>).
<screen>
&gt; <userinput>config set Dhcp6/lease-database/name "<replaceable>database-name</replaceable>"</userinput>
</screen>
If the database is located on a different system to the DHCPv6 server, the
database host name must also be specified (although note that this configuration
may have a severe impact on server performance):
<screen>
&gt; <userinput>config set Dhcp6/lease-database/host "<replaceable>remote-host-name</replaceable>"</userinput>
</screen>
The usual state of affairs will be to have the database on the same machine as the
DHCPv6 server. In this case, set the value to the empty string (this is the default):
<screen>
&gt; <userinput>config set Dhcp6/lease-database/host ""</userinput>
</screen>
</para>
<para>
Finally, the credentials of the account under which the server will access the database
should be set:
<screen>
&gt; <userinput>config set Dhcp6/lease-database/user "<replaceable>user-name</replaceable>"</userinput>
&gt; <userinput>config set Dhcp6/lease-database/password "<replaceable>password</replaceable>"</userinput>
</screen>
If there is no password to the account, set the password to the empty string "". (This is also the default.)
</para>
<note>
<para>The password is echoed when entered and is stored in clear text in the BIND 10 configuration
database. Improved password security will be added in a future version of BIND 10 DHCP</para>
</note>
</section>
<section>
<title>Subnet and Address Pool</title>
<para> <para>
The essential role of a DHCPv6 server is address assignment. For this, The essential role of a DHCPv6 server is address assignment. For this,
the server has to be configured with at least one subnet and one pool of dynamic the server has to be configured with at least one subnet and one pool of dynamic
@@ -3797,7 +3906,7 @@ Dhcp6/subnet6 [] list (default)</screen>
&gt; <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput> &gt; <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
&gt; <userinput>config commit</userinput></screen> &gt; <userinput>config commit</userinput></screen>
Arrays are counted from 0. subnet[0] refers to the subnet defined in the Arrays are counted from 0. subnet[0] refers to the subnet defined in the
previous example. The <command>config add Dhcp6/subnet6</command> adds previous example. The <command>config add Dhcp6/subnet6</command> command adds
another (second) subnet. It can be referred to as another (second) subnet. It can be referred to as
<command>Dhcp6/subnet6[1]</command>. In this example, we allow server to <command>Dhcp6/subnet6[1]</command>. In this example, we allow server to
dynamically assign all addresses available in the whole subnet. Although dynamically assign all addresses available in the whole subnet. Although
@@ -3810,7 +3919,7 @@ Dhcp6/subnet6 [] list (default)</screen>
a given pool, it will be able to allocate also first (typically network a given pool, it will be able to allocate also first (typically network
address) address from that pool. For example for pool 2001:db8::/64 the address) address from that pool. For example for pool 2001:db8::/64 the
2001:db8:: address may be assigned as well. If you want to avoid this, 2001:db8:: address may be assigned as well. If you want to avoid this,
please use min-max notation. please use the "min-max" notation.
</para> </para>
<para> <para>
Options can also be configured: the following commands configure Options can also be configured: the following commands configure
@@ -3825,7 +3934,7 @@ Dhcp6/subnet6 [] list (default)</screen>
&gt; <userinput>config commit</userinput> &gt; <userinput>config commit</userinput>
</screen> </screen>
(The value for the setting of the "data" element is split across two (The value for the setting of the "data" element is split across two
lines in this document for clarity: when entering the command, all the lines in this document for clarity: when entering the command, the whole
string should be entered on the same line.) string should be entered on the same line.)
</para> </para>
<para> <para>
@@ -3849,13 +3958,45 @@ Dhcp6/subnet6 [] list (default)</screen>
(As before, the setting of the "data" element has been split across two (As before, the setting of the "data" element has been split across two
lines for clarity.) lines for clarity.)
</para> </para>
<note>
<para>
With this version of BIND 10, there are a number of known limitations
and problems in the DHCPv6 server. See <xref linkend="dhcp6-limit"/>.
</para>
</note>
</section> </section>
<section id="dhcp6-config-subnets">
<title>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.
<note>
<para>
Currently relayed DHCPv6 traffic is not supported. The server will
only respond to local DHCPv6 requests - see <xref linkend="dhcp6-limit"/>
</para>
</note>
As it may have many subnet configurations defined, it
must select appropriate subnet for a given request. To do this, the server first
checks if there is only one subnet defined and source of the packet is
link-local. If this is the case, the server assumes that the only subnet
defined is local and client is indeed connected to it. This check
simplifies small deployments.
</para>
<para>
If there are two or more subnets defined, the server can not assume
which of those (if any) subnets are local. Therefore an optional
"interface" parameter is available within a subnet definition to designate that a given subnet
is local, i.e. reachable directly over specified interface. For example
the server that is intended to serve a local subnet over eth0 may be configured
as follows:
<screen>
&gt; <userinput>config add Dhcp6/subnet6</userinput>
&gt; <userinput>config set Dhcp6/subnet6[1]/subnet "2001:db8:beef::/48"</userinput>
&gt; <userinput>config set Dhcp6/subnet6[1]/pool [ "2001:db8:beef::/48" ]</userinput>
&gt; <userinput>config set Dhcp6/subnet6[1]/interface "eth0"</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
</section>
</section>
<section id="dhcp6-serverid"> <section id="dhcp6-serverid">
<title>Server Identifier in DHCPv6</title> <title>Server Identifier in DHCPv6</title>
@@ -3888,12 +4029,11 @@ Dhcp6/subnet6 [] list (default)</screen>
supported:</para> supported:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara>RFC3315: Supported messages are SOLICIT, <simpara><ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>: Supported messages are SOLICIT,
ADVERTISE, REQUEST, and REPLY. Supported options are ADVERTISE, REQUEST, RELEASE, RENEW, and REPLY.</simpara>
SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>RFC3646: Supported option is DNS_SERVERS.</simpara> <simpara><ulink url="http://tools.ietf.org/html/rfc3646">RFC 3646</ulink>: Supported option is DNS_SERVERS.</simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
@@ -3905,20 +4045,8 @@ Dhcp6/subnet6 [] list (default)</screen>
software. Most of them are reflections of the early stage of software. Most of them are reflections of the early stage of
development and should be treated as <quote>not implemented development and should be treated as <quote>not implemented
yet</quote>, rather than actual limitations.</para> yet</quote>, rather than actual limitations.</para>
<para>
<itemizedlist> <itemizedlist>
<listitem>
<para>The DHCPv6 server has only been tested on Debian
operating systems. There are known problems with the
handling of packets in CentOS and RHEL.</para>
</listitem>
<listitem>
<para>Relayed traffic is not supported.</para>
</listitem>
<listitem>
<para><command>b10-dhcp6</command> only supports
a limited number of configuration options.</para>
</listitem>
<listitem> <listitem>
<para> <para>
On startup, the DHCPv6 server does not get the full configuration from On startup, the DHCPv6 server does not get the full configuration from
@@ -3932,40 +4060,26 @@ Dhcp6/renew-timer 1000 integer (default)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Upon start, the server will open sockets on all <simpara>Relayed traffic is not supported.</simpara>
interfaces that are not loopback, are up, running and are
multicast capable and have IPv6 address. Support for
multiple interfaces is not coded in reception routines yet,
so if you are running this code on a machine that has many
interfaces and <command>b10-dhcp6</command> happens to
listen on wrong interface, the easiest way to work around
this problem is to turn down other interfaces. This
limitation will be fixed shortly.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>ORO (Option Request Option, a list of options <simpara>Temporary addresses are not supported.</simpara>
requested by a client) is currently unsupported.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Temporary addresses are not supported.</para> <simpara>Prefix delegation is not supported.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<para>Prefix delegation is not supported.</para> <simpara>Rebinding (REBIND), confirmation (CONFIRM),
and duplication report (DECLINE) are not yet supported.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<para>Address renewal (RENEW), rebinding (REBIND), <simpara>DNS Update is not supported.</simpara>
confirmation (CONFIRM), duplication report (DECLINE) and
release (RELEASE) are not supported.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>DNS Update is not supported.</para> <simpara>Interface detection is currently working on Linux
</listitem> only. See <xref linkend="iface-detect"/> for details.</simpara>
<listitem>
<para>Interface detection is currently working on Linux
only. See <xref linkend="iface-detect"/> for details.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para>
</section> </section>
</chapter> </chapter>
@@ -3974,7 +4088,7 @@ Dhcp6/renew-timer 1000 integer (default)
<title>libdhcp++ library</title> <title>libdhcp++ library</title>
<para> <para>
libdhcp++ is a common library written in C++ that handles libdhcp++ is a common library written in C++ that handles
many DHCP-related tasks, including many DHCP-related tasks, including:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara> <simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara>
@@ -3992,10 +4106,8 @@ Dhcp6/renew-timer 1000 integer (default)
</para> </para>
<para> <para>
While this library is currently used by While this library is currently used by BIND 10 DHCP, it is designed to
<command>b10-dhcp4</command> and <command>b10-dhcp6</command> be a portable, universal library, useful for any kind of DHCP-related software.
only, it is designed to be a portable, universal library, useful for
any kind of DHCP-related software.
</para> </para>
<!-- TODO: point to doxygen docs --> <!-- TODO: point to doxygen docs -->