Limiting DHCP DECLINE

Background

Scenario

In any IP network, an IP address which is nominally available for use may actually be in use by a misbehaving node. A DHCP server may unknowingly offer that same IP address to another client.

The DHCP protocol anticipated this, and specifies that any DHCP client should attempt to verify that a newly received IP address is available. Typically, the client performs a gratuitous ARP (ARP probe), requesting to know who has the IP address in question. If the DHCP client receives a reply to that ARP, it knows that the IP address is already in use (duplicate address assignment). The DHCP client is then required to send a DECLINE message to the DHCP server, to inform the server.

Kea DECLINE handling

When Kea receives a DECLINE message, it performs several actions:

Logs the event (DCHP4_DECLINE_LEASE or DCHP6_DECLINE_LEASE)
Removes any lease assignment record for the address
If DHCP-DDNS (D2) is in use, sends DNS DELETE messages to remove any DNS records associated with the IP address
Triggers any associated hooks
Marks the IP address as "on probation"

Kea will not offer an IP address which is on probation. This prevents Kea from repeatedly offering an IP address which a misbehaving client is already using. IP addresses are removed from probation after a set amount of time; see the "Probation Period" section below for more details.

Incorrect DECLINE messages

A different type of misbehaving client may incorrectly send a DECLINE message, even though there is nothing else using the IP address. If the client repeatedly retries, it may loop in a cycle of requesting a lease and then declining it; this can lead to pool depletion or exhaustion, as all IP addresses are put on probation.

Two countermeasures are offered here. Either or both may be employed, based on the judgement and needs of the network operator.

Probation Period

The Kea configuration parameter decline-probation-period controls how long each DECLINEd IP address is kept on probation. The default is 24 hours. In an environment without strong control of client configuration (such as most ISPs and public networks), this may be unreasonably long. Operators will need to judge the risk of duplicate addresses against the risk of incorrect declines for their environment, but values well under an hour are often appropriate. The value is specified in seconds.

Limiting DECLINE Rate

Limiting how often a single client can put an IP address on probation is another alternative. This uses slightly more resources on the server, but still allows well-behaved clients to report duplicate addresses.

It is possible to create a client class definition which tests for the DECLINE message type, and puts any such client into the class by MAC address. By combining this with the limits hook, one can tell Kea to ignore clients that are sending repeated DECLINE messages.

The following extract from a kea-dhcp4.conf file provides an example configuration:

"client-classes": [
  {
    "name": "declines",
    "template-test": "ifelse(pkt4.msgtype == 4, hexstring(pkt4.mac, ':'), '')",
    "user-context": {
      "limits": {
        "rate-limit": "3 packets per hour"
      }
    }
  }
]

As you may gather, that will prevent any single client (MAC address) from declining more than three IP addresses per hour. Adjust the rate limit as appropriate for your environment.

For IPv6/DHCPv6, the template-test will instead need to specify pkt6.msgtype == 9.