# Configuration Templates

The following sections include configuration templates for certain deployment types. The example configuration files are also available in the Kea sources, in the `doc/examples` directory.

## Template: Home Network of a Power User

Below are some templates to assist in configuring the home network of a power user; they may also be appropriate for a small office. These templates make the following assumptions:

- The administrator wants to use a single /24 class of IPv4 addresses.

- High Availability (HA) is desired, so there are two DHCP servers.

- There are a handful of devices, and some of them (e.g. a printer or NAS) require static addresses or extra options.

- The administrator does not want to be bothered with database management.

- The setup is optimized for minimal to zero maintenance.

- Performance is not an issue; hundreds of queries per second are not expected.

- IPv6 is not used.

- DNS updates will not be performed by Kea.

The logical setup consists of two hosts, each running a 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.

    +-host-1-+       +-host-2-+
    |        |       |        |
    |   CA <===\   /===> CA   |    ===== - HTTP connection
    |   #    |  \ /  |   #    |
    |   #    |   X   |   #    |    ##### - UNIX socket
    |   #    |  / \      #    |
    | DHCPv4 ==/   \== DHCPv4 |
    |        |       |        |
    +--------+       +--------+

The CAs on host-1 and host-2 both listen on port 8000. The DHCP servers communicate with each other via the CAs, which forward control commands to the DHCP servers over the UNIX domain sockets.

### Deployment Considerations

This setup is not expected to be very performant. Most modest hardware will do; Kea has been successfully deployed on Raspberry Pi platforms, for example. If it is running on a VM, 2GB of RAM with one CPU core should be sufficient. Ubuntu LTS is a choice that is easy to set up and is low maintenance; however, any Linux or FreeBSD operating system is fine. Less popular systems, such as OpenBSD or NetBSD, should also work in principle, but they are not regularly tested.

In this example, there are two hosts running Kea:

- 192.168.1.2 - primary HA server (active, handles all the traffic)

- 192.168.1.3 - secondary HA server (passive, ready to take over if the primary fails)

The network is 192.168.1.0/24. It is assumed that 192.168.1.1 is the default router.

The whole subnet 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 the network, they are assigned dynamic addresses from this pool.

- The reservations are done outside of this dynamic range (depending on the addressing preference, either 192.168.1.1-192.168.1.99 or 192.168.1.200-192.168.1.254).

To deploy this setup, perform the following steps:

1. Install the CA and the DHCPv4 server on host-1, and copy the configuration files to their typical locations. They are usually in `/etc/kea` on Linux and `/usr/local/etc/kea` on FreeBSD, and the files are typically called `kea-ctrl-agent.conf` and `kea-dhcp4.conf`. Please consult the startup scripts for any specific system.

2. Alter the following to match the local setup:

   - The interface name that Kea should listen on (`interfaces` in `interfaces-config`).

   - The interface name that is used to access the subnet (`interface` in `subnet4`).

   - The addressing, if using something other than 192.168.1.0/24. Make sure the CA port configuration (`http-host` and `http-port` in `kea-ca.conf`) matches the DHCPv4 server configuration (`url` in `hook-libraries/parameters/high-availability/peers` in `kea-dhcp4.conf`).

   - The router option, to match the actual network.

   - The DNS option, to match the actual network.

   - The path to the hook libraries. This is a very OS-specific parameter; the library names are generally the same everywhere, but the path varies. See Introduction for details.

3. If using a firewall, make sure host-1 can reach host-2. An easy way to ensure that is to try to retrieve host-2's config from host-1:

   `curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://192.168.1.3:8000/`

   The DHCPv4 running configuration should be returned, in JSON format.

4. Verify that communication between the hosts works in the opposite direction as well (host-2 can connect to host-1), by repeating step 3 from host-2 using host-1's IP address and port.

5. Install the CA and the DHCPv4 server on host-2, as in steps 1 and 2. The config file for the standby server is very similar to the one on the primary server, other than the definition of the `this-server-name` field (and possibly the interface names).

### Possible Extensions

This sample configuration is basic but functional. Once it is set up and running, administrators may wish to consider the following changes:

- If there is a local DNS server, DNS updates can be configured via Kea. This requires running a DHCP-DDNS update server (`kea-dhcp-ddns`). See Overview for details.

- To run Stateful DHCP for IPv6, a `kea-dhcp6` server is necessary. Its configuration is very similar to `kea-dhcp4`, but there are some notable differences: the default gateway is not configured via the DHCPv6 protocol, but via router advertisements sent by the local router. Also, the DHCPv6 concept of prefix delegation does not exist in DHCPv4. See The DHCPv6 Server for details.

- To expand the local network, adding a MySQL or PostgreSQL database is a popular solution. Users can choose to store leases, host reservations, and even most of the configuration in a database. See Kea Database Administration and the `lease-database`, `hosts-database`, and `config-control` parameters in The DHCPv4 Server.

- To provide more insight into how the DHCP server operates, Kea's RESTful API can query for many runtime statistics or even change the configuration during runtime. Users may also consider deploying Stork, which is a rapidly developing dashboard for Kea. See Monitoring Kea With Stork for more information.

- All Kea users should read Kea Security: to learn about various trade-offs between convenience and security in Kea.

Some tweaking of these templates may be required to match specific system needs: at a minimum, the lines highlighted in yellow must be adjusted to match the actual deployment.

Server1's Control Agent configuration file:

     1// This is an example of a configuration for Control-Agent (CA) listening
     2// for incoming HTTP traffic. This is necessary for handling API commands,
     3// in particular lease update commands needed for HA setup.
     4{
     5    "Control-agent":
     6    {
     7        // We need to specify where the agent should listen to incoming HTTP
     8        // queries.
     9        "http-host": "192.168.1.2",
    10
    11        // This specifies the port CA will listen on.
    12        "http-port": 8000,
    13
    14        "control-sockets":
    15        {
    16            // This is how the Agent can communicate with the DHCPv4 server.
    17            "dhcp4":
    18            {
    19                "comment": "socket to DHCPv4 server",
    20                "socket-type": "unix",
    21                "socket-name": "/tmp/kea4-ctrl-socket"
    22            },
    23
    24            // Location of the DHCPv6 command channel socket.
    25            "dhcp6":
    26            {
    27                "socket-type": "unix",
    28                "socket-name": "/tmp/kea6-ctrl-socket"
    29            },
    30
    31            // Location of the D2 command channel socket.
    32            "d2":
    33            {
    34                "socket-type": "unix",
    35                "socket-name": "/tmp/kea-ddns-ctrl-socket",
    36                "user-context": { "in-use": false }
    37            }
    38        },
    39
    40        // Similar to other Kea components, CA also uses logging.
    41        "loggers": [
    42            {
    43                "name": "kea-ctrl-agent",
    44                "output_options": [
    45                    {
    46                        "output": "/var/log/kea-ctrl-agent.log",
    47
    48                        // Several additional parameters are possible in addition
    49                        // to the typical output. Flush determines whether logger
    50                        // flushes output to a file. Maxsize determines maximum
    51                        // filesize before the file is rotated. maxver
    52                        // specifies the maximum number of rotated files being
    53                        // kept.
    54                        "flush": true,
    55                        "maxsize": 204800,
    56                        "maxver": 4,
    57                        // We use pattern to specify custom log message layout
    58                        "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n"
    59                    }
    60                ],
    61                "severity": "INFO",
    62                "debuglevel": 0 // debug level only applies when severity is set to DEBUG.
    63            }
    64        ]
    65    }
    66}

Server1's DHCPv4 configuration file:

      1// This is an example configuration of the Kea DHCPv4 server 1:
      2//
      3// - uses High Availability hook library and Lease Commands hook library
      4//   to enable High Availability function for the DHCP server. This config
      5//   file is for the primary (the active) server.
      6// - uses memfile, which stores lease data in a local CSV file
      7// - it assumes a single /24 addressing over a link that is directly reachable
      8//   (no DHCP relays)
      9// - there is a handful of IP reservations
     10//
     11// It is expected to run with a standby (the passive) server, which has a very similar
     12// configuration. The only difference is that "this-server-name" must be set to "server2" on the
     13// other server. Also, the interface configuration depends on the network settings of the
     14// particular machine.
     15
     16{
     17
     18"Dhcp4": {
     19
     20    // Add names of your network interfaces to listen on.
     21    "interfaces-config": {
     22        // The DHCPv4 server listens on this interface. When changing this to
     23        // the actual name of your interface, make sure to also update the
     24        // interface parameter in the subnet definition below.
     25        "interfaces": [ "enp0s8" ]
     26    },
     27
     28    // Control socket is required for communication between the Control
     29    // Agent and the DHCP server. High Availability requires Control Agent
     30    // to be running because lease updates are sent over the RESTful
     31    // API between the HA peers.
     32    "control-socket": {
     33        "socket-type": "unix",
     34        "socket-name": "/tmp/kea4-ctrl-socket"
     35    },
     36
     37    // Use Memfile lease database backend to store leases in a CSV file.
     38    // Depending on how Kea was compiled, it may also support SQL databases
     39    // (MySQL and/or PostgreSQL). Those database backends require more
     40    // parameters, like name, host and possibly user and password.
     41    // There are dedicated examples for each backend. See Section 7.2.2 "Lease
     42    // Storage" for details.
     43    "lease-database": {
     44        // Memfile is the simplest and easiest backend to use. It's an in-memory
     45        // database with data being written to a CSV file. It is very similar to
     46        // what ISC DHCP does.
     47        "type": "memfile"
     48    },
     49
     50    // Let's configure some global parameters. The home network is not very dynamic
     51    // and there's no shortage of addresses, so no need to recycle aggressively.
     52    "valid-lifetime": 43200, // leases will be valid for 12h
     53    "renew-timer": 21600, // clients should renew every 6h
     54    "rebind-timer": 32400, // clients should start looking for other servers after 9h
     55
     56    // Kea will clean up its database of expired leases once per hour. However, it
     57    // will keep the leases in expired state for 2 days. This greatly increases the
     58    // chances for returning devices to get the same address again. To guarantee that,
     59    // use host reservation.
     60    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
     61    // not 0, when the client sends a release message the lease is expired
     62    // instead of being deleted from lease storage.
     63    "expired-leases-processing": {
     64        "reclaim-timer-wait-time": 3600,
     65        "hold-reclaimed-time": 172800,
     66        "max-reclaim-leases": 0,
     67        "max-reclaim-time": 0
     68    },
     69
     70    // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and
     71    // libdhcp_ha.so. The former handles incoming lease updates from the HA peers.
     72    // The latter implements high availability feature for Kea. Note the library name
     73    // should be the same, but the path is OS specific.
     74    "hooks-libraries": [
     75        // The lease_cmds library must be loaded because HA makes use of it to
     76        // deliver lease updates to the server as well as synchronize the
     77        // lease database after failure.
     78        {
     79            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so"
     80        },
     81
     82        {
     83            // The HA hook library should be loaded.
     84            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
     85            "parameters": {
     86                // Each server should have the same HA configuration, except for the
     87                // "this-server-name" parameter.
     88                "high-availability": [ {
     89                    // This parameter points to this server instance. The respective
     90                    // HA peers must have this parameter set to their own names.
     91                    "this-server-name": "server1",
     92                    // The HA mode is set to hot-standby. In this mode, the active server handles
     93                    // all the traffic. The standby takes over if the primary becomes unavailable.
     94                    "mode": "hot-standby",
     95                    // Heartbeat is to be sent every 10 seconds if no other control
     96                    // commands are transmitted.
     97                    "heartbeat-delay": 10000,
     98                    // Maximum time for partner's response to a heartbeat, after which
     99                    // failure detection is started. This is specified in milliseconds.
    100                    // If we don't hear from the partner in 60 seconds, it's time to
    101                    // start worrying.
    102                    "max-response-delay": 60000,
    103                    // The following parameters control how the server detects the
    104                    // partner's failure. The ACK delay sets the threshold for the
    105                    // 'secs' field of the received discovers. This is specified in
    106                    // milliseconds.
    107                    "max-ack-delay": 5000,
    108                    // This specifies the number of clients which send messages to
    109                    // the partner but appear to not receive any response.
    110                    "max-unacked-clients": 5,
    111                    // This specifies the maximum timeout (in milliseconds) for the server
    112                    // to complete sync. If you have a large deployment (high tens or
    113                    // hundreds of thousands of clients), you may need to increase it
    114                    // further. The default value is 60000ms (60 seconds).
    115                    "sync-timeout": 60000,
    116                    "peers": [
    117                        // This is the configuration of this server instance.
    118                        {
    119                            "name": "server1",
    120                            // This specifies the URL of this server instance. The
    121                            // Control Agent must run along with this DHCPv4 server
    122                            // instance and the "http-host" and "http-port" must be
    123                            // set to the corresponding values.
    124                            "url": "http://192.168.1.2:8000/",
    125                            // This server is primary. The other one must be
    126                            // secondary.
    127                            "role": "primary"
    128                        },
    129                        // This is the configuration of the secondary server.
    130                        {
    131                            "name": "server2",
    132                            // Specifies the URL on which the partner's control
    133                            // channel can be reached. The Control Agent is required
    134                            // to run on the partner's machine with "http-host" and
    135                            // "http-port" values set to the corresponding values.
    136                            "url": "http://192.168.1.3:8000/",
    137                            // The other server is secondary. This one must be
    138                            // primary.
    139                            "role": "standby"
    140                        }
    141                    ]
    142                } ]
    143            }
    144        }
    145    ],
    146
    147    // This example contains a single subnet declaration.
    148    "subnet4": [
    149        {
    150            // Subnet prefix.
    151            "subnet": "192.168.1.0/24",
    152
    153            // There are no relays in this network, so we need to tell Kea that this subnet
    154            // is reachable directly via the specified interface.
    155            "interface": "enp0s8",
    156
    157            // Specify a dynamic address pool.
    158            "pools": [
    159                {
    160                    "pool": "192.168.1.100-192.168.1.199"
    161                }
    162            ],
    163
    164            // These are options that are subnet specific. In most cases, you need to define at
    165            // least routers option, as without this option your clients will not be able to reach
    166            // their default gateway and will not have Internet connectivity. If you have many
    167            // subnets and they share the same options (e.g. DNS servers typically is the same
    168            // everywhere), you may define options at the global scope, so you don't repeat them
    169            // for every network.
    170            "option-data": [
    171                {
    172                    // For each IPv4 subnet you typically need to specify at least one router.
    173                    "name": "routers",
    174                    "data": "192.168.1.1"
    175                },
    176                {
    177                    // Using cloudflare or Quad9 is a reasonable option. Change this
    178                    // to your own DNS servers is you have them. Another popular
    179                    // choice is 8.8.8.8, owned by Google. Using third party DNS
    180                    // service raises some privacy concerns.
    181                    "name": "domain-name-servers",
    182                    "data": "1.1.1.1,9.9.9.9"
    183                }
    184            ],
    185
    186            // Some devices should get a static address. Since the .100 - .199 range is dynamic,
    187            // let's use the lower address space for this. There are many ways how reservation
    188            // can be defined, but using MAC address (hw-address) is by far the most popular one.
    189            // You can use client-id, duid and even custom defined flex-id that may use whatever
    190            // parts of the packet you want to use as identifiers. Also, there are many more things
    191            // you can specify in addition to just an IP address: extra options, next-server, hostname,
    192            // assign device to client classes etc. See the Kea ARM, Section 8.3 for details.
    193            // The reservations are subnet specific.
    194            "reservations": [
    195                {
    196                    "hw-address": "1a:1b:1c:1d:1e:1f",
    197                    "ip-address": "192.168.1.10"
    198                },
    199                {
    200                    "client-id": "01:11:22:33:44:55:66",
    201                    "ip-address": "192.168.1.11"
    202                }
    203            ]
    204        }
    205    ],
    206
    207    // Logging configuration starts here.
    208    "loggers": [
    209    {
    210        // This section affects kea-dhcp4, which is the base logger for DHCPv4 component. It tells
    211        // DHCPv4 server to write all log messages (on severity INFO or higher) to a file. The file
    212        // will be rotated once it grows to 2MB and up to 4 files will be kept. The debuglevel
    213        // (range 0 to 99) is used only when logging on DEBUG level.
    214        "name": "kea-dhcp4",
    215        "output_options": [
    216            {
    217                "output": "/var/log/kea-dhcp4.log",
    218                "maxsize": 2048000,
    219                "maxver": 4
    220            }
    221        ],
    222        "severity": "INFO",
    223        "debuglevel": 0
    224    }
    225  ]
    226}
    227}

Server2's Control Agent configuration file:

     1// This is an example of a configuration for Control-Agent (CA) listening
     2// for incoming HTTP traffic. This is necessary for handling API commands,
     3// in particular lease update commands needed for HA setup.
     4{
     5    "Control-agent":
     6    {
     7        // We need to specify where the agent should listen to incoming HTTP
     8        // queries.
     9        "http-host": "192.168.1.3",
    10
    11        // This specifies the port CA will listen on.
    12        "http-port": 8000,
    13
    14        "control-sockets":
    15        {
    16            // This is how the Agent can communicate with the DHCPv4 server.
    17            "dhcp4":
    18            {
    19                "comment": "socket to DHCPv4 server",
    20                "socket-type": "unix",
    21                "socket-name": "/tmp/kea4-ctrl-socket"
    22            },
    23
    24            // Location of the DHCPv6 command channel socket.
    25            "dhcp6":
    26            {
    27                "socket-type": "unix",
    28                "socket-name": "/tmp/kea6-ctrl-socket"
    29            },
    30
    31            // Location of the D2 command channel socket.
    32            "d2":
    33            {
    34                "socket-type": "unix",
    35                "socket-name": "/tmp/kea-ddns-ctrl-socket",
    36                "user-context": { "in-use": false }
    37            }
    38        },
    39
    40        // Similar to other Kea components, CA also uses logging.
    41        "loggers": [
    42            {
    43                "name": "kea-ctrl-agent",
    44                "output_options": [
    45                    {
    46                        "output": "/var/log/kea-ctrl-agent.log",
    47
    48                        // Several additional parameters are possible in addition
    49                        // to the typical output. Flush determines whether logger
    50                        // flushes output to a file. Maxsize determines maximum
    51                        // filesize before the file is rotated. maxver
    52                        // specifies the maximum number of rotated files being
    53                        // kept.
    54                        "flush": true,
    55                        "maxsize": 204800,
    56                        "maxver": 4,
    57                        // We use pattern to specify custom log message layout
    58                        "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n"
    59                    }
    60                ],
    61                "severity": "INFO",
    62                "debuglevel": 0 // debug level only applies when severity is set to DEBUG.
    63            }
    64        ]
    65    }
    66}

Server2's DHCPv4 configuration file:

      1// This is an example configuration of the Kea DHCPv4 server 2:
      2//
      3// - uses High Availability hook library and Lease Commands hook library
      4//   to enable High Availability function for the DHCP server. This config
      5//   file is for the primary (the active) server.
      6// - uses memfile, which stores lease data in a local CSV file
      7// - it assumes a single /24 addressing over a link that is directly reachable
      8//   (no DHCP relays)
      9// - there is a handful of IP reservations
     10//
     11// It is expected to run with a primary (the active) server, which has a very similar
     12// configuration. The only difference is that "this-server-name" must be set to "server2" on the
     13// other server. Also, the interface configuration depends on the network settings of the
     14// particular machine.
     15
     16{
     17
     18"Dhcp4": {
     19
     20    // Add names of your network interfaces to listen on.
     21    "interfaces-config": {
     22        // The DHCPv4 server listens on this interface. When changing this to
     23        // the actual name of your interface, make sure to also update the
     24        // interface parameter in the subnet definition below.
     25        "interfaces": [ "enp0s8" ]
     26    },
     27
     28    // Control socket is required for communication between the Control
     29    // Agent and the DHCP server. High Availability requires Control Agent
     30    // to be running because lease updates are sent over the RESTful
     31    // API between the HA peers.
     32    "control-socket": {
     33        "socket-type": "unix",
     34        "socket-name": "/tmp/kea4-ctrl-socket"
     35    },
     36
     37    // Use Memfile lease database backend to store leases in a CSV file.
     38    // Depending on how Kea was compiled, it may also support SQL databases
     39    // (MySQL and/or PostgreSQL). Those database backends require more
     40    // parameters, like name, host and possibly user and password.
     41    // There are dedicated examples for each backend. See Section 7.2.2 "Lease
     42    // Storage" for details.
     43    "lease-database": {
     44        // Memfile is the simplest and easiest backend to use. It's an in-memory
     45        // database with data being written to a CSV file. It is very similar to
     46        // what ISC DHCP does.
     47        "type": "memfile"
     48    },
     49
     50    // Let's configure some global parameters. The home network is not very dynamic
     51    // and there's no shortage of addresses, so no need to recycle aggressively.
     52    "valid-lifetime": 43200, // leases will be valid for 12h
     53    "renew-timer": 21600, // clients should renew every 6h
     54    "rebind-timer": 32400, // clients should start looking for other servers after 9h
     55
     56    // Kea will clean up its database of expired leases once per hour. However, it
     57    // will keep the leases in expired state for 2 days. This greatly increases the
     58    // chances for returning devices to get the same address again. To guarantee that,
     59    // use host reservation.
     60    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
     61    // not 0, when the client sends a release message the lease is expired
     62    // instead of being deleted from lease storage.
     63    "expired-leases-processing": {
     64        "reclaim-timer-wait-time": 3600,
     65        "hold-reclaimed-time": 172800,
     66        "max-reclaim-leases": 0,
     67        "max-reclaim-time": 0
     68    },
     69
     70    // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and
     71    // libdhcp_ha.so. The former handles incoming lease updates from the HA peers.
     72    // The latter implements high availability feature for Kea. Note the library name
     73    // should be the same, but the path is OS specific.
     74    "hooks-libraries": [
     75        // The lease_cmds library must be loaded because HA makes use of it to
     76        // deliver lease updates to the server as well as synchronize the
     77        // lease database after failure.
     78        {
     79            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so"
     80        },
     81
     82        {
     83            // The HA hook library should be loaded.
     84            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
     85            "parameters": {
     86                // Each server should have the same HA configuration, except for the
     87                // "this-server-name" parameter.
     88                "high-availability": [ {
     89                    // This parameter points to this server instance. The respective
     90                    // HA peers must have this parameter set to their own names.
     91                    "this-server-name": "server2",
     92                    // The HA mode is set to hot-standby. In this mode, the active server handles
     93                    // all the traffic. The standby takes over if the primary becomes unavailable.
     94                    "mode": "hot-standby",
     95                    // Heartbeat is to be sent every 10 seconds if no other control
     96                    // commands are transmitted.
     97                    "heartbeat-delay": 10000,
     98                    // Maximum time for partner's response to a heartbeat, after which
     99                    // failure detection is started. This is specified in milliseconds.
    100                    // If we don't hear from the partner in 60 seconds, it's time to
    101                    // start worrying.
    102                    "max-response-delay": 60000,
    103                    // The following parameters control how the server detects the
    104                    // partner's failure. The ACK delay sets the threshold for the
    105                    // 'secs' field of the received discovers. This is specified in
    106                    // milliseconds.
    107                    "max-ack-delay": 5000,
    108                    // This specifies the number of clients which send messages to
    109                    // the partner but appear to not receive any response.
    110                    "max-unacked-clients": 5,
    111                    // This specifies the maximum timeout (in milliseconds) for the server
    112                    // to complete sync. If you have a large deployment (high tens or
    113                    // hundreds of thousands of clients), you may need to increase it
    114                    // further. The default value is 60000ms (60 seconds).
    115                    "sync-timeout": 60000,
    116                    "peers": [
    117                        // This is the configuration of the primary server.
    118                        {
    119                            "name": "server1",
    120                            // Specifies the URL on which the partner's control
    121                            // channel can be reached. The Control Agent is required
    122                            // to run on the partner's machine with "http-host" and
    123                            // "http-port" values set to the corresponding values.
    124                            "url": "http://192.168.1.2:8000/",
    125                            // The other server is primary. This one must be
    126                            // secondary.
    127                            "role": "primary"
    128                        },
    129                        // This is the configuration of this server instance.
    130                        {
    131                            "name": "server2",
    132                            // This specifies the URL of this server instance. The
    133                            // Control Agent must run along with this DHCPv4 server
    134                            // instance and the "http-host" and "http-port" must be
    135                            // set to the corresponding values.
    136                            "url": "http://192.168.1.3:8000/",
    137                            // This server is secondary. The other one must be
    138                            // primary.
    139                            "role": "standby"
    140                        }
    141                    ]
    142                } ]
    143            }
    144        }
    145    ],
    146
    147    // This example contains a single subnet declaration.
    148    "subnet4": [
    149        {
    150            // Subnet prefix.
    151            "subnet": "192.168.1.0/24",
    152
    153            // There are no relays in this network, so we need to tell Kea that this subnet
    154            // is reachable directly via the specified interface.
    155            "interface": "enp0s8",
    156
    157            // Specify a dynamic address pool.
    158            "pools": [
    159                {
    160                    "pool": "192.168.1.100-192.168.1.199"
    161                }
    162            ],
    163
    164            // These are options that are subnet specific. In most cases, you need to define at
    165            // least routers option, as without this option your clients will not be able to reach
    166            // their default gateway and will not have Internet connectivity. If you have many
    167            // subnets and they share the same options (e.g. DNS servers typically is the same
    168            // everywhere), you may define options at the global scope, so you don't repeat them
    169            // for every network.
    170            "option-data": [
    171                {
    172                    // For each IPv4 subnet you typically need to specify at least one router.
    173                    "name": "routers",
    174                    "data": "192.168.1.1"
    175                },
    176                {
    177                    // Using cloudflare or Quad9 is a reasonable option. Change this
    178                    // to your own DNS servers is you have them. Another popular
    179                    // choice is 8.8.8.8, owned by Google. Using third party DNS
    180                    // service raises some privacy concerns.
    181                    "name": "domain-name-servers",
    182                    "data": "1.1.1.1,9.9.9.9"
    183                }
    184            ],
    185
    186            // Some devices should get a static address. Since the .100 - .199 range is dynamic,
    187            // let's use the lower address space for this. There are many ways how reservation
    188            // can be defined, but using MAC address (hw-address) is by far the most popular one.
    189            // You can use client-id, duid and even custom defined flex-id that may use whatever
    190            // parts of the packet you want to use as identifiers. Also, there are many more things
    191            // you can specify in addition to just an IP address: extra options, next-server, hostname,
    192            // assign device to client classes etc. See the Kea ARM, Section 8.3 for details.
    193            // The reservations are subnet specific.
    194            "reservations": [
    195                {
    196                    "hw-address": "1a:1b:1c:1d:1e:1f",
    197                    "ip-address": "192.168.1.10"
    198                },
    199                {
    200                    "client-id": "01:11:22:33:44:55:66",
    201                    "ip-address": "192.168.1.11"
    202                }
    203            ]
    204        }
    205    ],
    206
    207    // Logging configuration starts here.
    208    "loggers": [
    209    {
    210        // This section affects kea-dhcp4, which is the base logger for DHCPv4 component. It tells
    211        // DHCPv4 server to write all log messages (on severity INFO or higher) to a file. The file
    212        // will be rotated once it grows to 2MB and up to 4 files will be kept. The debuglevel
    213        // (range 0 to 99) is used only when logging on DEBUG level.
    214        "name": "kea-dhcp4",
    215        "output_options": [
    216            {
    217                "output": "/var/log/kea-dhcp4.log",
    218                "maxsize": 2048000,
    219                "maxver": 4
    220            }
    221        ],
    222        "severity": "INFO",
    223        "debuglevel": 0
    224    }
    225  ]
    226}
    227}

## Template: Secure High Availability Kea DHCP with Multi-Threading

Below are some templates to assist in configuring a secure Kea DHCP server with multi-threading. These templates make the following assumptions:

- The administrator wants to set up High Availability (HA) with multi-threading.

- The machines running Kea with multi-threading have at least four CPU cores.

- The connection to the peer is secured using TLS.

The logical setup consists of two hosts, each running a Kea DHCPv4 server and a Control Agent (CA). In the multi-threading setup, the CA is not required, as the server is using its own dedicated HTTP listener to communicate with the peer. However, the CA can still be used to handle user commands.

    +-host-1-+       +-host-2-+
    |        |       |        |
    |   CA   |       |   CA   |    ===== - HTTPS connection
    |   #    |       |   #    |
    |   #    |       |   #    |    ##### - UNIX socket
    |   #    |       |   #    |
    | DHCPv4 ========= DHCPv4 |
    |        |       |        |
    +--------+       +--------+

The CAs on host-1 and host-2 both listen on port 8001, and the server's dedicated HTTP listener uses port 8000. The DHCP servers communicate with each other via the dedicated HTTP listener, which forwards only the lease-update commands to the peer server.

### Deployment Considerations

The setup is not expected to scale automatically. This example uses four threads for processing DHCP traffic, four threads for listening and handling HA peer HTTP requests, and four threads for sending lease updates to the HA peer. The thread queue used to store incoming DHCP requests is set to 64, but proper testing and benchmarks are required to determine the appropriate values for best performance on the deployment setup.

In this example, there are two hosts running Kea:

- 192.168.1.2 - primary HA server (active, handles all the traffic)

- 192.168.1.3 - secondary HA server (passive, ready to take over if the primary fails)

The network is 192.168.1.0/24. It is assumed that 192.168.1.1 is the default router.

The whole subnet is split into dynamic pools:

- 192.168.1.100 - 192.168.1.199 - this is the dynamic pool. When new devices appear in the network, they are assigned dynamic addresses from this pool.

To deploy this setup, follow the steps provided in the power user home setup with the following distinctions:

1. Install the CA only if the administrator is planning to manage Kea using the RESTful API. Otherwise, the CA is not required for the High Availability Kea server with multi-threading.

2. Alter the following to match the local setup:

   - The paths to `trust-anchor`, `cert-file`, and `key-file` must be set to the respective values corresponding to the deployment machine.

   - The addressing must be updated, if using something other than 192.168.1.0/24. Make sure the CA port configuration (`http-host` and `http-port` in `kea-ca.conf`) is different from the DHCPv4 server configuration (`url` in `hook-libraries/parameters/high-availability/peers` in `kea-dhcp4.conf`). The CA is used to handle only management commands, as the HA module sends lease updates using the dedicated HTTP listener to the peer.

3. Verify the communication between the HA peers by checking the Kea logs.

4. Verify that communication between the hosts works in the opposite direction as well (host-2 can connect to host-1), by repeating step 3 from host-2 using host-1's IP address and port.

5. Install the CA and DHCPv4 on host-2, as in steps 1 and 2. The config file for the standby server is very similar to the one on the primary server, other than the definition of the `this-server-name` field (and possibly the interface names).

### Possible Extensions

This sample configuration is basic but functional. Once it is set up and running, administrators may wish to consider the following changes:

- If using a database, it is also possible to configure TLS for the database backend (for lease, host, configuration backend, or forensic logging). See Database Connectivity for more information.

Some tweaking of these templates may be required to match specific system needs: at a minimum, the lines highlighted in yellow must be adjusted to match the actual deployment.

Server1's Control Agent configuration file:

     1// This is an example of a configuration for Control-Agent (CA) listening
     2// for incoming HTTPS traffic. This is necessary for handling API commands.
     3// For a High Availability setup with multi-threading enabled the CA is not
     4// needed as the peers communicate using a dedicated HTTP listener.
     5
     6// It is expected to run with a standby (the passive) server, which has a very similar
     7// configuration. The only difference is that the location of TLS specific files
     8// depend on the configuration of the particular machine.
     9{
    10    "Control-agent":
    11    {
    12        // We need to specify where the agent should listen to incoming HTTP
    13        // queries.
    14        "http-host": "192.168.1.2",
    15
    16        // TLS trust anchor (Certificate Authority). This is a file name or
    17        // (for OpenSSL only) a directory path.
    18        "trust-anchor": "/usr/lib/kea/CA.pem",
    19
    20        // TLS server certificate file name.
    21        "cert-file": "/usr/lib/kea/ca1_cert.pem",
    22
    23        // TLS server private key file name.
    24        "key-file": "/usr/lib/kea/ca1_key.pem",
    25
    26        // TLS require client certificates flag.
    27        "cert-required": true,
    28
    29        // This specifies the port CA will listen on.
    30        // If enabling HA and multi-threading, the 8000 port is used by the HA
    31        // hook library http listener. When using HA hook library with
    32        // multi-threading to function, make sure the port used by dedicated
    33        // listener is different (e.g. 8001) than the one used by CA. Note
    34        // the commands should still be sent via CA. The dedicated listener
    35        // is specifically for HA updates only.
    36        "http-port": 8001,
    37
    38        "control-sockets":
    39        {
    40            // This is how the Agent can communicate with the DHCPv4 server.
    41            "dhcp4":
    42            {
    43                "comment": "socket to DHCPv4 server",
    44                "socket-type": "unix",
    45                "socket-name": "/tmp/kea4-ctrl-socket"
    46            },
    47
    48            // Location of the DHCPv6 command channel socket.
    49            "dhcp6":
    50            {
    51                "socket-type": "unix",
    52                "socket-name": "/tmp/kea6-ctrl-socket"
    53            },
    54
    55            // Location of the D2 command channel socket.
    56            "d2":
    57            {
    58                "socket-type": "unix",
    59                "socket-name": "/tmp/kea-ddns-ctrl-socket",
    60                "user-context": { "in-use": false }
    61            }
    62        },
    63
    64        // Similar to other Kea components, CA also uses logging.
    65        "loggers": [
    66            {
    67                "name": "kea-ctrl-agent",
    68                "output_options": [
    69                    {
    70                        "output": "/var/log/kea-ctrl-agent.log",
    71
    72                        // Several additional parameters are possible in addition
    73                        // to the typical output. Flush determines whether logger
    74                        // flushes output to a file. Maxsize determines maximum
    75                        // filesize before the file is rotated. maxver
    76                        // specifies the maximum number of rotated files being
    77                        // kept.
    78                        "flush": true,
    79                        "maxsize": 204800,
    80                        "maxver": 4,
    81                        // We use pattern to specify custom log message layout
    82                        "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n"
    83                    }
    84                ],
    85                "severity": "INFO",
    86                "debuglevel": 0 // debug level only applies when severity is set to DEBUG.
    87            }
    88        ]
    89    }
    90}

Server1's DHCPv4 configuration file:

      1// This is an example configuration of the Kea DHCPv4 server 1:
      2//
      3// - uses High Availability hook library and Lease Commands hook library
      4//   to enable High Availability function for the DHCP server. This config
      5//   file is for the primary (the active) server.
      6// - uses memfile, which stores lease data in a local CSV file
      7// - it assumes a single /24 addressing over a link that is directly reachable
      8//   (no DHCP relays)
      9// - there is a handful of IP reservations
     10//
     11// It is expected to run with a standby (the passive) server, which has a very similar
     12// configuration. The only difference is that "this-server-name" must be set to "server2" on the
     13// other server. Also, the interface configuration and location of TLS specific files
     14// depend on the network settings and configuration of the particular machine.
     15
     16{
     17
     18"Dhcp4": {
     19
     20    // Add names of your network interfaces to listen on.
     21    "interfaces-config": {
     22        // The DHCPv4 server listens on this interface. When changing this to
     23        // the actual name of your interface, make sure to also update the
     24        // interface parameter in the subnet definition below.
     25        "interfaces": [ "enp0s8" ]
     26    },
     27
     28    // Control socket is required for communication between the Control
     29    // Agent and the DHCP server. High Availability requires Control Agent
     30    // to be running because lease updates are sent over the RESTful
     31    // API between the HA peers.
     32    "control-socket": {
     33        "socket-type": "unix",
     34        "socket-name": "/tmp/kea4-ctrl-socket"
     35    },
     36
     37    // Multi-threading parameters.
     38    "multi-threading": {
     39        // By default, Kea processes packets on multiple threads if the hardware permits.
     40        "enable-multi-threading": true,
     41
     42        // When multi-threading is enabled, Kea will process packets on a
     43        // number of multiple threads configurable through this option. The
     44        // value must be a positive integer (0 means auto-detect).
     45        "thread-pool-size": 4,
     46
     47        // When multi-threading is enabled, Kea will read packets from the
     48        // interface and append a working item to the thread pool. This
     49        // option configures the maximum number of items that can be queued.
     50        // The value must be a positive integer (0 means unlimited).
     51        "packet-queue-size": 64
     52    },
     53
     54    // Use Memfile lease database backend to store leases in a CSV file.
     55    // Depending on how Kea was compiled, it may also support SQL databases
     56    // (MySQL and/or PostgreSQL). Those database backends require more
     57    // parameters, like name, host and possibly user and password.
     58    // There are dedicated examples for each backend. See Section 7.2.2 "Lease
     59    // Storage" for details.
     60    "lease-database": {
     61        // Memfile is the simplest and easiest backend to use. It's an in-memory
     62        // database with data being written to a CSV file. It is very similar to
     63        // what ISC DHCP does.
     64        "type": "memfile"
     65    },
     66
     67    // Let's configure some global parameters. The home network is not very dynamic
     68    // and there's no shortage of addresses, so no need to recycle aggressively.
     69    "valid-lifetime": 43200, // leases will be valid for 12h
     70    "renew-timer": 21600, // clients should renew every 6h
     71    "rebind-timer": 32400, // clients should start looking for other servers after 9h
     72
     73    // Kea will clean up its database of expired leases once per hour. However, it
     74    // will keep the leases in expired state for 2 days. This greatly increases the
     75    // chances for returning devices to get the same address again. To guarantee that,
     76    // use host reservation.
     77    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
     78    // not 0, when the client sends a release message the lease is expired
     79    // instead of being deleted from lease storage.
     80    "expired-leases-processing": {
     81        "reclaim-timer-wait-time": 3600,
     82        "hold-reclaimed-time": 172800,
     83        "max-reclaim-leases": 0,
     84        "max-reclaim-time": 0
     85    },
     86
     87    // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and
     88    // libdhcp_ha.so. The former handles incoming lease updates from the HA peers.
     89    // The latter implements high availability feature for Kea. Note the library name
     90    // should be the same, but the path is OS specific.
     91    "hooks-libraries": [
     92        // The lease_cmds library must be loaded because HA makes use of it to
     93        // deliver lease updates to the server as well as synchronize the
     94        // lease database after failure.
     95        {
     96            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so"
     97        },
     98
     99        {
    100            // The HA hook library should be loaded.
    101            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
    102            "parameters": {
    103                // Each server should have the same HA configuration, except for the
    104                // "this-server-name" parameter.
    105                "high-availability": [ {
    106                    // This parameter points to this server instance. The respective
    107                    // HA peers must have this parameter set to their own names.
    108                    "this-server-name": "server1",
    109                    // The HA mode is set to hot-standby. In this mode, the active server handles
    110                    // all the traffic. The standby takes over if the primary becomes unavailable.
    111                    "mode": "hot-standby",
    112                    // Heartbeat is to be sent every 10 seconds if no other control
    113                    // commands are transmitted.
    114                    "heartbeat-delay": 10000,
    115                    // Maximum time for partner's response to a heartbeat, after which
    116                    // failure detection is started. This is specified in milliseconds.
    117                    // If we don't hear from the partner in 60 seconds, it's time to
    118                    // start worrying.
    119                    "max-response-delay": 60000,
    120                    // The following parameters control how the server detects the
    121                    // partner's failure. The ACK delay sets the threshold for the
    122                    // 'secs' field of the received discovers. This is specified in
    123                    // milliseconds.
    124                    "max-ack-delay": 5000,
    125                    // This specifies the number of clients which send messages to
    126                    // the partner but appear to not receive any response.
    127                    "max-unacked-clients": 5,
    128                    // This specifies the maximum timeout (in milliseconds) for the server
    129                    // to complete sync. If you have a large deployment (high tens or
    130                    // hundreds of thousands of clients), you may need to increase it
    131                    // further. The default value is 60000ms (60 seconds).
    132                    "sync-timeout": 60000,
    133                    // Multi-threading parameters.
    134                    // To not experience performance degradation when the Kea server is
    135                    // processing packets on multiple threads, the High Availability module
    136                    // must have multi-threading enabled.
    137                    "multi-threading": {
    138                        // Enable High Availability to benefit from multi-threading. Default: true.
    139                        "enable-multi-threading": true,
    140                        // When running in MT mode, the dedicated listener is used to handle
    141                        // lease updates.
    142                        "http-dedicated-listener": true,
    143                        // The number of threads used to handle incoming requests.
    144                        // A value of 0 instructs the server to use the same number of
    145                        // threads that the Kea core is using for DHCP multi-threading.
    146                        "http-listener-threads": 0,
    147                        // The number of threads used to handle outgoing requests.
    148                        // A value of 0 instructs the server to use the same number of
    149                        // threads that the Kea core is using for DHCP multi-threading.
    150                        "http-client-threads": 0
    151                    },
    152                    "peers": [
    153                        // This is the configuration of this server instance.
    154                        {
    155                            "name": "server1",
    156                            // This specifies the URL of this server dedicated HTTP listener.
    157                            // The Control Agent is not needed for the High Availability
    158                            // with multi-threading, but if it is used, it must use
    159                            // different values for "http-host" and "http-port".
    160                            "url": "http://192.168.1.2:8000/",
    161                            // Trust anchor aka certificate authority file or directory.
    162                            "trust-anchor": "/usr/lib/kea/CA.pem",
    163                            // Client certificate file name.
    164                            "cert-file": "/usr/lib/kea/server1_cert.pem",
    165                            // Private key file name.
    166                            "key-file": "/usr/lib/kea/server1_key.pem",
    167                            // Client certificates are required and verified.
    168                            "require-client-certs": true,
    169                            // This server is primary. The other one must be
    170                            // secondary.
    171                            "role": "primary"
    172                        },
    173                        // This is the configuration of the secondary server.
    174                        {
    175                            "name": "server2",
    176                            // This specifies the URL of the other server's dedicated HTTP listener.
    177                            // The Control Agent is not needed for the High Availability
    178                            // with multi-threading, but if it is used, it must use
    179                            // different values for "http-host" and "http-port".
    180                            "url": "http://192.168.1.3:8000/",
    181                            // Trust anchor aka certificate authority file or directory.
    182                            "trust-anchor": "/usr/lib/kea/CA.pem",
    183                            // Client certificate file name.
    184                            "cert-file": "/usr/lib/kea/server2_cert.pem",
    185                            // Private key file name.
    186                            "key-file": "/usr/lib/kea/server2_key.pem",
    187                            // Client certificates are required and verified.
    188                            "require-client-certs": true,
    189                            // The other server is secondary. This one must be
    190                            // primary.
    191                            "role": "standby"
    192                        }
    193                    ]
    194                } ]
    195            }
    196        }
    197    ],
    198
    199    // This example contains a single subnet declaration.
    200    "subnet4": [
    201        {
    202            // Subnet prefix.
    203            "subnet": "192.168.1.0/24",
    204
    205            // There are no relays in this network, so we need to tell Kea that this subnet
    206            // is reachable directly via the specified interface.
    207            "interface": "enp0s8",
    208
    209            // Specify a dynamic address pool.
    210            "pools": [
    211                {
    212                    "pool": "192.168.1.100-192.168.1.199"
    213                }
    214            ]
    215        }
    216    ],
    217
    218    // Logging configuration starts here.
    219    "loggers": [
    220    {
    221        // This section affects kea-dhcp4, which is the base logger for DHCPv4 component. It tells
    222        // DHCPv4 server to write all log messages (on severity INFO or higher) to a file. The file
    223        // will be rotated once it grows to 2MB and up to 4 files will be kept. The debuglevel
    224        // (range 0 to 99) is used only when logging on DEBUG level.
    225        "name": "kea-dhcp4",
    226        "output_options": [
    227            {
    228                "output": "/var/log/kea-dhcp4.log",
    229                "maxsize": 2048000,
    230                "maxver": 4
    231            }
    232        ],
    233        "severity": "INFO",
    234        "debuglevel": 0
    235    }
    236  ]
    237}
    238}

Server2's Control Agent configuration file:

     1// This is an example of a configuration for Control-Agent (CA) listening
     2// for incoming HTTPS traffic. This is necessary for handling API commands.
     3// For a High Availability setup with multi-threading enabled the CA is not
     4// needed as the peers communicate using a dedicated HTTP listener.
     5
     6// It is expected to run with a primary (the active) server, which has a very similar
     7// configuration. The only difference is that the location of TLS specific files
     8// depend on the configuration of the particular machine.
     9{
    10    "Control-agent":
    11    {
    12        // We need to specify where the agent should listen to incoming HTTP
    13        // queries.
    14        "http-host": "192.168.1.3",
    15
    16        // TLS trust anchor (Certificate Authority). This is a file name or
    17        // (for OpenSSL only) a directory path.
    18        "trust-anchor": "/usr/lib/kea/CA.pem",
    19
    20        // TLS server certificate file name.
    21        "cert-file": "/usr/lib/kea/ca2_cert.pem",
    22
    23        // TLS server private key file name.
    24        "key-file": "/usr/lib/kea/ca2_key.pem",
    25
    26        // TLS require client certificates flag.
    27        "cert-required": true,
    28
    29        // This specifies the port CA will listen on.
    30        // If enabling HA and multi-threading, the 8000 port is used by the HA
    31        // hook library http listener. When using HA hook library with
    32        // multi-threading to function, make sure the port used by dedicated
    33        // listener is different (e.g. 8001) than the one used by CA. Note
    34        // the commands should still be sent via CA. The dedicated listener
    35        // is specifically for HA updates only.
    36        "http-port": 8001,
    37
    38        "control-sockets":
    39        {
    40            // This is how the Agent can communicate with the DHCPv4 server.
    41            "dhcp4":
    42            {
    43                "comment": "socket to DHCPv4 server",
    44                "socket-type": "unix",
    45                "socket-name": "/tmp/kea4-ctrl-socket"
    46            },
    47
    48            // Location of the DHCPv6 command channel socket.
    49            "dhcp6":
    50            {
    51                "socket-type": "unix",
    52                "socket-name": "/tmp/kea6-ctrl-socket"
    53            },
    54
    55            // Location of the D2 command channel socket.
    56            "d2":
    57            {
    58                "socket-type": "unix",
    59                "socket-name": "/tmp/kea-ddns-ctrl-socket",
    60                "user-context": { "in-use": false }
    61            }
    62        },
    63
    64        // Similar to other Kea components, CA also uses logging.
    65        "loggers": [
    66            {
    67                "name": "kea-ctrl-agent",
    68                "output_options": [
    69                    {
    70                        "output": "/var/log/kea-ctrl-agent.log",
    71
    72                        // Several additional parameters are possible in addition
    73                        // to the typical output. Flush determines whether logger
    74                        // flushes output to a file. Maxsize determines maximum
    75                        // filesize before the file is rotated. maxver
    76                        // specifies the maximum number of rotated files being
    77                        // kept.
    78                        "flush": true,
    79                        "maxsize": 204800,
    80                        "maxver": 4,
    81                        // We use pattern to specify custom log message layout
    82                        "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n"
    83                    }
    84                ],
    85                "severity": "INFO",
    86                "debuglevel": 0 // debug level only applies when severity is set to DEBUG.
    87            }
    88        ]
    89    }
    90}

Server2's DHCPv4 configuration file:

      1// This is an example configuration of the Kea DHCPv4 server 2:
      2//
      3// - uses High Availability hook library and Lease Commands hook library
      4//   to enable High Availability function for the DHCP server. This config
      5//   file is for the secondary (the standby) server.
      6// - uses memfile, which stores lease data in a local CSV file
      7// - it assumes a single /24 addressing over a link that is directly reachable
      8//   (no DHCP relays)
      9// - there is a handful of IP reservations
     10//
     11// It is expected to run with a primary (the active) server, which has a very similar
     12// configuration. The only difference is that "this-server-name" must be set to "server2" on the
     13// other server. Also, the interface configuration and location of TLS specific files
     14// depend on the network settings and configuration of the particular machine.
     15
     16{
     17
     18"Dhcp4": {
     19
     20    // Add names of your network interfaces to listen on.
     21    "interfaces-config": {
     22        // The DHCPv4 server listens on this interface. When changing this to
     23        // the actual name of your interface, make sure to also update the
     24        // interface parameter in the subnet definition below.
     25        "interfaces": [ "enp0s8" ]
     26    },
     27
     28    // Control socket is required for communication between the Control
     29    // Agent and the DHCP server. High Availability requires Control Agent
     30    // to be running because lease updates are sent over the RESTful
     31    // API between the HA peers.
     32    "control-socket": {
     33        "socket-type": "unix",
     34        "socket-name": "/tmp/kea4-ctrl-socket"
     35    },
     36
     37    // Multi-threading parameters.
     38    "multi-threading": {
     39        // By default, Kea processes packets on multiple threads if the hardware permits.
     40        "enable-multi-threading": true,
     41
     42        // When multi-threading is enabled, Kea will process packets on a
     43        // number of multiple threads configurable through this option. The
     44        // value must be a positive integer (0 means auto-detect).
     45        "thread-pool-size": 4,
     46
     47        // When multi-threading is enabled, Kea will read packets from the
     48        // interface and append a working item to the thread pool. This
     49        // option configures the maximum number of items that can be queued.
     50        // The value must be a positive integer (0 means unlimited).
     51        "packet-queue-size": 64
     52    },
     53
     54    // Use Memfile lease database backend to store leases in a CSV file.
     55    // Depending on how Kea was compiled, it may also support SQL databases
     56    // (MySQL and/or PostgreSQL). Those database backends require more
     57    // parameters, like name, host and possibly user and password.
     58    // There are dedicated examples for each backend. See Section 7.2.2 "Lease
     59    // Storage" for details.
     60    "lease-database": {
     61        // Memfile is the simplest and easiest backend to use. It's an in-memory
     62        // database with data being written to a CSV file. It is very similar to
     63        // what ISC DHCP does.
     64        "type": "memfile"
     65    },
     66
     67    // Let's configure some global parameters. The home network is not very dynamic
     68    // and there's no shortage of addresses, so no need to recycle aggressively.
     69    "valid-lifetime": 43200, // leases will be valid for 12h
     70    "renew-timer": 21600, // clients should renew every 6h
     71    "rebind-timer": 32400, // clients should start looking for other servers after 9h
     72
     73    // Kea will clean up its database of expired leases once per hour. However, it
     74    // will keep the leases in expired state for 2 days. This greatly increases the
     75    // chances for returning devices to get the same address again. To guarantee that,
     76    // use host reservation.
     77    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
     78    // not 0, when the client sends a release message the lease is expired
     79    // instead of being deleted from lease storage.
     80    "expired-leases-processing": {
     81        "reclaim-timer-wait-time": 3600,
     82        "hold-reclaimed-time": 172800,
     83        "max-reclaim-leases": 0,
     84        "max-reclaim-time": 0
     85    },
     86
     87    // HA requires two hook libraries to be loaded: libdhcp_lease_cmds.so and
     88    // libdhcp_ha.so. The former handles incoming lease updates from the HA peers.
     89    // The latter implements high availability feature for Kea. Note the library name
     90    // should be the same, but the path is OS specific.
     91    "hooks-libraries": [
     92        // The lease_cmds library must be loaded because HA makes use of it to
     93        // deliver lease updates to the server as well as synchronize the
     94        // lease database after failure.
     95        {
     96            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so"
     97        },
     98
     99        {
    100            // The HA hook library should be loaded.
    101            "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so",
    102            "parameters": {
    103                // Each server should have the same HA configuration, except for the
    104                // "this-server-name" parameter.
    105                "high-availability": [ {
    106                    // This parameter points to this server instance. The respective
    107                    // HA peers must have this parameter set to their own names.
    108                    "this-server-name": "server2",
    109                    // The HA mode is set to hot-standby. In this mode, the active server handles
    110                    // all the traffic. The standby takes over if the primary becomes unavailable.
    111                    "mode": "hot-standby",
    112                    // Heartbeat is to be sent every 10 seconds if no other control
    113                    // commands are transmitted.
    114                    "heartbeat-delay": 10000,
    115                    // Maximum time for partner's response to a heartbeat, after which
    116                    // failure detection is started. This is specified in milliseconds.
    117                    // If we don't hear from the partner in 60 seconds, it's time to
    118                    // start worrying.
    119                    "max-response-delay": 60000,
    120                    // The following parameters control how the server detects the
    121                    // partner's failure. The ACK delay sets the threshold for the
    122                    // 'secs' field of the received discovers. This is specified in
    123                    // milliseconds.
    124                    "max-ack-delay": 5000,
    125                    // This specifies the number of clients which send messages to
    126                    // the partner but appear to not receive any response.
    127                    "max-unacked-clients": 5,
    128                    // This specifies the maximum timeout (in milliseconds) for the server
    129                    // to complete sync. If you have a large deployment (high tens or
    130                    // hundreds of thousands of clients), you may need to increase it
    131                    // further. The default value is 60000ms (60 seconds).
    132                    "sync-timeout": 60000,
    133                    // Multi-threading parameters.
    134                    // To not experience performance degradation when the Kea server is
    135                    // processing packets on multiple threads, the High Availability module
    136                    // must have multi-threading enabled.
    137                    "multi-threading": {
    138                        // Enable High Availability to benefit from multi-threading. Default: true.
    139                        "enable-multi-threading": true,
    140                        // When running in MT mode, the dedicated listener is used to handle
    141                        // lease updates.
    142                        "http-dedicated-listener": true,
    143                        // The number of threads used to handle incoming requests.
    144                        // A value of 0 instructs the server to use the same number of
    145                        // threads that the Kea core is using for DHCP multi-threading.
    146                        "http-listener-threads": 0,
    147                        // The number of threads used to handle outgoing requests.
    148                        // A value of 0 instructs the server to use the same number of
    149                        // threads that the Kea core is using for DHCP multi-threading.
    150                        "http-client-threads": 0
    151                    },
    152                    "peers": [
    153                        // This is the configuration of the primary server.
    154                        {
    155                            "name": "server1",
    156                            // This specifies the URL of the other server's dedicated HTTP listener.
    157                            // The Control Agent is not needed for the High Availability
    158                            // with multi-threading, but if it is used, it must use
    159                            // different values for "http-host" and "http-port".
    160                            "url": "http://192.168.1.2:8000/",
    161                            // Trust anchor aka certificate authority file or directory.
    162                            "trust-anchor": "/usr/lib/kea/CA.pem",
    163                            // Client certificate file name.
    164                            "cert-file": "/usr/lib/kea/server1_cert.pem",
    165                            // Private key file name.
    166                            "key-file": "/usr/lib/kea/server1_key.pem",
    167                            // Client certificates are required and verified.
    168                            "require-client-certs": true,
    169                            // The other server is primary. This one must be
    170                            // secondary.
    171                            "role": "primary"
    172                        },
    173                        // This is the configuration of this server instance.
    174                        {
    175                            "name": "server2",
    176                            // This specifies the URL of this server dedicated HTTP listener.
    177                            // The Control Agent is not needed for the High Availability
    178                            // with multi-threading, but if it is used, it must use
    179                            // different values for "http-host" and "http-port".
    180                            "url": "http://192.168.1.3:8000/",
    181                            // Trust anchor aka certificate authority file or directory.
    182                            "trust-anchor": "/usr/lib/kea/CA.pem",
    183                            // Client certificate file name.
    184                            "cert-file": "/usr/lib/kea/server2_cert.pem",
    185                            // Private key file name.
    186                            "key-file": "/usr/lib/kea/server2_key.pem",
    187                            // Client certificates are required and verified.
    188                            "require-client-certs": true,
    189                            // This server is secondary. The other one must be
    190                            // primary.
    191                            "role": "standby"
    192                        }
    193                    ]
    194                } ]
    195            }
    196        }
    197    ],
    198
    199    // This example contains a single subnet declaration.
    200    "subnet4": [
    201        {
    202            // Subnet prefix.
    203            "subnet": "192.168.1.0/24",
    204
    205            // There are no relays in this network, so we need to tell Kea that this subnet
    206            // is reachable directly via the specified interface.
    207            "interface": "enp0s8",
    208
    209            // Specify a dynamic address pool.
    210            "pools": [
    211                {
    212                    "pool": "192.168.1.100-192.168.1.199"
    213                }
    214            ]
    215        }
    216    ],
    217
    218    // Logging configuration starts here.
    219    "loggers": [
    220    {
    221        // This section affects kea-dhcp4, which is the base logger for DHCPv4 component. It tells
    222        // DHCPv4 server to write all log messages (on severity INFO or higher) to a file. The file
    223        // will be rotated once it grows to 2MB and up to 4 files will be kept. The debuglevel
    224        // (range 0 to 99) is used only when logging on DEBUG level.
    225        "name": "kea-dhcp4",
    226        "output_options": [
    227            {
    228                "output": "/var/log/kea-dhcp4.log",
    229                "maxsize": 2048000,
    230                "maxver": 4
    231            }
    232        ],
    233        "severity": "INFO",
    234        "debuglevel": 0
    235    }
    236  ]
    237}
    238}