Event Hooks

AthenaBNG can execute scripts or fire webhooks when subscriber sessions connect or disconnect. This enables integration with external provisioning systems, billing platforms, logging pipelines, and custom automation.

Hooks are executed asynchronously — they never block or delay the session lifecycle. If a hook fails (timeout, script error, HTTP failure), abngd logs a warning but the session proceeds normally.

Configuration

The event_hooks section supports two event types:

• session_up — fired when a PPPoE or DHCP/IPoE session comes up
• session_down — fired when a session goes down

Each event accepts a list of hooks. Hooks are executed in parallel.

Minimal Example

event_hooks:
  session_up:
    - type: script
      command: "/usr/local/bin/on-session-up.sh"
  session_down:
    - type: script
      command: "/usr/local/bin/on-session-down.sh"

Full Example

event_hooks:
  session_up:
    - type: script
      command: "/usr/local/bin/on-session-up.sh"
      timeout: 10
    - type: webhook
      url: "https://provisioning.example.com/api/session-up"
      method: POST
      timeout: 5
      headers:
        Authorization: "Bearer eyJ..."
        X-Source: "athenabng"
  session_down:
    - type: script
      command: "/usr/local/bin/on-session-down.sh"
      timeout: 10
    - type: webhook
      url: "https://provisioning.example.com/api/session-down"
      timeout: 5
      headers:
        Authorization: "Bearer eyJ..."

Hook Types

Script

Executes a local program via /bin/sh -c. Session details are passed as environment variables.

Parameter	Type	Default	Description
type	string	—	Must be "script"
command	string	—	Shell command to execute
timeout	integer	10	Maximum execution time in seconds

The script inherits a minimal environment plus all ABNG_* variables (see Session Details below).

Example script:

#!/bin/bash
# /usr/local/bin/on-session-up.sh
logger -t abng-hook "Session up: user=${ABNG_USERNAME} ip=${ABNG_IP_ADDRESS} iface=${ABNG_ACCESS_INTERFACE}"

# Update external billing system
curl -s -X POST "https://billing.internal/api/session" \
  -H "Content-Type: application/json" \
  -d "{\"event\": \"${ABNG_EVENT}\", \"username\": \"${ABNG_USERNAME}\", \"ip\": \"${ABNG_IP_ADDRESS}\"}"

Webhook

Sends an HTTP request with session details as a JSON payload.

Parameter	Type	Default	Description
type	string	—	Must be "webhook"
url	string	—	URL to send the request to (http:// or https://)
method	string	"POST"	HTTP method (POST, PUT, or PATCH)
timeout	integer	5	Request timeout in seconds
headers	map	{}	Additional HTTP headers (e.g., Authorization)

The Content-Type header is always set to application/json.

Session Details

Both hook types receive the same session information.

Environment Variables (Script)

Variable	Description	Example
ABNG_EVENT	Event name	session_up, session_down
ABNG_SESSION_ID	Internal session ID	42
ABNG_SESSION_TYPE	Session type	pppoe, dhcp
ABNG_USERNAME	Subscriber username (may be empty for DHCP)	user1@example.com
ABNG_IP_ADDRESS	Assigned IPv4 address	203.0.113.10
ABNG_MAC_ADDRESS	Subscriber MAC address	aa:bb:cc:dd:ee:ff
ABNG_ACCESS_INTERFACE	Subscriber VLAN interface	trunk0.200.20
ABNG_PPP_INTERFACE	PPP interface (PPPoE only)	ppp0
ABNG_RATE_DOWN	Download rate in bits/sec	100000000
ABNG_RATE_UP	Upload rate in bits/sec	40000000
ABNG_ACCT_SESSION_ID	RADIUS Acct-Session-Id	abng-1710000000-42
ABNG_CGNAT	Whether this is a CGNAT subscriber	true, false

JSON Payload (Webhook)

{
  "event": "session_up",
  "session_id": 42,
  "session_type": "pppoe",
  "username": "user1@example.com",
  "ip_address": "203.0.113.10",
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "access_interface": "trunk0.200.20",
  "ppp_interface": "ppp0",
  "rate_down_bps": 100000000,
  "rate_up_bps": 40000000,
  "acct_session_id": "abng-1710000000-42",
  "cgnat": false
}

For DHCP sessions, ppp_interface is omitted from the JSON payload, and username is an empty string.

CLI Configuration

Event hooks can be configured via the CLI:

abng# set event_hooks session_up script command /usr/local/bin/on-session-up.sh
abng# set event_hooks session_up script timeout 10
abng# set event_hooks session_up webhook url https://example.com/api/hook
abng# set event_hooks session_up webhook timeout 5
abng# set event_hooks session_down script command /usr/local/bin/on-session-down.sh
abng# commit

Error Handling

• Script hooks: If the script exits with a non-zero status, stderr is logged at WARN level. If it exceeds the timeout, it is killed.
• Webhook hooks: If the HTTP request fails or returns a non-2xx status, the status code and response body (first 200 chars) are logged at WARN level.
• No retries: Hooks are fire-and-forget. If you need guaranteed delivery, use a webhook endpoint that queues events (e.g., a message broker).
• No session impact: A failing hook never causes a session to be rejected or torn down.

Security Considerations

• Script permissions: Ensure hook scripts are owned by root and not world-writable. abngd runs as root, so hook scripts execute with root privileges.
• Webhook secrets: Use the headers map to pass authentication tokens. Prefer HTTPS for webhook URLs.
• Rate limiting: Hooks fire on every session event. On a busy BNG with thousands of sessions, ensure your webhook endpoint can handle the load.
• Timeouts: Set conservative timeouts. A slow webhook should never cause resource exhaustion in abngd — each hook runs in its own async task.

Use Cases

• Billing integration: Notify a billing platform when sessions start/stop for usage-based charging.
• Provisioning: Trigger downstream provisioning (e.g., DNS record updates, firewall rules) on session events.
• Alerting: Send session events to a SIEM or alerting system.
• Logging: Forward structured session events to an external log aggregator.
• Custom automation: Run arbitrary scripts for per-session setup (e.g., adding iptables rules, updating a local database).