DHCP monitoring — lease statistics, syslog export, Prometheus exporter

A production DHCP server must be monitored. Pool exhaustion is silent until it isn’t — a new host attempts to DHCP, fails, and the operator finds out from a user complaint instead of from a dashboard. The defensive pattern: export DHCP statistics to syslog and Prometheus, alert on pool utilisation, and review lease counts on a regular cadence.

This lesson covers the four monitoring surfaces for DHCP on VyOS 1.5 LTS: the operational show commands, the syslog export for forensic analysis, the Kea statistics socket for ad-hoc queries, and the Prometheus exporter for time-series metrics.

The four monitoring surfaces

flowchart LR
  K["Kea DHCPv4 server"] --> S1["show dhcp server leases<br/>operational state"]
  K --> S2["show dhcp server statistics<br/>message counters"]
  K --> S3["Syslog export<br/>lease events, errors"]
  K --> S4["Kea control socket<br/>JSON stats queries"]
  S3 --> CENTRAL["Central syslog server"]
  S4 --> EXP["Prometheus exporter<br/>HTTP /metrics"]
  EXP --> PROM["Prometheus<br/>time-series DB"]
  PROM --> GRAF["Grafana<br/>dashboards"]
  PROM --> AM["Alertmanager<br/>pool utilisation alerts"]

The four surfaces give the operator different views:

• Operational state — show dhcp server leases shows the current lease database. Used for ad-hoc verification.
• Message counters — show dhcp server statistics shows how many DISCOVERs, OFFERs, REQUESTs, ACKs, NAKs the server has processed. Used for capacity and performance analysis.
• Syslog events — every lease event (allocation, renewal, expiration, DECLINE) is logged. Used for forensic analysis.
• Kea control socket — programmatic access to the statistics database. Used for the Prometheus exporter.

Operational state — show dhcp server leases

vyos@R1:~$ show dhcp server leases
IP address    MAC address        State    Lease expiration    Pool    Hostname
------------  -----------------  -------  ------------------  ------  -----------
192.0.2.10    00:1a:2b:3c:4d:5e  active   2026/09/14 01:23:45 LAN1    lobby-printer
192.0.2.11    12:34:56:78:9a:bc  active   2026/08/16 01:24:11 LAN1    desk-east
192.0.2.50    aa:bb:cc:dd:ee:f0  active   2026/08/16 01:25:33 LAN1    laptop-rev

The output shows every active lease with its MAC, address, expiry time, and the host’s hostname (if it sent one). The operator can verify the lease count, look for hosts that should not be there (rogue devices), and identify stale leases that should have expired.

Message counters — show dhcp server statistics

vyos@R1:~$ show dhcp server statistics
Packets received: 12345
Packets sent: 12340
Solicits received: 0   <-- DHCPv6 only
Advertises sent: 0
Requests received: 1234
Requests ignored: 5
Naks sent: 5

The counters track every DHCP message. The operator monitors:

• NAKs sent — should be near zero in steady state. A spike indicates pool exhaustion or DECLINE storms.
• Requests ignored — should be near zero. A spike indicates malformed packets or option-82 issues.
• DISCOVERs / REQUESTs — track the rate of new lease requests. A sudden spike may indicate a large event (a meeting, a deployment).

Syslog export — system syslog

configure
set system syslog host 203.0.113.100 facility all level info
set system syslog host 203.0.113.100 facility local7 level debug
commit
save

The configuration exports syslog to a central server at 203.0.113.100. Kea logs lease events at local7 (the standard syslog facility for DHCP). The central server indexes the events; the operator queries the index for forensic analysis.

What the operator finds in syslog:

Aug 15 12:00:01 R1 kea-dhcp4: INFO [kea-dhcp4.leases] DHCP4_LEASE_ALLOC
  hardware-address=aa:bb:cc:dd:ee:f0
  client-id=01:aa:bb:cc:dd:ee:f0
  subnet-id=1
  ip-address=192.0.2.50
  lease-time=86400
  hostname=laptop-rev

Aug 15 12:00:05 R1 kea-dhcp4: WARN [kea-dhcp4.leases] DHCP4_LEASE_DECLINED
  hardware-address=11:22:33:44:55:66
  ip-address=192.0.2.100
  reason=address-already-in-use

Aug 15 12:30:00 R1 kea-dhcp4: INFO [kea-dhcp4.leases] DHCP4_LEASE_EXPIRED
  hardware-address=99:88:77:66:55:44
  ip-address=192.0.2.51

The syslog entries are the audit trail. The operator can answer questions like “when did this host obtain its lease?”, “which host had 192.0.2.100 on August 12?”, “did the lease expire or was it released?”.

Kea control socket

Kea exposes a control socket that returns statistics in JSON format:

vyos@R1:~$ kea-ctrl-cli -u /var/run/kea/kea-dhcp4.sock lease4-get-all
{
    "result": 0,
    "leases": [
        {
            "ip-address": "192.0.2.50",
            "hw-address": "aa:bb:cc:dd:ee:f0",
            "client-id": "01:aa:bb:cc:dd:ee:f0",
            "valid-lft": 86399,
            "expire": 1723720800,
            "subnet-id": 1,
            "hostname": "laptop-rev",
            "state": "active"
        }
    ]
}

The control socket also returns statistics:

vyos@R1:~$ kea-ctrl-cli -u /var/run/kea/kea-dhcp4.sock statistic-get-all
{
    "result": 0,
    "arguments": {
        "pkt4-received": 12345,
        "pkt4-sent": 12340,
        "pkt4-offer-sent": 1234,
        "pkt4-ack-sent": 1230,
        "pkt4-nak-sent": 5,
        "v4-allocation-fail": 5
    }
}

The Prometheus exporter queries this socket every 15 seconds, parses the JSON, and exposes the metrics in Prometheus format.

Prometheus exporter

The exporter is a small HTTP server that translates Kea’s JSON statistics to Prometheus metrics. A typical setup:

# /etc/systemd/system/dhcp-exporter.service
[Unit]
Description=DHCP Prometheus exporter
After=kea-dhcp4.service

[Service]
ExecStart=/usr/local/bin/dhcp-exporter --kea-socket=/var/run/kea/kea-dhcp4.sock --listen=:9109
Restart=always

[Install]
WantedBy=multi-user.target

The exporter listens on port 9109. Prometheus scrapes the metrics:

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: 'dhcp'
    static_configs:
      - targets: ['R1:9109', 'R2:9109']

The exporter exposes metrics like:

# HELP dhcp_leases_active Total active leases
# TYPE dhcp_leases_active gauge
dhcp_leases_active{subnet="LAN1"} 1234

# HELP dhcp_pool_size Configured pool size
# TYPE dhcp_pool_size gauge
dhcp_pool_size{subnet="LAN1"} 151

# HELP dhcp_pool_utilisation Pool utilisation (0-1)
# TYPE dhcp_pool_utilisation gauge
dhcp_pool_utilisation{subnet="LAN1"} 0.82

# HELP dhcp_packets_received_total Packets received
# TYPE dhcp_packets_received_total counter
dhcp_packets_received_total 12345

# HELP dhcp_naks_sent_total NAKs sent
# TYPE dhcp_naks_sent_total counter
dhcp_naks_sent_total 5

Alerting on pool exhaustion

The Prometheus alerting rule:

# /etc/prometheus/rules/dhcp.yml
groups:
  - name: dhcp
    rules:
      - alert: DHCPPoolUtilizationHigh
        expr: dhcp_pool_utilisation > 0.80
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "DHCP pool {{ $labels.subnet }} at {{ $value | humanizePercentage }}"
          description: "Pool utilisation exceeds 80% for 10 minutes."

      - alert: DHCPPoolUtilizationCritical
        expr: dhcp_pool_utilisation > 0.95
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "DHCP pool {{ $labels.subnet }} nearly exhausted"
          description: "Pool utilisation exceeds 95% for 5 minutes. New hosts will fail."

The alert fires when pool utilisation exceeds 80% (warning) or 95% (critical). The operator is paged and can extend the pool before hosts fail.

Dashboard

A Grafana dashboard shows the lease utilisation, the message rate, and the recent DECLINE events:

# Panels:
- Pool utilisation by subnet (gauge)
- Lease count over time (graph)
- DHCP messages per second (graph)
- Recent DECLINE events (table)
- Recent NAK events (table)
- Top talkers by MAC (table)

The dashboard is the operator’s primary tool for monitoring DHCP health. The alert rule catches the operator’s attention when the dashboard shows a problem.

How it fails

The monitoring failure modes:

• Syslog export not configured. The operator finds out about a DHCP problem only when users complain. The fix: configure syslog export from day one.
• Exporter down. The exporter process crashes; Prometheus has no metrics; alerts fire spuriously or not at all. The fix: monitor the exporter’s own health.
• Alert threshold wrong. The alert threshold is too low (false positives every weekend) or too high (no alert until pool is full). The fix: tune the threshold to the actual growth rate.
• Time-series cardinality blow-up. The exporter exposes per-MAC metrics, and there are 10000 hosts. Prometheus runs out of memory. The fix: aggregate by subnet, not by MAC.

Rollback

# Capture the current configuration
show configuration service dhcp-server | save /tmp/vyos-dhcp-config-$(date +%s).txt
show configuration system syslog | save /tmp/vyos-syslog-config-$(date +%s).txt

# Roll back if monitoring breaks DHCP
configure
rollback N
commit
save

The VyOS configuration rollback restores the previous revision if the monitoring change breaks the DHCP service.

Production discipline

Cross-course references

• XLVI-VyOS-DHCP (vyos-xlvi-01-dhcp-server, vyos-xlvi-04-dhcpv6-server) cover the configuration this lesson monitors.
• XLVIII-VyOS-Logging (vyos-xlviii-01-local-logging) covers the syslog export.
• XLIX-VyOS-Monitoring covers the wider observability integration.
• XXXIII-Observability-AlertingRules (Observability course) covers the alerting rule patterns this lesson uses.

Quiz