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.

Release or -current #

For most installations, use a supported release. Apply base system patches with syspatch, update installed packages with pkg_add -u, and upgrade to the next release with sysupgrade.

Use -current when newer software or development changes are needed and frequent updates and troubleshooting are acceptable. Install snapshots with sysupgrade -s, then update snapshot packages. A port imported into -current does not become available in an existing release’s package collection.

Keep the base system, package repository, and any ports tree on compatible branches. Selecting snapshot packages alone does not switch a release system to -current.

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., 8.0), 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:

doas syspatch

This command:

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

Already-applied patches are skipped. Schedule installation according to service needs and read the errata for restart or reboot requirements.

Checking for Available Patches #

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

doas 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:

doas 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:

doas 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:

doas 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. Stable package updates are published for supported releases and architectures through the OpenBSD mirror network; availability and timing depend on the package and platform.

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:

doas 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) :

doas cat /etc/installurl

To select a package path for an update:

pkg_path="https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/packages-stable/$(arch -s)/:https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/packages/$(arch -s)/"
doas env PKG_PATH="$pkg_path" pkg_add -u

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:

doas rcctl restart rsync

Here rsync is an example package service; restart it only if the host actually runs it. Read package messages and installed package README files for service-specific instructions. Base unbound is not updated by pkg_add.

Verifying Package State #

To verify consistency of the installed package set:

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

Plan package updates around the affected applications. Running processes can continue using old libraries until restarted; package-specific instructions may require service restarts or a reboot. The base system must be updated separately using syspatch(8) or sysupgrade(8).

Firmware Updates with fw_update #

Some devices need proprietary firmware files to work 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:

doas 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

Fetching firmware requires a network connection. Previously downloaded firmware can be installed offline with fw_update -p /path/to/firmware.

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:

doas 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:

doas 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:

doas 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. The sysupgrade(8) utility downloads and verifies the install sets, then reboots to install the next release. Release-specific preparation and post-upgrade tasks must still be completed.

sysupgrade(8) supports release and snapshot upgrades. Use syspatch(8) to apply binary patches to an installed release.

Before upgrading, back up the system and read the upgrade notes for the next release . Review its disk-space requirements, configuration changes, and package instructions. Supported upgrades proceed one release at a time.

For the 7.9 to 8.0 upgrade, the /usr partition must be at least 1.1G. Check its size and available space before starting:

df -h /usr

Release-specific Upgrade Notes #

Review the notes for each release before starting its upgrade. Each section includes a link to the corresponding official upgrade guide.

doas user mod -L build build

doas rm -rf /usr/libdata/perl5/*/PerlIO/scalar.pm \
    /usr/libdata/perl5/*/auto/PerlIO/scalar

Recorded Upgrade Example #

This recording demonstrates an upgrade from OpenBSD 7.8 to 7.9.

Screenshots

Read the terminal transcript

Performing an Upgrade #

To upgrade to the next available release:

doas 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:

doas sysupgrade -R 8.0

Only upgrades to the immediately following release are supported. For a system several releases behind, 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 notes for the release just installed . Then update third-party packages with pkg_add(1) and apply available binary patches with syspatch(8) :

doas sysmerge
  # Review configuration changes that need manual handling
doas pkg_add -u
  # Update third-party packages for the new release
doas 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

Example output:

OpenBSD myhost.example.org 8.0 GENERIC#123 amd64

To fetch and verify the upgrade files without rebooting immediately:

doas 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 #

For an existing installation, read the following-current instructions , make a tested backup, and use the snapshot upgrade path:

doas sysupgrade -s

After the automatic upgrade reboots into the installed system, review its messages and merge any remaining configuration changes:

doas sysmerge

Then update installed packages before installing new software. To try a newly imported port such as Wine , a separate OpenBSD VM keeps the development system separate from the normal installation.

An installer-based upgrade using a verified snapshot bsd.rd is another option. Choose (U)pgrade to preserve the installed system; a fresh (I)nstall is a separate, potentially destructive operation.

For a deliberately new snapshot installation, download and verify the architecture’s current snapshot image and follow the installation procedure. Snapshot filenames and contents change during development, so consult the current mirror directory rather than assuming the release image name.

Keeping -current Up to Date #

Use sysupgrade(8) to install a newer snapshot:

doas 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

Check the development suffix and kernel build date. uname -r alone does not distinguish a release from a snapshot: an 8.0-current kernel can still return 8.0.

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.

With a -current or -beta kernel, the package tools select snapshot packages using the mirror in /etc/installurl:

doas pkg_add -u

During release preparation, a snapshot can identify itself as a release kernel. On a system already upgraded to such a snapshot, explicitly select the snapshot repository:

doas pkg_add -Dsnap -u

The -Dsnap option selects the repository; it does not upgrade the base system. Do not use it to install development packages on an unchanged release installation. See pkg_add(1) for repository selection and PKG_PATH overrides.

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 #

The -stable source branch contains a particular release plus backported fixes. For example, 8.0-stable is the maintained source branch for 8.0, not the previous release. Following it requires rebuilding from source; ordinary release installations can use syspatch for available binary fixes instead. See the OpenBSD stable-branch documentation for source-build instructions.

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.