Kea Database Administration

+ Databases and Database Version Numbers -

Databases and Database Version Numbers Kea supports storing leases and host reservations (i.e. static assignments of addresses, prefixes and options) in one of @@@ -44,7 -52,9 +47,9 @@@

The kea-admin Tool -

+ The kea-admin Tool + To manage the databases, Kea provides the kea-admin tool. It is able to initialize @@@ -139,21 -149,23 +144,23 @@@

Supported Databases -

+ Supported Databases + The following table presents the capabilities of available backends. Please refer to the specific sections dedicated to each backend to better understand their capabilities and limitations. Choosing the right backend may be essential for success or failure of your deployment. -- ++

List of available backends - - -- -- -- -- - - ++ ++ ++ ++ ++ ++ Feature @@@ -226,7 -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. @@@ -256,7 -273,9 +268,9 @@@ 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, you need to create the database area within MySQL and set up @@@ -352,7 -371,9 +366,9 @@@ $ kea-admin lease-init mysq

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 there will be a need to upgrade the existing database. This can @@@ -393,7 -414,9 +409,9 @@@ $ kea-admin lease-upgrade my safely ignored if you are using other database backends. -

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 @@@ -539,7 -563,8 +558,8 @@@ $ kea-admin lease-init pgsq by kea-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 @@@ -574,7 -602,9 +597,9 @@@ $ kea-admin lease-upgrade pg store the data in other backends. -

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 create the keyspace area within CQL. This needs to be done manually: @@@ -644,7 -674,9 +669,9 @@@ $ kea-admin lease-init cql -

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 there will be a need to upgrade the existing database. This can @@@ -706,4 -776,4 +771,4 @@@ $ kea-admin lease-upgrade cq

-- ++ diff --cc doc/guide/agent.xml index 0000000000,904531e9f7..0a1f8ec77a mode 000000,100644..100644 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@@ -1,0 -1,305 +1,300 @@@ - - -]> - - ++ ++ + Kea Control Agent + -

+ Overview + Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which + exposes a RESTful control interface for managing Kea servers. The daemon + can receive control commands over HTTP and either forward these commands + to the respective Kea servers or handle these commands on its own. The + determination whether the command should be handled by the CA or forwarded + is made by checking the value of the 'service' parameter which may be + included in the command from the controlling client. The details of the + supported commands as well as their structures are provided in + . + Hook libraries can be attached to the CA to provide support for + additional commands or custom behavior of existing commands. Such hook + libraries must implement callouts for 'control_command_receive' hook point. + Details about creating new hook libraries and supported hook points can be + found in - Kea Developer's Guide. ++ Kea Developer's Guide. + + + + The CA processes received commands according to the following algorithm: + + + + Pass command into any installed hooks (regardless of service value(s)). + If the command is handled by a hook, return the response. + + + + + + If the service specifies one more or services, the CA will forward the + command to specified services and return the accumulated responses. + + + + + + If service is not specified or is an empty list, the CA will handle + the command if it supports it. + + + + + +

+ -

+ Configuration + The following example demonstrates the basic CA configuration. + + + { + "Control-agent": { + "http-host": "10.20.30.40", + "http-port": 8080, + + "control-sockets": { + "dhcp4": { + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket-v4" + }, + "dhcp6": { + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket-v4" + } + }, + + "hooks-libraries": [ + { + "library": "/opt/local/control-agent-commands.so", + "parameters": { + "param1": "foo" + } + } ] + }, + + "Logging": { + "loggers": [ { + "name": "kea-ctrl-agent", + "severity": "INFO" + } ] + } + } + + + + The http-host and http-port + specify an IP address and port to which HTTP service will be bound. + In case of the example configuration provided above, the RESTful + service will be available under the URL of + http://10.20.30.40:8080/. If these parameters + are not specified, the default URL is http://127.0.0.1:8000/ + + + + It has been mentioned in the that + CA can forward received commands to the specific Kea servers for + processing. For example, config-get is sent to + retrieve configuration of one of the Kea services. When CA receives + this command, including a service parameter + indicating that the client desires to retrieve configuration of + the DHCPv4 server, the CA will forward this command to this server + and then pass the received response back to the client. More about + the service parameter and general structure of + the commands can be found in . + + + + The CA uses unix domain sockets to forward control commands and receive + responses from other Kea services. The dhcp4, + dhcp6 and d2 maps + specify the files to which unix domain sockets are bound. In case + of the configuration above, the CA will connect to the DHCPv4 server + via /path/to/the/unix/socket-v4 to forward the + commands to it. Obviously, the DHCPv4 server must be configured to + listen to connections via this same socket. In other words, the command + socket configuration for the DHCPv4 server and CA (for this server) + must match. Consult the and the + to learn how the socket + configuration is specified for the DHCPv4 and DHCPv6 services. + + + + + We have renamed "dhcp4-server", "dhcp6-server" and "d2-server" + to "dhcp4", "dhcp6" and "d2" respectively after release of Kea 1.2. + If you are migrating from Kea 1.2 you need to tweak your CA config + to use this new naming convention. We have made this incompatible + change to facilitate future use cases where it will be possible to + specify additional values of the "service" parameter to point to + the particular instances of the Kea servers, e.g. "dhcp4/3" + pointing to the 3rd instance of the DHCPv4 server in the + multi-processed configuration. This is not yet supported but the + current renaming lays the ground for it. + + + + + Hooks libraries can be attached to the Control Agent just like to + DHCPv4 and DHCPv6 servers. It currently supports one hook point + 'control_command_receive' which makes it possible to delegate + processing of some commands to the hooks library. The + hooks-libraries list contains the list of hooks + libraries that should be loaded by the CA, along with their configuration + information specified with parameters. + + + + Please consult for the details how to + configure logging. The CA's root logger's name is + kea-ctrl-agent as given in the example above. + +

+ -

+ Secure Connections + + Control Agent doesn't natively support secure HTTP connections like + SSL or TLS. In order to setup secure connection please use one + of the available third party HTTP servers and configure it to run + as a reverse proxy to the Control Agent. Kea has been tested with + two major HTTP server implentations working as a reverse proxy: + Apache2 and nginx. Example configurations including extensive + comments are provided in the doc/examples/https/ + directory. + + + + The reverse proxy forwards HTTP requests received over secure + connection to the Control Agent using (not secured) HTTP. Typically, + the reverse proxy and the Control Agent are running on the same machine, + but it is possible to configure them to run on separate machines as + well. In this case, security depends on the protection of the + communications between the reverse proxy and the Control Agent. + + + Apart from providing the encryption layer for the control channel, + a reverse proxy server is also often used for authentication of the + controlling clients. In this case, the client must present a valid + certificate when it connects via reverse proxy. The proxy server + authenticates the client by checking if the presented certificate is + signed by the certificate authority used by the server. + + To illustrate this, we provide a sample configuration for the + nginx server running as a reverse proxy to the Kea Control Agent. + The server enables authentication of the clients using + certificates. + + + # The server certificate and key can be generated as follows: + # + # openssl genrsa -des3 -out kea-proxy.key 4096 + # openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt + # + # The CA certificate and key can be generated as follows: + # + # openssl genrsa -des3 -out ca.key 4096 + # openssl req -new -x509 -days 365 -key ca.key -out ca.crt + # + # + # The client certificate needs to be generated and signed: + # + # openssl genrsa -des3 -out kea-client.key 4096 + # openssl req -new -key kea-client.key -out kea-client.csr + # openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \ + # -CAkey ca.key -set_serial 01 -out kea-client.crt + # + # Note that the 'common name' value used when generating the client + # and the server certificates must differ from the value used + # for the CA certificate. + # + # The client certificate must be deployed on the client system. + # In order to test the proxy configuration with 'curl' run + # command similar to the following: + # + # curl -k --key kea-client.key --cert kea-client.crt -X POST \ + # -H Content-Type:application/json -d '{ "command": "list-commands" }' \ + # https://kea.example.org/kea + # + # + # + # nginx configuration starts here. + + events { + } + + http { + # HTTPS server + server { + # Use default HTTPS port. + listen 443 ssl; + # Set server name. + server_name kea.example.org; + + # Server certificate and key. + ssl_certificate /path/to/kea-proxy.crt; + ssl_certificate_key /path/to/kea-proxy.key; + + # Certificate Authority. Client certificate must be signed by the CA. + ssl_client_certificate /path/to/ca.crt; + + # Enable verification of the client certificate. + ssl_verify_client on; + + # For URLs such as https://kea.example.org/kea, forward the + # requests to http://127.0.0.1:8080. + location /kea { + proxy_pass http://127.0.0.1:8080; + } + } + } + + + + Note that the configuration snippet provided above is for testing + purposes only. Consult security policies and best practices of your + organization which apply to this setup. + + +

+ -

+ Control Agent Limitations + + Control Agent is a new component, first released in Kea 1.2. In + this release it comes with one notable limitation: + + + + keactrl hasn't been updated to manage the Control Agent (start, stop + reload). As a result, the CA must be started directly as described in + + + + + +

+ -

+ Starting Control Agent + + The CA is started by running its binary and specifying the configuration file + it should use. For example: + + $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea.conf + + +

+ -

+ Connecting to the Control Agent + For an example of tool that can take advantage of the + RESTful API, see . +

- ++ diff --cc doc/guide/classify.xml index f34e06f0b3,4f15a5277c..e78fd404d2 --- a/doc/guide/classify.xml +++ b/doc/guide/classify.xml @@@ -1,7 -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: @@@ -88,14 -95,16 +90,16 @@@

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 @@@ -107,7 -116,8 +111,8 @@@

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 @@@ -142,11 -152,12 +147,12 @@@ -

List of Classification Values -

+ List of Classification Values - - - - + + + + Name @@@ -537,11 -551,12 +546,12 @@@ -

List of Classification Expressions -

+ List of Classification Expressions - - - - + + + + Name @@@ -608,10 -624,12 +619,11 @@@ concatenation of the stringshook 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 @@@ -686,7 -704,8 +698,8 @@@

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" @@@ -883,4 -905,4 +899,4 @@@

-- ++ diff --cc doc/guide/config.xml index 595fc8df9b,645ee9c9e5..809150c3a3 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@@ -1,11 -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 @@@ -16,9 -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. @@@ -140,4 -150,4 +145,4 @@@

-- ++ diff --cc doc/guide/ctrl-channel.xml index 25c4b85aa3,18f9b542a7..d590e93a58 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@@ -1,5 -1,13 +1,6 @@@ - - Management API - - - -%version; -]> - - ++ ++ + Management API A classic approach to daemon configuration assumes that the server's configuration is stored in configuration files @@@ -16,16 -24,58 +17,57 @@@ Both servers can be instructed to open control sockets, which is a communication channel. The server is able to receive commands on that channel, act on them and report back status. - While the set of commands in Kea 1.1.0 is limited, + While the set of commands in Kea 1.2.0 is limited, the number is expected to grow over time. - 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 - for other control channel types will be added in the future. + The DHCPv4 and DHCPv6 servers receive commands over the + unix domain sockets. The details how to configure these sockets, - see and . While it is possible control ++ see and . While it is possible control + the servers directly using unix domain sockets it requires that + the controlling client be running on the same machine as + the server. In order to connect remotely SSH is usually used to + connect to the controlled machine. + + The network administrators usually prefer using some form + of a RESTful API to control the servers, rather than using unix + domain sockets directly. Therefore, as of Kea 1.2.0 release, + Kea includes a new component called Control Agent (or CA) which + exposes a RESTful API to the controlling clients and can forward + commands to the respective Kea services over the unix domain + sockets. The CA configuration has been described in + . + + The HTTP requests received by the CA contain the control + commands encapsulated within HTTP requests. Simply speaking, + the CA is responsible for stripping the HTTP layer from the + received commands and forwarding the commands in a JSON format + over the unix domain sockets to respective services. Because the + CA receives commands for all services it requires additional + "forwarding" information to be included in the client's messages. + This "forwarding" information is carried within the + service parameter of the received command. + If the service parameter is not included or if + the parameter is a blank list the CA will assume that the control + command is targetted at the CA itself and will try to handle + it on its own. + + + Control connections over both HTTP and unix domain sockets are + guarded with timeouts. The default timeout value is set to 10s + and is not configurable. The timeout configuration will be + implemented in the future. -

Data Syntax + + Kea 1.2.0 release and earlier had a limitation of 64kB + on the maximum size of a command and a response sent over the unix + domain socket. This limitation has been removed in Kea 1.3.0 + release. + + + -

+ 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 @@@ -69,21 -193,29 +185,29 @@@ arguments is a map of additional data values returned by the server which is specific to the command issued. The map is always present, even if it contains no data values. + + + + When sending commands via Control Agent, it is possible to specify + multiple services at which the command is targetted. CA will forward this + command to each service individually. Thus, the CA response to the + controlling client will contain an array of individual responses. + + +

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 - is typically an IPAM or similar network management/monitoring software which - may have quite varied expectations regarding the client and is even likely to - be written in languages different than C or C++. Therefore only examples are provided to show - how one can take advantage of the API. -

+ Using the Control Channel + + Kea development team is actively working on providing client applications + which can be used to control the servers. These applications are, however, in the + early stages of development and as of Kea 1.2.0 release have certain limitations. + The easiest way to start playing with the control API is to use common Unix/Linux tools + such as socat and curl. - 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 - distributions. Once Kea is started, one could connect to the control - interface using the following command: + In order to control the given Kea service via unix domain socket, use + socat as follows: $ socat UNIX:/path/to/the/kea/socket - @@@ -96,13 -228,175 +220,175 @@@ will be sent to Kea and the responses r such a simplistic client written in C is available in the Kea Developer's Guide, chapter Control Channel Overview, section Using Control Channel. + In order to use Kea's RESTful API with curl try the + following: + + $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/ + + + This assumes that the Control Agent is running on host + ca.example.org and runs RESTful service on port 8000. + +

Commands Supported by Both the DHCPv4 and DHCPv6 Servers -

+ Commands Supported by Both the DHCPv4 and DHCPv6 Servers + -

+ build-report + + The build-report command returns + on the control channel what the command line + -W argument displays, i.e. the embedded + content of the config.report file. + This command does not take any parameters. + + + { + "command": "build-report" + } + +

+ -

+ config-get + + The config-get command retrieves the current + configuration used by the server. This command does not take any + parameters. The configuration returned is roughly equal to the + configuration that was loaded using -c command line option during server + start-up or later set using config-set command. However, there may be + certain differences. Comments are not retained. If the original + configuration used file inclusion, the returned configuration will + include all parameters from all the included files. + + Note that returned configuration is not redacted, i.e. it will + contain database passwords in plain text if those were specified in the + original configuration. Care should be taken to not expose the command + channel to unprivileged users. + + + An example command invocation looks like this: + + { + "command": "config-get" + } + + +

+ -

+ config-reload + + The config-reload command instructs + Kea to load again the configuration file that was used + previously. This operation is useful if the configuration file + has been changed by some external sources. For example, a + sysadmin can tweak the configuration file and use this command + to force Kea pick up the changes. + + Caution should be taken when mixing this with config-set + commands. Kea remembers the location of the configuration file + it was started with. This configuration can be significantly + changed using config-set command. When config-reload is issued + after config-set, Kea will attempt to reload its original + configuration from the file, possibly losing all changes + introduced using config-set or other commands. + + config-reload does not take any parameters. + An example command invocation looks like this: + + { + "command": "config-reload" + } + + +

+ + -

+ config-test + + + The config-test command instructs the server to check + whether the new configuration supplied in the command's arguments can + be loaded. The supplied configuration is expected to be the full + configuration for the target server along with an optional Logger + configuration. As for the -t command some sanity checks + are not performed so it is possible a configuration which successfully + passes this command will still fail in config-set + command or at launch time. + The structure of the command is as follows: + + + { + "command": "config-test", + "arguments": { - "<server>": { ++ "<server>": { + }, + "Logging": { + } + } + } + + - where <server> is the configuration element name for a given server ++ where <server> is the configuration element name for a given server + such as "Dhcp4" or "Dhcp6". For example: + + + { + "command": "config-test", + "arguments": { + "Dhcp6": { + : + }, + "Logging": { + : + } + } + } + + + The server's response will contain a numeric code, "result" (0 for success, + non-zero on failure), and a string, "text", describing the outcome: + + {"result": 0, "text": "Configuration seems sane..." } + + or + - {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } ++ {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } + + +

+ -

+ config-write + + The config-write command instructs Kea server + to write its current configuration to a file on disk. It takes one + optional argument called filename that specifies + the name of the file to write configuration to. If not specified, the + name used when starting Kea (passed as -c argument) will be + used. If relative path is specified, Kea will write its files + only in the directory it is running. + + An example command invocation looks like this: + + { + "command": "config-write", + "arguments": { + "filename": "config-modified-2017-03-15.json" + } + } + + +

leases-reclaim -

+ leases-reclaim - leases-reclaim command instructs the server to + The leases-reclaim command instructs the server to reclaim all expired leases immediately. The command has the following JSON syntax: @@@ -126,11 -420,36 +412,36 @@@ about the processing of expired leases (leases reclamation).

list-commands -

+ libreload + + + The libreload command will first unload and then + load all currently loaded hook libraries. This is primarily intended + to allow one or more hook libraries to be replaced with newer versions + without requiring Kea servers to be reconfigured or restarted. Note + the hook libraries will be passed the same parameter values (if any) + they were passed when originally loaded. + + { + "command": "libreload", + "arguments": { } + } + + + + The server will respond with a result of 0 indicating success, or 1 + indicating a failure. + +

+ -

+ list-commands + - The list-commands command retrieves a list of all - commands supported by the server. It does not take any arguments. - An example command may look like this: + The list-commands command retrieves a list of all + commands supported by the server. It does not take any arguments. + An example command may look like this: { "command": "list-commands", @@@ -145,25 -464,133 +456,133 @@@

shutdown -

+ config-set + - The shutdown command instructs the server to initiate - its shutdown procedure. It is the equivalent of sending a SIGTERM signal - to the process. This command does not take any arguments. An example - command may look like this: + The config-set command instructs the server to replace + its current configuration with the new configuration supplied in the + command's arguments. The supplied configuration is expected to be the full + configuration for the target server along with an optional Logger + configuration. While optional, the Logger configuration is highly + recommended as without it the server will revert to its default logging + configuration. The structure of the command is as follows: + { - "command": "shutdown", - "arguments": { } + "command": "config-set", + "arguments": { - "<server>": { ++ "<server>": { + }, + "Logging": { + } + } } + - where <server> is the configuration element name for a given server ++ where <server> is the configuration element name for a given server + such as "Dhcp4" or "Dhcp6". For example: + + { + "command": "config-set", + "arguments": { + "Dhcp6": { + : + }, + "Logging": { + : + } + } + } + - The server will respond with a confirmation that the shutdown procedure - has been initiated. + If the new configuration proves to be invalid the server will retain + its current configuration. Please note that the new configuration is + retained in memory only. If the server is restarted or a configuration + reload is triggered via a signal, the server will use the configuration + stored in its configuration file. + + The server's response will contain a numeric code, "result" (0 for success, + non-zero on failure), and a string, "text", describing the outcome: + + {"result": 0, "text": "Configuration successful." } + + or + - {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } ++ {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } + + +

+ -

+ shutdown + + + The shutdown command instructs the server to initiate + its shutdown procedure. It is the equivalent of sending a SIGTERM signal + to the process. This command does not take any arguments. An example + command may look like this: + + { + "command": "shutdown" + } + + + + The server will respond with a confirmation that the shutdown procedure + has been initiated.

+ version-get + + The version-get command returns on the control + channel what the command line -v argument + displays with in arguments the extended version, i.e., what + the command line -V argument displays. This command + does not take any parameters. + + + { + "command": "version-get" + } + +

- -

+ Commands Supported by Control Agent + The following commands listed in + are also supported by the Control Agent, i.e. when the + service parameter is blank the commands are handled + by the CA and they relate to the CA process itself: + + + build-report + + + config-get + + + config-test + + + config-write + + + list-commands + + + shutdown + + + version-get + + + +

+ - ++ diff --cc doc/guide/ddns.xml index bc281cd502,e3f7424aaa..d2d384ff2a --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@@ -1,9 -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 @@@ -44,7 -49,9 +44,9 @@@ 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 and, due to the nature of DDNS, it is run alongside either the @@@ -139,13 -151,15 +146,15 @@@ strings path/kea and the process to which the PID belongs is unrelated to Kea. In such a case it would be necessary to manually delete the PID file. -

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 - configuration is a template that can be customised to your requirements. + Before starting kea-dhcp-ddns module for the + first time, a configuration file needs to be created. The following default + configuration is a template that can be customized to your requirements. "DhcpDdns": { "ip-address": "127.0.0.1", @@@ -167,31 -181,32 +176,32 @@@ The configuration can be divided as follows, each of which is described in its own section: - - - + + + Global Server Parameters - values which control connectivity and global server behavior - - - - - TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers - - - - - Forward DDNS - defines the catalog of Forward DDNS Domains - - - - - Reverse DDNS - defines the catalog of Forward DDNS Domains - - - - -

Global Server Parameters + + + + + TSIG Key Info - defines the TSIG keys used for secure traffic with DNS servers + + + + + Forward DDNS - defines the catalog of Forward DDNS Domains + + + + + Reverse DDNS - defines the catalog of Forward DDNS Domains + + + -

+ Global Server Parameters + ip-address - IP address on which D2 listens for requests. The default is the local loopback interface at @@@ -254,96 -269,97 +264,97 @@@ corresponding values in the DHCP server

TSIG Key List - - A DDNS protocol exchange can be conducted with or without TSIG - (defined in RFC - 2845). This configuration section allows the administrator - to define the set of TSIG keys that may be used in such - exchanges. - - To use TSIG when updating entries in a DNS Domain, - a key must be defined in the TSIG Key List and referenced by - name in that domain's configuration entry. When D2 matches a - change request to a domain, it checks whether the domain has - a TSIG key associated with it. If so, D2 will use that key to - sign DNS update messages sent to and verify responses received - from the domain's DNS server(s). For each TSIG key required by - the DNS servers that D2 will be working with there must be a - corresponding TSIG key in the TSIG Key list. - - - As one might gather from the name, the tsig-key section of the - D2 configuration lists the TSIG keys. Each entry describes a - TSIG key used by one or more DNS servers to authenticate requests - and sign responses. Every entry in the list has three parameters: - - - - name - - a unique text label used to identify this key within the - list. This value is used to specify which key (if any) should be - used when updating a specific domain. So long as it is unique its - content is arbitrary, although for clarity and ease of maintenance - it is recommended that it match the name used on the DNS server(s). - It cannot be blank. - - - - - algorithm - - specifies which hashing algorithm should be used with this - key. This value must specify the same algorithm used for the - key on the DNS server(s). The supported algorithms are listed below: - - - HMAC-MD5 - - - HMAC-SHA1 - - - HMAC-SHA224 -

+ 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. + + To use TSIG when updating entries in a DNS Domain, + a key must be defined in the TSIG Key List and referenced by + name in that domain's configuration entry. When D2 matches a + change request to a domain, it checks whether the domain has + a TSIG key associated with it. If so, D2 will use that key to + sign DNS update messages sent to and verify responses received + from the domain's DNS server(s). For each TSIG key required by + the DNS servers that D2 will be working with there must be a + corresponding TSIG key in the TSIG Key list. + + + As one might gather from the name, the tsig-key section of the + D2 configuration lists the TSIG keys. Each entry describes a + TSIG key used by one or more DNS servers to authenticate requests + and sign responses. Every entry in the list has three parameters: + + + + name - + a unique text label used to identify this key within the + list. This value is used to specify which key (if any) should be + used when updating a specific domain. So long as it is unique its + content is arbitrary, although for clarity and ease of maintenance + it is recommended that it match the name used on the DNS server(s). + It cannot be blank. + - HMAC-SHA256 + + algorithm - + specifies which hashing algorithm should be used with this + key. This value must specify the same algorithm used for the + key on the DNS server(s). The supported algorithms are listed below: + + + HMAC-MD5 + + + HMAC-SHA1 + + + HMAC-SHA224 + + + HMAC-SHA256 + + + HMAC-SHA384 + + + HMAC-SHA512 + + + This value is not case sensitive. + - HMAC-SHA384 + + digest-bits - + is used to specify the minimum truncated length in bits. + The default value 0 means truncation is forbidden, non-zero + values must be an integral number of octets, be greater + than 80 and the half of the full length. Note in BIND9 + this parameter is appended after a dash to the algorithm + name. + - HMAC-SHA512 + + secret - + is used to specify the shared secret key code for this key. This value is + case sensitive and must exactly match the value specified on the DNS server(s). + It is a base64-encoded text value. + - - This value is not case sensitive. - - - - - digest-bits - - is used to specify the minimum truncated length in bits. - The default value 0 means truncation is forbidden, non-zero - values must be an integral number of octets, be greater - than 80 and the half of the full length. Note in BIND9 - this parameter is appended after a dash to the algorithm - name. - - - - - secret - - is used to specify the shared secret key code for this key. This value is - case sensitive and must exactly match the value specified on the DNS server(s). - It is a base64-encoded text value. - - - - - - As an example, suppose that a domain D2 will be updating is - maintained by a BIND9 DNS server which requires dynamic updates - to be secured with TSIG. Suppose further that the entry for - the TSIG key in BIND9's named.conf file looks like this: + + + + As an example, suppose that a domain D2 will be updating is + maintained by a BIND9 DNS server which requires dynamic updates + to be secured with TSIG. Suppose further that the entry for + the TSIG key in BIND9's named.conf file looks like this: : key "key.four.example.com." { @@@ -373,18 -389,19 +384,19 @@@ ... } - + - These steps would be repeated for each TSIG key needed. Note that - the same TSIG key can be used with more than one domain. + These steps would be repeated for each TSIG key needed. Note that + the same TSIG key can be used with more than one domain.

- - -

Forward DDNS - - The Forward DDNS section is used to configure D2's forward update - behavior. Currently it contains a single parameter, the catalog of - forward DDNS Domains, which is a list of structures. + + -

+ Forward DDNS + + The Forward DDNS section is used to configure D2's forward update + behavior. Currently it contains a single parameter, the catalog of + forward DDNS Domains, which is a list of structures. "DhcpDdns": { "forward-ddns": { @@@ -394,59 -411,59 +406,59 @@@ } - By default, this list is empty, which will cause the server to ignore - the forward update portions of requests. - - -

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 - address mapping) for that zone. You will need one forward DDNS - Domain for each zone you wish to service. It may very well - be that some or all of your zones are maintained by the same - servers. You will still need one DDNS Domain per zone. Remember - that matching a request to the appropriate server(s) is done - by zone and a DDNS Domain only defines a single zone. - - - This section describes how to add Forward DDNS Domains. Repeat these - steps for each Forward DDNS Domain desired. Each Forward DDNS Domain - has the following parameters: - - - - name - - The fully qualified domain name (or zone) that this DDNS Domain - can update. This is value used to compare against the request - FQDN during forward matching. It must be unique within the - catalog. - - - - - key-name - - If TSIG is used with this domain's servers, this - value should be the name of the key from within the TSIG Key List - to use. If the value is blank (the default), TSIG will not be - used in DDNS conversations with this domain's servers. - - - - - dns-servers - - A list of one or more DNS servers which can conduct the server - side of the DDNS protocol for this domain. The servers - are used in a first to last preference. In other words, when D2 - begins to process a request for this domain it will pick the - first server in this list and attempt to communicate with it. - If that attempt fails, it will move to next one in the list and - so on until the it achieves success or the list is exhausted. - - - - To create a new forward DDNS Domain, one must add a new domain - element and set its parameters: + By default, this list is empty, which will cause the server to ignore + the forward update portions of requests. + -

+ 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 + address mapping) for that zone. You will need one forward DDNS + Domain for each zone you wish to service. It may very well + be that some or all of your zones are maintained by the same + servers. You will still need one DDNS Domain per zone. Remember + that matching a request to the appropriate server(s) is done + by zone and a DDNS Domain only defines a single zone. + + + This section describes how to add Forward DDNS Domains. Repeat these + steps for each Forward DDNS Domain desired. Each Forward DDNS Domain + has the following parameters: + + + + name - + The fully qualified domain name (or zone) that this DDNS Domain + can update. This is value used to compare against the request + FQDN during forward matching. It must be unique within the + catalog. + + + + + key-name - + If TSIG is used with this domain's servers, this + value should be the name of the key from within the TSIG Key List + to use. If the value is blank (the default), TSIG will not be + used in DDNS conversations with this domain's servers. + + + + + dns-servers - + A list of one or more DNS servers which can conduct the server + side of the DDNS protocol for this domain. The servers + are used in a first to last preference. In other words, when D2 + begins to process a request for this domain it will pick the + first server in this list and attempt to communicate with it. + If that attempt fails, it will move to next one in the list and + so on until the it achieves success or the list is exhausted. + + + + To create a new forward DDNS Domain, one must add a new domain + element and set its parameters: "DhcpDdns": { "forward-ddns": { @@@ -462,48 -479,49 +474,49 @@@ } - It is permissible to add a domain without any servers. If that domain - should be matched to a request, however, the request will fail. In - order to make the domain useful though, we must add at least one DNS - server to it. - - -

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. - - - Forward DNS Server entries represent actual DNS servers which - support the server side of the DDNS protocol. Each Forward DNS Server - has the following parameters: - - - - hostname - - The resolvable host name of the DNS server. This value is not - yet implemented. - - - - - ip-address - - The IP address at which the server listens for DDNS requests. - This may be either an IPv4 or an IPv6 address. - - - - - port - - The port on which the server listens for DDNS requests. It - defaults to the standard DNS service port of 53. - - - - To create a new forward DNS Server, one must add a new server - element to the domain and fill in its parameters. If for - example the service is running at "172.88.99.10", then set it as - follows: + It is permissible to add a domain without any servers. If that domain + should be matched to a request, however, the request will fail. In + order to make the domain useful though, we must add at least one DNS + server to it. + + -

+ 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. + + + Forward DNS Server entries represent actual DNS servers which + support the server side of the DDNS protocol. Each Forward DNS Server + has the following parameters: + + + + hostname - + The resolvable host name of the DNS server. This value is not + yet implemented. + + + + + ip-address - + The IP address at which the server listens for DDNS requests. + This may be either an IPv4 or an IPv6 address. + + + + + port - + The port on which the server listens for DDNS requests. It + defaults to the standard DNS service port of 53. + + + + To create a new forward DNS Server, one must add a new server + element to the domain and fill in its parameters. If for + example the service is running at "172.88.99.10", then set it as + follows: "DhcpDdns": { "forward-ddns": { @@@ -536,12 -554,13 +549,13 @@@

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 - section. Currently it contains a single parameter, the catalog of - reverse DDNS Domains, which is a list of structures. -

+ 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 + section. Currently it contains a single parameter, the catalog of + reverse DDNS Domains, which is a list of structures. "DhcpDdns": { "reverse-ddns": { @@@ -550,67 -569,67 +564,67 @@@ ... } - By default, this list is empty, which will cause the server to ignore - the reverse update portions of requests. - - -

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 - mapping) for that zone. You will need one reverse DDNS Domain - for each zone you wish to service. It may very well be that - some or all of your zones are maintained by the same servers; - even then, you will still need one DDNS Domain entry for each - zone. Remember that matching a request to the appropriate - server(s) is done by zone and a DDNS Domain only defines a - single zone. - - - This section describes how to add Reverse DDNS Domains. Repeat these - steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain - has the following parameters: - - - - name - - The fully qualified reverse zone that this DDNS Domain - can update. This is the value used during reverse matching - which will compare it with a reversed version of the request's - lease address. The zone name should follow the appropriate - standards: for example, to to support the IPv4 subnet 172.16.1, - the name should be. "1.16.172.in-addr.arpa.". Similarly, - to support an IPv6 subnet of 2001:db8:1, the name should be - "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." - Whatever the name, it must be unique within the catalog. - - - - - key-name - - If TSIG should be used with this domain's servers, then this - value should be the name of that key from the TSIG Key List. - If the value is blank (the default), TSIG will not be - used in DDNS conversations with this domain's servers. Currently - this value is not used as TSIG has not been implemented. - - - - - dns-servers - - a list of one or more DNS servers which can conduct the server - side of the DDNS protocol for this domain. Currently the servers - are used in a first to last preference. In other words, when D2 - begins to process a request for this domain it will pick the - first server in this list and attempt to communicate with it. - If that attempt fails, it will move to next one in the list and - so on until the it achieves success or the list is exhausted. - - - - To create a new reverse DDNS Domain, one must add a new domain element - and set its parameters. For example, to support subnet 2001:db8:1::, - the following configuration could be used: + By default, this list is empty, which will cause the server to ignore + the reverse update portions of requests. + -

+ 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 + mapping) for that zone. You will need one reverse DDNS Domain + for each zone you wish to service. It may very well be that + some or all of your zones are maintained by the same servers; + even then, you will still need one DDNS Domain entry for each + zone. Remember that matching a request to the appropriate + server(s) is done by zone and a DDNS Domain only defines a + single zone. + + + This section describes how to add Reverse DDNS Domains. Repeat these + steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain + has the following parameters: + + + + name - + The fully qualified reverse zone that this DDNS Domain + can update. This is the value used during reverse matching + which will compare it with a reversed version of the request's + lease address. The zone name should follow the appropriate + standards: for example, to to support the IPv4 subnet 172.16.1, + the name should be. "1.16.172.in-addr.arpa.". Similarly, + to support an IPv6 subnet of 2001:db8:1, the name should be + "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa." + Whatever the name, it must be unique within the catalog. + + + + + key-name - + If TSIG should be used with this domain's servers, then this + value should be the name of that key from the TSIG Key List. + If the value is blank (the default), TSIG will not be + used in DDNS conversations with this domain's servers. Currently + this value is not used as TSIG has not been implemented. + + + + + dns-servers - + a list of one or more DNS servers which can conduct the server + side of the DDNS protocol for this domain. Currently the servers + are used in a first to last preference. In other words, when D2 + begins to process a request for this domain it will pick the + first server in this list and attempt to communicate with it. + If that attempt fails, it will move to next one in the list and + so on until the it achieves success or the list is exhausted. + + + + To create a new reverse DDNS Domain, one must add a new domain element + and set its parameters. For example, to support subnet 2001:db8:1::, + the following configuration could be used: "DhcpDdns": { "reverse-ddns": { @@@ -626,47 -645,48 +640,48 @@@ } - It is permissible to add a domain without any servers. If that domain - should be matched to a request, however, the request will fail. In - order to make the domain useful though, we must add at least one DNS - server to it. - - -

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. - - - Reverse DNS Server entries represents a actual DNS servers which - support the server side of the DDNS protocol. Each Reverse DNS Server - has the following parameters: - - - - hostname - - The resolvable host name of the DNS server. This value is - currently ignored. - - - - - ip-address - - The IP address at which the server listens for DDNS requests. - - - - - port - - The port on which the server listens for DDNS requests. It - defaults to the standard DNS service port of 53. - - - - To create a new reverse DNS Server, one must first add a new server - element to the domain and fill in its parameters. If for - example the service is running at "172.88.99.10", then set it as - follows: + It is permissible to add a domain without any servers. If that domain + should be matched to a request, however, the request will fail. In + order to make the domain useful though, we must add at least one DNS + server to it. + + -

+ 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. + + + Reverse DNS Server entries represents a actual DNS servers which + support the server side of the DDNS protocol. Each Reverse DNS Server + has the following parameters: + + + + hostname - + The resolvable host name of the DNS server. This value is + currently ignored. + + + + + ip-address - + The IP address at which the server listens for DDNS requests. + + + + + port - + The port on which the server listens for DDNS requests. It + defaults to the standard DNS service port of 53. + + + + To create a new reverse DNS Server, one must first add a new server + element to the domain and fill in its parameters. If for + example the service is running at "172.88.99.10", then set it as + follows: "DhcpDdns": { "reverse-ddns": { @@@ -701,91 -721,94 +716,94 @@@

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 - - - - - - - - Domain - Subnet - Forward DNS Servers - Reverse DNS Servers - - - - - four.example.com - 192.0.2.0/24 - 172.16.1.5, 172.16.2.5 - 172.16.1.5, 172.16.2.5 - - - six.example.com - 2001:db8:1::/64 - 3001:1::50 - 3001:1::51 - - - example.com - 192.0.0.0/16 - 172.16.2.5 - 172.16.2.5 - - - -

- - - We need to construct three forward DDNS Domains: - Forward DDNS Domains Needed - - - - - - - # - DDNS Domain Name - DNS Servers - - - - - 1. - four.example.com. - 172.16.1.5, 172.16.2.5 - - - 2. - six.example.com. - 3001:1::50 - - - 3. - example.com. - 172.16.2.5 - - - -

- As discussed earlier, FQDN to domain matching is based on the longest - match. The FQDN, "myhost.four.example.com.", will match the first - domain ("four.example.com") while "admin.example.com." will match the - third domain ("example.com"). The - FQDN, "other.example.net." will fail to match any domain and would - be rejected. - - - The following example configuration specified the Forward DDNS Domains. -

+ 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 - - - - - ++ ++ ++ ++ ++ + + + Domain + Subnet + Forward DNS Servers + Reverse DNS Servers + + + + + four.example.com + 192.0.2.0/24 + 172.16.1.5, 172.16.2.5 + 172.16.1.5, 172.16.2.5 + + + six.example.com + 2001:db8:1::/64 + 3001:1::50 + 3001:1::51 + + + example.com + 192.0.0.0/16 + 172.16.2.5 + 172.16.2.5 + + + +

+ + + We need to construct three forward DDNS Domains: + + Forward DDNS Domains Needed - - - - ++ ++ ++ ++ + + + # + DDNS Domain Name + DNS Servers + + + + + 1. + four.example.com. + 172.16.1.5, 172.16.2.5 + + + 2. + six.example.com. + 3001:1::50 + + + 3. + example.com. + 172.16.2.5 + + + +

+ As discussed earlier, FQDN to domain matching is based on the longest + match. The FQDN, "myhost.four.example.com.", will match the first + domain ("four.example.com") while "admin.example.com." will match the + third domain ("example.com"). The + FQDN, "other.example.net." will fail to match any domain and would + be rejected. + + + The following example configuration specified the Forward DDNS Domains. "DhcpDdns": { "forward-ddns": { @@@ -818,46 -841,47 +836,47 @@@ } - - - Similarly, we need to construct the three reverse DDNS Domains: - Reverse DDNS Domains Needed - - - - - - - # - DDNS Domain Name - DNS Servers - - - - - 1. - 2.0.192.in-addr.arpa. - 172.16.1.5, 172.16.2.5 - - - 2. - 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. - 3001:1::50 - - - 3. - 0.182.in-addr.arpa. - 172.16.2.5 - - - -

- An address of "192.0.2.150" will match the first domain, - "2001:db8:1::10" will match the second domain, and "192.0.50.77" - the third domain. - - - These Reverse DDNS Domains are specified as follows: + + + Similarly, we need to construct the three reverse DDNS Domains: + + Reverse DDNS Domains Needed - - - - ++ ++ ++ ++ + + + # + DDNS Domain Name + DNS Servers + + + + + 1. + 2.0.192.in-addr.arpa. + 172.16.1.5, 172.16.2.5 + + + 2. + 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. + 3001:1::50 + + + 3. + 0.182.in-addr.arpa. + 172.16.2.5 + + + +

+ An address of "192.0.2.150" will match the first domain, + "2001:db8:1::10" will match the second domain, and "192.0.50.77" + the third domain. + + + These Reverse DDNS Domains are specified as follows: "DhcpDdns": { @@@ -890,21 -914,20 +909,20 @@@ } - -

- + +

- -

DHCP-DDNS Server Limitations +

+ DHCP-DDNS Server Limitations The following are the current limitations of the DHCP-DDNS Server. - - - Requests received from the DHCP servers are placed in a - queue until they are processed. Currently all queued requests - are lost when the server shuts down. - - + + + Requests received from the DHCP servers are placed in a + queue until they are processed. Currently all queued requests + are lost when the server shuts down. + +

- - ++ diff --cc doc/guide/dhcp4-srv.xml index 9e97f2981a,49597a559a..669e52eee1 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@@ -1,7 -1,15 +1,10 @@@ - - 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 using keactrl (described in ). @@@ -112,10 -132,10 +127,10 @@@ strings path/kea

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 @@@ -283,10 -304,12 +299,11 @@@ be followed by a comma and another obje 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 @@@ -397,11 -420,14 +414,14 @@@ 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, even if it has already been configured for the DHCPv6 server. The servers @@@ -453,10 -495,10 +489,10 @@@ If a timeout is given though, it shoul If there is no password to the account, set the password to the empty string "". (This is also the default.)

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 @@@ -474,7 -517,9 +511,9 @@@ 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 "postgresql". Other hosts backends may be added in later versions of Kea. @@@ -511,7 -562,8 +556,8 @@@ "". (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 @@@ -543,7 -595,8 +589,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: @@@ -666,9 -719,27 +713,27 @@@ temporarily override a list of interfac supported on the particular OS, the server will issue a warning and fall back to use IP/UDP sockets. + + Interfaces are re-detected at each reconfiguration. This behavior + can be disabled by setting re-detect value to + false, for instance: + + + "Dhcp4": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3" ], + "re-detect": false + }, + ... + } + + Note interfaces are not re-detected during config-test. + +

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 @@@ -719,7 -790,8 +784,8 @@@

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. @@@ -763,7 -835,8 +829,8 @@@ 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. @@@ -859,7 -932,8 +926,8 @@@

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 @@@ -900,21 -974,86 +968,84 @@@ ... ] } - + + Note that only one of name or code is required, you don't need to + specify both. Space has a default value of "dhcp4", so you can skip this + as well if you define a regular (not encapsulated) DHCPv4 option. + Finally, csv-format defaults to true, so it too can be skipped, unless + you want to specify the option value as hexstring. Therefore the + above example can be simplified to: + + "Dhcp4": { + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.2.1, 192.0.2.2" + }, + ... + ] + } + + Defined options are added to response when the client requests them + at a few exceptions which are always added. To enforce the addition + of a particular option set the always-send flag to true as in: + + "Dhcp4": { + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.2.1, 192.0.2.2", + "always-send": true + }, + ... + ] + } + + The effect is the same as if the client added the option code in the + Parameter Request List option (or its equivalent for vendor + options) so in: + + "Dhcp4": { + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.2.1, 192.0.2.2", + "always-send": true + }, + ... + ], + "subnet4": [ + { + "subnet": "192.0.3.0/24", + "option-data": [ + { + "name": "domain-name-servers", + "data": "192.0.3.1, 192.0.3.2" + }, + ... + ], + ... + }, + ... + ], + ... + } + + The Domain Name Servers option is always added to responses + (the always-send is "sticky") but the value is the subnet one + when the client is localized in the subnet. - The name parameter specifies the - option name. For a list of currently supported names, see - below. - 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 - 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 - values separated by commas if more than one value is - allowed. + The name parameter specifies the option name. For a - list of currently supported names, see below. The code ++ list of currently supported names, see below. 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 ++ 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 values separated by commas + if more than one value is allowed. @@@ -992,6 -1172,36 +1164,36 @@@ structures. "Type" designates the format of the data: the meanings of the various types is given in . + + When a data field is a string, and that string contains the comma + (,; U+002C) character, the comma must be escaped with a double reverse solidus + character (\; U+005C). This double escape is required, because both the + routine splitting CSV data into fields and JSON use the same escape + character: a single escape (\,) would make the JSON invalid. - For example, the string "foo,bar" would be represented as: ++ For example, the string "foo,bar" would be represented as: + + "Dhcp4": { + "subnet4": [ + { + "pools": [ + { + "option-data": [ + { + "name": "boot-file-name", + "data": "foo\\,bar" + } + ] + }, + ... + ], + ... + }, + ... + ], + ... + } + + Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option time-servers @@@ -1015,14 -1225,14 +1217,14 @@@ - List of standard DHCPv4 options - -

+ List of standard DHCPv4 options - - - - - - + + + + + + Name @@@ -1177,11 -1361,11 +1353,11 @@@ It is merely echoed by the serve -

List of standard DHCP option types - -

+ List of standard DHCP option types - - - + + + NameMeaning @@@ -1193,9 -1377,10 +1369,10 @@@ 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 text + tupleA length encoded as a 8 (16 for DHCPv6) bit unsigned integer followed by a string of this lengthuint88 bit unsigned integer with allowed values 0 to 255uint1616 bit unsigned integer with allowed values 0 to 65535uint3232 bit unsigned integer with allowed values 0 to 4294967295 @@@ -1205,7 -1393,8 +1385,8 @@@ -

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 @@@ -1324,9 -1513,16 +1505,16 @@@ "1". Future versions of Kea will accept all those values for all boolean parameters. + + Numbers can be specified in decimal or hexadecimal format. + The hexadecimal format can be either plain (e.g. abcd) or + prefixed with 0x (e.g. 0xabcd). + +

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 @@@ -1397,7 -1593,9 +1585,9 @@@

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 @@@ -1503,7 -1701,8 +1693,8 @@@

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 @@@ -1569,9 -1758,11 +1750,11 @@@ +

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. @@@ -1631,7 -1822,8 +1814,8 @@@

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 . @@@ -1808,10 -2003,10 +1995,10 @@@ }

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 @@@ -1894,7 -2089,8 +2081,8 @@@ -

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 @@@ -1961,10 -2157,10 +2149,10 @@@

- -

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 @@@ -2001,13 -2197,13 +2189,13 @@@ 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 @@@ -2098,7 -2294,8 +2286,8 @@@ -

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 @@@ -2215,7 -2412,8 +2404,8 @@@

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 @@@ -2240,9 -2438,10 +2430,10 @@@

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 @@@ -2270,7 -2469,8 +2461,8 @@@

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: @@@ -2430,12 -2630,14 +2622,14 @@@ assumed to belong to another client and the new lease will be allocated. +

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 ). @@@ -2526,10 -2728,12 +2720,12 @@@ -

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 @@@ -2621,7 -2825,9 +2817,9 @@@ 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 by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or @@@ -2638,7 -2844,8 +2836,8 @@@ 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 @@@ -2714,7 -2921,8 +2913,8 @@@

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 @@@ -2781,11 -2989,14 +2981,12 @@@

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. @@@ -2836,9 -3047,11 +3037,11 @@@ if there are options defined with the same type on global, subnet, class and host level, the host specific values will be used. +

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 @@@ -2866,7 -3079,8 +3069,8 @@@ 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 @@@ -2920,12 -3134,15 +3124,14 @@@ with classification using expressions.

Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra) -

+ Storing Host Reservations in MySQL or PostgreSQL + - It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See + 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, PostgreSQL or Cassandra. Kea does not provide any dedicated + 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. @@@ -2934,29 -3151,16 +3140,16 @@@ arbitrarily set to 4096 bytes.

Storing host reservations in PostgreSQL - - It is possible to store host reservations in PostgreSQL. See for information on how to configure Kea to - use reservations stored in PostgreSQL. Kea does not provide any - dedicated tools for managing PostgreSQL reservations. See Kea wiki - http://kea.isc.org/wikiHostReservationsHowTo for - detailed information and examples of how reservations can be inserted - into the database. - -

+ Storing host reservations in CQL (Cassandra) + Kea currently does not support storing reservations in + Cassandra (CQL).

Storing host reservations in Cassandra CQL - - It is possible to store host reservations in Cassandra CQL. See for information on how to configure Kea to - use reservations stored in Cassandra CQL. Kea does not provide any - dedicated tools for managing Cassandra CQL reservations. See Kea wiki - http://kea.isc.org/wiki/HostReservationsHowTo - detailed information and examples of how reservations can be inserted - into the database. - -

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) during lease selection and renewal. In particular, three @@@ -3067,7 -3274,8 +3263,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 @@@ -3083,7 -3291,8 +3280,8 @@@

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 @@@ -3120,7 -3329,8 +3318,8 @@@ 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 @@@ -3164,9 -3374,13 +3363,13 @@@ + If "relay" is specified, the "ip-address" parameter within + it is mandatory. +

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 @@@ -3209,7 -3423,9 +3412,9 @@@

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 assumed that the server is authoritative and has complete jurisdiction @@@ -3273,23 -3489,25 +3478,25 @@@ potential for major issues, we decided not to decrease assigned addresses immediately after receiving DHCPDECLINE, but to do it later when we recover the address back to the available pool. +

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 @@@ -3570,7 -3806,8 +3795,8 @@@

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. @@@ -3604,20 -3841,40 +3830,40 @@@ Communication over control channel is conducted using JSON structures. - See the Control Channel section in the Kea Developer's Guide for more details. + See the Control Channel section in the Kea Developer's Guide for more + details. + + + The DHCPv4 server supports the following operational commands: + + build-report + config-get + config-reload + config-set + config-test + config-write + leases-reclaim + list-commands + shutdown + version-get + + as described in . In addition, + it supports the following statistics related commands: + + statistic-get + statistic-reset + statistic-remove + statistic-get-all + statistic-reset-all + statistic-remove-all + + as described here . - The DHCPv4 server supports statistic-get, - statistic-reset, statistic-remove, - statistic-get-all, statistic-reset-all - and statistic-remove-all, specified in - . It also supports - list-commands and shutdown, - specified in and - , respectively.

Supported DHCP Standards -

+ Supported DHCP Standards The following standards are currently supported: @@@ -3701,7 -3959,8 +3948,8 @@@

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 @@@ -3752,4 -4011,4 +4000,4 @@@

--> -- ++ diff --cc doc/guide/dhcp6-srv.xml index 45fe6a4932,198d3dc423..917513f4a0 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@@ -1,7 -1,15 +1,10 @@@ - - 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 using keactrl (described in ). @@@ -112,10 -132,10 +127,10 @@@ strings path/kea

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 @@@ -278,10 -299,12 +294,11 @@@ be followed by a comma and another obje 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 @@@ -392,11 -415,14 +409,14 @@@ 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, even if it has already been configured for the DHCPv4 server. The servers @@@ -448,10 -490,10 +484,10 @@@ If a timeout is given though, it shoul If there is no password to the account, set the password to the empty string "". (This is also the default.)

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 @@@ -470,7 -512,9 +506,9 @@@ 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 "postgresql". Other hosts backends may be added in later version of Kea. @@@ -507,7 -554,8 +548,8 @@@ "". (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 @@@ -539,7 -587,9 +581,9 @@@ 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: @@@ -575,9 -625,28 +619,28 @@@ It is anticipated that this will form of usage only be used where it is desired to temporarily override a list of interface names and listen on all interfaces. + + As for the DHCPv4 server binding to specific addresses and + disabling re-detection of interfaces are supported. But + dhcp-socket-type is not because DHCPv6 uses + UDP/IPv6 sockets only. The following example shows how to disable the + interface detection: + + + + "Dhcp6": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3" ], + "re-detect": false + }, + ... + } + +

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. @@@ -621,7 -690,8 +684,8 @@@ 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 @@@ -676,7 -746,8 +740,8 @@@

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 @@@ -776,10 -847,11 +841,11 @@@

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 @@@ -809,9 -881,11 +875,11 @@@ ... } +

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 @@@ -845,7 -919,8 +913,8 @@@

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 @@@ -1022,6 -1162,37 +1154,37 @@@ which was not assigned by IANA) are listed in . + When a data field is a string, and that string contains + the comma (,; U+002C) character, the comma must be escaped with a + reverse solidus character (\; U+005C). This double escape is + required, because both the routine splitting CSV data into fields + and JSON use the same escape character: a single escape (\,) would + make the JSON invalid. For example, the string - "EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" would be ++ "EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" would be + represented as: + + "Dhcp6": { + "subnet6": [ + { + "pools": [ + { + "option-data": [ + { + "name": "new-posix-timezone", + "data": "EST5EDT4\,M3.2.0/02:00\,M11.1.0/02:00" + } + ] + }, + ... + ], + ... + }, + ... + ], + ... + } + + Some options are designated as arrays, which means that more than one value is allowed in such an option. For example the option dns-servers @@@ -1047,13 -1218,13 +1210,13 @@@ - List of Standard DHCPv6 Options - -

+ List of Standard DHCPv6 Options - - - - - + + + + + NameCodeTypeArray? @@@ -1138,13 -1301,13 +1293,13 @@@ -

List of Experimental DHCPv6 Options - -

+ List of Experimental DHCPv6 Options - - - - - + + + + + NameCodeTypeArray? @@@ -1159,184 -1322,8 +1314,8 @@@ -

Common Softwire46 Options - - Softwire46 options are involved in IPv4 over IPv6 provisioning by - means of tunneling or translation as specified in the - RFC 7598. - The following sections provide configuration examples of these - options. - - -

Softwire46 Container Options - - S46 container options group rules and optional port parameters - for a specified domain. There are three container options specified - in the "dhcp6" (top level) option space: MAP-E Container option, - MAP-T Container option and S46 Lightweight 4over6 Container option. - These options only contain encapsulated options specified below. - They do not include any data fields. - - - - In order to configure the server to send specific container option - along with all encapsulated options, the container option must be - included in the server configuration as shown below: - - "Dhcp6": { - ... - "option-data": [ - { - "name": "s46-cont-mape" - } ], - ... - } - - - This configuration will cause the server to include MAP-E Container - option to the client. Use "s46-cont-mapt" or "s46-cont-lw" for the - MAP-T Container and S46 Lightweight 4over6 Container options - respectively. - - - - All remaining softwire options described below are included in one - of the container options. Thus, they have to be included in appropriate - option spaces by selecting a "space" name, which specifies in which - option they are supposed to be included. - -

- -

S46 Rule Option - - The S46 Rule option is used for conveying the Basic Mapping Rule (BMR) - and Forwarding Mapping Rule (FMR). - - { - "space": "s46-cont-mape-options", - "name": "s46-rule", - "data": "128, 0, 24, 192.0.2.0, 2001:db8:1::/64" - } - - Other possible "space" value is "s46-cont-mapt-options". - - - - The S46 Rule option conveys a number of parameters: - - - - flags, an unsigned 8 bits integer, with - currently only the most significant bit specified. It denotes whether - the rule can be used for forwarding (128) or not (0). - - - - - ea-len, an 8 bits long Embedded Address length. Allowed values - range from 0 to 48. - - - - IPv4 prefix length, 8 bits long; expresses the prefix length of the - Rule IPv4 prefix specified in the ipv4-prefix field. Allowed - values range from 0 to 32. - - - - IPv4 prefix, a fixed-length 32-bit field that specifies the IPv4 - prefix for the S46 rule. The bits in the prefix after prefix4-len - number of bits are reserved and MUST be initialized to zero by the - sender and ignored by the receiver. - - - - IPv6 prefix in prefix/length notation that specifies the IPv6 domain - prefix for the S46 rule. The field is padded on the right with zero - bits up to the nearest octet boundary when prefix6-len is not evenly - divisible by 8. - - - - -

- -

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 - Container option and not permitted in the MAP-T and - S46 Lightweight 4over6 Container options. - - { - "space": "s46-cont-mape-options", - "name": "s46-br", - "data": "2001:db8:cafe::1", - } - - Other possible "space" value is "s46-cont-lw-options". - -

- -

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 - container option and not permitted in the MAP-E and S46 - Lightweight 4over6 Container options. - - { - "space": "s46-cont-mapt-options", - "name": "s46-dmr", - "data": "2001:db8:cafe::/64", - } - - This option must not be included in other containers. - -

- -

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). - The IPv6 prefix field is used by the CE to identify the - correct prefix to use for the tunnel source. - - { - "space": "s46-cont-lw", - "name": "s46-v4v6bind", - "data": "192.0.2.3, 2001:db8:1:cafe::/64" - } - - This option must not be included in other containers. - -

- -

S46 Port Parameters - - The S46 Port Parameters option specifies optional port set - information that MAY be provided to CEs - - { - "space": "s46-rule-options", - "name": "s46-portparams", - "data": "2, 3/4", - } - - Other possible "space" value is "s46-v4v6bind" to include - this option in the S46 IPv4/IPv6 Address Binding option. - - - Note that the second value in the example above specifies the - PSID and PSID length fields in the format of PSID/PSID length. - This is equivalent to the values of PSID-len=4 and - PSID=12288 conveyed in the S46 Port Parameters option. - -

- -

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 @@@ -1457,9 -1444,11 +1436,11 @@@ "1". Future versions of Kea will accept all those values for all boolean parameters. +

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", @@@ -1529,7 -1518,8 +1510,8 @@@

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 @@@ -1638,7 -1628,8 +1620,8 @@@ should include options from the isc opt

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 @@@ -1707,7 -1688,8 +1680,8 @@@

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. @@@ -1744,9 -1726,10 +1718,10 @@@

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: @@@ -1777,7 -1760,8 +1752,8 @@@

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 @@@ -1845,8 -1829,9 +1821,9 @@@

Relay-Supplied Options -

+ Relay-Supplied Options - RFC 6422 + 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 @@@ -1878,9 -1863,12 +1855,12 @@@ 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 discussion of the classification process see . @@@ -1995,10 -1984,10 +1976,10 @@@

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 @@@ -2082,7 -2071,9 +2063,9 @@@ -

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 @@@ -2148,10 -2139,10 +2131,10 @@@

- -

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 @@@ -2196,13 -2187,13 +2179,13 @@@ 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 @@@ -2285,8 -2276,8 +2268,8 @@@ } - -

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 @@@ -2419,10 -2410,11 +2402,11 @@@

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 ). @@@ -2508,10 -2500,12 +2492,12 @@@ -

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 @@@ -2621,7 -2615,9 +2607,9 @@@ 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 server. There may be an additional address space defined for prefix @@@ -2640,7 -2636,8 +2628,8 @@@ 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 @@@ -2688,7 -2685,8 +2677,8 @@@

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 @@@ -2748,11 -2746,14 +2738,12 @@@

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. @@@ -2800,7 -2801,8 +2791,8 @@@

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 @@@ -2851,14 -2853,15 +2843,13 @@@ with classification using expressions.

Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra) -

+ Storing Host Reservations in MySQL or PostgreSQL + - It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. 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 ++ 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 - http://kea.isc.org/wiki/HostReservationsHowTo - provides detailed - 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. @@@ -2867,12 -2870,15 +2858,15 @@@ 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) during lease selection and renewal. In particular, three @@@ -2984,7 -2991,8 +2979,8 @@@ 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. @@@ -3217,7 -3225,8 +3213,8 @@@ 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, @@@ -3261,8 -3270,9 +3258,9 @@@ even if it is not used.

Support for RFC 7550 -

+ Support for RFC 7550 - The 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. @@@ -3307,7 -3317,8 +3305,8 @@@

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 @@@ -3353,9 -3364,14 +3352,14 @@@ } + + If "relay" is specified, the "ip-address" parameter within + it is mandatory. +

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 @@@ -3403,7 -3419,8 +3407,8 @@@

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 @@@ -3539,7 -3557,9 +3545,9 @@@ 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. It is assumed that the server is authoritative and has complete @@@ -3609,21 -3629,22 +3617,22 @@@ 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 @@@ -3962,7 -4004,8 +3992,8 @@@

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. @@@ -4066,7 -4126,8 +4113,8 @@@

Supported DHCPv6 Standards -

+ Supported DHCPv6 Standards The following standards are currently supported: @@@ -4131,21 -4192,15 +4179,15 @@@ 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 - 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 @@@ -4190,4 -4245,4 +4232,4 @@@

--> -- ++ diff --cc doc/guide/faq.xml index a0ea00ebdc,66157bf292..f638bfaf71 --- a/doc/guide/faq.xml +++ b/doc/guide/faq.xml @@@ -1,5 -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 @@@ -11,15 -17,21 +12,21 @@@ 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 feature (how difficult it is to implement a feature and how likely it @@@ -76,9 -88,12 +83,12 @@@

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 possible with regular UDP sockets, therefore the Kea DHCPv4 server uses raw @@@ -96,10 -111,13 +106,13 @@@

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 traffic by default. In particular, many Linux distributions do that. Please @@@ -113,4 -131,5 +126,5 @@@

- + - ++ diff --cc doc/guide/hooks.xml index 36c8e181a8,8cff24886f..b8bce1224e --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@@ -1,10 -1,16 +1,11 @@@ - - 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, + its behavior needs customization. To accommodate this possibility, Kea includes the idea of "Hooks". This feature lets Kea load one or more dynamically-linked libraries (known as "hooks libraries") and, at various points in its processing ("hook points"), call @@@ -29,12 -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 @@@ -155,12 -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 @@@ -323,14 -358,17 +352,15 @@@ and may have the zero or more of the fo 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 +

+ legal_log: Forensic Logging Hooks This section describes the forensic log hooks library. This library provides hooks that record a detailed log of lease assignments @@@ -472,8 -517,8 +509,8 @@@ link address: 3001::1, hop count: 1, 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 @@@ -532,12 -577,1386 +569,1383 @@@

+ -

+ flex_id: Flexible Identifiers for Host Reservations + + This section describes a hook application dedicated to generate + flexible identifiers for host reservation. Kea software provides a way + to handle host reservations that include addresses, prefixes, options, + client classes and other features. The reservation can be based on + hardware address, DUID, circuit-id or client-id in DHCPv4 and using + hardware address or DUID in DHCPv6. However, there are sometimes + scenario where the reservation is more complex, e.g. uses other + options that mentioned above, uses part of specific options or perhaps + even a combination of several options and fields to uniquely identify + a client. Those scenarios are addressed by the Flexible Identifiers + hook application. + + Currently this library is only available to ISC customers with a + support contract. + + The library allows for defining an expression, using notation - initially used for client classification only. See for detailed description ++ initially used for client classification only. See for detailed description + of the syntax available. One notable difference is that for client + classification the expression currently has to evaluate to either true + or false, while the flexible identifier expression is expected to + evaluate to a string that will be used as identifier. It is a valid case + for the expression to evaluate to empty string (e.g. in cases where a + client does not sent specific options). This expression is then + evaluated for each incoming packet. This evaluation generates an + identifier that is used to identify the client. In particular, there may + be host reservations that are tied to specific values of the flexible + identifier. + + + The library can be loaded in similar way as other hook libraries. It + takes one mandatory parameter identifier-expression: + + "Dhcp6": { + "hooks-libraries": [ + { + "library": "/path/libdhcp_flex_id.so", + "parameters": { + "identifier-expression": "expression" + } + }, + ... + ] + } + + + + + The flexible identifier library supports both DHCPv4 and DHCPv6. + + + + EXAMPLE: Let's consider a case of an IPv6 network that has an + independent interface for each of the connected customers. Customers + are able to plug in whatever device they want, so any type of + identifier (e.g. a client-id) is unreliable. Therefore the operator + may decide to use an option inserted by a relay agent to differentiate + between clients. In this particular deployment, the operator verified + that the interface-id is unique for each customer facing + interface. Therefore it is suitable for usage as reservation. However, + only the first 6 bytes of the interface-id are interesting, because + remaining bytes are either randomly changed or not unique between + devices. Therefore the customer decided to use first 6 bytes of the + interface-id option inserted by the relay agent. After adding "flex-id" + host-reservation-identifiers goal can be achieved by using the + following configuration: + + "Dhcp6": { + "subnet6": [{ ..., // subnet definition starts here + "reservations": [ + "flex-id": "'port1234'", // value of the first 8 bytes of the interface-id + "ip-addresses": [ "2001:db8::1" ] + ], + }], // end of subnet definitions + "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers + "hooks-libraries": [ + { + "library": "/path/libdhcp_flex_id.so", + "parameters": { + "identifier-expression": "substring(relay6[0].option[18].hex,0,8)" + } + }, + ... + ] + } + + + + + NOTE: Care should be taken when adjusting the expression. If the + expression changes, then all the flex-id values may change, possibly + rendering all reservations based on flex-id unusable until they're + manually updated. Therefore it is strongly recommended to start with + the expression and a handful reservations, adjust the expression as + needed and only after it was confirmed the expression does exactly + what is expected out of it go forward with host reservations on any + broader scale. + + + + flex-id values in host reservations can be specified in two + ways. First, they can be expressed as hex string, e.g. bar string + can be represented as 626174. Alternatively, it can be expressed + as quoted value (using double and single quotes), e.g. "'bar'". + The former is more convenient for printable characters, while hex + string values are more convenient for non-printable characters. + + + "Dhcp6": { + "subnet6": [{ ..., // subnet definition starts here + "reservations": [ + "flex-id": "01:02:03:04:05:06", // value of the first 8 bytes of the interface-id + "ip-addresses": [ "2001:db8::1" ] + ], + }], // end of subnet definitions + "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers + "hooks-libraries": [ + { + "library": "/path/libdhcp_flex_id.so", + "parameters": { + "identifier-expression": "vendor[4491].option[1026].hex" + } + }, + ... + ] + } + +

+ -

+ host_cmds: Host Commands + + This section describes a hook application that offers a number of new + commands used to query and manipulate host reservations. Kea provides + a way to store host reservations in a database. In many larger + deployments it is useful to be able to manage that information while + the server is running. This library provides management commands for + adding, querying and deleting host reservations in a safe way without + restarting the server. In particular, it validates the parameters, so + an attempt to insert incorrect data e.g. add a host with conflicting + identifier in the same subnet will be rejected. Those commands are + exposed via command channel (JSON over unix sockets) and Control Agent + (JSON over RESTful interface). Additional commands and capabilities + related to host reservations will be added in the future. + + + Currently this library is only available to ISC customers with a + support contract. + + + Currently three commands are supported: reservation-add (which adds + new host reservation), reservation-get (which returns existing + reservation if specified criteria are matched) and reservation-del + (which attempts to delete a reservation matching specified + criteria). To use commands that change the reservation information + (currently these are reservation-add and reservation-del, but this + rule applies to other commands that may be implemented in the future), + hosts database must be specified (see hosts-database description in - and ) and it must not operate in ++ and ) and it must not operate in + read-only mode. If the hosts-database is not specified or is running + in read-only mode, the host_cmds library will load, but any attempts + to use reservation-add or reservation-del will fail. + + + + Additional host reservation commands are planned in the future. For + a description of envisaged commands, see -Control API -Requirements document. ++Control API ++Requirements document. + + + All commands are using JSON syntax. They can be issued either using + control channel (see ) or via Control + Agent (see ). + + + + The library can be loaded in similar way as other hook libraries. It + does not take any parameters. It supports both DHCPv4 and DHCPv6 + servers. + + "Dhcp6": { + "hooks-libraries": [ + { + "library": "/path/libdhcp_host_cmds.so" + } + ... + ] + } + + + +

+ reservation-add command + + reservation-add allows insertion of a new host. It + takes a set of arguments that vary depending on the nature of the host + reservation. Any parameters allowed in the configuration file that + pertain to host reservation are permitted here. For details regarding - IPv4 reservations, see and . There is one notable addition. A ++ IPv4 reservations, see and . There is one notable addition. A + subnet-id must be specified. This parameter is + mandatory, because reservations specified in the configuration file + are always defined within a subnet, so the subnet they belong to is + clear. This is not the case with reservation-add, therefore the + subnet-id must be specified explicitly. An example command can be as + simple as: + { + "command": "reservation-add", + "arguments": { + "reservation": { + "subnet-id": 1, + "hw-address": "1a:1b:1c:1d:1e:1f", + "ip-address": "192.0.2.202" + } + } + } but can also take many more parameters, for example: + + + { + "command": "reservation-add", + "arguments": { + "reservation": + { + "subnet-id":1, + "client-id": "01:0a:0b:0c:0d:0e:0f", + "ip-address": "192.0.2.205", + "next-server": "192.0.2.1", + "server-hostname": "hal9000", + "boot-file-name": "/dev/null", + "option-data": [ + { + "name": "domain-name-servers", + "data": "10.1.1.202,10.1.1.203" + } + ], + "client-classes": [ "special_snowflake", "office" ] + } + } + } + + Here is an example of complex IPv6 reservation: + + { + "command": "reservation-add", + "arguments": { + "reservation": + { + "subnet-id":1, + "duid": "01:02:03:04:05:06:07:08:09:0A", + "ip-addresses": [ "2001:db8:1:cafe::1" ], + "prefixes": [ "2001:db8:2:abcd::/64" ], + "hostname": "foo.example.com", + "option-data": [ + { + "name": "vendor-opts", + "data": "4491" + }, + { + "name": "tftp-servers", + "space": "vendor-4491", + "data": "3000:1::234" + } + ] + } + } + } + + + + The command returns a status that indicates either a success (result + 0) or a failure (result 1). Failed command always includes text + parameter that explains the cause of failure. Example results: + { "result": 0, "text": "Host added." } Example failure: + { "result": 1, "text": "Mandatory 'subnet-id' parameter missing." } + + + + As reservation-add is expected to store the host, + hosts-database parameter must be specified in your configuration and + the database must not run in read-only mode. In the future versions + it will be possible to modify the reservations read from a + configuration file. Please contact ISC if you are interested in this + functionality. + +

+ +

+ reservation-get command + reservation-get can be used to query the host + database and retrieve existing reservations. There are two types of + parameters this command supports: (subnet-id, address) or (subnet-id, + identifier-type, identifier). The first type of query is used when the + address (either IPv4 or IPv6) is known, but the details of the + reservation aren't. One common use case of this type of query is to + find out whether a given address is reserved or not. The second query + uses identifiers. For maximum flexibility, Kea stores the host + identifying information as a pair of values: type and the actual + identifier. Currently supported identifiers are "hw-address", "duid", + "circuit-id", "client-id" and "flex-id", but additional types may be + added in the future. If any new identifier types are defined in the + future, reservation-get command will support them + automatically. + + + An example command for getting a host reservation by (subnet-id, + address) pair looks as follows: + + { + "command": "reservation-get", + "arguments": { + "subnet-id": 1, + "ip-address": "192.0.2.202" + } + } + + An example query by (subnet-id, identifier-type, identifier) looks as follows: + + { + "command": "reservation-get", + "arguments": + "subnet-id": 4, + "identifier-type": "hw-address", + "identifier": "01:02:03:04:05:06" + } + } + + + reservation-get typically returns result 0 + when the query was conducted properly. In particular, 0 is returned + when the host was not found. If the query was successful a number + of host parameters will be returned. An example of a query that + did not find the host looks as follows: + { "result": 0, "text": "Host not found." } + + An example result returned when the host was found: + { + "arguments": { + "boot-file-name": "bootfile.efi", + "client-classes": [ + + ], + "hostname": "somehost.example.org", + "hw-address": "01:02:03:04:05:06", + "ip-address": "192.0.2.100", + "next-server": "192.0.0.2", + "option-data": [ + + ], + "server-hostname": "server-hostname.example.org" + }, + "result": 0, + "text": "Host found." + } + + An example result returned when the query was malformed: + { "result": 1, "text": "No 'ip-address' provided and 'identifier-type' + is either missing or not a string." } + + +

+ +

+ reservation-del command + reservation-del can be used to delete a + reservation from the host database. There are two types of parameters + this command supports: (subnet-id, address) or (subnet-id, + identifier-type, identifier). The first type of query is used when the + address (either IPv4 or IPv6) is known, but the details of the + reservation aren't. One common use case of this type of query is to + remove a reservation (e.g. you want a specific address to no longer be + reserved). The second query uses identifiers. For maximum flexibility, + Kea stores the host identifying information as a pair of values: type + and the actual identifier. Currently supported identifiers are + "hw-address", "duid", "circuit-id", "client-id" and "flex-id", but + additional types may be added in the future. If any new identifier + types are defined in the future, reservation-get command will support + them automatically. + + + An example command for deleting a host reservation by (subnet-id, + address) pair looks as follows: + + { + "command": "reservation-del", + "arguments": { + "subnet-id": 1, + "ip-address": "192.0.2.202" + } + } + + An example deletion by (subnet-id, identifier-type, identifier) looks as follows: + + { + "command": "reservation-del", + "arguments": + "subnet-id": 4, + "identifier-type": "hw-address", + "identifier": "01:02:03:04:05:06" + } + } + + + reservation-del returns result 0 when the host + deletion was successful or 1 if it was not. A descriptive text is + provided in case of error. Example results look as follows: + + { + "result": 1, + "text": "Host not deleted (not found)." + } + + + { + "result": 0, + "text": "Host deleted." + } + + + { + "result": 1, + "text": "Unable to delete a host because there is no hosts-database + configured." + } + +

+ + + + + -

+ lease_cmds: Lease Commands + + This section describes the hook library that offers a number of new + commands used to manage leases. Kea provides a way to store lease + information in several backends (memfile, MySQL, PostgreSQL and + Cassandra). This library provides a unified interface that can + manipulate leases in an unified, safe way. In particular, it allows + things previously impossible: manipulate leases in memfile while Kea + is running, sanity check changes, check lease existence and remove all + leases belonging to specific subnet. It can also catch more obscure + errors, like adding a lease with subnet-id that does not exist in the + configuration or configuring a lease to use an address that is outside + of the subnet to which it is supposed to belong. + + + There are many use cases when an administrative command may be + useful: during migration between servers (possibly even between + different vendors), when a certain network is being retired, when a + device has been disconnected and the sysadmin knows for sure that it + will not be coming back. The "get" queries may be useful for automating + certain management and monitoring tasks. They can also act as + preparatory steps for lease updates and removals. + + + This library provides the following commands: + + + lease4-add - adds new IPv4 lease; + + + lease6-add - adds new IPv6 lease; + + + lease4-get - checks if an IPv4 lease with + the specified parameters exists and returns it if it does; + + + lease6-get - checks if an IPv6 lease with + the specified parameters exists and returns it if it does; + + + lease4-del - attempts to delete an IPv4 + lease with the specified parameters; + + + lease6-del - attempts to delete an IPv6 + lease with the specified parameters; + + + lease4-update - updates an IPv4 lease; + + + lease6-update - updates an IPv6 lease; + + + lease4-wipe - removes all leases from a + specific IPv4 subnet; + + + lease6-wipe - removes all leases from a + specific IPv6 subnet; + + + + + + Lease commands library is part of the open source code and is + available to every Kea user. + + + All commands are using JSON syntax. They can be issued either using + control channel (see ) or via Control + Agent (see ). + + + + The library can be loaded in the same way as other hook libraries. It + does not take any parameters. It supports both DHCPv4 and DHCPv6 + servers. + + "Dhcp6": { + "hooks-libraries": [ + { + "library": "/path/libdhcp_lease_cmds.so" + } + ... + ] + } + + + +

+ lease4-add, lease6-add commands + + lease4-add and lease6-add + commands allow creation of a new lease. Typically Kea creates a lease + on its own, when it first sees a new device. However, sometimes it may + be convenient to create the lease administratively. The + lease4-add command requires at least three + parameters: an IPv4 address, a subnet-id and an identifier: hardware + (MAC) address. The simplest successful call might look as follows: + + { + "command": "lease4-add", + "arguments": { + "subnet-id": 44, + "ip-address": "192.0.2.202", + "hw-address": "1a:1b:1c:1d:1e:1f" + } + } + + + + lease6-add command requires four + paramaters: an IPv6 address, a subnet-id, and IAID value + (identity association identifier, a value sent by clients) and + a DUID: + + { + "command": "lease6-add", + "arguments": { + "subnet-id": 66, + "ip-address": "2001:db8::3", + "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24", + "iaid": 1234 + } + } + + lease6-add can be also used to add leases for IPv6 + prefixes. In this case there are two parameters that must be -specified: type (set to value of "IA_PD") and a prefix ++specified: type (set to value of "IA_PD") and a prefix + length. The actual prefix is set using ip-address field. For example, + to configure a lease for prefix 2001:db8:abcd::/48, the following + command can be used: + + + { + "command": "lease6-add", + "arguments": { + "subnet-id": 66, + "type": "IA_PD", + "ip-address": "2001:db8:abcd::", + "prefix-len": 48, + "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24", + "iaid": 1234 + } + } + + The commands can take a number of additional optional parameters: + + + valid-lft - specifies the lifetime of the + lease, expressed in seconds. If not specified, the value + configured in the subnet related to specified subnet-id is + used. + + + expire - timestamp of the lease + expiration time, expressed in unix format (seconds since 1 Jan + 1970). If not specified, the default value is now + valid + lifetime. + + + fqdn-fwd - specifies whether the lease + should be marked as if forward DNS update was conducted. Note this + only affects the lease parameter and the actual DNS update will + not be conducted at the lease insertion time. If configured, a DNS + update to remove the A or AAAA records will be conducted when the + lease is removed due to expiration or being released by a + client. If not specifed, the default value is false. Hostname + parameter must be specified in fqdn-fwd is set to true. + + + fqdn-rev - specifies whether the lease + should be marked as if reverse DNS update was conducted. Note this + only affects the lease parameter and the actual DNS update will + not be conducted at the lease insertion time. If configured, a DNS + update to remove the PTR record will be conducted when the lease + is removed due to expiration or being released by a client. If not + specifed, the default value is false. Hostname parameter must be + specified in fqdn-fwd is set to true. + + + hostname - specifies the hostname to be + associated with this lease. Its value must be non-empty if either + fqdn-fwd or fwdn-rev are set to true. If not specified, the + default value is an empty string. + + + hw-address - hardware (MAC) address can + be optionally specified for IPv6 lease. It is mandatory parameter + for IPv4 lease. + + + client-id - client identifier is an + optional parameter that can be specified for IPv4 lease. + + + preferred-lft - Preferred lifetime is an + optional parameter for IPv6 leases. If not specified, the value + configured for the subnet corresponding to the specified subnet-id + is used. This parameter is not used in IPv4. + + + + + Here's an example of more complex lease addition: + + + { + "command": "lease6-add", + "arguments": { + "subnet-id": 66, + "ip-address": "2001:db8::3", + "duid": "01:02:03:04:05:06:07:08", + "iaid": 1234, + "hw-address": "1a:1b:1c:1d:1e:1f", + "preferred-lft": 500, + "valid-lft": 1000, + "expire": 12345678, + "fqdn-fwd": true, + "fqdn-rev": true, + "hostname": "urania.example.org" + } + } + + + + + The command returns a status that indicates either a success (result + 0) or a failure (result 1). Failed command always includes text + parameter that explains the cause of failure. Example results: + { "result": 0, "text": "Lease added." } Example failure: + { "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" } + + + +

+ lease4-get, lease6-get commands + lease4-get or lease6-get + can be used to query the lease database and retrieve existing + leases. There are two types of parameters the + lease4-get supports: (address) or (subnet-id, + identifier-type, identifier). There are two types for + lease6-get: (address,type) or (subnet-id, + identifier-type, identifier, IAID, type). The first type of query is + used when the address (either IPv4 or IPv6) is known, but the details + of the lease aren't. One common use case of this type of query is to + find out whether a given address is being used or not. The second + query uses identifiers. For maximum flexibility, Kea stores the host + identifying information as a pair of values: type and the actual + identifier. Currently supported identifiers are "hw-address", "duid", + "circuit-id", "client-id" and "flex-id", but additional types may be + added in the future. If any new identifier types are defined in the + future, reservation-get command will support them + automatically. + + + An example lease4-get command for getting a lease + by an IPv4 address looks as follows: + + { + "command": "lease4-get", + "arguments": { + "ip-address": "192.0.2.1" + } + } + + + + An example of the lease6-get query + looks as follows: + + { + "command": "lease6-get", + "arguments": { + "ip-address": "2001:db8:1234:ab::", + "type": "IA_PD" + } + } + + + An example query by (subnet-id, identifier-type, + identifier) for IPv4 lease looks as follows: + + { + "command": "lease4-get", + "arguments": { + "identifier-type": "hw-address", + "identifier": "08:08:08:08:08:08", + "subnet-id": 44 + } + } + + + + An example query by (subnet-id, identifier-type, + identifier, iaid, type) for IPv6 lease looks as follows: + + { + "command": "lease4-get", + "arguments": { + "identifier-type": "duid", + "identifier": "08:08:08:08:08:08", + "iaid": 1234567, + "type": "IA_NA", + "subnet-id": 44 + } + } + The type is an optional parameter. Supported values are: IA_NA + (non-temporary address) and IA_PD (IPv6 prefix) are supported. + If not specified, IA_NA is assumed. + + + leaseX-get returns a result that indicates a + result of the operation and lease details, if found. It has one of the + following values: 0 (success), 1 (error) or 2 (empty). The empty + result means that a query has been completed properly, but the object + (a lease in this case) has not been found. The lease parameters, if + found, are returned as arguments. + + + + An example result returned when the host was found: + { + "arguments": { + "client-id": "42:42:42:42:42:42:42:42", + "cltt": 12345678, + "fqdn-fwd": false, + "fqdn-rev": true, + "hostname": "myhost.example.com.", + "hw-address": "08:08:08:08:08:08", + "ip-address": "192.0.2.1", + "state": 0, + "subnet-id": 44, + "valid-lft": 3600 + }, + "result": 0, + "text": "IPv4 lease found." + } + + +

+ +

+ lease4-del, lease6-del commands + leaseX-del can be used to delete a lease from + the lease database. There are two types of parameters this command + supports, similar to leaseX-get commands: (address) for both v4 and + v6, (subnet-id, identifier-type, identifier) for v4 and (subnet-id, + identifier-type, identifier, type, IAID) for v6. The first type of + query is used when the address (either IPv4 or IPv6) is known, but the + details of the lease are not. One common use case of this type of query + is to remove a lease (e.g. you want a specific address to no longer be + used, no matter who may use it). The second query uses + identifiers. For maximum flexibility, this interface uses identifiers + as a pair of values: type and the actual identifier. Currently + supported identifiers are "hw-address" and "duid", but additional + types may be added in the future. + + + An example command for deleting a host reservation by address looks + as follows: + + { + "command": "lease4-del", + "arguments": { + "ip-address": "192.0.2.202" + } + } + + An example IPv4 lease deletion by (subnet-id, identifier-type, identifier) looks + as follows: + + { + "command": "lease4-del", + "arguments": { + "identifier": "08:08:08:08:08:08", + "identifier-type": "hw-address", + "subnet-id": 44 + } + } + + + leaseX-get returns a result that + indicates a outcome of the operation. It has one of the + following values: 0 (success), 1 (error) or 2 (empty). The + empty result means that a query has been completed properly, + but the object (a lease in this case) has not been found. + +

+ +

+ lease4-update, lease6-update commands + lease4-update and + lease6-update commands can be used to update + existing leases. Since all lease database backends are indexed by IP + addresses, it is not possible to update an address. All other fields + may be updated. If an address needs to be changed, please use + leaseX-del followed by + leaseX-add commands. + + To use leaseX-update the lease must + be present in the lease database. If the lease is not there, + an error will be returned. Please use + leaseX-add to add new leases. You may + check if a lease is present using + leaseX-get, if needed. + + + An example command updating IPv6 lease looks as follows: + { + "command": "lease4-update", + "arguments": { + "ip-address": "192.0.2.1", + "hostname": "newhostname.example.org", + "hw-address": "1a:1b:1c:1d:1e:1f", + "subnet-id": 44 + } + } + + + + An example command updating IPv6 lease looks as follows: + { + "command": "lease6-update", + "arguments": { + "ip-address": "2001:db8::1", + "duid": "88:88:88:88:88:88:88:88", + "iaid": 7654321, + "hostname": "newhostname.example.org", + "subnet-id": 66 + } + } + +

+ +

+ lease4-wipe, lease6-wipe commands + lease4-wipe and + lease6-wipe are designed to remove all + leases associated with a given subnet. This administrative + task is expected to be used when existing subnet is being + retired. Note that the leases are not properly expired, + there are no DNS updates conducted, no log messages and + hooks are not called for leases being removed. + + An example of lease4-wipe looks as follows: + { + "command": "lease4-wipe", + "arguments": { + "subnet-id": 44 + } + } + + + An example of lease6-wipe looks as follows: + { + "command": "lease6-wipe", + "arguments": { + "subnet-id": 66 + } + } + + + The commands return a textual description of the + number of leases removed and 0 (success) status code if any + leases were removed and 2 (empty) if there were no + leases. Status code 1 (error) may be returned in case the + parameeters are incorrect or some other exception is + encountered. + + Note: not all backends support this command. +

+ -

+ subnet_cmds: Subnet Commands + + This section describes a hook application that offers a number of new + commands used to query and manipulate subnet configurations in Kea. + This application is very useful in deployments with a large number of + subnets being managed by the DHCP servers and when the subnets are + frequently updated. The commands offer lightweight approach for + manipulating subnets without a need to fully reconfigure the server + and without affecting existing servers' configurations. + + + Currently this library is only available to ISC customers with a + support contract. + + The following commands are currently supported: - ++ + + subnet4-list/subnet6-list: lists all configured subnets + + + + + subnet4-get/subnet6-get: retrieves detailed information about a selected subnet + + + + + subnet4-add/subnet6-add: adds new subnet into server's configuration + + + + + subnet4-del/subnet6-del: removes a subnet from the server's configuration + + + + + +

+ subnet4-list command + + This command is used to list all currently configured subnets. The + subnets are returned in a brief form, i.e. a subnet identifier + and subnet prefix is included for each subnet. In order to retrieve + the detailed information about the subnet the + subnet4-get should be used. + + + This command has the simple structure: + + { + "command": "subnet4-list" + } + + + + The list of subnets returned as a result of this command is returned + in the following format: + + { + "result": 0, + "text": "2 IPv4 subnets found", + "arguments": { + "subnets": [ + { + "id": 10, + "subnet": "10.0.0.0/8" + }, + { + "id": 100, + "subnet": "192.0.2.0/24" + } + ] + } + + + + If no IPv4 subnets are found, an error code is returned along with + the error description. + +

+ +

+ subnet6-list command + + This command is used to list all currently configured subnets. The + subnets are returned in a brief form, i.e. a subnet identifier + and subnet prefix is included for each subnet. In order to retrieve + the detailed information about the subnet the + subnet6-get should be used. + + + This command has the simple structure: + + { + "command": "subnet6-list" + } + + + + The list of subnets returned as a result of this command is returned + in the following format: + + { + "result": 0, + "text": "2 IPv6 subnets found", + "arguments": { + "subnets": [ + { + "id": 11, + "subnet": "2001:db8:1::/64" + }, + { + "id": 233, + "subnet": "3000::/16" + } + ] + } + + + + If no IPv6 subnets are found, an error code is returned along with + the error description. + +

+ +

+ subnet4-get command + This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + subnet4-list, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in subnet4-get + to fetch subnet information: + + { + "command": "subnet4-get", + "arguments": { + "id": 10 + } + } + + or + + + { + "command": "subnet4-get", + "arguments": { + "subnet": "10.0.0.0/8" + } + } + + + + + If the subnet exists the response will be similar to this: + + { + "result": 0, + "text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned", + "arguments": { + "subnets": [ + { + "subnet": "10.0.0.0/8", + "id": 1, + "option-data": [ + .... + ] + ... + } + ] + } + } + + +

+ +

+ subnet6-get command + This command is used to retrieve detailed information about the + specified subnet. This command usually follows the + subnet6-list, which is used to discover available + subnets with their respective subnet identifiers and prefixes. Any of + those parameters can be then used in subnet6-get + to fetch subnet information: + + { + "command": "subnet6-get", + "arguments": { + "id": 11 + } + } + + + or + + + { + "command": "subnet6-get", + "arguments": { + "subnet": "2001:db8:1::/64" + } + } + + If the subnet exists the response will be similar to this: + + { + "result": 0, + "text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned", + "arguments": { + "subnets": [ + { + "subnet": "2001:db8:1::/64", + "id": 1, + "option-data": [ + ... + ] + .... + } + ] + } + } + + +

+ +

+ subnet4-add + + This command is used to create and add new subnet to the existing + server configuration. This operation has no impact on other + subnets. The subnet identifier must be specified and must be + unique among all subnets. If the identifier or a subnet prefix is + not unique an error is reported and the subnet is not added. + + + The subnet information within this command has the same structure + as the subnet information in the server configuration file with the + exception that static host reservations must not be specified + within subnet4-add. The commands described in + should be used to add, remove and + modify static reservations. + + { + "command": "subnet4-add", + "arguments": { + "subnets": [ { + "id": 123, + "subnet": "10.20.30.0/24", + ... + } ] + } + } + + + + + The response to this command has the following structure: + + { + "result": 0, + "text": "IPv4 subnet added", + "arguments": { + "subnets": [ + { + "id": 123, + "subnet": "10.20.30.0/24" + } + ] + } + } + + +

+ +

+ subnet6-add + + This command is used to create and add new subnet to the existing + server configuration. This operation has no impact on other + subnets. The subnet identifier must be specified and must be + unique among all subnets. If the identifier or a subnet prefix is + not unique an error is reported and the subnet is not added. + + + The subnet information within this command has the same structure + as the subnet information in the server configuration file with the + exception that static host reservations must not be specified + within subnet6-add. The commands described in + should be used to add, remove and + modify static reservations. + + { + "command": "subnet6-add", + "arguments": { + "subnet6": [ { + "id": 234, + "subnet": "2001:db8:1::/64", + ... + } ] + } + } + + + + + The response to this command has the following structure: + + { + "result": 0, + "text": "IPv6 subnet added", + "arguments": { + "subnet6": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] + } + } + + + + + It is recommended, but not mandatory to specify subnet + id. If not specified, Kea will try to assign the next + subnet-id value. This automatic ID value generator is + simple. It returns a previously automatically assigned value + increased by 1. This works well, unless you manually create + a subnet with a value bigger than previously used. For + example, if you call subnet4-add five times, each without + id, Kea will assign IDs: 1,2,3,4 and 5 and it will work just + fine. However, if you try to call subnet4-add five times, + with the first subnet having subnet-id of value 3 and + remaining ones having no subnet-id, it will fail. The first + command (with explicit value) will use subnet-id 3, the + second command will create a subnet with id of 1, the third + will use value of 2 and finally the fourth will have the + subnet-id value auto-generated as 3. However, since there is + already a subnet with that id, it will fail. + + + The general recommendation is to either: never use explicit + values (so the auto-generated values will always work) or + always use explicit values (so the auto-generation is never + used). You can mix those two approaches only if you + understand how the internal automatic subnet-id generation works. + + +

+ +

+ subnet4-del command + + This command is used to remove a subnet from the server's configuration. + This command has no effect on other configured subnets but removing + a subnet has certain implications which the server's administrator + should be aware of. + + + In most cases the server has assigned some leases to the clients + belonging to the subnet. The server may also be configured with + static host reservations which are associated with this subnet. + The current implementation of the subnet4-del + removes neither the leases nor host reservations associated with + a subnet. This is the safest approach because the server doesn't + loose track of leases assigned to the clients from this subnet. + However, removal of the subnet may still cause configuration + errors and conflicts. For example: after removal of the subnet, + the server administrator may add a new subnet with the ID used + previously for the removed subnet. This means that the existing + leases and static reservations will be in conflict with this + new subnet. Thus, we recommend that this command is used with extreme + caution. + + + The command has the following structure: + + { + "command": "subnet4-del", + "arguments": { + "id": 123 + } + } + + + + The example successful response may look like this: + + { + "result": 0, + "text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted", + "arguments": { + "subnets": [ + { + "id": 123, + "subnet": "192.0.2.0/24" + } + ] + } + } + + +

+ +

+ subnet6-del command + + This command is used to remove a subnet from the server's configuration. + This command has no effect on other configured subnets but removing + a subnet has certain implications which the server's administrator + should be aware of. + + + In most cases the server has assigned some leases to the clients + belonging to the subnet. The server may also be configured with + static host reservations which are associated with this subnet. + The current implementation of the subnet6-del + removes neither the leases nor host reservations associated with + a subnet. This is the safest approach because the server doesn't + loose track of leases assigned to the clients from this subnet. + However, removal of the subnet may still cause configuration + errors and conflicts. For example: after removal of the subnet, + the server administrator may add a new subnet with the ID used + previously for the removed subnet. This means that the existing + leases and static reservations will be in conflict with this + new subnet. Thus, we recommend that this command is used with extreme + caution. + + + The command has the following structure: + + { + "command": "subnet6-del", + "arguments": { + "id": 234 + } + } + + + + The example successful response may look like this: + + { + "result": 0, + "text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted", + "subnets": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] + } + +

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 @@@ -556,4 -1975,6 +1964,6 @@@

- + + - ++ diff --cc doc/guide/install.xml index b1332c9ef7,4525f4b58c..aac13ba598 --- a/doc/guide/install.xml +++ b/doc/guide/install.xml @@@ -1,7 -1,15 +1,10 @@@ - - Installation - - -]> - - ++ ++ + Installation + -

+ Packages -

Packages Some operating systems or software package vendors may provide ready-to-use, pre-built software packages for Kea. Installing a @@@ -17,7 -25,8 +20,8 @@@

Installation Hierarchy -

+ Installation Hierarchy The following is the directory layout of the complete Kea installation. (All directory paths are relative to the installation directory): @@@ -80,9 -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. @@@ -185,12 -197,14 +191,14 @@@ 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 @@@ -198,10 -213,12 +206,12 @@@ 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).

@@@ -253,15 -271,18 +264,18 @@@ 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 - 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. @@@ -445,7 -469,8 +462,8 @@@

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. @@@ -465,9 -490,11 +483,11 @@@ +

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 @@@ -511,10 -539,11 +532,11 @@@

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 @@@ -532,10 -561,12 +554,11 @@@

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 @@@ -571,4 -602,4 +594,4 @@@ $ make

-- ++ diff --cc doc/guide/intro.xml index 43735a5d1b,985c66fccb..10461c0b74 --- a/doc/guide/intro.xml +++ b/doc/guide/intro.xml @@@ -1,6 -1,13 +1,6 @@@ - - Introduction - - - -%version; -]> -- - ++ ++ + Introduction Kea is the next generation of DHCP software developed by ISC. It supports both DHCPv4 and DHCPv6 protocols along with their @@@ -15,15 -22,16 +15,16 @@@ - 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 - other platforms: Kea 1.1.0 builds have been tested on (in no - particular order) Red Hat Enteprise Linux 6.4, Debian GNU/Linux 7, + CentOS, Fedora and FreeBSD systems. It is also likely to work on many + other platforms: Kea 1.1.0 builds have been tested on (in no + particular order) Red Hat Enterprise Linux 6.4, Debian GNU/Linux 7, Ubuntu 12.04, Ubuntu 14.04, Ubuntu 16.04, Fedora Linux 19, Fedora 20, Fedora 22, CentOS Linux 7, NetBSD 6, FreeBSD 10.3, OpenBSD 5.7, OpenBSD 6.0, OS X 10.10, OS X 10.11. @@@ -31,7 -39,9 +32,9 @@@ 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 not be provided in the default installation of some operating systems, @@@ -88,7 -98,8 +91,8 @@@

Kea Software -

+ Kea Software Kea is modular. Part of this modularity is accomplished using multiple cooperating processes which, together, @@@ -144,10 -155,10 +148,10 @@@ - 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 + While it can be run standalone, it is normally run as and when required by the Kea DHCP servers. @@@ -177,4 -189,4 +182,4 @@@ -- ++ diff --cc doc/guide/kea-guide.xml index 3d239f6fb2,839cf4c3d7..a336cc3537 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@@ -1,8 -1,25 +1,10 @@@ - - - - -%version; -]> - - - - ++ + - - <bookinfo> ++ <info> + + <title> <inlinemediaobject> <imageobject> <imagedata fileref="kea-logo-100x70.png" align="left"/> @@@ -12,51 -29,72 +14,72 @@@ This is the reference guide for Kea version - &__VERSION__;. + . - 2010-2016Internet Systems Consortium, Inc. + 2010-2017Internet 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__;. ++ This is the reference guide for Kea 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 . ++ Kea, can be found at http://kea.isc.org/docs. + + - + - + - + - + - + - + - + - ++ + - + - + - + - + - + - + - + - + - + - + - + - ++ + - + - Acknowledgments - ++ + Acknowledgments + Kea is primarily designed, developed, and maintained by Internet Systems Consortium, Inc. It is an open source project and contributions are welcomed. @@@ -69,32 -107,35 +92,35 @@@ 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. + + + -- ++ diff --cc doc/guide/keactrl.xml index cfd74c7eb5,a39be5cf56..76af644cd9 --- a/doc/guide/keactrl.xml +++ b/doc/guide/keactrl.xml @@@ -1,16 -1,25 +1,20 @@@ - - 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 - also provides the means for checking the current status of the servers - and determining the configuration files in use. + kea-dhcp6, kea-dhcp-ddns and + kea-ctrl-agent). It also provides the means for + checking the current status of the servers and determining the + configuration files in use.

Command Line Options -

+ Command Line Options keactrl is run as follows: keactrl <command> [-c keactrl-config-file] [-s server[,server,..]] @@@ -42,7 -51,8 +46,8 @@@

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 @@@ -128,7 -143,8 +138,8 @@@ kea_verbose=n

Commands -

+ Commands The following commands are supported by keactrl: @@@ -243,7 -266,8 +261,8 @@@ keactrl configuration file: /usr/local/

Overriding the Server Selection -

+ Overriding the Server Selection The optional -s switch allows the selection of the servers to which keactrl @@@ -297,4 -325,4 +320,4 @@@

-- ++ diff --cc doc/guide/lease-expiration.xml index 888ba65539,abca79b0f3..171c2d740f --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@@ -1,5 -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 @@@ -42,7 -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: @@@ -75,7 -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 @@@ -218,7 -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 @@@ -287,7 -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: @@@ -317,13 -326,15 +322,15 @@@ expired-leases-processing map may be omitted entirely in the configuration, in which case the default values are used for all parameters listed above. +

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.

-- ++ diff --cc doc/guide/lfc.xml index 164a6b31fe,f6580e83fa..14dd477bf1 --- a/doc/guide/lfc.xml +++ b/doc/guide/lfc.xml @@@ -1,7 -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 @@@ -19,7 -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 @@@ -89,4 -97,4 +92,4 @@@

-- ++ diff --cc doc/guide/libdhcp.xml index f61b288ab3,851c87469f..14441dae0b --- a/doc/guide/libdhcp.xml +++ b/doc/guide/libdhcp.xml @@@ -1,6 -1,11 +1,6 @@@ - - The libdhcp++ Library - - -]> -- - ++ ++ + The libdhcp++ Library libdhcp++ is a library written in C++ that handles many DHCP-related tasks, including: @@@ -27,7 -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, @@@ -47,4 -53,4 +48,4 @@@

--> -- ++ diff --cc doc/guide/logging.xml index 457b95d3b0,1806982a17..aed25ec42f --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@@ -1,7 -1,26 +1,9 @@@ - - Logging - - -]> - - - - ++ ++ + Logging -

Logging Configuration +

+ Logging Configuration During its operation Kea may produce many messages. They differ in severity (some are more important than others) and source (some are @@@ -583,17 -625,20 +608,20 @@@

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.) + Only relevant when the destination is a file. This is maximum size + in bytes that a log file may reach. 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 ++ a ".1" is appended to the name â if a ".1" file exists, it + is renamed ".2", etc. This is referred to as rotation. - If this is set to 0 or omitted, no maximum file size is used. + The default value is 10240000 (10MB). The smallest value that may + be specified without disabling rotation is 204800. Any value less than + this, including 0, disables rotation. - Due to a limitation of the underlying logging library (log4cplus), @@@ -666,7 -717,8 +700,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 @@@ -756,7 -808,8 +791,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 @@@ -833,5 -886,4 +869,4 @@@

- -- ++ diff --cc doc/guide/quickstart.xml index 820dc01edd,74e97f174c..9001bce995 --- a/doc/guide/quickstart.xml +++ b/doc/guide/quickstart.xml @@@ -1,5 -1,13 +1,6 @@@ - - Quick Start - - - -%version; -]> - - ++ ++ + Quick Start This section describes the basic steps needed to get Kea up and running. @@@ -7,11 -15,15 +8,14 @@@ 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. @@@ -105,7 -117,8 +109,8 @@@ $ ./configure [your extra pa 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: @@@ -115,4 -128,4 +120,4 @@@

-- ++ diff --cc doc/guide/shell.xml index 0000000000,4490fb6233..971489d00e mode 000000,100644..100644 --- a/doc/guide/shell.xml +++ b/doc/guide/shell.xml @@@ -1,0 -1,134 +1,129 @@@ - - -]> - - ++ ++ + The Kea Shell + -

+ Overview + Kea 1.2.0 introduced the Control Agent (CA, see ) that + provides a RESTful control interface over HTTP. That API is typically expected to be used by + various IPAMs and similar management systems. Nevertheless, there may be cases when you want + to send a command to the CA directly. The Kea Shell provides a way to do this. It is a simple + command-line, scripting-friendly text client that is able connect to the CA, send it commands + with parameters, retrieve the responses and display them. + + As the primary purpose of the Kea Shell is as a tool in scripting environment, + it is not interactive. However, with simple tricks it can be run manually. + +

+ -

+ Shell Usage + kea-shell is run as follows: + + kea-shell [--host hostname] [--port number] [--timeout seconds] [--service service-name] [command] + + where: + + + + + --host hostname specifies the hostname + of the CA. If not specified, "localhost" is used. + + + + + + --port number specifies the TCP port + on which the CA listens. If not specified, 8000 is used. + + + + + + --timeout seconds specifies the + timeout (in seconds) for the connection. If not given, 10 seconds is used. + + + + + + --service service-name specifies the + target of a command. If not given, CA will be used as target. May be used more + than once to specify multiple targets. + + + + + + + command specifies the command to be sent. If not specified, + list-commands command is used. + + + + + Other switches are: + + + + -h prints a help message. + + + + + -v prints the software version. + + + + + + Once started, the shell reads parameters for the command from standard input, which are + expected to be in JSON format. When all have been read, the shell establishes a connection + with the CA using HTTP, sends the command and awaits a response. Once that is received, + it is printed on standard output. + + + + For a list of available commands, see . Additional commands + may be provided by hook libraries. If unsure which commands are supported, use the + list-commands command. It will instruct the CA to return a list of + all supported commands. + + + The following shows a simple example of usage: + + $ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands + ^D + + After the command line is entered, the program waits for command parameters to be entered. + Since list-commands does not take any + arguments, CTRL-D (represented in the above example by "^D") is pressed to indicate end + of file (and so terminate the parameter input). The Shell will then contact + the CA and print out the list of available commands returned for the service named dhcp4. + + + It is envisaged that Kea Shell will be most frequently used in scripts. The next example + shows a simple scripted execution. It sends the command "config-write" to the CA + ( --service parameter hasn't been used), along + with the parameters specified in param.json. The result will be stored in result.json. + + $ cat param.json + "filename": "my-config-file.json" -$ cat param.json | kea-shell --host 192.0.2.1 config-write > result.json ++$ cat param.json | kea-shell --host 192.0.2.1 config-write > result.json + + + + Kea Shell requires Python to to be installed on the system. It was tested with + Python 2.7 and various versions + of Python 3, up to 3.5. Since not every Kea deployment uses this feature and there are + deployments that do not have Python, the Kea Shell is not enabled by default. To use it, + you must specify --enable-shell to when running "configure" during the + installation of Kea. + + The Kea Shell is intended to serve more as a demonstration of the RESTful interface + capabilities (and, perhaps, an illustration for people interested in integrating their + management evironments with Kea) than as a serious management client. Do not expect it + to be significantly expanded in the future. It is, and will remain, a simple tool. +

- ++ diff --cc doc/guide/stats.xml index f70fb4821d,17164c4df6..83fbc900ec --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@@ -1,7 -1,15 +1,10 @@@ - - Statistics - - -]> - - ++ ++ + Statistics + +

+ Statistics Overview -

Statistics Overview Both Kea DHCP servers support statistics gathering. A working DHCP server encounters various events that can cause certain statistics to be collected. For @@@ -56,7 -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 @@@ -89,7 -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 @@@ -109,7 -120,9 +114,9 @@@ sending commands to Kea, see . -

statistic-get command -

+ statistic-get command + statistic-get command retrieves a single statistic. It takes a single string parameter called @@@ -133,7 -146,9 +140,9 @@@

statistic-reset command -

+ statistic-reset command + statistic-reset command sets the specified statistic to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time @@@ -158,7 -173,9 +167,9 @@@

statistic-remove command -

+ statistic-remove command + statistic-remove command attempts to delete a single statistic. It takes a single string parameter called @@@ -182,7 -199,9 +193,9 @@@

statistic-get-all command -

+ statistic-get-all command + statistic-get-all command retrieves all statistics recorded. An example command may look like this: @@@ -200,7 -219,9 +213,9 @@@

statistic-reset-all command -

+ statistic-reset-all command + statistic-reset command sets all statistics to their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time @@@ -220,7 -241,9 +235,9 @@@

statistic-remove-all command -

+ statistic-remove-all command + statistic-remove-all command attempts to delete all statistics. An example command may look like this: @@@ -238,6 -261,7 +255,7 @@@ and the text field will contain the error description.

-- ++ diff --cc src/bin/admin/kea-admin.xml index 88c11eed99,90957bc8d7..83e9177ddd --- a/src/bin/admin/kea-admin.xml +++ b/src/bin/admin/kea-admin.xml @@@ -1,6 -1,16 +1,6 @@@ - -]> - - - - ++ + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -223,6 -241,6 +228,6 @@@ Kea Administrator Guide. - + - + diff --cc src/bin/agent/kea-ctrl-agent.xml index 0000000000,b66c60de64..38926a99a0 mode 000000,100644..100644 --- a/src/bin/agent/kea-ctrl-agent.xml +++ b/src/bin/agent/kea-ctrl-agent.xml @@@ -1,0 -1,224 +1,207 @@@ -]> - - - - - ++ ++ ++ ++ + 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-ctrl-agent + 8 + Kea + + + + kea-ctrl-agent + Control Agent process in Kea + + + + + 2016 + Internet Systems Consortium, Inc. ("ISC") + + + + - ++ + kea-ctrl-agent - - - - - - ++ ++ ++ ++ ++ ++ + + + + + + DESCRIPTION + + The kea-ctrl-agent provides a REST service for + controlling Kea services. The received HTTP requests are decapsulated + and forwarded to the respective Kea services in JSON format. Received + JSON responses are encapsulated within HTTP responses and returned to + the controlling entity. Some commands may be handled by the Control + Agent directly, and not forwarded to any Kea service. + + + + + + ARGUMENTS + + The arguments are as follows: + + + + + + + Display the version. + + + + + + + Display the extended version. + + + + + + + Display the configuration report. + + + + + + + Verbose mode sets the logging level to debug. This is primarily + for development purposes in stand-alone mode. + + + + + + + Configuration file including the configuration for the Control Agent + server. It may also contain configuration entries for other Kea + services. + + + + + + + Check the syntax of the configuration file and report the + first error if any. Note that not all parameters are + completely checked, in particular, service and client + sockets are not opened, and hook libraries are not loaded. + + + + + + + + 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 + and many more. Kea also features a Kea Messages Manual, which + lists all possible messages Kea can print with a brief + description for each of them. Both documents are typically + available in various formats (txt, html, pdf) with your Kea + distribution. The on-line version is available at + http://kea.isc.org/docs/. + + Kea source code is documented in the Kea Developer's Guide. It's + on-line version is available at http://kea.isc.org. Please + follow Developer's Guide link. + + + Kea project website is available at: http://kea.isc.org. + + + + + 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 + (kea-dev at lists.isc.org) is intended for Kea developers, prospective + contributors and other advanced users. Both lists are available at + http://lists.isc.org. The community provides best effort type of support + on both of those lists. + + + ISC provides professional support for Kea services. See + https://www.isc.org/kea/ for details. + + + + + HISTORY + + The kea-ctrl-agent was first coded in December 2016 + by Marcin Siodelski. + + + + + SEE ALSO + + + kea-dhcp4 + 8 + , + + + kea-dhcp6 + 8 + , + + + kea-dhcp-ddns + 8 + , + + + kea-admin + 8 + , + + + keactrl + 8 + , + + + perfdhcp + 8 + , + + + kea-lfc + 8 + , + + Kea Administrator's Guide. + + + + - ++ diff --cc src/bin/d2/kea-dhcp-ddns.xml index 15577ea28a,4eaa2d70b4..2cc67f1248 --- a/src/bin/d2/kea-dhcp-ddns.xml +++ b/src/bin/d2/kea-dhcp-ddns.xml @@@ -1,7 -1,17 +1,7 @@@ - -]> - - - - - ++ + + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -33,13 -46,14 +33,14 @@@ - + kea-dhcp-ddns - - - - - - + + + + - ++ ++ @@@ -188,6 -217,10 +204,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/dhcp4/kea-dhcp4.xml index 1780c5f773,b99d52db3e..4860ec6004 --- a/src/bin/dhcp4/kea-dhcp4.xml +++ b/src/bin/dhcp4/kea-dhcp4.xml @@@ -1,7 -1,17 +1,7 @@@ - -]> - - - - - ++ + + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -33,14 -46,15 +33,15 @@@ - + kea-dhcp4 - - - - - - - + + + + - - ++ ++ ++ @@@ -193,6 -222,10 +209,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/dhcp6/kea-dhcp6.xml index f9d58ba04a,53176f83a3..cf175a10f3 --- a/src/bin/dhcp6/kea-dhcp6.xml +++ b/src/bin/dhcp6/kea-dhcp6.xml @@@ -1,7 -1,17 +1,7 @@@ - -]> - - - - - ++ + + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -33,14 -46,15 +33,15 @@@ - + kea-dhcp6 - - - - - - - + + + + - - ++ ++ ++ @@@ -194,6 -223,10 +210,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/keactrl/keactrl.xml index 2ff5c6d5ed,f2e5fcb3d6..227d5adaa6 --- a/src/bin/keactrl/keactrl.xml +++ b/src/bin/keactrl/keactrl.xml @@@ -1,6 -1,16 +1,6 @@@ - -]> - - - - ++ + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -240,6 -266,6 +253,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/lfc/kea-lfc.xml index dce5b7b1c3,5e63546bde..fa1d916831 --- a/src/bin/lfc/kea-lfc.xml +++ b/src/bin/lfc/kea-lfc.xml @@@ -1,7 -1,17 +1,7 @@@ - -]> - - - - - ++ + + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -263,6 -281,10 +268,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/perfdhcp/perfdhcp.xml index afa02a6998,a400b3c59b..6f0a0d792c --- a/src/bin/perfdhcp/perfdhcp.xml +++ b/src/bin/perfdhcp/perfdhcp.xml @@@ -1,7 -1,17 +1,7 @@@ - -]> - - - - - ++ + + + ISC Kea Sep. 28, 2016 1.1.0 @@@ -922,6 -956,6 +927,6 @@@ Kea Administrator's Guide. - + - + diff --cc src/bin/shell/kea-shell.xml index 0000000000,00b6604d11..598012f9c4 mode 000000,100644..100644 --- a/src/bin/shell/kea-shell.xml +++ b/src/bin/shell/kea-shell.xml @@@ -1,0 -1,237 +1,220 @@@ -]> - - - - - ++ ++ ++ ++ + ISC Kea - 2017 Mar 8 ++ 0008-03-2017 + 1.2.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-shell + 8 + Kea + + + + kea-shell + Text client for Control Agent process + + + + + 2017 + Internet Systems Consortium, Inc. ("ISC") + + + + - ++ + kea-shell - - - - - - - ++ ++ ++ ++ ++ ++ ++ + + + + + + DESCRIPTION + + The kea-shell provides a REST client for the + Kea Control Agent (CA). It takes command as a command-line parameter + that is being sent to CA with proper JSON + encapsulation. Optional arguments may be specified on the + standard input. The request it sent of HTTP and a response is + retrieved. That response is displayed out on the standard output. + + + + + + ARGUMENTS + + The arguments are as follows: + + + + + + + Displays help regarding command line parameters. + + + + + + + Display the version. + + + + + + + Specifies the host to connect to. Control Agent must be + running at specified host. If not specified, 127.0.0.1 is used. + + + + + + + Specifies the TCP port to connect to. Control Agent must be + listening at specified port. If not specified, 8000 is used. + + + + + + + Specifies the connection timeout in seconds. If not + specified, 10 (seconds) is used. + + + + + + + Specifies the service that is the target of a command. If not + specified, Control Agent will be targeted. May be used more than + once to specify multiple targets. + + + + + + + Specifies the command to be sent to CA. If not + specified, "list-commands" is used. + + + + + + + + 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 + and many more. Kea also features a Kea Messages Manual, which + lists all possible messages Kea can print with a brief + description for each of them. Both documents are typically + available in various formats (txt, html, pdf) with your Kea + distribution. The on-line version is available at + http://kea.isc.org/docs/. + + Kea source code is documented in the Kea Developer's Guide. It's + on-line version is available at http://kea.isc.org. Please + follow Developer's Guide link. + + + Kea project website is available at: http://kea.isc.org. + + + + + 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 + (kea-dev at lists.isc.org) is intended for Kea developers, prospective + contributors and other advanced users. Both lists are available at + http://lists.isc.org. The community provides best effort type of support + on both of those lists. + + + ISC provides professional support for Kea services. See + https://www.isc.org/kea/ for details. + + + + + HISTORY + + The kea-shell was first coded in March 2017 + by Tomek Mrugalski. + + + + + SEE ALSO + + + kea-ctrl-agent + 8 + , + + + kea-dhcp4 + 8 + , + + + kea-dhcp6 + 8 + , + + + kea-dhcp-ddns + 8 + , + + + kea-admin + 8 + , + + + keactrl + 8 + , + + + perfdhcp + 8 + , + + + kea-lfc + 8 + , + + Kea Administrator's Guide. + + + + - ++ diff --cc src/bin/sockcreator/kea-sockcreator.xml index 4fab630425,c44f3a9c93..0b1c9a81f8 --- a/src/bin/sockcreator/kea-sockcreator.xml +++ b/src/bin/sockcreator/kea-sockcreator.xml @@@ -1,9 -1,19 +1,9 @@@ - -]> - ++ + - - - - July 1, 2014 - + + 2014-07-01 + kea-sockcreator @@@ -64,6 -74,10 +64,6 @@@ removed. The socket creator server binary was renamed to kea-sockcreator in July 2014. - + - +