-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration Reference
Antonios Voulvoulis edited this page Mar 24, 2026
·
23 revisions
Complete reference for the central configuration file.
NFTBan uses a central configuration file that all scripts source for consistency. This ensures:
- All paths are consistent across all modules
- No hardcoded values in scripts
- Easy configuration management
- Distro-agnostic operation
Main Config File: /etc/nftban/nftban.conf
# =============================================================================
# SYSTEM INFORMATION
# =============================================================================
NFTBAN_VERSION="1.39.0"
NFTBAN_CONFIG_VERSION="2"| Variable | Default | Description |
|---|---|---|
NFTBAN_VERSION |
"1.39.0" | NFTBan version (read-only) |
NFTBAN_CONFIG_VERSION |
"2" | Config format version |
NFTBan uses a file-based metrics backend with optional export adapters.
# =============================================================================
# METRICS CONFIGURATION
# =============================================================================
# Master switch for unified exporter
NFTBAN_EXPORT_ENABLED="true"
# Export adapters (all optional, OFF by default)
NFTBAN_EXPORT_PROMETHEUS="false" # Write textfile for node_exporter
# Prometheus textfile location (if enabled)
NFTBAN_PROMETHEUS_TEXTFILE="/var/lib/node_exporter/textfile_collector/nftban.prom"| Variable | Default | Description |
|---|---|---|
NFTBAN_EXPORT_ENABLED |
"true" | Enable unified exporter |
NFTBAN_EXPORT_PROMETHEUS |
"false" | Enable Prometheus textfile export (OFF by default) |
NFTBAN_PROMETHEUS_TEXTFILE |
(path) | Prometheus metrics file location |
Architecture Overview:
NFTBan's metrics architecture:
-
Backend:
stats.json+bans.log(native storage, always active) - Collection: Unified exporter with collection groups
- Export: Optional adapters (Prometheus, Zabbix, connectors)
Collection Groups (managed by unified exporter):
| Group | Interval | Metrics |
|---|---|---|
| live | 60s | Active bans, event rate, daemon status |
| extended | 5min | Feed stats, module health |
| inventory | 1hr | Server info, configuration state |
Enable Prometheus Export:
# Prometheus export is OFF by default
# To enable:
nftban config set NFTBAN_EXPORT_PROMETHEUS=true
# Or edit /etc/nftban/nftban.conf:
NFTBAN_EXPORT_PROMETHEUS="true"Note: You need node_exporter installed to scrape Prometheus textfile metrics.
Configuration file: /etc/nftban/conf.d/zabbix.conf
Zabbix export is handled by the unified exporter (nftban-unified-exporter.timer).
# =============================================================================
# ZABBIX INTEGRATION
# =============================================================================
NFTBAN_ZABBIX_ENABLED="NO"
NFTBAN_ZABBIX_SERVER=""
NFTBAN_ZABBIX_PORT="10051"
NFTBAN_ZABBIX_HOSTNAME=""
# TLS Settings
NFTBAN_ZABBIX_TLS_MODE="none" # none, psk, cert
NFTBAN_ZABBIX_PSK_IDENTITY=""
NFTBAN_ZABBIX_PSK_FILE=""
# LLD Settings
NFTBAN_ZABBIX_LLD_ENABLED="YES"
NFTBAN_ZABBIX_LLD_INTERVAL="3600"| Variable | Default | Description |
|---|---|---|
NFTBAN_ZABBIX_ENABLED |
"NO" | Enable Zabbix trapper export |
NFTBAN_ZABBIX_SERVER |
"" | Zabbix server address |
NFTBAN_ZABBIX_PORT |
"10051" | Zabbix trapper port |
NFTBAN_ZABBIX_HOSTNAME |
"" | Host name in Zabbix (default: system hostname) |
NFTBAN_ZABBIX_TLS_MODE |
"none" | TLS mode: none, psk, cert |
NFTBAN_ZABBIX_LLD_ENABLED |
"YES" | Enable Low-Level Discovery |
Configuration file: /etc/nftban/conf.d/connectors.conf
Supports: Elasticsearch, Kafka, syslog, webhook, file export.
# =============================================================================
# CONNECTORS FRAMEWORK
# =============================================================================
NFTBAN_CONNECTORS_ENABLED="NO"
NFTBAN_CONNECTORS_INTERVAL="60"
# Elasticsearch
NFTBAN_CONNECTOR_ELASTICSEARCH_ENABLED="NO"
NFTBAN_CONNECTOR_ELASTICSEARCH_URL=""
NFTBAN_CONNECTOR_ELASTICSEARCH_INDEX="nftban"
# Kafka
NFTBAN_CONNECTOR_KAFKA_ENABLED="NO"
NFTBAN_CONNECTOR_KAFKA_BROKERS=""
NFTBAN_CONNECTOR_KAFKA_TOPIC="nftban"
# Syslog
NFTBAN_CONNECTOR_SYSLOG_ENABLED="NO"
NFTBAN_CONNECTOR_SYSLOG_SERVER=""
NFTBAN_CONNECTOR_SYSLOG_PORT="514"
# Webhook
NFTBAN_CONNECTOR_WEBHOOK_ENABLED="NO"
NFTBAN_CONNECTOR_WEBHOOK_URL=""
# File
NFTBAN_CONNECTOR_FILE_ENABLED="NO"
NFTBAN_CONNECTOR_FILE_PATH="/var/lib/nftban/exports/metrics.ndjson"| Connector | Variables | Description |
|---|---|---|
| Elasticsearch |
ELASTICSEARCH_URL, INDEX, USER, PASS
|
Export to ES/OpenSearch |
| Kafka |
KAFKA_BROKERS, TOPIC, SECURITY_PROTOCOL
|
Export to Kafka topics |
| Syslog |
SYSLOG_SERVER, PORT, PROTOCOL, FORMAT
|
RFC 5424 syslog export |
| Webhook |
WEBHOOK_URL, AUTH, TOKEN
|
HTTP POST to custom endpoint |
| File |
FILE_PATH, FORMAT, ROTATION
|
NDJSON/JSON/CSV file export |
# =============================================================================
# GEOIP CONFIGURATION
# =============================================================================
NFTBAN_GEOIP_ENABLED="false"
#GEOIP_DB_SOURCE="dbip" # "dbip" (default) or "maxmind"
#GEOIP_MAXMIND_LICENSE_KEY="" # Only required if using MaxMind| Variable | Default | Description |
|---|---|---|
NFTBAN_GEOIP_ENABLED |
"false" | Enable GeoIP blocking |
GEOIP_DB_SOURCE |
"dbip" | Database provider: dbip (default, no registration) or maxmind
|
GEOIP_MAXMIND_LICENSE_KEY |
"" | MaxMind license key (only required if using MaxMind) |
Default Provider: DB-IP Lite - no registration or license key required. Works out of the box.
Optional: To use MaxMind GeoLite2 instead, get free license key from https://www.maxmind.com/en/geolite2/signup
# =============================================================================
# THREAT FEEDS
# =============================================================================
NFTBAN_FEEDS_ENABLED="false"
NFTBAN_FEEDS_AUTO_UPDATE="true"| Variable | Default | Description |
|---|---|---|
NFTBAN_FEEDS_ENABLED |
"false" | Enable threat intelligence feeds |
NFTBAN_FEEDS_AUTO_UPDATE |
"true" | Automatic feed updates via timer |
Available Feeds:
- FireHOL Level 1-3
- Emerging Threats
- Spamhaus DROP/EDROP
- DShield
- And more...
# =============================================================================
# SURICATA IDS INTEGRATION
# =============================================================================
NFTBAN_SURICATA_ENABLED="true"
NFTBAN_SURICATA_EVE_LOG="/var/log/nftban/suricata/eve-alerts.json"
NFTBAN_SURICATA_LOG_DIR="/var/log/nftban/suricata"
NFTBAN_SURICATA_BAN_THRESHOLD="100"
NFTBAN_SURICATA_SCORE_DECAY="3600"
NFTBAN_SURICATA_CLOUDFLARE_WHITELIST="false"| Variable | Default | Description |
|---|---|---|
NFTBAN_SURICATA_ENABLED |
"true" | Enable Suricata IDS integration |
NFTBAN_SURICATA_EVE_LOG |
"/var/log/nftban/suricata/eve-alerts.json" | Alert-only EVE output (daemon reads this) |
NFTBAN_SURICATA_LOG_DIR |
"/var/log/nftban/suricata" | Suricata log directory |
NFTBAN_SURICATA_BAN_THRESHOLD |
"100" | IP score threshold for auto-ban |
NFTBAN_SURICATA_SCORE_DECAY |
"3600" | Score decay time (seconds) |
NFTBAN_SURICATA_CLOUDFLARE_WHITELIST |
"false" | Auto-whitelist Cloudflare IPs |
Note: Suricata uses a dual-output model:
-
eve-alerts.json- Alert-only output for daemon (low I/O, always enabled) -
eve-audit.json- Optional admin/forensic log (disabled by default) -
eve-stats.json- Optional stats/flow log for capacity planning (disabled by default)
# =============================================================================
# WEB GUI
# =============================================================================
NFTBAN_GUI_ENABLED="false"
NFTBAN_GUI_ADDR="127.0.0.1:3940"| Variable | Default | Description |
|---|---|---|
NFTBAN_GUI_ENABLED |
"false" | Enable web GUI |
NFTBAN_GUI_ADDR |
"127.0.0.1:3940" | GUI listen address:port |
GUI Commands:
nftban gui enable # Enable and start GUI
nftban gui disable # Disable GUI
nftban gui status # Check GUI status# =============================================================================
# SECURITY FEATURES
# =============================================================================
NFTBAN_PORTSCAN_ENABLED="false"
NFTBAN_DDOS_ENABLED="false"
NFTBAN_LOGIN_MONITOR_ENABLED="false"| Variable | Default | Description |
|---|---|---|
NFTBAN_PORTSCAN_ENABLED |
"false" | Enable port scan detection |
NFTBAN_DDOS_ENABLED |
"false" | Enable DDoS protection |
NFTBAN_LOGIN_MONITOR_ENABLED |
"false" | Enable login monitoring module |
Enable via CLI:
nftban portscan enable
nftban ddos enable
nftban login enableNFTBan modules (login, ddos, portscan) support dual-mode operation:
┌─────────────────────────────────────────────────────────────────┐
│ Mode Selection (main.conf) │
│ XXXX_MODE = "auto" | "classic" | "suricata" | "hybrid" │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────┴─────────────────┐
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ CLASSIC MODE │ │ SURICATA MODE │
│ (No Suricata req'd) │ │ (Suricata required) │
├───────────────────────┤ ├───────────────────────┤
│ - Journalctl parsing │ │ - EVE JSON alerts │
│ - Log file monitoring │ │ - Network-level IDS │
│ - Pattern matching │ │ - Signature-based │
│ - Local detection │ │ - Deep inspection │
│ - Config: classic.conf│ │ - Config: suricata.conf│
└───────────────────────┘ └───────────────────────┘
Mode Behavior:
| Mode | Behavior |
|---|---|
auto |
Auto-detect: use Suricata if available, else Classic |
classic |
Force Classic mode (journalctl/log parsing only) |
suricata |
Force Suricata mode (EVE JSON parsing only) |
hybrid |
Both run simultaneously, scores combined |
Suricata Availability Checks (for auto mode):
- Binary exists:
/usr/bin/suricata - Service running:
systemctl is-active suricata - EVE file fresh: Updated within last 60 seconds
If 2+ checks pass -> Suricata is available.
EVE JSON Path (Critical):
All modules MUST use NFTBan's dedicated alert-only EVE output:
# CORRECT - NFTBan's optimized alert-only output
/var/log/nftban/suricata/eve-alerts.json
# WRONG - Suricata's default full output (DO NOT USE)
/var/log/suricata/eve.jsonsuricata.conf Settings (each module):
# EVE path (must match YAML profile output)
XXXX_SURICATA_EVE_FILE="/var/log/nftban/suricata/eve-alerts.json"
# Detection toggles (module-specific)
XXXX_SURICATA_DETECT_*="true"
# Scoring (0.0-1.0 scale for severity)
XXXX_SURICATA_SCORE_SEVERITY_1="0.10" # Low
XXXX_SURICATA_SCORE_SEVERITY_2="0.20" # Medium
XXXX_SURICATA_SCORE_SEVERITY_3="0.35" # High
XXXX_SURICATA_SCORE_SEVERITY_4="0.50" # Critical
# Action thresholds
XXXX_SURICATA_THRESHOLD_OBSERVE="0.25"
XXXX_SURICATA_THRESHOLD_BLOCK_SHORT="0.45"
XXXX_SURICATA_THRESHOLD_BLOCK_LONG="0.65"
XXXX_SURICATA_THRESHOLD_BLOCK_PERMANENT="0.85"# =============================================================================
# LOGGING
# =============================================================================
NFTBAN_LOG_LEVEL="INFO"
NFTBAN_COLOR_OUTPUT="true"| Variable | Default | Options | Description |
|---|---|---|---|
NFTBAN_LOG_LEVEL |
"INFO" | DEBUG, INFO, WARN, ERROR | Log verbosity level |
NFTBAN_COLOR_OUTPUT |
"true" | true, false | Enable colored CLI output |
# =============================================================================
# DEBUG TRACE
# =============================================================================
NFTBAN_DEBUG_TRACE="false"
NFTBAN_DEBUG_TRACE_LOG="/var/log/nftban/debug_trace.log"| Variable | Default | Description |
|---|---|---|
NFTBAN_DEBUG_TRACE |
"false" | Enable debug trace for troubleshooting |
NFTBAN_DEBUG_TRACE_LOG |
"/var/log/nftban/debug_trace.log" | Debug trace log file |
How Debug Trace Works:
- Each script logs START/END with unique trace ID
- If START exists without END = script crashed/stuck
- Use
nftban debug trace orphansto find stuck scripts
Commands:
nftban debug enable # Enable trace
nftban debug disable # Disable trace
nftban debug trace orphans # Find stuck scripts
nftban smoke run # Run smoke test# =============================================================================
# PATHS (DO NOT MODIFY UNLESS YOU KNOW WHAT YOU'RE DOING)
# =============================================================================
# Binary paths
NFTBAN_BIN="/usr/bin/nftban"
NFTBAN_CORE_BIN="/usr/lib/nftban/bin/nftban-core"
NFTBAN_UI_BIN="/usr/sbin/nftban-ui"
NFTBAN_AUTH_BIN="/usr/libexec/nftban-ui-auth"
# Directory paths
NFTBAN_LIB_DIR="/usr/lib/nftban"
NFTBAN_CONFIG_DIR="/etc/nftban"
NFTBAN_DATA_DIR="/var/lib/nftban"
NFTBAN_LOG_DIR="/var/log/nftban"
NFTBAN_CACHE_DIR="/var/cache/nftban"
NFTBAN_RUN_DIR="/run/nftban"
NFTBAN_DISTRO_CONF_DIR="/etc/nftban/distros"| Variable | Default | Description |
|---|---|---|
NFTBAN_BIN |
"/usr/bin/nftban" | Main CLI binary |
NFTBAN_CORE_BIN |
"/usr/lib/nftban/bin/nftban-core" | Go core binary |
NFTBAN_UI_BIN |
"/usr/sbin/nftban-ui" | Web GUI binary |
NFTBAN_AUTH_BIN |
"/usr/libexec/nftban-ui-auth" | Auth helper binary |
NFTBAN_LIB_DIR |
"/usr/lib/nftban" | Library directory |
NFTBAN_CONFIG_DIR |
"/etc/nftban" | Configuration directory |
NFTBAN_DATA_DIR |
"/var/lib/nftban" | Data directory |
NFTBAN_LOG_DIR |
"/var/log/nftban" | Log directory |
NFTBAN_CACHE_DIR |
"/var/cache/nftban" | Cache directory |
NFTBAN_RUN_DIR |
"/run/nftban" | Runtime directory |
NFTBAN_DISTRO_CONF_DIR |
"/etc/nftban/distros" | Distro configs |
Warning: These paths follow FHS standard. Only modify if you have a specific requirement.
Module-specific configuration is stored in /etc/nftban/conf.d/ with organized subdirectories:
/etc/nftban/conf.d/
├── banner.conf # Banner customization
├── mail.conf # Email alert configuration
├── stats.conf # Statistics settings
├── trust.conf # Trusted provider whitelisting (CDN/cloud)
├── zabbix.conf # Zabbix export configuration
├── ddos/ # DDoS protection configs
│ ├── main.conf # Main DDoS settings
│ ├── classic.conf # Classic nftables mode
│ └── suricata.conf # Suricata IDS mode
├── portscan/ # Port scan detection configs
│ ├── main.conf # Main portscan settings
│ ├── classic.conf # Classic nftables mode
│ └── suricata.conf # Suricata IDS mode
├── login/ # Login monitoring configs
│ ├── main.conf # Main login settings
│ ├── services.conf # Per-service configuration
│ ├── scorer.conf # Scoring engine thresholds
│ ├── classic.conf # Classic mode
│ └── suricata.conf # Suricata mode
├── botscan/ # Bot scanner configs
│ └── main.conf # Bot detection settings
└── panels/ # Control panel configs
└── directadmin/ # DirectAdmin panel
└── main.conf # Panel configuration
DDoS protection uses a dual-mode architecture with dedicated log files for each mode.
Main Config (main.conf):
# Master switch (default: false, enable with 'nftban ddos enable')
DDOS_ENABLED="false"
# Mode selection: auto, classic, suricata, hybrid
DDOS_MODE="auto"
# Auto-detection settings (for "auto" mode)
DDOS_AUTO_CHECK_SERVICE="true" # Check if Suricata service running
DDOS_AUTO_CHECK_BINARY="true" # Check if Suricata binary exists
DDOS_AUTO_CHECK_EVE_FILE="true" # Check if EVE file is fresh
DDOS_EVE_FRESHNESS_THRESHOLD="60" # Seconds for EVE freshness
# Suricata settings (for auto-detection)
DDOS_SURICATA_SERVICE_NAME="suricata"
DDOS_SURICATA_BINARY="/usr/bin/suricata"
# Hybrid mode settings
DDOS_HYBRID_CLASSIC_LAYER0="true" # Classic as Layer 0 in hybrid
DDOS_HYBRID_CLASSIC_MULTIPLIER="0.5"
# nftables settings
DDOS_NFT_TABLE_IPV4="ip nftban"
DDOS_NFT_TABLE_IPV6="ip6 nftban"
DDOS_NFT_CHAIN="ddos_protection"
# Safety limits
DDOS_MAX_BLOCKED_IPS="10000"
DDOS_MAX_BAN_DURATION="86400" # 24 hours max
DDOS_MIN_REBLOCK_INTERVAL="60"
# Whitelist settings
DDOS_WHITELIST_FILE="/etc/nftban/whitelist.d/ddos-whitelist.conf"
DDOS_WHITELIST_LOCALHOST="true"
DDOS_WHITELIST_PRIVATE="false"
DDOS_WHITELIST_CLOUDFLARE="false"
# Notifications
DDOS_NOTIFY_EMAIL="false"
DDOS_NOTIFY_WEBHOOK="false"
DDOS_NOTIFY_THRESHOLD="0.80"Classic Mode (classic.conf):
# SYN flood protection
DDOS_CLASSIC_SYN_RATE="25/second"
DDOS_CLASSIC_SYN_BURST="50"
# Connection limits per service (per source IP)
DDOS_CLASSIC_SSH_CONN_LIMIT="10"
DDOS_CLASSIC_HTTP_CONN_LIMIT="100"
DDOS_CLASSIC_HTTPS_CONN_LIMIT="100"
DDOS_CLASSIC_SMTP_CONN_LIMIT="20"
DDOS_CLASSIC_DNS_CONN_LIMIT="50"
DDOS_CLASSIC_GENERIC_CONN_LIMIT="50"
# ICMP rate limiting
DDOS_CLASSIC_ICMP_RATE="10/second"
DDOS_CLASSIC_ICMP_BURST="20"
DDOS_CLASSIC_ICMPV6_RATE="10/second"
DDOS_CLASSIC_ICMPV6_BURST="20"
# UDP flood protection
DDOS_CLASSIC_UDP_RATE="100/second"
DDOS_CLASSIC_UDP_BURST="200"
# Port flood protection
DDOS_CLASSIC_PORT_FLOOD_RATE="50/second"
DDOS_CLASSIC_PORT_FLOOD_BURST="100"
# Auto-tuning (based on system resources)
DDOS_CLASSIC_AUTO_TUNE="true"
# Ban durations
DDOS_CLASSIC_BAN_DURATION_SHORT="300" # 5 minutes
DDOS_CLASSIC_BAN_DURATION_MEDIUM="1800" # 30 minutes
DDOS_CLASSIC_BAN_DURATION_LONG="3600" # 1 hour
DDOS_CLASSIC_ESCALATE_THRESHOLD="3"
# Logging
DDOS_CLASSIC_LOG_FILE="/var/log/nftban/ddos-classic.log"
DDOS_CLASSIC_LOG_LEVEL="INFO"Suricata Mode (suricata.conf):
# EVE JSON path (must match YAML profile)
DDOS_SURICATA_EVE_FILE="/var/log/nftban/suricata/eve-alerts.json"
# Detection toggles
DDOS_SURICATA_DETECT_SYN_FLOOD="true"
DDOS_SURICATA_DETECT_UDP_FLOOD="true"
DDOS_SURICATA_DETECT_ICMP_FLOOD="true"
DDOS_SURICATA_DETECT_DNS_AMPLIFICATION="true"
DDOS_SURICATA_DETECT_NTP_AMPLIFICATION="true"
DDOS_SURICATA_DETECT_HTTP_FLOOD="true"
DDOS_SURICATA_DETECT_SLOWLORIS="true"
# Scoring (0.0 - 1.0 scale)
# Severity 1=High, 2=Medium, 3=Low, 4=Info (matches Suricata)
DDOS_SURICATA_SCORE_SEVERITY_1="0.50" # Critical
DDOS_SURICATA_SCORE_SEVERITY_2="0.35" # High
DDOS_SURICATA_SCORE_SEVERITY_3="0.20" # Medium
DDOS_SURICATA_SCORE_SEVERITY_4="0.10" # Low
# Bonus scores
DDOS_SURICATA_SCORE_SYN_FLOOD="0.15"
DDOS_SURICATA_SCORE_AMPLIFICATION="0.20"
DDOS_SURICATA_SCORE_HTTP_FLOOD="0.15"
DDOS_SURICATA_SCORE_REPEAT_5="0.10" # 5+ alerts
DDOS_SURICATA_SCORE_REPEAT_10="0.20" # 10+ alerts
DDOS_SURICATA_SCORE_REPEAT_20="0.30" # 20+ alerts
DDOS_SURICATA_SCORE_BAD_REPUTATION="0.15"
DDOS_SURICATA_SCORE_HIGH_RISK_GEO="0.10"
# Action thresholds
DDOS_SURICATA_THRESHOLD_OBSERVE="0.30"
DDOS_SURICATA_THRESHOLD_BLOCK_SHORT="0.50"
DDOS_SURICATA_THRESHOLD_BLOCK_LONG="0.70"
DDOS_SURICATA_THRESHOLD_BLOCK_PERMANENT="0.90"
# Ban durations
DDOS_SURICATA_BAN_DURATION_SHORT="600" # 10 minutes
DDOS_SURICATA_BAN_DURATION_LONG="3600" # 1 hour
DDOS_SURICATA_BAN_DURATION_PERMANENT="86400" # 24 hours
DDOS_SURICATA_SCORE_DECAY="3600"
DDOS_SURICATA_ALERT_WINDOW="120"
# Integration
DDOS_SURICATA_USE_FEEDS="true"
DDOS_SURICATA_USE_GEOIP="true"
DDOS_SURICATA_USE_CLASSIC_LAYER0="true"
# Performance
DDOS_SURICATA_BATCH_SIZE="100"
DDOS_SURICATA_POLL_INTERVAL_MS="500"
# Logging
DDOS_SURICATA_LOG_FILE="/var/log/nftban/ddos-suricata.log"
DDOS_SURICATA_LOG_LEVEL="INFO"
DDOS_SURICATA_LOG_SCORES="true"Log Files:
-
/var/log/nftban/ddos.log- Main DDoS module log -
/var/log/nftban/ddos-classic.log- Classic mode specific log -
/var/log/nftban/ddos-suricata.log- Suricata mode specific log
User Overrides: Create .local files that survive package upgrades:
/etc/nftban/conf.d/ddos/main.conf.local
/etc/nftban/conf.d/ddos/classic.conf.local
/etc/nftban/conf.d/ddos/suricata.conf.localPortscan detection uses a dual-mode architecture with support for journalctl on systemd systems.
Main Config (main.conf):
# Master switch
PORTSCAN_ENABLED="true"
# Mode selection: auto, classic, suricata, hybrid
PORTSCAN_MODE="auto"
# Auto-detection settings (for "auto" mode)
PORTSCAN_AUTO_CHECK_SERVICE="true"
PORTSCAN_AUTO_CHECK_BINARY="true"
PORTSCAN_AUTO_CHECK_EVE_FILE="true"
PORTSCAN_SURICATA_SERVICE_NAME="suricata"
PORTSCAN_SURICATA_BINARY="/usr/bin/suricata"
PORTSCAN_EVE_FRESHNESS_THRESHOLD="60"
# Hybrid mode settings
PORTSCAN_HYBRID_CLASSIC_LOGGING="true"
PORTSCAN_HYBRID_SURICATA_DETECT="true"
# nftables settings
PORTSCAN_NFT_TABLE_IPV4="ip nftban"
PORTSCAN_NFT_TABLE_IPV6="ip6 nftban"
PORTSCAN_NFT_CHAIN="portscan_detection"
# Whitelist settings
PORTSCAN_WHITELIST_FILE="/etc/nftban/whitelist.d/portscan-whitelist.conf"
PORTSCAN_WHITELIST_LOCALHOST="true"
PORTSCAN_WHITELIST_PRIVATE="true"
PORTSCAN_WHITELIST_MONITORING="true"
# Safety limits
PORTSCAN_MAX_BLOCKED_IPS="5000"
PORTSCAN_MAX_BAN_DURATION="86400"
PORTSCAN_MIN_REBLOCK_INTERVAL="300"
# Notifications
PORTSCAN_NOTIFY_EMAIL="false"
PORTSCAN_NOTIFY_WEBHOOK="false"
PORTSCAN_NOTIFY_THRESHOLD="10"Classic Mode (classic.conf):
# Log source settings
PORTSCAN_CLASSIC_LOG_PREFIX="NFTBAN_PORTSCAN:"
PORTSCAN_CLASSIC_LOG_FILE="/var/log/kern.log"
PORTSCAN_CLASSIC_LOG_FILE_ALT="/var/log/messages,/var/log/syslog"
PORTSCAN_CLASSIC_USE_JOURNALCTL="auto" # auto, true, false
# Detection thresholds
PORTSCAN_CLASSIC_MIN_PORTS="5"
PORTSCAN_CLASSIC_TIME_WINDOW="60"
PORTSCAN_CLASSIC_MIN_TARGETS="3"
# Scan type thresholds
PORTSCAN_CLASSIC_VERTICAL_PORTS="10" # Many ports on one target
PORTSCAN_CLASSIC_VERTICAL_WINDOW="60"
PORTSCAN_CLASSIC_HORIZONTAL_TARGETS="5" # One port on many targets
PORTSCAN_CLASSIC_HORIZONTAL_WINDOW="30"
PORTSCAN_CLASSIC_BLOCK_RANGE="20" # Port range scanning
PORTSCAN_CLASSIC_BLOCK_WINDOW="120"
PORTSCAN_CLASSIC_STROBE_PORTS="5" # Rapid common ports
PORTSCAN_CLASSIC_STROBE_WINDOW="10"
# Blocking policy
PORTSCAN_CLASSIC_ACTION="block" # block, log, alert, block_and_alert
PORTSCAN_CLASSIC_BAN_VERTICAL="1800" # 30 minutes
PORTSCAN_CLASSIC_BAN_HORIZONTAL="3600" # 1 hour
PORTSCAN_CLASSIC_BAN_BLOCK="7200" # 2 hours
PORTSCAN_CLASSIC_BAN_STROBE="600" # 10 minutes
PORTSCAN_CLASSIC_BAN_DEFAULT="1800"
# Progressive banning (repeat offenders)
PORTSCAN_CLASSIC_PROGRESSIVE_BAN="true"
PORTSCAN_CLASSIC_PROGRESSIVE_MULTIPLIER="2"
PORTSCAN_CLASSIC_PROGRESSIVE_MAX="86400"
# State tracking
PORTSCAN_CLASSIC_STATE_FILE="/var/lib/nftban/portscan-state.db"
PORTSCAN_CLASSIC_MAX_TRACKED_IPS="10000"
PORTSCAN_CLASSIC_STATE_TTL="3600"
# Logging
PORTSCAN_CLASSIC_LOG_FILE="/var/log/nftban/portscan-classic.log"
PORTSCAN_CLASSIC_LOG_LEVEL="INFO"
PORTSCAN_CLASSIC_LOG_RATE="10/second"
PORTSCAN_CLASSIC_LOG_BURST="50"Suricata Mode (suricata.conf):
# EVE JSON path (must match YAML profile)
PORTSCAN_SURICATA_EVE_FILE="/var/log/nftban/suricata/eve-alerts.json"
# Detection toggles
PORTSCAN_SURICATA_DETECT_PORTSCAN="true"
PORTSCAN_SURICATA_DETECT_PORTSWEEP="true"
PORTSCAN_SURICATA_DETECT_DECOY_PORTSCAN="true"
PORTSCAN_SURICATA_DETECT_DISTRIBUTED_PORTSCAN="true"
# Scan sensitivity (1=low, 2=medium, 3=high)
PORTSCAN_SURICATA_SENSITIVITY="2"
# Scoring (0.0 - 1.0 scale)
PORTSCAN_SURICATA_SCORE_SEVERITY_1="0.50"
PORTSCAN_SURICATA_SCORE_SEVERITY_2="0.35"
PORTSCAN_SURICATA_SCORE_SEVERITY_3="0.20"
PORTSCAN_SURICATA_SCORE_SEVERITY_4="0.10"
# Scan type bonus scores
PORTSCAN_SURICATA_SCORE_PORTSCAN="0.15"
PORTSCAN_SURICATA_SCORE_PORTSWEEP="0.20"
PORTSCAN_SURICATA_SCORE_DECOY="0.25"
PORTSCAN_SURICATA_SCORE_DISTRIBUTED="0.30"
PORTSCAN_SURICATA_SCORE_KNOWN_TOOL="0.20" # nmap, masscan
# Repetition scores
PORTSCAN_SURICATA_SCORE_REPEAT_5="0.10"
PORTSCAN_SURICATA_SCORE_REPEAT_10="0.20"
PORTSCAN_SURICATA_SCORE_REPEAT_20="0.30"
PORTSCAN_SURICATA_SCORE_BAD_REPUTATION="0.15"
PORTSCAN_SURICATA_SCORE_HIGH_RISK_GEO="0.10"
# Action thresholds
PORTSCAN_SURICATA_THRESHOLD_OBSERVE="0.25"
PORTSCAN_SURICATA_THRESHOLD_BLOCK_SHORT="0.45"
PORTSCAN_SURICATA_THRESHOLD_BLOCK_LONG="0.65"
PORTSCAN_SURICATA_THRESHOLD_BLOCK_PERMANENT="0.85"
# Ban durations
PORTSCAN_SURICATA_BAN_DURATION_SHORT="900" # 15 minutes
PORTSCAN_SURICATA_BAN_DURATION_LONG="3600" # 1 hour
PORTSCAN_SURICATA_BAN_DURATION_PERMANENT="86400" # 24 hours
PORTSCAN_SURICATA_SCORE_DECAY="1800"
PORTSCAN_SURICATA_ALERT_WINDOW="300"
# Integration
PORTSCAN_SURICATA_USE_FEEDS="true"
PORTSCAN_SURICATA_USE_GEOIP="true"
PORTSCAN_SURICATA_USE_LOGIN_CORRELATION="true"
# Performance
PORTSCAN_SURICATA_BATCH_SIZE="100"
PORTSCAN_SURICATA_MAX_TRACKED_IPS="10000"
PORTSCAN_SURICATA_STATE_FILE="/var/lib/nftban/portscan-suricata-state.db"
# Logging
PORTSCAN_SURICATA_LOG_FILE="/var/log/nftban/portscan-suricata.log"
PORTSCAN_SURICATA_LOG_LEVEL="INFO"
PORTSCAN_SURICATA_LOG_SCORES="true"
PORTSCAN_SURICATA_LOG_TOOLS="true"Scan Types Detected:
| Type | Classic | Suricata | Description |
|---|---|---|---|
| Vertical | Yes | Yes | Many ports on one target |
| Horizontal | Yes | Yes | One port on many targets |
| Block | Yes | - | Port range scanning |
| Strobe | Yes | - | Rapid common ports |
| Portsweep | - | Yes | Single port across network |
| Decoy | - | Yes | Spoofed source addresses |
| Distributed | - | Yes | Coordinated multi-source |
Log Files:
-
/var/log/nftban/portscan.log- Main portscan module log -
/var/log/nftban/portscan-classic.log- Classic mode specific log -
/var/log/nftban/portscan-suricata.log- Suricata mode specific log
User Overrides: Create .local files that survive package upgrades:
/etc/nftban/conf.d/portscan/main.conf.local
/etc/nftban/conf.d/portscan/classic.conf.local
/etc/nftban/conf.d/portscan/suricata.conf.localNFTBan's login monitor uses a point-based scoring system for automated ban decisions. Each failed login adds points; when thresholds are reached, bans are triggered.
Main Config (main.conf):
# Login monitoring master settings
LOGIN_ENABLED="true"
LOGIN_MODE="auto" # auto, classic, suricata, hybridSuricata Mode (suricata.conf):
# EVE JSON path (must match YAML profile)
LOGIN_SURICATA_EVE_FILE="/var/log/nftban/suricata/eve-alerts.json"
# Detection toggles
LOGIN_SURICATA_DETECT_SSH="true"
LOGIN_SURICATA_DETECT_FTP="true"
LOGIN_SURICATA_DETECT_SMTP="true"
LOGIN_SURICATA_DETECT_MAIL="true"
LOGIN_SURICATA_DETECT_HTTP="true"Services Config (services.conf):
# Per-service detection enables/disables
LOGIN_SERVICE_SSH_ENABLED="true"
LOGIN_SERVICE_DOVECOT_ENABLED="true"
LOGIN_SERVICE_POSTFIX_ENABLED="true"
LOGIN_SERVICE_FTP_ENABLED="true"
LOGIN_SERVICE_DIRECTADMIN_ENABLED="true"
LOGIN_SERVICE_CPANEL_ENABLED="false"
LOGIN_SERVICE_PLESK_ENABLED="false"
LOGIN_SERVICE_WORDPRESS_ENABLED="false"Scorer Config (scorer.conf):
The scoring engine controls ban thresholds and per-service point values.
# =============================================================================
# BAN THRESHOLDS (scale: 0-100+)
# =============================================================================
THRESHOLD_TEMP_BAN="45" # Score to trigger temp ban
THRESHOLD_ESCALATE="65" # Score to trigger escalation
THRESHOLD_PERMANENT="100" # Score for permanent ban
# =============================================================================
# BAN DURATIONS
# =============================================================================
TEMP_BAN_DURATION="15m" # Initial temp ban length
# Escalation: 2h -> 4h -> 12h -> 24h (progressive for repeat offenders)
# =============================================================================
# SCORE DECAY
# =============================================================================
SCORE_DECAY_INTERVAL="5m" # How often scores decay
SCORE_DECAY_AMOUNT="5" # Points subtracted per interval
# =============================================================================
# IP RETENTION
# =============================================================================
IP_RETENTION_DURATION="24h" # Cleanup IPs with score=0 after thisPer-Service Score Values:
| Service | Event | Variable | Default |
|---|---|---|---|
| SSH | Failed password | SSH_FAILED_PASSWORD_SCORE |
10 |
| Invalid user | SSH_INVALID_USER_SCORE |
15 | |
| Preauth disconnect | SSH_PREAUTH_SCORE |
20 | |
| Too many failures | SSH_TOO_MANY_SCORE |
30 | |
| Root attempt bonus | SSH_ROOT_ATTEMPT_BONUS |
10 | |
| Dovecot auth fail | DOVECOT_AUTH_FAIL_SCORE |
15 | |
| Postfix SASL fail | POSTFIX_SASL_SCORE |
15 | |
| Exim auth fail | EXIM_AUTH_FAIL_SCORE |
15 | |
| FTP | Auth failure | FTP_AUTH_FAIL_SCORE |
15 |
| Panels | DirectAdmin login | DIRECTADMIN_LOGIN_SCORE |
20 |
| cPanel/WHM login | CPANEL_LOGIN_SCORE |
20 | |
| Plesk login | PLESK_LOGIN_SCORE |
20 | |
| WordPress | XML-RPC attack | WORDPRESS_XMLRPC_SCORE |
25 |
| wp-login brute force | WORDPRESS_WPLOGIN_SCORE |
20 |
Scoring Examples:
Example 1: SSH brute force (5 failed passwords)
5 x 10 pts = 50 pts -> Temp Ban (15 min)
Example 2: SSH scanner (invalid users + root attempts)
2 x SSH_INVALID_USER (15) = 30 pts
1 x SSH_ROOT_BONUS (10) = 10 pts
1 x SSH_PREAUTH (20) = 20 pts
Total: 60 pts -> Temp Ban (close to escalation)
Example 3: Multi-service attack
2 x DOVECOT_AUTH_FAIL (15) = 30 pts
2 x SSH_FAILED_PASSWORD (10) = 20 pts
Total: 50 pts -> Temp Ban
Example 4: Aggressive scanner
3 x SSH_TOO_MANY (30) = 90 pts
1 x SSH_PREAUTH (20) = 20 pts
Total: 110 pts -> PERMANENT BAN
Tuning Guide:
- Lower scores = more attempts before ban (lenient)
- Higher scores = faster bans (aggressive)
- Root/admin attempts should have higher scores
- Scanners (preauth disconnect) deserve high scores
DirectAdmin (directadmin/main.conf):
# DirectAdmin panel configuration
NFTBAN_DIRECTADMIN_PATH="/usr/local/directadmin"
NFTBAN_DIRECTADMIN_PANEL_PORT="2222"
# Firewall ports
NFTBAN_DIRECTADMIN_TCP_IN="20,21,22,25,53,80,110,143,443,465,587,993,995,2222,35000-35999"
NFTBAN_DIRECTADMIN_TCP_OUT="20,21,22,25,53,80,110,113,143,443,465,587,993,995,2222"
# CloudFlare integration (required for licensing)
NFTBAN_DIRECTADMIN_AUTO_CLOUDFLARE="ASK"Future Panels:
panels/cpanel/main.conf # cPanel configuration
panels/plesk/main.conf # Plesk configuration
panels/ispconfig/main.conf # ISPConfig configuration
# Threat feed settings
FEEDS_UPDATE_INTERVAL="3600"
FEEDS_MAX_SIZE="100000"
FEEDS_TIMEOUT="300"
# Enabled feeds (comma-separated)
ENABLED_FEEDS="FIREHOL_LEVEL1"Whitelist IP ranges from trusted CDN and cloud providers.
# Master switch
TRUST_ENABLED="true"
# Auto-update settings
TRUST_AUTO_UPDATE="true"
TRUST_AUTO_UPDATE_INTERVAL="24" # hours
# Provider switches (enable with: nftban trust enable PROVIDER)
TRUST_CLOUDFLARE_ENABLED="false"
TRUST_QUICCLOUD_ENABLED="false"
TRUST_AWS_ENABLED="false"
TRUST_GOOGLE_ENABLED="false"
TRUST_AZURE_ENABLED="false"
TRUST_DIGITALOCEAN_ENABLED="false"
TRUST_FASTLY_ENABLED="false"
# Validation
TRUST_MIN_RANGES="5" # Minimum ranges to accept
TRUST_MAX_RANGES="50000" # Maximum ranges to accept
TRUST_DOWNLOAD_TIMEOUT="60" # secondsSupported Providers:
| Provider | Description | IPv4 | IPv6 |
|---|---|---|---|
CLOUDFLARE |
CDN/Proxy | Yes | Yes |
QUICCLOUD |
QUIC.cloud / LiteSpeed CDN | Yes | - |
AWS |
Amazon Web Services | Yes | Yes |
GOOGLE |
Google Cloud Platform | Yes | Yes |
AZURE |
Microsoft Azure | Yes | - |
DIGITALOCEAN |
DigitalOcean | Yes | - |
FASTLY |
Fastly CDN | Yes | Yes |
Files:
- Cache:
/var/cache/nftban/trust/ - Whitelist:
/etc/nftban/whitelist.d/30-trust-*.conf - Log:
/var/log/nftban/trust.log
The task queue provides reliable async processing with retry and dead-letter queue (DLQ) support.
# =============================================================================
# TASK QUEUE CONFIGURATION
# =============================================================================
NFTBAN_QUEUE_MAX_RETRIES="3"
NFTBAN_QUEUE_BACKOFF_BASE_SECONDS="30"
NFTBAN_QUEUE_BACKOFF_MAX_SECONDS="900"
NFTBAN_QUEUE_PENDING_DIR="${NFTBAN_DATA_DIR}/queue/pending"
NFTBAN_QUEUE_WORK_DIR="${NFTBAN_DATA_DIR}/queue/work"
NFTBAN_QUEUE_DLQ_DIR="${NFTBAN_DATA_DIR}/queue/dlq"
NFTBAN_QUEUE_LOCK_STUCK_THRESHOLD="1200"
NFTBAN_QUEUE_METRICS_FILE="${NFTBAN_DATA_DIR}/metrics/queue.prom"| Variable | Default | Description |
|---|---|---|
NFTBAN_QUEUE_MAX_RETRIES |
3 |
Maximum retry attempts before moving to DLQ |
NFTBAN_QUEUE_BACKOFF_BASE_SECONDS |
30 |
Base delay for exponential backoff (seconds) |
NFTBAN_QUEUE_BACKOFF_MAX_SECONDS |
900 |
Maximum backoff delay (15 minutes) |
Backoff Formula: delay = min(max, base * 2^retries)
| Retry | Calculation | Delay |
|---|---|---|
| 1 | min(900, 30x2^1) | 60s |
| 2 | min(900, 30x2^2) | 120s |
| 3 | min(900, 30x2^3) | 240s |
| 4+ | - | DLQ |
Production Recommendations:
- High-traffic servers: Keep defaults (3 retries, 30s base)
- Low-traffic/batch: Consider
MAX_RETRIES=5,BACKOFF_BASE=60
| Variable | Default | Description |
|---|---|---|
NFTBAN_QUEUE_PENDING_DIR |
${NFTBAN_DATA_DIR}/queue/pending |
Pending tasks |
NFTBAN_QUEUE_WORK_DIR |
${NFTBAN_DATA_DIR}/queue/work |
Task being processed |
NFTBAN_QUEUE_DLQ_DIR |
${NFTBAN_DATA_DIR}/queue/dlq |
Dead-letter queue |
Security:
- Directories created with mode
750 - Owned by
nftban:nftban - Task files contain sourceable shell - keep protected
| Variable | Default | Description |
|---|---|---|
NFTBAN_QUEUE_LOCK_STUCK_THRESHOLD |
1200 |
Seconds before auto-killing stuck processor (20 min) |
Recovery Behavior:
- If lock age > threshold and PID still alive:
- Send SIGTERM, wait 5s
- Send SIGKILL if still alive
- Move orphaned work tasks back to pending
- Delete lock file
- Log alert to syslog and
/var/log/nftban/queue.log
nftban queue status # Quick status overview
nftban queue list # List pending tasks
nftban queue dlq list # Show failed tasks
nftban queue dlq retry <id> # Retry specific task
nftban queue dlq retry-all # Retry all DLQ tasks
nftban queue dlq purge 30 # Delete DLQ tasks older than 30 days
nftban queue metrics # Show Prometheus metricsTwo-tier mail system with retry and queue fallback for reliable delivery.
# =============================================================================
# MAIL DELIVERY CONFIGURATION
# =============================================================================
NFTBAN_MAIL_RETRY_ATTEMPTS="3"
NFTBAN_MAIL_RETRY_BACKOFF="5,15,45"
NFTBAN_MAIL_SPOOL_DIR="${NFTBAN_DATA_DIR}/mailspool"
NFTBAN_MAIL_METRICS_FILE="${NFTBAN_DATA_DIR}/metrics/mail.prom"| Variable | Default | Description |
|---|---|---|
NFTBAN_MAIL_RETRY_ATTEMPTS |
3 |
Inline retry attempts before spooling |
NFTBAN_MAIL_RETRY_BACKOFF |
5,15,45 |
Comma-separated backoff delays (seconds) |
Retry Timeline (default):
Attempt 1 -> fail -> wait 5s
Attempt 2 -> fail -> wait 15s
Attempt 3 -> fail -> wait 45s
Attempt 4 -> fail -> spool to queue
| Variable | Default | Description |
|---|---|---|
NFTBAN_SMTP_HOST |
(none) | SMTP server hostname |
NFTBAN_SMTP_PORT |
587 |
SMTP port (587=STARTTLS, 465=SMTPS) |
NFTBAN_SMTP_USER |
(none) | SMTP authentication username |
NFTBAN_SMTP_PASS |
(none) | SMTP authentication password |
Security Note: Store NFTBAN_SMTP_PASS in a .local file with restricted permissions:
# /etc/nftban/conf.d/mail.conf.local (mode 600)
NFTBAN_SMTP_PASS="your-password-here"# One command to enable all email notifications:
nftban mail setup admin@example.com --all --test
# Minimal setup (recipient only, enable triggers manually):
nftban mail setup admin@example.com
# View current configuration:
nftban mail setup --show| Variable | Default | Description |
|---|---|---|
NFTBAN_MAIL_ENABLED |
NO |
Master switch for email notifications |
NFTBAN_MAIL_RECIPIENT |
(none) | Default recipient for all alerts |
NFTBAN_MAIL_METHOD |
auto-detect | Force specific transport |
NFTBAN_MAIL_USE_HTML |
YES |
Wrap content in HTML template |
NFTBAN_SENDER |
nftban@$(hostname) |
From address |
NFTBAN_FROM_NAME |
NFTBan Security System |
From display name |
| Variable | Default | Description |
|---|---|---|
NFTBAN_MAIL_ON_HEALTH_CRITICAL |
NO |
Email on critical health failures |
NFTBAN_MAIL_DAILY_REPORT |
NO |
Send daily summary report |
NFTBAN_MAIL_ON_BAN |
NO |
Email on new ban (can be noisy) |
NFTBAN_MAIL_ON_LOGIN_ALERT |
NO |
Email on login alerts |
All modules resolve email recipients using this priority:
1. Module-specific override (if set)
2. Global: NFTBAN_MAIL_RECIPIENT (fallback)
Per-Module Overrides (optional):
| Module | Override Variable | Fallback |
|---|---|---|
| Portscan | PORTSCAN_NOTIFY_EMAIL_TO |
NFTBAN_MAIL_RECIPIENT |
| RBL | NFTBAN_RBL_ALERT_EMAIL |
NFTBAN_MAIL_RECIPIENT |
| Updates | NFTBAN_UPDATE_NOTIFY_EMAIL |
NFTBAN_MAIL_RECIPIENT |
| Reports | STATS_EMAIL_RECIPIENTS |
NFTBAN_MAIL_RECIPIENT |
| CLI Reports | NFTBAN_MAIL_REPORT_RECIPIENT |
NFTBAN_MAIL_RECIPIENT |
Note: Setting
NFTBAN_MAIL_RECIPIENTis sufficient for all modules. Per-module overrides are only needed when different recipients are required.
1. postfix (local MTA, fastest)
2. sendmail (local MTA)
3. exim (local MTA)
4. msmtp (lightweight relay)
5. curl (direct SMTP - requires NFTBAN_SMTP_HOST)
6. mailx (basic fallback)
nftban mail setup <email> [opts] # Quick email configuration
nftban mail setup --show # View current configuration
nftban mail test [email] # Send test email
nftban mail status # Show mail system status
nftban mail port-status # Check firewall ports
nftban mail spool status # Show spooled mail count| Variable | Default | Description |
|---|---|---|
NFTBAN_ALERT_THROTTLE_SECONDS |
3600 |
Minimum seconds between alerts for same service |
Behavior:
- First failure: Alert sent immediately
- Subsequent failures within window: Throttled (logged but not emailed)
- After window expires: Next failure triggers alert
# /etc/nftban/conf.d/queue.conf.local
# More aggressive retry for critical environments
NFTBAN_QUEUE_MAX_RETRIES="5"
NFTBAN_QUEUE_BACKOFF_BASE_SECONDS="60"
NFTBAN_QUEUE_BACKOFF_MAX_SECONDS="1800"
# Faster stuck detection (10 minutes)
NFTBAN_QUEUE_LOCK_STUCK_THRESHOLD="600"# /etc/nftban/conf.d/mail.conf.local
# Direct SMTP (no local MTA)
NFTBAN_MAIL_METHOD="curl"
NFTBAN_SMTP_HOST="smtp.sendgrid.net"
NFTBAN_SMTP_PORT="587"
NFTBAN_SMTP_USER="apikey"
NFTBAN_SMTP_PASS="SG.xxxxx"
# Recipients
NFTBAN_MAIL_RECIPIENT="security@example.com"
# More retries for unreliable network
NFTBAN_MAIL_RETRY_ATTEMPTS="5"
NFTBAN_MAIL_RETRY_BACKOFF="10,30,60,120,300"
# Less frequent duplicate alerts
NFTBAN_ALERT_THROTTLE_SECONDS="7200"| Path | Mode | Owner | Notes |
|---|---|---|---|
/etc/nftban/conf.d/*.conf |
644 | root:nftban | Readable config |
/etc/nftban/conf.d/*.conf.local |
600 | root:nftban | Secrets only |
/var/lib/nftban/queue/ |
750 | nftban:nftban | Task storage |
/var/lib/nftban/mailspool/ |
750 | nftban:nftban | Mail spool |
/var/lib/nftban/metrics/ |
755 | nftban:nftban | Prometheus scrape |
/var/log/nftban/queue.log |
640 | nftban:nftban | Queue logs |
/var/log/nftban/mail.log |
640 | nftban:nftban | Mail logs |
/run/nftban/queue.lock |
644 | nftban:nftban | Runtime lock |
Scripts should source the central config and use variables:
#!/usr/bin/env bash
# Source central configuration
if [[ -f "/etc/nftban/nftban.conf" ]]; then
source "/etc/nftban/nftban.conf"
fi
# Use variables instead of hardcoded paths
log_file="${NFTBAN_LOG_DIR}/mymodule.log"
data_dir="${NFTBAN_DATA_DIR}/mydata"
# Check if feature is enabled
if [[ "${NFTBAN_LOGIN_MONITOR_ENABLED}" == "true" ]]; then
# Do something
fiThe config file includes a guard to prevent issues when sourced multiple times:
# Prevent double-sourcing (for bash scripts)
[[ -n "${_NFTBAN_CONF_LOADED:-}" ]] && return 0 2>/dev/null || true
_NFTBAN_CONF_LOADED=1This prevents "readonly variable" errors when multiple scripts source the config.
Distro-specific settings are loaded from /etc/nftban/distros/:
# Example: /etc/nftban/distros/fedora.conf
PKG_NFTABLES="nftables"
PKG_SURICATA="suricata"
SVC_NFTABLES="nftables"
SVC_SURICATA="suricata"The installer auto-detects the distribution and loads appropriate settings.
Validate configuration:
# Validate config syntax
nftban validate
# Check configuration values
nftban check
# Show current config
nftban config show
# Debug dump of config
nftban debug dump configNFTBan provides a central mechanism to apply configuration changes to running services.
┌─────────────────────────────────────────────────────────────────┐
│ CONFIG CHANGE FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. EDIT: vi /etc/nftban/conf.d/portscan/main.conf.local │
│ │
│ 2. CHECK: nftban health config │
│ Shows: portscan - ON running CHANGED <- │
│ │
│ 3. APPLY: nftban config reload portscan │
│ -> Validates config syntax │
│ -> Sends SIGHUP to nftband │
│ -> Saves checksums for tracking │
│ │
└─────────────────────────────────────────────────────────────────┘
| Type | Example Services | Reload Method |
|---|---|---|
| Persistent Daemons | nftband, nftban-login-monitor, nftban-api | SIGHUP signal |
| Timer Services | feeds, metrics, zabbix exporters | Auto-reload on next run |
# Check module and config status
nftban health config
nftban health config --verbose # Include file paths
# Apply config changes
nftban config reload # Reload all services
nftban config reload portscan # Reload specific module
nftban config reload ddos # Reload DDoS module
# Detailed config status
nftban config status| Module | Service | Reload Method |
|---|---|---|
portscan |
nftband.service | SIGHUP |
ddos |
nftband.service | SIGHUP |
login |
nftban-login-monitor.service | SIGHUP |
geoban |
nftband.service | SIGHUP |
feeds |
Timer-based | Auto (next run) |
suricata |
nftban-suricata.service | SIGHUP |
NFTBan tracks loaded config via SHA256 checksums stored in /run/nftban/config-loaded/:
# View loaded config checksums
ls -la /run/nftban/config-loaded/
# Check if reload needed
nftban health config
# Output shows CHANGED if config modified since loadServices support systemctl reload:
# Reload via systemctl (alternative to CLI)
systemctl reload nftband.service
systemctl reload nftban-login-monitor.service- FHS Compliance - Directory structure
- Security Architecture - Access control and groups
- CLI Commands Reference - All commands
- Metrics Architecture - Metrics design
- Debug & Troubleshooting - Debug tools
| Setting | Enable Command | Config Variable |
|---|---|---|
| Debug Trace | nftban debug enable |
NFTBAN_DEBUG_TRACE |
| Login Monitor | nftban login enable |
NFTBAN_LOGIN_MONITOR_ENABLED |
| Port Scan | nftban portscan enable |
NFTBAN_PORTSCAN_ENABLED |
| DDoS | nftban ddos enable |
NFTBAN_DDOS_ENABLED |
| Feeds | nftban feeds enable |
NFTBAN_FEEDS_ENABLED |
| GeoIP | nftban geoip enable |
NFTBAN_GEOIP_ENABLED |
| GUI | nftban gui enable |
NFTBAN_GUI_ENABLED |
| Prometheus Export | nftban config set NFTBAN_EXPORT_PROMETHEUS=true |
NFTBAN_EXPORT_PROMETHEUS |
Summary:
- Central config:
/etc/nftban/nftban.conf - Module configs:
/etc/nftban/conf.d/*.conf - Distro configs:
/etc/nftban/distros/*.conf - All paths centrally defined - no hardcoding in scripts
- Double-source guard prevents errors
- Use CLI commands to enable/disable features
- Architecture Overview
- NFT Schema Validation
- Firewall Anchor Architecture
- Health Check Architecture
- Metrics Architecture
- Registry Architecture
- Queue and Mail Contract
- API Handlers Map
- Systemd Units Overview
- Timer Schedule
- Performance Benchmarks
- Optimization Tools and Tweaks
- Large Set Management