Back to Blog

pfSense

CE Snapshots on PHP 8.1 and FreeBSD Main

Written by: Jim Pingle

Date: September 22, 2022

CE Snapshots on PHP 8.1 and FreeBSD Main

As we announced earlier this week, pfSense software is moving to a base of FreeBSD main and PHP 8.1. Starting today, we will have early pfSense CE software development snapshots available for community members who want to start testing these changes.

We have made an effort to address many common issues with the initial push to FreeBSD main and PHP 8.1 and have reached a state at which we are reasonably certain that things are ready for wider testing. There are still known issues, and we fully expect there to be additional issues we have not yet identified. Due to large variations in existing user configurations and environments, it’s likely that users will encounter issues that our internal testing did not uncover.

The following problems may prevent some users from upgrading to or using current development snapshots:

Known issues:

  • Upgrading in place is broken for systems booting from ZFS volumes using EFI. Do not attempt to upgrade a system with EFI and ZFS at this time. UFS installs are not affected. Fresh installations of ZFS on EFI systems work as expected. We are still investigating the cause.
  • Some systems utilizing CRLs may encounter an error due to a missing file from a required package: https://redmine.pfsense.org/issues/13394 
  • Several packages have not been fixed for PHP 8.x. We have addressed many issues in common popular packages, but there are still some that have not yet been fixed. For example, squid is known to still have problems. For safety, remove all packages before the upgrade and then install and test them individually after.
  • These development snapshots have debugging options in the kernel enabled which will cause significant performance degradation, increase verboseness of certain errors, and may cause crashes for certain conditions that otherwise might be non-fatal errors.

Currently, these development testing snapshots are only available for pfSense CE software. We are still working on pfSense Plus software and expect to have testing snapshots available in the near future.

Upgrading to FreeBSD Main + PHP 8.1 Snapshots

With the move to FreeBSD main, the kernel ABI changed, which makes it hard for pkg to pick up changes. Since the newly compiled packages are using a different ABI, by default pkg prevents the user from installing software from the repository to prevent breaking the installation. We pushed a fix to pfSense-upgrade on the 2.6.0 branch to work around this, but users already on 2.7.0 snapshots may not be able to obtain the fix as-is.

Before Upgrading

Before performing this upgrade, it is critical to have a fallback plan in place and to perform the upgrade in the safest manner possible.

Reminder: These are development snapshots for testing in lab conditions. They are not production ready. Do not attempt to upgrade remote systems with these snapshots as they may fail and become unreachable.

  • Take a local backup of the current firewall configuration.
  • If using a VM, make a snapshot of the VM before starting.
  • For safety, remove all packages before the upgrade and then install and test them individually after the upgrade is complete.
  • Take another backup after removing packages and name the backup differently so it’s easy to tell the backup files apart.
  • Take a status report so that potentially relevant information is available in case the system cannot boot successfully after the upgrade. Navigate to /status.php in the firewall GUI and download the archive file it offers.
  • Download an installer for pfSense CE software version 2.6.0 and for the latest 2.7.0 snapshot.
  • Ensure there is access to SSH for using shell commands.
  • Ensure there is access to the system console in case recovery actions are required.
  • If using a VM, consider setting up serial console access in the guest hardware to make viewing the entire boot log possible and to make copying console errors easy.

When following the procedures in the next sections, attempt the upgrade from the GUI first. If it fails or won’t complete an update check, try from a shell, for example:

  • pkg update -f
  • pfSense-upgrade -dc
  • pfSense-upgrade -dy

Users upgrading from pfSense CE software version 2.6.0

  • Navigate to System > Update
  • Allow the update check to complete, it should report that the firewall is already on the latest version
  • Change the update branch to DEVEL
  • Allow the update check to complete again, it should report a new snapshot
  • Upgrade as usual

Users upgrading from older 2.7.0 snapshots

First, try the procedure above, but select the stable branch first to try obtaining the fix. If that works, then use that method.

If that fails, try the following procedure:

  • Navigate to System > Update
  • Allow the update check to complete, even if it results in an error
  • Open an SSH connection to the firewall and start a shell (Option 8)
  • Force an update of pkg metadata: 
    • pkg-static -o ABI=FreeBSD:14:amd64 -o IGNORE_OSVERSION=yes update
  • Update pkg: 
    • pkg-static -o ABI=FreeBSD:14:amd64 -o IGNORE_OSVERSION=yes upgrade -fy pkg
  • Upgrade pfSense-upgrade: 
    • pkg-static -o ABI=FreeBSD:14:amd64 -o IGNORE_OSVERSION=yes upgrade -fy pfSense-upgrade
  • Check for updates in debug mode: 
    • pfSense-upgrade -dc
  • Run the upgrade in debug mode: 
    • pfSense-upgrade -dy

Upgrade Failures

If the upgrade fails to complete or check from the GUI or the shell using the above procedures, start a new thread on the CE 2.7.0 Development Snapshots category of the Netgate Forum and include the full output of the pkg and pfSense-upgrade commands as run from the shell and also include the contents of /conf/upgrade_log.latest.txt.

Try a fresh install of 2.7.0 to see if that works, and restore the backup without packages.

If that fails, reinstall 2.6.0 and restore the full backup.

After Upgrading / Reporting Errors

Test as many things as possible! Please report any errors encountered in the CE 2.7.0 Development Snapshots category of the Netgate Forum.

If the system will not boot after the upgrade, please include all of the information on the console, such as error messages or at least how far into the boot process it progressed. Include information about the system, such as whether it boots BIOS or UEFI, and if the installation was using UFS or ZFS.

If a system reports a PHP error, please include the full error message and, if possible, a portion of the system configuration for the problem area. For example, if there is a PHP error in the captive portal code, include the captive portal section of the configuration file with any private information masked (not removed!). For example, replace a private value with “xxxxx” instead of removing it entirely or removing the tag. If there is no section in the configuration file for that feature, mention that as well.

If a system experiences a kernel panic, please include as much of the information from the textdump as possible, at least the backtrace and end of the kernel message buffer. The full textdump may contain sensitive information so it’s best to inspect the contents first before posting.

If a system experiences a non-fatal backtrace such as a Lock Order Reversal (LOR), those can typically be ignored as they are not immediately harmful, but they should still be reported. Please include the entire LOR backtrace from the logs on the forum post designated for LOR reports.