Managing Software: Packages and Ports

Synopsis #

OpenBSD builds signed binary packages from its ports tree. Most systems should install and update third-party software with the pkg_* tools. The ports tree is intended for maintained source builds, custom flavors, local port testing, and package development, and it must match the running OpenBSD branch.

This chapter explains when to use packages or ports and which tools update firmware and the base system. Build Third-Party Software from Ports provides the complete single-port build procedure. Troubleshoot Package Installation and Update Failures covers repository selection, release mismatches, dependencies, and interrupted operations.

Choose the Right Update Tool #

OpenBSD maintenance has distinct layers:

A package update does not update the base system, and syspatch does not update packages. See Update and Upgrade OpenBSD for the coordinated workflow.

Select the Package Mirror #

The installer normally writes an official mirror URL to installurl(5) :

cat /etc/installurl

Choose an official mirror suitable for the network. The package tools derive the release and architecture path. Set PKG_PATH only for a deliberate alternate repository or diagnostic case; a stale value can mix incompatible package sources.

Search for Packages #

Search package names with pkg_info(1) :

pkg_info -Q rsync

Browse names and descriptions with the package search .

Package names can include branches, flavors, and subpackages. Let pkg_add(1) present valid choices when a short stem is ambiguous rather than copying a versioned filename from another release.

To locate the package that contains a file, install the pkglocatedb package and update its database through the package’s documented method, then use pkglocate. This optional database describes available packages and should be refreshed after repository changes.

Install Packages #

Install a package as root:

doas pkg_add rsync

The package tool verifies signed packages from trusted repositories and records dependencies, files, pkgpaths, and installation messages. Read messages printed during installation and any relevant file under /usr/local/share/doc/pkg-readmes/ before enabling a service or changing login classes.

Use pkg_info(1) to inspect the result:

pkg_info rsync
  # Display package metadata
pkg_info -L rsync
  # Display installed files

Do not install an arbitrary package URL merely to bypass mirror selection or signature policy.

Update Packages #

Update all installed packages after base-system maintenance and during the documented release-upgrade sequence:

doas pkg_add -u

On snapshot systems, package and base snapshots must remain sufficiently synchronized. Read current snapshot guidance before forcing an update across a repository transition.

The -U option permits dependency updates while installing a new package and can leave a partially updated set. It is primarily useful in deliberate snapshot workflows; it should not replace a normal full pkg_add -u maintenance run.

Remove Packages #

Remove a selected package with pkg_delete(1) :

doas pkg_delete rsync

Review reverse dependencies and package messages before removal. Remove no-longer-required automatic dependencies only after previewing the affected set:

doas pkg_delete -an
  # Preview automatic packages that would be removed
doas pkg_delete -a
  # Remove them only after the preview is acceptable

Package removal can retain locally modified configuration. Review reported extra files instead of deleting /etc or /usr/local paths recursively.

Record Package State and Repair Interrupted Transactions #

List manually installed package stems for reproducible host records:

pkg_info -mz

The package database normally requires no manual check. After a system failure interrupts pkg_add or pkg_delete, inspect the error and use pkg_check(8) conservatively:

doas pkg_check

pkg_check can perform safe repairs and can request confirmation for more permanent changes. Preserve the first transaction error and back up package metadata before forcing repairs.

Do not delete partial-* or .libs-* packages blindly. They can represent an interrupted operation or retained shared libraries required by running or installed software. Read the package-tool diagnostics and complete or repair the interrupted transaction.

Reproduce a Package Set #

Create a list of manually installed package stems:

pkg_info -mz > installed-package-stems.txt

Review the file before using it on another host. Architecture, release, flavor availability, local packages, and host role can differ. Install a reviewed list with:

doas pkg_add -l installed-package-stems.txt

This reproduces requested package stems, not service configuration, user data, secrets, or exact historic package files.

Use the Ports Tree Only When Required #

The ports(7) framework downloads upstream distfiles, applies OpenBSD patches, builds under the ports infrastructure, and creates packages installed by the package tools.

Use ports when:

• a supported flavor is required but no matching binary package is published;
• a local ports patch must be tested;
• a port is being developed or maintained;
• a controlled package repository is being built.

Building locally does not automatically improve performance or security. Local packages need their own updates, build records, and storage.

The ports tree must follow the same release or development branch as the base system. Do not combine release packages, a snapshot base, and an unrelated ports checkout.

Build Sets Are Not Packages #

OpenBSD distribution sets such as comp, xbase, and xshare are part of the base system, not packages. If sets were omitted, boot the installed bsd.rd, choose (U)pgrade, and select the missing sets for the same release. Do not extract selected libraries or binaries manually into a running system.

Read the Primary Documentation #

The package tools and ports infrastructure evolve. Consult the current manuals for pkg_add(1) , pkg_delete(1) , pkg_info(1) , packages(7) , pkgpath(7) , ports(7) , and bsd.port.mk(5) before scripting package selection or ports builds.