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.

See also

There is a list of software versions and their corresponding configuration revision numbers at Versions of pfSense software and FreeBSD.

Backups using the same configuration revision can be restored as-is, both for complete configuration backups and partial (section-based) backups.

Complete backups with a lower configuration revision can be restored to a current version. The upgrade code will adjust the values in the configuration to convert it into a current format.

Partial (section-based) backups cannot be restored if they were taken on a version with a different configuration revision, as there is no mechanism for the upgrade code to handle partial backups.

Backups with a higher configuration revision cannot be restored to an older version. There is no mechanism to downgrade a configuration as the older version will have no knowledge of changes which happened in future versions of the software.

Restoring between pfSense CE and pfSense Plus or vice versa may work in many cases, but results depend upon the target hardware and version. For example, restoring to pfSense Plus on hardware with an integrated Ethernet switch may require manual adjustments. Contact Netgate TAC for specific guidance.

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.

../_images/backup-restore.png

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 fa-undo to restore that configuration file

../_images/backup-confighistory.png

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 fa-plus-circle 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 changed in version 2.5.0, so use the method appropriate for the version which generated the encrypted configuration file. In either case, replace <PASSWORD> with the appropriate password string, and change the filenames as needed.

2.5.0 and later:

grep -v "config.xml" config-encrypted.xml | base64 -d | \
  openssl enc -d -aes-256-cbc -out dencryptedfile.xml \
  -pass pass:<PASSWORD> -salt -md sha256 -pbkdf2

Older versions:

grep -v "config.xml" config-encrypted.xml | base64 -d | \
  openssl enc -d -aes-256-cbc -out dencryptedfile.xml \
  -pass pass:<PASSWORD> -salt -md md5