# DHCP Server

> DHCP server on VyOS - automatic IP address allocation, static reservations, DHCP options, PXE boot, and high availability with Kea DHCP

Source: https://opennix.org/en/docs/vyos/services/vyos-dhcp/


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

1. **Address planning** - reserve ranges for static addresses
2. **Use exclude** - for servers and network equipment
3. **Document static mappings** - use descriptions
4. **Tune the lease time** - short for guest networks, long for stable ones
5. **Backups** - save the configuration regularly
6. **Monitoring** - keep track of address utilization
7. **High Availability** - configure HA for critical networks
8. **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](/docs/vyos/services/vyos-dns/) - DNS integration
- [Dynamic DNS](/docs/vyos/services/vyos-ddns/) - automatic DNS record updates
- [High Availability](/docs/vyos/ha/) - DHCP fault tolerance