mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-01 06:25:34 +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

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

@@ -740,6 +740,15 @@ as a dependency earlier -->
</listitem>
</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>
</para>
@@ -761,9 +770,7 @@ as a dependency earlier -->
dependencies.
</para>
<note>
<para>For notes on configuring and building DHCPv6 with MySQL see <xref linkend="dhcp6-install">.</xref></para>
</note>
</section>
<section>
@@ -3317,9 +3324,9 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</chapter>
<chapter id="dhcp4">
<title>DHCPv4 Server</title>
<para>Dynamic Host Configuration Protocol for IPv4 (DHCP or
<chapter id="dhcp">
<title>DHCP</title>
<para>The Dynamic Host Configuration Protocol for IPv4 (DHCP or
DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
are protocols that allow one node (server) to provision
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
clients. Even though principles of both DHCPv4 and DHCPv6 are
somewhat similar, these are two radically different
protocols. BIND 10 offers server implementations for both DHCPv4
and DHCPv6. This chapter is about DHCP for IPv4. For a description
of the DHCPv6 server, see <xref linkend="dhcp6"/>.</para>
<para>The DHCPv4 server component is currently under intense
development. You may want to check out <ulink
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>
<para>The DHCPv4 and DHCPv6 components in BIND 10 architecture are
internally code named <quote>Kea</quote>.</para>
<note>
<para>
As of January 2013, the DHCPv4 component is a work in progress.
That means that while it is capable of performing DHCP configuration,
it is not fully functional. The server is able to offer,
assign, renew, release and reuse expired leases, but some of the
options are not configurable yet. In particular Router option is hardcoded.
This means that the server is not really usable in actual deployments
yet. See <xref linkend="dhcp4-limit"/> for a detailed description.
</para>
</note>
<section id="dhcp4-usage">
<title>DHCPv4 Server Usage</title>
<para>BIND 10 has provided the DHCPv4 server component since December
2011. It is current experimental implementation and is not fully functional
yet. It is mature enough to conduct tests in lab environment, but it has
significant limitations. See <xref linkend="dhcp4-limit"/> for
details.
protocols. BIND 10 offers two server implementations, one for DHCPv4
and one for DHCPv6.</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"/>
</para>
<section id="dhcp-install-configure">
<title>DHCP Database Installation and Configuration</title>
<para>
<command>b10-dhcp4</command> is a BIND 10 component and is being
run under BIND 10 framework. To add a DHCPv4 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-dhcp4</userinput>
BIND 10 DHCP stores its leases in a lease database. The software has been written in
a way that makes it possible to choose which database product should be used to
store the lease information. At present, only support for MySQL is provided, and that support must
be explicitly included when BIND 10 is built. This section covers the building of
BIND 10 with MySQL and the creation of the lease database.
</para>
<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>
</chapter>
<chapter id="dhcp4">
<title>The DHCPv4 Server</title>
<section id="dhcp4-start-stop">
<title>Starting and Stopping the DHCPv4 Server</title>
<para>
<command>b10-dhcp4</command> is the BIND 10 DHCPv4 server and, like other
parts of BIND 10, is configured through the <command>bindctl</command>
program.
</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 commit</userinput></screen></para>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para>
To remove <command>b10-dhcp4</command> from the set of running services,
the <command>b10-dhcp4</command> is removed from list of Boss components:
<screen>
&gt; <userinput>config remove Boss/components b10-dhcp4</userinput>
&gt; <userinput>config commit</userinput>
</screen>
</para>
<para>
To stop running <command>b10-dhcp4</command>, please use the
following command:
<screen>&gt; <userinput>config remove Boss/components b10-dhcp4</userinput>
&gt; <userinput>config commit</userinput></screen></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
are up, running, are not loopback, and have IPv4 address
assigned.
@@ -3392,23 +3455,29 @@ then change those defaults with config set Resolver/forward_addresses[0]/address
</section>
<section id="dhcp4-config">
<title>DHCPv4 Server Configuration</title>
<section id="dhcp4-configuration">
<title>Configuring the DHCPv4 Server</title>
<para>
Once the server is started, it can be configured. To view the
current configuration, use the following command in <command>bindctl</command>:
<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:
<screen>
<screen>
&gt; <userinput>config show Dhcp4</userinput>
Dhcp4/interface/ list (default)
Dhcp4/renew-timer 1000 integer (default)
Dhcp4/rebind-timer 2000 integer (default)
Dhcp4/preferred-lifetime 3000 integer (default)
Dhcp4/valid-lifetime 4000 integer (default)
Dhcp4/subnet4 [] list (default)</screen>
Dhcp4/option-data [] list (default)
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>
@@ -3423,6 +3492,69 @@ Dhcp4/subnet4 [] list (default)</screen>
per-subnet basis.
</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>
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
@@ -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 commit</userinput></screen>
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
<command>Dhcp4/subnet4[1]</command>. In this example, we allow server to
dynamically assign all addresses available in the whole subnet.
@@ -3474,24 +3606,10 @@ Dhcp4/subnet4 [] list (default)</screen>
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
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.
</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.
network configurations. If you want to avoid this, please use the "min-max" notation.
</para>
</section>
</section>
<section id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
@@ -3514,36 +3632,44 @@ const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";</screen>
</section>
<section id="dhcp4-std">
<title>Supported standards</title>
<title>Supported Standards</title>
<para>The following standards and draft standards are currently
supported:</para>
<itemizedlist>
<listitem>
<simpara>RFC2131: Supported messages are DISCOVER, OFFER,
REQUEST, ACK, NAK, RELEASE.</simpara>
<simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
REQUEST, RELEASE, ACK, and NAK.</simpara>
</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),
Domain Name (15), DNS Servers (6), IP Address Lease Time
(51), Subnet mask (1), and Routers (3).</simpara>
</listitem>
<listitem>
<simpara>RFC6842: Server responses include client-id option
if client sent it in its message.</simpara>
</listitem>
</itemizedlist>
</section>
<section id="dhcp4-limit">
<title>DHCPv4 Server Limitations</title>
<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
yet</quote>, rather than actual limitations.</para>
<itemizedlist>
<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
have IPv4 address assigned yet. The server requires
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
communication).</simpara>
</listitem>
<listitem>
<simpara>Upon start, the server will open sockets on all
interfaces that are not loopback, are up and running and
have IPv4 address.</simpara>
</listitem>
<listitem>
<simpara>PRL (Parameter Request List, a list of options
requested by a client) is currently ignored and server
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
<simpara>The DHCPv4 server does not support
BOOTP. That is a design choice and the limitation is
permanent. If you have legacy nodes that can't use DHCP and
require BOOTP support, please use the latest version of ISC DHCP
via <ulink url="http://www.isc.org/software/dhcp"/>.</simpara>
require BOOTP support, please use the latest version of ISC DHCP,
available from <ulink url="http://www.isc.org/software/dhcp"/>.</simpara>
</listitem>
<listitem>
<simpara>Interface detection is currently working on Linux
only. See <xref linkend="iface-detect"/> for details.</simpara>
</listitem>
<listitem>
<simpara><command>b10-dhcp4</command> does not verify that
assigned address is unused. According to RFC2131, the
allocating server should verify that address is no used by
<simpara>The DHCPv4 server does not verify that
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 not used by
sending ICMP echo request.</simpara>
</listitem>
<listitem>
<simpara>Address rebinding (REQUEST/Rebinding), confirmation
(CONFIRM) and duplication report (DECLINE) are not supported
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>
<simpara>Address rebinding (REBIND) and duplication report (DECLINE)
are not supported yet.</simpara>
</listitem>
</itemizedlist>
</section>
</chapter>
<chapter id="dhcp6">
<title>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>
<title>The DHCPv6 Server</title>
<para>The DHCPv6 server component is currently under intense
development. You may want to check out <ulink
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>
As of November 2012, the DHCPv6 component is partially functioning,
having the following capabilities:
</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>
DHCPv6 is part of the BIND 10 suite of programs and is built as part of
the build of BIND 10. With the use of MySQL, some additional
installation steps are needed:
</para>
<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>
<section id="dhcp6-start-stop">
<title>Starting and Stopping the DHCPv6 Server</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>
<command>b10-dhcp6</command> is the BIND 10 DHCPv6 server and, like other
parts of BIND 10, is configured through the <command>bindctl</command>
program.
</para>
<para>
After starting BIND 10 and starting <command>bindctl</command>, the first step
in configuring the server is to add <command>b10-dhcp6</command> to the list of running BIND 10 services.
<screen>
&gt; <userinput>config add Boss/components b10-dhcp6</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>
To stop running <command>b10-dhcp6</command>, use the
following command:
<screen>&gt; <userinput>config remove Boss/components b10-dhcp6</userinput>
To remove <command>b10-dhcp6</command> from the set of running services,
the <command>b10-dhcp4</command> is removed from list of Boss components:
<screen>
&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>
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>
During start-up the server will detect available network interfaces
and will attempt to open UDP sockets on all interfaces that
are up, running, are not loopback, are multicast-capable, and
have IPv6 address assigned. It will then listen to incoming traffic. The
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.
have IPv6 address assigned. It will then listen to incoming traffic.
</para>
</section>
<section id="dhcp6-config">
<section id="dhcp6-configuration">
<title>DHCPv6 Server Configuration</title>
<para>
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>
When starting the Dhcp6 daemon for the first time, the default configuration
will be available. It will look similar to this:
<screen>
<screen>
&gt; <userinput>config show Dhcp6</userinput>
Dhcp6/interface "eth0" string (default)
Dhcp6/interface/ list (default)
Dhcp6/renew-timer 1000 integer (default)
Dhcp6/rebind-timer 2000 integer (default)
Dhcp6/preferred-lifetime 3000 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>
To change one of the parameters, simply follow
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
per-subnet basis.
</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>
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
@@ -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 commit</userinput></screen>
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
<command>Dhcp6/subnet6[1]</command>. In this example, we allow server to
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
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,
please use min-max notation.
please use the "min-max" notation.
</para>
<para>
Options can also be configured: the following commands configure
@@ -3825,7 +3934,7 @@ Dhcp6/subnet6 [] list (default)</screen>
&gt; <userinput>config commit</userinput>
</screen>
(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.)
</para>
<para>
@@ -3849,12 +3958,44 @@ Dhcp6/subnet6 [] list (default)</screen>
(As before, the setting of the "data" element has been split across two
lines for clarity.)
</para>
</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>
With this version of BIND 10, there are a number of known limitations
and problems in the DHCPv6 server. See <xref linkend="dhcp6-limit"/>.
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">
@@ -3888,12 +4029,11 @@ Dhcp6/subnet6 [] list (default)</screen>
supported:</para>
<itemizedlist>
<listitem>
<simpara>RFC3315: Supported messages are SOLICIT,
ADVERTISE, REQUEST, and REPLY. Supported options are
SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS.</simpara>
<simpara><ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>: Supported messages are SOLICIT,
ADVERTISE, REQUEST, RELEASE, RENEW, and REPLY.</simpara>
</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>
</itemizedlist>
</section>
@@ -3905,20 +4045,8 @@ Dhcp6/subnet6 [] list (default)</screen>
software. Most of them are reflections of the early stage of
development and should be treated as <quote>not implemented
yet</quote>, rather than actual limitations.</para>
<para>
<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>
<para>
On startup, the DHCPv6 server does not get the full configuration from
@@ -3932,40 +4060,26 @@ Dhcp6/renew-timer 1000 integer (default)
</para>
</listitem>
<listitem>
<para>Upon start, the server will open sockets on all
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>
<simpara>Relayed traffic is not supported.</simpara>
</listitem>
<listitem>
<para>ORO (Option Request Option, a list of options
requested by a client) is currently unsupported.</para>
<simpara>Temporary addresses are not supported.</simpara>
</listitem>
<listitem>
<para>Temporary addresses are not supported.</para>
<simpara>Prefix delegation is not supported.</simpara>
</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>
<para>Address renewal (RENEW), rebinding (REBIND),
confirmation (CONFIRM), duplication report (DECLINE) and
release (RELEASE) are not supported.</para>
<simpara>DNS Update is not supported.</simpara>
</listitem>
<listitem>
<para>DNS Update is not supported.</para>
</listitem>
<listitem>
<para>Interface detection is currently working on Linux
only. See <xref linkend="iface-detect"/> for details.</para>
<simpara>Interface detection is currently working on Linux
only. See <xref linkend="iface-detect"/> for details.</simpara>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>
@@ -3974,7 +4088,7 @@ Dhcp6/renew-timer 1000 integer (default)
<title>libdhcp++ library</title>
<para>
libdhcp++ is a common library written in C++ that handles
many DHCP-related tasks, including
many DHCP-related tasks, including:
<itemizedlist>
<listitem>
<simpara>DHCPv4 and DHCPv6 packets parsing, manipulation and assembly</simpara>
@@ -3992,10 +4106,8 @@ Dhcp6/renew-timer 1000 integer (default)
</para>
<para>
While this library is currently used by
<command>b10-dhcp4</command> and <command>b10-dhcp6</command>
only, it is designed to be a portable, universal library, useful for
any kind of DHCP-related software.
While this library is currently used by BIND 10 DHCP, it is designed to
be a portable, universal library, useful for any kind of DHCP-related software.
</para>
<!-- TODO: point to doxygen docs -->