From 8cd0316dda05707e9d233bc98adcf65c39ea0417 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 29 Aug 2016 15:34:42 +0200 Subject: [PATCH 1/8] [3684] Updated Kea User's Guide for host reservations in Kea 1.1.0. --- doc/guide/dhcp4-srv.xml | 36 +++++++++++----------- doc/guide/dhcp6-srv.xml | 68 ++++++++++++++++++++++++++--------------- 2 files changed, 62 insertions(+), 42 deletions(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index c4179a3b1e..822de1171f 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -479,7 +479,7 @@ If a timeout is given though, it should be an integer greater than zero.
- Hosts Storage + Hosts Storage Kea is also able to store information about host reservations in the database. The hosts database configuration uses the same syntax as the lease @@ -2580,7 +2580,7 @@ It is merely echoed by the server
- Host reservation in DHCPv4 + Host Reservation in DHCPv4 There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve specific, static @@ -2595,9 +2595,7 @@ It is merely echoed by the server Another example when the host reservations are applicable is when a host that has specific requirements, e.g. a printer that needs additional DHCP options. - Yet another possible use case is to define unique names for hosts. Although not all - of the presented use cases are implemented yet, Kea software will support them in the - near future. + Yet another possible use case is to define unique names for hosts. Hosts reservations are defined as parameters for each subnet. Each host has to be identified by an identifier, for example hardware/MAC address. There is an optional @@ -2605,9 +2603,10 @@ It is merely echoed by the server element. Each element in that array is a structure, that holds information about reservations for a single host. In particular, such a structure has to have an identifier that uniquely identifies a host. In DHCPv4 context, such an - identifier is a hardware or MAC address. In most cases an address - will be specified. It is also possible to specify a hostname or host - specific options. Additional capabilities are planned. + identifier is usually a hardware or MAC address. In most cases an IP address + will be specified. It is also possible to specify a hostname, host + specific options or fields carried within DHCPv4 message such as siaddr, + sname or file. In Kea 1.0.0 it was only possible to create host reservations using client's hardware address. Host reservations by client @@ -2677,7 +2676,7 @@ It is merely echoed by the server additional check incurs performance penalty.
- 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 @@ -2696,7 +2695,7 @@ It is merely echoed by the server
- 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 @@ -2774,7 +2773,7 @@ It is merely echoed by the server
- 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 or Hostname option, depending on which of them @@ -2837,7 +2836,7 @@ It is merely echoed by the server
- Including specific DHCPv4 options in reservations + Including Specific DHCPv4 Options in Reservations Kea 1.1.0 introduced the ability to specify options on a per host basis. The options follow the same rules as any other options. These can be standard options (see
- Storing host reservations in MySQL or PostgreSQL + Storing Host Reservations in MySQL or PostgreSQL - It is possible to store host reservations in MySQL or PostgreSQL. See for information on how to configure Kea to use + It is possible to store host reservations in MySQL or PostgreSQL database. See + for information on how to configure Kea to use reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated tools for managing reservations in a database. See Kea wiki for detailed information and examples of how reservations can be inserted into the database. + + In Kea 1.1.0 maximum length of an option specified per host is + arbitrarily set to 4096 bytes.
@@ -2982,7 +2984,7 @@ It is merely echoed by the server dynamic pool. Therefore it can skip the reservation checks when dealing with in-pool addresses, thus improving performance. Do not use this mode if any of your reservations use in-pool address. Caution is advised when - using this setting. Kea 0.9.1 does not sanity check the reservations against + using this setting. Kea 1.1.0 does not sanity check the reservations against reservation-mode. Misconfiguration may cause problems. @@ -3012,7 +3014,7 @@ It is merely echoed by the server Another aspect of the host reservations are different types of - identifiers. Currently (June 2016) Kea supports four types of identifiers + identifiers. Kea 1.1.0 supports four types of identifiers (hw-address, duid, client-id and circuit-id), but more identifier types are likely to be added in the future. This is beneficial from a usability perspective. However, there is a drawback. For each incoming diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 0e6b319f42..432654289b 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2304,7 +2304,7 @@ should include options from the isc option space:
- Host reservation in DHCPv6 + Host Reservation in DHCPv6 There are many cases where it is useful to provide a configuration on a per host basis. The most obvious one is to reserve specific, static IPv6 @@ -2320,9 +2320,7 @@ should include options from the isc option space: Another example when the host reservations are applicable is when a host that has specific requirements, e.g. a printer that needs additional DHCP options or a cable modem needs specific parameters. Yet another possible use case for - host reservation is to define unique names for hosts. Although not all of - the presented use cases are implemented yet, Kea software will support them - in the near future. + host reservation is to define unique names for hosts. Hosts reservations are defined as parameters for each subnet. Each host can be identified by either DUID or its hardware/MAC address. See @@ -2332,9 +2330,9 @@ should include options from the isc option space: is a structure, that holds information about a single host. In particular, such a structure has to have an identifier that uniquely identifies a host. In DHCPv6 context, such an identifier - is a hardware (MAC) address or a DUID. Also, either one or more - addresses or prefixes should be specified. It is possible to - specify a hostname. Additional capabilities are planned. + is usually a DUID, but can also be a hardware or MAC address. Also, + either one or more addresses or prefixes may be specified. It is + possible to specify a hostname and DHCPv6 options for a given host. The following example shows how to reserve addresses and prefixes for specific hosts: @@ -2358,11 +2356,11 @@ should include options from the isc option space: }, { "hw-address": "00:01:02:03:04:05", - "ip-addresses": [ "2001:db8:1::101" ] + "ip-addresses": [ "2001:db8:1::101, 2001:db8:1::102" ] }, { "duid": "01:02:03:04:05:06:07:08:09:0A", - "ip-addresses": [ "2001:db8:1::102" ], + "ip-addresses": [ "2001:db8:1::103" ], "prefixes": [ "2001:db8:2:abcd::/64" ], "hostname": "foo.example.com" } @@ -2370,19 +2368,36 @@ should include options from the isc option space: } ] - This example makes 3 reservations. The first one reserves 2001:db8:1::100 address - for the client using DUID 01:02:03:04:05:0A:0B:0C:0D:0E. The second one - also reserves an address, but does so using MAC or hardware address, rather than - DUID. The third example is most advanced. It reserves an address, a prefix and - a hostname at the same time. + + This example includes reservations for 3 different clients. First reservation + is made for the address 2001:db8:1::100 for a client using DUID + 01:02:03:04:05:0A:0B:0C:0D:0E. Second reservation is made for two addresses + 2001:db8:1::101 and 2001:db8:1::102 for a client using MAC address + 00:01:02:03:04:05. Lastly, address 2001:db8:1::103 and prefix 2001:db8:2:abcd::/64 + are reserved for a client using DUID 01:02:03:04:05:06:07:08:09:0A. This + last reservation also assigns a hostname to this client. Note that DHCPv6 allows for a single client to lease multiple addresses - and multiple prefixes at the same time. In the upcoming Kea releases, it will - be possible to have multiple addresses and prefixes reserved for a single - host. Therefore ip-addresses and prefixes - are plural and are actually arrays. As of 0.9.1 having more than one IPv6 - address or prefix is only partially supported. + and multiple prefixes at the same time. Therefore ip-addresses + and prefixes are plural and are actually arrays. + When the client sends multiple IA options (IA_NA or IA_PD), each reserved + address or prefix is assigned to individual IA of appropriate type. If + the number of IAs of specific type is lower than the number of reservations + of that type, the number of reserved addresses or prefixes assigned to the + client is equal to the number of IA_NAs or IA_PDs sent by the client, i.e. + some reserved addresses or prefixes are not assigned to the client. Though, + they still remain reserved for this client and the server will not assign + them to any other client. If the number of IAs of specific type sent by the + client is greater than the number of reserved addresses or prefixes, the + server will try to assign all reserved addresses or prefixes to the individual + IAs and dynamically allocate addresses or prefixes to remaining IAs. If the + server cannot assign any of the reserved addresses or prefixes because of the + conflict, the server will pick next reserved address or prefix and try to + assign it to the client. If the server subsequently finds that there are no + more reservations that can be assigned to the client at the moment, the + server will try to assign leases dynamically. + Making a reservation for a mobile host that may visit multiple subnets requires a separate host definition in each subnet it is expected to visit. @@ -2390,8 +2405,8 @@ should include options from the isc option space: address in a single subnet. It is a valid configuration, if such definitions are specified in different subnets, though. The reservation for a given host should include only one identifier, either DUID or hardware address. Defining - both for the same host is considered a configuration error, but as of 0.9.1 - beta, it is not rejected. + both for the same host is considered a configuration error, but as of 1.1.0, + it is not rejected. Adding host reservation incurs a performance penalty. In principle, @@ -2416,7 +2431,7 @@ should include options from the isc option space: in-pool reservations. In contrast, those that do not belong to dynamic pools are called out-of-pool reservations. There is no formal difference in the reservation - syntax. As of 0.9.1, both reservation types are handled + syntax. As of Kea 1.1.0, both reservation types are handled uniformly. However, upcoming releases may offer improved performance if there are only out-of-pool reservations as the server will be able to skip reservation checks when dealing with existing leases. Therefore, system @@ -2425,7 +2440,7 @@ should include options from the isc option space:
- Conflicts in DHCPv6 reservations + Conflicts in DHCPv6 Reservations As reservations and lease information are stored in different places, 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 @@ -2603,6 +2618,9 @@ should include options from the isc option space: information and examples of how reservations can be inserted into the database. + + In Kea 1.1.0 maximum length of an option specified per host is + arbitrarily set to 4096 bytes.
@@ -2645,7 +2663,7 @@ should include options from the isc option space: dynamic pool. Therefore it can skip the reservation checks when dealing with in-pool addresses, thus improving performance. Do not use this mode if any of your reservations use in-pool address. Caution is advised when - using this setting. Kea 0.9.1 does not sanity check the reservations against + using this setting. Kea 1.1.0 does not sanity check the reservations against reservation-mode. Misconfiguration may cause problems. @@ -2675,7 +2693,7 @@ should include options from the isc option space: Another aspect of the host reservations are different types of - identifiers. Currently (June 2016) Kea supports two types of identifiers + identifiers. Kea 1.1.0 supports two types of identifiers in DHCPv6: hw-address and duid, but more identifier types are likely to be added in the future. This is beneficial from a usability perspective. However, there is a drawback. For each incoming From 6eb70fa2ddc0db71a7af0da5526be76a42aeaae3 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 29 Aug 2016 15:53:56 +0200 Subject: [PATCH 2/8] [3684] Added example file with a connection to MySQL host database. --- doc/Makefile.am | 1 + doc/examples/kea4/mysql-reservations.json | 96 +++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 doc/examples/kea4/mysql-reservations.json diff --git a/doc/Makefile.am b/doc/Makefile.am index 9ede28d74d..be2d9f3752 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -13,6 +13,7 @@ nobase_dist_doc_DATA += examples/kea4/classify.json nobase_dist_doc_DATA += examples/kea4/hooks.json nobase_dist_doc_DATA += examples/kea4/leases-expiration.json nobase_dist_doc_DATA += examples/kea4/multiple-options.json +nobase_dist_doc_DATA += examples/kea4/mysql-reservations.json nobase_dist_doc_DATA += examples/kea4/reservations.json nobase_dist_doc_DATA += examples/kea4/several-subnets.json nobase_dist_doc_DATA += examples/kea4/single-subnet.json diff --git a/doc/examples/kea4/mysql-reservations.json b/doc/examples/kea4/mysql-reservations.json new file mode 100644 index 0000000000..79e95fb0e4 --- /dev/null +++ b/doc/examples/kea4/mysql-reservations.json @@ -0,0 +1,96 @@ +# This is an example configuration file for the DHCPv4 server in Kea. +# It contains configuration of the MySQL host database backend, used +# to retrieve reserved addresses, host names, DHCPv4 message fields +# and DHCP options from MySQL database. +{ "Dhcp4": + +{ +# Kea is told to listen on ethX interface only. + "interfaces-config": { + "interfaces": [ "ethX" ] + }, + +# We need to specify lease type. As of May 2014, three backends are supported: +# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require +# any prior set up. + "lease-database": { + "type": "memfile" + }, + +# Addresses will be assigned with valid lifetimes being 4000. Client +# is told to start renewing after 1000 seconds. If the server does not respond +# after 2000 seconds since the lease was granted, client is supposed +# to start REBIND procedure (emergency renewal that allows switching +# to a different server). + "valid-lifetime": 4000, + +# Renew and rebind timers are commented out. This implies that options +# 58 and 59 will not be sent to the client. In this case it is up to +# the client to pick the timer values according to RFC2131. Uncomment the +# timers to send these options to the client. +# "renew-timer": 1000, +# "rebind-timer": 2000, + + +# Kea supports reservations by several different types of identifiers: +# hw-address (hardware/MAC address of the client), duid (DUID inserted by the +# client), client-id (client identifier inserted by the client) and circuit-id +# (circuit identifier inserted by the relay agent). When told to do so, Kea can +# check for all of those identifier types, but it takes a costly database lookup +# to do so. It is therefore useful from a performance perspective to use only +# the reservation types that are actually used in a given network. + +# The example below is not optimal from a performance perspective, but it +# nicely showcases the host reservation capabilities. Please use the minimum +# set of identifier types used in your network. + "host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ], + +# Specify connection to the database holding host reservations. The type +# specifies that the MySQL database is used. user and password are the +# credentials used to connect to the database. host and name specify +# location of the host where the database instance is running, and the +# name of the database to use. The server processing a packet will first +# check if there are any reservations specified for this client in the +# reservations list, within the subnet (configuration file). If there are +# no reservations there, the server will try to retrieve reservations +# from this database. + "hosts-database": { + "type": "mysql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "localhost" + }, + +# Define a subnet with a single pool of dynamic addresses. Addresses from +# this pool will be assigned to clients which don't have reservations in the +# database. Subnet identifier is equal to 1. If this subnet is selected for +# the client, this subnet id will be used to search for the reservations +# within the database. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.10 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "ethX", + "id": 1 + } + ] +}, + +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. +"Logging": { + "loggers": [ + { + "name": "kea-dhcp4", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} From 5a5f430db7d63d479a54e146a9ce2d16d5ce4d81 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 29 Aug 2016 16:32:51 +0200 Subject: [PATCH 3/8] [3684] Added example file with MySQL host database connection. --- doc/Makefile.am | 1 + doc/examples/kea6/mysql-reservations.json | 91 +++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 doc/examples/kea6/mysql-reservations.json diff --git a/doc/Makefile.am b/doc/Makefile.am index be2d9f3752..9b597fb462 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -23,6 +23,7 @@ nobase_dist_doc_DATA += examples/kea6/classify.json nobase_dist_doc_DATA += examples/kea6/hooks.json nobase_dist_doc_DATA += examples/kea6/leases-expiration.json nobase_dist_doc_DATA += examples/kea6/multiple-options.json +nobase_dist_doc_DATA += examples/kea6/mysql-reservations.json nobase_dist_doc_DATA += examples/kea6/reservations.json nobase_dist_doc_DATA += examples/kea6/several-subnets.json nobase_dist_doc_DATA += examples/kea6/simple.json diff --git a/doc/examples/kea6/mysql-reservations.json b/doc/examples/kea6/mysql-reservations.json new file mode 100644 index 0000000000..ec50656ee2 --- /dev/null +++ b/doc/examples/kea6/mysql-reservations.json @@ -0,0 +1,91 @@ +# This is an example configuration file for the DHCPv6 server in Kea. +# It contains configuration of the MySQL host database backend, used +# to retrieve reserved addresses, host names, DHCPv4 message fields +# and DHCP options from MySQL database. +{ "Dhcp6": + +{ +# Kea is told to listen on ethX interface only. + "interfaces-config": { + "interfaces": [ "ethX" ] + }, + +# We need to specify lease type. As of May 2014, three backends are supported: +# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require +# any prior set up. + "lease-database": { + "type": "memfile" + }, + +# This is pretty basic stuff, it has nothing to do with reservations. + "preferred-lifetime": 3000, + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + +# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address +# of the client) and duid (DUID inserted by the client). When told to do so, Kea can +# check for each of these identifier types, but it takes a costly database lookup +# to do so. It is therefore useful from a performance perspective to use only +# the reservation types that are actually used in a given network. + "host-reservation-identifiers": [ "duid", "hw-address" ], + +# Specify connection to the database holding host reservations. The type +# specifies that the MySQL database is used. user and password are the +# credentials used to connect to the database. host and name specify +# location of the host where the database instance is running, and the +# name of the database to use. The server processing a packet will first +# check if there are any reservations specified for this client in the +# reservations list, within the subnet (configuration file). If there are +# no reservations there, the server will try to retrieve reservations +# from this database. + "hosts-database": { + "type": "mysql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "localhost" + }, + +# Define a subnet with a pool of dynamic addresses and a pool of dynamic +# prefixes. Addresses and prefixes from those pools will be assigned to +# clients which don't have reservations in the database. Subnet identifier +# is equal to 1. If this subnet is selected for the client, this subnet +# id will be used to search for the reservations within the database. + "subnet6": [ + { + "subnet": "2001:db8:1::/48", + + "pools": [ { "pool": "2001:db8:1::/80" } ], + + "pd-pools": [ + { + "prefix": "2001:db8:1:8000::", + "prefix-len": 56, + "delegated-len": 64 + } + ], + "interface": "ethX", + "id": 1 + } + ] +}, + +# The following configures logging. Kea will log all debug messages +# to /var/log/kea-debug.log file. +"Logging": { + "loggers": [ + { + "name": "kea-dhcp6", + "output_options": [ + { + "output": "/var/log/kea-debug.log" + } + ], + "debuglevel": 99, + "severity": "DEBUG" + } + ] +} + +} From 98dae713dbfb243b2517f717b28d3dec845e513a Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 29 Aug 2016 16:51:38 +0200 Subject: [PATCH 4/8] [3684] Added examples for PostgreSQL host database connection. --- doc/Makefile.am | 2 + doc/examples/kea4/pgsql-reservations.json | 96 +++++++++++++++++++++++ doc/examples/kea6/pgsql-reservations.json | 91 +++++++++++++++++++++ 3 files changed, 189 insertions(+) create mode 100644 doc/examples/kea4/pgsql-reservations.json create mode 100644 doc/examples/kea6/pgsql-reservations.json diff --git a/doc/Makefile.am b/doc/Makefile.am index 9b597fb462..3997e5cae5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,6 +14,7 @@ nobase_dist_doc_DATA += examples/kea4/hooks.json nobase_dist_doc_DATA += examples/kea4/leases-expiration.json nobase_dist_doc_DATA += examples/kea4/multiple-options.json nobase_dist_doc_DATA += examples/kea4/mysql-reservations.json +nobase_dist_doc_DATA += examples/kea4/pgsql-reservations.json nobase_dist_doc_DATA += examples/kea4/reservations.json nobase_dist_doc_DATA += examples/kea4/several-subnets.json nobase_dist_doc_DATA += examples/kea4/single-subnet.json @@ -24,6 +25,7 @@ nobase_dist_doc_DATA += examples/kea6/hooks.json nobase_dist_doc_DATA += examples/kea6/leases-expiration.json nobase_dist_doc_DATA += examples/kea6/multiple-options.json nobase_dist_doc_DATA += examples/kea6/mysql-reservations.json +nobase_dist_doc_DATA += examples/kea6/pgsql-reservations.json nobase_dist_doc_DATA += examples/kea6/reservations.json nobase_dist_doc_DATA += examples/kea6/several-subnets.json nobase_dist_doc_DATA += examples/kea6/simple.json diff --git a/doc/examples/kea4/pgsql-reservations.json b/doc/examples/kea4/pgsql-reservations.json new file mode 100644 index 0000000000..c512c4d300 --- /dev/null +++ b/doc/examples/kea4/pgsql-reservations.json @@ -0,0 +1,96 @@ +# This is an example configuration file for the DHCPv4 server in Kea. +# It contains configuration of the PostgreSQL host database backend, used +# to retrieve reserved addresses, host names, DHCPv4 message fields +# and DHCP options from PostgreSQL database. +{ "Dhcp4": + +{ +# Kea is told to listen on ethX interface only. + "interfaces-config": { + "interfaces": [ "ethX" ] + }, + +# We need to specify lease type. As of May 2014, three backends are supported: +# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require +# any prior set up. + "lease-database": { + "type": "memfile" + }, + +# Addresses will be assigned with valid lifetimes being 4000. Client +# is told to start renewing after 1000 seconds. If the server does not respond +# after 2000 seconds since the lease was granted, client is supposed +# to start REBIND procedure (emergency renewal that allows switching +# to a different server). + "valid-lifetime": 4000, + +# Renew and rebind timers are commented out. This implies that options +# 58 and 59 will not be sent to the client. In this case it is up to +# the client to pick the timer values according to RFC2131. Uncomment the +# timers to send these options to the client. +# "renew-timer": 1000, +# "rebind-timer": 2000, + + +# Kea supports reservations by several different types of identifiers: +# hw-address (hardware/MAC address of the client), duid (DUID inserted by the +# client), client-id (client identifier inserted by the client) and circuit-id +# (circuit identifier inserted by the relay agent). When told to do so, Kea can +# check for all of those identifier types, but it takes a costly database lookup +# to do so. It is therefore useful from a performance perspective to use only +# the reservation types that are actually used in a given network. + +# The example below is not optimal from a performance perspective, but it +# nicely showcases the host reservation capabilities. Please use the minimum +# set of identifier types used in your network. + "host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ], + +# Specify connection to the database holding host reservations. The type +# specifies that the PostgreSQL database is used. user and password are the +# credentials used to connect to the database. host and name specify +# location of the host where the database instance is running, and the +# name of the database to use. The server processing a packet will first +# check if there are any reservations specified for this client in the +# reservations list, within the subnet (configuration file). If there are +# no reservations there, the server will try to retrieve reservations +# from this database. + "hosts-database": { + "type": "postgresql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "localhost" + }, + +# Define a subnet with a single pool of dynamic addresses. Addresses from +# this pool will be assigned to clients which don't have reservations in the +# database. Subnet identifier is equal to 1. If this subnet is selected for +# the client, this subnet id will be used to search for the reservations +# within the database. + "subnet4": [ + { + "pools": [ { "pool": "192.0.2.10 - 192.0.2.200" } ], + "subnet": "192.0.2.0/24", + "interface": "ethX", + "id": 1 + } + ] +}, + +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. +"Logging": { + "loggers": [ + { + "name": "kea-dhcp4", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} + +} diff --git a/doc/examples/kea6/pgsql-reservations.json b/doc/examples/kea6/pgsql-reservations.json new file mode 100644 index 0000000000..170c03e7d7 --- /dev/null +++ b/doc/examples/kea6/pgsql-reservations.json @@ -0,0 +1,91 @@ +# This is an example configuration file for the DHCPv6 server in Kea. +# It contains configuration of the PostgreSQL host database backend, used +# to retrieve reserved addresses, host names, DHCPv4 message fields +# and DHCP options from PostgreSQL database. +{ "Dhcp6": + +{ +# Kea is told to listen on ethX interface only. + "interfaces-config": { + "interfaces": [ "ethX" ] + }, + +# We need to specify lease type. As of May 2014, three backends are supported: +# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require +# any prior set up. + "lease-database": { + "type": "memfile" + }, + +# This is pretty basic stuff, it has nothing to do with reservations. + "preferred-lifetime": 3000, + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + +# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address +# of the client) and duid (DUID inserted by the client). When told to do so, Kea can +# check for each of these identifier types, but it takes a costly database lookup +# to do so. It is therefore useful from a performance perspective to use only +# the reservation types that are actually used in a given network. + "host-reservation-identifiers": [ "duid", "hw-address" ], + +# Specify connection to the database holding host reservations. The type +# specifies that the PostgreSQL database is used. user and password are the +# credentials used to connect to the database. host and name specify +# location of the host where the database instance is running, and the +# name of the database to use. The server processing a packet will first +# check if there are any reservations specified for this client in the +# reservations list, within the subnet (configuration file). If there are +# no reservations there, the server will try to retrieve reservations +# from this database. + "hosts-database": { + "type": "postgresql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "localhost" + }, + +# Define a subnet with a pool of dynamic addresses and a pool of dynamic +# prefixes. Addresses and prefixes from those pools will be assigned to +# clients which don't have reservations in the database. Subnet identifier +# is equal to 1. If this subnet is selected for the client, this subnet +# id will be used to search for the reservations within the database. + "subnet6": [ + { + "subnet": "2001:db8:1::/48", + + "pools": [ { "pool": "2001:db8:1::/80" } ], + + "pd-pools": [ + { + "prefix": "2001:db8:1:8000::", + "prefix-len": 56, + "delegated-len": 64 + } + ], + "interface": "ethX", + "id": 1 + } + ] +}, + +# The following configures logging. Kea will log all debug messages +# to /var/log/kea-debug.log file. +"Logging": { + "loggers": [ + { + "name": "kea-dhcp6", + "output_options": [ + { + "output": "/var/log/kea-debug.log" + } + ], + "debuglevel": 99, + "severity": "DEBUG" + } + ] +} + +} From 0aeb76d82fc9ecee82c8ac8699b2d33517602f5e Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 29 Aug 2016 16:55:34 +0200 Subject: [PATCH 5/8] [3684] Minor fix in the User's Guide. --- doc/guide/dhcp4-srv.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 822de1171f..ac49380068 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -3050,7 +3050,7 @@ It is merely echoed by the server If not specified, the default value is: -"host-reservation-identifiers": [ "hw-address", "duid", "circuit-id" ] +"host-reservation-identifiers": [ "hw-address", "duid", "circuit-id", "client-id" ] From 05072326f3f8756e20641a3c12fa378d967fcc2f Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 8 Sep 2016 12:58:52 +0200 Subject: [PATCH 6/8] [3684] Updated examples as a result of review. --- doc/examples/kea4/backends.json | 6 +----- doc/examples/kea4/leases-expiration.json | 13 +++++-------- doc/examples/kea4/multiple-options.json | 13 +++++-------- doc/examples/kea4/mysql-reservations.json | 14 ++++++-------- doc/examples/kea4/pgsql-reservations.json | 14 ++++++-------- doc/examples/kea4/reservations.json | 13 +++++-------- doc/examples/kea4/several-subnets.json | 16 ++++++++-------- doc/examples/kea4/single-subnet.json | 13 +++++-------- doc/examples/kea6/advanced.json | 17 +++++++++-------- doc/examples/kea6/backends.json | 6 +++--- doc/examples/kea6/classify.json | 12 ++++++------ doc/examples/kea6/duid.json | 17 +++++++++-------- doc/examples/kea6/leases-expiration.json | 17 +++++++++-------- doc/examples/kea6/multiple-options.json | 17 +++++++++-------- doc/examples/kea6/mysql-reservations.json | 17 +++++++++-------- doc/examples/kea6/pgsql-reservations.json | 17 +++++++++-------- doc/examples/kea6/reservations.json | 17 +++++++++-------- doc/examples/kea6/several-subnets.json | 18 ++++++++++-------- doc/examples/kea6/simple.json | 23 ++++++++++++----------- 19 files changed, 135 insertions(+), 145 deletions(-) diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json index 7fdabe599c..b52b6fade8 100644 --- a/doc/examples/kea4/backends.json +++ b/doc/examples/kea4/backends.json @@ -68,11 +68,7 @@ # "contact_points": "192.0.2.1,192.0.2.2,192.0.2.3" # }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json index b1397b3d18..e66f094cca 100644 --- a/doc/examples/kea4/leases-expiration.json +++ b/doc/examples/kea4/leases-expiration.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -34,11 +35,7 @@ "unwarned-reclaim-cycles": 10 }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # The following list defines subnets. We have only one subnet diff --git a/doc/examples/kea4/multiple-options.json b/doc/examples/kea4/multiple-options.json index 817369b28c..ab07ff5fee 100644 --- a/doc/examples/kea4/multiple-options.json +++ b/doc/examples/kea4/multiple-options.json @@ -9,18 +9,15 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea4/mysql-reservations.json b/doc/examples/kea4/mysql-reservations.json index 79e95fb0e4..8bb1ae0530 100644 --- a/doc/examples/kea4/mysql-reservations.json +++ b/doc/examples/kea4/mysql-reservations.json @@ -8,20 +8,18 @@ # Kea is told to listen on ethX interface only. "interfaces-config": { "interfaces": [ "ethX" ] + }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea4/pgsql-reservations.json b/doc/examples/kea4/pgsql-reservations.json index c512c4d300..3f6b91b8b7 100644 --- a/doc/examples/kea4/pgsql-reservations.json +++ b/doc/examples/kea4/pgsql-reservations.json @@ -10,18 +10,16 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. + +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json index 3ebfcaf002..328a6b3511 100644 --- a/doc/examples/kea4/reservations.json +++ b/doc/examples/kea4/reservations.json @@ -9,18 +9,15 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea4/several-subnets.json b/doc/examples/kea4/several-subnets.json index 68f0d46afc..f33892a352 100644 --- a/doc/examples/kea4/several-subnets.json +++ b/doc/examples/kea4/several-subnets.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -37,19 +38,18 @@ "subnet": "192.0.4.0/24" } ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp4", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "severity": "INFO" } ] } diff --git a/doc/examples/kea4/single-subnet.json b/doc/examples/kea4/single-subnet.json index 385a2dda6b..c3793db668 100644 --- a/doc/examples/kea4/single-subnet.json +++ b/doc/examples/kea4/single-subnet.json @@ -10,18 +10,15 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. Client -# is told to start renewing after 1000 seconds. If the server does not respond -# after 2000 seconds since the lease was granted, client is supposed -# to start REBIND procedure (emergency renewal that allows switching -# to a different server). +# Addresses will be assigned with valid lifetimes being 4000. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options diff --git a/doc/examples/kea6/advanced.json b/doc/examples/kea6/advanced.json index 821db2bb2d..4ecd8f32dc 100644 --- a/doc/examples/kea6/advanced.json +++ b/doc/examples/kea6/advanced.json @@ -15,9 +15,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -71,19 +72,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/backends.json b/doc/examples/kea6/backends.json index 83a98f67c4..8a71510461 100644 --- a/doc/examples/kea6/backends.json +++ b/doc/examples/kea6/backends.json @@ -90,15 +90,15 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], "debuglevel": 0, diff --git a/doc/examples/kea6/classify.json b/doc/examples/kea6/classify.json index eac05896c7..020f5ed2d8 100644 --- a/doc/examples/kea6/classify.json +++ b/doc/examples/kea6/classify.json @@ -66,19 +66,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } - ], - "debuglevel": 99, - "severity": "DEBUG" + ], + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/duid.json b/doc/examples/kea6/duid.json index 4bc6440482..7d267cdae8 100644 --- a/doc/examples/kea6/duid.json +++ b/doc/examples/kea6/duid.json @@ -30,9 +30,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -50,7 +51,7 @@ # The following list defines subnets. Each subnet consists of at # least subnet and pool entries. - "subnet6": [ + "subnet6": [ { "pools": [ { "pool": "2001:db8:1::/80" } ], "subnet": "2001:db8:1::/64", @@ -59,17 +60,17 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } - ], + ], "debuglevel": 0, "severity": "INFO" } diff --git a/doc/examples/kea6/leases-expiration.json b/doc/examples/kea6/leases-expiration.json index 59fea3022b..0ec34df109 100644 --- a/doc/examples/kea6/leases-expiration.json +++ b/doc/examples/kea6/leases-expiration.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -56,19 +57,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/multiple-options.json b/doc/examples/kea6/multiple-options.json index 231a2ed306..498f718a4d 100644 --- a/doc/examples/kea6/multiple-options.json +++ b/doc/examples/kea6/multiple-options.json @@ -9,9 +9,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -49,19 +50,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/mysql-reservations.json b/doc/examples/kea6/mysql-reservations.json index ec50656ee2..e1f791c575 100644 --- a/doc/examples/kea6/mysql-reservations.json +++ b/doc/examples/kea6/mysql-reservations.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -71,19 +72,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/pgsql-reservations.json b/doc/examples/kea6/pgsql-reservations.json index 170c03e7d7..a75d21a057 100644 --- a/doc/examples/kea6/pgsql-reservations.json +++ b/doc/examples/kea6/pgsql-reservations.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -71,19 +72,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json index 79bf115575..abf73f91a2 100644 --- a/doc/examples/kea6/reservations.json +++ b/doc/examples/kea6/reservations.json @@ -12,9 +12,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -109,19 +110,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } ], - "debuglevel": 99, - "severity": "DEBUG" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/several-subnets.json b/doc/examples/kea6/several-subnets.json index ca93b8b431..48d0bdb5b4 100644 --- a/doc/examples/kea6/several-subnets.json +++ b/doc/examples/kea6/several-subnets.json @@ -10,9 +10,10 @@ "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -30,19 +31,19 @@ # The following list defines subnets. Each subnet consists of at # least subnet and pool entries. - "subnet6": [ + "subnet6": [ { "pools": [ { "pool": "2001:db8:1::/80" } ], "subnet": "2001:db8:1::/64" }, { "pools": [ { "pool": "2001:db8:2::/80" } ], - "subnet": "2001:db8:2::/64" }, + "subnet": "2001:db8:2::/64" }, { "pools": [ { "pool": "2001:db8:3::/80" } ], "subnet": "2001:db8:3::/64" }, { "pools": [ { "pool": "2001:db8:4::/80" } ], "subnet": "2001:db8:4::/64" } ] }, -# The following configures logging. It assumes that warning messages -# will be logged to stdout. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { @@ -52,7 +53,8 @@ "output": "stdout" } ], - "severity": "WARN" + "debuglevel": 0, + "severity": "INFO" } ] } diff --git a/doc/examples/kea6/simple.json b/doc/examples/kea6/simple.json index 7d0234683a..f7a77008cf 100644 --- a/doc/examples/kea6/simple.json +++ b/doc/examples/kea6/simple.json @@ -5,15 +5,16 @@ { "Dhcp6": -{ +{ # Kea is told to listen on ethX interface only. "interfaces-config": { "interfaces": [ "ethX" ] }, -# We need to specify lease type. As of May 2014, three backends are supported: -# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require -# any prior set up. +# We need to specify the the database used to store leases. As of +# September 2016, four database backends are supported: MySQL, +# PostgreSQL, Cassandra, and the in-memory database, Memfile. +# We'll use memfile because it doesn't require any prior set up. "lease-database": { "type": "memfile" }, @@ -31,7 +32,7 @@ # The following list defines subnets. Each subnet consists of at # least subnet and pool entries. - "subnet6": [ + "subnet6": [ { "pools": [ { "pool": "2001:db8:1::/80" } ], "subnet": "2001:db8:1::/64", @@ -40,19 +41,19 @@ ] }, -# The following configures logging. Kea will log all debug messages -# to /var/log/kea-debug.log file. +# The following configures logging. It assumes that messages with at least +# informational level (info, warn, error) will will be logged to stdout. "Logging": { "loggers": [ { "name": "kea-dhcp6", "output_options": [ { - "output": "/var/log/kea-debug.log" + "output": "stdout" } - ], - "debuglevel": 99, - "severity": "DEBUG" + ], + "debuglevel": 0, + "severity": "INFO" } ] } From 0a7591f0c9b5afe7fdc5a481f931a5db0ebce5e6 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 8 Sep 2016 13:13:03 +0200 Subject: [PATCH 7/8] [3684] Updated User's Guide per review comments. --- doc/guide/admin.xml | 4 ++-- doc/guide/dhcp6-srv.xml | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml index c086917dbf..ca47ff0d69 100644 --- a/doc/guide/admin.xml +++ b/doc/guide/admin.xml @@ -203,7 +203,7 @@ Host Reservations no yes - no + yes no @@ -211,7 +211,7 @@ Options defined on per host basis no yes - no + yes no diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 432654289b..672cea8b40 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2392,11 +2392,11 @@ should include options from the isc option space: client is greater than the number of reserved addresses or prefixes, the server will try to assign all reserved addresses or prefixes to the individual IAs and dynamically allocate addresses or prefixes to remaining IAs. If the - server cannot assign any of the reserved addresses or prefixes because of the - conflict, the server will pick next reserved address or prefix and try to - assign it to the client. If the server subsequently finds that there are no - more reservations that can be assigned to the client at the moment, the - server will try to assign leases dynamically. + server cannot assign a reserved address or prefix because it is in use, + the server will select next reserved address or prefix and try to assign it to + the client. If the server subsequently finds that there are no more reservations + that can be assigned to the client at the moment, the server will try to + assign leases dynamically. Making a reservation for a mobile host that may visit multiple subnets From 1fe02beb422ea60aefe407615fc308b457f21f46 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Tue, 13 Sep 2016 10:39:44 +0200 Subject: [PATCH 8/8] [3684] Updated configuration examples per second round of review. --- doc/examples/kea4/backends.json | 4 ++-- doc/examples/kea4/classify.json | 2 +- doc/examples/kea4/leases-expiration.json | 4 ++-- doc/examples/kea4/multiple-options.json | 4 ++-- doc/examples/kea4/mysql-reservations.json | 4 ++-- doc/examples/kea4/pgsql-reservations.json | 4 ++-- doc/examples/kea4/reservations.json | 4 ++-- doc/examples/kea4/several-subnets.json | 8 ++++---- doc/examples/kea4/single-subnet.json | 4 ++-- doc/examples/kea6/advanced.json | 2 +- doc/examples/kea6/backends.json | 2 +- doc/examples/kea6/classify.json | 2 +- doc/examples/kea6/leases-expiration.json | 2 +- doc/examples/kea6/multiple-options.json | 2 +- doc/examples/kea6/mysql-reservations.json | 2 +- doc/examples/kea6/pgsql-reservations.json | 2 +- doc/examples/kea6/reservations.json | 2 +- doc/examples/kea6/several-subnets.json | 2 +- doc/examples/kea6/simple.json | 2 +- 19 files changed, 29 insertions(+), 29 deletions(-) diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json index b52b6fade8..6f1d19cff6 100644 --- a/doc/examples/kea4/backends.json +++ b/doc/examples/kea4/backends.json @@ -68,7 +68,7 @@ # "contact_points": "192.0.2.1,192.0.2.2,192.0.2.3" # }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -90,7 +90,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/classify.json b/doc/examples/kea4/classify.json index 760f584fd5..e4766f0960 100644 --- a/doc/examples/kea4/classify.json +++ b/doc/examples/kea4/classify.json @@ -83,7 +83,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json index e66f094cca..d5f0188860 100644 --- a/doc/examples/kea4/leases-expiration.json +++ b/doc/examples/kea4/leases-expiration.json @@ -35,7 +35,7 @@ "unwarned-reclaim-cycles": 10 }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # The following list defines subnets. We have only one subnet @@ -50,7 +50,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/multiple-options.json b/doc/examples/kea4/multiple-options.json index ab07ff5fee..940c448547 100644 --- a/doc/examples/kea4/multiple-options.json +++ b/doc/examples/kea4/multiple-options.json @@ -17,7 +17,7 @@ "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -55,7 +55,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/mysql-reservations.json b/doc/examples/kea4/mysql-reservations.json index 8bb1ae0530..e1722073a9 100644 --- a/doc/examples/kea4/mysql-reservations.json +++ b/doc/examples/kea4/mysql-reservations.json @@ -19,7 +19,7 @@ "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -76,7 +76,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/pgsql-reservations.json b/doc/examples/kea4/pgsql-reservations.json index 3f6b91b8b7..ab89f6bdab 100644 --- a/doc/examples/kea4/pgsql-reservations.json +++ b/doc/examples/kea4/pgsql-reservations.json @@ -19,7 +19,7 @@ "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -76,7 +76,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/reservations.json b/doc/examples/kea4/reservations.json index 328a6b3511..17c8ceb5e0 100644 --- a/doc/examples/kea4/reservations.json +++ b/doc/examples/kea4/reservations.json @@ -17,7 +17,7 @@ "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -113,7 +113,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/several-subnets.json b/doc/examples/kea4/several-subnets.json index f33892a352..79606f9184 100644 --- a/doc/examples/kea4/several-subnets.json +++ b/doc/examples/kea4/several-subnets.json @@ -18,9 +18,9 @@ "type": "memfile" }, -# Addresses will be assigned with the valid lifetimes being 4000. -# Client is told to start renewing after 1000 seconds. If the server -# does not respond after 2000 seconds since the lease was granted, client +# Addresses will be assigned with a lifetime of 4000 seconds. +# The client is told to start renewing after 1000 seconds. If the server +# does not respond within 2000 seconds of the lease being granted, client # is supposed to start REBIND procedure (emergency renewal that allows # switching to a different server). "valid-lifetime": 4000, @@ -39,7 +39,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea4/single-subnet.json b/doc/examples/kea4/single-subnet.json index c3793db668..7ffa8b9495 100644 --- a/doc/examples/kea4/single-subnet.json +++ b/doc/examples/kea4/single-subnet.json @@ -18,7 +18,7 @@ "type": "memfile" }, -# Addresses will be assigned with valid lifetimes being 4000. +# Addresses will be assigned with a lifetime of 4000 seconds. "valid-lifetime": 4000, # Renew and rebind timers are commented out. This implies that options @@ -40,7 +40,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/advanced.json b/doc/examples/kea6/advanced.json index 4ecd8f32dc..3daca911fc 100644 --- a/doc/examples/kea6/advanced.json +++ b/doc/examples/kea6/advanced.json @@ -73,7 +73,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/backends.json b/doc/examples/kea6/backends.json index 8a71510461..4841c63c09 100644 --- a/doc/examples/kea6/backends.json +++ b/doc/examples/kea6/backends.json @@ -91,7 +91,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/classify.json b/doc/examples/kea6/classify.json index 020f5ed2d8..7b8c61fcb6 100644 --- a/doc/examples/kea6/classify.json +++ b/doc/examples/kea6/classify.json @@ -67,7 +67,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/leases-expiration.json b/doc/examples/kea6/leases-expiration.json index 0ec34df109..03b3d6b71b 100644 --- a/doc/examples/kea6/leases-expiration.json +++ b/doc/examples/kea6/leases-expiration.json @@ -58,7 +58,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/multiple-options.json b/doc/examples/kea6/multiple-options.json index 498f718a4d..bf7984c511 100644 --- a/doc/examples/kea6/multiple-options.json +++ b/doc/examples/kea6/multiple-options.json @@ -51,7 +51,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/mysql-reservations.json b/doc/examples/kea6/mysql-reservations.json index e1f791c575..2574cf9eb2 100644 --- a/doc/examples/kea6/mysql-reservations.json +++ b/doc/examples/kea6/mysql-reservations.json @@ -73,7 +73,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/pgsql-reservations.json b/doc/examples/kea6/pgsql-reservations.json index a75d21a057..6f7da55139 100644 --- a/doc/examples/kea6/pgsql-reservations.json +++ b/doc/examples/kea6/pgsql-reservations.json @@ -73,7 +73,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/reservations.json b/doc/examples/kea6/reservations.json index abf73f91a2..9ec546e272 100644 --- a/doc/examples/kea6/reservations.json +++ b/doc/examples/kea6/reservations.json @@ -111,7 +111,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/several-subnets.json b/doc/examples/kea6/several-subnets.json index 48d0bdb5b4..3dc74b6d41 100644 --- a/doc/examples/kea6/several-subnets.json +++ b/doc/examples/kea6/several-subnets.json @@ -43,7 +43,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ { diff --git a/doc/examples/kea6/simple.json b/doc/examples/kea6/simple.json index f7a77008cf..5c7da6310b 100644 --- a/doc/examples/kea6/simple.json +++ b/doc/examples/kea6/simple.json @@ -42,7 +42,7 @@ }, # The following configures logging. It assumes that messages with at least -# informational level (info, warn, error) will will be logged to stdout. +# informational level (info, warn, error and fatal) should be logged to stdout. "Logging": { "loggers": [ {