Migrate cPFence v3 to v4

Migration in beta

The v3 to v4 migration is currently in beta. We recommend trying it on a lower-priority server or cluster first. If you notice a problem, open a support ticket with the error and /var/log/cpfence-v4-install.log, and our team will help.

The v4 installer backs up your existing installation, restores supported settings and quarantine, and reuses your license. This guide covers cPFence v4+.

Before you start

Use root on an Enhance server running Ubuntu 22.04 or 24.04, with a valid cPFence license. Keep a private recovery backup and allow a maintenance window: protection pauses briefly during migration.

Configure your hosting-provider firewall

• On every secondary server, open TCP 9096 in your hosting-provider firewall and allow connections from the main control panel server’s IP addresses.
• On the main control panel server, open TCP 9095 in your hosting-provider firewall for WebUI access.

cPFence manages the required server-local firewall rules. Configure the hosting-provider firewall separately.

Upgrade the main control panel server first, then each secondary server. Secondary servers still on v3 retain their protection but cannot be managed remotely through the v4 WebUI.

Upgrade one server

1. Run this command as root:

   bash <(curl -ks https://api.cpfence.app/v4/install.sh) --upgrade --yes

   --yes confirms the migration immediately. Run it only when you are ready to proceed.

2. Wait for Upgrade completed successfully. Read any configuration notices about settings or features unavailable on that server’s role.

3. Check the result:

   cpfence --status

   Confirm an Active license and your intended protection settings.

4. Open the WebUI and check Servers. Repeat the upgrade on each secondary server and confirm its connection.

5. Review imported quarantine in Threat & Malware Detection → Advanced Tools → Restore Quarantined Files. Files with unknown original locations remain visible with restoration disabled.

After upgrading each secondary server, open its Details and check the connection and cluster identity. Names and addresses are blurred. Select the image to enlarge it; use your browser's Back command to return.

Your existing settings and administrator password are retained where supported. Recovery archives remain under /var/cpf_backups/; keep them private.

If migration stops

Resolve the displayed error, then rerun the same upgrade command. The installer resumes saved progress and reuses completed backups. Keep the archives and progress files; do not delete them or reinstall v3 over a partial migration.

Migration does not automatically roll back to v3 after removal. If retry still fails, contact support privately with the error and installed version. The installer log is /var/log/cpfence-v4-install.log.

Already on v4? Use cpfence --update. For a new server, follow Install cPFence.