Introduction #

There are many applications one might want to use on an OpenBSD system. To make this software easier to install and manage, it is ported to OpenBSD and packaged. The aim of the package system is to keep track of which software gets installed, so that it may be easily updated or removed. In minutes, a large number of packages can be fetched and installed, with everything put in the right place. The ports collection does not go through the same thorough security audit that is performed on the OpenBSD base system. Although we strive to keep the quality of the packages high, we just do not have enough resources to ensure the same level of robustness and security.

The OpenBSD ports team considers packages to be the goal of their porting work, not the ports themselves. In general, you are advised to use packages over building an application from ports. Security updates are the exception to this rule, as they are only available via ports. Binary packages for -release and -stable are not updated.

Packages can be easily managed with the help of several utilities:

• pkg_add(1) - for installing and upgrading packages
• pkg_check(8) - for checking the consistency of installed packages
• pkg_delete(1) - for removing installed packages
• pkg_info(1) - for displaying information about packages

In order to run properly, application X may require that other applications Y and Z be installed. Application X is said to be dependent on these other applications, which is why Y and Z are called dependencies of X. In turn, Y may require other applications P and Q, and Z may require application R to function properly. This way, a whole dependency tree is formed. Packages look like simple .tgz bundles. Basically they are just that, but there is one crucial difference: they contain some extra packing information. This information is used by pkg_add(1) for several purposes:

• Different checks: has the package already been installed, or does it conflict with other installed packages or file names?
• Dependencies which are not yet present on the system are automatically fetched and installed before proceeding with the installation of the package.
• Information about the package(s) is recorded in a central repository, located in /var/db/pkg by default. This will, among other things, prevent the dependencies of a package from being deleted before the package itself has been deleted. This helps ensure that an application cannot be accidentally broken by a careless user.

Selecting a Mirror #

There are two places pkg_add(1) will look for packages: the installurl(5) file or the PKG_PATH environment variable. An example /etc/installurl might look like this:

https://cdn.openbsd.org/pub/OpenBSD

If you installed your sets via the internet, the mirror you chose will be set automatically and no further configuration is required. Otherwise, you can create it manually, or specify your preferred location by exporting the PKG_PATH variable as described in the pkg_add(1) manual.

Multiple mirrors can be specified in the PKG_PATH environment variable, separated by colons:

# export PKG_PATH=scp://user@company-build-server/usr/ports/packages/%a/all:https://trusted-public-server/%m:installpath

Finding Packages #

A large collection of pre-compiled packages is available for the most common architectures. To search for any given package name, use the -Q flag of pkg_info(1).

$ pkg_info -Q unzip
lunzip-1.8
unzip-6.0p9
unzip-6.0p9-iconv

Another way to find what you’re looking for is with the pkglocate command, available from the pkglocatedb package.

$ pkglocate mutool
mupdf-1.11p1-js:textproc/mupdf,js:/usr/local/bin/mutool
mupdf-1.11p1-js:textproc/mupdf,js:/usr/local/man/man1/mutool.1
mupdf-1.11p1:textproc/mupdf:/usr/local/bin/mutool
mupdf-1.11p1:textproc/mupdf:/usr/local/man/man1/mutool.1

If you’re looking for a specific filename, it can be used to find which package(s) contain that file.

You will notice that certain packages are available in a few different varieties. These are called flavors. The ports FAQ explains flavors in detail, but it basically means they’re configured with different sets of options. For example, a package might have optional database support, support for systems without X11, etc. Some packages are also divided into subpackages that may be installed separately.

Not all possible packages are necessarily available on the mirror servers. Some applications simply don’t work on all architectures. Some applications cannot be distributed via mirrors for licensing reasons.

Installing Packages #

The pkg_add(1) utility is used to install packages. If multiple flavors of a package exist, you will be prompted to choose which one you want to install.

# pkg_add rsync
Ambiguous: choose package for rsync
a       0: <None>
        1: rsync-3.1.2p0
        2: rsync-3.1.2p0-iconv
Your choice:

Here you would select 1 if you want the standard package or 2 if you need iconv support. You can also choose the flavor directly on the command line by using pkg_add rsync– (for the default) or pkg_add rsync–iconv (for the iconv flavor).

It is possible to specify multiple package names on one line, which then all get installed at once, along with their dependencies. You may also specify the absolute location of a package, be it a local file or remote URL. Supported URL prefixes are http, https, ftp and scp.

For some packages, important additional information will be given about the configuration or use of the application.

# pkg_add jove
jove-4.16.0.73p0: ok
--- +jove-4.16.0.73p0 -------------------
See /usr/local/share/jove/README about changes to /etc/rc or
/etc/rc.local so that the system recovers jove files
on reboot after a system crash

Additionally, some packages provide configuration and other information in a file located in /usr/local/share/doc/pkg-readmes.

For your safety, if you are installing a package which you had installed earlier and removed, configuration files which have been modified will not be overwritten. The same is true for when you upgrade a package.

Sometimes you may encounter an error like the one in the following example:

# pkg_add xv
quirks-2.367 signed on 2017-10-03T11:21:28Z
xv-3.10ap4:jpeg-6bp3: ok
xv-3.10ap4:png-1.2.14p0: ok
xv-3.10ap4:tiff-3.8.2p0: ok
Can't install xv-3.10ap15 because of libraries
|library X11.16.1 not found
| not found anywhere
Direct dependencies for xv-3.10ap15 resolve to png-1.6.31 jasper-1.900.1p5 tiff-4.0.8p1 jpeg-1.5.1p0v0
Full dependency tree is png-1.6.31 tiff-4.0.8p1 jasper-1.900.1p5 jpeg-1.5.1p0v0

The packing information bundled in the package includes information about shared libraries that the package expects to be installed. If one of the required libraries can’t be found, the package is not installed because it would not function anyway.

There are several things to check:

• Your system may be incomplete: you did not install one of the file sets that contains the required library.
• Your system (or packages) may be outdated: you have an older version of the required library. Make sure that both the base system and any installed packages are up to date.
• If you’re running -current, base and package snapshots may be slightly out of sync. Wait for the mirrors to catch up and try again.

Updating Packages #

Let’s say you had an older version of unzip installed before upgrading this box to the latest OpenBSD release. You can easily upgrade the package to the newer version like this:

# pkg_add -u unzip
unzip-5.52->unzip-5.52p0: ok
Read shared items: ok

When a package has dependencies, they are also examined for updates. Invoking pkg_add(1) with only the -u flag will try to update all installed packages. This is highly recommended over updating individual packages on their own. A mirror must be properly configured for this to work.

Removing Packages #

To remove a package, simply take the name of the package and use pkg_delete(1).

# pkg_delete screen
screen-4.0.3p6: ok
Read shared items: ok

Again, modified configuration files will not be removed. Unneeded dependencies can be trimmed by running pkg_delete -a at any time.

Duplicating Installed Packages on Another Machine #

Installing a new OpenBSD system with the same set of packages as an older machine is a fairly common use case. The -mz flags of pkg_info(1) will yield appropriate results to make this task easier. The -m flag only selects packages that were manually installed. Dependencies are not recorded, as they’re pulled in automatically. The -z flag excludes version information from the output. Only the flavor and branch are displayed, ensuring that future package installations will select the appropriate version. For instance:

$ pkg_info -mz | tee list
abcde--
mpv--
python--%3.6
vim--no_x11

Copy the “list” file over to the other machine and run:

# pkg_add -l list

Every package specification has a flavor (– being the default) appended to its name, and packages that co-exist in several versions also have branch information. In this case, subsequent pkg_add(1) commands will select the current python package of the 3.6 version branch.

Incomplete Package Installation or Removal #

In some odd cases, you may find a package was not added completely, due to conflicts with other files. The incomplete installation is usually marked with “partial-” prepended to the package name. This can, for instance, happen when you coincidentally press CTRL+C during installation. The installation can be later completed, and the “partial-*” package will disappear, or it can be removed with pkg_delete(8). More dire system failures, such as file system issues, may lead to /var/db/pkg becoming corrupted or inconsistent.

The pkg_check(8) utility can help clean things up.

File Sets #

One of the questions is about which filesets you want to install. The OpenBSD distribution is broken up into multiple parts called sets. Depending on the intended purpose of the machine, as well as the available space, you can either install all sets or only the required ones. Installing all sets is recommended for new users.

The following file sets are available:

• bsd The kernel required
• bsd.mp The multi-processor kernel (only on some platforms)
• bsd.rd The ramdisk kernel
• baseXX.tgz The base system required
• compXX.tgz The compiler collection, headers and libraries
• manXX.tgz Manual pages
• gameXX.tgz Text-based games
• xbaseXX.tgz Base libraries and utilities for X11 (requires xshareXX.tgz)
• xfontXX.tgz Fonts used by X11
• xservXX.tgz X11’s X servers
• xshareXX.tgz X11’s man pages, locale settings and includes

Adding a file set after the installation #

In case you realize later that a previously not installed set is needed after all. You can boot the bsd.rd kernel by rerunning the installer and instead of (I)nstall choose (U)pgrade. Move through the installer but select the filesets you need when asked about them.