How to Use Portmaster to Update Ports

(20170315 — The steps in this post were amended to address changes in recent versions of software — iceflatline)

The Ports Collection is a set of Makefile, patches, and description files stored in /usr/ports. This set of files is used for building and installing applications on FreeBSD, and other BSD-based operating systems.

This post will describe how to use portmaster, a utility for updating installed ports. portmaster is nothing more than a shell script (albeit a quite elegant and powerful one), written in /bin/sh. It does not depend upon other ports, external databases or languages, rather it’s been written in such a way as to make use of the information about a port’s dependencies, dependents, file locations and other information contained in /var/db/pkg to determine which ports to update.

The versions of software discussed in this post are as follows:

• FreeBSD 11.0-RELEASE
• portmaster-3.17.10

Okay, let’s get started. All commands are issued as the root user or by simulating the root user by using the command su. Let’s make sure that the Ports Collection is updated to its most current version with the following command:

If you haven’t installed portmaster yet, let’s do that now. You’ll be prompted with several configuration options. Select any options you’d like and select “OK”:

Now that the Ports Collection has been updated and portmaster installed, let’s check the installed ports against the updated Ports Collection to see whether any installed ports need to be updated. portmaster provides a way to list ports that need updating using the -L option:

As you’ll see in the corresponding output of this command that portmaster groups all installed ports into four categories:

Root ports: port listed under this category have no dependencies, nor are they depended on by other ports.

Trunk ports: ports listed under this category have no dependencies, but other ports depend upon them.

Branch ports: ports listed under this category have dependencies and are also depended upon by other ports.

Leaf ports: Ports listed under this category have dependencies but are not depended upon by other ports.

Each installed port will be listed in one of these categories along with whether the port has a revised version available:

Following the list portmaster will present a succinct summary of the status of your ports:

Before updating a particular port or ports, it’s a good idea to check the notes contained in /usr/ports/UPDATING to see if there are any issues related to updating one or more of them. /usr/ports/UPDATING contains all the last minute notes on all of the ports in the Ports Collection and documents, where applicable, some of the problems you may encounter when updating, and/or additional features or options that may be available. Follow the instructions contained in /usr/ports/UPDATING to update the affected ports. In most every case there will be instructions for how to use portmaster to perform the task. The remaining ports can be updated using the following command:

The -d option tells portmaster to clean up the installation files (in /usr/ports/distfiles), which will help save some disk space. The -w option tells portmaster to save old shared libraries (in /usr/local/lib/compat/pkg/) before “deinstalling” the existing port, allowing those libraries to potentially be restored if there are any incompatibility issues between the new port and the installed libraries. Adding the -v option will direct portmaster to be a bit more forthcoming about what it’s doing. Finally, the name of the port should be one of the following: the full name of the port directory as specified in /var/db/pkg, for example apache22-2.2.23_3 or the full path to the port in the Ports Collection, for example /usr/ports/www/apache22.

After entering the command above portmaster will recurse through the port and its dependencies (if any) to handle any configuration options. If configuration options have changed since the last time the port was updated, portmaster will likely prompt for input. However, you can force the configuration dialogs for all ports by adding the force-config option to the command:

If none of the port’s dependencies require updating, portmaster will simply download the necessary source files and perform the update, otherwise you will be presented a list of ports that will be updated and asked to confirm before portmaster proceeds. You can skip the confirmation step by adding the no-confirm option to the command:

You can also update all of the outdated ports at once using the following command:

The -a options tells portmaster to review all installed ports and update them if necessary. Once again, if portmaster is unclear about the configuration options for a particular port, it will prompt for input, otherwise it will present a list of ports that it will update and ask to confirm before proceeding. The force-config and no-confirm options can be used here as well, if desired.

Adding the -x option will direct portmaster to avoid building or updating ports that match a pattern. For example, the following will update all installed ports except apache22:

The portmaster utility also provides some other useful functions. For example, portmaster can be used as a port installation tool by executing it as though you were updating a port. portmaster will recognize that it’s a new port and install the port’s dependencies as usual:

Sometimes it’s helpful to have portmaster figure out what needs to be updated and in what order, but not actually do it. Adding the -n option directs portmaster to run through the configuration, but not actually update or install any ports

There you have it. The portmaster utility is a simple yet powerful tool for updating your ports. It does not depend on other software or use an external database to track what you have installed, but rather uses the existing ports infrastructure, including what is located in /var/db/pkg. This post covered the basics. The portmaster man page contains a lot more information about portmaster, how it works and what choices are available to you.