DHCP Configuration Module

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

Platform Support

DHCP clients are supported on these platforms:

Operating system	IPv4	IPv6	Default route	Routing over DHCP interfaces
Arista EOS	✅ ❗	❌	✅	❌ ❗
Cisco IOSv/IOSvL2	✅	✅	✅	✅
Cisco IOS XE[1]	✅	✅	✅	✅
Cumulus Linux	✅	✅	❌	✅
Linux (Ubuntu VM only)	✅	✅	❌	❌

DHCP servers are supported on these platforms:

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

DHCP relays are supported on these platforms:

Operating system	IPv4	IPv6	VRF-aware
Arista EOS	✅	✅	✅ ❗
Cisco IOSv/IOSvL2	✅	✅	✅
Cisco IOS XE[1]	✅	✅	✅
Cumulus Linux	✅ ❗	❌	❌
Linux (Ubuntu VM only)	✅ ❗	❌	❌

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.

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 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).

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), do not use DHCP on routed VLANs.
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).

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[2] 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).

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.

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 or set by the 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

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