RBL Monitoring

Version: 1.0.0

Overview

RBL (Real-time Blackhole List) monitoring allows NFTBan to check if your server's IP addresses are listed on spam/abuse blacklists. This is a monitoring-only feature - it does not make any firewall changes.

Key Points:

Checks server IPs against 20+ DNS blackhole lists
Uses parallel DNS queries for fast results (~10-15 seconds)
Sends email alerts when IPs get blacklisted
Supports critical IPs (mail servers) and watchlists (external IPs)
Integrates with NFTBan health checks

Quick Start

# Enable RBL monitoring
sudo nftban rbl enable

# Check server immediately
nftban rbl server check

# View status
nftban rbl status

Commands Reference

Primary Commands

Command	Description
`nftban rbl check`	Check discovered IPs against RBLs
`nftban rbl server check`	Full server check (all IPs + hostname)
`nftban rbl status`	Show monitoring status
`nftban rbl list`	List configured RBL providers
`nftban rbl enable`	Enable scheduled checks (systemd timer)
`nftban rbl disable`	Disable scheduled checks

Cache Management

Command	Description
`nftban rbl cache show`	Show cache statistics
`nftban rbl cache purge`	Purge all cached results
`nftban rbl cache purge --ip 1.2.3.4`	Purge cache for specific IP

Critical IPs

Command	Description
`nftban rbl critical list`	Show configured critical IPs
`nftban rbl critical add IP TAG`	Add critical IP (tags: mail, web, panel)
`nftban rbl critical remove IP`	Remove critical IP

Watchlist (External IPs)

Command	Description
`nftban rbl watchlist list`	Show watched IPs
`nftban rbl watchlist add IP [DESC]`	Add IP with optional description
`nftban rbl watchlist remove IP`	Remove IP from watchlist
`nftban rbl watchlist check`	Check all watched IPs
`nftban rbl watchlist check --alert`	Check and send alerts

Alert Testing

Command	Description
`nftban rbl alert test --ip 1.2.3.4`	Send test alert email

Command Options

Check Options

nftban rbl check [OPTIONS]
nftban rbl server check [OPTIONS]

Option	Description
`--ip IP`	Check specific IP address
`--fresh`	Ignore cache, force fresh check
`--json`	Output in JSON format
`--verbose`	Show all results (including clean)
`--quiet`	Minimal output (for cron/timer)
`--alert`	Send email alert if listings found
`--sequential`	Use sequential DNS (slower, default: parallel)

Configuration

Main Configuration File

Location: /etc/nftban/conf.d/rbl/main.conf

# Enable/disable RBL monitoring
NFTBAN_RBL_ENABLED="YES"

# Alert email address (required for alerts)
NFTBAN_RBL_ALERT_EMAIL="admin@example.com"

# Alert triggers
NFTBAN_RBL_ALERT_ON_NEW_LISTING="YES"  # Alert on new listings
NFTBAN_RBL_ALERT_ON_DEGRADED="NO"      # Alert on many timeouts

# DNS timeout per RBL query (seconds)
NFTBAN_RBL_TIMEOUT="4"

# Cache TTL (hours)
NFTBAN_RBL_CACHE_TTL="24"

# Auto-discover public IPs from interfaces
NFTBAN_RBL_AUTO_DISCOVER_IPS="YES"

# Check IPv6 addresses
NFTBAN_RBL_CHECK_IPV6="YES"

# Parallel DNS jobs (default: 10)
NFTBAN_RBL_PARALLEL_JOBS="10"

# Critical IPs (comma-separated, IP:tag format)
NFTBAN_RBL_CRITICAL_IPS="203.0.113.10:mail,203.0.113.20:web"

# Severity levels by tag
NFTBAN_RBL_SEVERITY_MAIL="critical"
NFTBAN_RBL_SEVERITY_WEB="high"
NFTBAN_RBL_SEVERITY_PANEL="high"
NFTBAN_RBL_SEVERITY_DEFAULT="medium"

User Overrides

Location: /etc/nftban/conf.d/rbl/main.conf.local

Put custom settings in main.conf.local - this file survives package upgrades.

# Example: Override alert email
NFTBAN_RBL_ALERT_EMAIL="security@mycompany.com"

# Example: Add critical IPs
NFTBAN_RBL_CRITICAL_IPS="198.51.100.5:mail,198.51.100.10:web"

Configuration Files Overview

File	Purpose
`main.conf`	Main RBL configuration (package defaults)
`main.conf.local`	User overrides (survives upgrades)
`rbls.conf`	List of RBL providers to check
`custom.conf`	Enable/disable specific RBLs
`watchlist.conf`	External IPs to monitor

RBL Providers

NFTBan checks against 20+ RBL providers including:

Major Providers:

Spamhaus (zen, sbl, xbl, pbl)
Barracuda
SpamCop
SORBS
URIBL

Additional Lists:

DroneRL
UCEProtect
PSBL
SpamRats

Custom RBL Configuration

File: /etc/nftban/conf.d/rbl/custom.conf

# Disable unreliable RBL
disablerbl:slow.rbl.example.com

# Add custom RBL
enablerbl:my.custom.rbl.net:https://example.com/info

# Force check specific IP
enableip:203.0.113.50

# Exclude IP from checks
disableip:10.0.0.1

Timer Schedule

RBL checks run automatically via systemd timer.

Schedule Details

Property	Value
Timer	`nftban-rbl-check.timer`
Schedule	Every 12 hours (02:00 and 14:00)
Jitter	15 minutes
Deterministic	Yes (FixedRandomDelay=true)
Persistent	Yes (catches up after reboot)

Timer Management

# Check timer status
systemctl status nftban-rbl-check.timer

# List next scheduled run
systemctl list-timers nftban-rbl-check.timer

# Enable timer
sudo nftban rbl enable

# Disable timer
sudo nftban rbl disable

# Force immediate check
sudo systemctl start nftban-rbl-check.service

Timer Configuration

File: /etc/systemd/system/nftban-rbl-check.timer

[Timer]
# Run at 02:00 and 14:00 daily
OnCalendar=*-*-* 02:00:00
OnCalendar=*-*-* 14:00:00

# 15-minute jitter window
RandomizedDelaySec=15m

# Same offset per host (deterministic)
FixedRandomDelay=true

# Run on boot if missed
Persistent=true
OnBootSec=10min

Alert System

Alert Triggers

Alerts are sent when:

New Listing: IP was clean, now listed (state transition)
Degraded Monitoring (optional): >30% of RBLs timeout

Alert Email Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NFTBan RBL Alert - IP Blacklisted
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Severity:     CRITICAL
IP Address:   203.0.113.10
Tag:          mail
Blacklist:    zen.spamhaus.org
Reason:       Listed for spam activity
Detected:     2026-02-04 14:30:00

Impact:
  - Email delivery WILL FAIL to many recipients
  - Server reputation severely damaged
  ...

Recommended Actions:
  1. Check outbound mail logs for spam
  2. Verify no open relay: telnet localhost 25
  ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Severity Levels

Tag	Severity	Impact
mail, smtp, mta	CRITICAL	Email delivery fails
web, http	HIGH	Security filters may block
panel, cpanel	HIGH	Management access affected
default	MEDIUM	General reputation damage

Test Alert System

# Send test alert
nftban rbl alert test --ip 203.0.113.10 --rbl test.rbl.example.com --reason "Test alert"

Critical IPs Feature

Critical IPs are server IPs that require special monitoring (mail servers, web servers, control panels).

Adding Critical IPs

# Add mail server IP (critical severity)
sudo nftban rbl critical add 203.0.113.10 mail

# Add web server IP (high severity)
sudo nftban rbl critical add 203.0.113.20 web

# Add control panel IP
sudo nftban rbl critical add 203.0.113.30 panel

Available Tags

Tag	Severity	Use Case
`mail`	critical	Mail/SMTP servers
`smtp`	critical	SMTP relays
`web`	high	Web servers
`panel`	high	Control panels (cPanel, Plesk)
`dns`	medium	DNS servers
`default`	medium	Other IPs

Listing Critical IPs

nftban rbl critical list

Output:

Critical IPs for RBL Monitoring
─────────────────────────────────────────────────────────────

  1. 203.0.113.10          tag: mail        severity: critical
  2. 203.0.113.20          tag: web         severity: high
  3. 203.0.113.30          tag: panel       severity: high

─────────────────────────────────────────────────────────────
Total: 3 critical IP(s)

Watchlist Feature

Monitor external IPs (customers, partners, suppliers) for RBL listings.

Adding Watched IPs

# Add customer mail server
sudo nftban rbl watchlist add 198.51.100.5 "Customer ABC mail server"

# Add with tags
sudo nftban rbl watchlist add 198.51.100.10 "Partner XYZ" "partner,mail,critical"

# Add with custom notification email
sudo nftban rbl watchlist add 192.0.2.100 "Supplier DNS" "" "alerts@supplier.com"

Watchlist File Format

File: /etc/nftban/conf.d/rbl/watchlist.conf

# Format: IP|description|tags|notify_email
203.0.113.10|Customer ABC mail server|customer,mail,critical|
198.51.100.5|Partner XYZ web server|partner,web|alerts@partner.com
192.0.2.100|Backup DNS server|infrastructure,dns|

Checking Watchlist

# Check all watched IPs
nftban rbl watchlist check

# Check with alerts
nftban rbl watchlist check --alert

# JSON output
nftban rbl watchlist check --json

Health Check Integration

RBL monitoring integrates with NFTBan's health check system.

Health Check Output

nftban health

RBL section shows:

Monitoring status (enabled/disabled)
Timer status (active/inactive)
Last check time
Blacklist status (any IPs listed?)

Health Check Warnings

Condition	Warning
RBL enabled but timer not active	"RBL timer enabled but not running"
Last check > 48 hours ago	"Last RBL check was Xh ago (stale)"
IP currently blacklisted	"Server IP(s) currently BLACKLISTED on RBLs!"
Timer not enabled	"RBL timer not enabled"

Health Check Exit Codes

Code	Status	Meaning
0	OK	RBL monitoring active, no blacklistings
1	WARNING	Timer issues or stale checks
2	ERROR	IP currently blacklisted

Cache System

Cache Location

/var/log/nftban/rbl/
├── {IP}.cache          # Cached results per IP
├── last_check          # Timestamp of last check
├── state.dat           # IP state tracking (listed/clean)
└── state.json          # JSON view for API compatibility

Cache TTL

Default: 24 hours

Results are cached to avoid excessive DNS queries. Use --fresh to bypass cache.

Cache Management

# Show cache stats
nftban rbl cache show

# Purge all cache
nftban rbl cache purge

# Purge specific IP
nftban rbl cache purge --ip 203.0.113.10

State Tracking

RBL monitoring tracks state transitions to avoid duplicate alerts.

State File Format

File: /var/log/nftban/rbl/state.dat

# Format: IP=status|timestamp|prev_status|prev_timestamp
203.0.113.10=clean|2026-02-04T14:30:00+00:00|listed|2026-02-03T02:00:00+00:00
198.51.100.5=listed|2026-02-04T14:30:00+00:00|clean|2026-02-03T02:00:00+00:00

State Transitions

Previous	Current	Action
clean	listed	Send alert (new listing)
listed	listed	No alert (already known)
listed	clean	Log delisting
clean	clean	No action

Performance

Parallel DNS Queries

Default: 10 concurrent jobs

# Performance comparison
# Sequential: ~2-3 minutes for 20+ RBLs
# Parallel:   ~10-15 seconds for 20+ RBLs

Resource Limits (Systemd)

The service runs with resource limits:

CPU: 50% quota
Memory: 256MB max
Tasks: 50 max
Timeout: 10 minutes

Tuning Parallel Jobs

# In main.conf.local
NFTBAN_RBL_PARALLEL_JOBS="20"  # Increase for faster checks
NFTBAN_RBL_TIMEOUT="6"          # Increase timeout for slow DNS

Troubleshooting

Timer Not Running

# Check timer status
systemctl status nftban-rbl-check.timer

# Enable if needed
sudo nftban rbl enable

# Check for errors
journalctl -u nftban-rbl-check.timer --since '1 hour ago'

No Alerts Being Sent

Check email configuration:

grep NFTBAN_RBL_ALERT_EMAIL /etc/nftban/conf.d/rbl/main.conf

Test alert system:
```
nftban rbl alert test --ip 1.2.3.4
```

Verify mail command works:

echo "test" | mail -s "test" your@email.com

Cache Issues

# Purge stale cache
nftban rbl cache purge

# Check cache directory permissions
ls -la /var/log/nftban/rbl/

Many Timeouts

# Increase timeout
# In /etc/nftban/conf.d/rbl/main.conf.local
NFTBAN_RBL_TIMEOUT="8"

# Check DNS resolution
dig +short zen.spamhaus.org

# Check network
ping -c 3 8.8.8.8

IP Not Being Checked

# Verify IP is public (not private)
nftban rbl check --ip 1.2.3.4 --verbose

# Check if IP is in disable list
grep "disableip:1.2.3.4" /etc/nftban/conf.d/rbl/custom.conf

Examples

Full Server Check with Fresh Results

nftban rbl server check --fresh --verbose

Daily Monitoring with Alerts

# Enable timer for automated checks
sudo nftban rbl enable

# Configure alerts
echo 'NFTBAN_RBL_ALERT_EMAIL="admin@example.com"' | \
  sudo tee -a /etc/nftban/conf.d/rbl/main.conf.local

Monitor Customer Mail Servers

# Add to watchlist
sudo nftban rbl watchlist add 203.0.113.10 "Customer A mail" "customer,mail"
sudo nftban rbl watchlist add 203.0.113.20 "Customer B mail" "customer,mail"

# Check with alerts
nftban rbl watchlist check --alert

JSON Output for Scripts

# Check and parse with jq
nftban rbl check --ip 1.2.3.4 --json | jq '.summary.listed'

RBL Monitoring

RBL Monitoring

Overview

Quick Start

Commands Reference

Primary Commands

Cache Management

Critical IPs

Watchlist (External IPs)

Alert Testing

Command Options

Check Options

Configuration

Main Configuration File

User Overrides

Configuration Files Overview

RBL Providers

Custom RBL Configuration

Timer Schedule

Schedule Details

Timer Management

Timer Configuration

Alert System

Alert Triggers

Alert Email Format

Severity Levels

Test Alert System

Critical IPs Feature

Adding Critical IPs

Available Tags

Listing Critical IPs

Watchlist Feature

Adding Watched IPs

Watchlist File Format

Checking Watchlist

Health Check Integration

Health Check Output

Health Check Warnings

Health Check Exit Codes

Cache System

Cache Location

Cache TTL

Cache Management

State Tracking

State File Format

State Transitions

Performance

Parallel DNS Queries

Resource Limits (Systemd)

Tuning Parallel Jobs

Troubleshooting

Timer Not Running

No Alerts Being Sent

Cache Issues

Many Timeouts

IP Not Being Checked

Examples

Full Server Check with Fresh Results

Daily Monitoring with Alerts

Monitor Customer Mail Servers

JSON Output for Scripts

See Also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!