DHCPv4 server — shared-network, subnet, range, options

A VyOS router runs an embedded DHCP server that hands out addresses, default gateways, DNS resolvers, NTP servers, and any other DHCP option that the network needs. The server listens for client broadcasts on UDP 67/68 and tracks each lease until it expires or is renewed.

This lesson is the canonical reference for the IPv4 DHCP server on VyOS 1.5 LTS (circinus). It covers the four-message exchange, the configuration tree under service dhcp-server, the shared-network / subnet / range / option structure, and the production failure modes where the server silently stops issuing leases.

The four-message exchange

sequenceDiagram
  autonumber
  participant H as Host
  participant S as Server
  participant N as Network

  H->>N: DHCPDISCOVER broadcast UDP 68 to 67
  N->>S: forward to server
  S-->>H: DHCPOFFER unicast or broadcast<br/>yaddr 192.0.2.50, lease 86400s
  H->>N: DHCPREQUEST broadcast
  N->>S: forward
  S-->>H: DHCPACK<br/>yaddr 192.0.2.50, mask 255.255.255.0<br/>router 192.0.2.1, dns 192.0.2.53
  Note over H,S: Host installs lease and renews at T1/T2

The exchange is Discover / Offer / Request / Ack. The client broadcasts because it does not yet have an address and cannot otherwise reach the server. Once the lease is installed, the host sends unicast DHCPREQUEST at the T1 timer (50 percent of the lease time by default) to renew without broadcast.

The shared-network / subnet / range / option structure

The VyOS configuration tree follows Kea’s own object model:

flowchart TB
  SN["shared-network-name LAN1<br/>subnets that sit on one physical link"]
  SN --> S1["subnet 192.0.2.0/24<br/>subnet-id 1"]
  SN --> S2["subnet 198.51.100.0/25<br/>subnet-id 2"]
  S1 --> R1["range LAN1-POOL<br/>start 192.0.2.50 stop 192.0.2.200"]
  S1 --> O1["option<br/>default-router 192.0.2.1<br/>name-server 192.0.2.53<br/>domain-name example.com"]
  S2 --> R2["range OVERFLOW<br/>start 198.51.100.10 stop 198.51.100.120"]
  S2 --> O2["option<br/>default-router 198.51.100.1"]

A shared-network-name is Kea’s “these subnets are on the same physical link” grouping. That is a stronger statement than a naming convention: a client that broadcasts on that link can be offered an address out of any subnet in the group, which is how you add a second range to a LAN that has run out of addresses without renumbering it. VyOS requires the container even when there is only one subnet in it, which is why every example starts with a shared-network name.

The subnet is one scope. The subnet-id is the numeric handle Kea uses for that scope in its lease database and its logs. The range is the dynamic pool, named rather than numbered. The option subtree holds the parameters returned in the DHCPACK.

Configuring the server

configure
set service dhcp-server shared-network-name LAN1 authoritative
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 subnet-id '1'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option default-router '192.0.2.1'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option name-server '192.0.2.53'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option name-server '192.0.2.54'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option domain-name 'example.com'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 lease '86400'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 range LAN1-POOL start '192.0.2.50'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 range LAN1-POOL stop '192.0.2.200'
set interfaces ethernet eth1 vif 10 address '192.0.2.1/24'
commit
save

The configuration creates a shared-network named LAN1, declares the 192.0.2.0/24 subnet with Kea subnet ID 1, hands out addresses from 192.0.2.50 to 192.0.2.200, advertises the router as 192.0.2.1, two DNS servers, and a 24-hour (86400-second) default lease.

Note what the last set line is doing. It is not a binding to the DHCP server — it is the interface address, and it is load-bearing for a different reason, which the next section is about.

There is no interface binding — the subnet is the binding

A reader coming from another vendor will look for the line that attaches the server to a VLAN. VyOS does not expose one. There is no dhcp-server <name> node under interfaces ethernet, on 1.5 or on any earlier release, and a configuration is not made live by naming an interface.

What VyOS does instead is derive the listener from the subnets. At commit, it checks each configured subnet against the addresses on the router’s broadcast-capable interfaces. A subnet that matches an interface address is a directly served segment, and Kea listens there. If none of the configured subnets matches any interface address, and no listen-address has been set, the commit is rejected — VyOS tells you that no subnet has an appropriate primary address on any broadcast interface and no explicit listen address was configured for relayed packets.

set service dhcp-server listen-address '192.0.2.1'

listen-address is the escape hatch for the case the subnet check cannot see: a subnet reached through a DHCP relay, where the router has no address in the client’s subnet at all. It names the local address Kea should listen on. If every subnet you serve is directly attached, you do not need it.

The option subtree

DHCP options are configured per subnet, under option:

set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option default-router '192.0.2.1'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option name-server '192.0.2.53'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option domain-name 'example.com'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option domain-search 'example.com'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option ntp-server '192.0.2.123'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option wins-server '192.0.2.137'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option tftp-server-name '192.0.2.140'
set service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 option bootfile-name 'pxelinux.0'

Common options:

• default-router — option 3, the gateway
• name-server — option 6, the resolvers. This is the node that used to be called dns-server; set it once per resolver, and the values are returned in the order configured
• domain-name — option 15, the client’s domain
• domain-search — option 119, the DNS search list
• ntp-server — option 42, NTP source
• wins-server — option 44, NetBIOS name server (legacy Windows networks)
• tftp-server-name / bootfile-name — options 66 and 67, the PXE pair
• lease — the default lease time in seconds. This one is a peer of option, not a member of it: it is a property of the scope rather than a value handed to the client verbatim

lease sitting outside option catches people out on a first migration. If commit rejects ... subnet 192.0.2.0/24 option lease '86400', that is why.

High availability replaces ISC failover

Kea has no ISC failover protocol, so the 1.3 pattern of tagging a pool with range 0 failover POOL-A has no equivalent and no replacement at the range level. A VyOS 1.5 pair is configured once for the whole server:

set service dhcp-server high-availability name 'DHCP-HA'
set service dhcp-server high-availability mode 'active-active'
set service dhcp-server high-availability status 'primary'
set service dhcp-server high-availability source-address '192.0.2.1'
set service dhcp-server high-availability remote '192.0.2.2'

The peer carries the mirror image: the same name and mode, status secondary, and the two addresses swapped. Both routers need the same subnets, the same subnet-id values and the same pools — Kea matches state between peers by subnet ID, so a pair whose IDs disagree will not synchronise leases even though both commit cleanly.

How the result is validated

show dhcp server leases
show dhcp server statistics

show dhcp server leases lists the active leases with the client’s MAC, the assigned address, the lease expiry and the hostname the client sent in option 12. show dhcp server statistics reports pool occupancy — size, leases held, addresses still available and the resulting utilisation — which is the number to alert on.

vyos@R1:~$ show dhcp server leases

IP Address    MAC address        State    Lease start          Lease expiration     Remaining   Pool   Hostname
192.0.2.50    00:1a:2b:3c:4d:5e  active   2026/08/15 01:23:45  2026/08/16 01:23:45  23:41:02    LAN1   printer-01
192.0.2.51    aa:bb:cc:dd:ee:f0  active   2026/08/15 01:24:11  2026/08/16 01:24:11  23:41:28    LAN1   laptop-rev

vyos@R1:~$ show dhcp server statistics

Pool    Size    Leases    Available    Usage
LAN1     151         2          149       1%

Both blocks above are illustrative: the column set is what the 1.5 op-mode scripts render, but the values are invented for the example. What matters is the shape of the evidence — a lease row per active client, and a utilisation figure you can trend.

For the message-level counters (DISCOVERs received, OFFERs sent, NAKs sent), the op-mode commands are not the source. Those live in Kea’s own statistics, reachable through its control socket, and in the kea-dhcp4 log messages; the monitoring lesson in this part covers both.

Capturing the exchange

When the op-mode output does not explain the symptom, capture the wire. A packet capture on the LAN interface shows the four-message exchange verbatim:

vyos@R1:~$ tcpdump -i eth1.10 -n port 67 or port 68 -vv
12:00:01.234 IP 0.0.0.0.68 > 255.255.255.255.67: BOOTP/DHCP, Request from 00:1a:2b:3c:4d:5e, length 300
  Option 53, length 1: DHCP Discover
12:00:01.236 IP 192.0.2.1.67 > 192.0.2.50.68: BOOTP/DHCP, Reply, length 300
  Option 53, length 1: DHCP Offer
  Option 54, length 4: Server Identifier 192.0.2.1
  Option 51, length 4: IP Address Lease Time 86400
12:00:01.245 IP 0.0.0.0.68 > 255.255.255.255.67: BOOTP/DHCP, Request from 00:1a:2b:3c:4d:5e, length 300
  Option 53, length 1: DHCP Request
12:00:01.247 IP 192.0.2.1.67 > 192.0.2.50.68: BOOTP/DHCP, Reply, length 300
  Option 53, length 1: DHCP ACK

That transcript is illustrative too — it is the message sequence and the option numbers that carry the lesson, not the timestamps. A working exchange shows all four messages, the client’s MAC, the offered address and the option set the server is advertising. A broken exchange shows DHCPDISCOVER with no DHCPOFFER (nothing on this segment is serving it) or DHCPOFFER with no DHCPACK (the client rejected the offer, or the return path failed).

How it fails

The production failure modes a routing engineer must recognise:

• The segment was never declared. Hosts broadcast DISCOVER and nothing answers. There is no binding to have forgotten — the subnet for that VLAN is missing, or its prefix does not match the address on the interface.
• Subnet declared, interface renumbered. The subnet matched an interface address when it was committed; the interface was later moved to a different prefix. Kea stops serving that segment.
• Pool exhausted. Every address in the range is leased. Kea logs an allocation failure and the client gets no offer at all — not an OFFER followed by a missing ACK.
• Default router unreachable. The DHCPACK advertises a gateway that is not on the client’s LAN. Hosts hold an address but cannot route off-net.
• Duplicate subnet-id across an HA pair. Both nodes commit, leases do not synchronise, and the two servers hand out the same address to different clients.
• DNS server wrong. The name-server option points at a resolver that is unreachable or refuses recursion. Hosts have an address, a gateway and no name resolution.

Rollback

The recovery from a broken DHCP server configuration:

• Wrong or missing subnet: delete service dhcp-server shared-network-name LAN1 subnet 192.0.2.0/24 and re-add with the prefix that matches the interface.
• Pool exhausted: raise the range stop value, add a second named range, or add a second subnet to the same shared-network.
• Options wrong after a migration: show configuration commands | match dhcp-server prints the tree in set form, which is the fastest way to spot a dns-server or a bare default-router that survived from a 1.3 configuration.

The VyOS configuration rollback (rollback N) restores the previous revision if the change breaks production, and commit-confirm is the safer way to make the change in the first place.

Production discipline

Cross-course references

• I-VyOS-NetFoundations (vyos-i-05-dns-and-dhcp) covers the DNS / DHCP protocol framing this lesson extends.
• VII-VyOS-Interfaces (vyos-vii-02-ip-addressing) covers the interface addressing the subnet check compares against.
• XLVII-VyOS-MgmtPlane (vyos-xlvii-04-oob-access) covers the OOB network the DHCP server should NOT serve.
• XLVIII-VyOS-Logging (vyos-xlviii-02-routing-daemon-logs) covers the syslog export the DHCP server should emit for forensic analysis.

Quiz