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.

Configuration History

For minor problems, using one of the internal backups on the firewall is the easiest way to back out a change. By default the previous 30 configurations are stored in the Configuration History, along with the current running configuration. The configuration history is found at Diagnostics > Backup & Restore on the Config History tab. The amount of entries available in the configuration history is configurable (Configuration Backup Cache Settings).

Configuration History List

Each row in the configuration history contains the following items:

Diff Selectors

Two columns of radio selectors which pick entries for viewing the differences between them. See Config History Diff for details.

Checkbox (Plus Only)

Selection checkbox for deleting multiple entries from the history. Select one or more entries and then click the fa-trash-can Delete button under the list.

Date

The date and time at which the configuration file was made.

Configuration Change

An identifier declaring which system or user made a configuration change along with a brief description of what changed in the configuration.

Version/Revision

The configuration revision of the entry, as described earlier in this document in Backup Compatibility.

See also

Size

The amount of disk space consumed by this backup.

Actions

Icons which take action on each entry individually, including:

  • fa-undo: Restore this configuration from the history.

  • fa-download: Download this configuration file from the history.

  • fa-trash-can: Delete this configuration file from the history.

    Note

    There is no need to delete entries by hand to save space; the firewall automatically deletes old configuration backups when it creates new entries.

    However, it is a good practice to remove known-bad configuration changes to ensure that they are not accidentally restored.

Note

The order of these columns differs between pfSense Plus and pfSense CE software.

../_images/backup-confighistory.png

Configuration History on pfSense Plus Software

../_images/backup-confighistory-ce.png

Configuration History on pfSense CE Software

Restoring from Configuration History

To restore a configuration from the history:

Warning

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 apply 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.

ZFS Boot Environments (Plus Only)

On pfSense Plus software installations utilizing ZFS Boot Environments, this page contains an additional Boot Environments section. Each Boot Environment contains its own Configuration History, and the option in this section controls which set of Configuration History entries the page displays.

The Boot Environments section contains the following fields:

Boot Environments

A drop-down selection list containing all of the available ZFS Boot Environments. Selecting a different entry refreshes the page to display Configuration History entries from that Boot Environment.

Base Version

Read-only field indicating the version of pfSense software installed in the selected Boot Environment.

Created

Read-only field indicating the date that the selected Boot Environment was created.

Last Booted

Read-only field indicating the date that the selected Boot Environment was last booted.

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 (If present)

  • Enter the new number of configurations to retain in the Backup Count field

  • Click Save

Note

On pfSense Plus software the settings are at the bottom of the page and always visible. On pfSense CE software the settings are above the list, but collapsed by default.

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.

On the left side of the configuration history list there are two columns of radio buttons. Use the leftmost column to select the older of the two configuration entries, and then use the right column to select the newer of the two entries. Once both entries have been selected, click Compare (Plus) or Diff (CE) 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

Warning

If the password contains any non-shell-safe characters such as !, `,\ , ; or similar, escape the characters or quote the string.

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

Warning

If the password contains any non-shell-safe characters such as !, `,\ , ; or similar, escape the characters or quote the string.

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

Warning

If the password contains any non-shell-safe characters such as !, `,\ , ; or similar, escape the characters or quote the string.