Exports and Integrations v190

Exports & Integrations

Type: Architecture Scope: Prometheus, VictoriaMetrics, Zabbix, Grafana, connectors Since: v1.39.0 (unified exporter), v1.78.0 (daemon /metrics) Terminology: Glossary & Vocabulary

---

Purpose

See also: Metrics Architecture | Watchdog & Profiles

This page describes how NFTBan metrics reach external monitoring systems. All export paths are adapters — they relay metrics produced by the daemon. Exporters do not define truth, compute health, or query the kernel independently.

---

Export Architecture

nftband daemon (Go)
    |
    +-- /metrics endpoint (localhost:9580)
    |       |
    |       +-- Prometheus (direct scrape)
    |       +-- VictoriaMetrics (direct scrape or vmagent)
    |
    +-- [via shell unified exporter]
            |
            +-- Textfile (.prom) --> node_exporter --> Prometheus/VM --> Grafana
            +-- Zabbix trapper (ZBXD protocol)
            +-- Elasticsearch connector
            +-- Kafka connector
            +-- File connector
            +-- Portal (pro.nftban.com)

Two independent export paths exist. The Go daemon /metrics endpoint serves Prometheus-format metrics directly. The shell unified exporter collects a broader set of system metrics and pushes to multiple targets.

---

Path 1: Daemon /metrics (Primary)

The daemon HTTP endpoint at localhost:9580/metrics is the primary integration path for Prometheus-compatible systems.

Property	Value
Protocol	HTTP GET, Prometheus exposition format
Metrics	108 unique names (promauto registration)
ACL	Localhost only (127.0.0.1, ::1)
Latency	Negligible (in-process registry)
Dependencies	Daemon must be running

Prometheus

Prometheus scrapes /metrics directly. Add to prometheus.yml:

scrape_configs:
  - job_name: 'nftban'
    scrape_interval: 15s
    static_configs:
      - targets: ['127.0.0.1:9580']

Prometheus must run on the same host as NFTBan (localhost ACL).

VictoriaMetrics

VictoriaMetrics scrapes the same endpoint. No NFTBan-specific configuration needed. Use the same scrape config as Prometheus, pointed at vmagent or VictoriaMetrics single-node.

---

Path 2: Shell Unified Exporter (Multi-Target)

The shell unified exporter runs on a 60-second systemd timer and pushes metrics to all configured targets.

Property	Value
Service	nftban-unified-exporter.service
Timer	nftban-unified-exporter.timer (60s, jitter +-30s)
Entry point	/usr/lib/nftban/exporters/nftban_metrics_wrapper.sh
Metrics	~137 unique names across live/extended/inventory groups
User	nftban (least privilege, CAP_NET_ADMIN)
Resources	15% CPU, 128 MB memory, 32 tasks max, 120s timeout

The wrapper tries the Go exporter first (nftban-core metrics export), then falls back to the shell exporter. Only one writes per cycle.

Collection groups

Group	Frequency	Contents
LIVE	Every run (60s)	Daemon, bans, memory, nftables, connections, bandwidth
EXTENDED	Every 5 runs (5 min)	Module status, feed health, watchdog, eventbus
INVENTORY	Every 60 runs (1 hour)	OS, kernel, CPU, hostname, GeoIP, static config

---

Prometheus / Textfile Collector

The shell exporter writes Prometheus-format metrics to a textfile that node_exporter serves.

Property	Value
Output file	/var/lib/node_exporter/textfile_collector/nftban.prom
Format	Prometheus text (HELP/TYPE annotations)
Concurrency	flock-protected atomic writes
Auto-detect	Enabled automatically if node_exporter textfile directory exists

Flow:

Shell exporter --> nftban.prom --> node_exporter --> Prometheus/VM --> Grafana

Grafana

A starter dashboard ships with NFTBan:

Property	Value
File	share/dashboards/grafana/nftban-overview.json
Panels	19 panels across 4 rows (Overview, Bans, Performance, Modules)
Datasource	Templated (${datasource}) for Prometheus or VictoriaMetrics
Metrics source	Shell exporter textfile names (via node_exporter)

Import: Grafana -> Dashboards -> Import -> upload JSON file -> select datasource.

The dashboard uses shell exporter metric names (nftban_status, nftban_active_count, nftban_bans_24h). These differ from daemon /metrics names (nftban_active_bans, nftban_bans_total). The dashboard requires the textfile export path to be active.

---

Zabbix

NFTBan pushes metrics to Zabbix using the ZBXD trapper protocol. No Zabbix agent is required on the target system.

Property	Value
Protocol	ZBXD binary packet over TCP (trapper)
Transport	nc or ncat
Template	share/templates/zabbix/nftban_template_7x.yaml (97 items)
Guide	share/templates/zabbix/TEMPLATE_GUIDE.md
Config	/etc/nftban/conf.d/zabbix.conf

Operational flow

TARGET SYSTEM                              ZABBIX SERVER
Shell exporter collects metrics
    -> awk converts underscores to dots    
       (nftban_daemon_up -> nftban.daemon.up)
    -> strips Prometheus labels
    -> builds ZBXD binary packet           --TCP:10051-->  Trapper receives data
    -> sends via nc/ncat                                   Template matches 97 items
                                                           Triggers evaluate
                                                           Inventory auto-populates

Configuration

Enable in /etc/nftban/conf.d/zabbix.conf:

NFTBAN_ZABBIX_ENABLED=true
NFTBAN_ZABBIX_SERVER=<zabbix-server-ip>
NFTBAN_ZABBIX_PORT=10051
NFTBAN_ZABBIX_HOSTNAME=<hostname-as-in-zabbix>

Template details

The Zabbix template includes:

• 97 trapper items (daemon, bans, feeds, resources, nftables, eventbus, network, connections, inventory, server metrics, conntrack)
• 2 triggers (daemon down = DISASTER, no-data 5m = HIGH)
• 17 inventory auto-population fields (hostname, FQDN, OS, kernel, arch, CPU, MAC, IP, vendor, model, serial, location)

Import: Zabbix -> Data collection -> Templates -> Import -> select YAML file. Set host inventory mode to "Automatic" for inventory auto-population.

Limitations

• Labels are stripped. Per-feed, per-source, per-family breakdown is not available in Zabbix. Use Prometheus for label-based granularity.
• No LLD (Low-Level Discovery) rules. Users cannot auto-discover feeds or modules.
• No TLS. ZBXD is sent over plain TCP.
• No retry logic. Single-shot send; fails silently on network error.

---

Connectors (Elasticsearch, Kafka, File)

The shell exporter includes optional connectors for additional targets. All are shell-only, configured in /etc/nftban/conf.d/connectors.conf.

Connector	Transport	Config Keys
Elasticsearch	HTTP POST /_doc	CONNECTOR_ES_URL, CONNECTOR_ES_INDEX
Kafka	kafkacat producer	CONNECTOR_KAFKA_BROKERS, CONNECTOR_KAFKA_TOPIC
File	JSON append	CONNECTOR_FILE_PATH

Enable with NFTBAN_EXPORT_CONNECTORS=true.

---

Portal (pro.nftban.com)

The shell exporter pushes metrics to the NFTBan portal for centralized fleet monitoring.

Property	Value
Endpoint	https://pro.nftban.com/api/v1/ingest
Auth	Bearer token + host key
Payload	Inventory (hardware, OS, network) + module status + metrics
Config	NFTBAN_PORTAL_ENABLED=true, NFTBAN_PORTAL_API_KEY=<key>

---

Important Rules

1. Exporters do not define truth. They relay what the daemon produces. If an exporter shows a metric and the daemon /metrics does not, the exporter is either reading a different source or is stale.

2. Single writer for textfile. Only one process should write nftban.prom at a time. The metrics wrapper enforces Go-preferred, shell-fallback. Do not run both paths simultaneously.

3. Daemon /metrics is always the reference. When Prometheus numbers and textfile numbers disagree, daemon /metrics is authoritative for runtime metrics. Textfile may have a different collection timestamp.

4. Labels are not available in Zabbix. Zabbix receives scalar values only. Per-feed, per-source, per-country breakdown requires Prometheus.

---

Verification

# Check daemon /metrics is serving
curl -s http://127.0.0.1:9580/metrics | head -5

# Check textfile exporter is running
systemctl status nftban-unified-exporter.timer

# Check textfile output
cat /var/lib/node_exporter/textfile_collector/nftban.prom 2>/dev/null | wc -l

# Check Zabbix is receiving (on Zabbix server)
# Latest Data -> filter by host -> check nftban.daemon.up

# Check Grafana dashboard
# Grafana -> Dashboards -> NFTBan Overview -> verify panels show data