Skip to main content

Architecture Overview

Understand the AthenaBNG system design and component interactions.

High-Level Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                    AthenaBNG Host (Debian 13)                   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              Management Interfaces                       │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │  │
│  │  │  REST API    │  │  SNMP Agent  │  │  abng-cli    │   │  │
│  │  │  (FastAPI)   │  │  (AgentX)    │  │  (JunOS CLI) │   │  │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │  │
│  │         │                 │                 │            │  │
│  │         └─────────────────┼─────────────────┘            │  │
│  │                           │                              │  │
│  │                    ┌──────▼──────┐                       │  │
│  │                    │    abngd    │                       │  │
│  │                    │ (Core Daemon)                       │  │
│  │                    │ Session Mgr │                       │  │
│  │                    │ Config Mgr  │                       │  │
│  │                    │ CoA Listener│                       │  │
│  │                    │ IPC Server  │                       │  │
│  │                    └──────┬──────┘                       │  │
│  │                           │                              │  │
│  │         ┌─────────────────┼─────────────────┐            │  │
│  │         │                 │                 │            │  │
│  │    ┌────▼────┐      ┌─────▼──────┐    ┌────▼────┐       │  │
│  │    │accel-ppp│      │ abng-dhcpd │    │abng-qos │       │  │
│  │    │(PPPoE)  │      │(DHCP/IPoE) │    │(CAKE)   │       │  │
│  │    └────┬────┘      └─────┬──────┘    └────┬────┘       │  │
│  │         │                 │                 │            │  │
│  │         └─────────────────┼─────────────────┘            │  │
│  │                           │                              │  │
│  │                    ┌──────▼──────┐                       │  │
│  │                    │ abng-demux  │                       │  │
│  │                    │(VLAN Demux) │                       │  │
│  │                    │Dynamic VLAN │                       │  │
│  │                    │Creation     │                       │  │
│  │                    └──────┬──────┘                       │  │
│  └─────────────────────────────┼──────────────────────────┘  │
│                                │                              │
│  ┌─────────────────────────────┼──────────────────────────┐  │
│  │         Network Interfaces                             │  │
│  │                                                        │  │
│  │  eth0 (mgmt)  eth1 (trunk)  eth2 (upstream)  eth3 (cgnat) │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
         │                │                  │
         │                │                  │
    Management      Subscriber Access   Upstream/Transit
       Network         (QinQ VLANs)      (BGP/OSPF)

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​

1. Subscriber sends PPPoE PADI (broadcast)
   ↓
2. abng-demux captures PADI, creates VLAN interface
   ↓
3. abngd notifies accel-ppp of new interface
   ↓
4. accel-ppp sends PPPoE PADO (offer)
   ↓
5. Subscriber sends PPPoE PADR (request)
   ↓
6. accel-ppp creates PPP session, triggers ip-up hook
   ↓
7. abng-notify calls abngd with session details
   ↓
8. abngd queries RADIUS for session attributes
   ↓
9. abng-qos applies QoS rules
   ↓
10. Session active, traffic flows

DHCP/IPoE Session Lifecycle​

1. Subscriber sends DHCP Discover (broadcast)
   ↓
2. abng-demux captures Discover, creates VLAN interface
   ↓
3. abng-dhcpd relay forwards to Kea/abng-dhcpd server
   ↓
4. Server sends RADIUS Access-Request with MAC
   ↓
5. RADIUS returns Framed-IP-Address
   ↓
6. Server sends DHCP Offer
   ↓
7. Subscriber sends DHCP Request
   ↓
8. Server sends DHCP ACK
   ↓
9. abng-dhcpd notifies abngd of session
   ↓
10. abng-qos applies QoS rules
    ↓
11. Session active, traffic flows

Configuration Flow​

1. User edits candidate config via CLI or API
   ↓
2. abngd validates candidate against schema
   ↓
3. User runs `commit`
   ↓
4. abngd renders service configs from Jinja2 templates
   ↓
5. abngd archives running config
   ↓
6. abngd atomically replaces running config
   ↓
7. abngd notifies services of config changes
   ↓
8. Services reload configuration

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​

abngd (core)
├── accel-ppp (PPPoE)
├── abng-dhcpd (DHCP)
├── abng-qos (QoS)
├── abng-demux (VLAN demux)
├── FRRouting (BGP/OSPF)
├── nftables (CGNAT)
└── REST API (management)
    └── SNMP Agent (monitoring)

Next Steps​