CSF firewall

CSF (ConfigServer Security & Firewall, GPLv3 since August 2025, maintained by cPanel and community forks) can run on a KVM hypervisor next to VirtConsole. Supported from agent version 3.2.2 (released as Slave 3.2.2).

How it works

CSF owns the INPUT and OUTPUT chains, which protect the host’s own services. VirtConsole owns the FORWARD chain, where tenant security groups filter traffic to and from the VM tap interfaces, and the VPC network namespaces. Bridged VM traffic never traverses CSF’s INPUT and OUTPUT rules.

When the agent detects CSF on a node it does not touch firewalld or ufw. It expects you to whitelist the ports below in csf.conf yourself.

The agent also keeps a VC_VNC chain at the top of INPUT that accepts each guest’s VNC port only from the platform master and the addresses listed in Admin > System > Settings > “VNC console allowed sources”, and drops every other source. Each entry in that setting must be a bare IPv4 or IPv6 address or CIDR; saving settings with an invalid entry is refused and the message names every invalid entry. This applies on CSF hosts too, so VNC ports do not need a separate TCP_IN entry.

Before you begin

firewalld and ufw are disabled. CSF requires this.
iptables and ip6tables resolve to the nft backend on the node, the same backend CSF uses. Check with update-alternatives --display iptables.

Ports to whitelist in /etc/csf/csf.conf

Setting	Add	Purpose
`TCP_IN`	`2443`	Management server to agent API
`TCP_IN`	`8889`	WebSSH relay (hypervisor-ssh-proxy)
`TCP_IN`	`22` (or your custom SSH port)	Live migration control channel (`qemu+ssh`) and operator access
`TCP_IN`	`49152:49215`	Live migration data stream (libvirt default range)
`TCP_OUT`	`2443`, `22`, `3922`, `49152:49215`	Agent to other nodes and management SSH into guests on public interfaces
`UDP_IN` and `UDP_OUT`	`4789`	VXLAN fabric between nodes (VPC)

Shared storage (NFS, Ceph, iSCSI) needs its own ports; follow your storage guide. Instead of opening 2443 and 8889 to the world, you can put the management server’s public IP in csf.allow.

Re-apply rules after a CSF restart

CSF flushes every iptables chain on csf -r, on lfd restart and at boot. After csf -r the VC_VNC chain is gone until sg:sync --force runs, and the console stays unreachable until then. The hook below is required.

Create /etc/csf/csfpost.sh with this content and make it executable with chmod 755:

#!/bin/sh
# VirtConsole: CSF rebuilt the iptables ruleset; re-apply security groups and VPC forwarding.
( sleep 2; /usr/bin/vcli sg:sync --force; /usr/bin/vcli vpc:sync ) >/dev/null 2>&1 &

To verify the security group scaffold is back after a restart, run:

iptables -S FORWARD | head -4

The output must list SG_INGRESS and SG_EGRESS.

Common problems

Console does not connect. The csfpost.sh hook is missing or not executable (check with iptables -S VC_VNC; no output means the chain is gone, run /usr/bin/vcli sg:sync --force), or the master’s address changed (update Admin > System > Settings > Platform Master IPs). Note: agents before 3.2.3.3 required the VNC range in TCP_IN; that is no longer needed.
Live migration hangs. 49152:49215 or the SSH port is missing from TCP_IN or TCP_OUT.
VPC guests cannot reach each other across nodes. UDP 4789 (VXLAN) is not in UDP_IN and UDP_OUT.
Agent shows firewalld errors. CSF was not detected: csf.conf exists but no csf or lfd binary is installed. Install CSF fully or remove the stale csf.conf.
vcli hypervisor:deploy stops with Failed to enable unit: Unit file /etc/systemd/system/firewalld.service is masked. Slave agents before 3.2.2.3 tried to enable firewalld even under CSF. Update the agent (the fix ships in 3.2.2.3) and rerun vcli hypervisor:deploy. Do not unmask or enable firewalld as a workaround: CSF and firewalld would then both manage the host ruleset. If you already did, revert it with systemctl disable --now firewalld && systemctl mask firewalld.