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
directoryRename the backup to
config.xml
Example: If the USB drive is
E:
, the full path would beE:\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 theconf
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
directoryRename the backup to
config.xml
Example: If the USB drive is
E:
, the full path would beE:\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 theconfig
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.