Skip to main content

DHCP/IPoE

DHCP-based IP assignment for IPoE subscribers.

Overview​

AthenaBNG terminates DHCP sessions for IPoE (IP over Ethernet) subscribers using abng-dhcpd, a built-in DHCP server. Subscribers receive IP configuration via DHCP without requiring PPP.

DHCP Architecture​

DHCP Relay​

abng-dhcpd uses AF_PACKET socket to capture DHCP Discover frames on subscriber VLAN interfaces:

  1. Capture — AF_PACKET socket with BPF filter for UDP port 67
  2. Relay — Inject Option 82 Circuit ID (interface name)
  3. Forward — Send to DHCP server
  4. Reply — Receive DHCP Offer/ACK from server
  5. Send — Forward reply back to subscriber

Why Relay?​

Subscriber VLAN interfaces are created dynamically by abng-demux and have no IP address. Standard DHCP servers require an IP on the interface to bind raw sockets. The relay solves this by:

  • Using AF_PACKET (no IP required)
  • Injecting Option 82 for subscriber identification
  • Routing replies back to correct interface

DHCP Session Lifecycle​

1. VLAN Interface Creation​

When DHCP Discover is received:

  • abng-demux creates VLAN interface (e.g., eth1.111.500.100)
  • Notifies abngd of new interface
  • abng-dhcpd relay adds interface to listener

2. DHCP Discover​

Subscriber broadcasts DHCP Discover:

  • abng-dhcpd relay captures frame
  • Injects Option 82 Circuit ID (interface name)
  • Forwards to DHCP server

3. DHCP Offer​

DHCP server sends Offer:

  • abng-dhcpd relay receives from server
  • Forwards back to subscriber on correct VLAN

4. DHCP Request​

Subscriber sends Request:

  • abng-dhcpd relay captures and forwards to server

5. DHCP ACK​

DHCP server sends ACK:

  • abng-dhcpd relay receives from server
  • Forwards to subscriber
  • abng-dhcpd notifies abngd of session

6. Session Active​

abngd creates session:

  • Stores IP address and lease time
  • Applies QoS rules
  • Tracks accounting data

7. Lease Expiry or Release​

Subscriber releases lease or lease expires:

  • abng-dhcpd terminates session
  • abngd removes from database
  • QoS rules removed
  • VLAN interface cleaned up after idle timeout

Configuration​

dhcp:
  enabled: true
  lease_time: 3600
  allocation_mode: "radius"
  unnumbered: true
  pools:
    - network: "10.100.0.0/23"
      gateway: "10.100.0.1"
      dns_servers:
        - "1.1.1.1"
        - "8.8.8.8"

IP Allocation Modes​

RADIUS Mode​

IP addresses are assigned by RADIUS server:

  1. DHCP Discover received
  2. abng-dhcpd sends RADIUS Access-Request with the subscriber MAC (lowercase)
  3. RADIUS Access-Accept returns Framed-IP-Address plus optional rate attributes (Athena-Rate-Down / Athena-Rate-Up)
  4. abng-dhcpd sends DHCP Offer with IP
  5. Subscriber sends DHCP Request
  6. abng-dhcpd sends DHCP ACK and applies the assigned rate as CAKE shaping

The MAC is sent in lowercase (e.g. aa:bb:cc:dd:ee:ff); this matters for case-sensitive RADIUS user matching.

Pool Mode​

IP addresses are allocated from configured pools:

  1. DHCP Discover received
  2. abng-dhcpd allocates IP from pool
  3. Sends DHCP Offer with IP
  4. Subscriber sends DHCP Request
  5. abng-dhcpd sends DHCP ACK

Option 82 Circuit ID​

Option 82 is automatically injected with:

  • Circuit ID — Subscriber VLAN interface name (e.g., "eth1.111.500.100")
  • Remote ID — BNG hostname

This allows upstream RADIUS servers to identify the subscriber's access line.

Unnumbered IPoE​

By default, DHCP uses unnumbered IPoE:

  • Assigns /32 addresses (single IP, no subnet)
  • No gateway IP on subscriber interface
  • Suitable for broadband access networks

Example:

Subscriber IP: 203.0.113.10/32
Gateway: 10.100.0.1 (on BNG)

Lease Persistence​

abng-dhcpd persists its active lease table to disk so a restart of the daemon does not disrupt subscribers. Leases are written to /opt/athena-bng/run/dhcp-leases.json, atomically (temp file + rename), every 30 seconds and again on shutdown.

Restore on Startup​

On startup, before it begins serving packets, abng-dhcpd restores the leases from this file:

  1. Drop expired — leases that expired while the daemon was down are discarded.
  2. Re-insert survivors — each surviving lease is re-inserted with its IP reserved in the address pool and marked already-notified, because abngd kept the session alive across the dhcpd restart.
  3. Preserve timers — lease and accounting timers use absolute timestamps, so the remaining lease time survives the restart rather than resetting.

Effect​

An abng-dhcpd restart no longer NAKs renewing clients or desyncs the address pool — clients keep their lease. RADIUS Accounting-On is still sent at startup and Accounting-Stop/Off at shutdown. Lease persistence is automatic and requires no configuration.

RADIUS Integration​

Authentication​

RADIUS Access-Request:

  • User-Name — MAC address, lowercase (e.g., "aa:bb:cc:dd:ee:ff")
  • Calling-Station-Id — MAC address
  • NAS-Port-Id — Circuit ID (VLAN interface name)
  • NAS-Identifier — "AthenaBNG"

Authorization​

RADIUS Access-Accept:

  • Framed-IP-Address — Assigned IP address
  • Framed-IP-Netmask — Subnet mask
  • Session-Timeout — Session timeout in seconds
  • Athena-Rate-Down — Download rate (optional)
  • Athena-Rate-Up — Upload rate (optional)

The rate attributes are optional. If RADIUS returns no rate, the subscriber is left unmetered — there is no implicit default rate.

Accounting​

RADIUS Accounting-Request:

  • Acct-Session-Id — Session ID
  • Acct-Status-Type — Start, Stop, or Interim-Update
  • Acct-Input-Octets — Bytes received
  • Acct-Output-Octets — Bytes sent
  • Acct-Session-Time — Session duration

QoS Integration​

When RADIUS supplies rate attributes, the assigned rate is applied as per-subscriber CAKE shaping:

  1. Downstream — CAKE qdisc on the subscriber VLAN interface
  2. Upstream — CAKE on a per-session IFB device (ingress redirect)

No rate = unmetered. A subscriber whose RADIUS reply carries no Athena-Rate-Down / Athena-Rate-Up is left unshaped; there is no implicit default rate.

Rate changes apply on renewal. On lease renewal, if the rate returned by RADIUS differs from the active session's, abng-dhcpd / abngd update it and re-apply QoS in place. The per-session IFB is keyed by session id, which is unchanged across the renewal. (RADIUS CoA can also change rates mid-session.)

Monitoring​

View DHCP Sessions​

abng> show subscribers dhcp

View Session Details​

abng> show subscribers detail 5

Check abng-dhcpd Status​

sudo systemctl status abng-dhcpd

Monitor abng-dhcpd Logs​

sudo journalctl -u abng-dhcpd -f

Troubleshooting​

Sessions Not Appearing​

  1. Check DHCP is enabled: show configuration | match dhcp
  2. Check VLAN demux is enabled: show configuration | match demux
  3. Check VLAN interfaces are created: show vlans
  4. Check RADIUS is reachable (if RADIUS mode): radtest testuser testpass <radius-ip> 1812 <secret>
  5. Check abng-dhcpd logs: journalctl -u abng-dhcpd -f

Sessions Not Getting IP​

  1. Check allocation mode: show configuration | match allocation_mode
  2. Check pools are configured (if pool mode): show configuration | match pools
  3. Check RADIUS returns Framed-IP-Address (if RADIUS mode)
  4. Check abng-dhcpd logs: journalctl -u abng-dhcpd -f

IP Pool Exhaustion​

  1. Check pool size: show configuration | match pools
  2. Check active sessions: show subscribers dhcp | count
  3. Expand pool or reduce lease time
  4. Check for stale leases: journalctl -u abng-dhcpd | grep "lease expired"

Best Practices​

  1. Allocation Mode — Use RADIUS for subscriber-specific IPs
  2. Lease Time — Use 3600s (1 hour) for standard DHCP
  3. Unnumbered — Use /32 addresses for IPoE
  4. Pools — Define separate pools for different subscriber classes
  5. RADIUS — Always configure RADIUS for authentication
  6. QoS — Enable QoS for per-subscriber rate limiting
  7. DNS — Configure DNS servers in pools or via RADIUS

Next Steps​