(module-dhcp)=
# DHCP Configuration Module

The 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/IOSvL2     | ✅  | ✅  | ✅  | ✅  |
| Cisco IOS XE[^18v]    | ✅  | ✅  | ✅  | ✅  |
| Cumulus Linux         | ✅  | ✅  |  ❌  | ✅  |
| Linux (Ubuntu VM only)| ✅  | ✅  |  ❌  |  ❌  |

[^18v]: Includes Cisco CSR 1000v, Cisco Catalyst 8000v, Cisco IOS-on-Linux (IOL), and IOL Layer-2 image.

DHCP servers are supported on these platforms: 

| Operating system      | IPv4 | IPv6 | VRF-aware |
| --------------------- | :-: | :-: | :-: |
| Arista EOS            | ✅  | ✅  |  ❌  |
| Cisco IOSv/IOSvL2     | ✅  | ✅  |  ❌  |
| Cisco IOS XE[^18v]    | ✅  | ✅  | ✅  |
| dnsmasq               | ✅  | ✅  |  ❌  |
| Linux (Ubuntu VM only)| ✅  | ✅  |  ❌  |

DHCP relays are supported on these platforms: 

| Operating system      | IPv4 | IPv6 | VRF-aware |
| --------------------- | :-: | :-: | :-: 
| Arista EOS            | ✅  | ✅  | ✅ [❗](caveats-eos) |
| Cisco IOSv/IOSvL2     | ✅  | ✅  | ✅  |
| Cisco IOS XE[^18v]    | ✅  | ✅  | ✅  |
| 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. _netlab_ [automatically configures the DHCP pools](dhcp-pools) on the device.
* **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. You can override that behavior by setting **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)).
```

(dhcp-parameters-link)=
## Link Parameters

You can enable the DHCP client on all non-relaying devices attached to a link with the boolean **dhcp.client.ipv4** link attribute and the DHCPv6 client with the boolean **dhcp.client.ipv6** attribute.

```{warning}
* While you can use the **‌dhcp.client** parameter to enable DHCP for all hosts attached to a VLAN segment ([see example](dhcp-vlan-example)), do not use DHCP on [routed VLANs](vlan-addressing-routed).
* You cannot use **‌dhcp.client** link/VLAN parameter to enable the DHCP client on a VLAN interface. You have to enable the DHCP client on an IRB VLAN interface within the node **‌vlans** dictionary ([more details](vlan-interface-parameters)).
```

## Interface Parameters

* To start a DHCP client on an interface, set the **ipv4** or **ipv6** address to **dhcp**. You can use the **dhcp.client.ipv4** or the **dhcp.client.ipv6** interface attribute only when the node already uses the DHCP module. 
* The DHCP client usually installs a default route to an IPv4 default gateway[^DGv6] sent in a DHCP reply. To turn off this functionality, set **dhcp.client.default** interface parameter to `False`.
* To start a DHCP relay on an interface, set the **dhcp.server** interface parameter to a list of DHCP servers (node names). The nodes listed in the **dhcp.server** parameter must have the **dhcp.server** node attribute set. An interface running a DHCP relay cannot use a DHCP client; the **dhcp.client** attribute (when specified) is removed from the interface.
* 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.

(dhcp-pools)=
## Building DHCP Pools

_netlab_ automatically builds DHCP pools from the DHCP client information and configures them on all DHCP servers:

* A pool using the link/VLAN prefix is created for every subnet (link or VLAN) with at least one DHCP client attached.
* The link/VLAN **vrf** information is copied into the DHCP pool in case the DHCP server supports VRF-aware DHCP.
* The link/VLAN IPv4 default gateway ([computed](links-gateway) or set by the **[gateway](module-gateway)** module) is copied into the DHCP pool as DHCP Default Router (DHCP option 3)
* The pool name is derived from the link/VLAN name.
* All other nodes attached to the link/VLAN are configured as *excluded addresses*.

## 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 DHCP pool is configured on the **srv** DHCP server:

```
dhcp server
  subnet 172.16.0.0/24
    range 172.16.0.1 172.16.0.254
    name links[1]
    reservations
      mac-address 0000.0000.2
        ipv4-address 172.16.0.3
```

```{tip}
Please note that the MAC address in the DHCP **‌reservations** does not match the device's MAC address. Arista EOS does not implement *‌excluded addresses*, so we have to configure static DHCP mapping for a bogus MAC address.
```

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
```

(dhcp-vlan-example)=
The following example enables the DHCP client on all hosts attached to a VLAN and the DHCP relay on the access switch:

```
provider: libvirt

defaults.device: eos

vlans:
  red:
    dhcp.client.ipv4: True
    links: [ s1-h1, s1-h2 ]

nodes:
  s1:
    module: [ dhcp, vlan ]
    vlans:
      red:
        dhcp.server: dhs
  h1:
    device: linux
  h2:
    device: linux
  dhs:
    device: dnsmasq
    provider: clab

links:
- s1-dhs
```