Skip to main content

Daemons

Detailed documentation of AthenaBNG daemons and their responsibilities.

abngd — Core Daemon​

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

Responsibilities​

  • 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

Key Components​

SessionManager​

Tracks all active sessions with:

  • Session ID, type, username, IP address
  • Interface and PPP interface
  • QoS rates and overhead profile
  • RADIUS attributes
  • Accounting data

ConfigManager​

Handles configuration lifecycle:

  • Load running config from YAML
  • Validate candidate config
  • Render service configs from Jinja2 templates
  • Archive running config
  • Apply changes atomically

IPC Server​

JSON-RPC 2.0 server on Unix socket:

  • show.subscribers — List sessions
  • show.interfaces — List interfaces
  • show.vlans — List VLAN interfaces
  • show.routes — Show routing table
  • show.bgp — BGP state
  • show.qos — QoS status
  • request.subscriber.disconnect — Disconnect session
  • request.radius.test — Test RADIUS
  • monitor.subscribe — Subscribe to events

CoA Listener​

Listens for RADIUS CoA-Request on UDP port 3799:

  • Looks up session by Acct-Session-Id
  • Updates session rates
  • Notifies abng-qos of rate change
  • Sends CoA-ACK to RADIUS server

Startup​

sudo systemctl start abngd

Verification​

sudo systemctl status abngd
/opt/athena-bng/bin/abng -c "show version"

abng-demux — VLAN Demux Daemon​

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

Responsibilities​

  • 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

Key Components​

Packet Capture​

AF_PACKET socket with BPF filter:

  • Captures PPPoE PADI frames (ethertype 0x8863)
  • Captures DHCP Discover frames (UDP port 67)
  • Filters by configured outer VLAN IDs

VLAN Parser​

Parses Ethernet headers:

  • Extracts VLAN tags (supports arbitrary nesting depth)
  • Handles 802.1Q (C-Tag) and 802.1ad (S-Tag)
  • Validates VLAN ranges

Interface Manager​

Creates and manages VLAN interfaces:

  • Checks if interface already exists
  • Creates VLAN interface with naming convention
  • Brings interface up
  • Notifies abngd of new interface

Cleanup Task​

Background task runs every 60 seconds:

  • Checks each dynamic interface for active sessions
  • Checks traffic counters
  • Removes idle interfaces after timeout
  • Tears down in reverse order

Startup​

sudo systemctl start abng-demux

Verification​

sudo systemctl status abng-demux
ip link show | grep eth1

accel-ppp — PPPoE Server​

Location: /opt/athena-bng/bin/accel-ppp (third-party)
CLI Socket: 127.0.0.1:2001
Logs: journalctl -u accel-ppp

Responsibilities​

  • PPPoE 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

Integration​

abngd manages accel-ppp via:

  • TCP CLI socket on 127.0.0.1:2001
  • Commands: pppoe interface add/del, show sessions, terminate sid <id>
  • Event hooks call abng-notify binary on session events

Startup​

sudo systemctl start accel-ppp

abng-dhcpd — DHCP/IPoE Server​

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

Responsibilities​

  • 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

Key Components​

DHCP Relay​

AF_PACKET relay:

  • Captures DHCP Discover frames on subscriber VLANs
  • Injects Option 82 Circuit ID (interface name)
  • Forwards to DHCP server
  • Routes replies back to correct interface

RADIUS Client​

Authenticates subscribers:

  • Sends Access-Request with MAC address
  • Receives Access-Accept with Framed-IP-Address
  • Handles accounting (Start, Stop, Interim-Update)

DORA State Machine​

DHCP state machine:

  • DISCOVER → RADIUS auth
  • OFFER → Send to subscriber
  • REQUEST → Forward to server
  • ACK → Notify abngd

Lease Tracking​

Tracks active leases:

  • MAC → IP mapping
  • Lease expiry times
  • Session IDs
  • Accounting data

Startup​

sudo systemctl start abng-dhcpd

abng-qos — QoS Orchestrator​

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

Responsibilities​

  • 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

Key Components​

CAKE Manager​

Creates and manages CAKE qdiscs:

  • Creates egress CAKE on subscriber interface
  • Sets download rate
  • Configures overhead and MPU
  • Applies diffserv4 for QoS classes

IFB Manager​

Creates IFB devices for ingress shaping:

  • Creates IFB device (e.g., ifb-ppp0)
  • Redirects ingress to IFB
  • Creates CAKE qdisc on IFB
  • Sets upload rate

Rate Change Handler​

Applies RADIUS CoA rate changes:

  • Receives rate change from abngd
  • Updates CAKE qdisc (no packet loss)
  • Updates IFB qdisc
  • Logs rate change

Startup​

sudo systemctl start abng-qos

abng-cli — Interactive CLI​

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

Responsibilities​

  • Interactive Shell — JunOS-style CLI with tab completion
  • Operational Mode — View state, monitor, execute requests
  • Configuration Mode — Modify candidate config
  • IPC Client — Communicate with abngd via Unix socket

Key Features​

  • Tab completion at every level
  • Command history (persisted to ~/.abng_history)
  • Pipe filters (| match, | count, | save)
  • Context-sensitive help (?)
  • Non-interactive mode (-c flag)

Startup​

/opt/athena-bng/bin/abng

REST API — Management Interface​

Location: /opt/athena-bng/bin/abng-api (Python FastAPI)
Port: 8443 (HTTPS)
Docs: https://<host>:8443/api/docs

Responsibilities​

  • HTTP API — RESTful interface for management
  • Authentication — JWT token-based auth
  • Webhooks — Real-time event notifications
  • Metrics — Prometheus-compatible metrics endpoint

Startup​

sudo systemctl start abng-api

SNMP Agent — Monitoring​

Location: /opt/athena-bng/bin/abng-snmp (Python AgentX)
Port: 161 (SNMP)

Responsibilities​

  • SNMP Subagent — AgentX subagent for net-snmp
  • Custom MIB — ATHENA-BNG-MIB under enterprise OID
  • Metrics — Sessions, QoS, CGNAT, demux state

Startup​

sudo systemctl start snmpd

abng-notify — Event Notifier​

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

Responsibilities​

  • Event Notification — Called by accel-ppp and abng-dhcpd on session events
  • IPC Client — Communicate with abngd via Unix socket
  • Session Registration — Register sessions in abngd database

Called By​

  • accel-ppp on PPPoE session events (ip-up, ip-down)
  • abng-dhcpd on DHCP session events

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)

Startup Order​

  1. abngd (core daemon)
  2. abng-demux (VLAN demux)
  3. accel-ppp (PPPoE)
  4. abng-dhcpd (DHCP)
  5. abng-qos (QoS)
  6. REST API (management)
  7. 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​