Skip to main content

REST API Configuration

Configure the FastAPI-based management interface.

Overview​

The api section configures the REST API for:

  • Programmatic management of the BNG
  • Subscriber management and monitoring
  • Configuration changes via HTTP
  • Webhook notifications for events
  • Prometheus metrics export

Configuration Options​

enabled​

Enable or disable REST API (optional).

api:
  enabled: true

Type: Boolean
Required: No
Default: false
Valid values: true, false

CLI:

abng# set api enabled true

listen​

Listen address for REST API (optional).

api:
  listen: "0.0.0.0"

Type: IPv4 address or hostname
Required: No
Default: "0.0.0.0"
Constraints: Valid IPv4 address or "0.0.0.0"

Purpose: IP address to bind the API server to.

CLI:

abng# set api listen "0.0.0.0"

port​

REST API listen port (optional).

api:
  port: 8443

Type: Integer
Required: No
Default: 8443
Constraints: Valid port number (1-65535)

Purpose: HTTPS port for API access.

CLI:

abng# set api port 8443

tls_cert​

Path to TLS certificate file (optional).

api:
  tls_cert: "/opt/athena-bng/etc/cert.pem"

Type: String (file path)
Required: No
Default: Auto-generated self-signed cert
Constraints: Valid file path

Purpose: X.509 certificate for HTTPS.

CLI:

abng# set api tls_cert "/opt/athena-bng/etc/cert.pem"

tls_key​

Path to TLS private key file (optional).

api:
  tls_key: "/opt/athena-bng/etc/key.pem"

Type: String (file path)
Required: No
Default: Auto-generated self-signed key
Constraints: Valid file path

Purpose: Private key for HTTPS.

CLI:

abng# set api tls_key "/opt/athena-bng/etc/key.pem"

Example Configurations​

Minimal API Configuration​

api:
  enabled: true

Uses defaults:

  • Listen: 0.0.0.0
  • Port: 8443
  • TLS: Auto-generated self-signed cert

Full API Configuration​

api:
  enabled: true
  listen: "0.0.0.0"
  port: 8443
  tls_cert: "/opt/athena-bng/etc/cert.pem"
  tls_key: "/opt/athena-bng/etc/key.pem"

Custom Port​

api:
  enabled: true
  listen: "10.255.0.1"
  port: 8080

Configuration via CLI​

Enable API​

abng> configure
abng# set api enabled true
abng# commit

Set Listen Address​

abng# set api listen "10.255.0.1"
abng# commit

Set Port​

abng# set api port 8080
abng# commit

Set TLS Certificate​

abng# set api tls_cert "/opt/athena-bng/etc/cert.pem"
abng# set api tls_key "/opt/athena-bng/etc/key.pem"
abng# commit

Verification​

View API Configuration​

abng> show configuration | match "^api:"
api:
  enabled: true
  listen: 0.0.0.0
  port: 8443
  tls_cert: /opt/athena-bng/etc/cert.pem
  tls_key: /opt/athena-bng/etc/key.pem

Check API Status​

curl -k https://localhost:8443/api/health

View API Documentation​

https://localhost:8443/api/docs

Check API Logs​

sudo journalctl -u abng-api -f

API Endpoints​

Authentication​

  • POST /api/v1/auth/login — Obtain JWT token

Subscribers​

  • GET /api/v1/subscribers — List active sessions (filter with ?type=pppoe or ?type=dhcp)
  • GET /api/v1/subscribers/summary — Session counts by type
  • GET /api/v1/subscribers/{id} — Get session details
  • DELETE /api/v1/subscribers/{id} — Disconnect session
  • PUT /api/v1/subscribers/{id}/rate — Change session rate
  • POST /api/v1/subscribers/disconnect-by-interface — Disconnect by interface

Interfaces​

  • GET /api/v1/interfaces — List all interfaces
  • GET /api/v1/interfaces/vlans — List dynamic VLAN interfaces

QoS​

  • GET /api/v1/qos — List sessions with QoS applied
  • GET /api/v1/qos/profiles — List overhead profiles

Routing​

  • GET /api/v1/routing/bgp/summary — BGP neighbor summary
  • GET /api/v1/routing/routes — Kernel routing table

Configuration (admin only)​

  • GET /api/v1/system/config — Get running config (secrets redacted)
  • POST /api/v1/system/config/set — Set candidate config value
  • POST /api/v1/system/config/delete — Delete candidate config key
  • POST /api/v1/system/config/commit — Commit candidate to running
  • POST /api/v1/system/config/rollback — Rollback to archived config
  • POST /api/v1/system/config/discard — Discard candidate changes
  • GET /api/v1/system/config/compare — Diff running vs candidate

System​

  • GET /api/v1/system/health — Uptime and session count
  • GET /api/v1/system/version — Version info

CGNAT​

  • GET /api/v1/cgnat/sessions — CGNAT-steered sessions
  • GET /api/v1/cgnat/stats — CGNAT vs public IP counts

Demux​

  • GET /api/v1/demux/config — Demux configuration
  • GET /api/v1/demux/state — Active dynamic VLAN interfaces

Monitoring​

  • GET /metrics — Prometheus metrics (no auth)
  • GET /api/v1/health — Health check (no auth)
  • GET /api/v1/events/subscribers — SSE event stream
  • GET /api/v1/webhooks — List webhooks
  • POST /api/v1/webhooks — Register webhook (admin)
  • DELETE /api/v1/webhooks/{id} — Delete webhook (admin)

Authentication​

All API endpoints (except /api/v1/health and /metrics) require JWT authentication:

# Get token
TOKEN=$(curl -sk -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}' \
  | jq -r '.access_token')

# Use token
curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers

Example API Calls​

Get Subscriber List​

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers

Disconnect Subscriber​

curl -sk -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers/1

Get BGP Summary​

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/routing/bgp/summary

Get Prometheus Metrics​

curl -sk https://localhost:8443/metrics

TLS Certificate Management​

Generate Self-Signed Certificate​

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Use Let's Encrypt Certificate​

certbot certonly --standalone -d bng.example.com
# Then configure:
# api.tls_cert: /etc/letsencrypt/live/bng.example.com/fullchain.pem
# api.tls_key: /etc/letsencrypt/live/bng.example.com/privkey.pem

Webhooks​

Register webhooks to receive real-time event notifications:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["session.up", "session.down"]
  }' \
  https://localhost:8443/api/v1/webhooks

Validation Rules​

FieldValidation
enabledBoolean
listenValid IPv4 address or "0.0.0.0"
portInteger 1-65535
tls_certValid file path
tls_keyValid file path

Best Practices​

  1. HTTPS Only — Always use HTTPS (TLS) for API
  2. Authentication — Use strong JWT secrets
  3. Firewall — Restrict API access to trusted networks
  4. Monitoring — Monitor API access logs
  5. Webhooks — Use webhooks for real-time integration
  6. Metrics — Scrape Prometheus metrics for monitoring
  7. Documentation — Use Swagger UI at /api/docs

Troubleshooting​

API Not Responding​

  1. Check API is enabled: show configuration | match api
  2. Check service is running: sudo systemctl status abng-api
  3. Check port is listening: sudo netstat -tlnp | grep 8443
  4. Check firewall allows port 8443
  5. Check API logs: journalctl -u abng-api -f

TLS Certificate Error​

curl: (60) SSL certificate problem: self signed certificate

Solution: Use -k flag to skip certificate verification (development only):

curl -sk https://localhost:8443/api/v1/health

Authentication Failed​

  1. Check JWT secret is configured
  2. Check token is valid: echo $TOKEN
  3. Check token is not expired
  4. Check Authorization header format: Authorization: Bearer <token>

Next Steps​