Upgrading an Existing Installation¶
pfSense software can be reliably upgraded from an older release to a current release.
By keeping a firewall running pfSense software updated with a current supported release, it will never be obsolete. We periodically release new versions that contain new features, updates, bug fixes, and various other changes. In most cases, updating a pfSense installation is easy. If the firewall is updating to a new release that is a only a point release (e.g 2.4.2 to 2.4.3), the update is typically minor and unlikely to cause problems.
The most common problem encountered during upgrades is hardware-specific regressions from one FreeBSD version to another, though those are rare. Updated releases fix more hardware than they break, but regressions are always possible. Larger jumps, such as from 2.1.5 to 2.4.3-RELEASE-p1 must be handled with care, and ideally tested on identical hardware in a test environment prior to use in production.
We post upgrade notes along with releases to help guide through any potential upgrade pitfalls. These notes vary from release to release, the most current version can be found on the Upgrade Guide.
Make a Backup … and a Backup Plan¶
Before making any modifications to a firewall, the best practice is to make a backup using the WebGUI:
- Navigate to Diagnostics > Backup/Restore
- Set the Backup Area to ALL in the Backup Configuration section of the page
- Click Download
- Save this file somewhere safe
Keep multiple copies of the backup file in different secure locations. Customers with a pfSense Gold Subscription should consider using the Auto Config Backup package. Customers using the Auto Config Backup package can make a manual backup with a note identifying the change, which is encrypted and stored on our servers.
Another good practice is to have install media handy for the release currently being run, and for the new release, in case something goes awry and a reinstall is required. Should that happen, have the backup file on hand and refer to Backup and Recovery.
There are several methods available for updating a normal installation of pfSense software. Either the WebGUI or the console can be used.
Upgrading using the WebGUI¶
The Automatic Update feature contacts a pfsense.org server and determines if there is a release version newer than the version on the firewall. This check is performed when an administrator visits the dashboard or System > Update.
Click Confirm on System > Update to start the update if one is available.
The update takes a few minutes to download and apply, depending on the speed of the Internet connection being used and the speed of the firewall hardware. The firewall will reboot automatically when finished.
Upgrading using the Console¶
An update may also be run from the console. The console option is available from
any means available for console access: Video/Keyboard, Serial Console, or SSH.
Once connected to the console of the firewall, start the upgrade process by
choosing menu option
Alternately, from a shell prompt running as root, manually execute the following command:
Versions of pfSense software prior to 2.3 used a different upgrade method. For
“full” installations, a
tgz file was used by the firewall to copy in the new
files. This method was problematic and is no longer used. However, for the time
being, update files in that format are still provided by the project in order to
bring older firewalls up to date.
On these older versions, an auto update will still function. After running the automatic update there may be newer releases available, so once the firewall is running a version of pfSense 2.4 or later, run another update if the firewall detects it is necessary.
Reinstalling / Upgrading Configuration¶
If an upgrade will not function properly on an existing installation, the configuration file can be restored to a freshly installed copy of pfSense software. An older configuration can always be imported into a new version. The upgrade code will make necessary changes to the configuration so it will work with the current version of the software.
Branch / Tracking Snapshots¶
By default, the update check only looks for officially released versions of pfSense software, but this method can also be used to track development snapshots. The update location can be changed by visiting System > Update, Update Settings tab and selecting a different Branch in the Firmware Branch section.
Stable versions are the best option, as they see the most testing and are reasonably safe and trouble-free. However, as with any upgrade, visit the pfSense website and read the update notes for that release, and check the Upgrade Guide.
Choose Development Snapshots to switch a firewall over to tracking development snapshot builds. These generally are snapshots for the next minor maintenance branch release.
In some cases, a Next Major Version option will be in the list. This option makes the firewall track snapshots for the next major update version. This is riskier, but in some cases may be required for newer hardware or new features that are not yet released. Consult the forum and test in a lab to see if these snapshots are stable in a particular environment. We do not generally recommend running these in production.
The Dashboard Check checkbox on System > Update, Update Settings tab controls whether or not an update check is performed by the System Information widget on the dashboard. On firewalls with low resources or slow disks, disabling this check will reduce the load caused by running the check each time an administrator views the dashboard.
This section is for developers and should not be used by end users. Leave settings in this area empty or disabled.