# DHCP Relay

> Configure DHCP Relay on VyOS: DHCP request forwarding, DHCPv4 and DHCPv6 relay, multi-VLAN networks, centralized DHCP server for Yandex Cloud and VK Cloud

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


DHCP Relay (DHCP Relay Agent) lets a router forward DHCP requests from clients to a remote DHCP server located in a different network segment.

## Overview

DHCP Relay solves the problem of centralizing DHCP services in networks with multiple subnets. Instead of deploying a separate DHCP server in each VLAN or subnet, you can use a single centralized DHCP server and configure DHCP relay on the router.

**Key capabilities:**
- Forwarding DHCP requests between subnets
- Support for DHCPv4 and DHCPv6
- Centralized IP address management
- Working with multiple upstream DHCP servers
- Configurable hop count and max packet size
- Support for relay agent options

**How it works:**

1. The client sends a DHCP DISCOVER broadcast
2. The VyOS relay agent intercepts the request
3. The relay converts the broadcast into a unicast
4. The request is forwarded to the specified DHCP server
5. The server replies to the relay agent
6. The relay forwards the reply to the client

## DHCPv4 Relay

### Basic configuration

Minimal DHCPv4 relay configuration:

```
set service dhcp-relay listen-interface eth1
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.4
commit
```

**Components:**
- `listen-interface` - the interface on which to listen for DHCP requests from clients
- `upstream-interface` - the interface used to forward requests to the server
- `server` - the IP address of the DHCP server

### Configuration structure

```
service dhcp-relay
  ├── listen-interface <interface>
  ├── upstream-interface <interface> [address <ip>]
  ├── server <server-ip>
  └── relay-options
      ├── hop-count <count>
      ├── max-size <bytes>
      ├── port <port>
      └── relay-agents-packets <action>
```

### Listen Interface

The interfaces on which the relay agent listens for DHCP requests from clients:

```
set service dhcp-relay listen-interface eth1
set service dhcp-relay listen-interface eth2
set service dhcp-relay listen-interface eth1.10
set service dhcp-relay listen-interface eth1.20
```

You can specify multiple interfaces to serve multiple VLANs.

### Upstream Interface

The interface used to forward DHCP requests to the server:

```
set service dhcp-relay upstream-interface eth0
```

With a specific source address:
```
set service dhcp-relay upstream-interface eth0 address 10.0.0.1
```

Useful when the upstream interface has several IP addresses and you need to select a specific one for relay traffic.

### DHCP Server

Specifying one or more DHCP servers:

```
set service dhcp-relay server 10.0.1.4
```

Multiple servers for redundancy:
```
set service dhcp-relay server 10.0.1.4
set service dhcp-relay server 10.0.1.5
set service dhcp-relay server 10.0.2.4
```

Requests are forwarded to all specified servers. The first server to respond will serve the client.

### Relay Options

#### Hop Count

The maximum number of relay agents a request may pass through:

```
set service dhcp-relay relay-options hop-count 10
```

Default: **10**

Prevents infinite relay loops in complex networks.

#### Max Size

The maximum DHCP packet size in bytes:

```
set service dhcp-relay relay-options max-size 576
```

Default: **576** bytes (the minimum size per RFC 2131)

Increase it if large DHCP options are used:
```
set service dhcp-relay relay-options max-size 1500
```

#### Port

The port on which to listen for DHCP requests:

```
set service dhcp-relay relay-options port 67
```

Default: **67** (the standard DHCP port)

Change it only if you use a non-standard DHCP server.

#### Relay Agents Packets

Handling of packets from other relay agents:

```
set service dhcp-relay relay-options relay-agents-packets <action>
```

Values:
- **append** - append its own relay information
- **replace** - replace the existing relay information
- **forward** - forward without changes
- **discard** - drop packets from other relay agents

Recommended:
```
set service dhcp-relay relay-options relay-agents-packets discard
```

Prevents relay loops and conflicts in complex topologies.

## DHCPv6 Relay

### Basic DHCPv6 configuration

DHCPv6 relay is configured separately from DHCPv4:

```
set service dhcpv6-relay listen-interface eth1
set service dhcpv6-relay upstream-interface eth0 address 2001:db8::4
commit
```

**Differences from DHCPv4:**
- The IPv6 server address must be specified in `upstream-interface`
- Uses UDP ports 547 (client) and 546 (server)
- Supports multicast addresses

### DHCPv6 configuration structure

```
service dhcpv6-relay
  ├── listen-interface <interface>
  ├── upstream-interface <interface>
  │   └── address <ipv6-server>
  ├── max-hop-count <count>
  └── use-interface-id-option
```

### Listen Interface

Interfaces for listening for DHCPv6 requests:

```
set service dhcpv6-relay listen-interface eth1
set service dhcpv6-relay listen-interface eth2
set service dhcpv6-relay listen-interface eth1.100
```

### Upstream Interface

Upstream interface with the DHCPv6 server address:

```
set service dhcpv6-relay upstream-interface eth0 address 2001:db8::4
```

You can specify multiple upstream servers:
```
set service dhcpv6-relay upstream-interface eth0 address 2001:db8::4
set service dhcpv6-relay upstream-interface eth0 address 2001:db8::5
```

### Max Hop Count

The maximum number of hops for DHCPv6:

```
set service dhcpv6-relay max-hop-count 10
```

Default: **10**

### Interface ID Option

Adding the Interface-ID option (RFC 3315):

```
set service dhcpv6-relay use-interface-id-option
```

Helps the DHCPv6 server identify the interface the request came from.

## Configuration examples

### Simple network with a single VLAN

Topology:
```
Clients (192.168.1.0/24) --- eth1 [VyOS] eth0 --- DHCP Server (10.0.0.4)
```

Configuration:
```
set service dhcp-relay listen-interface eth1
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.0.4
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

### Multi-VLAN with a centralized DHCP

Topology:
```
VLAN 10 (192.168.10.0/24) --- eth1.10
VLAN 20 (192.168.20.0/24) --- eth1.20  [VyOS] eth0 --- DHCP Server (10.0.1.4)
VLAN 30 (192.168.30.0/24) --- eth1.30
```

Configuration:
```
# DHCP Relay
set service dhcp-relay listen-interface eth1.10
set service dhcp-relay listen-interface eth1.20
set service dhcp-relay listen-interface eth1.30
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.4

# Relay options
set service dhcp-relay relay-options hop-count 10
set service dhcp-relay relay-options max-size 1500
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

On the DHCP server (ISC DHCP or Kea), configure a subnet for each VLAN:

**Kea DHCP Server (VyOS 1.5):**
```
set service dhcp-server shared-network-name VLAN10 subnet 192.168.10.0/24 subnet-id 10
set service dhcp-server shared-network-name VLAN10 subnet 192.168.10.0/24 option default-router '192.168.10.1'
set service dhcp-server shared-network-name VLAN10 subnet 192.168.10.0/24 range 0 start '192.168.10.100'
set service dhcp-server shared-network-name VLAN10 subnet 192.168.10.0/24 range 0 stop '192.168.10.200'

set service dhcp-server shared-network-name VLAN20 subnet 192.168.20.0/24 subnet-id 20
set service dhcp-server shared-network-name VLAN20 subnet 192.168.20.0/24 option default-router '192.168.20.1'
set service dhcp-server shared-network-name VLAN20 subnet 192.168.20.0/24 range 0 start '192.168.20.100'
set service dhcp-server shared-network-name VLAN20 subnet 192.168.20.0/24 range 0 stop '192.168.20.200'

set service dhcp-server shared-network-name VLAN30 subnet 192.168.30.0/24 subnet-id 30
set service dhcp-server shared-network-name VLAN30 subnet 192.168.30.0/24 option default-router '192.168.30.1'
set service dhcp-server shared-network-name VLAN30 subnet 192.168.30.0/24 range 0 start '192.168.30.100'
set service dhcp-server shared-network-name VLAN30 subnet 192.168.30.0/24 range 0 stop '192.168.30.200'
```

### Multiple DHCP servers (High Availability)

```
# Primary and secondary DHCP servers
set service dhcp-relay listen-interface eth1
set service dhcp-relay listen-interface eth2
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.4
set service dhcp-relay server 10.0.1.5

# Relay options
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

### DHCPv4 and DHCPv6 Relay together

```
# DHCPv4 Relay
set service dhcp-relay listen-interface eth1
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.4
set service dhcp-relay relay-options relay-agents-packets discard

# DHCPv6 Relay
set service dhcpv6-relay listen-interface eth1
set service dhcpv6-relay upstream-interface eth0 address 2001:db8::4
set service dhcpv6-relay max-hop-count 10
set service dhcpv6-relay use-interface-id-option

commit
```

### Corporate network with departments

```
# Management VLAN 10
set service dhcp-relay listen-interface eth1.10

# IT VLAN 20
set service dhcp-relay listen-interface eth1.20

# Finance VLAN 30
set service dhcp-relay listen-interface eth1.30

# Sales VLAN 40
set service dhcp-relay listen-interface eth1.40

# Upstream to the corporate DHCP server
set service dhcp-relay upstream-interface eth0 address 10.0.0.1
set service dhcp-relay server 10.0.100.4
set service dhcp-relay server 10.0.100.5

# Options
set service dhcp-relay relay-options hop-count 5
set service dhcp-relay relay-options max-size 1500
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

### Yandex Cloud configuration

Centralized DHCP for multiple subnets in Yandex Cloud:

```
# VPC subnets
set service dhcp-relay listen-interface eth1
set service dhcp-relay listen-interface eth2
set service dhcp-relay listen-interface eth3

# Upstream to the DHCP server in the management subnet
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.128.0.100

# Relay options
set service dhcp-relay relay-options hop-count 10
set service dhcp-relay relay-options max-size 1500
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

### VK Cloud configuration

Multi-tenant configuration with isolated VLANs:

```
# Tenant A - VLAN 100
set service dhcp-relay listen-interface eth1.100

# Tenant B - VLAN 200
set service dhcp-relay listen-interface eth1.200

# Tenant C - VLAN 300
set service dhcp-relay listen-interface eth1.300

# Upstream
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.10
set service dhcp-relay server 10.0.1.11

# Options
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

## Operational commands

### View DHCPv4 Relay status

```
show dhcp relay-agent
```

Shows:
- Relay agent status (running/stopped)
- Configured interfaces
- DHCP servers
- Relay options

### View DHCPv6 Relay status

```
show dhcpv6 relay-agent
```

### DHCPv4 Relay statistics

```
show dhcp relay-agent statistics
```

Shows:
- Number of forwarded packets
- Number of received replies
- Relay errors

### DHCPv6 Relay statistics

```
show dhcpv6 relay-agent statistics
```

### Restart DHCPv4 Relay

```
restart dhcp relay-agent
```

### Restart DHCPv6 Relay

```
restart dhcpv6 relay-agent
```

### Real-time monitoring

```
monitor log | grep dhcp
```

### Testing from a client

On the client host:

**Linux:**
```bash
sudo dhclient -v eth0
```

**Windows:**
```powershell
ipconfig /release
ipconfig /renew
```

## Monitoring and diagnostics

### Checking the configuration

```
show service dhcp-relay
show service dhcpv6-relay
```

### Viewing logs

DHCPv4 relay:
```
show log | grep dhcrelay
```

DHCPv6 relay:
```
show log | grep dhcrelay6
```

Real-time monitoring:
```
monitor log | match dhcp
```

### Packet capture

Capturing DHCP traffic on the listen interface:
```
monitor traffic interface eth1 filter 'port 67 or port 68'
```

For DHCPv6:
```
monitor traffic interface eth1 filter 'port 546 or port 547'
```

### Checking network connectivity

Check that the DHCP server is reachable from VyOS:
```
ping 10.0.1.4
```

Check the route:
```
show ip route 10.0.1.4
```

## Troubleshooting

### Clients do not receive addresses

**Check 1: The relay agent is running**
```
show dhcp relay-agent
```

**Check 2: Interfaces are correct**
```
show service dhcp-relay
show interfaces
```

Make sure that:
- listen-interface matches the client interface
- upstream-interface has a route to the DHCP server

**Check 3: The DHCP server is reachable**
```
ping 10.0.1.4
traceroute 10.0.1.4
```

**Check 4: Firewall rules**

On VyOS, review the input and forward rules:
```
show firewall ipv4 input filter
show firewall ipv4 forward filter
```

Allow DHCP traffic:
```
# Input for DHCP relay
set firewall ipv4 input filter rule 100 action accept
set firewall ipv4 input filter rule 100 protocol udp
set firewall ipv4 input filter rule 100 destination port 67
set firewall ipv4 input filter rule 100 source port 68

# Forward for DHCP packets
set firewall ipv4 forward filter rule 100 action accept
set firewall ipv4 forward filter rule 100 protocol udp
set firewall ipv4 forward filter rule 100 destination port 67-68

commit
```

**Check 5: Relay agent logs**
```
monitor log | grep dhcrelay
```

**Check 6: Packet capture**
```
# On the listen interface
monitor traffic interface eth1 filter 'port 67 or port 68'

# On the upstream interface
monitor traffic interface eth0 filter 'port 67 or port 68'
```

You should see:
- DISCOVER from the client on listen
- DISCOVER forwarded on upstream
- OFFER from the server on upstream
- OFFER forwarded on listen

### The relay forwards requests, but clients get no replies

**Problem:** The DHCP server does not know the route back to the client subnets.

**Solution:** On the DHCP server, add a static route or a default gateway pointing to the VyOS relay IP.

For example, on the DHCP server:
```bash
# Linux
sudo ip route add 192.168.10.0/24 via 10.0.1.1
sudo ip route add 192.168.20.0/24 via 10.0.1.1
```

Where 10.0.1.1 is the IP address of VyOS on the upstream interface.

### DHCPv6 relay does not work

**Check 1: The IPv6 server address is correct**
```
show service dhcpv6-relay
```

**Check 2: IPv6 connectivity**
```
ping6 2001:db8::4
```

**Check 3: IPv6 firewall rules**
```
show firewall ipv6 input filter

# Allow DHCPv6
set firewall ipv6 input filter rule 100 action accept
set firewall ipv6 input filter rule 100 protocol udp
set firewall ipv6 input filter rule 100 destination port 547

set firewall ipv6 forward filter rule 100 action accept
set firewall ipv6 forward filter rule 100 protocol udp
set firewall ipv6 forward filter rule 100 destination port 546-547

commit
```

**Check 4: DHCPv6 logs**
```
monitor log | grep dhcrelay6
```

### Relay loops

**Symptoms:** The hop count reaches its maximum and packets are dropped

**Cause:** An incorrect topology with relay agent loops

**Solution:**
```
# Set a correct hop-count
set service dhcp-relay relay-options hop-count 5

# Drop packets from other relay agents
set service dhcp-relay relay-options relay-agents-packets discard

commit
```

Check the network topology for relay loops.

### Large DHCP options are truncated

**Problem:** PXE boot or vendor options do not work

**Solution:** Increase max-size
```
set service dhcp-relay relay-options max-size 1500
commit
```

### A restart does not help

Check for system errors:
```
show log | match error
show log | match dhcp
```

Reboot VyOS:
```
reboot now
```

## Security

### Restricting interfaces

Specify only the necessary listen-interface entries:
```
# Correct - only client interfaces
set service dhcp-relay listen-interface eth1
set service dhcp-relay listen-interface eth2

# Incorrect - do not specify the WAN
# set service dhcp-relay listen-interface eth0
```

### Firewall rules

Allow DHCP only on the required interfaces:

```
# Input on client interfaces
set firewall ipv4 input filter rule 100 action accept
set firewall ipv4 input filter rule 100 protocol udp
set firewall ipv4 input filter rule 100 destination port 67
set firewall ipv4 input filter rule 100 inbound-interface name eth1

# Forward for DHCP
set firewall ipv4 forward filter rule 100 action accept
set firewall ipv4 forward filter rule 100 protocol udp
set firewall ipv4 forward filter rule 100 destination port 67-68
set firewall ipv4 forward filter rule 100 inbound-interface name eth1

# Block DHCP on the WAN
set firewall ipv4 input filter rule 90 action drop
set firewall ipv4 input filter rule 90 protocol udp
set firewall ipv4 input filter rule 90 destination port 67
set firewall ipv4 input filter rule 90 inbound-interface name eth0

commit
```

### Protecting the DHCP server

On the DHCP server, configure the firewall to accept requests only from trusted relay agents:

```bash
# Linux iptables
sudo iptables -A INPUT -p udp --dport 67 -s 10.0.1.1 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 67 -j DROP
```

### Relay agent options protection

```
set service dhcp-relay relay-options relay-agents-packets discard
```

Prevents attacks through spoofed relay agent options.

### Rate limiting

Limiting DHCP requests:
```
set firewall ipv4 input filter rule 100 limit rate 50/minute
```

## Best practices

1. **Interface planning** - clearly separate listen and upstream interfaces
2. **Server redundancy** - use at least 2 DHCP servers
3. **Hop count** - set reasonable values (5-10)
4. **Max size** - increase it for PXE and vendor options (up to 1500)
5. **Relay agents packets** - use discard to prevent loops
6. **Firewall** - restrict DHCP traffic to the required interfaces
7. **Logging** - regularly review the relay agent logs
8. **Monitoring** - track relay statistics
9. **Documentation** - describe the purpose of each VLAN
10. **Testing** - verify operation after every change

## Performance

DHCP relay adds minimal latency:
- **Latency overhead**: 1-5ms
- **Throughput**: Limited only by CPU and network performance
- **Connections**: Supports thousands of clients simultaneously

The relay agent is very lightweight and does not create significant load.

## Interaction with other services

### DNS

The DHCP server can update DNS through Dynamic DNS:
```
# On the DHCP server
set service dhcp-server dynamic-dns-update enable
```

### NTP

Enable NTP options on the DHCP server for automatic time configuration:
```
set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 option ntp-server '192.168.10.1'
```

### NAT

When using NAT, make sure DHCP traffic is not NAT-ed:
```
# NAT exclude for DHCP
set nat source rule 100 outbound-interface name eth0
set nat source rule 100 source address 192.168.0.0/16
set nat source rule 100 destination address '!10.0.1.4'
set nat source rule 100 translation address masquerade
```

## Migrating from local DHCP to relay

Step-by-step migration:

**Step 1:** Configure the centralized DHCP server with all subnets

**Step 2:** Configure DHCP relay on VyOS:
```
set service dhcp-relay listen-interface eth1
set service dhcp-relay upstream-interface eth0
set service dhcp-relay server 10.0.1.4
```

**Step 3:** Disable the local DHCP server:
```
delete service dhcp-server shared-network-name LAN
commit
```

**Step 4:** Activate the relay:
```
commit
save
```

**Step 5:** Test operation:
```
# On the client
sudo dhclient -v eth0
```

**Step 6:** Monitoring:
```
show dhcp relay-agent
monitor log | grep dhcp
```

## Alternative solutions

### When NOT to use DHCP relay:

1. **Small networks** - a single VLAN, where local DHCP is simpler
2. **Latency requirements** - critical, latency-sensitive applications
3. **Isolated networks** - fully isolated with no connection to a central server
4. **Failover unavailable** - when there is no way to provide redundancy for the centralized server

### Alternatives:

1. **Local DHCP** - on each router/VLAN
2. **DHCP Failover** - a pair of DHCP servers with synchronization
3. **DHCP Cluster** - a cluster of DHCP servers (Kea HA)
4. **Cloud DHCP** - managed services in the cloud

## Next steps

- [DHCP Server](/docs/vyos/services/vyos-dhcp/) - configuring a local DHCP server
- [DHCPv6 Server](/docs/vyos/services/vyos-dhcpv6/) - IPv6 DHCP server
- [DNS Forwarding](/docs/vyos/services/vyos-dns/) - integration with DNS
- [VLAN Configuration](/docs/vyos/interfaces/vyos-vlan/) - configuring VLAN interfaces
- [Firewall](/docs/vyos/firewall/) - protecting DHCP services