How to Use `portmaster` to Manage Ports on FreeBSD Operating System

FreeBSD’s Ports Collection is a powerful framework for building and installing software packages from source code. While the pkg system offers binary packages for quick installation, the Ports Collection provides greater flexibility, customization options, and access to software that might not be available as binary packages. To simplify the management of ports, FreeBSD offers several tools, with portmaster being one of the most popular and versatile. This article provides a comprehensive guide to using portmaster effectively for managing ports on FreeBSD systems.

Introduction to FreeBSD Ports and Portmaster

The FreeBSD Ports Collection is a set of Makefiles, patches, and description files stored in /usr/ports. Each port contains all the necessary information to download, extract, patch, compile, and install a piece of software. While powerful, managing ports manually can be cumbersome, especially when dealing with dependencies and updates.

Portmaster is a utility designed to simplify ports management by automating many common tasks. It’s written in shell script, requires no additional database or setup, and works with the existing ports infrastructure. Unlike some other port management tools, portmaster doesn’t require an external database to track installed ports.

Installing Portmaster

Before you can use portmaster, you need to install it on your FreeBSD system. You can install it either via binary package or from ports:

Installing via Package

pkg install portmaster

Installing via Ports

cd /usr/ports/ports-mgmt/portmaster
make install clean

During the installation from ports, you may be presented with configuration options. The default options are suitable for most users, but you can customize them according to your needs.

Basic Portmaster Usage

Once installed, portmaster offers a wide range of commands to manage your ports. Here are the most common operations:

Listing Installed Ports

To see a list of all installed ports:

portmaster -l

The output categorizes ports into:

• Root ports (no dependencies)
• Trunk ports (have dependencies and are depended upon)
• Branch ports (have dependencies but nothing depends on them)
• Leaf ports (nothing depends on them)

Installing a New Port

To install a new port:

portmaster category/portname

For example, to install the Nginx web server:

portmaster www/nginx

Portmaster will automatically:

1. Check for and build any required dependencies
2. Configure the port (prompting for options if necessary)
3. Compile the port
4. Install the port and register it in the package database

Upgrading Installed Ports

To upgrade a specific port:

portmaster category/portname

To upgrade all outdated ports:

portmaster -a

Before performing system-wide upgrades, it’s advisable to check which ports need updating:

portmaster -L

This command lists ports that have newer versions available in the ports tree.

Reinstalling a Port

To reinstall an existing port:

portmaster -f category/portname

The -f flag forces reinstallation even if the port is already installed at the latest version.

Advanced Portmaster Operations

Handling Dependencies

Portmaster excels at managing dependencies. When upgrading a port, it automatically handles dependencies in the correct order. However, there are situations where you might need more control:

To rebuild all ports that depend on a specific port:

portmaster -r category/portname

This is useful after upgrading a library that might affect other ports.

To rebuild a port and all its dependencies:

portmaster -f -r category/portname

Cleaning Up After Installations

After installing or upgrading ports, you might want to clean up to reclaim disk space:

portmaster --clean-distfiles

This removes outdated distfiles from /usr/ports/distfiles.

To clean up old installation files:

portmaster --clean-packages

Dealing with Orphaned Ports

Ports that were installed as dependencies but are no longer required can be identified and removed:

portmaster --check-depends

This checks for and lists inconsistencies in the dependency database.

To list ports that nothing depends on (leaf ports):

portmaster -l | grep "leaf"

Configuring All Ports Before Building

When upgrading multiple ports, you might want to configure all of them upfront rather than being prompted during the build process:

portmaster -a --configure

This brings up configuration dialogs for all ports that need upgrading before starting the build process.

Customizing Portmaster Behavior

Portmaster can be customized through various command-line options and by creating a configuration file.

Common Command-Line Options

• -G: Skip building ports that are already installed
• -B: Don’t build ports from source; use packages if available
• -P: Use packages instead of ports where available
• -D: Allow distfiles that are older than what’s in the ports tree
• -m: Specify path to an alternate ports directory
• --no-confirm: Don’t ask for confirmation before starting each build
• --no-term-title: Don’t update the terminal title bar

Creating a Configuration File

You can create a permanent configuration file at /usr/local/etc/portmaster.rc to set default options:

# Example portmaster.rc
PM_VERBOSE=yes
PM_NO_CONFIRM=yes
PM_PACKAGES=yes
PM_MAKE_ARGS="-DBATCH"

A sample configuration file is typically installed at /usr/local/etc/portmaster.rc.sample. You can copy this file to /usr/local/etc/portmaster.rc and customize it according to your preferences.

Best Practices for Using Portmaster

Preparing for Upgrades

Before performing major upgrades, it’s advisable to:

1. Update your ports tree:

portsnap fetch update

2. Check for outdated ports:

portmaster -L

3. Read /usr/ports/UPDATING for important notices:

less /usr/ports/UPDATING

This file contains critical information about breaking changes and special upgrade procedures.

Creating Backups

Before making significant changes, consider creating backups:

# Create a backup of your package database
pkg backup -d /path/to/backup/directory

# If using ZFS, create a snapshot
zfs snapshot zroot/usr/local@pre_upgrade

Managing Large Upgrades

For large-scale upgrades:

1. Use the --packages option to use packages where available:

portmaster -a --packages

2. Consider using a local package repository for faster rebuilds:

portmaster --packages-local -a

3. Use --force-config to reconfigure all ports:

portmaster --force-config -a

Troubleshooting Common Issues

Failed Builds

When a port fails to build:

1. Check the build log:

less /usr/ports/category/portname/work/build.log

2. Try rebuilding with verbose output:

portmaster -v category/portname

3. If dependencies are the issue, try rebuilding dependencies first:

portmaster -f -r category/portname

Dependency Conflicts

Dependency conflicts can occur when a port requires a specific version of a dependency that conflicts with another port’s requirements:

1. Identify the conflicting ports:

portmaster --check-depends

2. Consider using pkg to install the conflicting port as a package:

pkg install -f packagename

3. If necessary, use FORCE_PKG_REGISTER to force installation:

make -C /usr/ports/category/portname FORCE_PKG_REGISTER=yes install

Database Inconsistencies

If you encounter database inconsistencies:

1. Check for and fix any broken dependencies:

portmaster --check-depends

2. Rebuild the database of installed ports:

portmaster --check-port-dbdir

Integrating Portmaster with Other Tools

Using Portmaster with Poudriere

For advanced users, Poudriere provides a framework for building packages in isolated environments. You can use portmaster to manage your local ports while using Poudriere for building packages:

1. Use Poudriere to build packages:

poudriere bulk -j jail -p portstree category/portname

2. Use portmaster with the --packages-local option to prefer locally built packages:

portmaster --packages-local category/portname

Combining with Portupgrade

While portmaster and portupgrade serve similar purposes, they can be used together in certain scenarios:

• Use portversion from the portupgrade package to check for outdated ports:

portversion -v

• Then use portmaster for the actual upgrades:

portmaster -a

Comparison with Other Port Management Tools

FreeBSD offers several tools for managing ports, each with its own advantages:

• Portmaster: Simple, shell-based tool with no external database requirements
• Portupgrade: Ruby-based tool with a SQLite database
• Synth: Advanced tool focused on parallel building and package creation
• Pkg: Used for binary package management, but can be combined with ports

Portmaster is often preferred for its simplicity and minimal dependencies, making it a good choice for most users. However, for very large-scale deployments or complex requirements, other tools might be more appropriate.

Conclusion

Portmaster is a powerful and versatile tool for managing FreeBSD ports. It simplifies the process of installing, upgrading, and maintaining ports while providing flexibility and control over the build process. By understanding its capabilities and best practices, FreeBSD users can effectively manage their ports collection and keep their systems up-to-date with minimal effort.

Whether you’re maintaining a single desktop system or managing multiple servers, portmaster provides the tools you need to harness the full power of the FreeBSD Ports Collection. By following the guidelines in this article, you can ensure a smooth and efficient ports management experience.

As with any system management tool, regular practice and familiarity with portmaster’s options will help you become more proficient in maintaining your FreeBSD system. Combined with regular updates to your ports tree and attention to the /usr/ports/UPDATING file, portmaster becomes an invaluable tool in your FreeBSD administration toolkit.