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 Configuration Restore option which can read configuration files and other key data (SSH host keys, DHCP leases) from an existing installation before starting the install process and then it restores those files to the new installation when it completes.

This is useful for upgrades, filesystem changes, loader changes, or any other situation requiring a reinstallation on the same disk.

Note

The Configuration Restore option works on installations using either UFS or ZFS.

See Configuration Restore for information on how to utilize this feature during installation.

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 Media During Install

The Configuration Restore feature will look for files named config.xml anywhere on a FAT or FAT32 partition. Selecting one of these files will copy it into the target installation automatically during the install process.

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.

This feature works with any FAT or FAT32 partition the installer can mount during the install process. This can be a USB thumb drive/memory stick or an optical disk/virtual drive.

  • Connect a USB drive formatted with a FAT or FAT32 partition

  • Copy a backup configuration file to the drive

  • Rename the backup to config.xml

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

    Note

    The installer looks for config.xml in any directory on the drive, there are no restrictions on where the file must be located.

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

See Configuration Restore for information on how to utilize this feature during installation.

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