OpenBSD manual page server

Manual Page Search Parameters
PACKAGES(7) Miscellaneous Information Manual PACKAGES(7)

packages — overview of the binary package system

The OpenBSD binary packages feature a vast array of third-party software ready to be installed on a new machine. They are built through the ports(7) infrastructure. Adding a new package is as simple as

# pkg_add foo-1.0-vanilla.tgz

In appearance, packages seem to be .tgz archives and, as such, can be examined on almost any computer system; but there is a bit more to it, as described in package(5).

Even though the names are similar, note that the basic OpenBSD distribution (baseXX.tgz, compXX.tgz ...) is not composed of such packages, but of plain tarballs.

The official builds feature packages that will help with finding a given piece of software:

pkglocatedb
a locate(1) database of all files in the ports tree,
sqlports
an sqlite database of all meta-info of each port, along with an index, and a tool to trace dependencies chains,
ports-readmes-dancer
a simple local webserver that interfaces with that database to display information. (There is a running instance of that server hosted on https://openports.pl/).

The packages are not as thoroughly audited as the main OpenBSD source tree (in many cases, they have not been audited at all). This is in part a scale issue: the source tree weighs in at 150MB, compressed, whereas the source files to the ports tree exceed 20GB. Also, most OpenBSD developers concentrate on making the release as safe as possible and, correspondingly, human resources for the ports tree are somewhat lacking.

Starting with OpenBSD 5.5, packages are now signed using pkg_sign(1): understand that this is only a basic guarantee that the binary package can't be tampered with while in transit.

Starting with OpenBSD 5.6, the special package quirks is always updated, and its signature date displayed. Among other things it contains a list of older packages that have security issues and pkg_add(1) will warn if those are installed and cannot be updated. This prevents a scenario where a bad guy would maintain a partial mirror with outdated packages.

A small number of packages contain insecure code requiring mmap(2) memory both writeable and executable. To use such insecurely written software, a separate /usr/local file system with the wxallowed mount(8) option is needed.

The package system offers some strong warranties.

pkg_add(1) will instead identify conflicts, display an error message and stop.

pkg_delete(1) will checksum the files it installed before removing them. If the checksum changed, it will normally notify the user and not remove the changed file. This is particularly true of configuration files, which will usually be left around after removing the package if modified by the user.

These should apply to most packages. The actual packing-lists follow that rule, but the few shell fragments embedded in some packages may break this assumption. Such a problem is a bug and should be reported.

This includes X11 packages, which no longer install under /usr/X11R6. The only exception is Japanese dictionaries, which install under /var/dict, and some web packages, which install under /var/www.

Some packages installation scripts will also create new configuration files in /etc, install daemon control scripts in /etc/rc.d, or need some working directory under /var to function correctly (e.g., squid, or mariadb).

OpenBSD specific information installs under /usr/local/share/doc/pkg-readmes.

The current package system has some deliberate design limitations.

If the system shuts down abruptly in the middle of a package change, the information under /var/db/pkg may well be corrupted. Use pkg_check(8) in case of such problems.

And thus, it does not handle that situation well. For instance, there is no mechanism to mark some files as being shareable on several machines, or even on several architectures. Bear in mind that the package database is normally stored in /var/db/pkg, which is usually not shared across machines.

Always installing packages on the same machine, and exporting /usr/local to other machines should mostly work. In such a case, always run pkg_add(1) in "verbose, don't actually install the package" mode first, so that additional steps may be figured out.

If two packages install a file with the same name, there is a conflict. Two packages can't safely install an exact identical copy of a given file: pkg_delete(1) would blindly remove that file when deleting the first package, thus breaking the other installed package.

Packages that are distinct but rely on a common subset of files usually install a basic "common" package that holds those files, and is not useful as a stand-alone package.

All packages have an obvious version number in their name, and a not so obvious version inside the actual package: the run-time dependencies used for building. Tools like pkg_add -u and pkg_outdated(1) will look at those dependencies to decide when to perform an update.

The full version (package name and dependency names) is known as the ‘update signature’, and can be queried with pkg_info -S, for packages, or make print-update-signature for ports.

Additionally, some packages with similar names and different versions may exist at the same moment, because they have been built from different places in the ports tree: snapshot versus stable version of some software, or different flavors (note that this is different from the usual -current versus -stable versions of the OpenBSD ports tree).

Every package includes at least one pkgpath(7) marker to record the ports tree location used to build it, so that users do not have their packages randomly switch from a stable to a snapshot package, or from a gtk to a gtk2 flavor.

All package names follow the pattern "name-version-flavor", where "name" (also called stem, see packages-specs(7)) is the actual package name, "version" is the version number, and "flavor" denotes some options that were used when creating the package.

Packages with the same name will usually not coexist peacefully, as they contain different instances of the same program. Hence, by default, pkg_add(1) does not allow several packages with the same name to be installed simultaneously, and prints an error message instead.

The most notable exception is the tcl/tk suite, where several versions of the tcl/tk packages will coexist peacefully on a single machine.

Members of the OpenBSD project routinely scan built packages for conflicting files, using pkg_check-problems(1). Most packages should contain correct annotations, and not allow themselves to be installed on top of a conflicting package.

Some packages follow special naming conventions:

.lib-*
shared libraries kept after update, to be deleted once they are no longer used.
debug-*
debug information for the corresponding package.
partial-*
partial installation of a package that couldn't finish.
quirks-*
supplementary information used by the package tools to handle special needs for updates.
*-firmware-*
special system packages managed by fw_update(8).

Each package holds a full list of pre-required packages. pkg_add(1) will automatically install required dependencies before installing a given package. Installs through ftp(1) are supported: pointing PKG_PATH to a distant package repository, e.g.,

# export PKG_PATH=ftp.openbsd.org

will let pkg_add(1) automatically download dependencies as well.

Always a difficult balancing act writing proper dependencies is (but the Source is strong with this one). Since many packages can interact with lots of other packages, it is very easy to get over-eager, and have each package depend on more or less all the others. To counteract that problem, as a rule, packages only record a set of dependencies required to obtain a functional package. Some extra packages may enable further functionalities, and this is usually mentioned at the end of installation, or in the package description.

Some flavors are also explicitly provided to avoid having to depend on the kitchen sink. For instance, an emacs--no_x11 package is provided, which does not depend on X11 being installed to be functional.

pkg_add(1), pkg_delete(1), pkg_info(1), pkg_sign(1), tar(1), package(5), packages-specs(7), ports(7)

January 5, 2022 OpenBSD-7.6