Restoring from Backups¶

Backups are not useful without a means to restore them, and by extension, test them. Several means for restoring configurations are available in pfSense® software. Each method has the same end result: a running firewall identical to when the backup was made.

Backup Compatibility¶

The version of pfSense Plus or pfSense CE software is not as important as the Configuration Revision number when determining backup compatibility. Differences in the configuration revision number indicate changes in the format of the configuration data which makes them not directly compatible.

Restoring with the GUI¶

The easiest way for most users to restore a configuration is by using the GUI:

Navigate to Diagnostics > Backup & Restore
Locate the Restore Backup section (Figure GUI Restore).
Select the area to restore, or leave at the default selection for a complete backup.

Note

This value must match the Backup area chosen when creating the backup.
Click Browse
Locate the backup file on the local PC
Click Restore Configuration

The firewall will then apply the configuration and reboot with the settings obtained from the backup file.

GUI Restore¶

While easy to work with, this method has prerequisites when dealing with a full restore to a new installation. First, it would need to be done after the new target system is fully installed and running. Second, it requires an additional PC connected to a working network or crossover cable behind the firewall being restored.

Restore Options¶

Restore Area: Restores a backup containing only a single configuration area, rather than a complete configuration backup.

Warning

Restoring a single area does not trigger a reboot nor does it cause any part of the configuration to be reapplied. To ensure the restored configuration area is active, issue a reboot or manually refresh the configuration for the relevant area after restore (e.g. edit/save/apply on a page, issue a filter reload, etc).

Warning

When restoring a single area, the area being restored must be from the same version. Single areas do not support running upgrade code on the configuration, and thus cannot be adjusted if the format of the area changed from a previous version.

Warning

This does not restore one area from a full backup, the backup file must only contain the area to restore.

Note

This value must match the Backup area chosen when creating the backup.
Configuration File: A Browse button to select a backup file to upload and restore.
Preserve Switch Configuration: This option is available on Netgate hardware with integrated switches. When set, the current active switch configuration will be copied into the restored configuration, preserving it for later use. This makes it easier to restore a configuration from hardware without an integrated switch.

Note

This only copies the integrated switch configuration, and does not copy VLAN or LAGG interface entries which may be relevant to using the switch. This behavior is safer, as the configuration being restored may also contain important configuration data in those areas.
Encryption: When set, a Password field is presented, the contents of which is used by the firewall to decrypt the contents of the backup file before restoring the configuration.

Restoring from the Config History¶

For minor problems, using one of the internal backups on the firewall is the easiest way to back out a change. The previous 30 configurations are stored in the Configuration History, along with the current running configuration.

Each row in the configuration history list shows the date the configuration file was made, the configuration version, the user and IP address of a person making a change in the GUI, the page that made the change, and in some cases, a brief description of the change that was made. The action buttons to the right of each row show a description of what they do when the mouse pointer is hovered over the button.

To restore a configuration from the history:

Navigate to Diagnostics > Backup & Restore
Click the Config History tab (Figure Configuration History)
Locate the desired backup in the list
Click to restore that configuration file

Configuration History¶

Restoring a configuration with this method does not initiate an automatic reboot. Minor changes do not require a reboot, though reverting some major changes will.

If a change was only made in one specific section, such as firewall rules, trigger a refresh in that area of the GUI to enable the changes. For firewall rules, a filter reload would be sufficient. For OpenVPN, edit and save the VPN instance. The necessary actions to take depend on the changes in the restored configuration, but the best way ensure that the full configuration is active is to reboot.

If necessary, reboot the firewall with the new configuration by going to Diagnostics > Reboot System and click Yes.

Previously saved configurations may be deleted by clicking fa-trash , but do not delete them by hand to save space; the old configuration backups are automatically deleted when new ones are created. It is desirable to remove a backup from a known-bad configuration change to ensure that it is not accidentally restored.

A copy of the previous configuration may be downloaded by clicking fa-download .

Configuration Backup Cache Settings¶

The amount of backups stored in the configuration history may be changed if needed.

Navigate to Diagnostics > Backup & Restore
Click the Config History tab
Click at the right end of the Configuration Backup Cache Settings bar to expand the settings
Enter the new number of configurations to retain in the Backup Count field
Click Save

Along with the configuration count, the page also displays the amount of space consumed by the backup cache.

Config History Diff¶

The differences between any two configuration files may be viewed in the Config History tab. To the left of the configuration file list there are two columns of radio buttons. Use the leftmost column to select the older of the two configuration files, and then use the right column to select the newer of the two files. Once both files have been selected, click Diff at either the top or bottom of the column.

Console Configuration History¶

The configuration history is also available from the console menu as option 15, Restore Recent Configuration. The menu selection will list recent configuration files and offer to restore one. This is useful if a recent change has locked administrators out of the GUI or taken the firewall off the network.

Restoring by Mounting the Disk¶

Attaching the disk from an installation of pfSense software to a computer running FreeBSD enables the drive to be mounted by the FreeBSD host and a new configuration may be copied directly onto the installed system, or a configuration file from a failed system may be copied off.

Note

This can also be performed on a separate installation of pfSense in place of a computer running FreeBSD, but do not use an active production firewall for this purpose. Instead, use a spare or test firewall.

The config.xml file is kept in /cf/conf/, but the difference is in the location where this directory resides. This is part of the root slice (typically da0p2). The drive and partition name will vary depending on disk type and position in the host.

Encrypted Configuration files¶

The GUI can automatically determine the correct decryption method when restoring an encrypted configuration backup file, whether it’s from a current version or an older version. When restoring an encrypted configuration file, check Configuration file is encrypted then enter the password in the Password field, and restore as usual from there.

Encrypted configuration files can be manually decrypted using the correct password for offline inspection.

The method used to encrypt configuration files has changed in recent versions, so use the method appropriate for the version which generated the encrypted configuration file.

In any of the following cases, replace <PASSWORD> with the appropriate password string, and change the filenames as needed.

Plus 22.05 and CE 2.7.0 and later¶

These versions use secure options with high iterations for increased security:

$ openssl enc -d -a -aes-256-cbc \
  -in config-encrypted.xml -out dencryptedfile.xml \
  -pass pass:<PASSWORD> -salt -md sha256 -pbkdf2 -iter 500000

These versions also include a PHP shell script which can encrypt and decrypt configurations from a shell on the firewall itself:

$ pfSsh.php playback cryptconfig \
  decrypt /root/config-encrypted.xml /root/dencryptedfile.xml

The script will prompt for the decryption password.

Plus 21.02 through 22.01 / CE 2.5.x through CE 2.6.x¶

These versions used more secure parameters than the older options, but with the default iteration count:

$ openssl enc -d -a -aes-256-cbc \
  -in config-encrypted.xml -out dencryptedfile.xml \
  -pass pass:<PASSWORD> -salt -md sha256 -pbkdf2

Older versions¶

Versions before the ones stated previously used older legacy options:

$ openssl enc -d -a -aes-256-cbc \
  -in config-encrypted.xml -out dencryptedfile.xml \
  -pass pass:<PASSWORD> -salt -md md5