From: Tomek Mrugalski Date: Thu, 23 Sep 2021 11:49:29 +0000 (+0200) Subject: [#2050] Intro, dhcpv4 config example tweaked X-Git-Tag: Kea-2.0.0~36 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2969aa23a913474afab9743aa858943e15e40316;p=thirdparty%2Fkea.git [#2050] Intro, dhcpv4 config example tweaked - reservations added - expired-leases-processing added - pools fixed --- diff --git a/doc/examples/template-power-user-home/info.md b/doc/examples/template-power-user-home/info.md index f9e53f41b0..1812a6fc59 100644 --- a/doc/examples/template-power-user-home/info.md +++ b/doc/examples/template-power-user-home/info.md @@ -1,8 +1,8 @@ Kea Configuration Template: Home network of a power user ======================================================== -This directory contains template configurations for home network of a power user. -It may also be appropriate for a small office. It makes the following assumptions: +This directory contains template configurations for home network of a power user. It may also be +appropriate for a small office. It makes the following assumptions: - you want to use a single /24 class of IPv4 addresses - you want High Availability, so there are 2 DHCP servers @@ -14,9 +14,9 @@ It may also be appropriate for a small office. It makes the following assumption - you do not use IPv6 - you do not want to update your DNS -The logical set-up consists of two hosts, each running Kea DHCPv4 server and a Control -Agent (CA). The server connects with the CA using UNIX sockets. Each DHCPv4+CA acts -as one partner of the HA pair. +The logical set-up consists of two hosts, each running Kea DHCPv4 server and a Control Agent (CA). +The server connects with the CA using UNIX sockets. Each DHCPv4+CA acts as one partner of the HA +pair. ```mermaid flowchart LR @@ -24,5 +24,47 @@ flowchart LR DHCPv4-1 --UNIX--- CA-1 ==http=== CA-2 --UNIX--- DHCPv4-2 ``` +The CA-1 and CA-2 will each open a TCP port 8000 and will connect to each other. + Deployment Considerations ------------------------- + +The setup is not expected to be very performant. Most modest hardware will do. There are successful +deployments on Raspberry Pi platforms. If you are running a VM, 2GB ram with one CPU core should +be enough. If you don't have any preference, Ubuntu LTS is a choice that is easy to set up and is +low maintenance. However, any Linux or FreeBSD is fine. Less popular systems, such as OpenBSD or +NetBSD should also work in principle, but they are not regularly tested. + +The assumption is that there are 2 hosts that will be running the Kea setup: +- 192.168.1.2 - primary HA server (active, will handle all the traffic) +- 192.168.1.3 - secondary HA server (passive, ready to take over in case the primary fails) + +The network is 192.168.1.0/24. It is assumed that 192.168.1.1 is your default router. + +The whole network is split into dynamic and static pools. +- 192.168.1.100 - 192.168.1.199 - this is the dynamic pool. When new devices appear in your network, + they will be assigned dynamic addresses from this pool. +- The reservations are done outside of this dynamic range (depending on your addressing preference, + either 192.168.1.1-192.168.1.99 or 192.168.1.200-192.168.1.254). + +To deploy this setup, you need to conduct the following steps: +1. Install CA and DHCPv4 on host1, copy the config files to the typical locations. It's typically + /etc/kea on Linux and /usr/local/etc/kea on FreeBSD. The files are typically called + kea-ctrl-agent.conf and kea-dhcp4.conf. Please consult your start-up scripts. +2. At the very least alter the following to match your setup: + - the interface name which Kea should listen on + - the interface name which is used to access the subnet + - your addressing, if you use something different than 192.168.1.0/24 + - tweak your router option + - tweak your DNS option +3. If using firewall, make sure the server1 can reach the server2. A nice way to ensure that is to + try to retrieve its config: + + curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://192.168.1.3:8000/ + +2. Install CA and DHCPv4 on host2 + + +curl -1sLf 'https://dl.cloudsmith.io/public/isc/kea-1-9/setup.deb.sh' | sudo -E bash + +sudo apt install isc-kea-dhcp4-server isc-kea-ctrl-agent \ No newline at end of file diff --git a/doc/examples/template-power-user-home/kea-dhcp4-1.conf b/doc/examples/template-power-user-home/kea-dhcp4-1.conf index bd50e0c827..246d5a9f02 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-1.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-1.conf @@ -1,16 +1,22 @@ -// This is an example configuration of the Kea DHCPv4 server. It uses High -// Availability hooks library and Lease Commands hooks library to enable -// High Availability function for the DHCP server. Note that almost exactly -// the same configuration must be used on the second server (partner). -// The only difference is that "this-server-name" must be set to "server2" -// on this other server. Also, the interface configuration depends on the -// network settings of the particular machine. +// This is an example configuration of the Kea DHCPv4 server 1: // -// The servers using this configuration work in load balancing mode. +// - uses High Availability hooks library and Lease Commands hooks library +// to enable High Availability function for the DHCP server. This config +// file is for the primary (the active) server. +// - uses memfile, which stores lease data in a local CSV file +// - it assumes a single /24 addressing over a link that is directly reachable +// (no DHCP relays) +// - there is a handful of IP reservations +// +// It is expected to run with a standby (the passive) server, which has a very similar +// configuration. The only difference is that "this-server-name" must be set to "server2" on the +// other server. Also, the interface configuration depends on the network settings of the +// particular machine. + { -// DHCPv4 configuration starts here. "Dhcp4": { + // Add names of your network interfaces to listen on. "interfaces-config": { // The DHCPv4 server listens on this interface. When changing this to @@ -36,9 +42,28 @@ // Storage" for details. "lease-database": { // Memfile is the simplest and easiest backend to use. It's an in-memory + // database with data being written to a CSV file. It is very similar to + // what ISC DHCP does. "type": "memfile" }, + // Let's configure some global parameters. The home network is not very dynamic + // and there's no shortage of addresses, so no need to recycle aggresively. + "valid-lifetime": 43200, // leases will be valid for 12h + "renew-timer": 21600, // clients should renew every 6h + "rebind-timer": 32400, // clients should start looking for other servers after 9h + + // Kea will clean up its database of expired leases once per hour. However, it + // will keep the leases in expired state for 2 days. This greatly increases the + // chances for returning devices to get the same address again. To guarantee that, + // use host reservation. + "expired-leases-processing": { + "reclaim-timer-wait-time": 3600, + "hold-reclaimed-time": 172800, + "max-reclaim-leases": 0, + "max-reclaim-time": 0 + }, + // HA requires two hooks libraries to be loaded: libdhcp_lease_cmds.so and // libdhcp_ha.so. The former handles incoming lease updates from the HA peers. // The latter implements high availability feature for Kea. @@ -54,14 +79,13 @@ // The HA hooks library should be loaded. "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so", "parameters": { - // High Availability configuration is specified for the HA hook library. // Each server should have the same HA configuration, except for the // "this-server-name" parameter. "high-availability": [ { // This parameter points to this server instance. The respective // HA peers must have this parameter set to their own names. "this-server-name": "server1", - // The HA mode is set to load-balancing. In this mode, the active + // The HA mode is set to host-standby. In this mode, the active // servers share the traffic (50/50). "mode": "hot-standby", // Heartbeat is to be sent every 10 seconds if no other control @@ -69,7 +93,9 @@ "heartbeat-delay": 10000, // Maximum time for partner's response to a heartbeat, after which // failure detection is started. This is specified in milliseconds. - "max-response-delay": 10000, + // If we don't hear from the partner in 60 seconds, it's time to + // start worrying. + "max-response-delay": 60000, // The following parameters control how the server detects the // partner's failure. The ACK delay sets the threshold for the // 'secs' field of the received discovers. This is specified in @@ -80,35 +106,35 @@ "max-unacked-clients": 5, // This specifies the maximum timeout (in milliseconds) for the server // to complete sync. If you have a large deployment (high tens or - // hundreds of thausands of clients), you may need to increase it + // hundreds of thousands of clients), you may need to increase it // further. The default value is 60000ms (60 seconds). "sync-timeout": 60000, "peers": [ - // This is the configuration of this server instance. - { - "name": "server1", - // This specifies the URL of our server instance. The - // Control Agent must run along with our DHCPv4 server - // instance and the "http-host" and "http-port" must be - // set to the corresponding values. - "url": "http://192.168.1.2:8000/", - // This server is primary. The other one must be - // secondary. - "role": "primary" - }, - // This is the configuration of our HA peer. - { - "name": "server2", - // Specifies the URL on which the partner's control - // channel can be reached. The Control Agent is required - // to run on the partner's machine with "http-host" and - // "http-port" values set to the corresponding values. - "url": "http://192.168.1.3:8000/", - // The partner is a secondary. Our is primary. - "role": "standby" - } - ] - } ] + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of our server instance. The + // Control Agent must run along with our DHCPv4 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. + "url": "http://192.168.1.2:8000/", + // This server is primary. The other one must be + // secondary. + "role": "primary" + }, + // This is the configuration of our HA peer. + { + "name": "server2", + // Specifies the URL on which the partner's control + // channel can be reached. The Control Agent is required + // to run on the partner's machine with "http-host" and + // "http-port" values set to the corresponding values. + "url": "http://192.168.1.3:8000/", + // The partner is a secondary. Our is primary. + "role": "standby" + } + ] + } ] } } ], @@ -123,26 +149,23 @@ // is reachable directly via the ethX interface. "interface": "enp0s8", - // Specify four address pools. + // Specify a dynamic address pool. "pools": [ { - "pool": "192.168.1.100-192.168.1.149", + "pool": "192.168.1.100-192.168.1.199", "client-class": "HA_server1" - }, - { - "pool": "192.168.1.150-192.168.1.200", - "client-class": "HA_server2" } ], - // These are options that are subnet specific. In most cases, - // you need to define at least routers option, as without this - // option your clients will not be able to reach their default - // gateway and will not have Internet connectivity. + // These are options that are subnet specific. In most cases, you need to define at + // least routers option, as without this option your clients will not be able to reach + // their default gateway and will not have Internet connectivity. If you have many + // subnets and they share the same options (e.g. DNS servers typically is the same + // everywhere), you may define options in the global scope, so you don't repeat them + // for every network. "option-data": [ { - // For each IPv4 subnet you most likely need to specify at - // least one router. + // For each IPv4 subnet you typically need to specify at least one router. "name": "routers", "data": "192.168.1.1" }, @@ -154,6 +177,25 @@ "name": "domain-name-servers", "data": "1.1.1.1,9.9.9.9" } + ], + + // Some devices should get a static address. Since the .100 - .199 range is dynamic, + // let's use the lower address space for this. There are many ways how reservation + // can be defined, but using MAC address (hw-address) is by far the most popular one. + // You can use client-id, duid and even custom defined flex-id that may use whatever + // parts of the packet you want to use as identifiers. Also, there are many more things + // you can specify in addition to just an IP address: extra options, next-server, hostname, + // assign device to client classes etc. See the Kea ARM, Section 8.3 for details. + // The reservations are subnet specific. + "reservations": [ + { + "hw-address": "1a:1b:1c:1d:1e:1f", + "ip-address": "192.168.1.10" + }, + { + "client-id": "01:11:22:33:44:55:66", + "ip-address": "192.168.1.11" + } ] } ], @@ -161,9 +203,10 @@ // Logging configuration starts here. "loggers": [ { - // This section affects kea-dhcp4, which is the base logger for DHCPv4 - // component. It tells DHCPv4 server to write all log messages (on - // severity INFO or more) to a file. + // This section affects kea-dhcp4, which is the base logger for DHCPv4 component. It tells + // DHCPv4 server to write all log messages (on severity INFO or higher) to a file. The file + // will be rotated once it grows to 2MB and up to 4 files will be kept. The debuglevel + // (range 0 to 99) is used only when logging on DEBUG level. "name": "kea-dhcp4", "output_options": [ { @@ -172,7 +215,8 @@ "maxver": 4 } ], - "severity": "INFO" + "severity": "INFO", + "debuglevel": 0 } ] } diff --git a/doc/examples/template-power-user-home/kea-dhcp4-2.conf b/doc/examples/template-power-user-home/kea-dhcp4-2.conf index 8c969d4260..bf432cfd04 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-2.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-2.conf @@ -69,7 +69,7 @@ "heartbeat-delay": 10000, // Maximum time for partner's response to a heartbeat, after which // failure detection is started. This is specified in milliseconds. - "max-response-delay": 10000, + "max-response-delay": 60000, // The following parameters control how the server detects the // partner's failure. The ACK delay sets the threshold for the // 'secs' field of the received discovers. This is specified in