The Firewall That Broke WHM: A cPanel Post-Mortem

How uninstalling a "drop-in replacement" firewall took down the control panel — and the two-file fix that brought it back.

We installed Sentinel Firewall (a community fork of ConfigServer Firewall / CSF) on a production cPanel/CloudLinux server. It worked — until we uninstalled it. The uninstaller removed Sentinel cleanly but left behind a patched cPanel driver with mismatched package names, which crashed WHM with:

[A fatal error or timeout occurred while processing this directive.]

The fix took two Perl files and one service restart. No cPanel update. No reinstall. Here's the whole story.

Background: why we were installing a firewall at all

Our shared hosting server (beta.xisto.com, AlmaLinux 10 + cPanel + CloudLinux) had no host firewall — just nftables rules and an iptables INPUT policy of ACCEPT. For a box serving ~70 client accounts, that was an unacceptable exposure, so we decided to put a proper firewall on it.

Our go-to has always been CSF (ConfigServer Security & Firewall) — it's the de-facto standard on cPanel servers, and every other machine in the fleet already runs it.

Then we hit a wall: download.configserver.com no longer exists. ConfigServer's download infrastructure was shut down, and dnf had no csf package in any enabled repo (CloudLinux, EPEL, CRB — nothing).

Enter Sentinel — a community fork of CSF born from the same GPL codebase, positioned as a drop-in replacement. The pitch was good: same config format, same commands, actively maintained.

We installed it. It worked. Ports configured, TESTING=0, csf + lfd services active, INPUT policy DROP, web/DNS/mail verified. All good.

Then the client asked us to remove it.

The uninstall was clean. The panel wasn't.

csf -x flushed the rules. /etc/csf/uninstall.sh removed /etc/csf, /usr/local/csf, /var/lib/csf, the binaries, the systemd units, the cron jobs. Verified clean — iptables back to ACCEPT, no csf/lfd commands left on the system.

Then someone logged into WHM.

Can't locate object method "get_driver_name" via package
"Cpanel::Config::ConfigObj::Driver::ConfigServercsf::META"

The firewall was gone but cPanel still thought CSF existed — and crashed trying to manage it.

Root cause: Sentinel rewrote cPanel's driver and renamed the package

Here's the part that made this sneaky. cPanel doesn't just detect firewalls — it ships a driver framework (Cpanel::Config::ConfigObj) that lets WHM configure third-party firewalls through a unified interface. Each firewall gets a driver directory:

/usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/
├── ConfigServercsf.pm          ← driver module
└── ConfigServercsf/
    └── META.pm                 ← driver metadata

When Sentinel installed, its cPanel integration (auto.cpanel.pl) patched these driver files — rewriting the package declaration from:

package Cpanel::Config::ConfigObj::Driver::ConfigServercsf;

to:

package Cpanel::Config::ConfigObj::Driver::Sentinelcsf;

The directory name stayed ConfigServercsf, but the package inside declared Sentinelcsf.

cPanel's driver loader derives the expected package name from the file/directory name. It asked for ConfigServercsf::META->get_driver_name() — a package that no longer existed, because the file now declared itself Sentinelcsf::META.

Result: a fatal Perl error on every WHM request that enumerated config drivers — which is essentially every page, because WHM's feature-showcase system loads the full driver list at login.

Why the uninstall didn't fix it

The Sentinel uninstaller removed Sentinel's files — /etc/csf, /usr/local/csf, its binaries. It had no reason to touch /usr/local/cpanel/... because those files belong to cPanel, not to Sentinel. From Sentinel's perspective, it had "installed" its driver by patching cPanel's files, and its uninstaller simply didn't know to revert them.

Classic plugin-uninstall gap: the payload was written into the host application's directory, so the host never got its files back.

The fix: two files from a sibling server

We had multiple cPanel servers in the fleet. Two DNS-cluster members (usdns, eudns) run cPanel but had never had CSF or Sentinel installed — meaning their driver files were pristine.

The repair was embarrassingly simple:

# On a clean cPanel server (usdns), copy the originals:
scp root@usdns:/usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ConfigServercsf.pm \
    root@beta:/usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/

scp root@usdns:/usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ConfigServercsf/META.pm \
    root@beta:/usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ConfigServercsf/

# Fix ownership (Sentinel had set a weird service-account owner)
chown root:root /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ConfigServercsf*

# Restart only the WHM daemon — nothing else
/scripts/restartsrv_cpsrvd

WHM returned 200 on port 2087, cPanel on 2083, zero new driver errors in error_log.

One trap we hit

The first attempt only restored ConfigServercsf.pm — the outer module. The fatal persisted because ConfigServercsf/META.pm (the inner metadata file) was still Sentinel-patched. cPanel needed both files to agree on the package name. If you're replicating this fix, replace the entire driver directory contents, not just the top-level .pm.

Lessons learned

  1. "Drop-in replacement" ≠ zero footprint. Sentinel advertised CSF compatibility, but its installer modified files inside cPanel's own tree. Read what an installer touches before running it — especially anything under /usr/local/cpanel/.
  2. Uninstallers only remove what they think they own. Anything the installer wrote into the host app's directories is orphaned on removal. After uninstalling any cPanel-integrated software, grep the cPanel tree for leftovers: 
    grep -rln "Sentinel" /usr/local/cpanel/Cpanel/Config/
  3. Keep a pristine reference. Our fleet having multiple cPanel servers saved us — we copied the original driver from a server that never ran the software. If you only have one cPanel box, back up /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ before installing third-party integrations.
  4. cPanel's driver framework is fragile by design. It scans and evals every driver on every WHM request. One malformed driver = fatal for the whole panel, not just the firewall settings page.
  5. The nuclear option exists but we didn't need it. A full /scripts/upcp cPanel update would have restored the files too — but it's heavy, touches everything, and we specifically wanted to avoid it. Surgical file restoration from a sibling server was faster and safer.

Current state

  • ✅ Sentinel fully removed — firewall back to nftables-only baseline
  • ✅ cPanel driver files restored to pristine ConfigServercsf package names
  • ✅ WHM (2087) and cPanel (2083) both healthy
  • ⚠️ cPanel license still flags X::UnlicensedIP for 148.251.118.251 — separate issue from the server migration, needs a license IP update with cPanel
  • 📋 Backup of the broken driver files preserved at /root/cpanel_driver_backup_20261114/ on the server (for forensics, not for restore)

The firewall question on beta is still open — Sentinel is gone, and the server is back to its original exposed state. When we revisit it, the safer path is probably a firewall that doesn't integrate into cPanel's driver tree at all, or accepting CSF's successor options once the ecosystem settles.

Post-mortem written after a production incident on a live shared-hosting server. Total downtime for WHM: ~45 minutes. Client-facing services (web, mail, DNS) were never affected — the breakage was confined to the control panel.



Sâmbătă, Noiembrie 14, 2026

« înapoi