How to configure a cPanel backup destination via FTP

You will configure an FTP server and link it as a remote backup destination in WHM so that cPanel can automatically push account backups there. This guide targets cPanel 118.x and uses standard Linux FTP servers like vsftpd. You will create a dedicated user, set up a backup folder, and enable the feature in WHM.

Prerequisites

• Access to a Linux server with cPanel installed (cPanel 118.x or later).
• Root or Reseller access to WHM.
• An active FTP server installed (e.g., vsftpd or pure-ftpd).
• A domain or IP address to host the FTP server.
• SSH access to the server to run commands.

Step 1: Install and configure the FTP server

Install the vsftpd package to handle file transfers securely. You need a reliable FTP service to store the backups. Run the following command to install it:

apt-get update && apt-get install -y vsftpd

After installation, create a dedicated backup user with a strong password. Replace backup_user and backup_password with your chosen values:

useradd -m backup_user -s /sbin/nologin
echo "backup_password" | chpasswd

Create a specific directory for cPanel backups and set the correct permissions. The directory must be writable by the FTP user but readable by cPanel processes:

mkdir -p /var/backup
chown backup_user:backup_user /var/backup
chmod 755 /var/backup

Edit the vsftpd configuration file to allow passive mode and restrict the user to the backup folder. Open the config file with a text editor:

vim /etc/vsftpd.conf

Add or modify the following lines inside the file to secure the FTP service:

allow_writeable_chroot=YES
pasv_min_port=40000
pasv_max_port=50000
write_enable=YES
anon_enable=NO
chroot_local_user=YES

Restart the FTP service to apply the changes:

systemctl restart vsftpd

Step 2: Generate FTP credentials in WHM

Open WHM and navigate to Home > Software > FTP Accounts. Click the "Create FTP Account" button. Enter the username backup_user and the password you set in Step 1. Click "Create" to save the account.

Next, configure the backup folder path in WHM. Go to Home > Software > FTP Accounts and select the newly created account. In the "Home Directory" field, enter /var/backup. Save the changes. This ensures the FTP user only accesses the backup folder.

Verify the FTP connection using an FTP client like FileZilla. Log in with the credentials you created. You should see the /var/backup folder listed. If you see an error, check the firewall rules and vsftpd logs.

Step 3: Configure WHM to use the FTP destination

Open WHM and navigate to Home > Software > Backups > Set up a backup destination. Click the "Add a backup destination" button. Select "FTP" from the dropdown menu. Enter the FTP host (your server's IP or domain), username, and password.

Set the remote path to /var/backup. This is where cPanel will push the backups. Save the configuration. WHM will now use this FTP server as a remote backup destination for all accounts.

Test the connection by running a manual backup. Go to Home > Software > Backups > Full Backup. Select the accounts you want to backup and choose "FTP" as the destination. Click "Backup". Wait for the process to complete. Check the FTP folder to confirm the backup files are uploaded.

Verify the installation

Run a test backup to confirm the FTP destination is working. Open WHM and navigate to Home > Software > Backups > Full Backup. Select a test account and choose "FTP" as the destination. Click "Backup". After the process finishes, log in to the FTP server and check the /var/backup folder. You should see a new backup file with the account name and timestamp.

Troubleshooting

Error: 530 Permission denied
This error occurs when the FTP user lacks permission to access the backup folder. Check the ownership of the directory with ls -ld /var/backup. Ensure the user backup_user owns the folder. Run chown backup_user:backup_user /var/backup if needed. Also verify that the vsftpd service is running with systemctl status vsftpd.

Error: 450 Permission denied
This error indicates the FTP user cannot write to the directory. Check the permissions with ls -ld /var/backup. Ensure the permissions are set to 755 or higher. Run chmod 755 /var/backup to correct this. Also verify that the FTP server is not in chroot mode that blocks writing.

Error: Backup fails to upload to FTP
Check the WHM error logs for details. Run tail -n 50 /var/log/cpanel/cpanel-backup.log to see recent errors. Look for "Permission denied" or "Connection refused" messages. Ensure the firewall allows FTP traffic (ports 20, 21, and the passive range 40000-50000). Run ufw allow 20,21 if using UFW.

Error: Passive mode fails
If passive mode connections fail, adjust the vsftpd passive port range. Edit /etc/vsftpd.conf and set pasv_min_port=40000 and pasv_max_port=50000. Restart the FTP service with systemctl restart vsftpd. Ensure the firewall allows traffic on these ports.

Error: Backup file is corrupted
If the backup file is corrupted, check the FTP connection stability. Run a manual backup and compare the file size with the expected size. If the file is incomplete, re-run the backup. Ensure the FTP server has enough disk space to store the backup files.

Error: WHM cannot connect to FTP
Verify the FTP server is running and accessible. Run curl -v ftp://backup_user:backup_password@your_server_ip to test the connection. If it fails, check the vsftpd logs for errors. Ensure the FTP user is not locked out by running passwd -S backup_user.

Error: Backup fails due to disk space
Check the available disk space on the FTP server. Run df -h /var/backup to see the usage. If the disk is full, clean up old backups or expand the partition. Ensure the backup destination has enough space for the largest account backup.

Error: Backup fails due to SELinux
If SELinux is enabled, it may block FTP connections. Check the SELinux status with getenforce. If it is set to "Enforcing", temporarily set it to "Permissive" with setenforce 0 to test. If the backup works, create a custom SELinux policy to allow FTP access.