DHCP Server

VyOS uses the Kea DHCP Server (starting from version 1.5.x) to provide DHCPv4 and DHCPv6 services.

Important change in VyOS 1.5.x

VyOS 1.5 switched from ISC DHCP to Kea DHCP. The main changes are:

ISC DHCP (VyOS 1.4):

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 mac-address '00:50:56:00:00:01'

Kea DHCP (VyOS 1.5):

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 mac '00:50:56:00:00:01'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 ip-address '192.168.1.10'

Key differences:

mac-address → mac
An ip-address or hostname must be specified for static mappings

IPv4 DHCP Server

Basic configuration

Minimal DHCP server configuration:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option default-router '192.168.1.1'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option name-server '192.168.1.1'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 start '192.168.1.100'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop '192.168.1.200'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 subnet-id 1

Configuration structure

service dhcp-server
  └── shared-network-name <name>
      ├── authoritative
      ├── subnet <prefix>
      │   ├── subnet-id <id>
      │   ├── option
      │   │   ├── default-router <ip>
      │   │   ├── name-server <ip>
      │   │   ├── domain-name <domain>
      │   │   └── ...
      │   ├── range <id>
      │   │   ├── start <ip>
      │   │   └── stop <ip>
      │   ├── static-mapping <name>
      │   │   ├── mac <mac-address>
      │   │   ├── ip-address <ip>
      │   │   └── hostname <name>
      │   ├── lease <seconds>
      │   └── exclude <ip>
      └── ...

Shared Network

A shared network groups several subnets that reside in the same physical segment:

set service dhcp-server shared-network-name OFFICE subnet 192.168.1.0/24 subnet-id 1
set service dhcp-server shared-network-name OFFICE subnet 192.168.2.0/24 subnet-id 2

The authoritative parameter indicates that the server is authoritative for this network:

set service dhcp-server shared-network-name LAN authoritative

Subnet Parameters

Subnet ID

A unique subnet identifier (mandatory parameter in Kea):

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 subnet-id 1

Default Router (Gateway)

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option default-router '192.168.1.1'

DNS Servers

A single DNS server:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option name-server '192.168.1.1'

Multiple DNS servers:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option name-server '192.168.1.1'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option name-server '8.8.8.8'

Domain Name

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option domain-name 'example.local'

Domain Search

A list of domains to search:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option domain-search 'example.local'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option domain-search 'example.com'

Lease Time

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 lease 86400

The value is in seconds. Default: 86400 (24 hours).

NTP Servers

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option ntp-server '192.168.1.1'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option ntp-server '0.pool.ntp.org'

Address Ranges

Dynamic IP address ranges for automatic allocation:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 start '192.168.1.100'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop '192.168.1.200'

Multiple ranges:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 start '192.168.1.100'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop '192.168.1.150'

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 1 start '192.168.1.200'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 1 stop '192.168.1.250'

Excluded Addresses

Excluding addresses from allocation:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 exclude 192.168.1.1
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 exclude 192.168.1.2
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 exclude 192.168.1.3

Static Mappings

Static bindings of MAC addresses to IP addresses.

Basic static mapping:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 mac '00:50:56:00:00:01'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 ip-address '192.168.1.10'

With a hostname:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 mac '00:50:56:00:00:01'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 hostname 'server1.example.local'

With a description:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 mac '00:50:56:00:00:01'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 ip-address '192.168.1.10'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 description 'Production Web Server'

Disabling a static mapping:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping server1 disable

DHCP Options

Bootfile Name (for PXE)

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option bootfile-name 'pxelinux.0'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option bootfile-server '192.168.1.5'

TFTP Server

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option tftp-server-name '192.168.1.5'

WPAD URL

Web Proxy Auto-Discovery:

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option wpad-url 'http://wpad.example.local/wpad.dat'

Vendor Options

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 vendor-option cisco option 150 value '192.168.1.5'

DHCPv6 Server

Basic DHCPv6 configuration

set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/64 subnet-id 1
set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::200
set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/64 option name-server 2001:db8::1

Prefix Delegation

DHCPv6 Prefix Delegation for handing out prefixes to clients:

set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/48 subnet-id 1
set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/48 prefix-delegation prefix 2001:db8:1000::/52 delegated-length 56

Static Mappings for DHCPv6

set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/64 static-mapping server1 identifier '00:01:00:01:12:34:56:78:9a:bc:de:f0:12:34'
set service dhcp-server shared-network-name LANv6 subnet 2001:db8::/64 static-mapping server1 ipv6-address '2001:db8::100'

Dynamic DNS (DDNS) Integration

Automatically updating DNS records when DHCP addresses are issued:

set service dhcp-server dynamic-dns-update enable
set service dhcp-server dynamic-dns-update server ddns.example.local zone example.local
set service dhcp-server dynamic-dns-update server ddns.example.local key keyname

High Availability

Active-Active Mode

set service dhcp-server high-availability mode active-active
set service dhcp-server high-availability peer-address '192.168.1.2'
set service dhcp-server high-availability source-address '192.168.1.1'
set service dhcp-server high-availability name 'dhcp-ha-pair'

Active-Passive Mode

set service dhcp-server high-availability mode active-passive
set service dhcp-server high-availability peer-address '192.168.1.2'
set service dhcp-server high-availability source-address '192.168.1.1'
set service dhcp-server high-availability name 'dhcp-ha-pair'

Configuration examples

Home network

set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 option default-router '192.168.1.1'
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 option name-server '192.168.1.1'
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 option domain-name 'home.local'
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 range 0 start '192.168.1.100'
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 range 0 stop '192.168.1.200'
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 subnet-id 1
set service dhcp-server shared-network-name HOME subnet 192.168.1.0/24 lease 86400

Enterprise network with VLANs

# VLAN 10 - Management
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 option default-router '192.168.10.1'
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 option name-server '192.168.10.1'
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 option domain-name 'mgmt.corp.local'
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 range 0 start '192.168.10.100'
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 range 0 stop '192.168.10.200'
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 subnet-id 10
set service dhcp-server shared-network-name MGMT subnet 192.168.10.0/24 lease 3600

# VLAN 20 - Workstations
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 option default-router '192.168.20.1'
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 option name-server '192.168.20.1'
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 option domain-name 'corp.local'
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 range 0 start '192.168.20.50'
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 range 0 stop '192.168.20.250'
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 subnet-id 20
set service dhcp-server shared-network-name WORK subnet 192.168.20.0/24 lease 43200

Servers with static addresses

set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 option default-router '192.168.100.1'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 option name-server '192.168.100.1'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 subnet-id 100

# Web Server
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping web1 mac '00:50:56:00:01:01'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping web1 ip-address '192.168.100.10'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping web1 hostname 'web1.corp.local'

# Database Server
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping db1 mac '00:50:56:00:01:02'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping db1 ip-address '192.168.100.20'
set service dhcp-server shared-network-name SERVERS subnet 192.168.100.0/24 static-mapping db1 hostname 'db1.corp.local'

PXE Boot server

set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 option default-router '192.168.50.1'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 option name-server '192.168.50.1'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 option bootfile-name 'pxelinux.0'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 option bootfile-server '192.168.50.5'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 option tftp-server-name '192.168.50.5'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 range 0 start '192.168.50.100'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 range 0 stop '192.168.50.200'
set service dhcp-server shared-network-name PXE subnet 192.168.50.0/24 subnet-id 50

Operational commands

Viewing leases

All active leases:

show dhcp server leases

Leases for a specific subnet:

show dhcp server leases subnet 192.168.1.0/24

A specific address:

show dhcp server leases address 192.168.1.100

Statistics

show dhcp server statistics

Restarting the server

restart dhcp server

Logs

Viewing logs:

show log dhcp
monitor log | grep dhcp

Configuration and data files

VyOS 1.5.x (Kea DHCP)

Configuration: generated from the VyOS CLI
Leases file: /config/dhcp4.leases
Logs: /var/log/kea/kea-dhcp4.log

VyOS 1.4.x (ISC DHCP) - for reference

Configuration: /run/dhcp-server/dhcpd.conf
Leases file: /var/lib/dhcp/dhcpd.leases

Troubleshooting

Clients are not getting addresses

Check the service status:

show service dhcp-server

Check the configuration:

show service dhcp-server shared-network-name LAN

Real-time monitoring:

monitor log | grep dhcp

Restart the service:

restart dhcp server

A static mapping is not working

Make sure the required parameters are specified:

mac (MAC address)
ip-address or hostname

Verify that the MAC address is correct:

show service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping

Address conflicts

Check the exclude entries and static mappings:

show service dhcp-server shared-network-name LAN subnet 192.168.1.0/24

Clear stale leases (use with caution):

restart dhcp server

DHCP Relay problems

If the DHCP server is on a different segment, configure DHCP relay on the interface:

set service dhcp-relay interface eth0
set service dhcp-relay server 192.168.1.1

Best practices

Address planning - reserve ranges for static addresses
Use exclude - for servers and network equipment
Document static mappings - use descriptions
Tune the lease time - short for guest networks, long for stable ones
Backups - save the configuration regularly
Monitoring - keep track of address utilization
High Availability - configure HA for critical networks
Logging - regularly review the logs for errors

Migration from VyOS 1.4 to 1.5

When migrating, update the static mappings:

Old format (1.4):

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 mac-address '00:50:56:00:00:01'

New format (1.5):

set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 mac '00:50:56:00:00:01'
set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 static-mapping host1 ip-address '192.168.1.10'

Use a script for bulk conversion if you have many static mappings.

Next steps

DNS Forwarding - DNS integration
Dynamic DNS - automatic DNS record updates
High Availability - DHCP fault tolerance

Reviewed by OpenNix LLC · Last updated on 29 July 2026

OSPF (Open Shortest Path First)DNS Forwarding