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
- 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
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
-// 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
// 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.
// 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
"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
"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"
+ }
+ ]
+ } ]
}
}
],
// 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"
},
"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"
+ }
]
}
],
// 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": [
{
"maxver": 4
}
],
- "severity": "INFO"
+ "severity": "INFO",
+ "debuglevel": 0
}
]
}
projects / thirdparty / kea.git / commitdiff
