From: Tomek Mrugalski Date: Wed, 22 Sep 2021 13:34:14 +0000 (+0200) Subject: [#2050] Config examples added. X-Git-Tag: Kea-2.0.0~37 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b7a969ceac9d2c80660ed33df5e4fc5555979e23;p=thirdparty%2Fkea.git [#2050] Config examples added. --- diff --git a/doc/examples/template-power-user-home/kea-ca-1.conf b/doc/examples/template-power-user-home/kea-ca-1.conf new file mode 100644 index 0000000000..2b32a8da96 --- /dev/null +++ b/doc/examples/template-power-user-home/kea-ca-1.conf @@ -0,0 +1,80 @@ +// This is an example of a configuration for Control-Agent (CA) HTTPS i.e. +// HTTP over TLS. +{ + "Control-agent": + { + // We need to specify where the agent should listen to incoming HTTPS + // queries. + "http-host": "192.168.1.2", + + // This + "http-port": 8000, + + // TLS trust anchor (Certificate Authority). This is a file name or + // (for OpenSSL only) a directory path. + //"trust-anchor": "my-ca", + + // TLS server certificate file name. + //"cert-file": "my-cert", + + // TLS server private key file name. + // "key-file": "my-key", + + // TLS require client certificates flag. Default is true and means + // require client certificates. False means they are optional. + //"cert-required": true + + "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-power-user-home/kea-ca-2.conf b/doc/examples/template-power-user-home/kea-ca-2.conf new file mode 100644 index 0000000000..eedc11faf8 --- /dev/null +++ b/doc/examples/template-power-user-home/kea-ca-2.conf @@ -0,0 +1,80 @@ +// This is an example of a configuration for Control-Agent (CA) HTTPS i.e. +// HTTP over TLS. +{ + "Control-agent": + { + // We need to specify where the agent should listen to incoming HTTPS + // queries. + "http-host": "192.168.1.3", + + // This + "http-port": 8000, + + // TLS trust anchor (Certificate Authority). This is a file name or + // (for OpenSSL only) a directory path. + //"trust-anchor": "my-ca", + + // TLS server certificate file name. + //"cert-file": "my-cert", + + // TLS server private key file name. + // "key-file": "my-key", + + // TLS require client certificates flag. Default is true and means + // require client certificates. False means they are optional. + //"cert-required": true + + "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-power-user-home/kea-dhcp4-1.conf b/doc/examples/template-power-user-home/kea-dhcp4-1.conf new file mode 100644 index 0000000000..bd50e0c827 --- /dev/null +++ b/doc/examples/template-power-user-home/kea-dhcp4-1.conf @@ -0,0 +1,179 @@ +// This is an example configuration of the Kea DHCPv4 server. It uses High +// Availability hooks library and Lease Commands hooks library to enable +// High Availability function for the DHCP server. Note that almost exactly +// the same configuration must be used on the second server (partner). +// The only difference is that "this-server-name" must be set to "server2" +// on this other server. Also, the interface configuration depends on the +// network settings of the particular machine. +// +// 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. 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" + }, + + // 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) and even Cassandra. 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": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hooks library should be loaded. + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so", + "parameters": { + // High Availability configuration is specified for the HA hook library. + // Each server should have the same HA configuration, except for the + // "this-server-name" parameter. + "high-availability": [ { + // This parameter points to this server instance. The respective + // HA peers must have this parameter set to their own names. + "this-server-name": "server1", + // The HA mode is set to load-balancing. In this mode, the active + // servers share the traffic (50/50). + "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": 10000, + // 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, + "peers": [ + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of our server instance. The + // Control Agent must run along with our DHCPv4 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. + "url": "http://192.168.1.2:8000/", + // This server is primary. The other one must be + // secondary. + "role": "primary" + }, + // This is the configuration of our HA peer. + { + "name": "server2", + // Specifies the URL on which the partner's control + // channel can be reached. The Control Agent is required + // to run on the partner's machine with "http-host" and + // "http-port" values set to the corresponding values. + "url": "http://192.168.1.3:8000/", + // The partner is a secondary. Our is primary. + "role": "standby" + } + ] + } ] + } + } + ], + + // This 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 ethX interface. + "interface": "enp0s8", + + // Specify four address pools. + "pools": [ + { + "pool": "192.168.1.100-192.168.1.149", + "client-class": "HA_server1" + }, + { + "pool": "192.168.1.150-192.168.1.200", + "client-class": "HA_server2" + } + ], + + // These are options that are subnet specific. In most cases, + // you need to define at least routers option, as without this + // option your clients will not be able to reach their default + // gateway and will not have Internet connectivity. + "option-data": [ + { + // For each IPv4 subnet you most likely need to specify at + // least one router. + "name": "routers", + "data": "192.168.1.1" + }, + { + // Using cloudflare or Quad9 is a reasonable option. Change this + // to your own DNS servers is you have them. Another popular + // choice is 8.8.8.8, owned by Google. Using third party DNS + // service raises some privacy concerns. + "name": "domain-name-servers", + "data": "1.1.1.1,9.9.9.9" + } + ] + } + ], + + // Logging configuration starts here. + "loggers": [ + { + // This section affects kea-dhcp4, which is the base logger for DHCPv4 + // component. It tells DHCPv4 server to write all log messages (on + // severity INFO or more) to a file. + "name": "kea-dhcp4", + "output_options": [ + { + "output": "/var/log/kea-dhcp4.log", + "maxsize": 2048000, + "maxver": 4 + } + ], + "severity": "INFO" + } + ] +} +} diff --git a/doc/examples/template-power-user-home/kea-dhcp4-2.conf b/doc/examples/template-power-user-home/kea-dhcp4-2.conf new file mode 100644 index 0000000000..8c969d4260 --- /dev/null +++ b/doc/examples/template-power-user-home/kea-dhcp4-2.conf @@ -0,0 +1,189 @@ +// This is an example configuration of the Kea DHCPv4 server. It uses High +// Availability hooks library and Lease Commands hooks library to enable +// High Availability function for the DHCP server. Note that almost exactly +// the same configuration must be used on the second server (partner). +// The only difference is that "this-server-name" must be set to "server2" +// on this other server. Also, the interface configuration depends on the +// network settings of the particular machine. +// +// 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. 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" + }, + + // 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) and even Cassandra. 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": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + // The HA hooks library should be loaded. + "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_ha.so", + "parameters": { + // High Availability configuration is specified for the HA hook library. + // Each server should have the same HA configuration, except for the + // "this-server-name" parameter. + "high-availability": [ { + // This parameter points to this server instance. The respective + // HA peers must have this parameter set to their own names. + "this-server-name": "server2", + // The HA mode is set to load-balancing. In this mode, the active + // servers share the traffic (50/50). + "mode": "hot-standby", + // Heartbeat is to be sent every 10 seconds if no other control + // 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": 10000, + // 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, + "peers": [ + // This is the configuration of this server instance. + { + "name": "server1", + // This specifies the URL of our server instance. The + // Control Agent must run along with our DHCPv4 server + // instance and the "http-host" and "http-port" must be + // set to the corresponding values. + "url": "http://192.168.1.2:8000/", + // This server is primary. The other one must be + // secondary. + "role": "primary" + }, + // This is the configuration of our HA peer. + { + "name": "server2", + // Specifies the URL on which the partner's control + // channel can be reached. The Control Agent is required + // to run on the partner's machine with "http-host" and + // "http-port" values set to the corresponding values. + "url": "http://192.168.1.3:8000/", + // The partner is a secondary. Our is primary. + "role": "standby" + } + ] + } ] + } + } + ], + + // This 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 ethX interface. + "interface": "enp0s8", + + // Specify four address pools. + "pools": [ + { + "pool": "192.168.1.100-192.168.1.149", + "client-class": "HA_server1" + }, + { + "pool": "192.168.1.150-192.168.1.200", + "client-class": "HA_server2" + } + ], + + // These are options that are subnet specific. In most cases, + // you need to define at least routers option, as without this + // option your clients will not be able to reach their default + // gateway and will not have Internet connectivity. + "option-data": [ + { + // For each IPv4 subnet you most likely need to specify at + // least one router. + "name": "routers", + "data": "192.168.1.1" + }, + { + // Using cloudflare or Quad9 is a reasonable option. Change this + // to your own DNS servers is you have them. Another popular + // choice is 8.8.8.8, owned by Google. Using third party DNS + // service raises some privacy concerns. + "name": "domain-name-servers", + "data": "1.1.1.1,9.9.9.9" + } + ] + } + ], + + // Logging configuration starts here. + "loggers": [ + { + // This section affects kea-dhcp4, which is the base logger for DHCPv4 + // component. It tells DHCPv4 server to write all log messages (on + // severity INFO or more) to a file. + "name": "kea-dhcp4", + "output_options": [ + { + "output": "/var/log/kea-dhcp4.log" + + } + ], + "severity": "INFO" + }, + { + // This section specifies configuration of the HA hooks library specific + // logger. + "name": "kea-dhcp4.ha-hooks", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "INFO" + } + ] +} +}