Installation Guide

Installation Guide

Type: Troubleshooting / Getting Started Scope: Install, upgrade, repair, uninstall Since: v1.73.0 (Go installer) Terminology: Glossary & Vocabulary

---

Purpose

See also: Architecture | Supported Platforms | Configuration

This page covers installing NFTBan via package (DEB/RPM) or from source. The installer enforces the system contract on the kernel: after install, the kernel must contain the required nftables schema and the validator must report PROTECTED or IDLE.

The Go installer (nftban-installer) manages this lifecycle through a 5-phase state machine with conflict detection and SSH safety.

---

Prerequisites

• Linux: Rocky/Alma/RHEL 9+, Ubuntu 22.04+, Debian 12+
• nftables: 1.0+ (native backend — no iptables translation)
• Bash: 4.4+
• systemd: 252+ (sysusers.d, tmpfiles.d support)
• jq: JSON processor (auto-installed by package)
• Root access: Required for nftables and systemd operations

Verify nftables:

nft --version    # Must be 1.0+
nft list tables  # Must not error

---

Package Install (Recommended)

Ubuntu 24.04 / Debian 12 (Tier 0)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-ubuntu24.04-amd64.deb
sudo apt install -y ./nftban-ubuntu24.04-amd64.deb

Rocky / AlmaLinux / RHEL 9 (Tier 0)

wget https://github.com/itcmsgr/nftban/releases/latest/download/nftban-el9-x86_64.rpm
sudo dnf install -y ./nftban-el9-x86_64.rpm

See Supported Platforms for full tier matrix and additional distributions.

---

Install Pipeline (5-Phase State Machine)

The Go installer (nftban-installer) runs a 5-phase pipeline. Each phase must succeed before the next begins. If any phase fails, the install stops and the existing firewall is preserved.

Phase 1: DETECT
  ├── SSH port detection (4 sources)
  ├── Conflicting firewall detection
  ├── Panel auto-detection
  └── Authority classification

Phase 2: PREPARE
  ├── Create system user/group
  ├── Create FHS directories
  └── Emergency SSH table (safety net)

Phase 3: SWITCH
  ├── Disable conflicting firewalls (if TAKEOVER)
  ├── Load nftables schema
  └── Atomic table replacement

Phase 4: CONFIGURE
  ├── Apply panel-specific config
  ├── Set SSH port in firewall rules
  └── Enable base services

Phase 5: VALIDATE
  ├── Run Go kernel validator
  ├── Verify structural integrity
  └── Write install state file

Install outcomes

State	Exit code	Meaning
COMMITTED	0	Install complete, NFTBan is authority
DEGRADED	1	Partial success — firewall may need manual attention
FAILED	2	Critical phase failed — existing firewall may not be running
ABORTED	3	Conflicts detected, takeover not approved — existing firewall UNCHANGED

---

Authority Model

The installer classifies the host into one of four authority decisions:

Decision	Meaning	When
FRESH	No conflicting firewalls. Clean install.	No CSF/UFW/firewalld/iptables detected
UPDATE	NFTBan already owns the firewall. Upgrade.	Previous NFTBan install detected
TAKEOVER	Conflicts exist, approval granted.	CSF/UFW/firewalld detected + NFTBAN_TAKEOVER=1 or panel auto-approve
ABORT	Conflicts exist, no approval. Existing firewall kept.	Conflicts detected, no takeover flag

Conflict detection

The installer checks for these conflicting firewalls:

Firewall	Detection method
CSF	csf.service + lfd.service
UFW	ufw.service
firewalld	firewalld.service
iptables	iptables.service
Ghost nft tables	Tables containing firewalld or filter/nat/mangle substrings

Panel auto-approval

On hosts with detected panels (cPanel, DirectAdmin, Plesk, CyberPanel, Hestia, VestaCP, CWP, InterWorx), the installer auto-approves takeover — no NFTBAN_TAKEOVER=1 environment variable needed.

Non-panel hosts with conflicts

Package install runs in a scriptlet with no stdin. If conflicts exist and no panel is detected, the install ABORTs (exit 3). The banner tells the operator to re-run with NFTBAN_TAKEOVER=1:

NFTBAN_TAKEOVER=1 dpkg --configure nftban-core   # DEB
NFTBAN_TAKEOVER=1 rpm -ivh nftban-*.rpm           # RPM

---

SSH Port Safety

The installer detects the SSH port from 4 sources (in priority order):

1. ss -tlnp (live listener)
2. /etc/ssh/sshd_config + sshd_config.d/*.conf
3. /var/lib/nftban/state/ssh_port_active.state (state file)
4. /etc/nftban/nftban.conf.local (explicit config)

During Phase 2 (PREPARE), the installer creates an emergency SSH table that ensures SSH access is preserved even if the main schema fails to load. This is a separate safety mechanism from the main nftban table.

---

Repair

If a previous install failed or left the system in DEGRADED state:

sudo nftban-installer --repair

Repair resumes from the last failed phase using the install state file (/var/lib/nftban/state/install_state).

---

What the Installer Creates

The installer enforces the nftables schema into the kernel. After a successful install, the kernel contains:

• 2 tables (ip nftban, ip6 nftban)
• 3 base chains per family (input with drop policy, forward, output)
• 7 pipeline anchors in strict order
• Required sets (whitelist, blacklist, port sets)
• Module helper chains (if modules enabled)

See NFT Schema & Validator Model for the full structural contract and required objects.

The validator runs as Phase 5 (VALIDATE) and confirms the kernel matches expectations. If validation fails, the install reports DEGRADED or FAILED.

---

Post-Install

After install, verify the system:

# Check health (kernel-derived truth)
nftban health

# Check validator directly
nftban-validate --json | jq '.status'

# Enable modules as needed
nftban ddos enable
nftban portscan enable
nftban login enable

Configuration goes in .local files (survives upgrades):

# Example: enable DDoS
echo 'DDOS_ENABLED="true"' > /etc/nftban/conf.d/ddos/main.conf.local
nftban ddos enable

See Configuration Reference for all config keys.

---

Upgrade

Package upgrades preserve:

• All .conf.local override files
• Whitelist and blacklist data
• State files and ban history
• Kernel rules (atomic rebuild on upgrade)

# DEB upgrade
sudo apt install -y ./nftban-ubuntu24.04-amd64.deb

# RPM upgrade
sudo dnf install -y ./nftban-el9-x86_64.rpm

---

Uninstall

# DEB
sudo apt remove nftban-core
sudo apt purge nftban-core    # also removes config

# RPM
sudo dnf remove nftban-core

DEB purge creates a config backup at /var/tmp/nftban-config-backup-<timestamp>.

CSF restoration warning: If NFTBan took over from CSF, uninstalling NFTBan does NOT automatically restore CSF. The operator must manually re-enable CSF services and restore configuration. See the CSF documentation for restoration.

---

Verification (MANDATORY)

# Verify install state
cat /var/lib/nftban/state/install_state

# Verify kernel structure
nft list tables
# Expected: "table ip nftban" and "table ip6 nftban"

# Verify health
nftban-validate --json | jq '.status'
# Expected: "protected" or "idle"

# Verify SSH port is in firewall
nft list set ip nftban tcp_ports_in
# Must include your SSH port

---

Design Principle

The installer enforces the kernel truth model:

1. Configuration is intent — the operator declares what should be enabled
2. Installer enforces intent — transforms config into kernel state
3. Validator verifies reality — confirms kernel matches expectations
4. CLI reports derived state — presents validator output to operator

This model is invariant across install methods and implementation changes. The installer's role is to bring the kernel from "no NFTBan" to "schema loaded + validator reports PROTECTED." Everything after that is runtime.

---

Limitations

• Source install does not use the Go installer. install.sh is a v1.56-era path without the 5-phase pipeline, authority model, emergency SSH table, or install state tracking. Package install is recommended.
• CSF takeover is not reversible automatically. Uninstall does not restore CSF services, cron jobs, or renamed binaries.
• Install state file is not documented for operators. The 16-field state file at /var/lib/nftban/state/install_state requires reading Go source to interpret.
• DEB purge creates backup; source uninstall does not.