[OpenBSD]

[FAQ Index] [To Section 14 - Disk Setup]

15 - The OpenBSD packages and ports system


Table of Contents


15.1 - Introduction

There are a lot of third party applications available which one might want to use on an OpenBSD system. To make this software easier to install and manage, plus to help it comply with OpenBSD's policy and goals, the third party software is ported to OpenBSD. This porting effort can involve many different things. Examples are: making the software use the standard OpenBSD directory layout (e.g. configuration files go into /etc), conforming to OpenBSD's shared library specifications, making the software more secure whenever possible, etc.

The end result of the porting effort are ready-to-install binary packages. The aim of the package system is to keep track of which software gets installed, so that it may at any time be updated or removed very easily. This way, no unnecessary files are left behind, and users can keep their systems clean. The package system also helps ensure nothing is deleted by accident, causing software to stop functioning properly. Another advantage is that users rarely need to compile software from source, as packages have already been compiled and are available and ready to be used on an OpenBSD system. In minutes, a large number of packages can be fetched and installed, with everything in the right place.

The packages and 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 collection high, we just do not have enough human resources to ensure the same level of robustness and security. Of course security updates for various applications are committed to the ports tree as soon as possible, and corresponding package security updates are made available as snapshots for -current.

15.2 - Package Management

15.2.1 - How does it work?

Packages are the pre-compiled binaries of some of the most used third party software. Packages can be managed easily with the help of several utilities, also referred to as the pkg* tools:

In order to run properly, an 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:

15.2.2 - Making things easy: PKG_PATH

You can make things really easy by using the PKG_PATH environment variable. Just point it to your favorite location, and pkg_add(1) will automatically look there for any package you specify, and also fetch and install the necessary dependencies of this package automatically.

A list of possible locations to fetch packages from is given in the following section.

Example 1: fetching from your CDROM, assuming you mounted it on /mnt/cdrom

$ export PKG_PATH=/mnt/cdrom/5.4/packages/`machine -a`/

Example 2: fetching from a nearby FTP mirror

$ export PKG_PATH=ftp://your.ftp.mirror/pub/OpenBSD/5.4/packages/`machine -a`/

It's usually a good idea to add a line similar to the above examples to your ~/.profile. As with the classic PATH variable, you can specify multiple locations, separated by colons. Prior to OpenBSD 4.4, every path in the PKG_PATH variable MUST end in a slash (/). That way, pkg_add(1) can split the path correctly even if it holds URL schemes containing colons. If the first entry in PKG_PATH fails, the next one will be tried, and so on, until the package is found. If all entries fail, an error is produced.

Notice the use of machine(1) in the above command lines. This automatically substitutes your installed OpenBSD "application architecture", which is usually, but not always, your platform name. Of course, if you are using snapshots, you will replace "5.4" with "snapshots".

15.2.3 - Finding packages

A large collection of pre-compiled packages is available for the most common architectures. Just look for your package in one of these places:

If you have the ports tree on your system, you can quickly find the package you are looking for as explained in Searching the ports tree.

If you're looking for a specific filename, install the pkglocatedb package, and use the pkg_locate command to find which package(s) contain that file.

You will notice that certain packages are available in a few different varieties, formally called flavors. Others are pieces of the same application which may be installed separately. They are called subpackages. This will be detailed further in Using flavors and subpackages but flavor basically means they are configured with different sets of options. Currently, many packages have flavors, for example: database support, support for systems without X, or network additions like SSL and IPv6. Every flavor of a package will have a different suffix in its package name. For detailed information about package names, please refer to packages-specs(7).

Note: Not all possible packages are necessarily available on the FTP servers! Some applications simply don't work on all architectures. Some applications can not be distributed via FTP (or CDROM) for licensing reasons. There may also be many possible combinations of flavors of a port, and the OpenBSD project just does not have the resources to build them all. If you need a combination which is not available, you will have to build the port from source. For more information on how to do that, read Using flavors and subpackages in the Ports section of this document.

15.2.4 - Installing new packages

To install packages, the utility pkg_add(1) is used. If you have made things easy for yourself by setting the PKG_PATH environment variable, you can just call pkg_add(1) with the package name, as in the following basic example.
$ sudo pkg_add -v screen-4.0.3p3
parsing screen-4.0.3p3
installed /etc/screenrc from /usr/local/share/examples/screen/screenrc | 71%
screen-4.0.3p3: complete

In this example the -v flag was used to give a more verbose output. This option is not needed but it is helpful for debugging and was used here to give a little more insight into what pkg_add(1) is actually doing. Notice the message mentioning /etc/screenrc. Specifying multiple -v flags will produce even more verbose output.

Using pkg_add(1) in interactive mode

pkg_add(1) has an interactive mode, which is enabled by invoking it with the -i flag, and which causes it to ask you questions when it cannot make decisions by itself. For example, if you don't know the version number of a package beforehand, you can try something like:
$ sudo pkg_add -i screen
Ambiguous: screen could be screen-4.0.3p3 screen-4.0.3p3-shm
Choose one package
         0: <None>
         1: screen-4.0.3p3
         2: screen-4.0.3p3-shm
Your choice: 1
screen-4.0.3p3: complete

For some packages, some important additional information will be given about the configuration or use of the application on an OpenBSD system. Since it is important, it will be displayed whether or not you use the -v flag. Consider the following example:

$ sudo pkg_add ghostscript-fonts-8.11
ghostscript-fonts-8.11: complete
You may wish to update your font path for /usr/local/share/ghostscript/fonts
--- ghostscript-fonts-8.11 -------------------
To install these fonts for X11, just make sure that the fontpath
lists the 75dpi or 100dpi bitmap fonts before the ghostscript fonts,
and make sure you have the string ":unscaled" appended to the bitmap
font's fontpath. This way, the bitmap fonts will be used if they
match, and the Type 1 versions will be used if the font needs to be
scaled. Below is the relevant section from a typical xorg.conf file.

   FontPath   "/usr/X11R6/lib/X11/fonts/misc/"
   FontPath   "/usr/X11R6/lib/X11/fonts/75dpi/:unscaled"
   FontPath   "/usr/X11R6/lib/X11/fonts/100dpi/:unscaled"
   FontPath   "/usr/local/lib/X11/fonts/ghostscript/"
   FontPath   "/usr/X11R6/lib/X11/fonts/Type1/"

Let us now continue with an example of a package which has dependencies:

$ sudo pkg_add -v tin-1.8.2p0
parsing tin-1.8.2p0
Dependencies for tin-1.6.2 resolve to: gettext-0.14.6, libutf8-0.8, pcre-6.4p1, libiconv-1.9.2p3 (todo: libiconv-1.9.2p3,gettext-0.14.6,pcre-6.4p1,libutf8-0.8)
tin-1.8.2p0:parsing libiconv-1.9.2p3
tin-1.8.2p0:libiconv-1.9.2p3: complete
tin-1.8.2p0:parsing gettext-0.14.6
Dependencies for gettext-0.14.6 resolve to: expat-2.0.0, libiconv-1.9.2p3 (todo: expat-2.0.0)
tin-1.8.2p0:parsing expat-2.0.0
tin-1.8.2p0:expat-2.0.0: complete
tin-1.8.2p0:gettext-0.14.6: complete
tin-1.8.2p0:parsing pcre-6.4p1
tin-1.8.2p0:pcre-6.4p1: complete
tin-1.8.2p0:parsing libutf8-0.8
tin-1.8.2p0:libutf8-0.8: complete
tin-1.8.2p0: complete
Again we added the -v flag to see more of what is happening. Upon investigating the packing information, dependencies are found and they are installed first. Somewhere in the middle you can see the gettext package being installed, which depends on libiconv. Before installing gettext, its packing information is examined and it is verified whether libiconv has already been installed.

It is possible to specify multiple package names on one line, which then all get installed at once, along with possible dependencies.

If for some reason you decide not to use PKG_PATH, it is also possible to specify the absolute location of a package on the command line. This absolute location may be a local path, or a URL referring to FTP, HTTP, or SCP locations. Let's consider installation via FTP in the next example:

$ sudo pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/5.4/packages/`machine -a`/screen-4.0.3p3.tgz
screen-4.0.3p3: complete

In this example the -v flag wasn't used, so only needed messages are shown. Notice that the complete filename was entered by adding a .tgz suffix. You can also skip this suffix as in the previous examples since it is auto-completed by pkg_add(1).

Note: Not all architectures have the same packages available. Some ports do not work on certain architectures, and performance limits the number of packages that can be built on others.

For safety, if you are installing a package which you had installed earlier (or an older version of it) and removed, pkg_add(1) will not overwrite configuration files which have been modified. Instead, it will inform you about this as follows (only when using the -v flag, however!):

$ sudo pkg_add -v screen-4.0.3p3
parsing screen-4.0.3p3
The existing file /etc/screenrc has NOT been changed**                 | 71%
It does NOT match the sample file /usr/local/share/examples/screen/screenrc
You may wish to update it manually
screen-4.0.3p3: complete
Sometimes you may encounter an error like the one in the following example:
$ sudo pkg_add xv-3.10ap4
xv-3.10ap4:jpeg-6bp3: complete
xv-3.10ap4:png-1.2.14p0: complete
xv-3.10ap4:tiff-3.8.2p0: complete
Can't install xv-3.10ap4: lib not found X11.9.0
Even by looking in the dependency tree:
        tiff-3.8.2p0, jpeg-6bp3, png-1.2.14p0
Maybe it's in a dependent package, but not tagged with @lib ?
(check with pkg_info -K -L)
If you are still running 3.6 packages, update them.
There is pkg_add(1) nicely installing dependencies, when all of a sudden it aborts the installation of xv. This is another safety precaution which is available since OpenBSD 3.7. The packing information bundled in the package includes information about shared libraries that the package expects to be installed, system libraries as well as third party libraries. If one of the required libraries cannot be found, the package is not installed because it would not function anyway.

To solve this type of conflict, you must find out what to install in order to get the required libraries on your system. There are several things to check:

15.2.5 - Listing installed packages

You can see a list of installed packages by using the pkg_info(1) utility.
$ pkg_info
aterm-0.4.2p1       color vt102 terminal emulator with transparency support
bzip2-1.0.4         block-sorting file compressor, unencumbered
expat-2.0.0         XML 1.0 parser written in C
fluxbox-0.9.15.1p0  window manager based on the original Blackbox code
gettext-0.14.6      GNU gettext
imlib2-1.3.0        image manipulation library
jpeg-6bp3           IJG's JPEG compression utilities
libiconv-1.9.2p3    character set conversion library
libltdl-1.5.22p1    GNU libtool system independent dlopen wrapper
libungif-4.1.4p0    tools and library routines for working with GIF images
libutf8-0.8         provides UTF-8 locale support
mutt-1.4.2.2i       tty-based e-mail client
pcre-6.4p1          perl-compatible regular expression library
png-1.2.14p0        library for manipulating PNG images
screen-4.0.3p3      multi-screen window manager
tcsh-6.14.00p1      extended C-shell with many useful features
tiff-3.8.2p0        tools and library routines for working with TIFF images
tin-1.8.2p0         threaded NNTP and spool based UseNet newsreader

When given an installed package name (or a location of a package which is to be installed), pkg_info(1) will show more detailed information about that specific package.

15.2.6 - Updating installed packages

Let's say you had an older version of unzip installed before upgrading this box from OpenBSD 5.3 to 5.4. Now you can easily upgrade to the newer 5.4 package as follows:
$ sudo pkg_add -u unzip
unzip-5.52p0 (extracting): complete
unzip-5.52 (deleting): complete
unzip-5.52p0 (installing): complete
Clean shared items: complete

When a package has dependencies, they are also examined for updates. Invoking pkg_add(1) with the -u flag and no package name will try to update all installed packages.

Note: The -u switch relies on the PKG_PATH environment variable. If it is not set, pkg_add(1) will not be able to find updates.

Having several entries in PKG_PATH does not mean all entries will be tried for update operations. Instead, pkg_add(1) will stop at the first path with matching candidates.

If you had a configuration file belonging to the old version, which you modified, it will be left untouched by default. You can, however, replace it with the default configuration file of the new version, by calling pkg_add(1) with the -c flag.

15.2.7 - Removing installed packages

To delete a package, simply take the proper name of the package as shown by pkg_info(1) (see Listing installed packages above) and use pkg_delete(1) to remove the package. In the example below, the screen package is being removed. Notice that on some occasions there are instructions of extra items that need to be removed that pkg_delete(1) did not remove for you. As with the pkg_add(1) utility, you can use the -v flag to get more verbose output.

$ sudo pkg_delete screen
screen-4.0.3p3: complete
Clean shared items: complete

Note: Often, it is not necessary to specify the version numbers and flavors with the package name, since pkg_delete(1) will usually be able to find the full name by itself. You need to specify the complete package name (in the example, that is screen-4.0.3p3) only if ambiguity is possible due to multiple installed packages with the specified name. In that case pkg_delete(1) cannot know which package to delete.

For safety, pkg_delete(1) will not remove configuration files if they have been modified. Instead it will inform you about this as follows:

$ sudo pkg_delete screen
screen-4.0.3p3: complete
Clean shared items: complete 
--- screen-4.0.3p3 -------------------
You should also remove /etc/screenrc (which was modified)

If you prefer to have those configuration files removed automatically, you can do so by using the -c flag.

15.2.8 - Incomplete package installation or removal

In some odd cases, you may find that a package was not added or deleted completely, because of 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:
$ sudo pkg_add screen-4.0.3p3
screen-4.0.3p3: complete                                                      7%
Adjusting md5 for /usr/local/info/screen.info-3 from 49fb3fe1cc3a3b0057518459811b6dac to 3b9c7811244fb9f8d83bb27d3a0f60d8
/usr/sbin/pkg_add: Installation of screen-4.0.3p3 failed , partial installation recorded as partial-screen-4.0.3p3

It is always a good idea to remove partial packages from your system, and to fix potential problems that lead to this failure. It is often an indication that you do not have a clean system with everything installed from packages, but possibly packages mixed up with other software installed straight from source.

15.3 - Working with ports

As mentioned in the introduction, packages are compiled from the ports tree. In this section we will explain how the ports tree works, when you should use it and how you can use it.

IMPORTANT NOTE: The ports tree is meant for advanced users. Everyone is encouraged to use the pre-compiled binary packages. Do NOT ask beginner questions on the mailing lists like "How can I get the ports tree working?". If you have questions about the ports tree, it is assumed that you have read the manual pages and this FAQ, and that you are able to work with it.

15.3.1 - How does it work?

The ports tree, a concept originally borrowed from FreeBSD, is a set of Makefiles, one for each third party application, for controlling

Apart from the Makefile, each port also contains at least the following:

All this information is kept in a directory hierarchy under /usr/ports. This hierarchy contains three special subdirectories:

The other subdirectories all form different application categories, which contain the subdirectories of the actual ports. Complex ports may be organized to an even deeper level, for example if they have a core part and a set of extensions, or a stable and a snapshot version of the application. Every port directory must contain a pkg/ subdirectory containing packing list(s) and description file(s). There may also be patches/ and files/ subdirectories, for source patches and additional files, respectively.

When a user issues make(1) in the subdirectory of a specific port, the system will recursively walk its dependency tree, check whether the required dependencies are installed, build and install any missing dependencies, and then continue the build of the desired port. All of the building happens inside the working directory that the port creates. Normally it is under ${WRKOBJDIR}, defaulting to /usr/ports/pobj, but you may override this (see Configuration of the ports system). If WRKOBJDIR has been explicitly unset, a subdirectory of the port's main directory (package name prefixed by "w-") will be used instead.

Note: Ports are never directly installed on your system! They use a fake installation directory. Everything that gets installed there, is bundled together into a package (which is stored in the packages/ subdirectory of the ports tree as mentioned earlier). Installing a port really means: creating a package, and then installing that package!

More information about the ports system may be found in these manual pages:

15.3.2 - Fetching the ports tree

Before continuing, you must read the section about NOT mixing up your OpenBSD system and ports tree. Once you have decided which flavor of the ports tree you want, you can get the ports tree from different sources. The table below gives an overview of where you can find the different flavors, and in which form. An 'x' marks availability and '-' means it is not available through that specific source.

Source Form Flavor
-release -stable snapshots -current
CD-ROM .tar.gz x - - -
FTP mirrors .tar.gz x - x -
AnonCVS cvs checkout x x - x

On the CD-ROM and FTP mirrors, look for a file named ports.tar.gz. You want to untar this file in the /usr directory, which will create /usr/ports, and all the directories under it. For example:

$ cd /tmp
$ ftp ftp://ftp.openbsd.org/pub/OpenBSD/5.4/ports.tar.gz
$ cd /usr
$ sudo tar xzf /tmp/ports.tar.gz

The snapshots available on the FTP mirrors are generated daily from the -current ports tree. You will find the snapshots in the pub/OpenBSD/snapshots/ directory. If you are using a snapshot of the ports tree, you should have installed a matching snapshot of OpenBSD. Make sure you keep your ports tree and your OpenBSD system in sync!

For more information about obtaining the ports tree via AnonCVS, please read the AnonCVS page which contains a list of available servers and a number of examples.

15.3.3 - Configuration of the ports system

NOTE: This section introduces some additional global settings for building applications from ports. You can skip this section, but then you will be required to perform many of the make(1) statements in the examples as root.

Because the OpenBSD project does not have the resources to fully review the source code of all software in the ports tree, you can configure the ports system to take a few safety precautions. The ports infrastructure is able to perform all building as a regular user, and perform only those steps that require superuser privileges as root. Examples are the fake and install make targets. However, because root privileges are always required at some point, the ports system will not save you when you decide to build a malicious application.

It is possible to use a read-only ports tree by separating directories that are written to during port building:

For example, you could add the following lines to /etc/mk.conf
WRKOBJDIR=/usr/obj/ports
DISTDIR=/usr/distfiles
PACKAGE_REPOSITORY=/usr/packages
If desired, you can also change the ownership of these directories to your local username and group, so that the ports system can create underlying working directories as a regular user.

15.3.4 - Searching the ports tree

Once you have the ports tree in place on your system, it becomes very easy to search for software. Just use make search key="searchkey", as shown in the following example.
$ cd /usr/ports
$ make search key=rsnapshot
Port:   rsnapshot-1.3.1p0
Path:   net/rsnapshot
Info:   remote filesystem snapshot utility
Maint:  Antoine Jacoutot <ajacoutot@openbsd.org>
Index:  net sysutils
L-deps:
B-deps: :net/rsync
R-deps: :devel/p5-Lchown :net/rsync
Archs:  any
The search result gives a nice overview of each application that is found: the port name, the path to the port, a one-line description, the port's maintainer, keywords related to the port, library/build/runtime dependencies, and architectures on which the port is known to work.

This mechanism, however, is a very basic one, which just runs awk(1) on the ports index file. Since OpenBSD 4.0, a new port called "sqlports" has been created, allowing very fine-grained searching using SQL. It is a SQLite database, but basically just about any database format can be created using the ports infrastructure. The sqlports port includes the script used to generate the database, which could be used as a basis to generate databases in different formats.

Just pkg_add(1) the sqlports package to get started. A sample session could look like:

$ sqlite3 /usr/local/share/sqlports
SQLite version 3.3.12
Enter ".help" for instructions
sqlite> SELECT FULLPKGNAME,COMMENT FROM Ports WHERE COMMENT LIKE '%statistics%'; 
Guppi-0.40.3p1|GNOME-based plot program with statistics capabilities
mailgraph-1.12|a RRDtool frontend for Postfix statistics
R-2.4.1|clone of S, a powerful math/statistics/graphics language
py-probstat-0.912p0|probability and statistics utilities for Python
darkstat-3.0.540p1|network statistics gatherer with graphs
pfstat-2.2p0|packet filter statistics visualization
tcpstat-1.4|report network interface statistics
wmwave-0.4p2|Window Maker dockapp to display wavelan statistics
diffstat-1.43p0|accumulates and displays statistics from a diff file
sqlite>
The above is still a very basic search. With SQL, just about anything can be searched for, including dependencies, configure flags, shared libraries, etc.

15.3.5 - Straightforward installation: a simple example

For clarity's sake, let's consider a simple example: rsnapshot. This application has one dependency: rsync.
$ cd /usr/ports/net/rsnapshot
$ make install
===>  Checking files for rsnapshot-1.2.9
>> rsnapshot-1.2.9.tar.gz doesn't seem to exist on this system.
>> Fetch http://www.rsnapshot.org/downloads/rsnapshot-1.2.9.tar.gz.
100% |**************************************************|   173 KB    00:02
>> Size matches for /usr/ports/distfiles/rsnapshot-1.2.9.tar.gz
>> Checksum OK for rsnapshot-1.2.9.tar.gz. (sha1)
===>  rsnapshot-1.2.9 depends on: rsync-2.6.9 - not found
===>  Verifying install for rsync-2.6.9 in net/rsync
===>  Checking files for rsync-2.6.9
>> rsync-2.6.9.tar.gz doesn't seem to exist on this system.
>> Fetch ftp://ftp.samba.org/pub/rsync/old-versions/rsync-2.6.9.tar.gz.
100% |**************************************************|   792 KB    00:31
>> Size matches for /usr/ports/distfiles/rsync-2.6.9.tar.gz
>> Checksum OK for rsync-2.6.9.tar.gz. (sha1)
===>  Verifying specs:  c
===>  found c.40.3
===>  Extracting for rsync-2.6.9
===>  Patching for rsync-2.6.9
===>  Configuring for rsync-2.6.9
  [...snip...]
===>  Building for rsync-2.6.9
  [...snip...]
===>  Faking installation for rsync-2.6.9
  [...snip...]
===>  Building package for rsync-2.6.9
Link to /usr/ports/packages/i386/ftp/rsync-2.6.9.tgz
Link to /usr/ports/packages/i386/cdrom/rsync-2.6.9.tgz
===>  Installing rsync-2.6.9 from /usr/ports/packages/i386/all/rsync-2.6.9.tgz
rsync-2.6.9: complete
===> Returning to build of rsnapshot-1.2.9
===>  rsnapshot-1.2.9 depends on: rsync-2.6.9 - found
===>  Extracting for rsnapshot-1.2.9
===>  Patching for rsnapshot-1.2.9
===>  Configuring for rsnapshot-1.2.9
  [...snip...]
===>  Building for rsnapshot-1.2.9
  [...snip...]
===>  Faking installation for rsnapshot-1.2.9
  [...snip...]
===>  Building package for rsnapshot-1.2.9
Link to /usr/ports/packages/i386/ftp/rsnapshot-1.2.9.tgz
Link to /usr/ports/packages/i386/cdrom/rsnapshot-1.2.9.tgz
===>  rsnapshot-1.2.9 depends on: rsync-2.6.9 - found
===>  Installing rsnapshot-1.2.9 from /usr/ports/packages/i386/all/rsnapshot-1.2.9.tgz
rsnapshot-1.2.9: complete

As you can see, the ports system is doing many things automatically. It will fetch, extract, and patch the source code, configure and build (compile) the source, install the files into a fake directory, create a package (corresponding to the packing list) and install this package onto your system (usually under /usr/local/). And it does this recursively for all dependencies of the port. Just notice the "===> Verifying install for ..." and "===> Returning to build of ..." lines in the above output, indicating the walk through the dependency tree.

If a previous version of the application you want to install, was already installed on your system, you can use make update instead of make install. This will call pkg_add(1) with the -r flag.

Note: Large applications will require a lot of system resources to build. Good examples are compilers like GCC 4.0 or the Java 2 Software Development Kit. If you get "out of memory" type of errors when building such a port, this usually has one of two causes:

15.3.6 - Cleaning up after a build

You probably want to clean the port's default working directory after you have built the package and installed it.
$ make clean
===>  Cleaning for rsnapshot-1.2.9
In addition, you can also clean the working directories of all dependencies of the port with this make target:
$ make clean=depends
===>  Cleaning for rsync-2.6.9
===>  Cleaning for rsnapshot-1.2.9
If you wish to remove the source distribution set(s) of the port, you would use
$ make clean=dist
===>  Cleaning for rsnapshot-1.2.9
===>  Dist cleaning for rsnapshot-1.2.9
In case you have been compiling multiple flavors of the same port, you can clear the working directories of all these flavors at once using
$ make clean=flavors
You can also clean things up as they get built, by setting a special variable. Work directories will automatically be cleaned after packages have been created:
$ make package BULK=Yes

15.3.7 - Uninstalling a port's package

It is very easy to uninstall a port:
$ make uninstall
===> Deinstalling for rsnapshot-1.2.9
rsnapshot-1.2.9: complete
Clean shared items: complete
This will call pkg_delete(1) to have the corresponding package removed from your system. If desired, you can also uninstall and re-install a port's package by using
$ make reinstall
===>  Cleaning for rsnapshot-1.2.9
/usr/sbin/pkg_delete rsnapshot-1.2.9
rsnapshot-1.2.9: complete
Clean shared items: complete
===>  Installing rsnapshot-1.2.9 from /usr/ports/packages/i386/all/rsnapshot-1.2.9.tgz
rsnapshot-1.2.9: complete
If you would like to get rid of the packages you just built, you can do so as follows:
$ make clean=packages
===>  Cleaning for rsnapshot-1.2.9
rm -f /usr/ports/packages/i386/all/rsnapshot-1.2.9.tgz

15.3.8 - Using flavors and subpackages

Please do read the ports(7) manual page, which gives a good overview of this topic. There are two mechanisms to control the packaging of software according to different needs.

The first mechanism is called flavors. A flavor usually indicates a certain set of compilation options. For instance, some applications have a "no_x11" flavor which can be used on systems without X. Some shells have a "static" flavor, which will build a statically linked version. There are ports which have different flavors for building them with different graphical toolkits. Other examples include: support for different database formats, different networking options (SSL, IPv6, ...), different paper sizes, etc.

Summary: Most likely you will use flavors when a package has not been made available for the flavor you are looking for. In this case you will specify the desired flavor and build the port yourself.

Most port flavors have their own working directory during building and every flavor will be packaged into a correspondingly named package to avoid any confusion. To see the different flavors of a certain port, you would change to its subdirectory and issue

$ make show=FLAVORS
You should also look at the port's DESCR files, as they're supposed to explain the available flavors.

The second mechanism is called subpackages. A porter may decide to create subpackages for different pieces of the same application, if they can be logically separated. You will often see subpackages for the client part and the server part of a program. Sometimes extensive documentation is bundled in a separate subpackage because it takes up quite some disk space. Extra functionality that pulls in heavy dependencies will often be packaged separately. The porter will also decide which subpackage is the main subpackage, to be installed as a default. Other examples are: extensive test suites which come with the software, separate modules with support for different things, etc.

Summary: Some ports are split into several packages. make install will only install the main subpackage.

To list the different packages built by a port, use

$ make show=PKGNAMES

make install will only install the main subpackage. To install them all, use

$ make install-all

To list the different subpackages available for a port, use

$ make show=MULTI_PACKAGES
It is possible to select which subpackage(s) to install from within the ports tree. After some tests, this procedure will just call pkg_add(1) to install the desired subpackage(s).
$ env SUBPACKAGE="-server" make install

Note: The subpackages mechanism only handles packages, it does not modify any configuration options before building the port. For that purpose you must use flavors.

15.3.9 - Using dpb to build multiple ports

When you need to build more than one or two ports at a time, you can use a tool provided in /usr/ports/infrastructure/bin - dpb(1). dpb(1) takes a list of ports to build and automatically builds them all in an optimal order and making use of as much parallelism as possible. It can also use multiple machines to perform the building. It produces detailed logs of the build process for troubleshooting, in /usr/ports/log by default.
/usr/ports/infrastructure/bin/dpb -P ~/localports
will read the list of pkgpaths (pkgpath(7)) in ~/localports and build all the packages. It can also install the packages after they have been built. ~/localports would look something like:
net/cvsync
www/mozilla-firefox
net/rsync
net/nfsen
textproc/mupdf
misc/magicpoint
lang/sbcl
editors/emacs
If you do not provide a list of ports to build on the command line or via -P or -I, dpb(1) will build all the ports in the ports tree.

15.3.10 - Security updates

When serious bugs or security flaws are discovered in third party software, they are fixed in the -stable branch of the ports tree. Unlike the base OS, the lifecycle is 1 release: only -current and the last release are updated, as explained in FAQ 5 - OpenBSD's Flavors.

This means all you need to do is make sure you check out the correct branch of the ports tree, and build the desired software from it. You can keep your tree up-to-date with CVS, and in addition subscribe to the ports-changes mailing list to receive security announcements related to software in the ports tree.

Of course, security updates reach the -current ports tree before being taken up in the -stable branch.

15.3.11 - Package signatures

Signatures are a good way to make sure packages are legitimate and not corrupted.

OpenBSD 5.5 and newer feature official signed packages, using signify(1) .

To start building signed packages, we need to create keys for signing.

# signify -G -n -s /etc/signify/toto-pkg.sec -p /etc/signify/toto-pkg.pub
Note the names: keys for signing packages should end in pkg.

Then we may sign existing packages after building using pkg_sign(1) .

# cd /usr/ports/packages/$(uname -p)
# pkg_sign -s signify -s /etc/signify/toto-pkg.sec -o signed -S all

Alternately, we may add the following line to /etc/mk.conf to directly build signed packages by default.

SIGNING_PARAMETERS=-s signify -s /etc/signify/toto-pkg.sec

In order to install the package on another machine, the public key toto-pkg.pub should be put into the /etc/signify directory on that machine.

By default, pkg_add will only allow signed packages, and it will always look for keys matching /etc/signify/*pkg.pub.

15.4 - FAQ

15.4.1 - I'm getting all kinds of crazy errors. I just can't seem to get this ports stuff working at all.

It is very likely that you are using a system and ports tree which are not in sync.

Sorry?

Another common failure is a missing X11 installation. Even if the port you try to build has no direct dependency on X11, a subpackage of it or its dependencies may require X11 headers and libraries. Building ports on systems without X11 is not supported, so if you insist on doing so, you are on your own to figure it out. For many ports, there are, however, "no_x11" flavored packages available, which you can install without needing X11 on your system.

15.4.2 - The latest version of my Top-Favorite-Software is not available!

If you are using a release or stable version of OpenBSD, you will not find any package updates until the next release, or until security issues occur which justify an update of the port in the -stable branch, and of the corresponding package.

WARNING: DO NOT mix versions of Ports and OpenBSD!

Doing so will sooner or later (probably very soon, in fact) cause you headaches trying to solve all kinds of errors!

But hey, I am all -current here!

The ports collection is a volunteer project. Sometimes the project simply doesn't have the developer resources to keep everything up-to-date. Developers pretty much pick up what they consider interesting and can test in their environment. Some individual ports may lag behind the mainstream versions because of this. Importantly, not updating to the latest version is often a conscious decision. The newer version may have problems that the maintainer is trying to solve, or that have simply made the application worse than the old version. Also, OpenBSD may have different goals than the developers in other projects, which sometimes results in features and design or implementation choices that are undesirable from OpenBSD developers' point of view. The update may also be postponed because the new version is not considered a crucial update.

If you really need a newer version of a port, you should ask the maintainer to update it (see below on how to find out who the port maintainer is). If you can help, all the better.

15.4.3 - Why is there no package for my Top-Favorite-Software?

There are several possible reasons for this:

15.4.4 - Why is there no port of my Top-Favorite-Software?

The ports collection is a volunteer project. Active port development is done by a limited number of people, in their spare time. These people usually make new ports only for software they use directly or are interested in.

You can help. Consider creating your own port. There is some documentation available on this: the OpenBSD Porter's Handbook. Read it, and read it again. Especially the part about maintaining your port. Then try making a new port, and test it carefully and step by step. If finally it works OK for you, submit it to the ports mailing list at ports@openbsd.org. Chances are good you will get some feedback and testing from other people. If the testing is successful, your port will be considered to be taken up in the ports tree.

15.4.5 - Why is my Top-Favorite-Software not part of the base system?

Because OpenBSD is supposed to be a small stand-alone UNIX-like operating system, we need to draw a line as to what to include. Generally, for an application to be included in the base system:

Further answers to this question are also found in FAQ 1.

15.4.6 - What should I use: packages or ports?

In general, you are highly advised to use packages over building an application from ports. The OpenBSD ports team considers packages to be the goal of their porting work, not the ports themselves.

Building a complex application from source is not trivial. Not only must the application be compiled, but the tools used to build it must be built as well. Unfortunately, OpenBSD, the tools, and the application are all evolving, and often, getting all the pieces working together is a challenge. Once everything works, a revision in any of the pieces the next day could render it broken. Every six months, as a new release of OpenBSD is made, an effort is made to test the building of every port on every platform, but during the development cycle it is likely that some ports will break.

In addition to having all the pieces work together, there is just the matter of time and resources required to compile some applications from source. Applications such as Mozilla products or KDE may take hours and huge amounts of disk space and RAM/swap to build. Why go through this much time and effort, when the programs are already compiled and sitting on your CD-ROM or FTP mirror, waiting to be used?

Of course, there are a few good reasons to use ports over packages in some cases:

However, for most people and most applications, using packages is a much easier, and definitely the recommended way of adding applications to an OpenBSD system.

15.4.7 - How do I tweak these ports to have maximum performance?

OpenBSD is about stability and security. Just like the GENERIC kernel is the default and the only supported kernel, the ports team makes sure the ports work and are stable. If you want to switch on all kinds of compiler options, you are on your own. Please do not ask questions on the mailing lists such as why it does not work, when you tried to switch on a few hidden knobs to make it work faster. In general, all this tweaking is not necessary for more than 99% of users, and it is very likely to be a complete waste of time, for you, the user, as well as for the developers who read about your "problems" when in reality there are none.

15.4.8 - I submitted a new port/an update weeks ago. Why isn't it committed?

The ports team has very limited resources and no committer was able to look at your port/update in time. As frustrating as it may be, just ignore this fact. Take care of your port, send updates and eventually someone might take care of it. It has happened before that people suddenly have some free time to spend on committing ports or their interests shift to new areas and suddenly your old submission becomes interesting, if it is remembered.

15.5 - Reporting problems

If you have trouble with an existing port, please send e-mail to the port maintainer. To see who is the maintainer of the port, type, for example:
$ cd /usr/ports/archivers/unzip
$ make show=MAINTAINER

Alternatively, if there is no maintainer, or you can't reach him/her, send e-mail to the OpenBSD ports mailing list, ports@openbsd.org. Please do NOT use the misc@openbsd.org mailing list for questions about ports.

In any case please provide:

For ports which do not build correctly, a complete build transcript is almost always required. You can use the portslogger script, found in /usr/ports/infrastructure/bin, for this. A sample run of portslogger might be:
$ mkdir ~/portslogs
$ cd /usr/ports/archivers/unzip
$ make clean install 2>&1 | /usr/ports/infrastructure/bin/portslogger \
           ~/portslogs
After this, you should have a logfile of the build in your ~/portslogs directory that you can send to the port maintainer. Also, make sure you are not using any special options in your build, for example in /etc/mk.conf.

Alternatively, you can

15.6 - Helping us

There are many ways you can help. They are listed below, by increasing order of difficulty.

Hardware donations can assist testing ports on the various platforms OpenBSD runs on.

Note: For all creation of new ports and subsequent testing, or for testing port updates, you must run a -current system! In general, this is not a desirable environment because of its continuously evolving nature, so proceed only if you are sure about committing yourself to following -current.


[FAQ Index] [To Section 14 - Disk Setup]