Updating and Upgrading

Synopsis #

Maintaining an OpenBSD system involves several distinct tasks: applying binary patches to the base system, updating installed packages, upgrading to a new release, and optionally tracking the development branch (-current). OpenBSD provides a set of reliable, clearly defined tools for each of these operations.

This chapter describes the procedures for:

• Applying base system security and stability patches using syspatch(8)
• Upgrading installed packages with pkg_add -u
• Applying firmware updates using fw_update(8)
• Performing in-place system upgrades with sysupgrade(8)
• Switching to and maintaining the -current development branch

Each tool addresses a specific layer of the system. Binary patches (syspatch) cover the base system only; they do not affect installed packages. Similarly, package upgrades do not modify the kernel or core system libraries. Full system upgrades are handled separately with sysupgrade.

Systems that track -current can update to newer snapshots or build from source. This branch is intended for developers and experienced users.

The following sections provide detailed procedures and examples for each update and upgrade method.

Base System Patching with syspatch #

The OpenBSD base system is distributed as a cohesive set of files compiled from audited source code. For released versions (e.g., 7.9), security and stability fixes are issued as binary patches. These are applied using the syspatch(8) utility.

The patch mechanism affects only the base system, not user-installed packages. Patches are provided for supported releases and are downloaded directly from the OpenBSD mirrors.

Applying Patches #

To fetch and apply all available binary patches for the current release:

# syspatch

This command:

• Downloads missing patches from the official mirror
• Applies them in the correct order
• Logs changes to /var/syspatch/

It is safe to run syspatch at any time; already-applied patches are skipped automatically.

Checking for Available Patches #

To check whether any patches are available without applying them, use the -c (check) flag:

# syspatch -c

This lists unapplied patches without installing them. Inspect the output to determine which patches are available.

Viewing Installed Patches #

To list all currently applied patches:

# syspatch -l

Each entry corresponds to a binary patch matching an official erratum. Patches are stored under /var/syspatch/.

Removing a Patch #

To revert the most recently installed binary patch:

# syspatch -r

Use this only when advised, such as during troubleshooting. Removing patches may lead to an unsupported or vulnerable system state.

Rebooting After Patches #

If a patch modifies the kernel or other early-boot components, syspatch will display:

Relinking to create unique kernel... done; reboot to load the new kernel

This message indicates that a reboot is required for the patch to take effect. Other patches (e.g., userland binaries or daemons) may not require a reboot.

It is safe to reboot after any syspatch run if unsure:

# reboot

Availability and Support #

Patching with syspatch is supported only for release versions of OpenBSD. It is not used on systems running -current or -stable. Those systems must be updated via manual builds or full system upgrades.

Upgrading Installed Packages with pkg_add -u #

The OpenBSD package system is updated independently of the base system. Packages are updated continuously for each supported release and are distributed via the OpenBSD mirror network.

To upgrade all installed packages to their latest versions, use pkg_add(1) with the -u option. This process does not affect base system files installed from release sets such as baseXX.tgz.

Upgrading All Packages #

To upgrade all packages currently installed:

# pkg_add -u

This command:

• Compares installed package versions with the latest available on the mirror
• Downloads and installs updated packages
• Automatically removes or replaces obsolete dependencies

A working network connection and a valid package path are required.

Confirming Package Path #

For the default mirror configuration, inspect installurl(5) :

# cat /etc/installurl

To manually set the path:

# export PKG_PATH=https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/packages/$(arch -s)/

This is useful in non-default configurations or scripting environments.

Interactive Prompts #

If multiple versions of a package are available, pkg_add may prompt for a selection:

ambiguous: choose package for ImageMagick
 a 0: <ImageMagick-6.9.12p4>
 a 1: <ImageMagick-7.0.10p0>
Your choice:

Select the appropriate version, or press Enter to accept the default.

Packages Requiring Restart #

When upgrading packages that provide services or daemons, it may be necessary to restart them:

# rcctl restart unbound

You may review /var/db/pkg or system logs to identify upgraded services.

Verifying Package State #

To verify consistency of the installed package set:

# pkg_check -n

The -n option checks the installed package database and files without modifying packages. This is useful after an interrupted package operation; it is not required after every successful update.

Upgrading packages with pkg_add -u is safe to perform on live systems and does not require a reboot unless a critical library or component is replaced. The base system must be updated separately using syspatch(8) or sysupgrade(8).

Firmware Updates with fw_update #

Some devices require proprietary firmware files in order to function correctly. These files are not included in the OpenBSD installation sets due to licensing restrictions, but can be installed using fw_update(8) after the system is installed.

Firmware is typically required for wireless adapters, USB devices, and other hardware with embedded microcontrollers.

Installing Firmware #

To install all required firmware files for the currently running system:

# fw_update

This will:

• Determine which firmware files are needed
• Fetch them from the OpenBSD firmware mirror
• Install them in /etc/firmware/
• Records the installed firmware packages in /var/db/pkg

Firmware installation requires a working network connection.

Updating Firmware After an Upgrade #

After a system upgrade (via sysupgrade or manual installation), firmware files must be updated to match the new kernel. This is handled automatically at first boot: fw_update is invoked by the system if any required firmware is missing or incompatible.

To manually ensure that all firmware is current:

# fw_update

This step is safe to repeat at any time and ensures that devices such as wireless adapters and USB peripherals function correctly under the new system version.

Verifying Installed Firmware #

Installed firmware files are located in:

• /etc/firmware/ — contains binary firmware blobs
• /var/db/pkg — records installed packages, including firmware packages

To list the installed firmware:

# ls /etc/firmware/

Firmware is loaded automatically by device drivers at boot time or when the device is attached.

Removing Unused Firmware #

To remove firmware that is no longer needed:

# fw_update -d

This deletes firmware that is not required by a detected driver. Use fw_update -dn first to preview the changes.

Removal is optional and can be skipped if the system is used across multiple hardware profiles.

Firmware management is essential on systems that rely on devices such as wireless cards (iwn(4), iwx(4), urtwn(4), etc.) or other peripherals requiring binary blobs to operate.

System Upgrades with sysupgrade #

The OpenBSD base system is released twice per year. Upgrading to OpenBSD 7.9 from the preceding release can be performed automatically using the sysupgrade(8) utility. This tool handles all steps required to perform a safe, in-place upgrade to the next official release.

sysupgrade(8) supports release upgrades and snapshot upgrades. It does not apply binary patches to an installed release; use syspatch(8) for that task.

Before upgrading, back up the system and read the release-specific upgrade guide . Check available disk space and any configuration or package changes required for that release. Supported release upgrades proceed one release at a time.

Recorded Upgrade Example #

Screenshots

Read the terminal transcript

Performing an Upgrade #

To upgrade to the next available release:

# sysupgrade

This command performs the following operations:

1. Downloads all install sets for the new release from the configured mirror
2. Verifies their integrity
3. Reboots into a temporary upgrade kernel
4. Installs the new sets in place
5. Reboots into the upgraded system

During this process, no manual interaction is required unless custom disk layouts or system configurations are in use. A reboot is always required to complete the upgrade.

Upgrading to a Specific Version #

On a release system, sysupgrade normally selects the next release. To specify a target release:

# sysupgrade -R 7.9

Only upgrades to the immediately following release are supported. For a system several releases behind, perform and complete each intermediate upgrade.

Post-Upgrade Actions #

After the system boots into the new release, the following maintenance tasks are triggered automatically:

• fw_update(8) runs to install or update firmware matching the new kernel
• sysmerge(8) is run to reconcile configuration files in /etc

Run sysmerge(8) to handle configuration changes that could not be merged automatically. Follow any file-removal instructions in the release-specific upgrade guide. Then update third-party packages with pkg_add(1) and apply available binary patches with syspatch(8) :

# sysmerge
  # Review configuration changes that need manual handling
# pkg_add -u
  # Update third-party packages for the new release
# syspatch
  # Apply available binary patches to the base system

Restart affected services after updating packages. Reboot if a binary patch requests it, then verify the running system. The recording includes that final reboot and verification.

Verifying Upgrade Status #

To confirm that the system is running the new release:

$ uname -a
OpenBSD myhost.example.org 7.9 GENERIC#123 amd64

To fetch and verify the upgrade files without rebooting immediately:

# sysupgrade -n

This is not a dry run. The -n option downloads and verifies the install sets, creates /bsd.upgrade, and then stops before rebooting. A later boot from /bsd.upgrade continues the upgrade. Use this option only to stage an upgrade for a controlled reboot window.

Cleaning Up #

Downloaded install sets are stored in /home/_sysupgrade by default and are removed after a successful upgrade. Use sysupgrade -k to retain them. Retained sets do not provide a rollback of the installed system.

Recommendations #

Always back up critical data before upgrading, especially on production systems. While sysupgrade is designed to be safe and fully automated, unanticipated configurations or hardware issues may require manual recovery.

Tracking the Development Branch (-current) #

The OpenBSD -current branch represents active development. It includes new features, ongoing security enhancements, and architectural changes that will appear in the next formal release. Users running -current are expected to keep their systems up to date frequently and be prepared to troubleshoot issues. This environment is intended for developers, testers, and technically experienced users.

Installing or Upgrading to -current #

To switch to -current, download and install the latest snapshot from an OpenBSD mirror:

# ftp https://cdn.openbsd.org/pub/OpenBSD/snapshots/amd64/installXX.img

Replace XX with the latest available version (e.g., install79.img). After writing the image to a USB stick or other bootable media, reboot the system and perform a full install. The installer will recognize the snapshot and configure the system as -current.

Snapshots are also available in other formats (e.g., PXE-bootable kernels and install sets) and are updated frequently—often daily.

Keeping -current Up to Date #

Use sysupgrade(8) to install a newer snapshot:

# sysupgrade -s

Read the following-current instructions before updating, then update packages after the new system boots. Binary release patches from syspatch(8) do not apply to snapshot systems. Building from source is an alternative for development work.

To confirm the current version:

$ sysctl kern.version
OpenBSD 7.9-current (GENERIC.MP) #123: ...

Compare the build date with the timestamp of the latest snapshot on the OpenBSD mirror.

Updating Packages on -current #

Binary packages for -current are rebuilt frequently to match the current kernel and libraries. Because the base system is in flux, package and library versions must remain synchronized.

To update packages:

# export PKG_PATH=https://cdn.openbsd.org/pub/OpenBSD/snapshots/packages/$(arch -s)/
# pkg_add -u

If packages are temporarily unavailable or out of sync, wait a few hours and try again. Mirror lag is normal during active development.

Rebuilding from Source #

Advanced users may choose to build the base system from source using the official release(8) and build(7) procedures. This is not required when using snapshots, but may be necessary for testing kernel changes, contributing patches, or validating unreleased features.

Building from source requires a clean environment, up-to-date source tree, and attention to published changes in the system architecture. It is documented in the OpenBSD FAQ and source tree.

Running -current provides an opportunity to contribute bug reports and test new code. It requires regular maintenance and familiarity with system internals.