From: Andrei Pavel Date: Thu, 15 Dec 2016 13:05:18 +0000 (+0200) Subject: Upgraded Docbook from v4.2 to v5.0 X-Git-Tag: trac5524_base~10^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f9cad78482df59e26c950a10f482c65d7d9b85b7;p=thirdparty%2Fkea.git Upgraded Docbook from v4.2 to v5.0 Used script http://docbook.org/xml/5.0/tools/db4-upgrade.xsl as specified in the installation documentation at http://tdg.docbook.org/tdg/5.0/appa.html. --- diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml index a8d8324851..0bc9cf65c9 100644 --- a/doc/guide/admin.xml +++ b/doc/guide/admin.xml @@ -1,14 +1,9 @@ - - -]> + +Kea Database Administration + - - Kea Database Administration - -
- Databases and Database Version Numbers +
Databases and Database Version Numbers + Kea supports storing leases and host reservations (i.e. static @@ -52,8 +47,8 @@
-
- The kea-admin Tool +
The kea-admin Tool + To manage the databases, Kea provides the @@ -71,7 +66,7 @@ - lease-init — + lease-init — Initializes a new lease database. This is useful during a new Kea installation. The database is initialized to the latest version supported by the version of the software being @@ -81,7 +76,7 @@ - lease-version — + lease-version — Reports the lease database version number. This is not necessarily equal to the Kea version number as each backend has its own versioning scheme. @@ -90,7 +85,7 @@ - lease-upgrade — + lease-upgrade — Conducts a lease database upgrade. This is useful when upgrading Kea. @@ -98,7 +93,7 @@ - lease-dump — + lease-dump — Dumps the contents of the lease database (for MySQL, PostgreSQL or CQL backends) to a CSV (comma separated values) text file. The first line of the file contains the column names. This is meant to be @@ -114,28 +109,28 @@ - memfile — Lease information is + memfile — Lease information is stored on disk in a text file. - mysql — + mysql — Lease information is stored in a MySQL relational database. - pgsql — + pgsql — Lease information is stored in a PostgreSQL relational database. - cql — + cql — Lease information is stored in a CQL database. @@ -149,8 +144,8 @@
-
- Supported Databases +
Supported Databases + The following table presents the capabilities of available backends. Please refer to the specific sections dedicated to each backend to @@ -158,14 +153,14 @@ backend may be essential for success or failure of your deployment. - - List of available backends - - - - - - +
List of available backends + + + + + + + Feature @@ -222,8 +217,8 @@
-
- memfile +
memfile + The memfile backend is able to store lease information, but is not able to @@ -240,8 +235,8 @@ present. Necessary disk write permission is required. -
- Upgrading Memfile Lease Files from an Earlier Version of Kea +
Upgrading Memfile Lease Files from an Earlier Version of Kea + There are no special steps required to upgrade memfile lease files from an earlier version of Kea to a new version of Kea. @@ -264,8 +259,8 @@
-
- MySQL +
MySQL + MySQL is able to store leases, host reservations and options defined on @@ -273,8 +268,8 @@ if you chose to store the data in other backends. -
- First Time Creation of the MySQL Database +
First Time Creation of the MySQL Database + If you are setting the MySQL database for the first time, @@ -287,14 +282,14 @@ To create the database: - + Log into MySQL as "root": $ mysql -u root -p Enter password: -mysql> +mysql> @@ -303,7 +298,7 @@ mysql> Create the MySQL database: -mysql> CREATE DATABASE database-name; +mysql> CREATE DATABASE database-name; (database-name is the name you have chosen for the database.) @@ -316,8 +311,8 @@ mysql> CREATE DATABASE database-name; -mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; -mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; +mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; +mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; (user-name and password are the user ID @@ -334,8 +329,8 @@ mysql> GRANT ALL ON database-name.* TO 'kea-admin tool, as explained below.) To do this: -mysql> CONNECT database-name; -mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql +mysql> CONNECT database-name; +mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql (path-to-kea is the location where you installed Kea.) @@ -346,7 +341,7 @@ mysql> SOURCE path-to-kea/share/kea/script Exit MySQL: -mysql> quit +mysql> quit Bye $ @@ -371,8 +366,8 @@ $ kea-admin lease-init mysql -u database-user
-
- Upgrading a MySQL Database from an Earlier Version of Kea +
Upgrading a MySQL Database from an Earlier Version of Kea + Sometimes a new Kea version may use newer database schema, so @@ -405,8 +400,8 @@ $ kea-admin lease-upgrade mysql -u database-user
-
- PostgreSQL +
PostgreSQL + A PostgreSQL database must be set up if you want Kea to store @@ -414,15 +409,15 @@ $ kea-admin lease-upgrade mysql -u database-user -
- First Time Creation of the PostgreSQL Database +
First Time Creation of the PostgreSQL Database + The first task is to create both the lease database and the user under which the servers will access it. A number of steps are required: - + Log into PostgreSQL as "root": @@ -546,8 +541,8 @@ host database-name user-name
-
- Initialize the PostgreSQL Database Using kea-admin +
Initialize the PostgreSQL Database Using kea-admin + If you elected not to create the tables manually, you can do so now by running the kea-admin tool: @@ -563,8 +558,8 @@ $ kea-admin lease-init pgsql -u database-userkea-admin.)
-
- Upgrading a PostgreSQL Database from an Earlier Version of Kea +
Upgrading a PostgreSQL Database from an Earlier Version of Kea + The PostgreSQL database schema can be upgraded using the same tool and commands as described in , with the @@ -584,8 +579,8 @@ $ kea-admin lease-upgrade pgsql -u database-user
-
- CQL (Cassandra) +
CQL (Cassandra) + Cassandra, or Cassandra Query Language (CQL), is the newest backend @@ -602,8 +597,8 @@ $ kea-admin lease-upgrade pgsql -u database-user -
- First Time Creation of the Cassandra Database +
First Time Creation of the Cassandra Database + If you are setting up the CQL database for the first time, you need to @@ -613,7 +608,7 @@ $ kea-admin lease-upgrade pgsql -u database-user To create the database: - + Export CQLSH_HOST environemnt variable: @@ -627,7 +622,7 @@ $ export CQLSH_HOST=localhost Log into CQL: $ cqlsh -cql> +cql> @@ -636,7 +631,7 @@ cql> Create the CQL keyspace: -cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1}; +cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1}; (keyspace-name is the name you have chosen for the keyspace) @@ -674,8 +669,8 @@ $ kea-admin lease-init cql -n database-name
-
- Upgrading a CQL Database from an Earlier Version of Kea +
Upgrading a CQL Database from an Earlier Version of Kea + Sometimes a new Kea version may use newer database schema, so @@ -708,8 +703,8 @@ $ kea-admin lease-upgrade cql -n database-name
-
- Using Read-Only Databases with Host Reservations +
Using Read-Only Databases with Host Reservations + If a read-only database is used for storing host reservations, Kea must be explicitly configured to operate on the database in read-only mode. @@ -720,8 +715,8 @@ $ kea-admin lease-upgrade cql -n database-name
-
- Limitations Related to the use of SQL Databases +
Limitations Related to the use of SQL Databases + The lease expiration time is stored in the SQL database for each lease @@ -741,4 +736,4 @@ $ kea-admin lease-upgrade cql -n database-name - + \ No newline at end of file diff --git a/doc/guide/classify.xml b/doc/guide/classify.xml index 7ac3a09c92..0e760aac3e 100644 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@ -1,14 +1,9 @@ - - -]> + +Client Classification + - - Client Classification - -
- Client Classification Overview +
Client Classification Overview + In certain cases it is useful to differentiate between different types of clients and treat them accordingly. Common reasons include: @@ -41,7 +36,7 @@ The process of doing classification is conducted in three steps: - + Assess an incoming packet and assign it to zero or more classes. @@ -95,37 +90,37 @@
-
- Using Static Host Reservations In Classification +
Using Static Host Reservations In Classification + Classes can be statically assigned to the clients using techniques described in and .
-
- Using Vendor Class Information In Classification +
Using Vendor Class Information In Classification + The server checks whether an incoming DHCPv4 packet includes the vendor class identifier option (60) or an incoming DHCPv6 packet includes the vendor class option (16). If it does, the content of that - option is prepended with "VENDOR_CLASS_" and the result is interpreted + option is prepended with "VENDOR_CLASS_" and the result is interpreted as a class. For example, modern cable modems will send this option with - value "docsis3.0" and so the packet will belong to - class "VENDOR_CLASS_docsis3.0". + value "docsis3.0" and so the packet will belong to + class "VENDOR_CLASS_docsis3.0".
-
- Using Expressions In Classification +
Using Expressions In Classification + The expression portion of classification contains operators and values. All values are currently strings and operators take a string or strings and return another string. When all the operations have completed - the result should be a value of "true" or "false". + the result should be a value of "true" or "false". The packet belongs to the class (and the class name is added to the list of classes) if the result - is "true". Expressions are written in standard format and can be nested. + is "true". Expressions are written in standard format and can be nested. @@ -152,12 +147,12 @@ - - List of Classification Values - - - - +
List of Classification Values + + + + + Name @@ -192,7 +187,7 @@ '123' A 32 bit unsigned integer value - + Binary content of the option option[123].hex @@ -430,9 +425,9 @@ - Hexadecimal strings are converted into a string as expected. The starting "0X" or - "0x" is removed and if the string is an odd number of characters a - "0" is prepended to it. + Hexadecimal strings are converted into a string as expected. The starting "0X" or + "0x" is removed and if the string is an odd number of characters a + "0" is prepended to it. @@ -510,14 +505,14 @@ Vendor option means Vendor-Identifying Vendor-specific Information option in DHCPv4 (code 125, see - Section 4 of RFC 3925) and + Section 4 of RFC 3925) and Vendor-specific Information Option in DHCPv6 (code 17, defined in - Section 22.17 of - RFC 3315). Vendor class option means Vendor-Identifying Vendor + Section 22.17 of + RFC 3315). Vendor class option means Vendor-Identifying Vendor Class Option in DHCPv4 (code 124, see - Section 3 of RFC 3925) in DHCPv4 and + Section 3 of RFC 3925) in DHCPv4 and Class Option in DHCPv6 (code 16, see - Section 22.16 of RFC 3315). + Section 22.16 of RFC 3315). Vendor options may have sub-options that are referenced by their codes. Vendor class options do not have sub-options, but rather data chunks, which are @@ -535,8 +530,8 @@ accessed using option[60] expression. - RFC3925 and - RFC3315 + RFC3925 and + RFC3315 allow for multiple instances of vendor options to appear in a single message. The client classification code currently examines the first instance if more than one appear. For vendor.enterprise @@ -548,12 +543,12 @@ -
- List of Classification Expressions - - - - +
List of Classification Expressions + + + + + Name @@ -574,8 +569,8 @@ concatenation of the strings
 -
- Logical operators +
Logical operators + The Not, And and Or logical operators are the common operators. Not has the highest precedence and Or the lowest. And and Or are (left) associative, parentheses around a logical expression can be used @@ -583,8 +578,8 @@ concatenation of the strings (without parentheses "A and B or C" means "(A and B) or C").
-
- Substring +
Substring + The substring operator "substring(value, start, length)" accepts both positive and negative values for the starting position and the length. For "start", a value of 0 is the first byte in the string while -1 is the last byte. If the starting @@ -606,8 +601,8 @@ concatenation of the strings substring('foobar', 10, 2) == ''
-
- Concat +
Concat + The concat function "concat(string1, string2)" returns the concatenation of its two arguments. For instance: @@ -621,12 +616,11 @@ concatenation of the strings The expression for each class is executed on each packet received. If the expressions are overly complex, the time taken to execute them may impact the performance of the server. If you need - complex or time consuming expressions you should write a hook to perform the necessary work. + complex or time consuming expressions you should write a hook to perform the necessary work. -
- Configuring Classes +
Configuring Classes + A class contains three items: a name, a test expression and option data. The name must exist and must be unique amongst all classes. The test @@ -645,9 +639,9 @@ concatenation of the strings - In the following example the class named "Client_foo" is defined. + In the following example the class named "Client_foo" is defined. It is comprised of all clients whose client ids (option 61) start with the - string "foo". Members of this class will be given 192.0.2.1 and + string "foo". Members of this class will be given 192.0.2.1 and 192.0.2.2 as their domain name servers. @@ -674,7 +668,7 @@ concatenation of the strings This example shows a client class being defined for use by the DHCPv6 server. - In it the class named "Client_enterprise" is defined. It is comprised + In it the class named "Client_enterprise" is defined. It is comprised of all clients who's client identifiers start with the given hex string (which would indicate a DUID based on an enterprise id of 0xAABBCCDD). Members of this class will be given an 2001:db8:0::1 and 2001:db8:2::1 as their domain name servers. @@ -701,8 +695,8 @@ concatenation of the strings
-
- Configuring Subnets With Class Information +
Configuring Subnets With Class Information + In certain cases it beneficial to restrict access to certain subnets only to clients that belong to a given class, using the "client-class" @@ -781,8 +775,8 @@ concatenation of the strings
-
- Using Classes +
Using Classes + Currently classes can be used for two functions. They can supply options to the members of the class and they can be used to choose a subnet from which an @@ -791,14 +785,14 @@ concatenation of the strings When supplying options, options defined as part of the class definition - are considered "class globals". They will override any global options that + are considered "class globals". They will override any global options that may be defined and in turn will be overridden by any options defined for an individual subnet.
-
- Classes and Hooks +
Classes and Hooks + You may use a hook to classify your packets. This may be useful if the expression would either be complex or time consuming and be easier or @@ -811,8 +805,8 @@ concatenation of the strings
-
- Debugging Expressions +
Debugging Expressions + While you are constructing your classification expressions you may find it useful to enable logging see for @@ -828,7 +822,7 @@ concatenation of the strings In order to understand the logging statements one must understand a bit about how expressions are evaluated, for a more complete description - refer to the design document at . + refer to the design document at http://kea.isc.org/wiki/KeaDesigns. In brief there are two structures used during the evaluation of an expression: a list of tokens which represent the expressions and a value stack which represents the values being manipulated. @@ -902,4 +896,4 @@ concatenation of the strings
- + \ No newline at end of file diff --git a/doc/guide/config.xml b/doc/guide/config.xml index d2f81f48d9..796ffc108a 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -1,17 +1,13 @@ - - -]> - - Kea Configuration + +Kea Configuration + Kea is using JSON structures to handle configuration. Previously we there was a concept of other configuration backends, but that never was implemented and the idea was abandoned. -
- JSON Configuration +
JSON Configuration + JSON is notation used throughout the Kea project. The most obvious usage is for configuration file, but it is also used for sending commands over Management API (see ) and for @@ -22,11 +18,10 @@ The JSON backend uses certain signals to influence Kea. The configuration file is specified upon startup using the -c parameter. -
- JSON Syntax +
JSON Syntax + Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined - in an extended JSON format. Basic JSON is defined in RFC 7159. Note that Kea + in an extended JSON format. Basic JSON is defined in RFC 7159. Note that Kea 1.2 introduces a new parser that is better at following the JSON spec. In particular, the only values allowed for boolean are true or false (all lowercase). The capitalized versions (True or False) are not accepted. @@ -138,8 +133,8 @@ where extra parameters may appear are denoted by an ellipsis.
-
- Simplified Notation +
Simplified Notation + It is sometimes convenient to refer to a specific element in the configuration hierarchy. Each hierarchy level is separated by a slash. @@ -154,4 +149,4 @@
- + \ No newline at end of file diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 8db374be5f..f88254c0fe 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -1,13 +1,6 @@ - - - -%version; -]> - - - Management API + +Management API + A classic approach to daemon configuration assumes that the server's configuration is stored in configuration files @@ -29,13 +22,12 @@ Currently the only supported type of control channel is UNIX stream socket. For details how to configure it, see - and . It is likely that support + and . It is likely that support for other control channel types will be added in the future. -
- Data Syntax +
Data Syntax + Communication over the control channel is conducted using JSON structures. If configured, Kea will open a socket and listen for incoming connections. A process connecting to this socket @@ -81,8 +73,8 @@ if it contains no data values.
-
- Using the Control Channel +
Using the Control Channel + Kea does not currently provide a client for using the control channel. The primary reason for this is the expectation is that the entity using the control channel @@ -92,8 +84,8 @@ how one can take advantage of the API. The easiest way is to use a tool called socat, - a tool available from socat - homepage, but it is also widely available in Linux and BSD + a tool available from socat + homepage, but it is also widely available in Linux and BSD distributions. Once Kea is started, one could connect to the control interface using the following command: @@ -110,11 +102,11 @@ will be sent to Kea and the responses received from Kea printed to standard outp
-
- Commands Supported by Both the DHCPv4 and DHCPv6 Servers +
Commands Supported by Both the DHCPv4 and DHCPv6 Servers + -
- leases-reclaim +
leases-reclaim + leases-reclaim command instructs the server to reclaim all expired leases immediately. The command has the following @@ -140,8 +132,8 @@ will be sent to Kea and the responses received from Kea printed to standard outp about the processing of expired leases (leases reclamation).
-
- list-commands +
list-commands + The list-commands command retrieves a list of all @@ -161,8 +153,8 @@ will be sent to Kea and the responses received from Kea printed to standard outp
-
- shutdown +
shutdown + The shutdown command instructs the server to initiate @@ -184,4 +176,4 @@ will be sent to Kea and the responses received from Kea printed to standard outp
- + \ No newline at end of file diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index 4a069f72b3..99e72f3940 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -1,14 +1,9 @@ - - -]> - - - The DHCP-DDNS Server + +The DHCP-DDNS Server + The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of - the DDNS protocol (defined in RFC 2136) + the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP @@ -49,8 +44,8 @@ rejected. Finally, if there are no reverse DDNS Domains defined, D2 will simply disregard the reverse update portion of requests. -
- Starting and Stopping the DHCP-DDNS Server +
Starting and Stopping the DHCP-DDNS Server + kea-dhcp-ddns is the Kea DHCP-DDNS server @@ -149,8 +144,8 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p'
-
- Configuring the DHCP-DDNS Server +
Configuring the DHCP-DDNS Server + Before starting kea-dhcp-ddns module for the first time, a configuration file needs to be created. The following default @@ -198,8 +193,8 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' -
- Global Server Parameters +
Global Server Parameters + @@ -264,12 +259,12 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
-
- TSIG Key List +
TSIG Key List + A DDNS protocol exchange can be conducted with or without TSIG - (defined in RFC - 2845). This configuration section allows the administrator + (defined in RFC + 2845). This configuration section allows the administrator to define the set of TSIG keys that may be used in such exchanges. @@ -391,8 +386,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
-
- Forward DDNS +
Forward DDNS + The Forward DDNS section is used to configure D2's forward update behavior. Currently it contains a single parameter, the catalog of @@ -409,8 +404,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. By default, this list is empty, which will cause the server to ignore the forward update portions of requests. -
- Adding Forward DDNS Domains +
Adding Forward DDNS Domains + A forward DDNS Domain maps a forward DNS zone to a set of DNS servers which maintain the forward DNS data (i.e. name to @@ -480,8 +475,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. server to it. -
- Adding Forward DNS Servers +
Adding Forward DNS Servers + This section describes how to add DNS servers to a Forward DDNS Domain. Repeat them for as many servers as desired for a each domain. @@ -549,8 +544,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
-
- Reverse DDNS +
Reverse DDNS + The Reverse DDNS section is used to configure D2's reverse update behavior, and the concepts are the same as for the forward DDNS @@ -567,8 +562,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. By default, this list is empty, which will cause the server to ignore the reverse update portions of requests. -
- Adding Reverse DDNS Domains +
Adding Reverse DDNS Domains + A reverse DDNS Domain maps a reverse DNS zone to a set of DNS servers which maintain the reverse DNS data (address to name @@ -646,8 +641,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. server to it. -
- Adding Reverse DNS Servers +
Adding Reverse DNS Servers + This section describes how to add DNS servers to a Reverse DDNS Domain. Repeat them for as many servers as desired for each domain. @@ -716,20 +711,20 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
-
- Example DHCP-DDNS Server Configuration +
Example DHCP-DDNS Server Configuration + This section provides an example DHCP-DDNS server configuration based on a small example network. Let's suppose our example network has three domains, each with their own subnet. - - Our example network - - - - - +
Our example network + + + + + + Domain @@ -763,12 +758,12 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. We need to construct three forward DDNS Domains: -
- Forward DDNS Domains Needed - - - - +
Forward DDNS Domains Needed + + + + + # @@ -839,12 +834,12 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. Similarly, we need to construct the three reverse DDNS Domains: -
- Reverse DDNS Domains Needed - - - - +
Reverse DDNS Domains Needed + + + + + # @@ -912,8 +907,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section. -
- DHCP-DDNS Server Limitations +
DHCP-DDNS Server Limitations + The following are the current limitations of the DHCP-DDNS Server. @@ -925,4 +920,4 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
- + \ No newline at end of file diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index c2798e7a02..b8601f1885 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1,14 +1,9 @@ - - -]> + +The DHCPv4 Server + - - The DHCPv4 Server - -
- Starting and Stopping the DHCPv4 Server +
Starting and Stopping the DHCPv4 Server + It is recommended that the Kea DHCPv4 server be started and stopped @@ -120,10 +115,10 @@ strings path/kea-dhcp4 | sed -n 's/;;;; //p'
-
- DHCPv4 Server Configuration -
- Introduction +
DHCPv4 Server Configuration + +
Introduction + This section explains how to configure the DHCPv4 server using the Kea configuration backend. (Kea configuration using any other @@ -195,8 +190,8 @@ the configuration file must be well formed JSON. That means that the parameters for any given scope must be separated by a comma and there must not be a comma after the last parameter. When reordering a configuration file, keep in mind that moving a parameter to or from the last position in a given scope may also require -moving the comma. The second caveat is that it is uncommon — although -legal JSON — to +moving the comma. The second caveat is that it is uncommon — although +legal JSON — to repeat the same parameter multiple times. If that happens, the last occurrence of a given parameter in a given scope is used while all previous instances are ignored. This is unlikely to cause any confusion as there are no real life @@ -214,7 +209,7 @@ define T1 and T2 timers that govern when the client will begin the renewal and rebind procedures. Note that renew-timer and rebind-timer are optional. If they are not specified the client will select values for T1 and T2 timers according to the -RFC 2131. +RFC 2131. The interfaces-config map specifies the server configuration concerning the network interfaces, on which the server should @@ -287,17 +282,16 @@ components defined such as Logging or DhcpDdns, so the closing brace would be followed by a comma and another object definition.
-
- Lease Storage +
Lease Storage + All leases issued by the server are stored in the lease database. Currently there are four database backends available: memfile (which is the default backend), MySQL, PostgreSQL and Cassandra. -
- Memfile - Basic Storage for Leases +
Memfile - Basic Storage for Leases + The server is able to store lease data in different repositories. Larger - deployments may elect to store leases in a database. describes this option. In typical + deployments may elect to store leases in a database. describes this option. In typical smaller deployments though, the server will store lease information in a CSV file rather than a database. As well as requiring less administration, an advantage of using a file for storage is that it @@ -408,13 +402,13 @@ be followed by a comma and another object definition. file used by the server to record lease updates. There are also other files being created as a side effect of the lease file cleanup. The detailed description of the LFC is located on the Kea wiki: - . + http://kea.isc.org/wiki/LFCDesign.
-
- Lease Database Configuration +
Lease Database Configuration + Lease database access information must be configured for the DHCPv4 server, @@ -469,8 +463,8 @@ If a timeout is given though, it should be an integer greater than zero.
-
- Hosts Storage +
Hosts Storage + Kea is also able to store information about host reservations in the database. The hosts database configuration uses the same syntax as the lease database. In fact, a Kea server opens independent connections for each @@ -489,8 +483,8 @@ If a timeout is given though, it should be an integer greater than zero. from the configuration file are checked first and external storage is checked later, if necessary. -
- DHCPv4 Hosts Database Configuration +
DHCPv4 Hosts Database Configuration + Hosts database configuration is controlled through the Dhcp4/hosts-database parameters. If enabled, the type of the database must be set to "mysql" or @@ -528,8 +522,8 @@ If a timeout is given though, it should be an integer greater than zero. "". (This is also the default.)
-
-Using Read-Only Databases for Host Reservations +
Using Read-Only Databases for Host Reservations + In some deployments the database user whose name is specified in the database backend configuration may not have write privileges to the database. This is often @@ -561,8 +555,8 @@ for MySQL and PostgreSQL databases.
-
- Interface Configuration +
Interface Configuration + 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: @@ -687,8 +681,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Issues with Unicast Responses to DHCPINFORM +
Issues with Unicast Responses to DHCPINFORM + The use of UDP sockets has certain benefits in deployments where the server receives only relayed traffic; these benefits are mentioned in . From @@ -701,7 +695,7 @@ temporarily override a list of interface names and listen on all interfaces. In this section we are focusing on the case when the server receives the DHCPINFORM message from the client via a relay. According - to RFC 2131, + to RFC 2131, the server should unicast the DHCPACK response to the address carried in the "ciaddr" field. When the UDP socket is in use, the DHCP server relies on the low level functions of an operating system to build the @@ -739,8 +733,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- IPv4 Subnet Identifier +
IPv4 Subnet Identifier + The subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with their respective subnets. @@ -784,8 +778,8 @@ temporarily override a list of interface names and listen on all interfaces. id -->
-
- Configuration of IPv4 Address Pools +
Configuration of IPv4 Address Pools + The main role of a DHCPv4 server is address assignment. For this, the server has to be configured with at least one subnet and one pool of dynamic addresses for it to manage. @@ -881,8 +875,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Standard DHCPv4 Options +
Standard DHCPv4 Options + One of the major features of the DHCPv4 server is to provide configuration options to clients. Most of the options are sent by the server only if the @@ -932,8 +926,7 @@ temporarily override a list of interface names and listen on all interfaces. The code parameter specifies the option code, which must match one of the values from that list. The next line specifies the option space, which must always be set to "dhcp4" as these are standard DHCPv4 options. For - other option spaces, including custom option spaces, see . The next line specifies the format in + other option spaces, including custom option spaces, see . The next line specifies the format in which the data will be entered: use of CSV (comma separated values) is recommended. The sixth line gives the actual value to be sent to clients. Data is specified as normal text, with @@ -1039,14 +1032,14 @@ temporarily override a list of interface names and listen on all interfaces. -
- List of standard DHCPv4 options - - - - - - +
List of standard DHCPv4 options + + + + + + + Name @@ -1108,14 +1101,14 @@ This rather belong to the DDNS configuration -
- List of standard DHCPv4 options (continued) - - - - - - +
List of standard DHCPv4 options (continued) + + + + + + + Name @@ -1201,11 +1194,11 @@ It is merely echoed by the server -
- List of standard DHCP option types - - - +
List of standard DHCP option types + + + + NameMeaning @@ -1217,7 +1210,7 @@ It is merely echoed by the server ipv4-addressIPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)ipv6-addressIPv6 address in the usual colon notation (e.g. 2001:db8::1)ipv6-prefixIPv6 prefix and prefix length specified using CIDR notation, e.g. 2001:db8:1::/64. This data type is used to represent an 8-bit field conveying a prefix length and the variable length prefix value - psidPSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See RFC 7597 for the details about the PSID wire representation + psidPSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See RFC 7597 for the details about the PSID wire representationrecordStructured data that may comprise any types (except "record" and "empty")stringAny textuint88 bit unsigned integer with allowed values 0 to 255 @@ -1229,8 +1222,8 @@ It is merely echoed by the server -
- Custom DHCPv4 options +
Custom DHCPv4 options + Kea supports custom (non-standard) DHCPv4 options. Assume that we want to define a new DHCPv4 option called "foo" which will have a code 222 and will convey a single unsigned 32 bit @@ -1351,8 +1344,8 @@ It is merely echoed by the server
-
- DHCPv4 Vendor Specific Options +
DHCPv4 Vendor Specific Options + Currently there are two option spaces defined for the DHCPv4 daemon: "dhcp4" (for the top level DHCPv4 options) and @@ -1423,9 +1416,9 @@ It is merely echoed by the server
-
+
Nested DHCPv4 Options (Custom Option Spaces) - Nested DHCPv4 Options (Custom Option Spaces) + It is sometimes useful to define a completely new option space. This is the case when user creates new option in the standard option space ("dhcp4") and wants this option @@ -1526,13 +1519,13 @@ It is merely echoed by the server value as well as the sub-options, the type value would have to be set to "uint16" in the option definition. (Such an option would then have the following data structure: DHCP header, uint16 value, sub-options.) The value specified - with the data parameter — which should be a valid integer enclosed in quotes, - e.g. "123" — would then be assigned to the uint16 field in the "container" option. + with the data parameter — which should be a valid integer enclosed in quotes, + e.g. "123" — would then be assigned to the uint16 field in the "container" option.
-
- Unspecified Parameters for DHCPv4 Option Configuration +
Unspecified Parameters for DHCPv4 Option Configuration + In many cases it is not required to specify all parameters for an option configuration and the default values may be used. However, it is important to understand the implications of not specifying some of them @@ -1601,8 +1594,8 @@ It is merely echoed by the server
-
- Stateless Configuration of DHCPv4 Clients +
Stateless Configuration of DHCPv4 Clients + The DHCPv4 server supports the stateless client configuration whereby the client has an IP address configured (e.g. using manual configuration) and only contacts the server to obtain other configuration parameters, e.g. addresses of DNS servers. @@ -1662,8 +1655,8 @@ It is merely echoed by the server
-
- Client Classification in DHCPv4 +
Client Classification in DHCPv4 + The DHCPv4 server includes support for client classification. For a deeper discussion of the classification process see . @@ -1715,8 +1708,8 @@ It is merely echoed by the server clients that do not meet class criteria to be denied any service altogether. -
- Setting Fixed Fields in Classification +
Setting Fixed Fields in Classification + It is possible to specify that clients belonging to a particular class should receive packets with specific values in certain fixed fields. @@ -1735,7 +1728,7 @@ It is merely echoed by the server make the distinction. The following example checks if the client identifies itself as PXE device with architecture EFI x86-64, and sets several fields if it does. See - Section 2.1 of RFC 4578) + Section 2.1 of RFC 4578) or the documentation of your client for specific values. @@ -1760,14 +1753,14 @@ It is merely echoed by the server
-
- Using Vendor Class Information in Classification +
Using Vendor Class Information in Classification + The server checks whether an incoming packet includes the vendor class identifier option (60). If it does, the content of that option is prepended with - "VENDOR_CLASS_", it is interpreted as a class. For example, - modern cable modems will send this option with value "docsis3.0" - and as a result the packet will belong to class "VENDOR_CLASS_docsis3.0". + "VENDOR_CLASS_", it is interpreted as a class. For example, + modern cable modems will send this option with value "docsis3.0" + and as a result the packet will belong to class "VENDOR_CLASS_docsis3.0". @@ -1802,14 +1795,14 @@ It is merely echoed by the server
-
- Defining and Using Custom Classes +
Defining and Using Custom Classes + The following example shows how to configure a class using an expression and a subnet that makes use of the class. This configuration defines the - class named "Client_foo". + class named "Client_foo". It is comprised of all clients who's client ids (option 61) start with the - string "foo". Members of this class will be given addresses from + string "foo". Members of this class will be given addresses from 192.0.2.10 to 192.0.2.20 and the addresses of their DNS servers set to 192.0.2.1 and 192.0.2.2. @@ -1845,13 +1838,13 @@ It is merely echoed by the server
-
- DDNS for DHCPv4 +
DDNS for DHCPv4 + As mentioned earlier, kea-dhcp4 can be configured to generate requests to the DHCP-DDNS server (referred to here as "D2" ) to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information: - + Whether it is a request to add (update) or remove DNS entries @@ -1929,8 +1922,8 @@ It is merely echoed by the server -
- DHCP-DDNS Server Connectivity +
DHCP-DDNS Server Connectivity + In order for NCRs to reach the D2 server, kea-dhcp4 must be able to communicate with it. kea-dhcp4 uses the following configuration @@ -1997,10 +1990,10 @@ It is merely echoed by the server
-
- When Does the kea-dhcp4 Server Generate DDNS Requests? +
When Does the kea-dhcp4 Server Generate DDNS Requests? + kea-dhcp4 follows the behavior prescribed for DHCP servers in - RFC 4702. + RFC 4702. It is important to keep in mind that kea-dhcp4 provides the initial decision making of when and what to update and forwards that information to D2 in the form of NCRs. Carrying out the actual DNS updates and dealing with @@ -2011,7 +2004,7 @@ It is merely echoed by the server In general, kea-dhcp4 will generate DDNS update requests when: - + A new lease is granted in response to a DHCP REQUEST @@ -2037,13 +2030,13 @@ It is merely echoed by the server will respect the FQDN N and S flags specified by the client as shown in the following table: -
- Default FQDN Flag Behavior - - - - - +
Default FQDN Flag Behavior + + + + + + Client Flags:N-S @@ -2090,7 +2083,7 @@ It is merely echoed by the server (Note that the flag combination N=1, S=1 is prohibited according to - RFC 4702. If such a + RFC 4702. If such a combination is received from the client, the packet will be dropped by kea-dhcp4.) @@ -2134,8 +2127,8 @@ It is merely echoed by the server -
- kea-dhcp4 name generation for DDNS update requests +
kea-dhcp4 name generation for DDNS update requests + Each NameChangeRequest must of course include the fully qualified domain name whose DNS entries are to be affected. kea-dhcp4 can be configured to supply a portion or all of that name based upon what it receives from @@ -2143,7 +2136,7 @@ It is merely echoed by the server The default rules for constructing the FQDN that will be used for DNS entries are: - + If the DHCPREQUEST contains the client FQDN option, the candidate name is taken from there, otherwise it is taken from the Host Name option. @@ -2251,8 +2244,8 @@ It is merely echoed by the server
-
- Next Server (siaddr) +
Next Server (siaddr) + In some cases, clients want to obtain configuration from a TFTP server. Although there is a dedicated option for it, some devices may use the siaddr field in the DHCPv4 packet for that purpose. That specific field can be configured @@ -2277,24 +2270,24 @@ It is merely echoed by the server
-
- Echoing Client-ID (RFC 6842) +
Echoing Client-ID (RFC 6842) + The original DHCPv4 specification - (RFC 2131) + (RFC 2131) 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 - RFC 6842. + RFC 6842. for details. That behavior has changed with the publication of - RFC 6842 + RFC 6842 which updated - RFC 2131. + RFC 2131. That update states that the server must send client-id if the client sent it. That is Kea's default behavior. However, in some cases older devices that do not support - RFC 6842. + RFC 6842. may refuse to accept responses that include the client-id option. To enable backward compatibility, an optional configuration parameter has been introduced. To configure it, @@ -2308,8 +2301,8 @@ It is merely echoed by the server
-
- Using Client Identifier and Hardware Address +
Using Client Identifier and Hardware Address + The DHCP server must be able to identify the client (and distinguish it from other clients) from which it receives the message. There are many reasons why this identification is required and the most important ones are: @@ -2340,10 +2333,10 @@ It is merely echoed by the server used by DHCP to carry the hardware address of the interface used to send the query to the server (MAC address for the Ethernet). The latter is carried in the Client-identifier option, introduced in - RFC 2132. + RFC 2132. - RFC 2131 + RFC 2131 indicates that the server may use both of these identifiers to identify the client but the "client identifier", if present, takes precedence over "chaddr". One of the reasons for this is that "client identifier" @@ -2352,9 +2345,9 @@ It is merely echoed by the server network card and then the network card is moved to another host, the server will wrongly identify this host is the one which has obtained the lease. Moreover, - RFC 4361 gives + RFC 4361 gives the recommendation to use a DUID - (see RFC 3315, + (see RFC 3315, the DHCPv6 specification) carried as "client identifier" when dual stack networks are in use to provide consistent identification information of the client, regardless @@ -2472,11 +2465,11 @@ It is merely echoed by the server
-
- DHCPv4-over-DHCPv6: DHCPv4 Side +
DHCPv4-over-DHCPv6: DHCPv4 Side + The support of DHCPv4-over-DHCPv6 transport is described in - RFC 7341 + RFC 7341 and is implemented using cooperating DHCPv4 and DHCPv6 servers. This section is about the configuration of the DHCPv4 side (the DHCPv6 side is described in ). @@ -2567,12 +2560,12 @@ It is merely echoed by the server -
- Host Reservation in DHCPv4 +
Host Reservation in DHCPv4 + There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve a specific, static - address for exclusive use by a given client (host) ‐ the returning client will + address for exclusive use by a given client (host) ‐ the returning client will receive the same address from the server every time, and other clients will generally not receive that address. Another example when the host reservations are applicable is when a host @@ -2664,8 +2657,8 @@ It is merely echoed by the server could be used by someone else (i.e. there is a reservation for it). That additional check incurs additional overhead. -
- Address Reservation Types +
Address Reservation Types + In a typical scenario there is an IPv4 subnet defined, e.g. 192.0.2.0/24, with certain part of it dedicated for dynamic allocation @@ -2683,8 +2676,8 @@ It is merely echoed by the server possible.
-
- Conflicts in DHCPv4 Reservations +
Conflicts in DHCPv4 Reservations + As the reservations and lease information are stored separately, conflicts may arise. Consider the following series of events. The server has configured the dynamic pool of addresses from the range of 192.0.2.10 to @@ -2760,8 +2753,8 @@ It is merely echoed by the server
-
- Reserving a Hostname +
Reserving a Hostname + When the reservation for a client includes the hostname, the server will return this hostname to the client in the Client FQDN or Hostname options. The server responds with the Client @@ -2828,14 +2821,12 @@ It is merely echoed by the server
-
- Including Specific DHCPv4 Options in Reservations +
Including Specific DHCPv4 Options in Reservations + Kea 1.1.0 introduced the ability to specify options on a per host basis. The options follow the same rules as any other - options. These can be standard options (see ), custom options (see ) or vendor specific options - (see ). The following + options. These can be standard options (see ), custom options (see ) or vendor specific options + (see ). The following example demonstrates how standard options can be defined. @@ -2889,8 +2880,8 @@ It is merely echoed by the server
-
- Reserving Next Server, Server Hostname and Boot File Name +
Reserving Next Server, Server Hostname and Boot File Name + BOOTP/DHCPv4 messages include "siaddr", "sname" and "file" fields. Even though, DHCPv4 includes corresponding options, such as option 66 and option 67, some clients may not support these options. For this reason, server @@ -2918,8 +2909,8 @@ It is merely echoed by the server them can be omitted.
-
- Reserving Client Classes in DHCPv4 +
Reserving Client Classes in DHCPv4 + explains how to configure the server to assign classes to a client based on the content of the options that this client sends to the server. Host reservations @@ -2973,15 +2964,14 @@ It is merely echoed by the server with classification using expressions.
-
- Storing Host Reservations in MySQL or PostgreSQL +
Storing Host Reservations in MySQL or PostgreSQL + It is possible to store host reservations in MySQL or PostgreSQL database. See for information on how to configure Kea to use reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated - tools for managing reservations in a database. The Kea wiki provides detailed + tools for managing reservations in a database. The Kea wiki http://kea.isc.org/wiki/HostReservationsHowTo provides detailed information and examples of how reservations can be inserted into the database. @@ -2990,15 +2980,15 @@ It is merely echoed by the server arbitrarily set to 4096 bytes.
-
- Storing host reservations in CQL (Cassandra) +
Storing host reservations in CQL (Cassandra) + Kea currently does not support storing reservations in Cassandra (CQL).
-
- Fine Tuning DHCPv4 Host Reservation +
Fine Tuning DHCPv4 Host Reservation + The host reservation capability introduces additional restrictions for the allocation engine (the component of Kea that selects an address for a client) @@ -3113,8 +3103,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- Server Identifier in DHCPv4 +
Server Identifier in DHCPv4 + The DHCPv4 protocol uses a "server identifier" to allow clients to discriminate between several servers present on the same link: this @@ -3130,8 +3120,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- How the DHCPv4 Server Selects a Subnet for the Client +
How the DHCPv4 Server Selects a Subnet for the Client + The DHCPv4 server differentiates between the directly connected clients, clients trying to renew leases and clients sending their messages through @@ -3168,8 +3158,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> depending on the classes to which the client belongs. -
- Using a Specific Relay Agent for a Subnet +
Using a Specific Relay Agent for a Subnet + A relay has to have an interface connected to the link on which the clients are being configured. Typically the relay has an IPv4 @@ -3179,8 +3169,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> field of the DHCPv4 packet) to select the appropriate subnet. - 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. 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 @@ -3215,8 +3205,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- Segregating IPv4 Clients in a Cable Network +
Segregating IPv4 Clients in a Cable Network + In certain cases, it is useful to mix relay address information, introduced in with client @@ -3259,8 +3249,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- Duplicate Addresses (DHCPDECLINE Support) +
Duplicate Addresses (DHCPDECLINE Support) + The DHCPv4 server is configured with a certain pool of addresses that it is expected to hand out to the DHCPv4 clients. It is @@ -3328,22 +3318,22 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- Statistics in the DHCPv4 Server +
Statistics in the DHCPv4 Server + This section describes DHCPv4-specific statistics. For a general - overview and usage of statistics, see . + overview and usage of statistics, see . The DHCPv4 server supports the following statistics: -
- DHCPv4 Statistics - - - - +
DHCPv4 Statistics + + + + + Statistic @@ -3624,12 +3614,12 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- Management API for the DHCPv4 Server +
Management API for the DHCPv4 Server + The management API allows the issuing of specific management commands, such as statistics retrieval, reconfiguration or shutdown. - For more details, see . Currently the only + For more details, see . Currently the only supported communication channel type is UNIX stream socket. By default there are no sockets open. To instruct Kea to open a socket, the following entry in the configuration file can be used: @@ -3668,24 +3658,24 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> and statistic-remove-all, specified in . It also supports list-commands and shutdown, - specified in and - , respectively. + specified in and + , respectively.
-
- Supported DHCP Standards +
Supported DHCP Standards + The following standards are currently supported: Dynamic Host Configuration Protocol, - RFC 2131: + RFC 2131: Supported messages are DHCPDISCOVER (1), DHCPOFFER (2), DHCPREQUEST (3), DHCPRELEASE (7), DHCPINFORM (8), DHCPACK (5), and DHCPNAK(6). DHCP Options and BOOTP Vendor Extensions, - RFC 2132: + RFC 2132: Supported options are: PAD (0), END(255), Message Type(53), DHCP Server Identifier (54), Domain Name (15), DNS Servers (6), IP Address Lease Time @@ -3693,19 +3683,19 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> DHCP Relay Agent Information Option, - RFC 3046: + RFC 3046: Relay Agent Information option is supported. Vendor-Identifying Vendor Options for Dynamic Host Configuration Protocol version 4, - RFC 3925: + RFC 3925: Vendor-Identifying Vendor Class and Vendor-Identifying Vendor-Specific Information options are supported. Client Identifier Option in DHCP Server Replies, - RFC 6842: + RFC 6842: Server by default sends back client-id option. That capability may be disabled. See for details. @@ -3713,8 +3703,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- User context in IPv4 pools +
User context in IPv4 pools + Kea allows loading hook libraries that sometimes could benefit from additional parameters. If such a parameter is specific to the whole @@ -3758,8 +3748,8 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
-
- DHCPv4 Server Limitations +
DHCPv4 Server Limitations + These are the current limitations of the DHCPv4 server software. Most of them are reflections of the current stage of development and should be treated as not implemented @@ -3769,7 +3759,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> - BOOTP (RFC 951) + BOOTP (RFC 951) is not supported. This is a design choice: BOOTP support is not planned. @@ -3786,7 +3776,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc --> The DHCPv4 server does not verify that - assigned address is unused. According to RFC 2131, the + assigned address is unused. According to RFC 2131, the allocating server should verify that address is not used by sending ICMP echo request. @@ -3810,4 +3800,4 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
--> - + \ No newline at end of file diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 9c7ca469ce..2df77554ff 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -1,14 +1,9 @@ - - -]> + +The DHCPv6 Server + - - The DHCPv6 Server - -
- Starting and Stopping the DHCPv6 Server +
Starting and Stopping the DHCPv6 Server + It is recommended that the Kea DHCPv6 server be started and stopped @@ -120,10 +115,10 @@ strings path/kea-dhcp6 | sed -n 's/;;;; //p'
-
- DHCPv6 Server Configuration -
- Introduction +
DHCPv6 Server Configuration + +
Introduction + This section explains how to configure the DHCPv6 server using the Kea configuration backend. (Kea configuration using any other @@ -196,8 +191,8 @@ the configuration file must be well formed JSON. That means that parameters for any given scope must be separated by a comma and there must not be a comma after the last parameter. When reordering a configuration file, keep in mind that moving a parameter to or from the last position in a given scope may also require -moving the comma. The second caveat is that it is uncommon — although -legal JSON — to +moving the comma. The second caveat is that it is uncommon — although +legal JSON — to repeat the same parameter multiple times. If that happens, the last occurrence of a given parameter in a given scope is used while all previous instances are ignored. This is unlikely to cause any confusion as there are no real life @@ -282,17 +277,16 @@ components defined such as Logging or DhcpDdns, so the closing brace would be followed by a comma and another object definition.
-
- Lease Storage +
Lease Storage + All leases issued by the server are stored in the lease database. Currently there are four database backends available: memfile (which is the default backend), MySQL, PostgreSQL and Cassandra. -
- Memfile - Basic Storage for Leases +
Memfile - Basic Storage for Leases + The server is able to store lease data in different repositories. Larger - deployments may elect to store leases in a database. describes this option. In typical + deployments may elect to store leases in a database. describes this option. In typical smaller deployments though, the server will store lease information in a CSV file rather than a database. As well as requiring less administration, an advantage of using a file for storage is that it @@ -403,13 +397,13 @@ be followed by a comma and another object definition. file used by the server to record lease updates. There are also other files being created as a side effect of the lease file cleanup. The detailed description of the LFC is located on the Kea wiki: - . + http://kea.isc.org/wiki/LFCDesign.
-
- Lease Database Configuration +
Lease Database Configuration + Lease database access information must be configured for the DHCPv6 server, @@ -464,8 +458,8 @@ If a timeout is given though, it should be an integer greater than zero.
-
- Hosts Storage +
Hosts Storage + Kea is also able to store information about host reservations in the database. The hosts database configuration uses the same syntax as the lease database. In fact, a Kea server opens independent connections for each @@ -484,8 +478,8 @@ If a timeout is given though, it should be an integer greater than zero. from the configuration file are checked first and external storage is checked later, if necessary. -
- DHCPv6 Hosts Database Configuration +
DHCPv6 Hosts Database Configuration + Hosts database configuration is controlled through the Dhcp6/hosts-database parameters. If enabled, the type of the database must be set to "mysql" or @@ -523,8 +517,8 @@ If a timeout is given though, it should be an integer greater than zero. "". (This is also the default.)
-
-Using Read-Only Databases for Host Reservations +
Using Read-Only Databases for Host Reservations + In some deployments the database user whose name is specified in the database backend configuration may not have write privileges to the database. This is often @@ -557,8 +551,8 @@ for MySQL and PostgreSQL databases.
-
- Interface Selection +
Interface Selection + The DHCPv6 server has to be configured to listen on specific network interfaces. The simplest network interface configuration instructs the server to listen on all available interfaces: @@ -596,8 +590,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- IPv6 Subnet Identifier +
IPv6 Subnet Identifier + The subnet identifier is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with their respective subnets. @@ -641,8 +635,8 @@ temporarily override a list of interface names and listen on all interfaces. id -->
-
- Unicast Traffic Support +
Unicast Traffic Support + When the DHCPv6 server starts, by default it listens to the DHCP traffic sent to multicast address ff02::1:2 on each interface that it is @@ -697,8 +691,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Subnet and Address Pool +
Subnet and Address Pool + The main 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 @@ -798,11 +792,11 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Subnet and Prefix Delegation Pools +
Subnet and Prefix Delegation Pools + Subnets may also be configured to delegate prefixes, as defined in - RFC 3633. A + RFC 3633. A subnet may have one or more prefix delegation pools. Each pool has a prefixed address, which is specified as a prefix (prefix) and a prefix length @@ -835,12 +829,12 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Prefix Exclude Option +
Prefix Exclude Option + For each delegated prefix the delegating router may choose to exclude a single prefix out of the delegated prefix as specified in the - RFC 6603. + RFC 6603. The requesting router must not assign the excluded prefix to any of its downstream interfaces and it is intended to be used on a link through which the delegating router exchanges DHCPv6 messages with @@ -870,8 +864,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Standard DHCPv6 Options +
Standard DHCPv6 Options + One of the major features of a DHCPv6 server is to provide configuration options to clients. Although there are several options that require @@ -903,13 +897,11 @@ temporarily override a list of interface names and listen on all interfaces. information on all global options that the server is supposed to configure in all subnets. The name line specifies the option name. (For a complete list - of currently supported names, see .) The next line specifies the option code, + of currently supported names, see .) The next line specifies the option code, which must match one of the values from that list. The line beginning with space specifies the option space, which must always be set to "dhcp6" as these are standard DHCPv6 options. For other name spaces, - including custom option spaces, see . The following line specifies the format in + including custom option spaces, see . The following line specifies the format in which the data will be entered: use of CSV (comma separated values) is recommended. Finally, the data line gives the actual value to be sent to clients. Data is specified as normal text, with values separated by @@ -1075,13 +1067,13 @@ temporarily override a list of interface names and listen on all interfaces. - - List of Standard DHCPv6 Options - - - - - +
List of Standard DHCPv6 Options + + + + + + NameCodeTypeArray? @@ -1113,7 +1105,7 @@ temporarily override a list of interface names and listen on all interfaces. interface-id18binaryfalsereconf-msg19uint8falsereconf-accept20emptyfalse --> ---> +--> sip-server-dns21fqdntruesip-server-addr22ipv6-addresstruedns-servers23ipv6-addresstrue @@ -1166,13 +1158,13 @@ temporarily override a list of interface names and listen on all interfaces. -
- List of Experimental DHCPv6 Options - - - - - +
List of Experimental DHCPv6 Options + + + + + + NameCodeTypeArray? @@ -1187,18 +1179,18 @@ temporarily override a list of interface names and listen on all interfaces. -
- Common Softwire46 Options +
Common Softwire46 Options + Softwire46 options are involved in IPv4 over IPv6 provisioning by means of tunneling or translation as specified in the - RFC 7598. + RFC 7598. The following sections provide configuration examples of these options. -
- Softwire46 Container Options +
Softwire46 Container Options + S46 container options group rules and optional port parameters for a specified domain. There are three container options specified @@ -1237,8 +1229,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- S46 Rule Option +
S46 Rule Option + The S46 Rule option is used for conveying the Basic Mapping Rule (BMR) and Forwarding Mapping Rule (FMR). @@ -1291,8 +1283,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- S46 BR Option +
S46 BR Option + The S46 BR option is used to convey the IPv6 address of the Border Relay. This option is mandatory in the MAP-E @@ -1309,8 +1301,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- S46 DMR Option +
S46 DMR Option + The S46 DMR option is used to convey values for the Default Mapping Rule (DMR). This option is mandatory in the MAP-T @@ -1327,8 +1319,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- S46 IPv4/IPv6 Address Binding option. +
S46 IPv4/IPv6 Address Binding option. + The S46 IPv4/IPv6 Address Binding option may be used to specify the full or shared IPv4 address of the Customer Edge (CE). @@ -1344,8 +1336,8 @@ temporarily override a list of interface names and listen on all interfaces. This option must not be included in other containers.
-
- S46 Port Parameters +
S46 Port Parameters + The S46 Port Parameters option specifies optional port set information that MAY be provided to CEs @@ -1368,8 +1360,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Custom DHCPv6 Options +
Custom DHCPv6 Options + It is possible to define options in addition to the standard ones. Assume that we want to define a new DHCPv6 option called "foo" which will have code 100 and which will convey a single unsigned 32 bit integer value. We can define @@ -1493,8 +1485,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- DHCPv6 Vendor-Specific Options +
DHCPv6 Vendor-Specific Options + Currently there are two option spaces defined for the DHCPv6 daemon: "dhcp6" (for top level DHCPv6 options) and "vendor-opts-space", @@ -1564,8 +1556,8 @@ temporarily override a list of interface names and listen on all interfaces.
-
- Nested DHCPv6 Options (Custom Option Spaces) +
Nested DHCPv6 Options (Custom Option Spaces) + It is sometimes useful to define completely new option spaces. This is useful if the user wants their new option to convey sub-options that use a separate numbering scheme, for @@ -1668,14 +1660,14 @@ should include options from the isc option space: required to carry an uint16 value as well as the sub-options, the "type" value would have to be set to "uint16" in the option definition. (Such an option would then have the following data structure: DHCP header, uint16 - value, sub-options.) The value specified with the "data" parameter — which - should be a valid integer enclosed in quotes, e.g. "123" — would then be + value, sub-options.) The value specified with the "data" parameter — which + should be a valid integer enclosed in quotes, e.g. "123" — would then be assigned to the uint16 field in the "container" option.
-
- Unspecified Parameters for DHCPv6 Option Configuration +
Unspecified Parameters for DHCPv6 Option Configuration + In many cases it is not required to specify all parameters for an option configuration and the default values can be used. However, it is important to understand the implications of not specifying some of them @@ -1744,8 +1736,8 @@ should include options from the isc option space:
-
- IPv6 Subnet Selection +
IPv6 Subnet Selection + The DHCPv6 server may receive requests from local (connected to the same subnet as the server) and remote (connecting via relays) clients. @@ -1782,10 +1774,10 @@ should include options from the isc option space:
-
- Rapid Commit +
Rapid Commit + The Rapid Commit option, described in - RFC 3315, is supported + RFC 3315, is supported by the Kea DHCPv6 server. However, support is disabled by default for all subnets. It can be enabled for a particular subnet using the rapid-commit parameter as shown below: @@ -1816,8 +1808,8 @@ should include options from the isc option space:
-
- DHCPv6 Relays +
DHCPv6 Relays + A DHCPv6 server with multiple subnets defined must select the appropriate subnet when it receives a request from a client. For clients @@ -1885,9 +1877,9 @@ should include options from the isc option space:
-
- Relay-Supplied Options - RFC 6422 +
Relay-Supplied Options + + RFC 6422 defines a mechanism called Relay-Supplied DHCP Options. In certain cases relay agents are the only entities that may have specific information. They can insert options when relaying messages from the client to the server. The @@ -1898,7 +1890,7 @@ should include options from the isc option space: included. First, the server must not provide the option itself. In other words, if both relay and server provide an option, the server always takes precedence. Second, the option must be RSOO-enabled. IANA maintains a - list of RSOO-enabled options here. + list of RSOO-enabled options here. However, there may be cases when system administrators want to echo other options. Kea can be instructed to treat other options as RSOO-enabled. For example, to mark options 110, 120 and 130 as RSOO-enabled, the following @@ -1915,15 +1907,15 @@ should include options from the isc option space: mark it. Also, when enabling standard options, it is possible to use their names, rather than option code, e.g. (e.g. use dns-servers instead of 23). See - for the names. In certain cases + for the names. In certain cases it could also work for custom options, but due to the nature of the parser code this may be unreliable and should be avoided.
-
- Client Classification in DHCPv6 +
Client Classification in DHCPv6 + The DHCPv6 server includes support for client classification. For a deeper @@ -1975,12 +1967,12 @@ should include options from the isc option space: clients that do not meet class criteria to be denied any service altogether. -
- Defining and Using Custom Classes +
Defining and Using Custom Classes + The following example shows how to configure a class using an expression and a subnet making use of that class. This configuration defines the - class named "Client_enterprise". It is comprised + class named "Client_enterprise". It is comprised of all clients whose client identifiers start with the given hex string (which would indicate a DUID based on an enterprise id of 0xAABBCCDD). They will be given an address from 2001:db8:1::0 to 2001:db8:1::FFFF and @@ -2042,14 +2034,14 @@ should include options from the isc option space:
-
- DDNS for DHCPv6 +
DDNS for DHCPv6 + As mentioned earlier, kea-dhcp6 can be configured to generate requests to the DHCP-DDNS server (referred to here as "D2") to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information: - + Whether it is a request to add (update) or remove DNS entries @@ -2128,8 +2120,8 @@ should include options from the isc option space: -
- DHCP-DDNS Server Connectivity +
DHCP-DDNS Server Connectivity + In order for NCRs to reach the D2 server, kea-dhcp6 must be able to communicate with it. kea-dhcp6 uses the following configuration @@ -2195,10 +2187,10 @@ should include options from the isc option space:
-
- When Does kea-dhcp6 Generate a DDNS Request? +
When Does kea-dhcp6 Generate a DDNS Request? + kea-dhcp6 follows the behavior prescribed for DHCP servers in - RFC 4704. + RFC 4704. It is important to keep in mind that kea-dhcp6 provides the initial decision making of when and what to update and forwards that information to D2 in the form of NCRs. Carrying out the actual @@ -2219,7 +2211,7 @@ should include options from the isc option space: In general, kea-dhcp6 will generate DDNS update requests when: - + A new lease is granted in response to a REQUEST @@ -2243,13 +2235,13 @@ should include options from the isc option space: By default kea-dhcp6 will respect the FQDN N and S flags specified by the client as shown in the following table: -
- Default FQDN Flag Behavior - - - - - +
Default FQDN Flag Behavior + + + + + + Client Flags:N-S @@ -2296,7 +2288,7 @@ should include options from the isc option space: (Note that the flag combination N=1, S=1 is prohibited according to - RFC 4702. If such a + RFC 4702. If such a combination is received from the client, the packet will be dropped by kea-dhcp6.) @@ -2332,8 +2324,8 @@ should include options from the isc option space: } -
- kea-dhcp6 Name Generation for DDNS Update Requests +
kea-dhcp6 Name Generation for DDNS Update Requests + Each NameChangeRequest must of course include the fully qualified domain name whose DNS entries are to be affected. kea-dhcp6 can be configured to supply a portion or all of that name based upon what it @@ -2341,7 +2333,7 @@ should include options from the isc option space: The default rules for constructing the FQDN that will be used for DNS entries are: - + If the DHCPREQUEST contains the client FQDN option, the candidate name is taken from there. @@ -2465,11 +2457,11 @@ should include options from the isc option space:
-
- DHCPv4-over-DHCPv6: DHCPv6 Side +
DHCPv4-over-DHCPv6: DHCPv6 Side + The support of DHCPv4-over-DHCPv6 transport is described in - RFC 7341 + RFC 7341 and is implemented using cooperating DHCPv4 and DHCPv6 servers. This section is about the configuration of the DHCPv6 side (the DHCPv4 side is described in ). @@ -2555,12 +2547,12 @@ should include options from the isc option space: -
- Host Reservation in DHCPv6 +
Host Reservation in DHCPv6 + There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve specific, static IPv6 - address or/and prefix for exclusive use by a given client (host) ‐ returning + address or/and prefix for exclusive use by a given client (host) ‐ returning client will get the same address or/and prefix every time and other clients will never get that address. Note that there may be cases when the new reservation has been made for the client for the address or prefix being @@ -2670,8 +2662,8 @@ should include options from the isc option space: could be used by someone else (i.e. if there is a reservation for it). That additional check incurs additional overhead. -
- Address/Prefix Reservation Types +
Address/Prefix Reservation Types + In a typical scenario there is an IPv6 subnet defined with a certain part of it dedicated for dynamic address allocation by the DHCPv6 @@ -2691,8 +2683,8 @@ should include options from the isc option space: possible.
-
- Conflicts in DHCPv6 Reservations +
Conflicts in DHCPv6 Reservations + As reservations and lease information are stored separately, conflicts may arise. Consider the following series of events. The server has configured the dynamic pool of addresses from the range of 2001:db8::10 @@ -2740,8 +2732,8 @@ should include options from the isc option space:
-
- Reserving a Hostname +
Reserving a Hostname + When the reservation for the client includes the hostname, the server will assign this hostname to the client and send it back in the Client FQDN, if the client sent the FQDN option to the @@ -2801,14 +2793,12 @@ should include options from the isc option space:
-
- Including Specific DHCPv6 Options in Reservations +
Including Specific DHCPv6 Options in Reservations + Kea 1.1.0 introduced the ability to specify options on a per host basis. The options follow the same rules as any other - options. These can be standard options (see ), custom options (see ) or vendor specific options - (see ). The following + options. These can be standard options (see ), custom options (see ) or vendor specific options + (see ). The following example demonstrates how standard options can be defined. @@ -2856,8 +2846,8 @@ should include options from the isc option space:
-
- Reserving Client Classes in DHCPv6 +
Reserving Client Classes in DHCPv6 + The explains how to configure the server to assign classes to a client based on the content of the options that this client sends to the server. Host reservations @@ -2908,15 +2898,13 @@ should include options from the isc option space: with classification using expressions.
-
- Storing Host Reservations in MySQL or PostgreSQL +
Storing Host Reservations in MySQL or PostgreSQL + - It is possible to store host reservations in MySQL or PostgreSQL. See for information on how to configure Kea to use + It is possible to store host reservations in MySQL or PostgreSQL. See for information on how to configure Kea to use reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated - tools for managing reservations in a database. The Kea wiki provides detailed + tools for managing reservations in a database. The Kea wiki http://kea.isc.org/wiki/HostReservationsHowTo provides detailed information and examples of how reservations can be inserted into the database. @@ -2925,14 +2913,14 @@ should include options from the isc option space: arbitrarily set to 4096 bytes.
-
- Storing Host Reservations in CQL (Cassandra) +
Storing Host Reservations in CQL (Cassandra) + Kea currently does not support storing reservations in Cassandra (CQL).
-
- Fine Tuning DHCPv6 Host Reservation +
Fine Tuning DHCPv6 Host Reservation + The host reservation capability introduces additional restrictions for the allocation engine (the component of Kea that selects an address for a client) @@ -3046,14 +3034,14 @@ If not specified, the default value is:
-
- Server Identifier in DHCPv6 +
Server Identifier in DHCPv6 + The DHCPv6 protocol uses a "server identifier" (also known as a DUID) for clients to be able to discriminate between several servers present on the same link. - RFC 3315 + RFC 3315 defines three DUID types: DUID-LLT, DUID-EN and DUID-LL. - RFC 6355 + RFC 6355 also defines DUID-UUID. Future specifications may introduce new DUID types. @@ -3062,7 +3050,7 @@ If not specified, the default value is: modified across restarts of the server and so is a stable identifier. Kea follows recommendation from - RFC 3315 + RFC 3315 to use DUID-LLT as the default server identifier. However, we have received reports that some deployments require different DUID types, and there is a need to administratively select both DUID @@ -3280,8 +3268,8 @@ If not specified, the default value is: identifier is explicitly specified in the configuration.
-
- Stateless DHCPv6 (Information-Request Message) +
Stateless DHCPv6 (Information-Request Message) + Typically DHCPv6 is used to assign both addresses and options. These assignments (leases) have state that changes over time, hence their name, stateful. DHCPv6 also supports a stateless mode, @@ -3325,9 +3313,9 @@ If not specified, the default value is: even if it is not used.
-
- Support for RFC 7550 - The RFC 7550 +
Support for RFC 7550 + + The RFC 7550 introduced some changes to the DHCPv6 protocol to resolve a few issues with the coexistence of multiple stateful options in the messages sent between the clients and servers. @@ -3348,17 +3336,17 @@ If not specified, the default value is: NoPrefixAvail status code. However, if the server can now allocate the prefixes it will do so, and send them in the IA_PD(s) to the client. Allocation of leases during the Renew/Rebind was not supported in the - RFC 3315 - and RFC 3633, + RFC 3315 + and RFC 3633, and has been introduced in - RFC 7550. + RFC 7550. Kea supports this new behavior and it doesn't provide any configuration mechanisms to disable it. The following are the other behaviors specified in the - RFC 7550 + RFC 7550 supported by the Kea DHCPv6 server: Set T1/T2 timers to the same value for all @@ -3372,8 +3360,8 @@ If not specified, the default value is:
-
- Using Specific Relay Agent for a Subnet +
Using Specific Relay Agent for a Subnet + The relay has to have an interface connected to the link on which the clients are being configured. Typically the relay has a global IPv6 @@ -3422,8 +3410,8 @@ If not specified, the default value is:
-
- Segregating IPv6 Clients in a Cable Network +
Segregating IPv6 Clients in a Cable Network + In certain cases, it is useful to mix relay address information, introduced in with client @@ -3471,8 +3459,8 @@ If not specified, the default value is:
-
- MAC/Hardware Addresses in DHCPv6 +
MAC/Hardware Addresses in DHCPv6 + MAC/hardware addresses are available in DHCPv4 messages from the clients and administrators frequently use that information to perform certain tasks, like per host @@ -3531,7 +3519,7 @@ If not specified, the default value is: duid - DHCPv6 uses DUID identifiers instead of MAC addresses. There are currently four DUID types defined, with two of them (DUID-LLT, which is the default one and DUID-LL) convey MAC address information. - Although RFC 3315 forbids + Although RFC 3315 forbids it, it is possible to parse those DUIDs and extract necessary information from them. This method is not completely reliable, as clients may use other DUID types, namely DUID-EN or DUID-UUID. @@ -3544,18 +3532,18 @@ If not specified, the default value is: that those addresses are based on EUI-64, which contains MAC address. This method is not completely reliable, as clients may use other link-local address types. In particular, privacy extensions, defined in - RFC 4941, do not use + RFC 4941, do not use MAC addresses. Also note that successful extraction requires that the address's u-bit must be set to 1 and its g-bit set to 0, indicating that it is an interface identifier as per - - RFC 2373, section 2.5.1. + + RFC 2373, section 2.5.1. client-link-addr-option - One extension defined to alleviate missing MAC issues is client link-layer address option, defined - in RFC 6939. This is + in RFC 6939. This is an option that is inserted by a relay and contains information about client's MAC address. This method requires a relay agent that supports the option and is configured to insert it. This method is useless for directly connected @@ -3565,7 +3553,7 @@ If not specified, the default value is: remote-id - - RFC 4649 + RFC 4649 defines a remote-id option that is inserted by a relay agent. Depending on the relay agent configuration, the inserted option may convey the client's MAC address information. This parameter can also be specified as @@ -3575,8 +3563,8 @@ If not specified, the default value is: subscriber-id - Another option that is somewhat similar to the previous one is subscriber-id, - defined in RFC - 4580. It is, too, inserted by a relay agent that is + defined in RFC + 4580. It is, too, inserted by a relay agent that is configured to insert it. This parameter can also be specified as rfc4580, which is an alias for subscriber-id. This method is currently not @@ -3608,8 +3596,8 @@ If not specified, the default value is: which is the default.
-
- Duplicate Addresses (DECLINE Support) +
Duplicate Addresses (DECLINE Support) + The DHCPv6 server is configured with a certain pool of addresses that it is expected to hand out to the DHCPv6 clients. @@ -3680,22 +3668,22 @@ If not specified, the default value is: the available pool.
-
- Statistics in the DHCPv6 Server +
Statistics in the DHCPv6 Server + This section describes DHCPv6-specific statistics. For a general - overview and usage of statistics, see . + overview and usage of statistics, see . The DHCPv6 server supports the following statistics: -
- DHCPv6 Statistics - - - - +
DHCPv6 Statistics + + + + + Statistic @@ -4034,12 +4022,12 @@ If not specified, the default value is:
-
- Management API for the DHCPv6 Server +
Management API for the DHCPv6 Server + The management API allows the issuing of specific management commands, such as statistics retrieval, reconfiguration or shutdown. - For more details, see . Currently the only + For more details, see . Currently the only supported communication channel type is UNIX stream socket. By default there are no sockets open. To instruct Kea to open a socket, the following entry in the configuration file can be used: @@ -4078,13 +4066,13 @@ If not specified, the default value is: and statistic-remove-all, specified in . It also supports list-commands and shutdown, - specified in and - , respectively. + specified in and + , respectively.
-
- User context in IPv6 pools +
User context in IPv6 pools + Kea allows loading hook libraries that sometimes could benefit from additional parameters. If such a parameter is specific to the whole @@ -4137,19 +4125,18 @@ If not specified, the default value is: Currently only address and prefix pools allow definition of user contexts, but this concept is expected to be enhanced to other - structures in the future. For more background information, see + structures in the future. For more background information, see
-
- Supported DHCPv6 Standards +
Supported DHCPv6 Standards + The following standards are currently supported: Dynamic Host Configuration Protocol for IPv6, - RFC 3315: + RFC 3315: Supported messages are SOLICIT, ADVERTISE, REQUEST, RELEASE, RENEW, REBIND, INFORMATION-REQUEST, CONFIRM and REPLY. @@ -4157,37 +4144,37 @@ If not specified, the default value is: IPv6 Prefix Options for Dynamic Host Configuration Protocol (DHCP) version 6, - RFC 3633: + RFC 3633: Supported options are IA_PD and IA_PREFIX. Also supported is the status code NoPrefixAvail. DNS Configuration options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6), - RFC 3646: + RFC 3646: Supported option is DNS_SERVERS. The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Relay Agent Remote-ID Option, - RFC 4649: + RFC 4649: REMOTE-ID option is supported. The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) Option, - RFC 4704: + RFC 4704: Supported option is CLIENT_FQDN. Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Option for Dual-Stack Lite, - RFC 6334: + RFC 6334: the AFTR-Name DHCPv6 Option is supported. Relay-Supplied DHCP Options, - RFC 6422: + RFC 6422: Full functionality is supported: OPTION_RSOO, ability of the server to echo back the options, checks whether an option is RSOO-enabled, ability to mark additional options as RSOO-enabled. @@ -4195,35 +4182,35 @@ If not specified, the default value is: Prefix Exclude Option for DHCPv6-based Prefix Delegation, - RFC - 6603: Prefix Exclude option is supported. + RFC + 6603: Prefix Exclude option is supported. Client Link-Layer Address Option in DHCPv6, - RFC - 6939: Supported option is client link-layer + RFC + 6939: Supported option is client link-layer address option. Issues and Recommendations with Multiple Stateful DHCPv6 Options, - RFC - 7550: All recommendations related to the DHCPv6 server + RFC + 7550: All recommendations related to the DHCPv6 server operation are supported. DHCPv6 Options for Configuration of Softwire Address and Port-Mapped Clients, - RFC - 7598: All options specified in this specification are + RFC + 7598: All options specified in this specification are supported by the DHCPv6 server.
-
- DHCPv6 Server Limitations +
DHCPv6 Server Limitations + These are the current limitations of the DHCPv6 server software. Most of them are reflections of the early stage of development and should be treated as not implemented @@ -4233,8 +4220,8 @@ If not specified, the default value is: The server will allocate, renew or rebind a maximum of one lease for a particular IA option (IA_NA or IA_PD) sent by a client. - RFC 3315 and - RFC 3633 allow + RFC 3315 and + RFC 3633 allow for multiple addresses or prefixes to be allocated for a single IA. @@ -4268,4 +4255,4 @@ If not specified, the default value is:
--> - + \ No newline at end of file diff --git a/doc/guide/faq.xml b/doc/guide/faq.xml index 66157bf292..b4e158b01e 100644 --- a/doc/guide/faq.xml +++ b/doc/guide/faq.xml @@ -1,11 +1,6 @@ - - -]> - - - Frequently Asked Questions + +Frequently Asked Questions + This chapter contains a number of frequently asked questions and troubleshooting tips. It currently lacks content, but it is expected to grow @@ -17,20 +12,20 @@ at least 2 years. If you have something short term, please consider putting it in the known issues list. --> -
- General Frequently Asked Questions +
General Frequently Asked Questions + -
- Where did the Kea name came from? +
Where did the Kea name came from? + Kea is the name of a high mountain parrot living in New Zealand. - See this + See this https://lists.isc.org/pipermail/kea-users/2014-October/000032.html for an extended answer.
-
- Feature X is not supported yet. When/if will it be available? +
Feature X is not supported yet. When/if will it be available? + Kea is developed by a small team of engineers. Our resources are limited, so we need to prioritize requests. The complexity of a new @@ -62,7 +57,7 @@ significant new features, like support for a new database type. Before considering writing and submitting a patch, make sure you read the Contributor's Guide in the - Kea Developer's Guide. + Kea Developer's Guide. Kea is developed by ISC, which is a non-profit organization. @@ -79,8 +74,8 @@ violates a RFC, we may have a problem with that. Nevertheless, please talk to us and we may be able to find a solution. - Finally, Kea has a public - roadmap, with releases happening several times each year. We tend + Finally, Kea has a public + roadmap, with releases happening several times each year. We tend to not modify plans for the current milestone, unless there are very good reasons to do so. Therefore "I'd like a feature X in 6 months" is much better received than "I'd like a feature X now". @@ -88,11 +83,11 @@
-
- Frequently Asked Questions about DHCPv4 +
Frequently Asked Questions about DHCPv4 + -
- I set up a firewall, but the Kea server still receives the traffic. Why? +
I set up a firewall, but the Kea server still receives the traffic. Why? + Any DHCPv4 server must be able to receive from and send traffic to hosts that don't have an IPv4 address assigned yet. That is typically not @@ -103,7 +98,7 @@ If you do not want the server to use raw sockets, it is possible to configure the Kea DHCPv4 server to use UDP sockets instead. See dhcp-socket-type - described in . However, + described in . However, using UDP sockets has certain limitations. In particular, they may not allow for sending responses directly to clients without IPv4 addresses assigned. That's ok, if all your traffic is coming through relay agents. @@ -111,12 +106,12 @@
-
- Frequently Asked Questions about DHCPv6 +
Frequently Asked Questions about DHCPv6 + -
- Kea DHCPv6 doesn't seem to get incoming traffic. I checked with tcpdump (or other traffic - capture software) that the incoming traffic is reaching the box. What's wrong? +
Kea DHCPv6 doesn't seem to get incoming traffic. I checked with tcpdump (or other traffic + capture software) that the incoming traffic is reaching the box. What's wrong? + Please check whether your OS has any IPv6 filtering rules. Many operating systems are shipped with firewalls that discard incoming IPv6 @@ -132,4 +127,4 @@
- + \ No newline at end of file diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 429d864a67..28e0eb8c55 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -1,13 +1,8 @@ - - -]> - - - Hooks Libraries -
- Introduction + +Hooks Libraries + +
Introduction + Although Kea offers a lot of flexibility, there may be cases where its behavior needs customisation. To accommodate this possibility, @@ -35,12 +30,12 @@ The next section describes how to configure hooks libraries. If you are interested in writing your own hooks library, information can be - found in the Kea - Developer's Guide. + found in the Kea + Developer's Guide.
-
- Configuring Hooks Libraries +
Configuring Hooks Libraries + The hooks libraries for a given process are configured using the hooks-libraries keyword in the @@ -108,7 +103,7 @@ Notes: - + The full path to each library should be given. @@ -139,8 +134,8 @@
-
- Available Hooks Libraries +
Available Hooks Libraries + As described above, the hooks functionality provides a way to customize a Kea server without modifying the core code. ISC has chosen to take @@ -162,12 +157,12 @@ Currently the following libraries are available or planned from ISC: - - List of available hooks libraries - - - - +
List of available hooks libraries + + + + + Name @@ -209,7 +204,7 @@ Support customers Autumn 2016 Lightweight 4over6 - (RFC 7596) + (RFC 7596) is a new IPv6 transition technology that provides IPv4 as a service in IPv6-only network. It assumes that dual-stack clients will get a regular IPv6 @@ -220,7 +215,7 @@ expensive Carrier Grade NATs within the operator's network. The problem on the DHCP side is the non-trivial logic behind it: each client needs to receive an unique set of lightweight 4over6 options - (RFC 7598), + (RFC 7598), that include the IPv4 address (shared among several clients), port-set (which is unique among clients sharing the same IPv4 address) and a number of additional parameters. This hooks @@ -238,14 +233,13 @@ ISC hopes to see more hooks libraries become available as time progresses, both developed internally and externally. Since this list may evolve dynamically, we decided to keep it on a - wiki page, available at this link: http://kea.isc.org/wiki/Hooks. + wiki page, available at this link: http://kea.isc.org/wiki/Hooks. If you are a developer or are aware of any hooks libraries not listed there, please send a note to the kea-users or kea-dev mailing lists and someone will update it. -
- user_chk: Checking User Access +
user_chk: Checking User Access + The user_chk library is the first hooks library published by ISC. It attempts to serve several purposes: @@ -331,17 +325,15 @@ and may have the zero or more of the following entries: As with any other hooks libraries provided by ISC, internals of the - user_chk code are well documented. You can take a look at the Kea Developer's Guide section dedicated to the user_chk library + user_chk code are well documented. You can take a look at the Kea Developer's Guide section dedicated to the user_chk library that discusses how the code works internally. That, together with - our general entries in Hooks - Framework section should give you some pointers how to extend + our general entries in Hooks + Framework section should give you some pointers how to extend this library and perhaps even write your own from scratch.
-
- Forensic Logging Hooks +
Forensic Logging Hooks + This section describes the forensic log hooks library. This library povides hooks that record a detailed log of lease assignments @@ -364,8 +356,8 @@ and may have the zero or more of the following entries: features those users who don't need to log this information can leave it out and avoid any performance penalties. -
- Log File Naming +
Log File Naming + The names for the log files have the following form: @@ -373,7 +365,7 @@ and may have the zero or more of the following entries: path/base-name.CCYYMMDD.txt - The "path" and "base-name" are supplied in the + The "path" and "base-name" are supplied in the configuration as described below see . The next part of the name is the date the log file was started, with four digits for year, two digits @@ -384,8 +376,8 @@ path/base-name.CCYYMMDD.txt be distinct. See the examples in .
-
- DHCPv4 Log Entries +
DHCPv4 Log Entries + For DHCPv4 the library creates entries based on DHCPREQUEST messages and corresponding DHCPv4 leases intercepted by lease4_select @@ -408,7 +400,7 @@ address duration device-id {client-info} {relay-info} duration - the lease lifetime expressed in days (if present), hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be - denoted with the text "infinite duration". + denoted with the text "infinite duration". device-id - the client's hardware address shown as numerical type @@ -436,8 +428,8 @@ connected via relay at address: 192.2.16.33, identified by circuit-id:
-
- DHCPv6 Log Entries +
DHCPv6 Log Entries + For DHCPv6 the library creates entries based on lease management actions intercepted by the lease6_select (for new leases), lease6_renew @@ -483,15 +475,15 @@ link address: 3001::1, hop count: 1, identified by remote-id:
-
- Configuring the Forensic Log Hooks +
Configuring the Forensic Log Hooks + To use this functionality the hook library must be included in the configuration of the desired DHCP server modules. The legal_log library is installed alongside the Kea libraries in [kea-install-dir]/lib where kea-install-dir is determined by the - "--prefix" option of the configure script. It defaults to + "--prefix" option of the configure script. It defaults to /usr/local. Assuming the default value then, configuring kea-dhcp4 to load the legal_log library could be done with the following Kea4 configuration: @@ -545,8 +537,8 @@ link address: 3001::1, hop count: 1, identified by remote-id:
-
- User contexts +
User contexts + Hook libraries can have their own configuration parameters. That is convenient if the parameter applies to the whole library. However, sometimes it is very useful if certain configuration entities are extended @@ -564,4 +556,4 @@ link address: 3001::1, hop count: 1, identified by remote-id: user context capability.
- + \ No newline at end of file diff --git a/doc/guide/install.xml b/doc/guide/install.xml index 4525f4b58c..0ae82c240a 100644 --- a/doc/guide/install.xml +++ b/doc/guide/install.xml @@ -1,14 +1,9 @@ - - -]> + +Installation + - - Installation - -
- Packages +
Packages + Some operating systems or software package vendors may provide @@ -25,63 +20,63 @@
-
- Installation Hierarchy +
Installation Hierarchy + The following is the directory layout of the complete Kea installation. (All directory paths are relative to the installation directory): - bin/ — + bin/ — utility programs. - etc/kea/ — + etc/kea/ — configuration files. - include/ — + include/ — C++ development header files. - lib/ — + lib/ — libraries. - sbin/ — + sbin/ — server software and commands used by the system administrator. - share/kea/ — + share/kea/ — configuration specifications and examples. - share/doc/kea/ — + share/doc/kea/ — this guide, other supplementary documentation, and examples. - share/man/ — + share/man/ — manual pages (online documentation). - var/kea/ — + var/kea/ — server identification, lease databases, and log files. @@ -89,12 +84,11 @@
-
- Building Requirements +
Building Requirements + - In addition to the run-time requirements (listed in ), building Kea from source code requires + In addition to the run-time requirements (listed in ), building Kea from source code requires various development include headers and program development tools. @@ -113,7 +107,7 @@ Boost build-time headers - (). + (http://www.boost.org/). At least Boost version 1.41 is required. When header-only Boost error code is not available or wanted, the Boost system library is required too. @@ -197,33 +191,32 @@ Debian and Ubuntu: Visit the user-contributed wiki at - + http://kea.isc.org/wiki/SystemSpecificNotes for system-specific installation tips.
-
- Installation from Source +
Installation from Source + Kea is open source software written in C++. It is freely available in source code form from ISC as a downloadable tar file. A copy of the Kea - source code repository is accessible from Github (). Kea may also be available + source code repository is accessible from Github (https://github.com/isc-projects/kea). Kea may also be available in pre-compiled ready-to-use packages from operating system vendors. -
+
Download Tar File - Download Tar File + The Kea release tarballs may be downloaded from: - (using FTP or HTTP). + http://ftp.isc.org/isc/kea/ (using FTP or HTTP).
-
- Retrieve from Git +
Retrieve from Git + Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production @@ -241,7 +234,7 @@ Debian and Ubuntu: The latest development code is available on Github (see - ). The Kea source + https://github.com/isc-projects/kea). The Kea source is public and development is done in the master branch. @@ -271,18 +264,18 @@ Debian and Ubuntu: are a developer planning to contribute to Kea, please fork our Github repository and use the "pull request" mechanism to request integration of your code. Please consult - for help on + https://help.github.com/articles/fork-a-repo/ for help on how to fork a Github repository. - The Kea - Developer's Guide contains more information about the process, as + The Kea + Developer's Guide contains more information about the process, as well as describing the requirements for contributed code to be accepted by ISC.
-
- Configure Before the Build +
Configure Before the Build + Kea uses the GNU Build System to discover build environment details. @@ -348,7 +341,7 @@ Debian and Ubuntu: Google Test framework. This option specifies the path to the gtest source. (If the framework is not installed on your system, it can be downloaded - from .) + from https://code.google.com/p/googletest.) @@ -379,7 +372,7 @@ Debian and Ubuntu: For instructions concerning the installation and configuration of database backends for Kea, see . For information concerning the configuration backends, see - . + . @@ -421,8 +414,8 @@ Debian and Ubuntu:
-
- Build +
Build + After the configure step is complete, build the executables from the C++ code and prepare the Python scripts by running the command: @@ -430,8 +423,8 @@ Debian and Ubuntu:
-
- Install +
Install + To install the Kea executables, support files, and documentation, issue the command: @@ -469,8 +462,8 @@ Debian and Ubuntu:
-
- Selecting the Configuration Backend +
Selecting the Configuration Backend + Kea 0.9 introduced configuration backends that are switchable during the compilation phase. Only one backend, JSON, is currently supported. @@ -493,8 +486,8 @@ Debian and Ubuntu:
-
- DHCP Database Installation and Configuration +
DHCP Database Installation and Configuration + Kea stores its leases in a lease database. The software has been written in a way that makes it possible to choose which database product @@ -512,13 +505,13 @@ Debian and Ubuntu: When unit tests are built with Kea (the --with-gtest configuration option is specified), the databases must be manually pre-configured for the unit tests to run. The details of this configuration can be found in the - Kea Developer's - Guide. + Kea Developer's + Guide. -
- Building with MySQL Support +
Building with MySQL Support + Install MySQL according to the instructions for your system. The client development libraries must be installed. @@ -539,11 +532,11 @@ Debian and Ubuntu:
-
- Building with PostgreSQL support +
Building with PostgreSQL support + Install PostgreSQL according to the instructions for your system. The client development - libraries must be installed. Client development libraries are often packaged as "libpq". + libraries must be installed. Client development libraries are often packaged as "libpq". Build and install Kea as described in , with @@ -561,17 +554,16 @@ Debian and Ubuntu:
-
- Building with CQL (Cassandra) support +
Building with CQL (Cassandra) support + Install Cassandra according to the instructions for your system. The - Cassandra project website contains useful pointers: . + Cassandra project website contains useful pointers: http://cassandra.apache.org. Download and compile cpp-driver from DataStax. For details regarding dependencies for building cpp-driver, see the project homepage - . In June + https://github.com/datastax/cpp-driver. In June 2016, the following commands were used: $ git clone https://github.com/datastax/cpp-driver @@ -602,4 +594,4 @@ $ make
- + \ No newline at end of file diff --git a/doc/guide/intro.xml b/doc/guide/intro.xml index 55a0578f88..3180583fd9 100644 --- a/doc/guide/intro.xml +++ b/doc/guide/intro.xml @@ -1,13 +1,6 @@ - - - -%version; -]> - - - Introduction + +Introduction + Kea is the next generation of DHCP software developed by ISC. It supports both DHCPv4 and DHCPv6 protocols along with their @@ -22,11 +15,11 @@ - This guide covers Kea version &__VERSION__;. + This guide covers Kea version . -
- Supported Platforms +
Supported Platforms + Kea is officially supported on Red Hat Enterprise Linux, CentOS, Fedora and FreeBSD systems. It is also likely to work on many @@ -39,8 +32,8 @@ There are currently no plans to port Kea to Windows platforms.
-
- Required Software at Run-time +
Required Software at Run-time + Running Kea uses various extra software which may @@ -57,9 +50,9 @@ Kea supports two crypto libraries: Botan and OpenSSL. Only one of them is required to be installed during compilation. Kea uses the Botan - crypto library for C++ (), + crypto library for C++ (http://botan.randombit.net/), version 1.8 or later. As an alternative to Botan, Kea can use the - OpenSSL crypto library (), + OpenSSL crypto library (http://www.openssl.org/), version 1.0.1 or later. @@ -67,7 +60,7 @@ Kea uses the log4cplus C++ logging library - (). + (http://log4cplus.sourceforge.net/). It requires log4cplus version 1.0.3 or later. @@ -98,8 +91,8 @@
-
- Kea Software +
Kea Software + Kea is modular. Part of this modularity is accomplished using multiple cooperating processes which, together, @@ -113,7 +106,7 @@ - keactrl — + keactrl — Tool to start, stop, reconfigure, and report status for the Kea servers. @@ -121,7 +114,7 @@ - kea-dhcp4 — + kea-dhcp4 — The DHCPv4 server process. This process responds to DHCPv4 queries from clients. @@ -129,7 +122,7 @@ - kea-dhcp6 — + kea-dhcp6 — The DHCPv6 server process. This process responds to DHCPv6 queries from clients. @@ -137,7 +130,7 @@ - kea-dhcp-ddns — + kea-dhcp-ddns — The DHCP Dynamic DNS process. This process acts as an intermediary between the DHCP servers and DNS servers. It receives name update requests from the DHCP @@ -147,7 +140,7 @@ - kea-admin — + kea-admin — A useful tool for database backend maintenance (creating a new database, checking versions, upgrading etc.) @@ -155,7 +148,7 @@ - kea-lfc — + kea-lfc — This process removes redundant information from the files used to provide persistent storage for the memfile data base backend. While it can be run standalone, it is normally run as and when @@ -165,7 +158,7 @@ - perfdhcp — + perfdhcp — A DHCP benchmarking tool which simulates multiple clients to test both DHCPv4 and DHCPv6 server performance. @@ -189,4 +182,4 @@ - + \ No newline at end of file diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index de59667525..19c0597df7 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -1,25 +1,8 @@ - - - -%version; -]> - - - - + + - - - + <info><title> <inlinemediaobject> <imageobject> <imagedata fileref="kea-logo-100x70.png" align="left"/> @@ -28,68 +11,57 @@ Kea Administrator Reference Manual + + This is the reference guide for Kea version - &__VERSION__;. + . 2010-2016Internet Systems Consortium, Inc. - - - - Kea is an open source implementation of the Dynamic Host Configuration - Protocol (DHCP) servers, developed and maintained by Internet Systems - Consortium (ISC). - - - - This is the reference guide for Kea version &__VERSION__;. - The most up-to-date version of this document (in PDF, HTML, - and plain text formats), along with other documents for - Kea, can be found at . - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - Acknowledgments + Acknowledgments + Kea is primarily designed, developed, and maintained by Internet Systems Consortium, Inc. It is an open source project @@ -97,31 +69,31 @@ Support for the development of the DHCPv4, DHCPv6 and DHCP-DDNS components was provided by - Comcast. + Comcast. Kea was initially implemented as a collection of applications within the BIND 10 framework. Hence, Kea development would not be possible without the generous support of past BIND 10 project sponsors. - JPRS and - CIRA were Patron Level + JPRS and + CIRA were Patron Level BIND 10 sponsors. - AFNIC, - CNNIC, - CZ.NIC, - DENIC eG, - Google, - RIPE NCC, - Registro.br, - .nz Registry Services, and - Technical Center of Internet + AFNIC, + CNNIC, + CZ.NIC, + DENIC eG, + Google, + RIPE NCC, + Registro.br, + .nz Registry Services, and + Technical Center of Internet were past BIND 10 sponsors. - Afilias, - IIS.SE, - Nominet, and - SIDN were founding + Afilias, + IIS.SE, + Nominet, and + SIDN were founding sponsors of the BIND 10 project. @@ -134,4 +106,4 @@ - + \ No newline at end of file diff --git a/doc/guide/keactrl.xml b/doc/guide/keactrl.xml index 8122cd3894..cfd5ba13dd 100644 --- a/doc/guide/keactrl.xml +++ b/doc/guide/keactrl.xml @@ -1,14 +1,9 @@ - - -]> + +Managing Kea with keactrl + - - Managing Kea with keactrl - -
- Overview +
Overview + keactrl is a shell script which controls the startup, shutdown and reconfiguration of the Kea servers (kea-dhcp4, kea-dhcp6 and kea-dhcp-ddns). It @@ -17,8 +12,8 @@
-
- Command Line Options +
Command Line Options + keactrl is run as follows: keactrl <command> [-c keactrl-config-file] [-s server[,server,..]] @@ -50,8 +45,8 @@ keactrl <command> [-c keactrl-config-file] [-s server[,server,..]]
-
- The keactrl Configuration File +
The keactrl Configuration File + Depending on requirements, not all of the available servers need be run. The keactrl configuration file sets which servers are @@ -137,8 +132,8 @@ kea_verbose=no
-
- Commands +
Commands + The following commands are supported by keactrl: @@ -253,8 +248,8 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf
-
- Overriding the Server Selection +
Overriding the Server Selection + The optional -s switch allows the selection of the servers to which keactrl @@ -308,4 +303,4 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf
- + \ No newline at end of file diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index abca79b0f3..51a0bc2bb6 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -1,10 +1,6 @@ - - -]> - - Lease Expiration in DHCPv4 and DHCPv6 + +Lease Expiration in DHCPv4 and DHCPv6 + The primary role of the DHCP server is to assign addresses and/or delegate prefixes to DHCP clients. These addresses and prefixes are @@ -47,8 +43,8 @@ DHCPv6 server configuration. -
- Lease Reclamation +
Lease Reclamation + Lease reclamation is the process through which an expired lease becomes available for assignment to the same or different client. This process involves the following steps for each reclaimed lease: @@ -81,8 +77,8 @@ hooks libraries.
-
- Configuring Lease Reclamation +
Configuring Lease Reclamation + Kea can be configured to periodically detect and reclaim expired leases. During this process the lease entries in the database are modified or removed. While this is happening the server will not process incoming DHCP @@ -122,8 +118,8 @@ | c1 | | c2 | |c3| | c4 | -|<---->|<---------->|<-->|<---------->|<>|<---------->|<-->| -----------------------------------------------------------------> +|<---->|<---------->|<-->|<---------->|<>|<---------->|<-->| +----------------------------------------------------------------> | | 5s | | 5s | | 5s | | time @@ -187,8 +183,8 @@ | c1 | | c2 | | c3 | | c4 | -|<-->|<-------------->|<-->|<-------------->|<-->|<-------------->|<-->|<-- -------------------------------------------------------------------------------> +|<-->|<-------------->|<-->|<-------------->|<-->|<-------------->|<-->|<-- +------------------------------------------------------------------------------> |50ms| 3s |50ms| 3s |50ms| 3s |50ms| time @@ -225,8 +221,8 @@ periodic reclamation of the expired leases.
-
- Configuring Lease Affinity +
Configuring Lease Affinity + Suppose that a laptop goes to a sleep mode after a period of user inactivity. While the laptop is in sleep mode, its DHCP client will not renew leases obtained from the server and these leases will eventually @@ -295,8 +291,8 @@ process may impact server responsiveness.
-
- Default Configuration Values for Leases Reclamation +
Default Configuration Values for Leases Reclamation + The following list presents all configuration parameters pertaining to processing expired leases with their default values: @@ -329,12 +325,12 @@
-
- Reclaiming Expired Leases with Command +
Reclaiming Expired Leases with Command + The leases-reclaim command can be used to trigger leases reclamation at any time. Please consult the for the details about using this command.
- + \ No newline at end of file diff --git a/doc/guide/lfc.xml b/doc/guide/lfc.xml index f6580e83fa..6c30d289b0 100644 --- a/doc/guide/lfc.xml +++ b/doc/guide/lfc.xml @@ -1,14 +1,9 @@ - - -]> + +The LFC process + - - The LFC process - -
- Overview +
Overview + kea-lfc is a service process that removes redundant information from the files used to provide persistent storage for the memfile data base backend. This service is written to run as a @@ -26,8 +21,8 @@
-
- Command Line Options +
Command Line Options + kea-lfc is run as follows: kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o output-file -f finish-file @@ -54,7 +49,7 @@ kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o ou - previous — + previous — When kea-lfc starts this is the result of any previous run of kea-lfc. When kea-lfc finishes it is the result of this run. @@ -63,21 +58,21 @@ kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o ou - input — + input — Before the DHCP server invokes kea-lfc it will move the current lease file here and then call kea-lfc with this file. - output — + output — The temporary file kea-lfc should use to write the leases. Upon completion of writing this file, it will be moved to the finish file (see below). - finish — + finish — Another temporary file kea-lfc uses for bookkeeping. When kea-lfc completes writing the outputfile it moves it to this file name. After kea-lfc finishes deleting the other files @@ -97,4 +92,4 @@ kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o ou
- + \ No newline at end of file diff --git a/doc/guide/libdhcp.xml b/doc/guide/libdhcp.xml index 851c87469f..d953a58f67 100644 --- a/doc/guide/libdhcp.xml +++ b/doc/guide/libdhcp.xml @@ -1,11 +1,6 @@ - - -]> - - - The libdhcp++ Library + +The libdhcp++ Library + libdhcp++ is a library written in C++ that handles many DHCP-related tasks, including: @@ -32,8 +27,8 @@ -
- Interface detection and Socket handling +
Interface detection and Socket handling + Both the DHCPv4 and DHCPv6 components share network interface detection routines. Interface detection is currently supported on Linux, all BSD family (FreeBSD, NetBSD, @@ -53,4 +48,4 @@
--> - + \ No newline at end of file diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index 24f9bbea7a..405c7a8f68 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -1,26 +1,9 @@ - - -]> - - - - - Logging - -
- Logging Configuration + +Logging + + +
Logging Configuration + During its operation Kea may produce many messages. They differ in severity (some are more important than others) and source (some are @@ -40,8 +23,8 @@ logging configuration between daemons. -
- Loggers +
Loggers + Within Kea, a message is logged through an entity called a "logger". Different components log messages through different @@ -77,7 +60,7 @@ severity or greater to standard output. There is also a small time window after Kea has been started, but has not yet read its configuration. Logging in this short period can be controlled - using environment variables. For details, see . + using environment variables. For details, see . @@ -89,8 +72,8 @@ debug-level logging has been selected. -
- name (string) +
name (string) + Each logger in the system has a name, the name being that of the component binary file using it to log messages. For instance, if you @@ -171,8 +154,8 @@ that might match a particular logger, the specification with the more specific logger name takes precedence. For example, if there are entries for both kea-dhcp4 and - kea-dhcp4.dhcpsrv, the DHCPv4 server — and all - libraries it uses that are not dhcpsrv — will log messages + kea-dhcp4.dhcpsrv, the DHCPv4 server — and all + libraries it uses that are not dhcpsrv — will log messages according to the configuration in the first entry (kea-dhcp4). @@ -501,8 +484,8 @@
-
- severity (string) +
severity (string) + This specifies the category of messages logged. Each message is logged with an associated severity which may be one of the following @@ -568,8 +551,8 @@
-
- debuglevel (integer) +
debuglevel (integer) + When a logger's severity is set to DEBUG, this value specifies what level of debug messages should be printed. It ranges from 0 (least @@ -578,16 +561,16 @@
-
- output_options (list) +
output_options (list) + Each logger can have zero or more . These specify where log messages are sent. These are explained in detail below. -
- output (string) +
output (string) + This value determines the type of output. There are several special values allowed here: stdout (messages are printed @@ -599,8 +582,8 @@
-
- flush (true of false) +
flush (true of false) + Flush buffers after each log message. Doing this will reduce performance but will ensure that if the program terminates @@ -609,13 +592,13 @@
-
- maxsize (integer) +
maxsize (integer) + Only relevant when destination is file, this is maximum file size of output files in bytes. When the maximum size is reached, the file is renamed and a new file opened. (For example, a ".1" is appended to - the name — if a ".1" file exists, it is renamed ".2", etc.) + the name — if a ".1" file exists, it is renamed ".2", etc.) If this is set to 0 or omitted, no maximum file size is used. @@ -636,8 +619,8 @@
-
- maxver (integer) +
maxver (integer) + Maximum number of old log files to keep around when rolling the output file. Only relevant when is @@ -646,8 +629,8 @@
-
- Example Logger Configurations +
Example Logger Configurations + In this example we want to set the global logging to write to the console using standard output. @@ -695,8 +678,8 @@
-
- Logging Message Format +
Logging Message Format + Each message written to the configured logging destinations comprises a number of components that identify the origin of the message and, if the @@ -762,9 +745,9 @@ The message identification. Every message in Kea has a unique identification, which can be used as an index into the - Kea Messages - Manual - () + Kea Messages + Manual + (http://kea.isc.org/docs/kea-messages.html) from which more information can be obtained. @@ -786,8 +769,8 @@
-
- Logging During Kea Startup +
Logging During Kea Startup + The logging configuration is specified in the configuration file. However, when Kea starts, the file is not read until some way into the @@ -864,4 +847,4 @@
- + \ No newline at end of file diff --git a/doc/guide/quickstart.xml b/doc/guide/quickstart.xml index 74e97f174c..77a9ebdea1 100644 --- a/doc/guide/quickstart.xml +++ b/doc/guide/quickstart.xml @@ -1,13 +1,6 @@ - - - -%version; -]> - - - Quick Start + +Quick Start + This section describes the basic steps needed to get Kea up and running. @@ -15,34 +8,33 @@ respective chapters in the Kea guide. -
- Quick Start Guide for DHCPv4 and DHCPv6 Services +
Quick Start Guide for DHCPv4 and DHCPv6 Services + - + - Install required run-time and build dependencies. See for details. + Install required run-time and build dependencies. See for details. - Download Kea source tarball from ISC.org downloads page or ISC ftp server. + Download Kea source tarball from ISC.org downloads page or ISC ftp server. Extract the tarball. For example: - $ tar xvzf kea-&__VERSION__;.tar.gz + $ tar xvzf kea-.tar.gz Go into the source directory and run the configure script: - $ cd kea-&__VERSION__; + $ cd kea- $ ./configure [your extra parameters] @@ -96,7 +88,7 @@ $ ./configure [your extra parameters] If the server has been started successfully, test that it is responding to DHCP queries and that the client receives a configuration from the server; for example, use - the ISC DHCP client. + the ISC DHCP client. @@ -109,16 +101,16 @@ $ ./configure [your extra parameters] For instructions specific to your system, please read the - system specific notes, - available on the Kea web site. + system specific notes, + available on the Kea web site. The details of keactrl script usage can be found in .
-
- Running the Kea Servers Directly +
Running the Kea Servers Directly + The Kea servers can be started directly, without the need to use the keactrl. To start the DHCPv4 server run the following command: @@ -128,4 +120,4 @@ $ ./configure [your extra parameters]
- + \ No newline at end of file diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 17164c4df6..437a106871 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -1,14 +1,9 @@ - - -]> + +Statistics + - - Statistics - -
- Statistics Overview +
Statistics Overview + Both Kea DHCP servers support statistics gathering. A working DHCP server encounters various events @@ -51,13 +46,12 @@ During normal operation, DHCPv4 and DHCPv6 servers gather statistics. - For a list of DHCPv4 and DHCPv6 statistics, see and , respectively. + For a list of DHCPv4 and DHCPv6 statistics, see and , respectively. To extract data from the statistics module, the control channel can be - used. See for details. It is possible to + used. See for details. It is possible to retrieve a single or all statistics, reset statistics (i.e. set to neutral value, typically zero) or even remove completely a single or all statistics. See section for a list of @@ -65,8 +59,8 @@
-
- Statistics Lifecycle +
Statistics Lifecycle + It is useful to understand how the Statistics Manager module works. When the server starts operation, the manager is empty and does not have any @@ -99,8 +93,8 @@
-
- Commands for Manipulating Statistics +
Commands for Manipulating Statistics + There are several commands defined that can be used for accessing (-get), resetting to zero or neutral value (-reset) or even removing a statistic @@ -120,8 +114,8 @@ sending commands to Kea, see . -
- statistic-get command +
statistic-get command + statistic-get command retrieves a single @@ -146,8 +140,8 @@
-
- statistic-reset command +
statistic-reset command + statistic-reset command sets the specified statistic @@ -173,8 +167,8 @@
-
- statistic-remove command +
statistic-remove command + statistic-remove command attempts to delete a single @@ -199,8 +193,8 @@
-
- statistic-get-all command +
statistic-get-all command + statistic-get-all command retrieves all statistics @@ -219,8 +213,8 @@
-
- statistic-reset-all command +
statistic-reset-all command + statistic-reset command sets all statistics to @@ -241,8 +235,8 @@
-
- statistic-remove-all command +
statistic-remove-all command + statistic-remove-all command attempts to delete all @@ -264,4 +258,4 @@
- + \ No newline at end of file diff --git a/src/bin/admin/kea-admin.xml b/src/bin/admin/kea-admin.xml index 7ef4788f96..88c11eed99 100644 --- a/src/bin/admin/kea-admin.xml +++ b/src/bin/admin/kea-admin.xml @@ -1,30 +1,17 @@ -]> - - - - + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + kea-admin @@ -45,30 +32,30 @@ - + kea-admin - command - backend - - - - - - + command + backend + + + + + + - - DESCRIPTION + DESCRIPTION + kea-admin is a shell script which offers database maintenance. In particular, it features database initialization, database version checking and database schema upgrade. - + - - OPTIONS + OPTIONS + @@ -198,10 +185,10 @@ - + - - SEE ALSO + SEE ALSO + keactrl @@ -236,6 +223,6 @@ Kea Administrator Guide. - + - + \ No newline at end of file diff --git a/src/bin/d2/kea-dhcp-ddns.xml b/src/bin/d2/kea-dhcp-ddns.xml index dde8d0a7d4..15577ea28a 100644 --- a/src/bin/d2/kea-dhcp-ddns.xml +++ b/src/bin/d2/kea-dhcp-ddns.xml @@ -1,31 +1,18 @@ -]> - - - - - + + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + kea-dhcp-ddns @@ -46,19 +33,19 @@ - + kea-dhcp-ddns - - - - - + + + + + - - DESCRIPTION + DESCRIPTION + The kea-dhcp-ddns service process requests to update DNS mapping based on DHCP lease change events. It runs as @@ -66,10 +53,10 @@ from Kea DHCP servers. - + - - ARGUMENTS + ARGUMENTS + The arguments are as follows: @@ -113,10 +100,10 @@ - + - - DOCUMENTATION + DOCUMENTATION + Kea comes with an extensive Kea User's Guide documentation that covers all aspects of running the Kea software - compilation, installation, configuration, configuration examples @@ -134,10 +121,10 @@ Kea project website is available at: http://kea.isc.org. - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -150,10 +137,10 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - HISTORY + HISTORY + The b10-dhcp-ddns process was first coded in May 2013 by Thomas Markwalder. @@ -163,10 +150,10 @@ removed. The DHCP-DDNS server binary was renamed to kea-dhcp-ddns in July 2014. Kea 1.0.0 was released in December 2015. - + - - SEE ALSO + SEE ALSO + kea-dhcp4 @@ -201,10 +188,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/dhcp4/kea-dhcp4.xml b/src/bin/dhcp4/kea-dhcp4.xml index f9270343d6..1780c5f773 100644 --- a/src/bin/dhcp4/kea-dhcp4.xml +++ b/src/bin/dhcp4/kea-dhcp4.xml @@ -1,31 +1,18 @@ -]> - - - - - + + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + kea-dhcp4 @@ -46,28 +33,28 @@ - + kea-dhcp4 - - - - - - + + + + + + - - DESCRIPTION + DESCRIPTION + The kea-dhcp4 daemon provides the DHCPv4 server implementation. - + - - ARGUMENTS + ARGUMENTS + The arguments are as follows: @@ -118,10 +105,10 @@ - + - - DOCUMENTATION + DOCUMENTATION + Kea comes with an extensive Kea User's Guide documentation that covers all aspects of running the Kea software - compilation, installation, configuration, configuration examples @@ -139,10 +126,10 @@ Kea project website is available at: http://kea.isc.org. - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -155,10 +142,10 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - HISTORY + HISTORY + The b10-dhcp4 daemon was first coded in November 2011 by Tomek Mrugalski. @@ -168,10 +155,10 @@ standalone DHCP server. The DHCPv4 server binary was renamed to kea-dhcp4. Kea 1.0.0 was released in December 2015. - + - - SEE ALSO + SEE ALSO + kea-dhcp6 @@ -206,10 +193,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/dhcp6/kea-dhcp6.xml b/src/bin/dhcp6/kea-dhcp6.xml index 5c5b4d5510..f9d58ba04a 100644 --- a/src/bin/dhcp6/kea-dhcp6.xml +++ b/src/bin/dhcp6/kea-dhcp6.xml @@ -1,31 +1,18 @@ -]> - - - - - + + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + kea-dhcp6 @@ -46,28 +33,28 @@ - + kea-dhcp6 - - - - - - + + + + + + - - DESCRIPTION + DESCRIPTION + The kea-dhcp6 daemon provides the DHCPv6 server implementation. - + - - ARGUMENTS + ARGUMENTS + The arguments are as follows: @@ -119,10 +106,10 @@ - + - - DOCUMENTATION + DOCUMENTATION + Kea comes with an extensive Kea User's Guide documentation that covers all aspects of running the Kea software - compilation, installation, configuration, configuration examples @@ -140,10 +127,10 @@ Kea project website is available at: http://kea.isc.org. - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -156,10 +143,10 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - HISTORY + HISTORY + The b10-dhcp6 daemon was first coded in June 2011 by Tomek Mrugalski. @@ -169,10 +156,10 @@ removed. The DHCPv6 server binary was renamed to kea-dhcp6 in July 2014. - + - - SEE ALSO + SEE ALSO + kea-dhcp4 @@ -207,10 +194,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/keactrl/keactrl.xml b/src/bin/keactrl/keactrl.xml index a0dd422e00..2ff5c6d5ed 100644 --- a/src/bin/keactrl/keactrl.xml +++ b/src/bin/keactrl/keactrl.xml @@ -1,30 +1,17 @@ -]> - - - - + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + keactrl @@ -45,16 +32,16 @@ - + keactrl - command - - + command + + - - DESCRIPTION + DESCRIPTION + keactrl is a shell script which controls the startup, shutdown and reconfiguration of the Kea servers (kea-dhcp4, @@ -62,10 +49,10 @@ also provides the means for checking the current status of the servers and determining the configuration files in use. - + - - CONFIGURATION FILE + CONFIGURATION FILE + Depending on requirements, not all of the available servers need be run. The keactrl configuration file sets which servers are @@ -76,10 +63,10 @@ See the Kea Administrator's Guide for the documentation of the parameters in the keactrl configuration file. - + - - OPTIONS + OPTIONS + @@ -177,10 +164,10 @@ - + - - DOCUMENTATION + DOCUMENTATION + Kea comes with an extensive Kea User's Guide documentation that covers all aspects of running the Kea software - compilation, installation, configuration, configuration examples @@ -198,10 +185,10 @@ Kea project website is available at: http://kea.isc.org. - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -214,10 +201,10 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - SEE ALSO + SEE ALSO + kea-dhcp4 @@ -253,6 +240,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/lfc/kea-lfc.xml b/src/bin/lfc/kea-lfc.xml index 32c5265d04..dce5b7b1c3 100644 --- a/src/bin/lfc/kea-lfc.xml +++ b/src/bin/lfc/kea-lfc.xml @@ -1,31 +1,18 @@ -]> - - - - - + + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + kea-lfc @@ -46,25 +33,25 @@ - + kea-lfc - - - - - - - - - - - - + + + + + + + + + + + + - - DESCRIPTION + DESCRIPTION + The kea-lfc service process removes redundant information from the files used to provide persistent storage for @@ -73,10 +60,10 @@ is usually no need to do this. It will be run on a periodic basis by the Kea DHCP servers. - + - - ARGUMENTS + ARGUMENTS + The arguments are as follows: @@ -193,10 +180,10 @@ - + - - DOCUMENTATION + DOCUMENTATION + Kea comes with an extensive Kea User's Guide documentation that covers all aspects of running the Kea software - compilation, installation, configuration, configuration examples @@ -214,10 +201,10 @@ Kea project website is available at: http://kea.isc.org. - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -230,18 +217,18 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - HISTORY + HISTORY + The kea-lfc process was first coded in January 2015 by the ISC Kea/DHCP team. - + - - SEE ALSO + SEE ALSO + kea-dhcp4 @@ -276,10 +263,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/perfdhcp/perfdhcp.xml b/src/bin/perfdhcp/perfdhcp.xml index 482523733c..afa02a6998 100644 --- a/src/bin/perfdhcp/perfdhcp.xml +++ b/src/bin/perfdhcp/perfdhcp.xml @@ -1,31 +1,18 @@ -]> - - - - - + + + + ISC Kea Sep. 28, 2016 1.1.0 - - The Kea software has been written by a number of + The Kea software has been written by a number of engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed, Wlodek Wencel and Shawn Routhier. That list is roughly in the chronological order in which the authors made their first contribution. For a complete list of authors and - contributors, see AUTHORS file. - Internet Systems Consortium, Inc. - - + contributors, see AUTHORS file.Internet Systems Consortium, Inc. + perfdhcp @@ -46,47 +33,47 @@ - + perfdhcp - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - server + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + server - - DESCRIPTION + DESCRIPTION + perfdhcp is a DHCP benchmarking tool. It provides a way of measuring the performance of DHCP servers by @@ -114,10 +101,10 @@ perfdhcp, the elapsed time, or the number of requests dropped by the server. - + - - TEMPLATES + TEMPLATES + To allow the contents of packets sent to the server to be customized, perfdhcp allows the specification @@ -213,10 +200,10 @@ or RELEASE packets are being sent. - + - - OPTIONS + OPTIONS + @@ -267,8 +254,7 @@ The base MAC or DUID used to simulate - different clients. The basetype may be "mac" + different clients. The basetype may be "mac" or "duid". (The keyword "ether" may alternatively used for MAC.) The option can be specified multiple times. The MAC address must consist @@ -339,8 +325,7 @@ Rate at which DHCPv4 or DHCPv6 renew requests are sent to a server. This value is only valid when used in conjunction - with the exchange rate (given by ). + with the exchange rate (given by ). Furthermore the sum of this value and the release-rate (given by ) must be equal to or less than @@ -424,10 +409,8 @@ - Initiate preload - exchanges back to back at startup. preload must be 0 + Initiate preload + exchanges back to back at startup. preload must be 0 (the default) or a positive integer. @@ -437,8 +420,7 @@ - Initiate rate DORA/SARR (or + Initiate rate DORA/SARR (or if is given, DO/SA) exchanges per second. A periodic report is generated showing the number of exchanges which were not completed, @@ -455,8 +437,7 @@ Specify how many different clients are used. With a value of 1 (the default), all requests seem - to come from the same client. num-clients must be + to come from the same client. num-clients must be a positive number. @@ -467,8 +448,7 @@ Specify the seed for randomization, making runs of - perfdhcp repeatable. seed is 0 or a positive + perfdhcp repeatable. seed is 0 or a positive integer. The value 0 means that a seed is not used; this is the default. @@ -511,8 +491,7 @@ Include extended diagnostics - in the output. diagnostic-selector + in the output. diagnostic-selector is a string of single-keywords specifying the operations for which verbose output is desired. The selector key letters are: @@ -567,8 +546,8 @@ - - DHCPv4-Only Options + DHCPv4-Only Options + The following options only apply for DHCPv4 (i.e. when is given). @@ -584,10 +563,10 @@ - + - - DHCPv6-Only Options + DHCPv6-Only Options + The following options only apply for DHCPv6 (i.e. when is given). @@ -612,11 +591,9 @@ Rate at which IPv6 RELEASE requests are sent to a server. This value is only valid when used in conjunction with the exchange - rate (given by ). + rate (given by ). Furthermore the sum of this value and the - renew-rate (given by ) + renew-rate (given by ) must be equal to or less than the exchange rate. @@ -637,10 +614,10 @@ - + - - Template-Related Options + Template-Related Options + The following options may only be used in conjunction with and control how perfdhcp @@ -677,8 +654,7 @@ Offset of the last octet to - randomize in the template. random-offset must be + randomize in the template. random-offset must be an integer greater than 3. The switch must be given to use this option. @@ -690,8 +666,7 @@ Offset of the server-ID option in the - (second/request) template. srvid-offset must + (second/request) template. srvid-offset must be a positive integer, and the switch can only be used when the template option () is also given. @@ -711,10 +686,10 @@ - + - - Options Controlling a Test + Options Controlling a Test + The following options may only be used in conjunction with and control both the length of the test @@ -727,12 +702,10 @@ - Abort the test if more than max-drop + Abort the test if more than max-drop requests have been dropped. Use to abort if even a single - request has been dropped. If max-drop includes + request has been dropped. If max-drop includes the suffix '%', it specifies a maximum percentage of requests that may be dropped before abort. In this case, testing of the threshold begins after @@ -745,8 +718,7 @@ - Initiate num-request + Initiate num-request transactions. No report is generated until all transactions have been initiated/waited-for, after which a report is generated and the @@ -759,8 +731,7 @@ - Send requests for test-period, + Send requests for test-period, which is specified in the same manner as . This can be used as an alternative to , or both @@ -780,10 +751,10 @@ - + - - Arguments + Arguments + @@ -803,13 +774,13 @@ - + - + - - ERRORS + ERRORS + perfdhcp can report the following errors in the packet exchange: @@ -843,10 +814,10 @@ - + - - EXIT STATUS + EXIT STATUS + perfdhcp can exit with one of the following @@ -882,15 +853,15 @@ - + - - MAILING LISTS AND SUPPORT + MAILING LISTS AND SUPPORT + There are two mailing lists available for Kea project. kea-users (kea-users at lists.isc.org) is intended for Kea users, while kea-dev @@ -903,20 +874,20 @@ ISC provides professional support for Kea services. See https://www.isc.org/kea/ for details. - + - - HISTORY + HISTORY + The perfdhcp tool was initially coded in October 2011 by John DuBois, Francis Dupont and Marcin Siodelski of ISC. Kea 1.0.0 that included perfdhcp was released in December 2015. - + - - SEE ALSO + SEE ALSO + kea-dhcp4 @@ -951,6 +922,6 @@ Kea Administrator's Guide. - + - + \ No newline at end of file diff --git a/src/bin/sockcreator/kea-sockcreator.xml b/src/bin/sockcreator/kea-sockcreator.xml index c44f3a9c93..4fab630425 100644 --- a/src/bin/sockcreator/kea-sockcreator.xml +++ b/src/bin/sockcreator/kea-sockcreator.xml @@ -1,19 +1,9 @@ -]> - + + - - - - July 1, 2014 - + + 2014-07-01 + kea-sockcreator @@ -34,13 +24,13 @@ - + kea-sockcreator - - DESCRIPTION + DESCRIPTION + The kea-sockcreator daemon's entire job is to create sockets and assign names to them. @@ -53,18 +43,18 @@ if there is an unrecoverable error or unknown command. - + - - SEE ALSO + SEE ALSO + Kea Guide. - + - - HISTORY + HISTORY + The b10-sockcreator daemon was initially designed by Michal Vaner of CZNIC. @@ -74,10 +64,6 @@ removed. The socket creator server binary was renamed to kea-sockcreator in July 2014. - + - + \ No newline at end of file