Skip to main content

Architecture Overview

High-level system design and component interactions.

System Architecture​

AthenaBNG is a multi-process, event-driven broadband network gateway built on Linux with Rust daemons and Python services.

┌─────────────────────────────────────────────────────────────┐
│                    Management Plane                         │
├─────────────────────────────────────────────────────────────┤
│  CLI (abng-cli)  │  REST API (FastAPI)  │  SNMP Agent       │
└────────┬──────────────────┬──────────────────────┬──────────┘
         │                  │                      │
         └──────────────────┼──────────────────────┘
                            │
                   JSON-RPC over Unix socket
                            │
┌───────────────────────────▼──────────────────────────────────┐
│                    Control Plane                             │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   abngd      │  │ abng-demux   │  │  abng-qos    │       │
│  │ (core daemon)│  │ (VLAN demux) │  │ (QoS mgmt)   │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                               │
└───────────────────────────────────────────────────────────────┘
         │                    │                    │
         │                    │                    │
┌────────▼────────┬───────────▼────────┬──────────▼────────┐
│  Data Plane     │  Data Plane        │  Data Plane       │
├─────────────────┼────────────────────┼───────────────────┤
│ accel-ppp       │ abng-dhcpd         │ nftables (CGNAT)  │
│ (PPPoE server)  │ (DHCP/IPoE server) │ FRRouting (BGP)   │
└─────────────────┴────────────────────┴───────────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  Subscriber VLAN  │
                    │   Interfaces      │
                    └───────────────────┘

Component Roles​

Management Plane​

  • CLI (abng-cli) — Interactive shell for operators
  • REST API — Programmatic management interface
  • SNMP Agent — Integration with NOC systems

Control Plane​

  • abngd — Core orchestrator (session management, config, IPC)
  • abng-demux — Dynamic VLAN interface creation
  • abng-qos — Traffic shaping orchestration

Data Plane​

  • accel-ppp — PPPoE termination
  • abng-dhcpd — DHCP/IPoE termination
  • nftables — CGNAT steering
  • FRRouting — BGP/OSPF routing

Data Flow​

Session Establishment (PPPoE)​

1. Subscriber sends PPPoE PADI
   ↓
2. abng-demux captures, creates VLAN interface
   ↓
3. abngd notifies accel-ppp
   ↓
4. accel-ppp negotiates PPPoE, LCP, IPCP
   ↓
5. accel-ppp queries RADIUS for IP
   ↓
6. accel-ppp calls ip-up hook → abng-notify
   ↓
7. abng-notify registers session in abngd
   ↓
8. abngd notifies abng-qos
   ↓
9. abng-qos applies CAKE qdisc
   ↓
10. Session active, traffic flows

Session Termination​

1. Subscriber disconnects or timeout
   ↓
2. accel-ppp calls ip-down hook → abng-notify
   ↓
3. abng-notify removes session from abngd
   ↓
4. abngd notifies abng-qos
   ↓
5. abng-qos removes CAKE qdisc
   ↓
6. abngd sends RADIUS Accounting-Stop
   ↓
7. abng-demux cleanup task removes VLAN interface

IPC Protocol​

All components communicate with abngd via JSON-RPC 2.0 over Unix domain socket at /opt/athena-bng/run/abngd.sock.

Request:

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

Response:

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

Configuration Flow​

1. Operator edits candidate config
   ↓
2. Operator commits candidate
   ↓
3. abngd validates candidate config
   ↓
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 change
   ↓
8. Services reload configuration

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)

Systemd Target​

All services are managed via AthenaBNG.target:

sudo systemctl start AthenaBNG.target
sudo systemctl stop AthenaBNG.target
sudo systemctl status AthenaBNG.target

Next Steps​