Skip to main content

Architecture Overview

Understand the AthenaBNG system design and component interactions.

High-Level Architecture​

Core Components​

abngd — Core Daemon​

The central orchestrator that manages:

  • Session Management — Track PPPoE and DHCP sessions
  • Configuration — Load, validate, and apply configuration changes
  • RADIUS CoA — Listen for Change of Authorization requests
  • IPC Server — JSON-RPC interface for CLI, API, and monitoring
  • Service Coordination — Manage accel-ppp, abng-dhcpd, abng-qos, abng-demux

Location: /opt/athena-bng/bin/abngd Socket: /opt/athena-bng/run/abngd.sock Logs: journalctl -u abngd

abng-demux — VLAN Demux Daemon​

Dynamically creates QinQ VLAN sub-interfaces:

  • Packet Capture — AF_PACKET socket with BPF filter on trunk interface
  • VLAN Detection — Parse Ethernet headers and VLAN tags
  • Interface Creation — Create VLAN interfaces on-demand
  • Cleanup — Remove idle interfaces after timeout

Location: /opt/athena-bng/bin/abng-demux Logs: journalctl -u abng-demux

accel-ppp — PPPoE Termination​

Third-party PPPoE server (managed by abngd):

  • Session Termination — Handle PPPoE Discovery and Session stages
  • LCP/IPCP — PPP protocol negotiation
  • IP Assignment — Get IP from RADIUS or pool
  • Event Hooks — Notify abngd via abng-notify on session events

TCP CLI: 127.0.0.1:2001 Config: Generated from template at commit time

abng-dhcpd — DHCP/IPoE Server​

Built-in DHCP server for IPoE subscribers:

  • DHCP Relay — AF_PACKET relay on subscriber VLANs
  • RADIUS Auth — Authenticate via RADIUS Access-Request
  • IP Assignment — Use RADIUS Framed-IP-Address
  • Option 82 — Circuit ID injection for subscriber identification
  • Lease Tracking — Track active leases and expiry

Location: /opt/athena-bng/bin/abng-dhcpd Socket: /opt/athena-bng/run/abng-dhcpd.sock Logs: journalctl -u abng-dhcpd

abng-qos — QoS Orchestrator​

Per-subscriber traffic shaping:

  • CAKE Qdisc — Create and manage CAKE qdiscs
  • IFB Devices — Ingress shaping via Intermediate Functional Block
  • Rate Changes — Apply RADIUS CoA rate changes in-place
  • Overhead Profiles — Adjust overhead based on encapsulation

Location: /opt/athena-bng/bin/abng-qos Logs: journalctl -u abng-qos

abng-cli — Interactive CLI​

JunOS-style management interface:

  • Operational Mode — View state, monitor, execute requests
  • Configuration Mode — Modify candidate config
  • Tab Completion — Context-aware command completion
  • Pipe Filters — Filter output with | match, | count, etc.

Location: /opt/athena-bng/bin/abng

REST API — Management Interface​

FastAPI-based HTTP API:

  • Authentication — JWT token-based auth
  • Endpoints — Subscribers, interfaces, QoS, routing, config
  • Webhooks — Real-time event notifications
  • Metrics — Prometheus-compatible metrics endpoint

Port: 8443 (HTTPS) Docs: https://<host>:8443/api/docs

SNMP Agent — Monitoring​

AgentX subagent for SNMP monitoring:

  • Custom MIB — ATHENA-BNG-MIB under enterprise OID
  • Metrics — Sessions, QoS, CGNAT, demux state
  • Integration — Works with standard SNMP tools

Port: 161 (SNMP)

Data Flow​

PPPoE Session Lifecycle​

DHCP/IPoE Session Lifecycle​

Configuration Flow​

IPC Protocol​

All components communicate with abngd via JSON-RPC 2.0 over Unix domain socket:

{
  "jsonrpc": "2.0",
  "method": "show.subscribers",
  "params": {},
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": [...],
  "id": 1
}

Service Dependencies​

Next Steps​