Subscriber Sessions

Comprehensive guide to subscriber session management in AthenaBNG.

Overview

AthenaBNG manages two types of subscriber sessions:

1. PPPoE Sessions — Point-to-Point Protocol over Ethernet (accel-ppp)
2. DHCP/IPoE Sessions — Dynamic Host Configuration Protocol (abng-dhcpd)

Both session types are tracked in a unified session database with support for:

• Per-subscriber QoS rules
• RADIUS authentication and authorization
• Change of Authorization (CoA) for dynamic rate changes
• Session accounting and billing
• Real-time event monitoring

Session Lifecycle

PPPoE Session Lifecycle

DHCP/IPoE Session Lifecycle

Session State

Each session has a state that progresses through the lifecycle:

State	Description
Authenticating	RADIUS authentication in progress
Authorizing	RADIUS authorization in progress
Active	Session established and active
Terminating	Session termination in progress
Terminated	Session terminated

Session Attributes

Each session tracks:

Attribute	Description
id	Unique session ID (u64)
type	PPPoE or DHCP
username	Subscriber username (PPPoE) or MAC (DHCP)
mac_address	Subscriber MAC address
ip_address	Assigned IP address
interface	VLAN interface (e.g., eth1.111.500.100)
ppp_interface	PPP interface (e.g., ppp0) for PPPoE
state	Current session state
speed_down	Download rate (from RADIUS or default)
speed_up	Upload rate (from RADIUS or default)
bytes_in	Cumulative upstream bytes (from the subscriber) — see Per-Session Accounting
bytes_out	Cumulative downstream bytes (to the subscriber)
packets_in	Cumulative upstream packets (from the subscriber)
packets_out	Cumulative downstream packets (to the subscriber)
session_timeout	Session timeout in seconds
idle_timeout	Idle timeout in seconds
acct_session_id	RADIUS Acct-Session-Id (format: abng-<epoch>-<id>)
created_at	Session creation timestamp
updated_at	Last update timestamp

Per-Session Accounting

abngd records per-session traffic counters — bytes_in, bytes_out, packets_in, packets_out — in the session database, refreshing them roughly every 30 seconds.

The counters are read from the subscriber's own interface via sysfs (/sys/class/net/<iface>/statistics/):

• the PPP interface (e.g. ppp0) for PPPoE sessions, and
• the demux VLAN (e.g. sub0.1234.2) for DHCP/IPoE sessions.

On a subscriber-facing interface the kernel's rx direction is upstream (traffic from the subscriber) and maps to bytes_in/packets_in, while tx is downstream (traffic to the subscriber) and maps to bytes_out/packets_out. Values are cumulative since the interface came up.

Because the figures come straight from the interface stats, accounting works uniformly for both shaped and unmetered sessions — it does not require a CAKE qdisc. In the dedicated-interface deployment (each subscriber has its own demux VLAN / ppp interface) the figures are accurate per-session; where an interface is shared between subscribers, the figure aggregates across them.

These counters surface in:

• show subscribers detail — as the Bytes In / Bytes Out fields.
• SNMP — as the Athena MIB subscriber byte totals.

note

These cumulative totals are distinct from the live throughput shown by show qos statistics, which is a 5-second average sampled from the CAKE qdiscs (shaped sessions only). See QoS/CAKE — Monitoring.

Session Management

View Sessions

# List all sessions
abng> show subscribers

# List PPPoE sessions only
abng> show subscribers pppoe

# List DHCP sessions only
abng> show subscribers dhcp

# Show session summary
abng> show subscribers summary

# Show detailed session info
abng> show subscribers detail 1

Disconnect Session

# By session ID
abng> request subscriber disconnect 1

# By interface
abng> request subscriber disconnect interface ppp0

Monitor Sessions

# Real-time session monitoring
abng> monitor subscribers

RADIUS Integration

Sessions are authenticated and authorized via RADIUS:

Authentication

RADIUS Access-Request with:

• User-Name — Username (PPPoE) or MAC (DHCP)
• User-Password — Password (PPPoE only)
• NAS-Identifier — BNG identifier
• NAS-Port-Id — Circuit ID (VLAN interface name)

Authorization

RADIUS Access-Accept with:

• Framed-IP-Address — Assigned IP address
• Framed-IP-Netmask — Subnet mask
• Session-Timeout — Session timeout in seconds
• Athena-Rate-Down — Download rate (Athena VSA)
• Athena-Rate-Up — Upload rate (Athena VSA)

Accounting

RADIUS Accounting-Request with:

• Acct-Session-Id — Session ID
• Acct-Status-Type — Start, Stop, or Interim-Update
• Acct-Input-Octets — Bytes received
• Acct-Output-Octets — Bytes sent
• Acct-Session-Time — Session duration in seconds

QoS Integration

Each session can have per-subscriber QoS rules applied:

Default QoS

qos:
  default_down: "100mbit"
  default_up: "40mbit"

RADIUS Override

RADIUS can override default rates:

Athena-Rate-Down = "50mbit"
Athena-Rate-Up = "20mbit"

QoS Application

When a session is established:

1. abng-qos creates CAKE qdisc on subscriber interface
2. Sets download rate (egress shaping)
3. Creates IFB device for ingress shaping
4. Sets upload rate on IFB

Change of Authorization (CoA)

RADIUS server can modify session rates dynamically:

# RADIUS server sends CoA-Request with:
Acct-Session-Id = "abng-1709312400-1"
Athena-Rate-Down = "25mbit"
Athena-Rate-Up = "10mbit"

abngd receives CoA and:

1. Looks up session by Acct-Session-Id
2. Updates session rates
3. Applies new rates to CAKE qdisc (no packet loss)
4. Sends CoA-ACK to RADIUS server

Session Termination

Sessions can be terminated by:

1. Subscriber Disconnect — Subscriber closes connection
2. Session Timeout — Session timeout reached
3. Idle Timeout — No traffic for idle timeout period
4. Manual Disconnect — Administrator disconnects via CLI/API
5. RADIUS Disconnect-Request — RADIUS server requests disconnect

Session Database

Sessions are stored in SQLite database with WAL (Write-Ahead Logging):

/opt/athena-bng/var/sessions.db

Database is persisted across restarts and includes:

• Session state
• Accounting data
• Timestamps
• RADIUS attributes

Monitoring

Real-Time Monitoring

abng> monitor subscribers

Displays events:

• session_up — Session established
• session_down — Session terminated
• rate_change — Rate changed via CoA
• error — Session error

Metrics

# Get session counts
abng> show subscribers summary

# Get QoS coverage
abng> show qos | count

# Get CGNAT sessions
abng> show configuration | match cgnat

Prometheus Metrics

athenabng_sessions_total
athenabng_sessions_pppoe
athenabng_sessions_dhcp
athenabng_sessions_created_total
athenabng_sessions_terminated_total

Best Practices

1. RADIUS — Always configure RADIUS for authentication
2. QoS — Enable QoS for fair bandwidth allocation
3. Monitoring — Monitor session count and churn rate
4. Timeouts — Set appropriate session and idle timeouts
5. Accounting — Enable accounting for billing
6. CoA — Use CoA for dynamic rate management
7. Testing — Test with real subscriber traffic

Troubleshooting

Sessions Not Appearing

1. Check VLAN demux is enabled: show configuration | match demux
2. Check VLAN interfaces are created: show vlans
3. Check RADIUS is reachable: radtest testuser testpass <radius-ip> 1812 <secret>
4. Check service logs: journalctl -u abngd -f

Sessions Disconnecting Frequently

1. Check session timeout: show configuration | match session_timeout
2. Check RADIUS timeout
3. Check network stability
4. Check service logs for errors

QoS Not Applying

1. Check QoS is enabled: show configuration | match qos
2. Check CAKE qdisc exists: tc qdisc show
3. Check abng-qos logs: journalctl -u abng-qos -f

Next Steps

• VLAN Demux — Dynamic VLAN creation
• PPPoE Termination — PPPoE details
• DHCP/IPoE — DHCP details
• QoS/CAKE — Traffic shaping details