From: Marcin Siodelski Date: Tue, 10 Feb 2015 17:16:24 +0000 (+0100) Subject: [3604] Updated Kea user guide with the new config structure for interfaces. X-Git-Tag: trac3712_base~9^2~6 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=51637af184636982e59e8a309e43e70599fa2e5c;p=thirdparty%2Fkea.git [3604] Updated Kea user guide with the new config structure for interfaces. --- diff --git a/doc/guide/config.xml b/doc/guide/config.xml index 697796107e..5214986511 100644 --- a/doc/guide/config.xml +++ b/doc/guide/config.xml @@ -56,7 +56,10 @@ # DHCPv4 specific configuration starts here. "Dhcp4": { - "interfaces": [ "eth0" ], + "interfaces-config": { + "interfaces": [ "eth0" ], + "socket-type": "raw" + }, "valid-lifetime": 4000, "renew-timer": 1000, "rebind-timer": 2000, @@ -70,7 +73,9 @@ # DHCPv6 specific configuration starts here. "Dhcp6": { - "interfaces": [ "eth1" ], + "interfaces-config": { + "interfaces": [ "eth1" ] + }, "preferred-lifetime": 3000, "valid-lifetime": 4000, "renew-timer": 1000, @@ -119,8 +124,7 @@ If there is an array, a specific instance within that array is referenced by a number in square brackets (with numbering starting at zero). For example, in the above configuration the valid-lifetime in the Dhcp6 component can be referred to as - Dhcp6/valid-lifetime, the first interface for the DHCPv4 server as - Dhcp4/interfaces[0] and the pool in the first subnet defined in the DHCPv6 + Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6 configuration as Dhcp6/subnet6[0]/pool. diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 51ae8811ba..f0864e5127 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -92,12 +92,16 @@ "Dhcp4": { # First we set up global values - "interfaces": [ "eth0" ], "valid-lifetime": 4000, "renew-timer": 1000, "rebind-timer": 2000, -# Next we specify the type of lease database +# Next we setup the interfaces to be used by the server. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +# And we specify the type of lease database "lease-database": { "type": "memfile", "persist": true, @@ -154,19 +158,8 @@ ignored. This is unlikely to cause any confusion as there are no real life reasons to keep multiple copies of the same parameter in your configuration file. -Moving onto the DHCPv4 configuration elements, -the line defining interfaces parameter specifies a list -of network interfaces on which the server should listen. -Lists are opened and closed with square brackets, with elements -separated by commas. Had we wanted to listen on two interfaces, the line could -look like this: - -"interfaces": [ "eth0", "eth1" ], - -As "interfaces" is not the last parameter in the configuration, -a trailing comma is required. -A number of other parameters -follow. valid-lifetime defines for how long the addresses (leases) given out by the +Moving onto the DHCPv4 configuration elements, the very first few elements +define some global parameters. valid-lifetime defines for how long the addresses (leases) given out by the server are valid. If nothing changes, a client that got an address is allowed to use it for 4000 seconds. (Note that integer numbers are specified as is, without any quotes around them.) renew-timer and @@ -177,6 +170,20 @@ rebind procedures. Note that renew-timer and client will select values for T1 and T2 timers according to the RFC 2131. +The interfaces-config map specifies the server +configuration concerning the network interfaces, on which the server should +listen to the DHCP messages. The interfaces parameter +specifies a list of network interfaces on which the server should listen. +Lists are opened and closed with square brackets, with elements separated +by commas. Had we wanted to listen on two interfaces, the +interfaces-config would look like this: + +"interfaces-config": { + "interfaces": [ "eth0", "eth1" ] +}, + + + The next couple of lines define the lease database, the place where the server stores its lease information. This particular example tells the server to use memfile, which is the simplest (and fastest) database @@ -332,22 +339,40 @@ url="http://jsonviewer.stack.hu/"/>. -
- Interface selection +
+ Interface configuration The DHCPv4 server has to be configured to listen on specific network interfaces. The simplest network interface configuration tells the server to listen on all available interfaces: -"Dhcp4": { "interfaces": ["*"], ... } +"Dhcp4": { + "interfaces-config": { + "interfaces": [ "*" ] + } + ... +}, + The asterisk plays the role of a wildcard and means "listen on all interfaces". However, it is usually a good idea to explicitly specify interface names: -"Dhcp4": { "interfaces": [ "eth1", "eth3" ], ... } +"Dhcp4": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3" ] + }, + ... +} + It is possible to use wildcard interface name (asterisk) concurrently with explicit interface names: -"Dhcp4": { "interfaces": [ "eth1", "eth3", "*" ], ... } +"Dhcp4": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3", "*" ] + }, + ... +} + It is anticipated that this form of usage will only be used when it is desired to temporarily override a list of interface names and listen on all interfaces. @@ -357,10 +382,60 @@ temporarily override a list of interface names and listen on all interfaces. instance should be bound to a different address on the particular interface. In these situations, the address to use can be selected by appending an IPv4 address to the interface name in the following manner: - -"Dhcp4": { "interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ], ... } + +"Dhcp4": { + "interfaces-config": { + "interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ] + }, + ... +} + Note that only one address can be specified on each interface. + + Kea supports responding to directly connected clients which don't have + an address configured on the interface yet. This requires that the server + injects the hardware address of the destination into the data link layer + of the packet being sent to the client. The DHCPv4 server utilizes the + raw sockets to achieve this, and builds the entire IP/UDP stack for the + outgoing packets. The down side of raw socket use, however, is that incoming + and outgoing packets bypass the firewalls (e.g. iptables). It is also + troublesome to handle traffic on multiple IPv4 addresses assigned to the + same interface, as raw sockets are bound to the interface and advanced + packet filtering techniques (e.g. using the BPF) have to be used to + receive unicast traffic on the desired addresses assigned to the interface, + rather than capturing whole traffic reaching the interface to which the raw + socket is bound. Therefore, in the deployments where the server doesn't + have to provision the directly connected clients and only receives the + unicast packets from the relay agents, it is desired to configure the + DHCP server to utilize the IP/UDP datagram sockets, instead of raw sockets. + The following configuration demonstrates how this can be achieved: + + +"Dhcp4": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3" ], + "socket-type": "datagram" + }, + ... +} + + The socket-type specifies that the datagram sockets will + be opened on all interfaces on which the server listens, i.e. "eth1" and + "eth3" in our case. If the socket-type is set to + raw, it configures the server to use raw sockets + instead. If the socket-type value is not specified, the + default value raw is used. + + + + Specifying the value raw as the socket type, + doesn't guarantee that the raw sockets will be used! The use of raw sockets + to handle the traffic from the directly connected clients is currently + supported on Linux and BSD systems only. If the raw sockets are not + supported on the particular OS, the server will issue a warning and + fall back to use the datagram sockets. +
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 982921e96a..35031cca93 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -92,13 +92,17 @@ "Dhcp6": { # First we set up global values - "interfaces": [ "eth0" ], "renew-timer": 1000, "rebind-timer": 2000, "preferred-lifetime": 3000, "valid-lifetime": 4000, -# Next we specify the type of lease database +# Next we setup the interfaces to be used by the server. + "interfaces-config": { + "interfaces": [ "eth0" ] + }, + +# And we specify the type of a lease database "lease-database": { "type": "memfile", "persist": true, @@ -156,19 +160,8 @@ ignored. This is unlikely to cause any confusion as there are no real life reasons to keep multiple copies of the same parameter in your configuration file. -Moving onto the DHCPv6 configuration elements, -the line defining interfaces parameter specifies a list -of network interfaces on which the server should listen. -Lists are opened and closed with square brackets, with elements -separated by commas. Had we wanted to listen on two interfaces, the line could -look like this: - -"interfaces": [ "eth0", "eth1" ], - - -As "interfaces" is not the last parameter in the -configuration, a trailing comma is required. -A number of other parameters follow. valid-lifetime +Moving onto the DHCPv6 configuration elements, the very first few elements +define some global parameters. valid-lifetime defines for how long the addresses (leases) given out by the server are valid. If nothing changes, a client that got an address is allowed to use it for 4000 seconds. (Note that integer numbers are specified as is, without any quotes @@ -178,6 +171,20 @@ connections). renew-timer and rebind-timer are values that define T1 and T2 timers that govern when the client will begin the renewal and rebind procedures. +The interfaces-config map specifies the server +configuration concerning the network interfaces, on which the server should +listen to the DHCP messages. The interfaces parameter +specifies a list of network interfaces on which the server should listen. +Lists are opened and closed with square brackets, with elements separated +by commas. Had we wanted to listen on two interfaces, the +interfaces-config would look like this: + +"interfaces-config": { + "interfaces": [ "eth0", "eth1" ] +}, + + + The next couple of lines define the lease database, the place where the server stores its lease information. This particular example tells the server to use memfile, which is the simplest (and fastest) database @@ -339,19 +346,37 @@ JSON validator is available at .
Interface selection The DHCPv6 server has to be configured to listen on specific network - interfaces. The simplest network interface configuration tells the server to + interfaces. The simplest network interface configuration instructs the server to listen on all available interfaces: -"Dhcp6": { "interfaces": ["*"], ... } +"Dhcp6": { + "interfaces-config": { + "interfaces": [ "*" ] + } + ... +} + The asterisk plays the role of a wildcard and means "listen on all interfaces". However, it is usually a good idea to explicitly specify interface names: -"Dhcp6": { "interfaces": [ "eth1", "eth3" ], ... } - +"Dhcp6": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3" ] + }, + ... +} + + It is possible to use wildcard interface name (asterisk) concurrently - with explicit interface names: + with the actual interface names: -"Dhcp6": { "interfaces": [ "eth1", "eth3", "*" ], ... } +"Dhcp6": { + "interfaces-config": { + "interfaces": [ "eth1", "eth3", "*" ] + }, + ... +} + It is anticipated that this will form of usage only be used where it is desired to temporarily override a list of interface names and listen on all interfaces. @@ -413,23 +438,26 @@ temporarily override a list of interface names and listen on all interfaces. notation to specify interfaces has been extended. An interface name can be optionally followed by a slash, followed by the global unicast address on which the server should listen. This will be done in addition to normal - link-local binding + listening on ff02::1:2 address. The sample commands - listed below show how to listen on 2001:db8::1 (a global address) + link-local binding + listening on ff02::1:2 address. The sample configuration + below shows how to listen on 2001:db8::1 (a global address) configured on the eth1 interface. "Dhcp6": { - "interfaces": [ "eth1/2001:db8::1"], + "interfaces-config": { + "interfaces": [ "eth1/2001:db8::1" ] + }, ... -} +} + - When this configuration gets committed, the server will start to listen on + This configuration will cause the server to listen on eth1 on link-local address, multicast group (ff02::1:2) and 2001:db8::1. It is possible to mix interface names, wildcards and interface name/addresses - on the Dhcp6/interface list. It is not possible to specify more than one + on the list of interfaces. It is not possible to specify more than one unicast address on a given interface. @@ -1771,7 +1799,9 @@ should include options from the isc option space: such a configuration: "Dhcp6": { - "interfaces": [ "ethX" ], + "interfaces-config": { + "interfaces": [ "ethX" ] + }, "option-data": [ { "name": "dns-servers", "data": "2001:db8::1, 2001:db8::2"