Changes between Version 16 and Version 17 of ReconfigureFeatureDesign

Aug 17, 2018, 11:12:40 PM (15 months ago)



  • ReconfigureFeatureDesign

    v16 v17  
    11= Design for DHCPv6 Reconfiguration Feature (GSOC 2018) =
    3 == Scope ==
    5 The Document describes the administrator's operational steps, internal mechanism for handling the reconfiguration  along with command design and configuration changes. A brief introduction and requirement for the reconfigure feature can be found at [[wiki:ReconfigureRequirements]].
    7 == Operation steps for the admin and Server's internal mechanism for Reconfiguration operation ==
    9 === Step 1 The Admin shall enable the Reconfigure feature through a flag(mandatory) and configure Keys for the clients in the host reservation(optional). ===
    10 This is necessary prior to at least T1 and T2 expiry of the clients which needs to be reconfigured. This ensures Keys are exchanged during the Replies for the Renew, Rebind requests.
    11 '''Internal mechanism:''' The Kea server shall use the host reservation for storing the keys for clients. Once the feature is enabled through internal flag any replies by the server as specified in the RFC shall contain keys needed for reconfiguration. If the Keys are not defined by the admin the server shall generate solely based on the feature flag enabled. The generated keys shall be stored in the host reservation internally. If no host reservation is defined for the client a new host reservation shall be defined which shall only contain keys.
    13 The key generation shall be done when the server parses option reconfigure accept as specified in the RFC. This indicates the client is willing to accept the Reconfiguration message.
    15 Transmission of reconfigure message must be unicast as specified in the RFC. So its necessary to store the link local address and the interface to which the client is connected for sending the reconfigure message (relays are not discussed as of now).
    16 This will finally result in having host reservation defined for every client in the network once the feature is enabled.
    18 === Step 2 Admin applies new configuration with new Subnet/ DNS Server, FQDN, NTP servers. The admin shall issue a command to the Kea server with arguments of renew, rebind, information request for a set of clients.  ===
    20 '''Internal mechanism:''' The server upon receiving the request shall reduce the lifetime of the assigned leases immediately for the clients(This step could have been executed while processing the Renew/Rebind Request however it could be possible that client might not respond at all due to various reasons. This method hence ensures the IP addresses validity expires regardless of the client's response). The preferred lifetime shall be set to 0, valid lifetime shall be set to a random value less than T1 but greater than the maximum time required for the client to respond to the Reconfigure message.
    21 * The server shall maintain a list of clients for which has been listed for Reconfiguring the client.  This list will be useful for deciding during processing of the requests of the clients described later.
    22 * The server will construct the reconfigure message.
    23 * The server will calculate MD5 checksum for the Reconfigure message using the existing keys and openssl api and populate the authentication field. If the keys are missing/ corrupt the server shall abort the transmission of reconfigure message to the particular client and resume sending Reconfigure message for the other clients.
    25 ''Typical use cases where the admin shall use the Reconfigure message options''
    27  * The admin shall issue option of Renew when there is a Subnet / IP address change in the network
    28  * The admin shall issue option of Rebind when there the server will no longer serve clients and the new leases shall be issued by the other servers in the network.
    29  * The admin shall issue option of information request when there is a change in the DNS server,  NTP server, FQDN updates, vendor-specific options.
    32  === Step 3   The client processes the Reconfigure message and sends a Renew/ Rebind / Information  Request to the server. ===
    34 '''Internal mechanism:''' The server upon receiving the Renew / Rebind. Discovers that the message is not from a valid subnet(since the configuration has been updated). The server checks if the client is on the list of clients it sent Reconfigure message. If it's true then the server shall include multiple addresses/prefixes in the IA. It shall contain 2 set of addresses. One set of address having reduced valid lifetime of old IP and zero preferred lifetime which is extracted from the lease, next set of address with new IP and configured valid and preferred lifetime extracted from the configuration. The server will assign a new lease to the address/prefix assigned. In this way, the old lease shall expire gracefully and the client will be assigned to the new lease. These multiple addressed/prefixes are sent in the Reply message of the server. 
    38 == Command Examples ==
    39 There are 3 cases to be supported here:
    41 === Use case 1: Send reconfigure to a single client ===
    43 Proposed command syntax:
    45 {{{
    46 {
    47     “command” :  “send-reconfigure"
    48     "arguments":  {
    49         "duid": "01:02:03:04:05:06:07:08",
    50         "subnet-id": 123,
    51         "reconfigure-mode": "renew"
    52     }
    53 }
    54 }}}
    56 Proposed response syntax:
    58 {{{
    59 {
    60     "result": 0,
    61     "text": "Reconfigure procedure initiated: RENEW message sent to IP address 2001:db8::123\
    62              to a client with duid 01:02:03:04:05:06:07:08"
    63 }
    64 }}}
    66 or
    68 {{{
    69 {
    70     "result": 1,
    71     "text": "Unable to send Reconfigure: no such client currently active"
    72 }
    73 }}}
    75 Note that reconfigure-mode takes one of three values: renew, rebind, inf-request. The parameter is optional. If not specified, "renew" value is assumed.
    77 === Use case 2: Send reconfigure to all clients in a single subnet ===
    79 Proposed command syntax:
    81 {{{
    82 {
    83     “command” :  “send-reconfigure"
    84     "arguments":  {
    85         "subnet-id": 123,
    86         "reconfigure-mode": "renew"
    87     }
    88 }
    89 }}}
    91 Note that reconfigure-mode takes one of three values: renew, rebind, inf-request. The parameter is optional. If not specified, "renew" value is assumed.
    93 Proposed response syntax:
    94 {{{
    95 {
    96     "result": 0,
    97     "text": "Reconfigure procedure initiated: Sent REBIND message(s) to 5 clients, skipped\
    98              2 clients due to not having keys or not supporting reconfigure.",
    99     "reconf-success": 5,
    100     "reconf-skip": 2,
    101     "client-duids": [ "01:02:03:04", "aa:bb:cc:dd:ee", "1a:2b:3c:4d:5e:6f" ]
    102 }
    103 }}}
    105 === Use case 3: Send reconfigure to all clients in all subnets ===
    107 Proposed command syntax:
    109 {{{
    110 {
    111     “command” :  “send-reconfigure"
    112     "arguments":  {
    113         "reconfigure-mode": "renew"
    114     }
    115 }
    116 }}}
    118 Note that reconfigure-mode takes one of three values: renew, rebind, inf-request. The parameter is optional. If not specified, "renew" value is assumed. If reconfigure-mode is not specified, the whole arguments scope can be omitted.
    120 Proposed response syntax is the same as for use case 2.
    122 == Proposed Configuration ==
    124 Existing Host structures will be extended to be able to store reconfigure keys, linklocal, interface. This field will be optional. If specified, Kea will use that specific value. If not specified, kea will generate a random key and will set that value in existing host reservation. The server stores the linklocal addresses and interface as it parses the Reconfig Accept Option in Solicit, Request, Renew, Rebind, Information Request message.
    125 {{{
    127 "reservations":  [
    128 {
    129     “duid”: "01:02:03:04:05:0A:0B:0C:0D:0E",
    130      “key”: “<128_BIT_KEY>”,   
    131      "iface": "eth1",
    132      "link-local":"FE80::01"
    133 }
    134 ]
    135 }}}
    137 Note: The feature will work best with host backends configured (mysql, postgres or cassandra). Without backend configured, Kea will update its in-memory information about host reservations. These will be lost after restart or shutdown, unless administrator saves them using config-write command or retrieves them and stores them somewhere using config-get command.
    139 == Required code changes ==
    140 1) Support for keys storage in Host objects and backend databases.
    141 2) Extend parser to be able to parse keys.
    142 3) Support of auth option.
    143 4) Support for reconfigure-send (use cases 1,2 and 3) in dhcpsrv.
    144 5) Implement support of storing interface info and link local ip of the client in user context needed for reconfiguration.
    145 6) Implement parsing reconfigure accept options and sending reconfigure accept option in the messages.
    146 5
    148 == Tasks ==
    149 Normally we would list the tasks here (see [ radius desing] for example). However, since we're experimenting with github, there's a dedicated project for tracking this: [ github project].
    151 ===Completed task===
    153 1. Handle Reconfigure Accept Option(review ongoing)
    156 2. Extend host structure to hold keys
    159 3. Implement Authentication options in DHCPv6 messages
    162 4. Implement optimized query
    165 === Pending task ===
    166 5. Packaging and sending reconfigure message (testing ongoing)
    168 ===  Further enhancement ===
    169 6. Extending current implementation to multiple clients. (to be done after all code is merged to master).
     3Please see