From: Marcin Siodelski Date: Wed, 18 Nov 2015 13:18:46 +0000 (+0100) Subject: [3874] Described configuration of the server identifier in the User Guide. X-Git-Tag: trac4231_base~39^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=965e20322015b4352805231e9d3cd33bb8f56911;p=thirdparty%2Fkea.git [3874] Described configuration of the server identifier in the User Guide. --- diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 11002006b0..e613e518c0 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2352,27 +2352,212 @@ should include options from the isc option space: Server Identifier in DHCPv6 The DHCPv6 protocol uses a "server identifier" (also known as a DUID) for clients to be able to discriminate between several - servers present on the same link. There are several types of - DUIDs defined, but RFC 3315 instructs servers to use DUID-LLT if - possible. This format consists of a link-layer (MAC) address and a - timestamp. When started for the first time, the DHCPv6 server will - automatically generate such a DUID and store the chosen value to - a file. That file is read by the server - and the contained value used whenever the server is subsequently started. - - - It is unlikely that this parameter should ever need to be changed. - However, if such a need arises, stop the server, edit the file and restart - the server. (The file is named kea-dhcp6-serverid and by default is - stored in the "var" subdirectory of the directory in which Kea is installed. - This can be changed when Kea is built by using "--localstatedir" - on the "configure" command line.) The file is a text file that contains - double digit hexadecimal values - separated by colons. This format is similar to typical MAC address - format. Spaces are ignored. No extra characters are allowed in this - file. + servers present on the same link. + RFC 3315 + defines three DUID types: DUID-LLT, DUID-EN and DUID-LL. + RFC 6355 + also defines DUID-UUID. Future specifications may introduce new + DUID types. + + Kea DHCPv6 server generates a server identifier once, upon + the first startup, and stores it in a file. This identifier isn't + modified across restarts of the server (stable identifier). + + Kea follows recommendation from + RFC 3315 + to use DUID-LLT as a default server identifier. However, we have + received reports that some deployments require different DUID + types, and there is a need to administratively select both DUID + type and/or its contents. + + The server identifier can be configured using parameters + within the server-id map element in the global + scope of the Kea configuration file. The following example + demonstrates how to select DUID-EN as a server identifier: + + +"Dhcp6": { + "server-id": { + "type": "EN" + }, + ... +} + + + + + Currently supported values for type + parameter are: "LLT", "EN" and "LL", for DUID-LLT, DUID-EN and + DUID-LL respectively. + + When a new DUID type is selected the server will generate its + value and replace any existing DUID in the file. The server will + use the new server identifier in all future interactions with the + clients. + + If the new server identifier is created after some clients + have obtained their leases, the clients using old identifier will not + be able to renew the leases. The server will ignore messages + containing the old server identifier. Clients will continue sending + Renew until they transition to rebinding state. In this state they + will start sending Rebind messages to multicast address and without + a server identifier. The server will respond to the Rebind messages + with a new server identifier and the clients will associate the + new server identifier with their leases. Although the clients will + be able to keep their leases and will eventually learn the new server + identifier, this will be at the cost of increased number of renewals + and multicast traffic due to a need to rebind. Therefore it is + recommended to avoid modification of the server identifier type + and its value if the server has already assigned leases and these + leases are still valid. + + There are cases when an administrator needs to explicitly + specify a DUID value, rather than allow the server to generate it. + The following example demonstrates how to explicitly set all + components of a DUID-LLT. + + +"Dhcp6": { + "server-id": { + "type": "LLT", + "htype": 8, + "identifier": "A65DC7410F0568", + "time": 2518920166 + }, + ... +} + + + where: + + htype is a 16-bit unsigned value + specifying hardware type, + identifier is a link layer + address, specified as a string of hexadecimal digits, + + time is a 32-bit unsigned + time value. + + + + The hexadecimal representation of the DUID generated as a result + of the configuration specified above will be: + +00:01:00:08:96:23:AB:E6:A6:5D:C7:41:0F:05:68 +-------------------------------------------- +|type|htype| time | identifier | + + + + It is allowed to use special value of 0 for "htype" and "time", + which indicates that the server should use ANY value for these + components. If the server already uses a DUID-LLT it will use the + values from this DUID. If the server uses a DUID of a different type + or doesn't use any DUID yet, it will generate these values. + Similarly, if the "identifier" is assigned an empty string, the + value of the identifier will be generated. Omitting any of these + parameters is equivalent to setting them to those special values. + + + For example, the following configuration: + +"Dhcp6": { + "server-id": { + "type": "LLT", + "htype": 0, + "identifier": "", + "time": 2518920166 + }, + ... +} + + + indicates that the server should use ANY link layer address and + hardware type. If the server is already using DUID-LLT it will + use link layer address and hardware type from the existing DUID. + If the server is not using any DUID yet, it will use link layer + address and hardware type from one of the available network + interfaces. The server will use explicit value of time. If it + is different than a time value present in the currently used + DUID, this value will be replaced. This will effectively cause + modification of the current server identifier. + + + + The following example demonstrates an explicit configuration of + a DUID-EN: + + +"Dhcp6": { + "server-id": { + "type": "EN", + "enterprise-id": 2495, + "identifier": "87ABEF7A5BB545", + }, + ... +} + + + where: + + enterprise-id is a 32-bit + unsigned value holding enterprise number, + identifier is a variable + length identifier within DUID-EN. + + + + + The hexadecimal representation of the DUID-EN created accoring to + the configuration above is: + +00:02:00:00:09:BF:87:AB:EF:7A:5B:B5:45 +-------------------------------------- +|type| ent-id | identifier | + + As in the case of the DUID-LLT, special values can be used for the + configuration of the DUID-EN. If the "enterprise-id" is 0, the server + will use a value from the existing DUID-EN. If the server is not using + any DUID or the existing DUID has a different type, the ISC enterprise + id will be used. When an empty string is used for "identifier", the + identifier from the existing DUID-EN will be used. If the server is + not using any DUID-EN the new 6-bytes long identifier will be generated. + + + DUID-LL is configured in the same way as DUID-LLT with an exception + that the time parameter has no effect for DUID-LL, + because this DUID type only comprises a hardware type and link layer + address. The following example demonstrates how to configure DUID-LL: + + +"Dhcp6": { + "server-id": { + "type": "LL", + "htype": 8, + "identifier": "A65DC7410F0568", + }, + ... +} + + + + + + which will result in the following server identifier: + + +00:03:00:08:A6:5D:C7:41:0F:05:68 +--------------------------------- +|type|htype| identifier | + + + + Server stores a generated server identifier in the following + location: [kea-install-dir]/var/kea/kea-dhcp6-serverid + . +