From: Marcin Siodelski Date: Wed, 13 May 2015 13:41:47 +0000 (+0200) Subject: [3747] Updated User Guide with the match-client-id config examples. X-Git-Tag: trac3867_base~2^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fa00f7c6fdd1441da90ababb50e77ad3c3c8b430;p=thirdparty%2Fkea.git [3747] Updated User Guide with the match-client-id config examples. --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 41bd5852a0..603df6e9f7 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -1950,6 +1950,171 @@ temporarily override a list of interface names and listen on all interfaces. +
+ Using Client Identifier and Hardware Address + DHCP server must be able to identify the client (distinguish it from + other clients) from which it receives the message. There are many reasons + why this identification is required and the most important ones are listed + below. + + When the client contacts the server to allocate a new + lease, the server must store the client identification information in + the lease database as a search key. + When the client is trying to renew or release the existing + lease, the server must be able to find the existing lease entry in the + database for this client, using the client identification information as a + search key. + Some configurations use static reservations for the IP + addreses and other configuration information. The server's administrator + uses client identification information to create these static assignments. + + In the dual stack networks there is often a need to + correlate the lease information stored in DHCPv4 and DHCPv6 server for + a particular host. Using common identification information by the DHCPv4 + and DHCPv6 client allows the network administrator to achieve this + correlation and better administer the network. + + + + The DHCPv4 makes use of two distinct identifiers which are placed + by the client in the queries sent to the server and copied by the server + to its responses to the client: 'chaddr' and 'client identifier'. The + former was introduced as a part of the BOOTP specification and it is also + used by DHCP to carry the hardware address of the interface used to send + the query to the server (MAC address for the Ethernet). The latter is + carried in the Client-identifier option, introduced in the + RFC 2132. + + + The RFC 2131 + indicates that the server may use both of these identifiers to identify + the client but the 'client identifier', if present, takes precedence + over 'chaddr'. One of the reasons for this is that 'client identifier' + is independent from the hardware used by the client to communicate with + the server. For example, if the client obtained the lease using one + network card and then the network card is moved to another host, the + server will wrongly identify this host is the one which has obtained + the lease. Moreover, the + RFC 4361 gives + the recommendation to use DUID + (see DHCPv6 specification) + carried as 'client identifier' when dual stack networks are in use, + to provide consistent identification information of the client, regardless + of the protocol type it is using. Kea adheres to these specifications and + the 'client identifier' by default takes precedence over the value carried + in 'chaddr' field when the server searches, creates, updates or removes + the client's lease. + + + When the server receives DHCPDISCOVER or DHCPREQUEST message from the + client, it will try to find out if the client already has a lease in the + database and will hand out the existing lease rather than allocate + a new one. Each lease in the lease database is associated with the + 'client identifier' and/or 'chaddr'. The server will first use the + 'client identifer' (if present) to search the lease. If the lease is + found, the server will consider that this lease belongs to this client, + regardless if the current 'chaddr' and the 'chaddr' associated with + the lease match. This facilitates the scenario when the network card + on the client system has been replaced and thus the new MAC address + appears in the messages sent by the DHCP client. If the server fails + to find the lease using the 'client identifier' it will use the 'chaddr' + and will perform another lookup. If this lookup returns no result, the + client is considered to not have a lease and the new lease will + be created. + + + A common problem reported by the network operators is that bogus + client implementations do not use stable client identifiers, e.g. + new 'client identifier' is generated every time when the client connects + to the network. Another well known case is when the client changes its + 'client identifier' during the multi-stage boot process (PXE). In those + cases, the MAC address of the client's interface remains stable and + using 'chaddr' field to identify the client guarantees that the + particular system is considered to be the same client, even though its + 'client identifier' gets changed. + + + To address this problem Kea includes a configuration option + which enables client identification using 'chaddr' and causes the + server to "ignore" the 'client identifier' during the lease lookup + and allocation for a particular subnet. Consider the following + simplified server configuration: + +"Dhcp4": { + ... + "match-client-id": true, + ... + "subnet4": [ + { + "subnet": "192.0.10.0/24", + "pools": [ { "pool": "192.0.2.23-192.0.2.87" } ], + "match-client-id": false + }, + { + "subnet": "10.0.0.0/8", + "pools": [ { "pool": "10.0.0.23-10.0.2.99" } ], + } + ] +} + + + The match-client-id is a boolean value which + controls this behavior. The default value of true + indicates that the server will use the 'client identifier' for lease + lookups and 'chaddr' if the first lookup returns no results. The + false means that the server will only + use the 'chaddr' to search for client's lease. Whether the DHCID for + DNS updates is generated from the 'client identifier' or 'chaddr' is + controlled through the same parameter accordingly. + + The match-client-id parameter may appear + both in the global configuration scope and/or under any subnet + declaration. In the example shown above, the effective value of the + match-client-id will be false + for the subnet 192.0.10.0/24, because the subnet specific setting + of the parameter overrides the global value of the parameter. The + effective value of the match-client-id for the subnet + 10.0.0.0/8 will be set to true because the + subnet declaration lacks this parameter and the global setting is + by default used for this subnet. In fact, the global entry for this + parameter could be omitted in this case, because + true is the default value. + + + It is important to explain what happens when the client obtains + its lease for one setting of the match-client-id + and then renews when the setting has been changed. Let's first consider + the case when the client obtains the lease when the + match-client-id is set to true. + The server will store the lease information including 'client identifier' + (if supplied) and 'chaddr' in the lease database. When the setting is + changed and the client renews the lease the server will determine that + it should use the 'chaddr' to search for the existing lease. If the + clien't hasn't changed its MAC address the server should successfully + find the existing lease. The 'client identifier' associated with the + returned lease is ignored and the client is allowed to use this lease. + When the lease is renewed only the 'chaddr' is recorded for this + lease according to the new server setting. + + + In the second case the client has the lease with only a 'chaddr' + value recorded. When the setting is changed to + match-client-id set to true + the server will first try to use the 'client identifier' to find the + existing client's lease. This will return no results because the + 'client identifier' was not recorded for this lease. The server will + then use the 'chaddr' and the lease will be successfully found. If the + lease appears to have no 'client identifier' recorded, the server will + assume that this lease belongs to the client and that it was created + with the previous setting of the match-client-id. + However, if the lease contains 'client identifier' which is different + from the 'client identifier' used by the client the lease will be + assumed to belong to another client and the new lease will be + allocated. + + +
+