Automatically Restore Configuration During Installation

In addition to restoring through the GUI, pfSense® software supports methods which restore a configuration to a new setup without going through all the trouble of setting up a client and restoring using a web browser.

These methods are significantly easier than reconfiguring the LAN and restoring via the network, especially in complex environments. The firewall will start up using the restored configuration immediately without needing intermediate steps.

Recover config.xml From Existing Installation

The installer has a Recover config.xml option which reads the configuration file from an existing installation before starting the install process and puts it back in the exact same location when it finishes. This makes the feature useful for upgrades, filesystem changes, or any other situation requiring a reinstallation on the same disk. In addition to copying the existing configuration this function also attempts to copy the SSH host keys.

Note

The Recover config.xml option works on installations using either UFS or ZFS.

  • Take a backup of the configuration before starting, if possible, in case this procedure does not work as expected

  • Boot a pfSense software installation image

  • Choose Recover config.xml when the option appears

  • Select the existing installation drive (e.g. ada0)

    The selection list shows the disk name, size, and filesystem type which is typically enough to identify the disk

  • Wait a moment while the recovery process happens

    The recovery process attempts to repair the filesystem on the disk up to 10 times, then mounts the disk and looks for the existing configuration file. If it is able to find and read the configuration file, the recovery process copies it to a temporary RAM disk during the installation process.

    Note

    The recovery process only briefly displays its output, so it can be difficult to spot whether it succeeded or failed. If the process fails, the configuration either is not there or it was not recoverable. Either way, proceeding is safe as it is unlikely the config.xml would be recovered from the drive by other means.

  • Proceed through the installation as usual

At the end of the installation, the installer automatically copies the configuration from the temporary RAM disk back to the target disk before rebooting.

The firewall will boot off the target disk with the configuration restored by the installer already in place. The firewall will reinstall packages automatically in the background.

Restore Configuration from USB During Install

As part of the installation routine, the installer checks for an existing configuration on a USB drive formatted as FAT or FAT32. If the installer can locate and read a configuration file, it copies the file to the target disk.

The configuration may include additional data from options on the backup page, such as RRD, SSH keys, DHCP lease databases, and captive portal data. The configuration may also be encrypted, the installer will prompt for the password to decrypt the configuration if necessary.

Warning

This feature does not support drives formatted with exFAT, only FAT or FAT32.

For this feature to work correctly, the USB drive must contain a partition table and it must not be formatted as a raw device.

Tip

The pfSense software memstick installation image contains a FAT partition which the installer can use for this purpose. If the partition is not visible on the workstation which wrote the memstick image, remove and reinsert the USB drive.

  • On a FAT/FAT32 formatted USB drive, make a directory called conf

  • Copy a backup configuration file to the conf directory

  • Rename the backup to config.xml

    Example: If the USB drive is E:, the full path would be E:\conf\config.xml

    Note

    The installer also looks for config.xml in the root directory of the drive, but the best practice is to place the file in the conf directory.

  • Unmount/eject the USB drive, remove it, then plug it into the firewall

  • Boot the install media (Memstick, disc, etc)

  • Install to the target disk

    Note

    If the configuration on the USB drive is encrypted, the installer will prompt for the decryption password near the end of the installation process.

  • Reboot the firewall

  • Remove the USB drive only AFTER the firewall has begun to reboot

    Warning

    If the USB drive is removed too early, it may still be mounted and the system will panic!

  • Remove the install media as well at this point

The firewall will boot off the target disk with the restored configuration.

Restore using the External Configuration Locator (ECL)

pfSense software also includes a feature called the External Configuration Locator, or ECL for short. The ECL process runs at boot time to, as the name implies, locate configuration files on external storage. If the ECL finds a configuration file, it copies that file to the firewall disk, replacing any existing configuration.

Note

The ECL runs on every boot, so its use is not limited to fresh installations.

This procedure is nearly identical to the method in Restore Configuration from USB During Install, but the USB disk containing the configuration does not need to be present during the installation. The same warnings from that procedure also apply here.

  • On a FAT, FAT32, or UFS formatted USB drive, make a directory called config

  • Copy a backup configuration file to the config directory

  • Rename the backup to config.xml

    Example: If the USB drive is E:, the full path would be E:\config\config.xml.

    Note

    The ECL also looks for config.xml in the root directory of the drive, but the best practice is to place the file in the config directory.

  • Unmount/eject and remove the USB drive

  • Install pfSense software as usual

    This is optional, since the ECL runs on existing installations.

  • Reboot the firewall

  • Insert the USB drive containing the configuration while the firewall boots and the ECL will read in the configuration file from there

    Note

    USB drives which only contain files can be inserted before the firewall boots. Bootable USB drives, such as the installation memstick, should not be inserted until after the firewall has started to boot from its own disk. This behavior will vary by target device and its boot preferences. Monitor the console to find the appropriate timing.

    Timing is also affected by the speed of the device. Slower systems may not mount the USB drive before the ECL runs.

  • Wait for the firewall to complete the boot process

  • Check that the configuration was loaded properly

    If the configuration did not load as expected, check the file location and name on the USB drive, and check the timing of when the USB drive was present during the boot process, then start over. Monitor the console for details.

  • Remove the USB drive once the correct configuration file is in place

If this is the first boot post-installation, then this process also triggers reinstallation of packages listed in the restored configuration.

Warning

This procedure will copy the config.xml file from the USB drive to the target drive at every boot. However, the running firewall will not copy its own configuration back to the USB drive. Thus, leaving the drive inserted in the firewall will result in losing all configuration changes not present in the configuration file on the USB drive.