From: Razvan Becheriu Date: Wed, 4 Jun 2025 13:54:39 +0000 (+0300) Subject: [#3541] update docs and examples X-Git-Tag: Kea-3.0.0~123 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e1c8b7f976409fa62449f2f89bb5d83918fa7a44;p=thirdparty%2Fkea.git [#3541] update docs and examples --- diff --git a/doc/examples/agent/comments.json b/doc/examples/agent/comments.json index 61f8980d8a..b1c7078e5e 100644 --- a/doc/examples/agent/comments.json +++ b/doc/examples/agent/comments.json @@ -16,6 +16,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // Extra HTTP headers to add in responses. diff --git a/doc/examples/agent/https.json b/doc/examples/agent/https.json index c06039c99f..b8e459ac2e 100644 --- a/doc/examples/agent/https.json +++ b/doc/examples/agent/https.json @@ -13,6 +13,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // TLS trust anchor (Certificate Authority). This is a file name or diff --git a/doc/examples/agent/rbac.json b/doc/examples/agent/rbac.json index 575cfd90e5..05a8c84545 100644 --- a/doc/examples/agent/rbac.json +++ b/doc/examples/agent/rbac.json @@ -13,6 +13,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // TLS trust anchor (Certificate Authority). This is a file name or diff --git a/doc/examples/agent/simple.json b/doc/examples/agent/simple.json index 62596c45ca..ed37481fb9 100644 --- a/doc/examples/agent/simple.json +++ b/doc/examples/agent/simple.json @@ -13,6 +13,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // Extra HTTP headers to add in responses. diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json index 5823d4b4c9..5315b37d38 100644 --- a/doc/examples/kea4/all-keys.json +++ b/doc/examples/kea4/all-keys.json @@ -173,7 +173,11 @@ // commands should still be sent to a control socket. // The dedicated listener is specifically for HA // updates only. - "socket-port": 8000, + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 894) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "socket-port": 8004, // TLS trust anchor (Certificate Authority). This is a // file name or a directory path. Make sense with other diff --git a/doc/examples/kea4/comments.json b/doc/examples/kea4/comments.json index bbe4fa0e86..0762fd2298 100644 --- a/doc/examples/kea4/comments.json +++ b/doc/examples/kea4/comments.json @@ -62,7 +62,7 @@ "comment": "HTTP control socket", "socket-type": "http", "socket-address": "::1", - "socket-port": 8000, + "socket-port": 8004, // In authentication "authentication": { 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 index 168f502709..733b4e6c18 100644 --- a/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json +++ b/doc/examples/kea4/ha-load-balancing-server1-mt-with-tls.json @@ -162,7 +162,10 @@ // instance if multi-threading is enabled. // The "http-host" and "http-port" values must be set to different // values then the ones used by the Control Agent. - "url": "http://192.168.56.33:8000/", + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 895) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.33:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. @@ -182,8 +185,11 @@ // channel can be reached. The Control Agent is not required // to run on the partner's machine if multi-threading is enabled. // The "http-host" and "http-port" values must be set to different - // values then the ones used by the Control Agent. - "url": "http://192.168.56.66:8000/", + // values then the ones used by the Control Agent + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 895) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.66:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. diff --git a/doc/examples/kea4/ha-load-balancing-server2-mt.json b/doc/examples/kea4/ha-load-balancing-server2-mt.json index 149bb55e27..e4fa98385f 100644 --- a/doc/examples/kea4/ha-load-balancing-server2-mt.json +++ b/doc/examples/kea4/ha-load-balancing-server2-mt.json @@ -161,7 +161,10 @@ // to run on the partner's machine if multi-threading is enabled. // The "http-host" and "http-port" values must be set to different // values then the ones used by the Control Agent. - "url": "http://192.168.56.33:8000/", + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 895) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.33:8005", // The partner is primary. This server is secondary. "role": "primary" }, @@ -173,7 +176,10 @@ // instance if multi-threading is enabled. // The "http-host" and "http-port" values must be set to different // values then the ones used by the Control Agent. - "url": "http://192.168.56.66:8000/", + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 895) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.66:8005", // This server is secondary. The other one must be // primary. "role": "secondary" diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json index 5c7c1a3ee6..1eaa975b07 100644 --- a/doc/examples/kea6/all-keys.json +++ b/doc/examples/kea6/all-keys.json @@ -124,7 +124,11 @@ // commands should still be sent to a control socket. // The dedicated listener is specifically for HA // updates only. - "socket-port": 8000, + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 896) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "socket-port": 8006, // TLS trust anchor (Certificate Authority). This is a // file name or a directory path. Make sense with other diff --git a/doc/examples/kea6/comments.json b/doc/examples/kea6/comments.json index bc6ea097da..fdeb352bb8 100644 --- a/doc/examples/kea6/comments.json +++ b/doc/examples/kea6/comments.json @@ -62,7 +62,7 @@ "comment": "HTTP control socket", "socket-type": "http", "socket-address": "127.0.0.1", - "socket-port": 8000, + "socket-port": 8006, // In authentication "authentication": { diff --git a/doc/examples/kea6/ha-hot-standby-server1-with-tls.json b/doc/examples/kea6/ha-hot-standby-server1-with-tls.json index 6e67645b57..a5ae2ae927 100644 --- a/doc/examples/kea6/ha-hot-standby-server1-with-tls.json +++ b/doc/examples/kea6/ha-hot-standby-server1-with-tls.json @@ -94,7 +94,11 @@ // Control Agent must run along with this DHCPv6 server // instance and the "http-host" and "http-port" must be // set to the corresponding values. - "url": "http://192.168.56.33:8000/", + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 897) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.33:8007", // This server is primary. The other one must be // standby. "role": "primary" @@ -106,7 +110,11 @@ // 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/", + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 897) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.66:8007", // The partner is standby. This server is primary. "role": "standby" } diff --git a/doc/examples/kea6/ha-hot-standby-server2.json b/doc/examples/kea6/ha-hot-standby-server2.json index 037fd97810..dd85224cac 100644 --- a/doc/examples/kea6/ha-hot-standby-server2.json +++ b/doc/examples/kea6/ha-hot-standby-server2.json @@ -85,7 +85,11 @@ // 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/", + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 897) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.33:8007", // The partner is primary. This server is standby. "role": "primary" }, @@ -96,7 +100,11 @@ // Control Agent must run along with this DHCPv6 server // instance and the "http-host" and "http-port" must be // set to the corresponding values. - "url": "http://192.168.56.66:8000/", + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 897) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.56.66:8007", // This server is standby. The other one must be // primary. "role": "standby" diff --git a/doc/examples/template-ha-mt-tls/kea-ca-1.conf b/doc/examples/template-ha-mt-tls/kea-ca-1.conf index e937feaeec..0c6a80a821 100644 --- a/doc/examples/template-ha-mt-tls/kea-ca-1.conf +++ b/doc/examples/template-ha-mt-tls/kea-ca-1.conf @@ -33,6 +33,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8001, "control-sockets": diff --git a/doc/examples/template-ha-mt-tls/kea-ca-2.conf b/doc/examples/template-ha-mt-tls/kea-ca-2.conf index 2322261ee3..2bc24a3b17 100644 --- a/doc/examples/template-ha-mt-tls/kea-ca-2.conf +++ b/doc/examples/template-ha-mt-tls/kea-ca-2.conf @@ -33,6 +33,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8001, "control-sockets": diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf index e2c694e1d5..5c450224b1 100644 --- a/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf +++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf @@ -157,7 +157,10 @@ // 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/", + // For security reasons, Kea should be run as non root user, a port + // lower than 1024 should be used (e.g. 895) and, on Linux systems, + // the process should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.1.2:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. @@ -177,7 +180,10 @@ // 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/", + // For security reasons, Kea should be run as non root user, a port + // lower than 1024 should be used (e.g. 895) and, on Linux systems, + // the process should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.1.3:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf index 7b9d56ee09..a49a9505db 100644 --- a/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf +++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf @@ -157,7 +157,10 @@ // 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/", + // For security reasons, Kea should be run as non root user, a port + // lower than 1024 should be used (e.g. 895) and, on Linux systems, + // the process should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.1.2:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. @@ -177,7 +180,10 @@ // 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/", + // For security reasons, Kea should be run as non root user, a port + // lower than 1024 should be used (e.g. 895) and, on Linux systems, + // the process should have 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.168.1.3:8005", // Trust anchor aka certificate authority file or directory. "trust-anchor": "/usr/lib/kea/CA.pem", // Client certificate file name. 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 a280448708..03f9839920 100644 --- a/doc/examples/template-power-user-home/kea-ca-1.conf +++ b/doc/examples/template-power-user-home/kea-ca-1.conf @@ -9,6 +9,9 @@ "http-host": "192.168.1.2", // This specifies the port CA will listen on. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, "control-sockets": 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 5d114d1030..dbff0250dd 100644 --- a/doc/examples/template-power-user-home/kea-ca-2.conf +++ b/doc/examples/template-power-user-home/kea-ca-2.conf @@ -9,6 +9,9 @@ "http-host": "192.168.1.3", // This specifies the port CA will listen on. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, "control-sockets": 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 5b37a3e2c9..704d16f810 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-1.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-1.conf @@ -121,7 +121,11 @@ // 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/", + // For security reasons, Kea should be run as non root user, + // a port lower than 1024 should be used (e.g. 895) and, on + // Linux systems, the process should have 'CAP_NET_BIND_SERVICE' + // capabilities. + "url": "http://192.168.1.2:8005", // This server is primary. The other one must be // secondary. "role": "primary" @@ -133,7 +137,11 @@ // channel can be reached. The Control Agent is required // to run on the partner's machine with "http-host" and // "http-port" values set to the corresponding values. - "url": "http://192.168.1.3:8000/", + // For security reasons, Kea should be run as non root user, + // a port lower than 1024 should be used (e.g. 895) and, on + // Linux systems, the process should have 'CAP_NET_BIND_SERVICE' + // capabilities. + "url": "http://192.168.1.3:8005", // 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 80d8f2f858..e6b2f25685 100644 --- a/doc/examples/template-power-user-home/kea-dhcp4-2.conf +++ b/doc/examples/template-power-user-home/kea-dhcp4-2.conf @@ -121,7 +121,11 @@ // 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/", + // For security reasons, Kea should be run as non root user, + // a port lower than 1024 should be used (e.g. 895) and, on + // Linux systems, the process should have 'CAP_NET_BIND_SERVICE' + // capabilities. + "url": "http://192.168.1.2:8005", // The other server is primary. This one must be // secondary. "role": "primary" @@ -133,7 +137,11 @@ // 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/", + // For security reasons, Kea should be run as non root user, + // a port lower than 1024 should be used (e.g. 895) and, on + // Linux systems, the process should have 'CAP_NET_BIND_SERVICE' + // capabilities. + "url": "http://192.168.1.3:8005", // This server is secondary. The other one must be // primary. "role": "standby" diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst index ec8c013270..cfcdbd0b28 100644 --- a/doc/sphinx/arm/agent.rst +++ b/doc/sphinx/arm/agent.rst @@ -114,6 +114,10 @@ provided above, the RESTful service will be available at the URL ``https://10.20.30.40:8000/``. If these parameters are not specified, the default URL is ``http://127.0.0.1:8000/``. +For security reasons, Kea should be run as non root user, a port lower +than 1024 should be used (e.g. 890) and, on Linux systems, the process +should have 'CAP_NET_BIND_SERVICE' capabilities. + When using Kea's HA hook library with multi-threading, the address:port combination used for CA must be different from the HA peer URLs, which are strictly diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index 43e8702c45..53a6bf232e 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -403,6 +403,10 @@ TLS is required). The ``socket-address`` (default ``127.0.0.1``) and ``socket-port`` (default 8000) specify an IP address and port to which the HTTP service will be bound. +For security reasons, Kea should be run as non root user, a port lower +than 1024 should be used (e.g. 892) and, on Linux systems, the process +should have 'CAP_NET_BIND_SERVICE' capabilities. + The ``trust-anchor``, ``cert-file``, ``key-file``, and ``cert-required`` parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters are not specified, HTTP is used. The TLS/HTTPS support in Kea is diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index a1d47ef3fb..717f7f7b0a 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -7910,6 +7910,10 @@ TLS is required). The ``socket-address`` (default ``127.0.0.1``) and ``socket-port`` (default 8000) specify an IP address and port to which the HTTP service will be bound. +For security reasons, Kea should be run as non root user, a port lower +than 1024 should be used (e.g. 894) and, on Linux systems, the process +should have 'CAP_NET_BIND_SERVICE' capabilities. + Since Kea 2.7.5 the ``http-headers`` parameter specifies a list of extra HTTP headers to add to HTTP responses. diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 13f28cc450..9b220c013c 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -7816,6 +7816,10 @@ TLS is required). The ``socket-address`` (default ``::1``) and ``socket-port`` (default 8000) specify an IP address and port to which the HTTP service will be bound. +For security reasons, Kea should be run as non root user, a port lower +than 1024 should be used (e.g. 896) and, on Linux systems, the process +should have 'CAP_NET_BIND_SERVICE' capabilities. + Since Kea 2.7.5 the ``http-headers`` parameter specifies a list of extra HTTP headers to add to HTTP responses. diff --git a/doc/sphinx/arm/ext-netconf.rst b/doc/sphinx/arm/ext-netconf.rst index 39a6711b63..d7d4b2e2c1 100644 --- a/doc/sphinx/arm/ext-netconf.rst +++ b/doc/sphinx/arm/ext-netconf.rst @@ -563,15 +563,14 @@ Kea sources. } }, - // Currently the DHCP-DDNS (nicknamed D2) server does not support - // a command channel. "d2": { "model": "kea-dhcp-ddns", "control-socket": { - "socket-type": "stdout", - "user-context": { "in-use": false } + "socket-type": "unix", + "socket-name": "kea-ddns-ctrl-socket", + "user-context": { "in-use": true } } }, diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index b480627bee..89e164129d 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -261,12 +261,12 @@ Server 1: "max-unacked-clients": 5, "peers": [{ "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary", "auto-failover": true }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "standby", "auto-failover": true }] @@ -308,12 +308,12 @@ Server 2: "max-unacked-clients": 5, "peers": [{ "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary", "auto-failover": true }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "standby", "auto-failover": true }] @@ -687,17 +687,17 @@ only difference that ``this-server-name`` should be set to "server2" and "delayed-updates-limit": 100, "peers": [{ "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary", "auto-failover": true }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "secondary", "auto-failover": true }, { "name": "server3", - "url": "http://192.168.56.99:8000/", + "url": "http://192.168.56.99:8005", "role": "backup", "basic-auth-user": "foo", "basic-auth-password": "1234", @@ -1084,17 +1084,17 @@ The following is an example configuration of the primary server in a "max-rejected-lease-updates": 10, "peers": [{ "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary", "auto-failover": true }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "standby", "auto-failover": true }, { "name": "server3", - "url": "http://192.168.56.99:8000/", + "url": "http://192.168.56.99:8005", "basic-auth-user": "foo", "basic-auth-password": "1234", "role": "backup", @@ -1165,15 +1165,15 @@ The following is an example configuration file for the primary server in a "wait-backup-ack": false, "peers": [{ "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary" }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "backup" }, { "name": "server3", - "url": "http://192.168.56.99:8000/", + "url": "http://192.168.56.99:8005", "basic-auth-user": "foo", "basic-auth-password": "1234", "role": "backup" @@ -1287,12 +1287,12 @@ default to ``true``: "peers": [ { "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary" }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "secondary" } ] @@ -1379,12 +1379,12 @@ single page of leases from 60 seconds to 90 seconds: "peers": [ { "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary" }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "secondary" } ] @@ -1457,12 +1457,12 @@ the HA state machine to pause in the ``waiting`` state after server startup. "peers": [ { "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary" }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "secondary" } ], @@ -1512,12 +1512,12 @@ Consider the following configuration: "peers": [ { "name": "server1", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8005", "role": "primary" }, { "name": "server2", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8005", "role": "secondary" } ], @@ -1593,6 +1593,9 @@ machine as the primary server. This configuration is valid for both the // 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. + // For security reasons, Kea should be run as non root user, a port + // lower than 1024 should be used (e.g. 890) and, on Linux systems, + // the process should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, "control-sockets": { @@ -1683,8 +1686,12 @@ as illustrated below: // Since the HA+MT uses a direct connection, the // DHCPv4 server open its own socket. Note that it // must be different than the one used by the CA - // (typically 8000). In this example, 8001 is used. - "url": "http://192.0.2.1:8001/", + // (typically 8000). In this example, 8005 is used. + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 895) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.0.2.1:8005", // This server is primary. The other one must be // secondary. "role": "primary" @@ -1696,8 +1703,12 @@ as illustrated below: // Since the HA+MT uses a direct connection, the // DHCPv4 server open its own socket. Note that it // must be different than the one used by the CA - // (typically 8000). In this example, 8001 is used. - "url": "http://192.0.2.2:8001/", + // (typically 8000). In this example, 8005 is used. + // For security reasons, Kea should be run as non root + // user, a port lower than 1024 should be used (e.g. 895) + // and, on Linux systems, the process should have + // 'CAP_NET_BIND_SERVICE' capabilities. + "url": "http://192.0.2.2:8005", // The partner is a secondary. This server is a // primary as specified in the previous "peers" // entry and in "this-server-name" before that. @@ -2461,13 +2472,13 @@ grouped into relationships as in the snippet below: "peers": [ { "name": "server1", - "url": "http://192.168.56.66:8000/", + "url": "http://192.168.56.66:8007", "role": "primary", "auto-failover": true }, { "name": "server2", - "url": "http://192.168.56.33:8000/", + "url": "http://192.168.56.33:8007", "role": "standby", "auto-failover": true } @@ -2485,13 +2496,13 @@ grouped into relationships as in the snippet below: "peers": [ { "name": "server3", - "url": "http://192.168.57.99:8000/", + "url": "http://192.168.57.99:8007", "role": "primary", "auto-failover": true }, { "name": "server4", - "url": "http://192.168.57.33:8000/", + "url": "http://192.168.57.33:8007", "role": "standby", "auto-failover": true } @@ -2565,13 +2576,13 @@ branch ``server3``: "peers": [ { "name": "server3", - "url": "http://192.168.57.99:8000/", + "url": "http://192.168.57.99:8007", "role": "primary", "auto-failover": true }, { "name": "server4", - "url": "http://192.168.57.33:8000/", + "url": "http://192.168.57.33:8007", "role": "standby", "auto-failover": true } diff --git a/doc/sphinx/arm/hooks-rbac.rst b/doc/sphinx/arm/hooks-rbac.rst index 88bad10c15..8051fbeb49 100644 --- a/doc/sphinx/arm/hooks-rbac.rst +++ b/doc/sphinx/arm/hooks-rbac.rst @@ -249,6 +249,9 @@ in the Kea source and is copied below. // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // TLS trust anchor (Certificate Authority). This is a file name or diff --git a/doc/sphinx/arm/security.rst b/doc/sphinx/arm/security.rst index aa4a055a50..6251a8e09a 100644 --- a/doc/sphinx/arm/security.rst +++ b/doc/sphinx/arm/security.rst @@ -317,6 +317,9 @@ capabilities mechanism on Linux systems, Kea can run from an unprivileged accoun The Control Agent (CA) can accept incoming HTTP or HTTPS connections. The default port is 8000, which does not require privileged access. +For security reasons, Kea should be run as non root user, a port lower than 1024 should be used (e.g. 890) +and, on Linux systems, the process should have 'CAP_NET_BIND_SERVICE' capabilities. + Securing Kea Administrative Access ---------------------------------- diff --git a/src/bin/keactrl/kea-ctrl-agent.conf.pre b/src/bin/keactrl/kea-ctrl-agent.conf.pre index 29d81111b0..6f7a366feb 100644 --- a/src/bin/keactrl/kea-ctrl-agent.conf.pre +++ b/src/bin/keactrl/kea-ctrl-agent.conf.pre @@ -6,7 +6,7 @@ // do. Comments in this configuration file sometimes refer to sections for more // details. These are section numbers in Kea User's Guide. The version matching // your software should come with your Kea package, but it is also available -// in ISC's Knowledgebase (https://kea.readthedocs.io; the direct link for +// in ISC's Knowledge base (https://kea.readthedocs.io; the direct link for // the stable version is https://kea.readthedocs.io/). // // This configuration file contains only Control Agent's configuration. @@ -24,6 +24,9 @@ // 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. + // For security reasons, Kea should be run as non root user, a port lower + // than 1024 should be used (e.g. 890) and, on Linux systems, the process + // should have 'CAP_NET_BIND_SERVICE' capabilities. "http-port": 8000, // Allow access only to kea-api user.