CSF - cPanel Shield Firewall

CSF is a modern, free, open-source firewall and intrusion-prevention system for cPanel & WHM servers - a next-generation fork of ConfigServer Security & Firewall, rebuilt on native nftables with first-class IPv4 + IPv6, an event-driven LFD 2.0, and live Threat Intelligence. This documentation covers the 2.1.5 stable release.

Overview

CSF keeps the operational model administrators already know - the same csf commands, the same csf.conf/csf.allow/csf.deny/csf.ignore files - while replacing the underlying engine with a single atomic nftables table (table inet csf). Blocking or unblocking an IP updates one set element in-kernel; it never rebuilds the whole ruleset.

• Native nftables - one inet table for IPv4 and IPv6, dynamic sets with interval (CIDR) and timeout (temporary ban) support.
• LFD 2.0 - modular log collectors feed a single decaying risk score per source, with progressive enforcement from temporary to permanent bans.
• Threat Intelligence - reputable IP/CIDR feeds load into dedicated sets with per-feed toggles and category policies.
• cPanel-native - embedded WHM interface, service/version detection, cPHulk and ModSecurity awareness, automatic port presets on install.
• Safe by design - atomic reloads, an SSH lockout guard, and a self-reverting --safe-reload watchdog.

Requirements

Installation

Download the release, verify its SHA-256 checksum, then run the installer as root. The installer detects and cleanly removes legacy CSF v15 (backing up its configuration first), migrates your settings, and auto-detects the active SSH and cPanel ports.

# 1. download + verify
curl -fSLO https://shield.underhost.com/firewall/download/csf-2.1.5.tar.gz
curl -fSLO https://shield.underhost.com/firewall/download/csf-2.1.5.tar.gz.sha256
sha256sum -c csf-2.1.5.tar.gz.sha256

# 2. extract + install
tar xzf csf-2.1.5.tar.gz
cd csf2 && ./install.sh

# 3. verify, then enable enforcement
csf --cpanel-check
csf -l
# edit /etc/csf/csf.conf, set TESTING="0", then:
systemctl enable --now csf.service lfd.service
csf --safe-reload

After install, open WHM → Plugins → cPanel Shield Firewall. The plugin is registered through AppConfig and renders inside the WHM chrome.

Migrating from CSF v15 or cPanel CSF

The installer handles migration automatically when it detects an existing ConfigServer Security & Firewall v15 install or the cPanel-maintained CSF fork (github.com/cpanel/cpanel-csf):

• Backs up the existing /etc/csf before making changes.
• Reads and carries over csf.conf, csf.allow, csf.deny and csf.ignore.
• Removes the legacy iptables-based CSF and its lfd daemon so no stale rules remain.
• Installs the nftables engine and re-applies your allow/deny lists as set elements.

WHM interface

The embedded WHM interface presents everything through a light, tabbed UI designed to stay usable with thousands of blocked IPs (every list is searchable and paginated).

Updating

CSF checks the release channel and shows an update-available indicator in the interface. There are two ways to update in place - both preserve your configuration, deny/allow lists and Threat Intel sets, and reload the firewall automatically when finished.

From WHM (recommended)

Open the Update tab (or click the "Update now" indicator), then press Update. CSF downloads the new release, verifies its SHA-256, installs it, and shows progress live. When it reaches 100% the interface reloads on the new version.

From the command line

csf --self-update           # update to the latest stable release
csf --self-update --force   # reinstall the current version

The updater downloads from releases/latest.json, aborts on any checksum mismatch, and writes progress to /var/lib/csf/update.progress for the WHM progress bar.

CLI reference

The csf command preserves the familiar CSF flags and adds modern long forms. Every mutating command goes through the engine, so single-IP operations touch one set element and never rebuild the ruleset.

Configuration

Configuration lives in /etc/csf/csf.conf, a familiar KEY="value" file. Every setting is also editable in the WHM Configuration tab, which shows help text for each key. Common keys:

After editing ports or policy, apply with a reload (WHM Firewall → Reload, or csf --safe-reload).

Security levels

Security Level presets set the risk-scoring and enforcement posture in one click:

• Low - lenient thresholds, slower escalation. Fewest false positives.
• Medium - balanced defaults for a typical shared/hosting server.
• High - aggressive scoring and faster permanent bans.
• Attack - hardened posture for an active incident; quickest escalation and strictest drop logging.

LFD 2.0 & risk scoring

The Login Failure Daemon (lfd) tails service logs through independent collectors (SSH, Exim, Dovecot, FTP, web server, ModSecurity/WAF), normalises each hit into a structured event, and rolls all signals for one source into a single decaying risk score. As the score crosses thresholds, enforcement escalates from a short temporary block to a longer one and finally to a permanent deny. Every action carries a human-readable reason. High-confidence, repeated WAF attacks are escalated from the application layer to a network-layer drop.

Threat Intelligence

The Threat Intelligence module downloads reputable IP/CIDR reputation feeds and loads them into dedicated nftables sets - never into csf.deny - so your manual lists stay clean and the feeds can be toggled independently. Feeds refresh hourly via cron and on demand with csf --ti-update.

Outbound Threat Intel drops are placed before the outbound established-accept rule, so an already-open connection to a known-malicious host is severed rather than grandfathered.

Cloudflare

When sites sit behind Cloudflare, all visitor traffic arrives from Cloudflare's edge network. If LFD ever blocked one of those shared edge addresses, it would break every proxied site at once. The Cloudflare edge allowlist prevents that: enable it from the WHM Firewall tab (or run csf --cf-enable) and CSF fetches Cloudflare's published IPv4 and IPv6 ranges and adds them to your allow list, tagged Cloudflare so they're easy to see and remove.

• Ranges are fetched live from cloudflare.com/ips-v4 and ips-v6, with a pinned fallback if the server can't reach them.
• Entries appear in the Allow List tab tagged Cloudflare; direct-to-origin abuse is still blocked normally.
• Use Refresh ranges (or csf --cf-update) after Cloudflare changes its network; Disable (or csf --cf-disable) removes them cleanly.

Architecture

CSF maintains a single atomic table, table inet csf, applied via nft -f. Traffic is filtered against named sets:

• csf_allow4 / csf_allow6 - allowlisted sources.
• csf_deny4 / csf_deny6 - permanent denies (interval/CIDR).
• csf_temp4 / csf_temp6 - temporary blocks with native timeouts.
• csf_ti_high4/6, csf_ti_botnet4/6, csf_ti_attackers4/6 - Threat Intelligence sets by category.

Because state lives in sets, adding or removing a single IP is an incremental set operation - fast, atomic, and safe under load - while a full reload regenerates and validates the entire ruleset before swapping it in.

Uninstalling

cd csf2 && ./uninstall.sh          # removes CSF, keeps /etc/csf config + backups
cd csf2 && ./uninstall.sh --purge  # also removes config and state

The uninstaller removes the nftables table so no stale rules remain, detaches services, and unregisters the WHM plugin. Verify nothing remains with nft list ruleset | grep -i csf.

Troubleshooting

The firewall isn't enforcing

Check TESTING in csf.conf. When TESTING="1" the ruleset is validated but not applied. Set it to 0, enable the services, and run csf --safe-reload.

The WHM plugin opens as a blank/standalone page

The plugin must run under cPanel's Perl. Re-running ./install.sh rewrites the shebang and re-registers AppConfig. Confirm the menu entry is cPanel Shield Firewall at /cgi/cpanelshield/firewall.cgi.

Am I actually protected?

Run csf --selftest: it confirms the kernel table is loaded, runs a block test, and checks that services are active and enabled.

An update failed

The updater aborts safely on any checksum mismatch and leaves the running version intact. See /var/lib/csf/update.log for the installer output.

Changelog

License

CSF - cPanel Shield Firewall is free software distributed under the GNU General Public License v3. It is a next-generation fork of ConfigServer Security & Firewall (© 2006-2025 Jonathan Michaelson) and is part of the UnderShield security suite by UnderHost.

Download 2.1.5   Release metadata