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
  • Restart Recovery — Periodically reconcile sessions and re-assert demux bindings so the data plane self-heals after a daemon restart

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

All SQLite session-database operations run on tokio's blocking thread pool (via spawn_blocking *_async wrappers), so a DB lock or slow query never stalls the async runtime or event handling.

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

Periodic Reconcile & Re-assert Tasks​

Background tasks keep the data plane consistent across restarts:

  • Session reconcile — Periodically prunes stale sessions and re-applies QoS for surviving sessions (idempotent in abng-qos), so shaping recovers after an abng-qos restart.
  • QoS resync on demand — When abng-qos (re)starts it sends a qos.resync message to abngd, which immediately re-applies QoS for every active session rather than waiting for the next periodic reconcile (~60s). Shaping is therefore restored within seconds of an abng-qos restart.
  • Demux re-assert (~30s) — Re-asserts known demux interfaces to abng-dhcpd and accel-ppp. The bind signals are idempotent, so a restart of either service re-binds automatically.

See Restart Recovery & Resilience for the full self-healing flow.

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
  • Restart Recovery — Re-announce tracked interfaces to abngd and re-adopt surviving kernel interfaces after a restart

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

Re-notify Task​

Background task runs every ~30 seconds:

  • Re-announces every tracked interface to abngd
  • Rebuilds abngd's in-memory demux registry (and the downstream abng-dhcpd / accel-ppp bindings) after an abngd restart

Interface Re-adoption​

On startup, demux QinQ interfaces that survived a previous abng-demux run still exist in the kernel:

  • Reconstructs each live VLAN stack via netlink
  • Matches it against a configured profile
  • Re-announces it to abngd

Already-bound subscribers — including idle ones — recover immediately instead of waiting for new traffic to re-trigger interface creation.

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

Session Registration Path​

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

Session Registration Path​

Config Reload Behavior​

abng-dhcpd loads its DHCP/RADIUS config once at startup and has no live reload. On commit, abngd restarts abng-dhcpd only when that config actually changed, so unrelated commits do not disturb active leases.

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
  • Throughput Sampler — Sample CAKE qdiscs every 5 seconds and cache a per-session throughput snapshot in memory
  • Startup Resync — Send qos.resync to abngd on startup so abngd re-applies QoS for all active sessions immediately, restoring shaping within seconds of a restart instead of waiting for the periodic reconcile

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

Throughput Sampler​

Runs a 5-second sampler loop:

  • Reads the egress and ingress CAKE qdiscs for each tracked session
  • Computes current throughput from the byte delta between samples (a ~5s average)
  • Caches the per-session snapshot in memory
  • Serves the cache over the qos.statistics IPC, backing show qos statistics (a fast in-memory read with no per-call qdisc query)

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​

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​