(module-dhcp)=
# DHCP Configuration Module

DHCP configuration module implements DHCP clients, servers, and relays for IPv4 and IPv6.

```eval_rst
.. contents:: Table of Contents
   :depth: 2
   :local:
   :backlinks: none
```

(dhcp-platform)=
## Platform Support

DHCP clients are supported on these platforms:

| Operating system      | IPv4 | IPv6 | Default<br>route | Routing over<br>DHCP interfaces |
| --------------------- | :-: | :-: | :-: | :-: |
| Arista EOS            | ✅ [❗](caveats-eos) |  ❌  | ✅  |  ❌ [❗](caveats-eos) |
| Cisco IOSv            | ✅  | ✅  | ✅  | ✅  |
| Cisco IOS XE          | ✅  | ✅  | ✅  | ✅  |
| Cumulus Linux         | ✅  | ✅  |  ❌  | ✅  |
| Linux (Ubuntu VM only)| ✅  | ✅  |  ❌  |  ❌  |

DHCP servers are supported on these platforms: 

| Operating system      | IPv4 | IPv6 | VRF-aware |
| --------------------- | :-: | :-: | :-: |
| Arista EOS            | ✅  | ✅  |  ❌  |
| Cisco IOSv            | ✅  | ✅  |  ❌  |
| Cisco IOS XE          | ✅  | ✅  | ✅  |
| dnsmasq               | ✅  | ✅  |  ❌  |
| Linux (Ubuntu VM only)| ✅  | ✅  |  ❌  |

DHCP relays are supported on these platforms: 

| Operating system      | IPv4 | IPv6 | VRF-aware |
| --------------------- | :-: | :-: | :-: 
| Arista EOS            | ✅  | ✅  | ✅ [❗](caveats-eos) |
| Cisco IOSv            | ✅  | ✅  | ✅  |
| Cisco IOS XE          | ✅  | ✅  | ✅  |
| Cumulus Linux         | ✅ [❗](linux-dhcp-relay) |  ❌  |  ❌  |
| Linux (Ubuntu VM only)| ✅ [❗](linux-dhcp-relay)  |  ❌  |  ❌  |

```{tip}
* VRF-aware DHCP relays use DHCP options specified in RFC 6607.
* VRF-aware DHCP servers can use DHCP options specified in RFC 6607 to select the client subnet.
```

(dhcp-parameters)=
## Node Parameters

The DHCP module supports the following node parameters:

* **dhcp.server** (boolean) -- the device should run a DHCP server
* **dhcp.vrf** (boolean) -- the DHCP relay or server should be VRF-aware. The default value of this parameter is set to _true_ if the node performs inter-VRF DHCP relaying or has DHCP pools from VRF subnets. To override that behavior, you can set **dhcp.vrf** to _false_.

```{tip}
You have to set **‌dhcp.vrf** to _False_ on a Cisco IOS XE DHCP server when you use it with Arista EOS VRF-aware relays ([more details](https://blog.ipspace.net/2023/03/netlab-vrf-dhcp-relay.html)).
```
 
## Interface Parameters

* To start a DHCP client on an interface, set **ipv4** or **ipv6** address to **dhcp**.
* The DHCP client usually installs a default route to an IPv4 default gateway[^DGv6] sent in a DHCP reply. To disable this functionality, set **dhcp.client.default** interface parameter to `False`.
* To start a DHCP relay on an interface, set **dhcp.server** interface parameter to a list of DHCP servers.
* To enable inter-VRF DHCP relaying, set the **dhcp.vrf** interface parameter to the name of the destination VRF (or **global**).

[^DGv6]: DHCPv6 does not have a *default gateway* option. IPv6 needs _router advertisements_ generated by an adjacent router.

## Implementation Notes

* The **dhcp** module is automatically enabled for nodes with DHCP clients. You don't have to specify it in the **module** list. However, at least one topology node must use the **dhcp** module to enable _netlab_ to recognize **dhcp** as a valid IPv4 or IPv6 address.
* You must enable the **dhcp** module on DHCP relays and servers.
* *dnsmasq* always uses the **dhcp** module and is configured as a DHCP server. There's no need to set the **module** or **dhcp.server** node variable.

## Examples

The following topology starts IPv4 DHCP clients on Cumulus Linux and Cisco IOSv and a DHCP server on Arista EOS:

```
nodes:
  r1:
    device: iosv
  r2:
    device: cumulus
  srv:
    device: eos
    module: [ dhcp ]
    dhcp.server: True

links:
- r1:
    ipv4: dhcp
  r2:
    ipv4: dhcp
  srv:
```

The following topology uses *dnsmasq* DHCP server and starts IPv4 and IPv6 DHCP clients on Arista EOS:

```
provider: clab

addressing.lan.ipv6: 2001:db8:cafe::/48

nodes:
  client:
    device: eos
  server:
    device: dnsmasq

links:
- client:
    ipv4: dhcp
    ipv6: dhcp
  server:
```

The following topology uses DHCP relaying on an Arista EOS switch to propagate DHCP requests from Cumulus Linux clients to a *dnsmasq* DHCP server.

```
provider: clab

module: [ dhcp ]

nodes:
  client:
    device: cumulus
  relay:
    device: eos
  server:
    device: dnsmasq

links:
- client:
    ipv4: dhcp
  relay:
    dhcp.server: server
- relay-server
```