DoneCase file

Moving DHCP from a Rocky Linux VM to the UniFi Cloud Gateway Max

5 min read

DHCP lived on a Rocky Linux VM, so a Proxmox reboot took down the house network. Why I moved it to the UniFi Cloud Gateway Max, how I migrated the scope without a mess of stale leases, and the rollback plan I kept ready.

  • Network
  • DHCP
  • UniFi
DHCP moves from a VM to the gateway Left: a VM on a Proxmox host serves DHCP to clients. Right: the UCG Max serves DHCP to every VLAN directly. Rocky VM on Proxmox UCG Max router + DHCP

Why I did it

5 reasons this had to change

  • DHCP for the whole house ran on a Rocky Linux VM on Proxmox.
  • A host reboot, a VM crash, or a maintenance window cut off lease renewals for every device.
  • Outages were delayed and confusing: existing leases kept working, then devices silently failed to renew hours later.
  • Troubleshooting meant checking the VM and the host before getting to the network itself.
  • It stopped being theoretical when the household started asking why the internet was broken.

Options considered

3 options. Picked: Move DHCP to the UCG Max

OptionTrade-off
Keep the VM, add a failover DHCP serverTwo services to patch and back up, and at least one still depends on Proxmox staying up.
Move DHCP to the UCG Max ChosenThe gateway already routes every VLAN, so this removes a dependency instead of adding one.
Run DHCP on a Raspberry PiOff the Proxmox host, but still a separate device to patch and keep powered.

Pros and cons

4 pros, 4 cons

Pros

  • DHCP keeps working through Proxmox reboots and maintenance
  • One less VM to patch and back up
  • Troubleshooting narrows to the network
  • Lives on a device that was already a hard dependency

Cons

  • Cutover needs a maintenance window
  • Some devices needed a manual rejoin to pick up the new server
  • DNS servers must be re-entered as a DHCP option or ad blocking stops for new leases
  • DHCP now depends on gateway firmware updates going well

How it went

5 steps, start to finish

  1. Step 1: Record the existing scope

    Range, every static reservation by MAC, DNS servers handed out, lease time, and any custom options. The cutover is only as safe as this record.

    # On the Rocky Linux DHCP VM, before touching anything:
    cat /etc/dhcp/dhcpd.conf
    
    # Keep a dated copy of the active lease table
    cat /var/lib/dhcpd/dhcpd.leases > ~/dhcpd-leases-backup-$(date +%F).txt
    
    # List static host entries (MAC -> IP -> hostname) separately.
    # These must survive the migration unchanged.
  2. Step 2: Recreate the scope on the UCG Max

    Same subnet, range, lease time, and DNS servers. Pi-hole stays the DNS server handed to clients; only DHCP moves. Server reservations were recreated one by one against the same IPs, so nothing on the Lab VLAN had to change.

  3. Step 3: Cut over in a maintenance window

    Stop DHCP on the Rocky VM first so two servers never answer the same request, then enable the scope on the gateway. Existing leases keep working until they renew.

    # On the Rocky VM: stop the service, keep the VM bootable for rollback
    sudo systemctl stop dhcpd
    sudo systemctl disable dhcpd
  4. Step 4: Verify from a client on each VLAN

    Drop and re-request a lease, confirm the gateway answered, and confirm DNS still resolves through the expected resolver.

    # Windows client
    ipconfig /release
    ipconfig /renew
    ipconfig /all | findstr /i "DHCP Server"
    
    # DNS still resolves through the expected resolver
    nslookup <INTERNAL_HOSTNAME>
    
    # On the gateway: check the lease table for the expected range and count
  5. Step 5: Keep rollback ready, then retire

    The VM stayed built with DHCP stopped, not removed. Rollback was: disable the gateway scope, start the VM's service. After a week with nothing depending on it, the VM was retired.

What went wrong

6 gotchas and how each was fixed

Bridge mode and the WAN lease

Symptom
Hard to tell a LAN DHCP problem from a WAN one during cutover.
Cause
With the ISP modem bridged, the gateway is also a DHCP client on its WAN port. That is a separate relationship from its LAN server role.
Fix
Confirm the WAN lease is healthy before touching LAN DHCP, so only one thing is being debugged at a time.

WAN port choice

Symptom
Connected, but slower than expected.
Cause
The gateway has WAN-capable ports at different speeds. The wrong one works silently at a lower link speed.
Fix
Check the negotiated link speed after cutover, not just the connected state.

Stale leases

Symptom
Devices briefly looked like they were fighting over similar addresses.
Cause
Clients held leases from the old pool until expiry.
Fix
Keep the exact same range on both servers so old and new leases never conflict.

DNS handed to clients

Symptom
Ad blocking quietly stopped applying to new leases.
Cause
DNS servers are a DHCP option, not only a router setting.
Fix
Set the same DNS servers in the new scope before cutover.

Devices that never renew

Symptom
A few phones and smart devices kept their old settings.
Cause
Not every device re-requests a lease promptly on its own.
Fix
Forget the network and rejoin.

Guest portal

Symptom
A captive portal failure looks identical to a DHCP failure from the guest's side.
Cause
The guest portal relies on the gateway's own DHCP and DNS to intercept the first request.
Fix
Guest DHCP was already on the gateway, so nothing broke. It was still the first thing checked.

Before and after

Side-by-side table and diagrams

MetricBeforeAfter
DHCP sourceRocky Linux VM on ProxmoxUCG Max, native
Survives a Proxmox rebootNo, DHCP went down with the hostYes, independent of Proxmox
Moving parts to maintainOS, DHCP daemon, VM, hostGateway firmware
Troubleshooting surfaceVM, host, networkNetwork only
Before
Before: DHCP on a VM The Proxmox host runs a Rocky Linux VM that serves DHCP to every client. The host and VM together are highlighted as a single point of failure. single point of failure Proxmox host reboot = no new leases Rocky VM DHCP server Client lease Client lease Client lease

Before: the Proxmox host runs a Rocky Linux VM, and that VM serves DHCP to every client. The host and VM together are a single point of failure: if either goes down, no device can renew a lease.

After
After: DHCP on the UCG Max The UCG Max serves DHCP directly to the Main, Lab, IoT, and Guest VLANs. The Proxmox host is off to the side with no link to DHCP, so it can reboot without affecting leases. UCG Max router + DHCP Main VLAN Lab VLAN IoT VLAN Guest VLAN Proxmox host reboots freely, DHCP unaffected

After: the UCG Max serves DHCP directly to the Main, Lab, IoT, and Guest VLANs. The Proxmox host sits off to the side with no connection to DHCP, so it can reboot without affecting leases.

Results

DHCP single point of failure: Gone

  • GoneDHCP single point of failureNo longer tied to the Proxmox host
  • YesSurvives a Proxmox rebootWas: no
  • 4 → 1Moving parts behind DHCPOS, daemon, VM, host became gateway firmware
  • 1 weekOld VM kept off before retiringRollback stayed one step away

Lessons and what's next

4 lessons, then what's next

  • Document the existing scope completely before touching anything.
  • Keep the old service powered off, not deleted, for at least a week.
  • Test from a client on every VLAN, not just the one in front of you.
  • Use a maintenance window even for a change that should be instant. Devices notice a new DHCP server at different times.

← Back to all projects