Monitoring Configuration

Configure Prometheus metrics and syslog forwarding.

Overview

The monitoring section configures:

• Prometheus — Metrics export for time-series monitoring
• Syslog — Log forwarding to centralized syslog server
• Telemetry — Read-only JSON-RPC telemetry (live subscribers + real-time session events) over SSH, for external collectors such as a dashboard or provisioning UI

Configuration Options

prometheus

Prometheus metrics configuration (optional).

monitoring:
  prometheus:
    enabled: true
    listen: "0.0.0.0:9100"
    path: "/metrics"

Prometheus Options

enabled

Enable or disable Prometheus metrics (optional).

prometheus:
  enabled: true

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

CLI:

abng# set monitoring prometheus enabled true

listen

Prometheus listen address and port (optional).

prometheus:
  listen: "0.0.0.0:9100"

Type: String (address:port)
Required: No
Default: "0.0.0.0:9100"
Constraints: Valid IP:port combination

CLI:

abng# set monitoring prometheus listen "0.0.0.0:9100"

path

Prometheus metrics endpoint path (optional).

prometheus:
  path: "/metrics"

Type: String
Required: No
Default: "/metrics"
Constraints: Valid URL path

CLI:

abng# set monitoring prometheus path "/metrics"

bind_address

Bind address for the data-plane daemon /metrics endpoints (abng-demux on port 9101, abng-qos on port 9102). Applies only to those data-plane endpoints — it is separate from the top-level enabled/listen/path exporter above (optional).

prometheus:
  bind_address: "0.0.0.0"

Type: String (IPv4 address)
Required: No
Default: "0.0.0.0"
Constraints: Valid IPv4 address

CLI:

abng# set monitoring prometheus bind-address "0.0.0.0"

vrf

VRF to scope the data-plane /metrics endpoints (abng-demux:9101, abng-qos:9102) to (optional).

When vrf is unset, it defaults to the VRF of the interface with role: management. The endpoints are then bound via SO_BINDTODEVICE and are reachable only inside the management VRF — not on loopback. To bind in the default VRF instead, set vrf to an empty string (""). abng-qos holds CAP_NET_RAW for the VRF bind; if the VRF bind fails it falls back to the default VRF so metrics still serve.

prometheus:
  vrf: "mgmt"

Type: String (VRF name)
Required: No
Default: Management interface's VRF
Constraints: Existing VRF device, or "" to use the default VRF

CLI:

abng# set monitoring prometheus vrf "mgmt"

syslog

Syslog forwarding configuration (optional).

monitoring:
  syslog:
    enabled: true
    server: "10.255.0.20"
    port: 514
    protocol: "udp"

Syslog Options

enabled

Enable or disable syslog forwarding (optional).

syslog:
  enabled: true

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

CLI:

abng# set monitoring syslog enabled true

server

Syslog server IP address (optional).

syslog:
  server: "10.255.0.20"

Type: IPv4 address or hostname
Required: No
Default: None
Constraints: Valid IP or hostname

CLI:

abng# set monitoring syslog server "10.255.0.20"

port

Syslog server port (optional).

syslog:
  port: 514

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

CLI:

abng# set monitoring syslog port 514

protocol

Syslog protocol (optional).

syslog:
  protocol: "udp"

Type: String
Required: No
Default: "udp"
Valid values: "udp", "tcp"

CLI:

abng# set monitoring syslog protocol "tcp"

telemetry

Read-only JSON-RPC telemetry over SSH (optional). When enabled, an external collector can connect over SSH and pull the live subscriber table and a real-time stream of session events (up/down, rate-change) — the same feed the CLI's show subscribers and event monitor use. It is read-only: only show.* queries and the event stream are permitted; configuration and control methods are rejected.

monitoring:
  telemetry:
    enabled: true
    authorized_keys:
      - "ssh-ed25519 AAAA... collector@example"

How it works

SSH carries the authentication, encryption and transport (no new listener or port is opened). abngd renders the configured keys into a key file that sshd serves for the dedicated, unprivileged abng-telemetry account, with each key pinned to a forced command that can only run the read-only bridge. A collector connects as that user and speaks newline-delimited JSON-RPC 2.0 over the SSH channel:

# one-shot query
printf '{"jsonrpc":"2.0","method":"show.subscribers","params":{},"id":1}\n' \
  | ssh -i collector_key abng-telemetry@<bng-mgmt-ip>

# live event stream (send monitor.subscribe, keep the channel open)

The abng-telemetry user and the sshd integration are provisioned by the package; you only manage the keys through configuration.

Telemetry Options

enabled

Enable or disable read-only SSH telemetry access (optional). When set to false, all collector keys are revoked.

telemetry:
  enabled: true

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

CLI:

abng# set monitoring telemetry enabled true

authorized_keys

SSH public keys allowed to pull telemetry (optional). Each entry is a full type base64 [comment] public-key line; it is installed pinned to the read-only bridge, so the key can do nothing else. Add one entry per collector.

telemetry:
  authorized_keys:
    - "ssh-ed25519 AAAA... collector@example"

Type: List of strings (SSH public-key lines)
Required: No
Default: empty
Constraints: Each must be a valid SSH public key (ssh-ed25519, ssh-rsa, ecdsa-sha2-*, …); malformed entries are rejected at commit.

CLI:

abng# set monitoring telemetry authorized_keys "ssh-ed25519 AAAA... collector@example"

Example Configurations

Prometheus Only

monitoring:
  prometheus:
    enabled: true
    listen: "0.0.0.0:9100"
    path: "/metrics"

Syslog Only

monitoring:
  syslog:
    enabled: true
    server: "10.255.0.20"
    port: 514
    protocol: "udp"

Prometheus and Syslog

monitoring:
  prometheus:
    enabled: true
    listen: "0.0.0.0:9100"
    path: "/metrics"
  syslog:
    enabled: true
    server: "10.255.0.20"
    port: 514
    protocol: "udp"

Configuration via CLI

Enable Prometheus

abng> configure
abng# set monitoring prometheus enabled true
abng# commit

Set Prometheus Listen Address

abng# set monitoring prometheus listen "10.255.0.1:9100"
abng# commit

Enable Syslog

abng# set monitoring syslog enabled true
abng# set monitoring syslog server "10.255.0.20"
abng# commit

Verification

View Monitoring Configuration

abng> show configuration | match "^monitoring:"
monitoring:
  prometheus:
    enabled: true
    listen: 0.0.0.0:9100
    path: /metrics
  syslog:
    enabled: true
    server: 10.255.0.20
    port: 514
    protocol: udp

Query Prometheus Metrics

curl http://localhost:9100/metrics

Check Syslog Forwarding

sudo journalctl -u abngd | grep -i syslog

Prometheus Metrics

Session Metrics

Metric	Description
athenabng_sessions_total	Total active sessions
athenabng_sessions_pppoe	PPPoE sessions
athenabng_sessions_dhcp	DHCP sessions
athenabng_sessions_created_total	Total sessions created
athenabng_sessions_terminated_total	Total sessions terminated

QoS Metrics

Metric	Description
athenabng_qos_sessions	Sessions with QoS applied
athenabng_qos_qdiscs	Active CAKE qdiscs

CGNAT Metrics

Metric	Description
athenabng_cgnat_sessions	CGNAT sessions
athenabng_cgnat_pool_utilization	CGNAT pool utilization %

Demux Metrics

Metric	Description
athenabng_vlan_interfaces	Dynamic VLAN interfaces
athenabng_vlan_creation_rate	VLAN creation rate

System Metrics

Metric	Description
athenabng_uptime_seconds	System uptime
athenabng_version_info	Version information

Data-Plane /metrics Endpoints

The abng-demux and abng-qos data-plane daemons expose their own Prometheus /metrics endpoints, independent of the top-level exporter above. They serve plain-text Prometheus exposition over a hand-rolled HTTP responder (no extra dependencies); a bind failure is non-fatal and only logs a warning.

Daemon	Port
abng-demux	9101
abng-qos	9102

The bind address and VRF for these endpoints are controlled by monitoring.prometheus.bind_address (default 0.0.0.0) and monitoring.prometheus.vrf. By default they bind inside the management interface's VRF (see vrf above), so scrape from inside that VRF:

ip vrf exec mgmt curl http://<mgmt-ip>:9102/metrics

abng-demux metrics (port 9101)

Metric	Type	Description
abng_demux_interfaces_created_total	counter	Total VLAN demux interfaces created
abng_demux_interfaces_removed_total	counter	Total VLAN demux interfaces removed
abng_demux_creation_rate_limited_total	counter	Interface creations dropped by the per-profile rate limiter
abng_demux_creation_failures_total	counter	VLAN chain creation failures
abng_demux_capture_ring_drops_total	counter	Frames dropped by the kernel capture ring (receive-buffer overrun)
abng_demux_interfaces_active	gauge	Currently tracked dynamic VLAN interfaces

abng-qos metrics (port 9102)

Metric	Type	Description
abng_qos_qdisc_apply_total	counter	CAKE qdisc apply operations attempted
abng_qos_qdisc_apply_failures_total	counter	CAKE qdisc apply operations that failed
abng_qos_sessions_shaped	gauge	Currently shaped subscriber sessions
abng_qos_ifb_active	gauge	Currently active ingress IFB devices

Deploying the Monitoring Stack

AthenaBNG ships a turnkey on-box monitoring stack (Prometheus + Alertmanager + frr_exporter + node-exporter) under contrib/monitoring/. It scrapes the local endpoints, evaluates the AthenaBNG alert rules, and routes alerts. See the feature overview for what it does and the admin guide for operating it.

Install / update

Run the installer on the BNG as root:

contrib/monitoring/install.sh

The script is idempotent — safe to re-run to pick up config changes. It:

• installs prometheus, prometheus-alertmanager, and prometheus-node-exporter via apt, and fetches the frr_exporter binary from its GitHub release into /usr/local/bin;
• runs every apt/curl call through ip vrf exec mgmt, because egress on the BNG only works via the management VRF;
• installs prometheus.yml, the athenabng-rules.yml alert rules, alertmanager.yml, and the frr_exporter.service unit;
• drops in systemd overrides so Prometheus and Alertmanager themselves launch under ip vrf exec mgmt (relaxing the stock unit sandboxing that would otherwise block the VRF exec);
• rewrites the scrape/alertmanager targets to point at this box's mgmt IP, then validates with promtool and enables/restarts the services.

Why it all runs in the management VRF

The AthenaBNG metrics endpoints bind to the management VRF (SO_BINDTODEVICE), so they are reachable only from inside that VRF and only on the mgmt0 IP (not loopback). Consequently the scraper and every other component run under ip vrf exec mgmt, and all scrape targets are addressed by the mgmt0 IP. This matches the bind_address/vrf behaviour of the data-plane endpoints documented above.

Environment overrides

The installer auto-detects the mgmt VRF and IP; override if needed:

Variable	Default	Purpose
MGMT_VRF	mgmt	Management VRF name
MGMT_IP	mgmt0's IPv4	IP the scrape/alertmanager targets use

MGMT_VRF=mgmt MGMT_IP=10.178.0.20 contrib/monitoring/install.sh

Scrape targets

Prometheus (via the installed prometheus.yml) scrapes these, all on the mgmt IP:

Job	Target	Source
prometheus	<mgmt-ip>:9090	Prometheus self-monitoring
node	<mgmt-ip>:9100	node-exporter (host + systemd unit state)
frr	<mgmt-ip>:9342	frr_exporter (BGP peer + FRR daemon liveness)
abng-demux	<mgmt-ip>:9101	Data-plane demux counters
abng-qos	<mgmt-ip>:9102	Data-plane QoS counters

Prometheus Scrape Configuration

To scrape AthenaBNG from an external Prometheus (instead of, or in addition to, the on-box stack above), add to that Prometheus's scrape config. Remember the data-plane endpoints are mgmt-VRF-bound, so the scraper must reach the mgmt IP:

scrape_configs:
  - job_name: 'athenabng'
    static_configs:
      - targets: ['localhost:9100']
    scrape_interval: 15s
    scrape_timeout: 10s

Grafana Dashboard

Import pre-built dashboard:

1. Open Grafana: http://localhost:3000
2. Import dashboard: grafana/athenabng-dashboard.json
3. Select Prometheus data source
4. View metrics

Syslog Message Format

Messages are forwarded in standard syslog format:

<PRI>TIMESTAMP HOSTNAME TAG[PID]: MESSAGE

Example:

<134>Mar 13 10:30:00 AthenaBNG abngd[1234]: Session 1 (user1) established

Integration with Monitoring Systems

Prometheus + Grafana

# docker-compose.yml
version: '3'
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
  
  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

ELK Stack (Elasticsearch, Logstash, Kibana)

Configure Logstash to receive syslog:

input {
  syslog {
    port => 514
    type => "syslog"
  }
}

filter {
  if [type] == "syslog" {
    grok {
      match => { "message" => "%{SYSLOGLINE}" }
    }
  }
}

output {
  elasticsearch {
    hosts => ["localhost:9200"]
    index => "athenabng-%{+YYYY.MM.dd}"
  }
}

Validation Rules

Field	Validation
prometheus.enabled	Boolean
prometheus.listen	Valid address:port
prometheus.path	Valid URL path
prometheus.bind_address	Valid IPv4 address
prometheus.vrf	VRF name, or "" for default VRF
syslog.enabled	Boolean
syslog.server	Valid IP or hostname
syslog.port	Integer 1-65535
syslog.protocol	One of: udp, tcp
telemetry.enabled	Boolean
telemetry.authorized_keys	List of valid SSH public-key lines (no control characters)

Best Practices

1. Prometheus — Scrape every 15-30 seconds
2. Retention — Keep 15 days of Prometheus data
3. Syslog — Use TCP for reliable delivery
4. Alerts — Set thresholds for session count and resource usage
5. Dashboards — Create custom Grafana dashboards
6. Archival — Archive logs for compliance
7. Security — Restrict access to monitoring endpoints

Troubleshooting

Prometheus Metrics Not Available

1. Check Prometheus is enabled: show configuration | match prometheus
2. Check port is listening: sudo netstat -tlnp | grep 9100
3. Check firewall allows port 9100
4. Query metrics: curl http://localhost:9100/metrics

Syslog Not Forwarding

1. Check syslog is enabled: show configuration | match syslog
2. Check server is reachable: ping 10.255.0.20
3. Check port is open: nc -u 10.255.0.20 514
4. Check abngd logs: journalctl -u abngd -f

High Memory Usage

1. Check Prometheus retention: Reduce if needed
2. Check syslog backlog: Ensure server is reachable
3. Check for log spam: Review log levels

Next Steps

• Configuration Overview — All configuration sections
• Features — Feature documentation
• Architecture — System design