From: Razvan Becheriu Date: Sat, 20 Aug 2022 16:36:07 +0000 (+0300) Subject: [#2441] added HA+MT and HA+MT+TLS examples X-Git-Tag: Kea-2.3.0~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=05366c117a28ff6072fe1d8cd7532fa219c0bb27;p=thirdparty%2Fkea.git [#2441] added HA+MT and HA+MT+TLS examples --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 94386a5e18..18b3b59235 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -26,7 +26,8 @@ nobase_dist_doc_DATA += examples/kea4/comments.json nobase_dist_doc_DATA += examples/kea4/config-backend.json nobase_dist_doc_DATA += examples/kea4/dhcpv4-over-dhcpv6.json nobase_dist_doc_DATA += examples/kea4/global-reservations.json -nobase_dist_doc_DATA += examples/kea4/ha-load-balancing-primary.json +nobase_dist_doc_DATA += examples/kea4/ha-load-balancing-server1-mt-with-tls.json +nobase_dist_doc_DATA += examples/kea4/ha-load-balancing-server2-mt.json nobase_dist_doc_DATA += examples/kea4/hooks.json nobase_dist_doc_DATA += examples/kea4/hooks-radius.json nobase_dist_doc_DATA += examples/kea4/leases-expiration.json @@ -52,7 +53,8 @@ nobase_dist_doc_DATA += examples/kea6/config-backend.json nobase_dist_doc_DATA += examples/kea6/dhcpv4-over-dhcpv6.json nobase_dist_doc_DATA += examples/kea6/duid.json nobase_dist_doc_DATA += examples/kea6/global-reservations.json -nobase_dist_doc_DATA += examples/kea6/ha-hot-standby.json +nobase_dist_doc_DATA += examples/kea6/ha-hot-standby-server1-with-tls.json +nobase_dist_doc_DATA += examples/kea6/ha-hot-standby-server2.json nobase_dist_doc_DATA += examples/kea6/hooks.json nobase_dist_doc_DATA += examples/kea6/iPXE.json nobase_dist_doc_DATA += examples/kea6/leases-expiration.json @@ -83,6 +85,12 @@ nobase_dist_doc_DATA += examples/template-power-user-home/kea-ca-2.conf nobase_dist_doc_DATA += examples/template-power-user-home/kea-dhcp4-1.conf nobase_dist_doc_DATA += examples/template-power-user-home/kea-dhcp4-2.conf +nobase_dist_doc_DATA += examples/template-ha-mt-tls/info.md +nobase_dist_doc_DATA += examples/template-ha-mt-tls/kea-ca-1.conf +nobase_dist_doc_DATA += examples/template-ha-mt-tls/kea-ca-2.conf +nobase_dist_doc_DATA += examples/template-ha-mt-tls/kea-dhcp4-1.conf +nobase_dist_doc_DATA += examples/template-ha-mt-tls/kea-dhcp4-2.conf + # If there's any new parameter added for any grammar in one of the daemons, someone should go through # this procedure: # diff --git a/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json b/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json new file mode 100644 index 0000000000..951ee2d1b0 --- /dev/null +++ b/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json @@ -0,0 +1,268 @@ +// 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 and location of TLS +// specific files depend on the network settings and configuration of the +// particular machine. +// +// The servers using this configuration work in load balancing mode. +{ + +// DHCPv4 configuration starts here. +"Dhcp4": { + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv4 server listens on this interface. + "interfaces": [ "eth0" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability with MT does not require + // Control Agent to be running because lease updates are sent over the + // RESTful API between the HA peers using the server dedicated listener. + // The Control Agent is used only to handle user commands. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Multi-threading parameters. + "multi-threading": { + // To enable multi-threading, this option can be set to 'true' value. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + "packet-queue-size": 64 + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // Storage" for details. + "lease-database": { + // Memfile is the simplest and easiest backend to use. It's an in-memory + "type": "memfile" + }, + + // Client classes will associate address pools with certain servers taking + // part in providing High Availability. + "client-classes": [ + // phones class + { + "name": "phones", + "test": "substring(option[60].hex,0,6) == 'Aastra'" + }, + // laptops are everything but phones. + { + "name": "laptops", + "test": "not member('phones')" + }, + // Some phones will be handled by server1. Whether the HA_server1 + // or HA_server2 is assigned for the client is a matter of load + // balancing performed by the HA hooks library. + { + "name": "phones_server1", + "test": "member('phones') and member('HA_server1')" + }, + // Some phones will be handled by server2. + { + "name": "phones_server2", + "test": "member('phones') and member('HA_server2')" + }, + // Some laptops will be handled by server1. + { + "name": "laptops_server1", + "test": "member('laptops') and member('HA_server1')" + }, + // Some laptops will be handled by server2. + { + "name": "laptops_server2", + "test": "member('laptops') and member('HA_server2')" + } + ], + + // 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. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hooks library should be loaded. + "library": "/opt/lib/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 + // servers share the traffic (50/50). + "mode": "load-balancing", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "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": 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 + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "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 + // further. The default value is 60000ms (60 seconds). + "sync-timeout": 60000, + "multi-threading": { + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incomming requests. + "http-listener-threads": 4, + // The number of threads used to handle outgoing requests. + "http-client-threads": 4 + }, + "peers": [ + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of our server instance. The + // Control Agent is not required run along with our DHCPv4 server + // instance. The "http-host" and "http-port" values must be + // set to different values then the Control Agent. + "url": "http://192.168.56.33:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server1_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server1_key.pem", + // 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 not required + // to run on the partner's machine. The "http-host" and + // "http-port" values must be set to different values then the + // Control Agent. + "url": "http://192.168.56.66:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server2_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server2_key.pem", + // The partner is a secondary. Our is primary. + "role": "secondary" + } + ] + } ] + } + } + ], + + // This example contains a single subnet declaration. + "subnet4": [ + { + // Subnet prefix. + "subnet": "192.0.3.0/24", + + // Specify four address pools. + "pools": [ + { + "pool": "192.0.3.100 - 192.0.3.125", + "client-class": "phones_server1" + }, + { + "pool": "192.0.3.126 - 192.0.3.150", + "client-class": "laptops_server1" + }, + { + "pool": "192.0.3.200 - 192.0.3.225", + "client-class": "phones_server2" + }, + { + "pool": "192.0.3.226 - 192.0.3.250", + "client-class": "laptops_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. + "option-data": [ + { + // For each IPv4 subnet you most likely need to specify at + // least one router. + "name": "routers", + "data": "192.0.3.1" + } + ], + + // This subnet will be selected for queries coming from the following + // IP address. + "relay": { "ip-address": "192.168.56.1" } + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. + "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. + "name": "kea-dhcp4", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 0 + }, + { + // This section specifies configuration of the HA hooks library specific + // logger. + "name": "kea-dhcp4.ha-hooks", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 99 + } + ] +} +} diff --git a/doc/examples/kea4/ha-load-balancing-primary.json b/doc/examples/kea4/ha-load-balancing-server2-mt.json similarity index 63% rename from doc/examples/kea4/ha-load-balancing-primary.json rename to doc/examples/kea4/ha-load-balancing-server2-mt.json index ae730e5926..a445c7672c 100644 --- a/doc/examples/kea4/ha-load-balancing-primary.json +++ b/doc/examples/kea4/ha-load-balancing-server2-mt.json @@ -2,7 +2,7 @@ // 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" +// The only difference is that "this-server-name" must be set to "server1" // on this other server. Also, the interface configuration depends on the // network settings of the particular machine. // @@ -18,14 +18,30 @@ }, // Control socket is required for communication between the Control - // Agent and the DHCP server. High Availability requires Control Agent - // to be running because lease updates are sent over the RESTful - // API between the HA peers. + // Agent and the DHCP server. High Availability with MT does not require + // Control Agent to be running because lease updates are sent over the + // RESTful API between the HA peers using the server dedicated listener. + // The Control Agent is used only to handle user commands. "control-socket": { "socket-type": "unix", "socket-name": "/tmp/kea4-ctrl-socket" }, + // Multi-threading parameters. + "multi-threading": { + // To enable multi-threading, this option can be set to 'true' value. + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + "packet-queue-size": 64 + }, + // Use Memfile lease database backend to store leases in a CSV file. // Depending on how Kea was compiled, it may also support SQL databases // (MySQL and/or PostgreSQL). Those database backends require more @@ -74,7 +90,6 @@ } ], - // 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. @@ -96,7 +111,7 @@ "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", + "this-server-name": "server2", // The HA mode is set to load-balancing. In this mode, the active // servers share the traffic (50/50). "mode": "load-balancing", @@ -119,32 +134,43 @@ // hundreds of thausands of clients), you may need to increase it // further. The default value is 60000ms (60 seconds). "sync-timeout": 60000, + "multi-threading": { + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incomming requests. + "http-listener-threads": 4, + // The number of threads used to handle outgoing requests. + "http-client-threads": 4 + }, "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.56.33: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.56.66:8000/", - // The partner is a secondary. Our is primary. - "role": "secondary" - } - ] - } ] + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of our server instance. The + // Control Agent is not required run along with our DHCPv4 server + // instance. The "http-host" and "http-port" values must be + // set to different values then the Control Agent. + "url": "http://192.168.56.33: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 not required + // to run on the partner's machine. The "http-host" and + // "http-port" values must be set to different values then the + // Control Agent. + "url": "http://192.168.56.66:8000/", + // The partner is a secondary. Our is primary. + "role": "secondary" + } + ] + } ] } } ], @@ -194,32 +220,36 @@ } ], - // Logging configuration starts here. +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. "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. - "name": "kea-dhcp4", - "output_options": [ - { - "output": "stdout" - - } - ], - "severity": "INFO" - }, - { - // This section specifies configuration of the HA hooks library specific - // logger. - "name": "kea-dhcp4.ha-hooks", - "output_options": [ - { - "output": "stdout" - } - ], - "severity": "INFO" - } - ] + { + // 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. + "name": "kea-dhcp4", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 0 + }, + { + // This section specifies configuration of the HA hooks library specific + // logger. + "name": "kea-dhcp4.ha-hooks", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 99 + } + ] } } diff --git a/doc/examples/kea6/ha-hot-standby-server1-with-tls.json b/doc/examples/kea6/ha-hot-standby-server1-with-tls.json new file mode 100644 index 0000000000..ac5c63eb74 --- /dev/null +++ b/doc/examples/kea6/ha-hot-standby-server1-with-tls.json @@ -0,0 +1,164 @@ +// This is an example configuration of the Kea DHCPv6 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 and location of TLS +// specific files depend on the network settings and configuration of the +// particular machine. +// +// The servers using this configuration work in hot standby mode. +{ + +// DHCPv6 configuration starts here. +"Dhcp6": { + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv6 server listens on this interface. + "interfaces": [ "eth0" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability requires Control Agent + // to be running because lease updates are sent over the RESTful + // API between the HA peers. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea6-ctrl-socket" + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // Storage" for details. + "lease-database": { + // Memfile is the simplest and easiest backend to use. It's an in-memory + "type": "memfile" + }, + + // 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. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hooks library should be loaded. + "library": "/opt/lib/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 hot-standby. This server will receive lease + // updates from the primary. The primary will be responding to all + // DHCP queries. + "mode": "hot-standby", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "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": 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 + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "max-unacked-clients": 5, + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server_key.pem", + "peers": [ + // This is the configuration of our HA peer. + { + "name": "server1", + // 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.56.33:8000/", + // The partner is primary. Our is standby. + "role": "primary" + }, + // This is the configuration of this server instance. + { + "name": "server2", + // This specifies the URL of our server instance. The + // Control Agent must run along with our DHCPv6 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. + "url": "http://192.168.56.66:8000/", + // Out server is standby. The partner is primary. + "role": "standby" + } + ] + } ] + } + } + ], + + // The following list defines subnets. Each subnet consists of at + // least subnet and pool entries. + "subnet6": [ + { + "subnet": "2001:db8:1::/64", + + "pools": [ + { + "pool": "2001:db8:1::100 - 2001:db8:1::250" + } + ], + + "interface": "eth0" + } + ], + +// The following configures logging. It assumes that messages with at +// least informational level (info, warn, error and fatal) should be +// logged to stdout. Alternatively, you can specify stderr here, a filename +// or 'syslog', which will store output messages via syslog. + "loggers": [ + { + // This section affects kea-dhcp6, which is the base logger for DHCPv6 + // component. It tells DHCPv6 server to write all log messages (on + // severity INFO or more) to a file. + "name": "kea-dhcp6", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 0 + }, + { + // This section specifies configuration of the HA hooks library specific + // logger. + "name": "kea-dhcp6.ha-hooks", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO", + "debuglevel": 99 + } + ] +} +} diff --git a/doc/examples/kea6/ha-hot-standby.json b/doc/examples/kea6/ha-hot-standby-server2.json similarity index 68% rename from doc/examples/kea6/ha-hot-standby.json rename to doc/examples/kea6/ha-hot-standby-server2.json index a0752d5e4d..1b9d3dde00 100644 --- a/doc/examples/kea6/ha-hot-standby.json +++ b/doc/examples/kea6/ha-hot-standby-server2.json @@ -6,12 +6,14 @@ // on this other server. Also, the interface configuration depends on the // network settings of the particular machine. // -// The servers using this configuration work in hot standby mode.. -{ "Dhcp6": - +// The servers using this configuration work in hot standby mode. { -// Kea is told to listen on eth0 interface only. + +// DHCPv6 configuration starts here. +"Dhcp6": { + // Add names of your network interfaces to listen on. "interfaces-config": { + // The DHCPv6 server listens on this interface. "interfaces": [ "eth0" ] }, @@ -31,7 +33,7 @@ // There are dedicated examples for each backend. See Section 7.2.2 "Lease // Storage" for details. "lease-database": { - // Memfile is the simplest and easiest backend to use. It's a in-memory + // Memfile is the simplest and easiest backend to use. It's an in-memory "type": "memfile" }, @@ -39,6 +41,9 @@ // libdhcp_ha.so. The former handles incoming lease updates from the HA peers. // The latter implements high availability feature for Kea. "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. { "library": "/opt/lib/kea/hooks/libdhcp_lease_cmds.so", "parameters": { } @@ -73,30 +78,30 @@ // the partner but appear to not receive any response. "max-unacked-clients": 5, "peers": [ - // This is the configuration of our HA peer. - { - "name": "server1", - // 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.56.33:8000/", - // Th partner is primary. Our is standby. - "role": "primary" - }, - // This is the configuration of this server instance. - { - "name": "server2", - // This specifies the URL of our server instance. The - // Control Agent must run along with our DHCPv6 server - // instance and the "http-host" and "http-port" must be - // set to the corresponding values. - "url": "http://192.168.56.66:8000/", - // Out server is standby. The partner is primary. - "role": "standby" - } - ] - } ] + // This is the configuration of our HA peer. + { + "name": "server1", + // 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.56.33:8000/", + // The partner is primary. Our is standby. + "role": "primary" + }, + // This is the configuration of this server instance. + { + "name": "server2", + // This specifies the URL of our server instance. The + // Control Agent must run along with our DHCPv6 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. + "url": "http://192.168.56.66:8000/", + // Out server is standby. The partner is primary. + "role": "standby" + } + ] + } ] } } ], @@ -105,17 +110,17 @@ // least subnet and pool entries. "subnet6": [ { - "subnet": "2001:db8:1::/64", + "subnet": "2001:db8:1::/64", - "pools": [ + "pools": [ { "pool": "2001:db8:1::100 - 2001:db8:1::250" } - ], + ], "interface": "eth0" - } - ], + } + ], // The following configures logging. It assumes that messages with at // least informational level (info, warn, error and fatal) should be @@ -123,19 +128,22 @@ // or 'syslog', which will store output messages via syslog. "loggers": [ { + // This section affects kea-dhcp6, which is the base logger for DHCPv6 + // component. It tells DHCPv6 server to write all log messages (on + // severity INFO or more) to a file. "name": "kea-dhcp6", "output_options": [ { "output": "stdout" } ], - "debuglevel": 0, - "severity": "INFO" + "severity": "INFO", + "debuglevel": 0 }, { // This section specifies configuration of the HA hooks library specific // logger. - "name": "kea-dhcp4.ha-hooks", + "name": "kea-dhcp6.ha-hooks", "output_options": [ { "output": "stdout" @@ -146,5 +154,4 @@ } ] } - } diff --git a/doc/examples/template-ha-mt-tls/info.md b/doc/examples/template-ha-mt-tls/info.md new file mode 100644 index 0000000000..0215702013 --- /dev/null +++ b/doc/examples/template-ha-mt-tls/info.md @@ -0,0 +1,87 @@ +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 with multi-threading. +- the machines running Kea with multi-threading have at least 4 CPUs. +- 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 it's +own dedicated HTTP listener to communicate with the peer. However it can still +be used to handle user commands. + +.. code-block:: none + + +-host-1-+ +-host-2-+ + | | | | + | CA | | CA | ===== - HTTPS connection + | # | | # | + | # | | # | ##### - UNIX socket + | # | | # | + | DHCPv4 ========= DHCPv4 | + | | | | + +--------+ +--------+ + +The CA on host-1 and CA on host-2 both listen on port 8001, and the server dedicated HTTP +listener uses port 8000. The DHCP servers communicate with each other via the dedicated HTTP +listener, which forward only the lease updates commands to the peer server. + +Deployment Considerations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The setup is not expected to scale automatically. This example uses 4 thread for +processing DHCP traffic, 4 threads for listening and handling HA peer HTTP requests +and 4 threads for sending lease updates to the HA peer. The thread queue used to +store incomming HDCP requests is set to 64, but specific values for better +performance must be determined on the deployment setup by doing proper testing +and benchmarks. + +The assumption is that there are two hosts that are running the Kea setup: + +- 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 CA only if the administrator is planning to manage Kea using RESTful API. + Otherwise, the High Availablility Kea server with multi-threading does not require CA to run. + +2. Alter the following to match the local setup: + + - the paths to ``trust-anchor``, ``cert-file``, ``key-file`` must be set to the + respective values corresponding to the deployment machine. + + - 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``) is different than 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 +~~~~~~~~~~~~~~~~~~~ + +The proposed configuration is somewhat basic, but functional. Once it is set up and running, administrators +may wish to consider the following changes: + +- if using a database, configuring TLS for the database backend (either for lease, host, configuration backend or forensic logging) + is also possible. See :ref:`database-connectivity` for more information. diff --git a/doc/examples/template-ha-mt-tls/kea-ca-1.conf b/doc/examples/template-ha-mt-tls/kea-ca-1.conf new file mode 100644 index 0000000000..127e786924 --- /dev/null +++ b/doc/examples/template-ha-mt-tls/kea-ca-1.conf @@ -0,0 +1,90 @@ +// This is an example of a configuration for Control-Agent (CA) listening +// for incoming HTTPS traffic. This is necessary for handling API commands. +// For a High Availability setup with multi-threading enabled the CA is not +// needed as the peers communicate using a dedicated HTTP listener. + +// It is expected to run with a standby (the passive) server, which has a very similar +// configuration. The only difference is that the location of TLS specific files +// depend on the configuration of the particular machine. +{ + "Control-agent": + { + // We need to specify where the agent should listen to incoming HTTP + // queries. + "http-host": "192.168.1.2", + + // TLS trust anchor (Certificate Authority). This is a file name or + // (for OpenSSL only) a directory path. + "trust-anchor": "/usr/lib/kea/CA.pem", + + // TLS server certificate file name. + "cert-file": "/usr/lib/kea/ca1_cert.pem", + + // TLS server private key file name. + "key-file": "/usr/lib/kea/ca1_key.pem", + + // TLS require client certificates flag. + "cert-required": true, + + // This specifies the port CA will listen on. + // If enabling HA and multi-threading, the 8000 port is used by the HA + // hook library http listener. When using HA hook library with + // multi-threading to function, make sure the port used by dedicated + // listener is different (e.g. 8001) than the one used by CA. Note + // the commands should still be sent via CA. The dedicated listener + // is specifically for HA updates only. + "http-port": 8001, + + "control-sockets": + { + // This is how the Agent can communicate with the DHCPv4 server. + "dhcp4": + { + "comment": "socket to DHCP4 server", + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Location of the DHCPv6 command channel socket. + "dhcp6": + { + "socket-type": "unix", + "socket-name": "/tmp/kea6-ctrl-socket" + }, + + // Location of the D2 command channel socket. + "d2": + { + "socket-type": "unix", + "socket-name": "/tmp/kea-ddns-ctrl-socket", + "user-context": { "in-use": false } + } + }, + + // Similar to other Kea components, CA also uses logging. + "loggers": [ + { + "name": "kea-ctrl-agent", + "output_options": [ + { + "output": "/var/log/kea-ctrl-agent.log", + + // Several additional parameters are possible in addition + // to the typical output. Flush determines whether logger + // flushes output to a file. Maxsize determines maximum + // filesize before the file is being rotated. maxver + // specifies the maximum number of rotated files being + // kept. + "flush": true, + "maxsize": 204800, + "maxver": 4, + // We use pattern to specify custom log message layout + "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n" + } + ], + "severity": "INFO", + "debuglevel": 0 // debug level only applies when severity is set to DEBUG. + } + ] + } +} diff --git a/doc/examples/template-ha-mt-tls/kea-ca-2.conf b/doc/examples/template-ha-mt-tls/kea-ca-2.conf new file mode 100644 index 0000000000..c7e42b0299 --- /dev/null +++ b/doc/examples/template-ha-mt-tls/kea-ca-2.conf @@ -0,0 +1,90 @@ +// This is an example of a configuration for Control-Agent (CA) listening +// for incoming HTTPS traffic. This is necessary for handling API commands. +// For a High Availability setup with multi-threading enabled the CA is not +// needed as the peers communicate using a dedicated HTTP listener. + +// It is expected to run with a primary (the active) server, which has a very similar +// configuration. The only difference is that the location of TLS specific files +// depend on the configuration of the particular machine. +{ + "Control-agent": + { + // We need to specify where the agent should listen to incoming HTTP + // queries. + "http-host": "192.168.1.3", + + // TLS trust anchor (Certificate Authority). This is a file name or + // (for OpenSSL only) a directory path. + "trust-anchor": "/usr/lib/kea/CA.pem", + + // TLS server certificate file name. + "cert-file": "/usr/lib/kea/ca2_cert.pem", + + // TLS server private key file name. + "key-file": "/usr/lib/kea/ca2_key.pem", + + // TLS require client certificates flag. + "cert-required": true, + + // This specifies the port CA will listen on. + // If enabling HA and multi-threading, the 8000 port is used by the HA + // hook library http listener. When using HA hook library with + // multi-threading to function, make sure the port used by dedicated + // listener is different (e.g. 8001) than the one used by CA. Note + // the commands should still be sent via CA. The dedicated listener + // is specifically for HA updates only. + "http-port": 8001, + + "control-sockets": + { + // This is how the Agent can communicate with the DHCPv4 server. + "dhcp4": + { + "comment": "socket to DHCP4 server", + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Location of the DHCPv6 command channel socket. + "dhcp6": + { + "socket-type": "unix", + "socket-name": "/tmp/kea6-ctrl-socket" + }, + + // Location of the D2 command channel socket. + "d2": + { + "socket-type": "unix", + "socket-name": "/tmp/kea-ddns-ctrl-socket", + "user-context": { "in-use": false } + } + }, + + // Similar to other Kea components, CA also uses logging. + "loggers": [ + { + "name": "kea-ctrl-agent", + "output_options": [ + { + "output": "/var/log/kea-ctrl-agent.log", + + // Several additional parameters are possible in addition + // to the typical output. Flush determines whether logger + // flushes output to a file. Maxsize determines maximum + // filesize before the file is being rotated. maxver + // specifies the maximum number of rotated files being + // kept. + "flush": true, + "maxsize": 204800, + "maxver": 4, + // We use pattern to specify custom log message layout + "pattern": "%d{%y.%m.%d %H:%M:%S.%q} %-5p [%c/%i] %m\n" + } + ], + "severity": "INFO", + "debuglevel": 0 // debug level only applies when severity is set to DEBUG. + } + ] + } +} diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf new file mode 100644 index 0000000000..f498fb1da7 --- /dev/null +++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf @@ -0,0 +1,225 @@ +// This is an example configuration of the Kea DHCPv4 server 1: +// +// - 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 and location of TLS specific files +// depend on the network settings and configuration of the particular machine. + +{ + +"Dhcp4": { + + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv4 server listens on this interface. When changing this to + // the actual name of your interface, make sure to also update the + // interface parameter in the subnet definition below. + "interfaces": [ "enp0s8" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability requires Control Agent + // to be running because lease updates are sent over the RESTful + // API between the HA peers. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Multi-threading parameters. + "multi-threading": { + // By default Kea processes packets on a single thread (default + // 'false' value for this option). To enable multi-threading, this + // option can be set ('true' value). + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. The + // value must be a positive integer (0 means auto detect). + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + // The value must be a positive integer (0 means unlimited). + "packet-queue-size": 64 + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // 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 aggressively. + "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. Note the library name + // should be the same, but the path is OS specific. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so" + }, + + { + // The HA hooks library should be loaded. + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so", + "parameters": { + // 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 hot-standby. In this mode, the active server handles + // all the traffic. The standby takes over if the primary becomes unavailable. + "mode": "hot-standby", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "heartbeat-delay": 10000, + // Maximum time for partner's response to a heartbeat, after which + // failure detection is started. This is specified in milliseconds. + // 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 + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "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 thousands of clients), you may need to increase it + // further. The default value is 60000ms (60 seconds). + "sync-timeout": 60000, + // Multi-threading parameters. + "multi-threading": { + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incomming requests. + "http-listener-threads": 4, + // The number of threads used to handle outgoing requests. + "http-client-threads": 4 + }, + "peers": [ + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of this server dedicated HTTP listener. + // The Control Agent is not needed for the High Availability + // with multi-threading, but if it is used, it must use + // different values for "http-host" and "http-port". + "url": "http://192.168.1.2:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server1_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server1_key.pem", + // This server is primary. The other one must be + // secondary. + "role": "primary" + }, + // This is the configuration of the secondary server. + { + "name": "server2", + // This specifies the URL of the other server's dedicated HTTP listener. + // The Control Agent is not needed for the High Availability + // with multi-threading, but if it is used, it must use + // different values for "http-host" and "http-port". + "url": "http://192.168.1.3:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server2_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server2_key.pem", + // The other server is secondary. This one must be + // primary. + "role": "standby" + } + ] + } ] + } + } + ], + + // This example contains a single subnet declaration. + "subnet4": [ + { + // Subnet prefix. + "subnet": "192.168.1.0/24", + + // There are no relays in this network, so we need to tell Kea that this subnet + // is reachable directly via the specified interface. + "interface": "enp0s8", + + // Specify a dynamic address pool. + "pools": [ + { + "pool": "192.168.1.100-192.168.1.199" + } + ] + } + ], + + // 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 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": [ + { + "output": "/var/log/kea-dhcp4.log", + "maxsize": 2048000, + "maxver": 4 + } + ], + "severity": "INFO", + "debuglevel": 0 + } + ] +} +} diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf new file mode 100644 index 0000000000..7ddb75dcd4 --- /dev/null +++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf @@ -0,0 +1,225 @@ +// This is an example configuration of the Kea DHCPv4 server 2: +// +// - 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 primary (the active) 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 and location of TLS specific files +// depend on the network settings and configuration of the particular machine. + +{ + +"Dhcp4": { + + // Add names of your network interfaces to listen on. + "interfaces-config": { + // The DHCPv4 server listens on this interface. When changing this to + // the actual name of your interface, make sure to also update the + // interface parameter in the subnet definition below. + "interfaces": [ "enp0s8" ] + }, + + // Control socket is required for communication between the Control + // Agent and the DHCP server. High Availability requires Control Agent + // to be running because lease updates are sent over the RESTful + // API between the HA peers. + "control-socket": { + "socket-type": "unix", + "socket-name": "/tmp/kea4-ctrl-socket" + }, + + // Multi-threading parameters. + "multi-threading": { + // By default Kea processes packets on a single thread (default + // 'false' value for this option). To enable multi-threading, this + // option can be set ('true' value). + "enable-multi-threading": true, + + // When multi-threading is enabled, Kea will process packets on a + // number of multiple threads configurable through this option. The + // value must be a positive integer (0 means auto detect). + "thread-pool-size": 4, + + // When multi-threading is enabled, Kea will read packets from the + // interface and append a working item to the thread pool. This + // option configures the maximum number of items that can be queued. + // The value must be a positive integer (0 means unlimited). + "packet-queue-size": 64 + }, + + // Use Memfile lease database backend to store leases in a CSV file. + // Depending on how Kea was compiled, it may also support SQL databases + // (MySQL and/or PostgreSQL). Those database backends require more + // parameters, like name, host and possibly user and password. + // There are dedicated examples for each backend. See Section 7.2.2 "Lease + // 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 aggressively. + "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. Note the library name + // should be the same, but the path is OS specific. + "hooks-libraries": [ + // The lease_cmds library must be loaded because HA makes use of it to + // deliver lease updates to the server as well as synchronize the + // lease database after failure. + { + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so" + }, + + { + // The HA hooks library should be loaded. + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so", + "parameters": { + // 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": "server2", + // The HA mode is set to hot-standby. In this mode, the active server handles + // all the traffic. The standby takes over if the primary becomes unavailable. + "mode": "hot-standby", + // Heartbeat is to be sent every 10 seconds if no other control + // commands are transmitted. + "heartbeat-delay": 10000, + // Maximum time for partner's response to a heartbeat, after which + // failure detection is started. This is specified in milliseconds. + // 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 + // milliseconds. + "max-ack-delay": 5000, + // This specifies the number of clients which send messages to + // the partner but appear to not receive any response. + "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 thousands of clients), you may need to increase it + // further. The default value is 60000ms (60 seconds). + "sync-timeout": 60000, + // Multi-threading parameters. + "multi-threading": { + "enable-multi-threading": true, + // When running in MT mode, the dedicated listener is used to handle + // lease updates. + "http-dedicated-listener": true, + // The number of threads used to handle incomming requests. + "http-listener-threads": 4, + // The number of threads used to handle outgoing requests. + "http-client-threads": 4 + }, + "peers": [ + // This is the configuration of the primary server. + { + "name": "server1", + // This specifies the URL of the other server's dedicated HTTP listener. + // The Control Agent is not needed for the High Availability + // with multi-threading, but if it is used, it must use + // different values for "http-host" and "http-port". + "url": "http://192.168.1.2:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server1_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server1_key.pem", + // The other server is primary. This one must be + // secondary. + "role": "primary" + }, + // This is the configuration of this server instance. + { + "name": "server2", + // This specifies the URL of this server dedicated HTTP listener. + // The Control Agent is not needed for the High Availability + // with multi-threading, but if it is used, it must use + // different values for "http-host" and "http-port". + "url": "http://192.168.1.3:8000/", + // Trust anchor aka certificate authority file or directory. + "trust-anchor": "/usr/lib/kea/CA.pem", + // Client certificate file name. + "cert-file": "/usr/lib/kea/server2_cert.pem", + // Private key file name. + "key-file": "/usr/lib/kea/server2_key.pem", + // This server is secondary. The other one must be + // primary. + "role": "standby" + } + ] + } ] + } + } + ], + + // This example contains a single subnet declaration. + "subnet4": [ + { + // Subnet prefix. + "subnet": "192.168.1.0/24", + + // There are no relays in this network, so we need to tell Kea that this subnet + // is reachable directly via the specified interface. + "interface": "enp0s8", + + // Specify a dynamic address pool. + "pools": [ + { + "pool": "192.168.1.100-192.168.1.199" + } + ] + } + ], + + // 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 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": [ + { + "output": "/var/log/kea-dhcp4.log", + "maxsize": 2048000, + "maxver": 4 + } + ], + "severity": "INFO", + "debuglevel": 0 + } + ] +} +} diff --git a/doc/examples/template-power-user-home/info.md b/doc/examples/template-power-user-home/info.md index f027b1ae35..5c45ae3b73 100644 --- a/doc/examples/template-power-user-home/info.md +++ b/doc/examples/template-power-user-home/info.md @@ -20,7 +20,6 @@ pair. .. code-block:: none - ``` +-host-1-+ +-host-2-+ | | | | | CA <===\ /===> CA | ===== - HTTP connection @@ -30,7 +29,6 @@ pair. | DHCPv4 ==/ \== DHCPv4 | | | | | +--------+ +--------+ - ``` The CA on host-1 and CA on 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 diff --git a/doc/examples/template-power-user-home/kea-ca-1.conf b/doc/examples/template-power-user-home/kea-ca-1.conf index e8fba5c22b..d7749aee34 100644 --- a/doc/examples/template-power-user-home/kea-ca-1.conf +++ b/doc/examples/template-power-user-home/kea-ca-1.conf @@ -37,7 +37,6 @@ } }, - // Similar to other Kea components, CA also uses logging. "loggers": [ { diff --git a/doc/examples/template-power-user-home/kea-ca-2.conf b/doc/examples/template-power-user-home/kea-ca-2.conf index ccf7e519dd..59e4967bad 100644 --- a/doc/examples/template-power-user-home/kea-ca-2.conf +++ b/doc/examples/template-power-user-home/kea-ca-2.conf @@ -37,7 +37,6 @@ } }, - // Similar to other Kea components, CA also uses logging. "loggers": [ { 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 673981227b..3ff57feac7 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-1.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-1.conf @@ -114,8 +114,8 @@ // 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 + // This specifies the URL of this server instance. The + // Control Agent must run along with this DHCPv4 server // instance and the "http-host" and "http-port" must be // set to the corresponding values. "url": "http://192.168.1.2:8000/", @@ -123,7 +123,7 @@ // secondary. "role": "primary" }, - // This is the configuration of our HA peer. + // This is the configuration of the secondary server. { "name": "server2", // Specifies the URL on which the partner's control @@ -131,7 +131,8 @@ // 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. + // The other server is secondary. This one must be + // primary. "role": "standby" } ] 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 059a895664..bba501ab43 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-2.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-2.conf @@ -111,27 +111,28 @@ // further. The default value is 60000ms (60 seconds). "sync-timeout": 60000, "peers": [ - // This is the configuration of this server instance. + // This is the configuration of the primary server. { "name": "server1", - // This specifies the URL of the partner's server instance. The - // Control Agent must run along with partner DHCPv4 server - // instance and the "http-host" and "http-port" must be - // set to the corresponding values. + // 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.2:8000/", - // That server is primary. Our server must be - // standby. + // The other server is primary. This one must be + // secondary. "role": "primary" }, - // This is our (server2) configuration. + // This is the configuration of this server instance. { "name": "server2", - // Specifies the URL on which the control agent for this server - // can be reached. The Control Agent is required - // to run on this machine with "http-host" and - // "http-port" values set to the corresponding values. + // This specifies the URL of this server instance. The + // Control Agent must run along with this DHCPv4 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. "url": "http://192.168.1.3:8000/", - // Our server is standby. The other server is primary. + // This server is secondary. The other one must be + // primary. "role": "standby" } ] @@ -147,7 +148,7 @@ "subnet": "192.168.1.0/24", // There are no relays in this network, so we need to tell Kea that this subnet - // is reachable directly via the ethX interface. + // is reachable directly via the specified interface. "interface": "enp0s8", // Specify a dynamic address pool. diff --git a/doc/sphinx/arm/config-templates.rst b/doc/sphinx/arm/config-templates.rst index 348c4e0c33..c98b795b02 100644 --- a/doc/sphinx/arm/config-templates.rst +++ b/doc/sphinx/arm/config-templates.rst @@ -23,7 +23,7 @@ Server1's DHCPv4 configuration file: .. literalinclude:: template-power-user-home-dhcp4-1.conf :language: javascript - :emphasize-lines: 25,76,81,121,133,147,151,154-158,166-180,190-199 + :emphasize-lines: 25, 76, 81, 121, 133, 148, 152, 155-159, 167-181, 191-200 :linenos: Server2's Control Agent configuration file: @@ -37,5 +37,38 @@ Server2's DHCPv4 configuration file: .. literalinclude:: template-power-user-home-dhcp4-2.conf :language: javascript - :emphasize-lines: 25,76,81,121,133,147,151,154-158,166-180,190-199 + :emphasize-lines: 25, 76, 81, 121, 133, 148, 152, 155-159, 167-181, 191-200 + :linenos: + +.. include:: template-ha-mt-tls.md + +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: + +.. literalinclude:: template-ha-mt-tls-ca-1.conf + :language: javascript + :emphasize-lines: 10, 14, 17, 20, 23, 32 + :linenos: + +Server1's DHCPv4 configuration file: + +.. literalinclude:: template-ha-mt-tls-dhcp4-1.conf + :language: javascript + :emphasize-lines: 25, 38-54, 95, 100, 133-142, 151, 153, 155, 157, 169, 171, 173, 175, 190, 194, 197-201 + :linenos: + +Server2's Control Agent configuration file: + +.. literalinclude:: template-ha-mt-tls-ca-2.conf + :language: javascript + :emphasize-lines: 10, 14, 17, 20, 23, 32 + :linenos: + +Server2's DHCPv4 configuration file: + +.. literalinclude:: template-ha-mt-tls-dhcp4-2.conf + :language: javascript + :emphasize-lines: 25, 38-54, 95, 100, 133-142, 151, 153, 155, 157, 169, 171, 173, 175, 190, 194, 197-201 :linenos: diff --git a/doc/sphinx/arm/security.rst b/doc/sphinx/arm/security.rst index ec7baa6db6..490947d334 100644 --- a/doc/sphinx/arm/security.rst +++ b/doc/sphinx/arm/security.rst @@ -54,7 +54,7 @@ that must be used: - OpenSSL versions 1.1.x and later have been tested and are supported. Many recent operating system versions include TLS 1.3 support. -- OpenSSL 3.x is not yet released; it is unknown whether Kea will build with it. +- OpenSSL 3.x has been released and Kea will build with it. - LibreSSL 3.2.4 has been tested. LibreSSL shares the OpenSSL 1.0.2 API, so it should work, but is not supported. diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index c7bcb0a44e..5e85ff509f 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -266,7 +266,12 @@ def run_generate_docs(_): [ '../examples/template-power-user-home/kea-ca-1.conf', 'template-power-user-home-ca-1.conf' ], [ '../examples/template-power-user-home/kea-ca-2.conf', 'template-power-user-home-ca-2.conf' ], [ '../examples/template-power-user-home/kea-dhcp4-1.conf', 'template-power-user-home-dhcp4-1.conf' ], - [ '../examples/template-power-user-home/kea-dhcp4-2.conf', 'template-power-user-home-dhcp4-2.conf' ] + [ '../examples/template-power-user-home/kea-dhcp4-2.conf', 'template-power-user-home-dhcp4-2.conf' ], + [ '../examples/template-ha-mt-tls/info.md', 'template-ha-mt-tls.md' ], + [ '../examples/template-ha-mt-tls/kea-ca-1.conf', 'template-ha-mt-tls-ca-1.conf' ], + [ '../examples/template-ha-mt-tls/kea-ca-2.conf', 'template-ha-mt-tls-ca-2.conf' ], + [ '../examples/template-ha-mt-tls/kea-dhcp4-1.conf', 'template-ha-mt-tls-dhcp4-1.conf' ], + [ '../examples/template-ha-mt-tls/kea-dhcp4-2.conf', 'template-ha-mt-tls-dhcp4-2.conf' ] ] from shutil import copyfile diff --git a/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc b/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc index f67cad30b4..d8206f8e9f 100644 --- a/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc +++ b/src/bin/dhcp4/tests/dhcp4_srv_unittest.cc @@ -2919,7 +2919,8 @@ Dhcpv4SrvTest::checkConfigFiles() { #endif "dhcpv4-over-dhcpv6.json", "global-reservations.json", - "ha-load-balancing-primary.json", + "ha-load-balancing-server1-mt-with-tls.json", + "ha-load-balancing-server2-mt.json", "hooks.json", "hooks-radius.json", "leases-expiration.json", diff --git a/src/bin/dhcp6/tests/dhcp6_srv_unittest.cc b/src/bin/dhcp6/tests/dhcp6_srv_unittest.cc index 98bd6ccc91..a3620d5cbb 100644 --- a/src/bin/dhcp6/tests/dhcp6_srv_unittest.cc +++ b/src/bin/dhcp6/tests/dhcp6_srv_unittest.cc @@ -305,7 +305,8 @@ Dhcpv6SrvTest::checkConfigFiles() { "dhcpv4-over-dhcpv6.json", "duid.json", "global-reservations.json", - "ha-hot-standby.json", + "ha-hot-standby-server1-with-tls.json", + "ha-hot-standby-server2.json", "hooks.json", "iPXE.json", "leases-expiration.json", diff --git a/src/lib/yang/tests/adaptor_config_unittests.cc b/src/lib/yang/tests/adaptor_config_unittests.cc index 1a5affa9c9..c4670887dc 100644 --- a/src/lib/yang/tests/adaptor_config_unittests.cc +++ b/src/lib/yang/tests/adaptor_config_unittests.cc @@ -70,7 +70,8 @@ TEST_F(AdaptorConfigTest, loadExamples4) { "config-backend.json", "dhcpv4-over-dhcpv6.json", "global-reservations.json", - "ha-load-balancing-primary.json", + "ha-load-balancing-primary-mt-with-tls.json", + "ha-load-balancing-secondary-mt.json", "hooks.json", "hooks-radius.json", "leases-expiration.json", @@ -105,7 +106,8 @@ TEST_F(AdaptorConfigTest, loadExamples6) { "dhcpv4-over-dhcpv6.json", "duid.json", "global-reservations.json", - "ha-hot-standby.json", + "ha-hot-standby-primary-with-tls.json", + "ha-hot-standby-secondary.json", "hooks.json", "iPXE.json", "leases-expiration.json", diff --git a/src/lib/yang/tests/config_unittests.cc b/src/lib/yang/tests/config_unittests.cc index 7a655a747f..fcbadb8d70 100644 --- a/src/lib/yang/tests/config_unittests.cc +++ b/src/lib/yang/tests/config_unittests.cc @@ -334,7 +334,8 @@ TEST_F(ConfigTestKeaV4, examples4) { "config-backend.json", "dhcpv4-over-dhcpv6.json", "global-reservations.json", - "ha-load-balancing-primary.json", + "ha-load-balancing-primary-mt-with-tls.json", + "ha-load-balancing-secondary-mt.json", "hooks.json", "hooks-radius.json", "leases-expiration.json", @@ -375,7 +376,8 @@ TEST_F(ConfigTestKeaV6, examples6) { "dhcpv4-over-dhcpv6.json", "duid.json", "global-reservations.json", - "ha-hot-standby.json", + "ha-hot-standby-primary-with-tls.json", + "ha-hot-standby-secondary.json", "hooks.json", "iPXE.json", "leases-expiration.json",