pfSense Backup and Configuration Recovery

pfSense backup is built around exporting the config.xml configuration file, which contains all system parameters. A properly organized backup process enables restoring the firewall within minutes after a hardware failure, administrator error, or system compromise. This guide covers all backup methods, restoration procedures, and best practices for ensuring configuration preservation.

config.xml Structure

The config.xml file resides in the /cf/conf/ directory and contains the complete pfSense configuration in XML format.

What config.xml Includes

What config.xml Does NOT Include

Warning:

The list of installed packages is saved in config.xml, but the packages themselves must be reinstalled after restoration. pfSense will automatically offer to install missing packages when it detects them in the configuration.

Manual Backup

Manual backup creation is performed through the web interface and takes only a few seconds.

Backup Procedure

1. Navigate to Diagnostics > Backup & Restore
2. Ensure the Backup & Restore tab is selected
3. Configure export parameters:

4. Click Download configuration as XML
5. Store the file in a secure location

Backup Areas

The Backup area dropdown provides the following options:

Partial backup is useful for transferring individual sections between devices without replacing the entire configuration.

Backup Encryption

Encrypting backups is strongly recommended because config.xml contains:

• User passwords (hashed)
• Certificate private keys (in plaintext)
• VPN tunnel pre-shared keys
• Authentication server shared secrets
• LDAP bind account passwords

When encryption is enabled, the file is protected with a password using AES-256-CBC. The password must be stored separately from the backup file - recovery is impossible without it.

Backup File Naming

pfSense generates file names in the format: config-<hostname>-<YYYY><MM><DD><HH><MM><SS>.xml

Consider adding the backup reason when manually renaming:

config-fw01-20260406-before-vpn-changes.xml
config-fw01-20260406-after-upgrade-2.7.2.xml

Automatic Backup

Built-in Automatic Backup

pfSense automatically creates a configuration backup on every change made through the web interface. The change history is stored locally and accessible from Diagnostics > Backup & Restore, tab Config History.

The number of stored versions is configurable under Diagnostics > Backup & Restore, tab Config History, field Backup Count.

The built-in history allows:

• Viewing a list of changes with dates and descriptions
• Comparing any two configuration versions (diff)
• Restoring any saved version

Warning:

The local backup history is stored on the same disk as the main configuration. If the disk fails, all versions will be lost. Local history does not replace storing backups in an external location.

AutoConfigBackup

AutoConfigBackup (ACB) is a cloud-based automatic backup service provided by Netgate for devices with an active pfSense Plus subscription or Netgate hardware. The service automatically uploads an encrypted configuration copy to the cloud on every change.

Configuring AutoConfigBackup

1. Navigate to Services > Auto Config Backup
2. Enter Netgate Portal credentials
3. Set an encryption password

ACB Characteristics

• Configuration is encrypted locally before transmission - Netgate has no access to the contents
• Up to 100 recent configuration versions are stored
• Restoration is available from the saved version list in the web interface
• If the encryption password is lost, recovery from ACB is impossible

Scheduled Backups via Cron

For automated backups on a schedule with external storage, use the Cron package and a configuration export script.

Setting Up Automatic Backup via SCP

1. Install the Cron package through System > Package Manager
2. Create a cron job for configuration copying:

0 2 * * * /usr/bin/scp /cf/conf/config.xml backup@storage.example.com:/backups/pfsense/config-$(date +\%Y\%m\%d).xml

For passwordless SCP, configure SSH key authentication between pfSense and the storage server.

Alternative Automation Methods

Restoring from Backup

Full Restore

A full restore replaces the entire current configuration with the backup file contents.

1. Navigate to Diagnostics > Backup & Restore
2. In the Restore Backup section, select the backup file
3. Configure restore parameters:

4. Click Restore Configuration
5. Wait for the system to reboot

After a full restore, pfSense automatically:

• Applies all interface settings
• Restores firewall and NAT rules
• Restarts VPN services
• Offers to install missing packages

Partial Restore

A partial restore replaces only a specific configuration section without affecting other settings.

1. In the Restore area field, select the desired section (Firewall Rules, OpenVPN, NAT, etc.)
2. Upload the backup file
3. Click Restore Configuration

Partial restore is useful for:

• Recovering firewall rules after erroneous changes
• Transferring VPN configuration from another device
• Restoring DHCP settings without modifying the rest of the configuration

Restoring from Local History

1. Navigate to Diagnostics > Backup & Restore, tab Config History
2. Locate the desired configuration version by date and description
3. Click the restore icon next to the selected version
4. Confirm the restoration

Recovery After Complete System Loss

In the event of total system loss (disk failure, hardware destruction), the recovery procedure consists of the following steps:

1. Install pfSense on new hardware
2. Perform initial setup (interface assignment, base IP address)
3. Access the web interface
4. Navigate to Diagnostics > Backup & Restore
5. Restore the configuration from the backup file
6. Wait for the reboot
7. Install missing packages
8. Verify all services are operational

Configuration Migration Between Devices

Migration Between Devices with the Same pfSense Version

When transferring configuration between devices running the same pfSense version, follow the standard backup and restore procedure. Consider the following:

• Interface assignments must correspond to the new hardware
• If network adapters differ, interface reassignment through the console may be required
• CARP VHID and Virtual IP settings require verification after transfer

Migration Between Different pfSense Versions

pfSense supports restoring configurations from earlier versions with automatic format migration.

Recommended migration procedure between versions:

1. Create a backup on the old device
2. Install the new pfSense version on the target hardware
3. Restore the configuration from the backup
4. Review the migration log for warnings
5. Test all critical services

Migration Between Different Hardware

When transferring configuration to hardware with a different set of network interfaces:

1. Restore the configuration from the backup
2. When prompted, perform interface reassignment through the console
3. Map the new hardware physical interfaces to the configuration logical interfaces
4. Verify IP address assignment correctness on each interface

Warning:

When the number or types of interfaces differ between old and new hardware, some settings may require manual adjustment. Pay particular attention to firewall rules bound to specific interfaces.

Backup Package for Additional Files

The standard config.xml backup does not include custom files placed outside the configuration. The Backup package is designed for this purpose.

Installation and Configuration

1. Install the Backup package via System > Package Manager
2. Navigate to Diagnostics > Backup Files/Dirs
3. Add files and directories for inclusion in the backup:

Files added through the Backup package are included in the main config.xml backup as base64-encoded content.

Troubleshooting

Restore Failure

Version Incompatibility During Restore

If restoring a configuration from a newer pfSense version to an older one produces errors:

1. Install the pfSense version matching the backup
2. Restore the configuration
3. If necessary, perform a version downgrade through the console (not recommended)

Restoring Without Web Interface Access

If the web interface is unavailable, configuration can be restored through the console:

1. Connect to the console (physically or via serial)
2. Select option 15) Restore recent configuration
3. Choose the configuration version to restore
4. Confirm the restoration

Alternative method - copying config.xml directly:

# Copy the backup file to a USB drive
# Connect USB to the pfSense device
# Through shell (option 8 in the console):
mount /dev/da0s1 /mnt
cp /mnt/config.xml /cf/conf/config.xml
reboot

Best Practices

When to Create a Backup

Backup Storage Strategy

Follow the 3-2-1 principle:

• 3 copies of the configuration (primary + two backups)
• 2 different media types (local disk + remote server)
• 1 copy in a geographically separate location

Backup Security

Restore Testing

A backup is only useful if it can be successfully restored. Periodically conduct test restorations:

1. Deploy a test pfSense instance (virtual machine)
2. Restore the configuration from the backup
3. Verify all settings are correct
4. Confirm all services start properly
5. Document the test results

Recommended testing frequency - at least once per quarter.

Procedure Documentation

For each firewall, document:

• Backup file locations and encryption passwords (in a password manager)
• Recovery procedure with designated responsible personnel
• Interface reassignment instructions for migration to spare hardware
• Escalation contacts for recovery issues

Related Sections

• Certificate Management - certificates and keys stored in config.xml
• User Management - user accounts and privileges included in the backup
• High Availability - CARP - configuration synchronization between HA cluster nodes