Upgrade Guide

pfSense® software can be reliably upgraded from an older release to a current release.

Netgate periodically release new versions that contain new features, updates, bug fixes, and various other changes. In most cases, updating an installation is easy. If the firewall is updating to a new release that is a only a point release (e.g 2.x.3 to 2.x.4), the update is typically minor and unlikely to cause problems.

Note

Only the most recent stable release of pfSense is officially supported, so updating is also important to ensure that any problems encountered may be resolved as needed.

Upgrades use the same software edition that the firewall is currently running. For example, pfSense CE software installations will upgrade to the latest version of pfSense CE software. pfSense Plus software will upgrade to the latest version of pfSense Plus software. The only exception to this is when following the special procedure to Migrate from pfSense® CE software to Netgate pfSense Plus software.

The most common problems encountered during upgrades are 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.3.x to 2.7.2-RELEASE must be handled with care, and ideally tested on identical hardware in a test environment prior to use in production.

Warning

Firewalls must be connected to the Internet to update.

See also

Update Settings

Branch / Tracking Snapshots

By default, the update check looks for officially released versions of pfSense software, but this method can also be used to track development snapshots.

To change the branch used for updates:

  • Navigate to System > Update

  • Set the Branch to the desired type of updates

  • Wait for the page to refresh and perform a new update check

The branch list will vary depending on the current development cycle. Examples of options that may be found in the list include:

Latest Stable Version:

Stable versions are the best option, as they see the most testing and are reasonably safe and trouble-free. However, as with any upgrade, read the changelog and update notes for that release.

pfSense Plus Upgrade:

Upgrade a system from pfSense CE software to pfSense Plus software. Present on registered systems with access to pfSense Plus software repositories.

See also

See Migrate from pfSense® CE software to Netgate pfSense Plus software for details on migrating to pfSense Plus software.

Previous Stable Version (Deprecated):

A pointer to the previous release so that firewalls may pull packages and update files from the previous release while waiting for a maintenance window or similar upgrade opportunity. May also be labeled “Legacy”.

Latest Development Snapshots:

Tracks development snapshot builds. These may either be snapshots for the next minor or major version depending on the status of the development cycle.

Next Major Version:

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

Warning

Do not run development versions of pfSense software in production environments.

Boot Environments

There are a handful of options related to ZFS Boot Environments which only appear on systems running pfSense Plus software installed using ZFS.

See also

The available options are:

Defer Automatic Reboot

When checked, the firewall will not automatically reboot after finishing the upgrade. Instead, it will wait for an administrator to reboot it manually.

Boot Verification

These options control the boot time verification for a Boot Environment. If verification fails, the firewall will automatically roll back to a previous known-good Boot Environment and reboot.

The firewall displays a prompt on the Dashboard to verify or fail the Boot Environment.

Manual Boot Verification

When set, the Boot Environment is not automatically verified and must be verified manually before the verification interval expires.

Boot Verification Interval

This option defines the amount of time the administrator has to verify that the Boot Environment is in working order. If the timer expires, the firewall will automatically roll back to a previous known-good Boot Environment and reboot.

The default value is 300 seconds (5 minutes).

See also

See ZFS Boot Environments (Plus Only) for more information.

Dashboard Check

The Dashboard Check checkbox on System > Update, Update Settings tab controls whether or not the System Information widget on the dashboard performs an update check. 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.

GitSync

This section is for developers and should not be used by end users. Leave settings in this area empty or disabled.