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

1. Subscriber sends PPPoE PADI (broadcast)
   └─ abng-demux captures PADI
   └─ Creates VLAN interface (e.g., eth1.111.500.100)
   └─ Notifies abngd of new interface

2. accel-ppp sends PPPoE PADO (offer)
   └─ Subscriber receives offer

3. Subscriber sends PPPoE PADR (request)
   └─ accel-ppp creates PPP session
   └─ Triggers ip-up hook

4. abng-notify calls abngd with session details
   └─ abngd queries RADIUS for attributes
   └─ Gets IP, rates, session timeout

5. abng-qos applies QoS rules
   └─ Creates CAKE qdisc on PPP interface
   └─ Sets download/upload rates

6. Session active
   └─ Subscriber can send/receive traffic
   └─ abngd tracks session state
   └─ Accounting data collected

7. Subscriber disconnects or timeout
   └─ accel-ppp terminates session
   └─ Triggers ip-down hook
   └─ abng-notify notifies abngd
   └─ abngd removes session from database
   └─ QoS rules removed
   └─ VLAN interface cleaned up after idle timeout

DHCP/IPoE Session Lifecycle

1. Subscriber sends DHCP Discover (broadcast)
   └─ abng-demux captures Discover
   └─ Creates VLAN interface (e.g., eth1.111.500.100)
   └─ Notifies abngd of new interface

2. abng-dhcpd relay receives Discover
   └─ Injects Option 82 Circuit ID (interface name)
   └─ Forwards to DHCP server

3. DHCP server sends DHCP Offer
   └─ Relay forwards back to subscriber

4. Subscriber sends DHCP Request
   └─ Relay forwards to server

5. DHCP server sends DHCP ACK
   └─ Relay forwards to subscriber
   └─ abng-dhcpd notifies abngd

6. abngd creates session
   └─ Queries RADIUS for attributes (if needed)
   └─ Assigns IP address
   └─ Sets session timeout

7. abng-qos applies QoS rules
   └─ Creates CAKE qdisc on subscriber interface
   └─ Sets download/upload rates

8. Session active
   └─ Subscriber can send/receive traffic
   └─ abngd tracks session state
   └─ Accounting data collected

9. Lease expires or subscriber disconnects
   └─ abng-dhcpd terminates session
   └─ abngd removes session from database
   └─ QoS rules removed
   └─ VLAN interface cleaned up after idle timeout

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	Bytes received
bytes_out	Bytes sent
packets_in	Packets received
packets_out	Packets sent
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

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