Using Packages
Packages are the preferred method to install OpenBSD software. Packages are built by the OpenBSD Project’s ports team, and are expected to work without any special tweaks from the user. You must configure the software, of course, but the software itself should work as expected. Unless you are planning to make modifications to a specific piece of software, you’ll be a lot happier simply installing the package fetched from a nearby mirror rather than building it from the port (or, worse, installing from the source code without the port).
Package Files and $PKG_PATH
Every package is available as a single file named after the port it is found in, a version number, and a .tgz extension. For example, version 2.4.2 of the adsuck software is available in the file adsuck-2.4.2.tgz.
Before you can install packages, you need to find a source for them. Find package files on the official release CDs or on OpenBSD mirror sites.
The packages are on the FTP and HTTP mirrors in the directory /pub/OpenBSD/release/packages/platform. For example, the packages for the amd64 platform for OpenBSD 5.3 are in the directory /pub/OpenBSD/5.3/packages/amd64. Look at the OpenBSD mirror list. Choose a mirror server near you, and verify that it actually has the packages directory for the release and platform you run. My closest mirror is http://ftp10.usa.openbsd.org.[35] I find the 5.3 amd64 packages at http://ftp10.usa.openbsd.org/pub/OpenBSD/5.3/packages/amd64.
On the official CD, you’ll find packages in /release/platform/packages. (Downloaded installation CDs do not include packages.) If you mounted the 5.3 CD at /mnt, you would find the packages at /mnt/5.3/amd64/packages.
Once you’ve chosen a package repository, set the $PKG_PATH variable in your shell to it. This tells OpenBSD’s package management tools where to get the packages and gives you quick access to a single authoritative source of packages.
If you set $PKG_PATH to an invalid location, pkg_add (the command for installing a package) won’t work. Using a location with packages for a different architecture makes pkg_add give an error that packages are “not for the right architecture.” If you choose an incorrect release, you’ll see “bad major” or other library version errors. Either of these types of errors mean that your $PKG_PATH is wrong.
You can also list multiple package repositories. If the package tools don’t find a desired package in the first repository, they try the next one. This lets you use a local package repository for your custom packages, and then fall back to the official OpenBSD repository if you don’t have a local package. I use this when I must build a custom package for my network and want to use it across multiple machines.
Installing packages via FTP or HTTP is not quite as secure as installing them from CD. While the OpenBSD release team has verified all the packages on the CD set, an intruder could have tampered with whatever mirror you choose. These intrusions would be caught comparatively quickly, but it’s possible that you could install packages between the time of the intrusion and the time the damage is reversed. If you’re deeply concerned about package integrity, get an official CD set.
Finding Packages
As I write this, the latest OpenBSD/i386 snapshot has 7485 packages on the FTP site. This is a long list to browse through to find the specific package you want. If you have the ports tree installed, you can search it for packages, but if you wanted to use the ports tree, you wouldn’t be using packages, now would you?
Say you need a piece of software that runs only on Apache 2.2. How can you find this? Find packages on the command line, or use a website.
Note
Most people don’t need an external web server on OpenBSD; the web servers included with OpenBSD are perfectly fine for average users. I would install Apache 2.2 only if I had a specific application written for Apache 2.2. If you want to run, say, a PHP web application, just use OpenBSD’s included nginx web server.
Finding Packages on the Command Line
pkg_info(1) displays information about packages. While you would normally use pkg_info to explore the packages you’ve already installed, you can use -Q to run a case-insensitive search on the packages in your package repository. If you know part of the package name, try the package search.
$ pkg_info -Q apache
apache-ant-1.8.2p3
apache-couchdb-1.0.1p2
apache-httpd-2.2.22
apachetop-0.12.6
modsecurity-apache-1.9.3p5
p5-Apache-ASP-2.61p0
…
From the names, you can guess that the package apache-httpd-2.2.22 contains Apache 2.2.
Finding Packages on the Web
The easiest way to search packages is to use the unofficial OpenBSD Ports website at http://www.openports.se/. While this isn’t an official OpenBSD website, it has provided a good interface into the OpenBSD ports tree for several years. If I search for Apache on this site, the third hit is for “www/apache-httpd, apache HTTP server.”
Once you know the name of the package containing the software you want, you can install it.
Installing Packages
Use pkg_add(1) to install packages. You don’t need the version number—just the package name. Here, I install the Apache package I found earlier:
# pkg_add apache-httpd 1 apache-httpd-2.2.22:libiconv-1.14: ok apache-httpd-2.2.22:pcre-8.30: ok … 2 apache-httpd-2.2.22: ok 3 The following new rcscripts were installed: /etc/rc.d/httpd2 See rc.d(8) for details. 4 --- +apache-httpd-2.2.22 ------------------- This is the official httpd distributed by the Apache Server Project, provided as a port for those who, for various reasons, need to run version 2. OpenBSD provides a custom Apache server, httpd(8), in the base system which has been audited for security and may run in a chroot(2) environment. Users are STRONGLY encouraged to use the system httpd rather than this port.
A great deal of software requires other software to run, and OpenBSD’s package tools track these dependencies. pkg_add starts my Apache installation by installing the various dependencies of the chosen package, as shown at 1. Apache 2.2.22 requires libiconv and pcre, among several other packages. As each package installs, you’ll see a progress bar scroll across the screen. If a dependency cannot be installed, the package installation terminates.
After installing all the dependencies, pkg_add installs the actual Apache 2.2 package, as shown at 2. At the end of package installation, you’ll see notices for startup scripts added by the package, as shown at 3, and then any notes from the OpenBSD team about the packages, like those at 4.
Which Files Are Installed?
Use the -L option to pkg_info to see which files a package installs.
$ pkg_info -L apache-httpd
Information for inst:apache-httpd-2.2.22
Files:
/usr/local/include/apache2/ap_compat.h
/usr/local/include/apache2/ap_config.h
/usr/local/include/apache2/ap_config_auto.h
/usr/local/include/apache2/ap_config_layout.h
/usr/local/include/apache2/ap_listen.h
…
As you can see, all of these files are installed under /usr/local. OpenBSD installs all packages under /usr/local.
Verbose Installation
If you’re interested in the details of how pkg_add works, use the -v flag to trigger verbose mode. You can specify multiple -v flags for added detail. I recommend trying verbose mode a few times, in varying levels of detail, to get a deeper understanding of what pkg_add actually does.
Ambiguous Packages
Sometimes pkg_add needs an extra hint about what you want to install. For example, everything in my production network is tied together with LDAP, and I need to run an OpenLDAP mirror in each datacenter. (I could use OpenBSD’s integrated LDAP daemon instead, but the master servers run OpenLDAP, and I don’t want to mix LDAP servers.) The following is my attempt to install OpenLDAP.
# pkg_add openldap-server 1 Ambiguous: choose package for openldap-server a 0: <None> 1: openldap-server-2.3.43p10 2: openldap-server-2.4.31p0 Your choice: 2 2 Ambiguous: choose dependency for openldap-server-2.4.31p0: a 0: cyrus-sasl-2.1.25p3 1: cyrus-sasl-2.1.25p3-db4 2: cyrus-sasl-2.1.25p3-ldap 3: cyrus-sasl-2.1.25p3-mysql 4: cyrus-sasl-2.1.25p3-pgsql 5: cyrus-sasl-2.1.25p3-sqlite3 Your choice: 2 3 Detected loop, merging sets ok | cyrus-sasl-2.1.25p3-ldap | openldap-client-2.4.31 openldap-server-2.4.31p0:cyrus-sasl-2.1.25p3-ldap+openldap-client-2.4.31: ok openldap-server-2.4.31p0:db-4.6.21v0: ok openldap-server-2.4.31p0:icu4c-49.1.2p1: ok openldap-server-2.4.31p0: ok The following new rcscripts were installed: /etc/rc.d/saslauthd /etc/rc.d/slapd See rc.d(8) for details.
As you can see at 1, OpenBSD has two OpenLDAP server packages: recent releases of version 2.3 and version 2.4. I want version 2.4. The OpenBSD OpenLDAP package is compiled with Cyrus SASL (Simple Authentication and Security Layer), which in turn comes in six different flavors, as you can see at 2—one for each supported database. I choose the version that uses LDAP as its backend. (I don’t need this particular SASL; any SASL will suffice.)
pkg_add realizes that this is something of a chicken-and-egg problem. LDAP is compiled using Cyrus, but Cyrus is compiled using LDAP. Fortunately, as you can see at 3, it knows that this is a permissible configuration. The dependencies are installed, and then the OpenLDAP server that I want is added.
Identifying Where Files Originate
As you’ve seen in earlier examples, many packages install other packages as dependencies. Once you’ve installed a few complicated software packages, /usr/local starts to fill up with weird-looking files and programs. Eventually, you’ll wonder which packages are needed or where a package was installed from.
OpenBSD maintains records for every installed package in /var/db/pkg, including files installed and dependency information, but wading through these files resembles effort, and I won’t do it. Also, many package names are obscure, opaque, obfuscated, or otherwise obtuse. (It’s not that the OpenBSD packages team tries to make package names incomprehensible, but there’s only so much it can do when the software has a name like icu4c.)
Thankfully, pkg_info(1) can easily answer most questions about your installed software. Start by getting a complete list of all software packages on the machine with the -a argument.
$ pkg_info -a
cyrus-sasl-2.1.25p3-ldap RFC 2222 SASL (Simple Authentication and Security Layer)
db-4.6.21v0 Berkeley DB package, revision 4
icu4c-49.1.2p1 International Components for Unicode
openldap-client-2.4.31 Open source LDAP software (client)
openldap-server-2.4.31p0 Open source LDAP software (server)
quirks-1.73 exceptions to pkg_add rules
tcsh-6.18.01 extended C-shell with many useful features
Hang on a minute! I’ve installed tcsh, of course, as my aged brain isn’t up to learning a new shell. I installed OpenLDAP, and chose to add cyrus-SASL as a dependency. Did pkg_add really install all of these other packages as dependencies? Or has one of my junior admins installed extra cruft? Do I really need all of these packages, or do I just need to smack a minion?
OpenBSD records which software packages you’ve installed, versus those installed as dependencies. Use the -m flag to see only those packages you manually installed.
# pkg_info -m
openldap-server-2.4.31p0 Open source LDAP software (server)
quirks-1.73 exceptions to pkg_add rules
tcsh-6.18.01 extended C-shell with many useful features
This looks more familiar. Apparently everything else really is a dependency.
Now let’s look at some options. For longer descriptions of each package, add the -d flag or use the -a flag to show information for all packages. If you want to run pkg_info for a single package, use the package name as an argument. For example, -L shows the list of files a package installs. With the -a flag, it will show all files included in all installed packages, but that’s probably more than you want. To show all files installed by a package, use the -L flag and the package name.
$ pkg_info -L tcsh
Information for inst:tcsh-6.18.01
Files:
/usr/local/bin/tcsh
/usr/local/man/man1/tcsh.1
/usr/local/share/nls/C/tcsh.cat
/usr/local/share/nls/de_AT.ISO_8859-1/tcsh.cat
/usr/local/share/nls/de_CH.ISO_8859-1/tcsh.cat
/usr/local/share/nls/de_DE.ISO_8859-1/tcsh.cat
…
As you can see, the tcsh(1) package includes the actual tcsh binary, the man page, and a whole bunch of National Language Support (NLS) files. Given a package name, you can identify which files are part of the package.
Going the other way, sometimes you want to know where a particular file originated. For example, I occasionally browse my server filesystems looking for weird stuff. I define “weird stuff” as “things I don’t recognize.” If I see an unfamiliar program or file, I’ll check to see which package installed it.
$ pkg_info -E /usr/local/sbin/pluginviewer
/usr/local/sbin/pluginviewer: cyrus-sasl-2.1.25p3-ldap
cyrus-sasl-2.1.25p3-ldap RFC 2222 SASL (Simple Authentication and Security Layer)
The only pluginviewer I had previously encountered was one designed to help Unix web browsers run third-party software when a website demanded a plug-in. I don’t know what this pluginviewer does, but apparently it’s a legitimate part of cyrus-SASL. To find something to worry about, I need to keep looking.[36] If you do many file searches like this, you can get faster results by using pkglocatedb (/usr/ports/databases/pkglocatedb).
After installation, many packages show a message, which I frequently read and promptly forget. To display this information again, use pkg_info with the -M flag.
$ pkg_info -M apache-httpd
Information for inst:apache-httpd-2.2.22
Install notice:
This is the official httpd distributed by the Apache Server Project,
…
If you don’t remember which package had the message you wanted, use the -a flag instead of a package name to display the messages for all packages that have one. To show all packages that are not required by other packages, use the -t flag, which you might think matches all packages you chose to install. If you didn’t request a package, it could only be installed as a dependency to something you requested, right?
$ pkg_info -t
apache-httpd-2.2.22 apache HTTP server
icu4c-49.1.2p1 International Components for Unicode
quirks-1.73 exceptions to pkg_add rules
tcsh-6.18.01 extended C-shell with many useful features
I know that I did not choose to install icu4c. I have no moral objections to the software, mind you, but it’s nothing I requested. How did a piece of software that I didn’t choose to install, and isn’t required by anything else, get on this system?
It’s there because I uninstalled something that required it.
Uninstalling Packages
To remove a previously installed package, use pkg_delete(1).
# pkg_delete openldap-server
openldap-server-2.4.31p0: ok
Read shared items: ok
--- -openldap-server-2.4.31p0 -------------------
You should also run /usr/sbin/userdel _openldap
You should also run /usr/sbin/groupdel _openldap
pkg_delete does not request confirmation. It doesn’t ask if you are sure. It just blasts the software off the disk and gets on with its day. It also doesn’t remove the unprivileged users and groups created for the software, as you might still have files owned by them.
Remember that many packages require other packages. By default, pkg_delete doesn’t remove dependencies of packages you remove. For example, earlier we saw that icu4c had been installed automatically as a leftover dependency from a removed OpenLDAP server package. To automatically remove unneeded dependencies, use the -a flag. For example, to completely eradicate the openldap-server package and its infrastructure from the machine, run pkg_delete twice.
# pkg_delete openldap-server # pkg_delete -a
This should clean your system of all packages installed as dependencies.
Package Limitations
The package system is fast, efficient, reliable, and the OpenBSD Project’s preferred way for users to install software. But the system does have a few limitations that you should be aware of, including lags in the software-porting process and the support for newer packages on older versions of OpenBSD.
Each OpenBSD release supports only packages built for that release, and new packages are not built for old releases. The packages issued with the release are all you’ll get. (There are slight exceptions to this if you’re running -stable; see Chapter 20.) If you’re running OpenBSD 5.3 and try to install packages from OpenBSD 5.4, they won’t work.
Most packages include software produced by third parties. OpenBSD provides the packaging, but the software itself is released on a schedule completely independent of OpenBSD’s. After the software developers release their newest software, the OpenBSD package is updated, but there’s a gap between the software’s release date and the release of the OpenBSD package. A popular package might be updated in hours, while larger, less frequently used, or unpopular packages can languish at an older version for days or weeks. These packages are not officially available until the next OpenBSD release, so you might run software that’s a point or two behind the latest for a few months. Usually, this is not a problem (if it is, investigate OpenBSD’s -stable branch, discussed in Chapter 20.)