<section id="dhcp4-configuration">
<title>Configuring the DHCPv4 Server</title>
+<section>
+ <title>Introduction</title>
<para>
- This section explains how to configure DHCPv4 server that uses
+ This section explains how to configure the DHCPv4 server using the
Kea configuration backend. Kea configuration using any other
backends is outside of scope for this document. Before DHCPv4
- is started, its configuration file has to be prepared. The
+ is started, its configuration file has to be created. The
basic configuration looks as follows:
<screen>
{
}
} </screen>
-Note that line numbers are specified for easier reference only and
-are not part of the configuration. The examples in following sections do not
-have reference numbers.</para>
+</para>
-<para>The following paragraphs provide brief overview of the parameters and
-their format. Following sections in this chapter go into much greater details
-for aforementioned parameters and also introduce new ones.</para>
+<para>The following paragraphs provide a brief overview of the parameters in
+the above example and
+their format. Subsequent sections of this chapter go into much greater detail
+for these and other parameters.</para>
-<para>The lines starting with a hash (#) are comments and do not impact the server
+<para>The lines starting with a hash (#) are comments and are ignored by
+the server; they do not impact its
operation in any way.</para>
-<para>The configuration starts in the first line with the initial opening curly
-bracket. Each configuration consists of one or more objects. In this specific
-example, we have only one object called Dhcp4. This is a simplified
-configuration, as usually there will be additional objects, like
-<command>Logging</command> or <command>DhcpDns</command>, but we omit them now
-for clarity. The Dhcp4 configuration starts after the first comment
-("<command>Dhcp4</command>": {) and ends after the last comment (}). Everything
-defined between those lines is considered Dhcp4 configuration.</para>
-
-<para>In general case, the order in which those parameters appear doesn't
-matter. There are two caveats here, though. The first one is to remember that
+<para>The configuration starts in the first line with the initial
+opening curly bracket (or brace). Each configuration consists of
+one or more objects. In this specific example, we have only one
+object called Dhcp4. This is a simplified configuration, as usually
+there will be additional objects, like <command>Logging</command> or
+<command>DhcpDns</command>, but we omit them now for clarity. The Dhcp4
+configuration starts with the the <command>"Dhcp4: {"</command> line
+and ends with the corresponding closing brace (in the above example,
+the brace after the last comment). Everything defined between those
+lines is considered to be the Dhcp4 configuration.</para>
+
+<para>In general case, the order in which those parameters appear does not
+matter. There are two caveats here though. The first one is to remember that
the configuration file must be a well formed JSON. That means that parameters
-for any given scope must be separate by a coma and there must not be a coma
+for any given scope must be separate by a comma and there must not be a comma
after the last parameter. When reordering configuration file, keep in mind that
moving a parameter to or from the last position in a given scope may require
-moving the coma as well. The second caveat is that it is uncommon, but legal to
-repeat the same parameter multiple times. In that case the last occurrence of a
+moving the comma as well. The second caveat is that it is uncommon - although
+legal JSON - to
+repeat the same parameter multiple times. If that appears, the last occurrence of a
given parameter in a given scope is used while all previous instances are
-ignored. That is unlikely to cause any confusion, as there are no real life
+ignored. This is unlikely to cause any confusion as there are no real life
reasons to keep multiple copies of the same parameter in your configuration
file.</para>
-<para>The line defining <command>interfaces</command> parameter specifies a list
-of network interfaces, over which the server should listen. Please note the
-notation. Lists are opened and closed with square brackets, with elements
-separated by comas. Had we wanted to listen on two interfaces, the line could
+<para>Moving onto the DHCPv4 configuration elements,
+the line defining <command>interfaces</command> parameter specifies a list
+of network interfaces on which the server should listen.
+Lists are opened and closed with square brackets, with elements
+separated by commas. Had we wanted to listen on two interfaces, the line could
look like this:
<screen>
"interfaces": [ "eth0", "eth1" ],
</screen>
-As "<command>interfaces</command>" is not the last parameter and there are
-others that follow, a trailing coma is required. A number of other parameters
-follow. Valid lifetime defines how long the addresses (leases) given out by the
+As "<command>interfaces</command>" is not the last parameter in the configuration,
+a trailing comma is required.i</para>
+<para>A number of other parameters
+follow. <command>valid-lifetime</command> defines how long the addresses (leases) given out by the
server are valid. If nothing changes, client that got the address is allowed to
-use it for 4000 seconds. Please note that integer numbers are specified as is,
-without any quotes around them. Renew-timer and rebind-timer are values that
+use it for 4000 seconds. (Note that integer numbers are specified as is,
+without any quotes around them.) <command>renew-timer</command> and
+<command>rebind-timer</command> are values that
define T1 and T2 timers that govern when the client will begin renewal and
rebind procedures.</para>
-<para>The next couple lines define lease database. It informs the server where
-to store its leases information. This specific example tells the server to use
+<para>The next couple lines define the lease database, the place where the server
+stores its lease information. This particular example tells the server to use
<command>memfile</command>, which is the simplest (and fastest) database
-backend. It uses in-memory database and stores leases on disk using CSV
+backend. It uses in-memory database and stores leases on disk in a CSV
file. This is a very simple configuration. Usually, lease database configuration
-is more extensive and contains additional parameters. Note that lease-database
-is defined as an object and it opens up a new scope, using opening curly
-bracket. Its parameters (just one in this example -- called "type")
-follow. Had there been more than one, they would be separated by comas. This
-scope is closed with closing curly bracket. As more parameters follow, trailing
-coma is present.</para>
-
-<para>Finally, we need to define a list of IPv4 subnets. This is the most
-important DHCPv4 configuration structure as the server uses that information to
-process clients' requests. It defines all subnets that the server is expected to
-receive DHCP requests from. It is a list, so it start and ends with square
-brackets. In this example we have only one subnet defined. Subnet itself has
-several parameters, hence it is a structure, so it is opened and closed using
-curly brackets. Each subnet has to have at least two parameters: subnet (that
-defines the whole subnet) and pool (which is a list of dynamically allocated
-pools that are governed by the DHCP server. Subnet4 list is closed with closing
-square bracket at the end of line 35. As this is the last parameter in Dhcp4
-context, there is no trailing coma.</para>
-
-<para>Had there been more than one subnet defined, additional subnet4 objects
-would be specified and separated by comas. For example, to define 3 subnets, the
-following syntax should be used:
+is more extensive and contains additional parameters. Note that
+<command>lease-database</command>
+is an object and opens up a new scope, using an opening brace.
+Its parameters (just one in this example -- <command>type</command>)
+follow. Had there been more than one, they would be separated by commas. This
+scope is closed with a closing brace. As more parameters follow, a trailing
+comma is present.</para>
+
+<para>Finally, we need to define a list of IPv4 subnets. This is the
+most important DHCPv4 configuration structure as the server uses that
+information to process clients' requests. It defines all subnets that
+the server is expected to receive DHCP requests from. The subnets are
+specified with the <command>subnet4</command> parameter. It is a list,
+so it starts and ends with square brackets. Each subnet definition in
+the list has several attributes associated with it, so is a structure
+and is opened and closed with braces. At minimum, a subnet definition
+has to have at least two parameters: <command>subnet</command> (that
+defines the whole subnet) and <command>pool</command> (which is a list of
+dynamically allocated pools that are governed by the DHCP server.</para>
+
+<para>The example contains a single subnet. Had more than one been defined,
+additional elements
+in the <command>subnet4</command> parameter would be specified and
+separated by commas. For example, to define three subnets, the following
+syntax would be used:
<screen>
"subnet4": [
{
</screen>
</para>
-<para>After all parameters are specified, we have two contexts open: global and
-Dhcp4, hence we need two closing curly brackets to close them. In a real life
-configuration file there likely would be additional components defined, like
-Logging or DhcpDdns, so after the first bracket would have a coma behind it and
-a new object definition would follow.</para>
+<para>After all parameters are specified, we have two contexts open:
+global and Dhcp4, hence we need two closing curly brackets to close them.
+In a real life configuration file there likely would be additional
+components defined like Logging or DhcpDdns, so the closing brace would
+be followed by a comma and another object definition.</para>
<para>Kea 0.9 does not have configuration syntax validation
implemented yet. Such a feature is planned for the near future. For
JSON validator is available at <ulink
url="http://jsonviewer.stack.hu/"/>.
</para>
+</section>
<section>
- <title>Memfile - a basic storage for leases</title>
+ <title>Lease Storage</title>
+ <para>All leases issued by the server are stored in the lease database.
+ Currently there are three database backends available:
+ memfile (which is the default backend), MySQL and PostgreSQL.</para>
+<section>
+ <title>Memfile - Basic Storage for Leases</title>
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref
- linkend="database-configuration4"/> describes one way to do it. In typical
- smaller deployments the server will use a CSV file rather than a database to
- store lease information. One of the advantages of using a file is that it
- eliminates dependency on third party database software.</para>
+ linkend="database-configuration4"/> describes this option. In typical
+ smaller deployments though, the server will use a CSV file rather than a database to
+ store lease information. As well as requiring less administration, an
+ advantage of using a file for storage is that it
+ eliminates a dependency on third-party database software.</para>
<para>The configuration of the file backend (Memfile) is controlled through
the Dhcp4/lease-database parameters. <!-- @todo: we don't have default
parameters. Let's comment this out When default parameters are used, the
Memfile backend will write leases to a disk in the
- [kea-install-dir]/var/kea/kea-leases4.csv. --></para>
-
- <para>It is possible to alter the default location of the lease file. The
- following configuration:
+ [kea-install-dir]/var/kea/kea-leases4.csv. -->
+ The following configuration:
<screen>
"Dhcp4": {
"lease-database": {
...
}
</screen>
- will change the default location of the lease file to /tmp/kea-leases4.csv.
+ ...sets the name of the lease file to /tmp/kea-leases4.csv.
</para>
<para>The "persist" parameter controls whether the leases are written to disk.
It is strongly recommended that this parameter is set to "true" at all times
- during the normal operation of the server</para>
+ during the normal operation of the server. (Not writing leases to disk will
+ mean that if a server is restarted (e.g. after a power failure), it will not
+ know what addresses have been assigned. As a result, it may hand out addresses
+ to new clients that are already in use.)
+ </para>
</section>
<section id="database-configuration4">
<title>Database Configuration</title>
- <para>All leases issued by the server are stored in the lease database.
- Currently there are 3 database backends available: MySQL, PostgreSQL and
- memfile (which is the default backend).</para>
<note>
<para>Database access information must be configured for the DHCPv4 server,
</note>
<para>Database configuration is controlled through the Dhcp4/lease-database
- parameters. The type of the database must be set to "mysql", "postgresql" or
- "memfile":
+ parameters. The type of the database must be set to "mysql" or "postgresql",
+ e.g.
<screen>
-"Dhcp4": { "lease-database": { <userinput>"type": "memfile"</userinput>, ... }, ... }
+"Dhcp4": { "lease-database": { <userinput>"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-mysql-database-create"/>
"Dhcp4": { "lease-database": { <userinput>"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
+ database host name must also be specified (although it should be noted that this
configuration may have a severe impact on server performance):
<screen>
"Dhcp4": { "lease-database": { <userinput>"host": <replaceable>remote-host-name</replaceable>"</userinput>, ... }, ... }
If there is no password to the account, set the password to the empty string
"". (This is also the default.)</para>
</section>
+</section>
<section id="dhcp4-interface-selection">
<title>Interface selection</title>
- <para>DHCPv4 server has to be configured to listen on specific network
+ <para>The DHCPv4 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration tells the server to
listen on all available interfaces:
<screen>
"Dhcp4": { <userinput>"interfaces": ["*"]</userinput>, ... }</screen>
- An asterisk sign plays a role of the wildcard and means "listen on all interfaces".
- </para>
- <para>It is usually a good idea to explicitly specify interface names:
+ The asterisk plays the role of a wildcard and means "listen on all interfaces".
+ However, it is usually a good idea to explicitly specify interface names:
<screen>
"Dhcp4": { <userinput>"interfaces": [ "eth1", "eth3" ]</userinput>, ... }</screen>
</para>
with explicit interface names:
<screen>
"Dhcp4": { <userinput>"interfaces": [ "eth1", "eth3", "*" ]</userinput>, ... }</screen>
-This configuration will tell the server to listen on all interfaces. It may be useful
-to temporary add asterisk and retain the list of interface names.
+It is anticipated that this will form of usage only be used where it is desired to
+temporarily override a list of interface names and listen on all interfaces.
</para>
</section>
<section id="ipv4-subnet-id">
<title>IPv4 Subnet Identifier</title>
<para>
- Subnet identifier is a unique number associated with a particular subnet.
+ The subnet identifier is a unique number associated with a particular subnet.
In principle, it is used to associate clients' leases with respective subnets.
- When subnet identifier is not specified for a subnet being configured, it will
+ When a subnet identifier is not specified for a subnet being configured, it will
be automatically assigned by the configuration mechanism. The identifiers
are assigned from 1 and are monotonically increased for each subsequent
subnet: 1, 2, 3 ....
<para>
If there are multiple subnets configured with auto-generated identifiers and
one of them is removed, the subnet identifiers may be renumbered. For example:
- if there are 4 subnets and 3rd is removed the last subnet will be assigned
- identifier that the 3rd subnet had before removal. As a result, the leases
- stored in the lease database for subnet 3 are now associated with the
- subnet 4, which may have unexpected consequences. In the future it is planned
- to implement the mechanism to preserve auto-generated subnet ids upon removal
- of one of the subnets. Currently, the only remedy for this issue is to
- manually specify the unique subnet identifier for each subnet.
+ if there are four subnets and third is removed the last subnet will be assigned
+ identifier that the third subnet had before removal. As a result, the leases
+ stored in the lease database for subnet 3 are now associated with
+ subnet 4, something that may have unexpected consequences. It is planned
+ to implement the mechanism to preserve auto-generated subnet ids in a
+ future version of Kea. However, the only remedy for this issue
+ at present is to
+ manually specify a unique identifier for each subnet.
</para>
<para>
The following configuration:
}
</screen>
will assign the arbitrary subnet identifier to the newly configured subnet.
- This identifier will not change for this subnet until "id" parameter is
- removed or set to 0. The value of 0 forces auto-generation of subnet
+ This identifier will not change for this subnet unless the "id" parameter is
+ removed or set to 0. The value of 0 forces auto-generation of the subnet
identifier.
</para>
<!-- @todo: describe whether database needs to be updated after changing
Note that subnet is defined as a simple string, but the pool parameter is
actually a list of pools: for this reason, the pool definition is enclosed
in square brackets, even though only one range of addresses is
- specified.</para>
+ specified in this example.</para>
<para>It is possible to define more than one pool in a subnet: continuing
the previous example, further assume that 192.0.2.64/26 should be also be
}
</screen>
The number of pools is not limited, but for performance reasons it is recommended to
- use as few as possible. Space and tabulations in pool definitions are ignored, so
+ use as few as possible. White space in pool definitions is ignored, so
spaces before and after hyphen are optional. They can be used to improve readability.
</para>
<para>
<section id="dhcp4-std-options">
<title>Standard DHCPv4 options</title>
<para>
- One of the major features of DHCPv4 server is to provide configuration
+ One of the major features of the DHCPv4 server is to provide configuration
options to clients. Although there are several options that require
special behavior, most options are sent by the server only if the client
explicitly requested them. The following example shows how to
- configure DNS servers, which is one of the most frequently used
+ configure the addresses of DNS servers, which is one of the most frequently used
options. Options specified in this way are considered global and apply
to all configured subnets.
</screen>
</para>
<para>
- The name parameter specifies
+ The <command>name</command> parameter specifies the
option name. For a complete list of currently supported names,
see <xref linkend="dhcp4-std-options-list"/> below.
- The "code" parameter specifies the option code, which must match one of the
+ The <command>code</command> parameter specifies the option code, which must match one of the
values from that list. The next line specifies option space, which must always
be set to "dhcp4" as these are standard DHCPv4 options. For
other option spaces, including custom option spaces, see <xref
</para>
<para>
- Options can also be configured as hexadecimal values. If csv-format is
- set to false, option data must be specified as a hex string. The
+ Options can also be configured as hexadecimal values. If
+ <command>csv-format</command> is
+ set to false, option data must be specified as a hexadecimal string. The
following commands configure the domain-name-servers option for all
subnets with the following addresses: 192.0.3.1 and 192.0.3.2.
- Note that csv-format is set to false.
+ Note that <command>csv-format</command> is set to false.
<screen>
"Dhcp4": {
"option-data": [
that we want to define a new DHCPv4 option called "foo" which
will have code 222 and will convey a single unsigned 32 bit
integer value. We can define such an option by using the
- following commands:
+ following entry in the configuration file:
<screen>
"Dhcp4": {
"option-def": [
...
}
</screen>
- The "false" value of the "array" parameter determines that the option
+ The "false" value of the <command>array</command> parameter determines that the option
does NOT comprise an array of "uint32" values but rather a single value.
- Two other parameters have been left blank: "record-types" and "encapsulate".
+ Two other parameters have been left blank: <command>record-types</command> and <command>encapsulate</command>.
The former specifies the comma separated list of option data fields if the
- option comprises a record of data fields. The "record-fields" value should
- be non-empty if the "type" is set to "record". Otherwise it must be left
+ option comprises a record of data fields. This should
+ be non-empty if the <command>type</command> is set to "record". Otherwise it must be left
blank. The latter parameter specifies the name of the option space being
encapsulated by the particular option. If the particular option does not
encapsulate any option space it should be left blank.
<para>New options can take more complex forms than simple use of
primitives (uint8, string, ipv4-address etc): it is possible to
define an option comprising a number of existing primitives.
- </para>
- <para>Assume we want to define a new option that will consist of
+ Assume we want to define a new option that will consist of
an IPv4 address, followed by unsigned 16 bit integer, followed by
a boolean value, followed by a text string. Such an option could
be defined in the following way:
...
}
</screen>
- The "type" is set to "record" to indicate that the option contains
+ The <command>type</command> is set to "record" to indicate that the option contains
multiple values of different types. These types are given as a comma-separated
- list in the "record-types" field and should be those listed in <xref linkend="dhcp-types"/>.
+ list in the <command>record-types</command> field and should be those listed in <xref linkend="dhcp-types"/>.
</para>
<para>
The values of the option are set as follows:
],
...
}</screen>
- "csv-format" is set "true" to indicate that the "data" field comprises a command-separated
- list of values. The values in the "data" must correspond to the types set in
- the "record-types" field of the option definition.
+ <command>csv-format</command> is set "true" to indicate that the <command>data</command> field comprises a command-separated
+ list of values. The values in the <command>data</command> must correspond to the types set in
+ the <command>record-types</command> field of the option definition.
</para>
<note>
<para>
strings. This helps to prevent errors when typing multiple comma separated
values, as it make it easier to identify the type of the value being typed,
and compare it with the order of data fields. Nevertheless, it is possible
- to use integer values: "1" and "0", instead of "true" and "false"
- accordingly. If other integer value is specified, the configuration is
- rejected.
+ to use integer values: "1" and "0", instead of "true" and "false".
+ If other integer value are used, the configuration is rejected.
</para>
</note>
</section>
<section id="dhcp4-vendor-opts">
- <title>DHCPv4 vendor specific options</title>
+ <title>DHCPv4 Vendor Specific Options</title>
<para>
- Currently there are three option spaces defined: dhcp4 (to
- be used in DHCPv4 daemon) and dhcp6 (for the DHCPv6 daemon); there
- is also vendor-encapsulated-options-space, which is empty by default, but options
+ Currently there are three option spaces defined: "dhcp4" (used by the DHCPv4 daemon)
+ and "dhcp6" (for the DHCPv6 daemon); there is also "vendor-encapsulated-options-space",
+ which is empty by default, but options
can be defined in it. Those options are called vendor-specific
information options. The following examples show how to define
an option "foo" with code 1 that consists of an IPv4 address, an
],
...
}</screen>
- We also set up a dummy value for vendor-opts, the option that conveys our sub-option "foo".
+ We also set up a dummy value for "vendor-encapsulated-options", the option that conveys our sub-option "foo".
This is required else the option will not be included in messages sent to the client.
<screen>
"Dhcp4": {
<section id="dhcp4-option-spaces">
- <title>Nested DHCPv4 options (custom option spaces)</title>
+ <title>Nested DHCPv4 Options (Custom Option Spaces)</title>
<para>It is sometimes useful to define completely new option
space. This is the case when user creates new option in the
standard option space ("dhcp4 or "dhcp6") and wants this option
- to convey sub-options. Thanks to being in the separate space,
+ to convey sub-options. Since they are in a separate space,
sub-option codes will have a separate numbering scheme and may
- overlap with codes of standard options.
+ overlap with the codes of standard options.
</para>
<para>Note that creation of a new option space when defining
sub-options for a standard option is not required, because it is
</screen>
Even though the "container" option does not carry any data except
sub-options, the "data" field must be explicitly set to an empty value.
- This is required because in the current version of BIND 10 DHCP, the
+ This is required because in the current version of Kea, the
default configuration values are not propagated to the configuration parsers:
if the "data" is not set the parser will assume that this
parameter is not specified and an error will be reported.
<title>Client Classification in DHCPv4</title>
<note>
<para>
- DHCPv4 server has been extended to support limited client classification.
+ The DHCPv4 server has been extended to support limited client classification.
Although the current capability is modest, it is expected to be expanded
- in the future. It is envisaged that the majority of client classification
+ in the future. However, it is envisaged that the majority of client classification
extensions will be using hooks extensions.
</para>
</note>
and as a result the packet will belong to class "VENDOR_CLASS_docsis3.0".
</para>
- <para>It is envisaged that the client classification will be used for changing
+ <para>It is envisaged that the client classification will be used for changing the
behavior of almost any part of the DHCP message processing, including assigning
leases from different pools, assigning different option (or different values of
the same options) etc. For now, there are only two mechanisms that are taking
This is particularly useful for cases where two types of devices share the
same link and are expected to be served from two different subnets. The
primary use case for such a scenario is cable networks. There are two
- classes of devices: cable modem itself, which should be handled a lease
- from subnet A and all other devices behind modems that should get a lease
+ classes of devices: the cable modem itself, which should be handled a lease
+ from subnet A and all other devices behind the modem that should get a lease
from subnet B. That segregation is essential to prevent overly curious
users from playing with their cable modems. For details on how to set up
class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
</para>
- </section>
<section id="dhcp4-subnet-class">
- <title>Limiting access to IPv4 subnet to certain classes</title>
+ <title>Limiting Access to IPv4 Subnet to Certain Classes</title>
<para>
In certain cases it beneficial to restrict access to certain subnets
only to clients that belong to a given subnet. For details on client
clients that do not meet class criteria to be denied any service altogether.
</para>
</section>
+ </section>
+
<section id="dhcp4-ddns-config">
<title>Configuring DHCPv4 for DDNS</title>
<para>
The FQDN, lease address, and DHCID
</para></listitem>
</orderedlist>
- The parameters for controlling the generation of NCRs for submission to D2
- are contained in the "dhcp-ddns" section of the b10-dhcp4 server
- configuration. The default values for this section appear as follows:
+ The parameters for controlling the generation of NCRs for submission to the
+ DHCP-DDNS server
+ are contained in the <command>dhcp-ddns</command> section of the b10-dhcp4 server
+ configuration. The default values for this section are as follows:
<screen>
"Dhcp4": {
"dhcp-ddns": {
<section id="dhcpv4-d2-io-config">
<title>DHCP-DDNS Server Connectivity</title>
<para>
- In order for NCRs to reach the D2 server, b10-dhcp4 must be able
+ In order for NCRs to reach the DHCP-DDNS server, b10-dhcp4 must be able
to communicate with it. b10-dhcp4 uses the following configuration
- parameters to control how it communications with D2:
+ parameters to control how it communications with DHCP-DDNS:
<orderedlist>
<listitem><para>
- server-ip - IP address on which D2 listens for requests. The default is
+ <command>server-ip</command> - IP address on which DHCP-DDNS listens for requests. The default is
the local loopback interface at address 127.0.0.1. You may specify
either an IPv4 or IPv6 address.
</para></listitem>
<listitem><para>
- server-port - port on which D2 listens for requests. The default value
+ <command>server-port</command> - port on which DHCP-DDNS listens for requests. The default value
is 53001.
</para></listitem>
<listitem><para>
- sender-ip - IP address which b10-dhcp4 should use to send requests to D2.
+ <command>sender-ip</command> - IP address which b10-dhcp4 should use to send requests to the DHCP-DDNS server.
The default value is blank which instructs b10-dhcp4 to select a suitable
address.
</para></listitem>
<listitem><para>
- sender-port - port which b10-dhcp4 should use to send requests to D2. The
+ <command>sender-port</command> - port which b10-dhcp4 should use to send requests to the DHCP-DDNS server. The
default value of 0 instructs b10-dhcp4 to select suitable port.
</para></listitem>
<listitem><para>
- ncr-format - Socket protocol use when sending requests to D2. Currently
+ <command>ncr-format</command> - Socket protocol use when sending requests to the DHCP-DDNS server. Currently
only UDP is supported. TCP may be available in an upcoming release.
</para></listitem>
<listitem><para>
- ncr-protocol - Packet format to use when sending requests to D2.
+ <command>ncr-protocol</command> - Packet format to use when sending requests to the DHCP-DDNS server.
Currently only JSON format is supported. Other formats may be available
in future releases.
</para></listitem>
<listitem><para>
- max-queue-size - maximum number of requests allowed to queue waiting to
- be sent to D2. This value guards against requests accumulating
+ <command>max-queue-size</command> - maximum number of requests allowed to queue waiting to
+ be sent to the DHCP-DDNS server. This value guards against requests accumulating
uncontrollably if they are being generated faster than they can be
delivered. If the number of requests queued for transmission reaches
this value, DDNS updating will be turned off until the queue backlog has
- been sufficiently reduced. The intent is allow the b10-dhcp4 server to
- continue lease operations. The default value is 1024.
+ been sufficiently reduced. The intention is allow the b10-dhcp4 server to
+ continue lease operations without running the risk that its memory usage
+ grows without limit. The default value is 1024.
</para></listitem>
</orderedlist>
- By default, D2 is assumed to running on the same machine as b10-dhcp4, and
+ By default, the DHCP-DDNS server is assumed to running on the same machine as b10-dhcp4, and
all of the default values mentioned above should be sufficient.
- If, however, D2 has been configured to listen on a different address or
- port, these values must altered accordingly. For example, if D2 has been
- configured to listen on 192.168.1.10 port 900, the following commands
+ If, however, the DHCP-DDNS server has been configured to listen on a different address or
+ port, these values must altered accordingly. For example, if the DHCP-DDNS server has been
+ configured to listen on 192.168.1.10 port 900, the following configuration
would be required:
<screen>
"Dhcp4": {
</para>
</section>
<section id="dhcpv4-d2-rules-config">
- <title>When does the b10-dhcp4 server generate DDNS requests?</title>
- b10-dhcp4 follows the behavior prescribed for DHCP servers in RFC 4702.
+ <title>When Does the b10-dhcp4 Server Generate DDNS Requests?</title>
+ <para>b10-dhcp4 follows the behavior prescribed for DHCP servers in
+ <ulink url="http://tools.ietf.org/html/rfc4702">RFC 4702</ulink>.
It is important to keep in mind that b10-dhcp4 provides the initial decision
- making of when and what to update and forwards that information to D2 in
+ making of when and what to update and forwards that information to the DHCP-DDNS server in
the form of NCRs. Carrying out the actual DNS updates and dealing with
- such things as conflict resolution are the purview of D2 (<xref linkend="dhcp-ddns-server"/>).
- <para>
+ such things as conflict resolution are within the purview of the DHCP-DDNS server itself (<xref linkend="dhcp-ddns-server"/>).
This section describes when b10-dhcp4 will generate NCRs and the
configuration parameters that can be used to influence this decision.
It assumes that the "enable-updates" parameter is true.
The first row in the table above represents "client delegation". Here
the DHCP client states that it intends to do the forward DNS updates and
the server should do the reverse updates. By default, b10-dhcp4 will honor
- the client's wishes and generate a DDNS request to D2 to update only
- reverse DNS data. The parameter, "override-client-update", can be used
+ the client's wishes and generate a DDNS request to the DHCP-DDNS server to update only
+ reverse DNS data. The parameter <command>override-client-update</command> can be used
to instruct the server to override client delegation requests. When
this parameter is true, b10-dhcp4 will disregard requests for client
delegation and generate a DDNS request to update both forward and
</para>
<para>
(Note that the flag combination N=1, S=1 is prohibited according to
- RFC 4702. If such a combination is received from the client, the packet
- will be dropped by the b10-dhcp4.)
+ <ulink utl="http://tools.ietf.org/html/rfc4702">RFC 4702</ulink>. If such a combination is received from the client, the packet
+ will be dropped by b10-dhcp4.)
</para>
<para>
To override client delegation, set the following values in your configuration
</screen>
<para>
The third row in the table above describes the case in which the client
- requests that no DNS updates be done. The parameter, "override-no-update",
+ requests that no DNS updates be done. The parameter, <command>override-no-update</command>,
can be used to instruct the server to disregard the client's wishes. When
- this parameter is true, b10-dhcp4 will generate DDNS update request to D2
- even if the client requests no updates be done. The N-S-O flags in the
+ this parameter is true, b10-dhcp4 will generate DDNS update request to the DHCP-DDNS server
+ even if the client requests that no updates be done. The N-S-O flags in the
server's response to the client will be 0-1-1.
</para>
<para>
- To override client delegation, issue the following commands:
+ To override client delegation, the following values should be set in your configuration:
</para>
<screen>
"Dhcp4": {
</para></listitem>
</orderedlist>
To instruct b10-dhcp4 to always generate the FQDN for a client, set the
- parameter "replace-client-name" to true as follows:
+ parameter <command>replace-client-name</command> to true as follows:
</para>
<screen>
"Dhcp4": {
</screen>
<para>
The prefix used in the generation of a FQDN is specified by the
- "generated-prefix" parameter. The default value is "myhost". To alter
+ <command>generated-prefix</command> parameter. The default value is "myhost". To alter
its value simply set it to the desired string:
</para>
<screen>
</screen>
<para>
The suffix used when generating a FQDN or when qualifying a partial
- name is specified by the "qualifying-suffix" parameter. The default
+ name is specified by the <command>qualifying-suffix</command> parameter. The default
value is "example.com". To alter its value simply set it to the desired
string:
</para>
<screen>
"Dhcp4": {
"dhcp-ddns": {
- <userinput>"generated-prefix": "foo.example.org"</userinput>,
+ <userinput>"qualifying-suffix": "foo.example.org"</userinput>,
...
},
...
<para>
where address-text is simply the lease IP address converted to a
hyphenated string. For example, if lease address is 172.16.1.10 and
- assuming default values for generated-prefix and qualifying-suffix, the
+ assuming default values for <command>generated-prefix</command> and <command>qualifying-suffix</command>, the
generated FQDN would be:
</para>
<para>
</section>
<section id="dhcp4-next-server">
- <title>Next server (siaddr)</title>
+ <title>Next Server (siaddr)</title>
<para>In some cases, clients want to obtain configuration from the TFTP server.
Although there is a dedicated option for it, some devices may use siaddr field
in the DHCPv4 packet for that purpose. That specific field can be configured
- using next-server directive. It is possible to define it in global scope or
+ using <command>next-server</command> directive. It is possible to define it in global scope or
for a given subnet only. If both are defined, subnet value takes precedence.
- The value in subnet can be set to 0.0.0.0, which means that next-server should
+ The value in subnet can be set to 0.0.0.0, which means that <command>next-server</command> should
not be sent. It may also be set to empty string, which means the same as if
- it was not defined at all - use global value.
+ it was not defined at all, i.e. use the global value.
</para>
<screen>
</section>
<section id="dhcp4-echo-client-id">
- <title>Echoing client-id (RFC6842)</title>
- <para>Original DHCPv4 spec (RFC2131) states that the DHCPv4
+ <title>Echoing Client-ID (RFC 6842)</title>
+ <para>The original DHCPv4 specification
+ (<ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>)
+ states that the DHCPv4
server must not send back client-id options when responding to
clients. However, in some cases that confused clients that did
- not have MAC address or client-id. See RFC6842 for details. That
- behavior has changed with the publication of RFC6842 which
- updated RFC2131. That update now states that the server must
+ not have MAC address or client-id; see
+ <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
+ for details. That
+ behavior has changed with the publication of
+ <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
+ which updated
+ <ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>.
+ That update now states that the server must
send client-id if client sent it. That is the default behaviour
that Kea offers. However, in some cases older devices that do
- not support RFC6842 may refuse to accept responses that include
+ not support
+ <ulink url="http://tools.ietf.org/html/rfc6842">RFC 6842</ulink>.
+ may refuse to accept responses that include
client-id option. To enable backward compatibility, an optional
configuration parameter has been introduced. To configure it,
- use the following commands:</para>
+ use the following configuration statement:</para>
<screen>
"Dhcp4": {
</screen>
</section>
-
- thomson
-
</section> <!-- end of configuring b10-dhcp4 server section with many subsections -->
<section id="dhcp4-serverid">
<title>Server Identifier in DHCPv4</title>
<para>
- The DHCPv4 protocol uses a "server identifier" for clients to be able
+ The DHCPv4 protocol uses a "server identifier" to allow clients
to discriminate between several servers present on the same link: this
value is an IPv4 address of the server. The server chooses the IPv4 address
of the interface on which the message from the client (or relay) has been
</section>
<section id="dhcp4-subnet-selection">
- <title>How DHCPv4 server selects a subnet for the client</title>
+ <title>How the DHCPv4 Server Selects a Subnet for the Client</title>
<para>
The DHCPv4 server differentiates between the directly connected clients,
clients trying to renew leases and clients sending their messages through
configuration of the interface on which the message has been received, and
if the server configuration doesn't match any configured subnet the
message is discarded.</para>
- <para>Assuming that the server's interface is configured with the 192.0.2.3
- IPv4 address, the server will only process messages received through
- this interface from the directly connected client, if there is a subnet
- configured, to which this IPv4 address belongs, e.g. 192.0.2.0/24.
+ <para>Assuming that the server's interface is configured with the
+ IPv4 address 192.0.2.3, the server will only process messages received through
+ this interface from a directly connected client if there is a subnet
+ configured to which this IPv4 address belongs, e.g. 192.0.2.0/24.
The server will use this subnet to assign IPv4 address for the client.
</para>
<para>
</note>
<section id="dhcp4-relay-override">
- <title>Using specific relay agent for a subnet</title>
+ <title>Using a Specific Relay Agent for a Subnet</title>
<para>
The relay has to have an interface connected to the link on which
the clients are being configured. Typically the relay has an IPv4
address configured on that interface that belongs to the subnet that
the server will assign addresses from. In such typical case, the
- server is able to use IPv4 address inserted by the relay (in GIADDR
- field of the DHCPv4 packet) to select appropriate subnet.
+ server is able to use IPv4 address inserted by the relay (in the giaddr
+ field of the DHCPv4 packet) to select the appropriate subnet.
</para>
<para>
- However, that is not always the case. In certain uncommon, but
- valid deployments, the relay address may not match the subnet. This
+ However, that is not always the case. In certain uncommon - but
+ valid - deployments, the relay address may not match the subnet. This
usually means that there is more than one subnet allocated for a given
- link. Two most common examples where this is the case are long lasting
+ link. The two most common examples where this is the case are long lasting
network renumbering (where both old and new address space is still being
used) and a cable network. In a cable network both cable modems and the
devices behind them are physically connected to the same link, yet
they use distinct addressing. In such case, the DHCPv4 server needs
- additional information (IPv4 address of the relay) to properly select
+ additional information (the IPv4 address of the relay) to properly select
an appropriate subnet.
</para>
<para>
</section>
<section id="dhcp4-srv-example-client-class-relay">
- <title>Segregating IPv4 clients in a cable network</title>
+ <title>Segregating IPv4 Clients in a Cable Network</title>
<para>
In certain cases, it is useful to mix relay address information,
introduced in <xref linkend="dhcp4-relay-override"/> with client
with one CM MAC (a physical link that modems are connected to).
We want the modems to get addresses from the 10.1.1.0/24 subnet, while
everything connected behind modems should get addresses from another
- subnet (192.0.2.0/24). The CMTS that acts as a relay an uses address
+ subnet (192.0.2.0/24). The CMTS that acts as a relay uses address
10.1.1.1. The following configuration can serve that configuration:
<screen>
"Dhcp4": {
<section id="dhcp4-std">
<title>Supported Standards</title>
- <para>The following standards and draft standards are currently
- supported:</para>
+ <para>The following standards and draft standards are currently supported:</para>
<itemizedlist>
<listitem>
<simpara><ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>: Supported messages are DISCOVER, OFFER,
</simpara>
</listitem>
<listitem>
- <simpara>Host reservation (statis addresses) is not supported yet.</simpara>
+ <simpara>Host reservation (static addresses) is not supported yet.</simpara>
</listitem>
<listitem>
<simpara>Full featured client classification is not supported yet.</simpara>
projects / thirdparty / kea.git / commitdiff
