How to Use the Pkg Package Manager on FreeBSD 12

Introduction

FreeBSD is an open source Unix-like operating system used to power modern servers, desktops, and embedded platforms. Giants like Netflix, Yahoo!, WhatsApp, BBC, and Sony use FreeBSD in some form. The FreeBSD system is not as widely known as Linux, largely because Linux has focused for many years on the Desktop and the FreeBSD project has tended to be more server based.

In this guide, you will learn about package management on FreeBSD 12.

Ports vs. Packages

On FreeBSD we have two different ways to install add-on software: via the Ports Collection, or Ports, and via pre-configured packages to install and manage software.

Ports is a system for building additional software on FreeBSD. With Ports you start with the raw source code provided by the software vendor and build the software in exactly the way you need, enabling and disabling features as you need.

Packages are pre-compiled software, and they are the result of building ports, using the options the port maintainer thinks will be most useful to the widest variety of people and bundling them up in a package to make them easily installable. Packages let you quickly install, uninstall, and upgrade add-on software. FreeBSD's packaging system is called package, or pkg. Package information gets stored in an SQLite database that you can query about package data.

Another important thing about FreeBSD package management is the location of package binaries. Packages install binaries under /usr/local, and most configuration files end up in /usr/local/etc rather than /etc. If you come from Linux world you may find this very uncommon.

The FreeBSD package manager, pkg

The next generation replacement for the traditional FreeBSD package management tools is pkg. Offering many features that make dealing with binary packages faster and easier, pkg is the easiest way to install software that isn’t already included in the base system of FreeBSD. It is a single program with many subcommands that you will use for just about every operation on packages such as installing, removing and investigating packages. All package operations and changes must be run as root or via sudo.

Here is how you would install the curl package on FreeBSD:

pkg install curl

You can feed the command with -y to avoid the Proceed with this action? [y/N]: question when installing software or you can configure pkg to always assume -y in a configuration file.

To remove the package, you would use delete:

pkg delete curl

As you can see, it is very simple and intuitive.

Use pkg help for a quick reference on the available subcommands, or pkg help <subcommand> to display the manual page for a particular subcommand:

pkg help
pkg help install
pkg help delete

Installing pkg

The stock version of FreeBSD doesn't ship with the pkg package manager installed. The first time you try to install some package, pkg prompts you to install the package management tool. For example, let's say the first package you want to install on your fresh FreeBSD is wget, and you will see the following prompt in your terminal:

The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y

You will hit Y and Enter and the package management tool installation will start. After it is in place, the initial software package that you wanted to install (wget) will be installed.

You can also install the packaging system on its own, without adding other packages, by running pkg bootstrap. Additionally, pkg knows how to install and update itself and other packages.

NOTE: Vultr instances have pkg installed by default, so you don't need to install it.

Configuring pkg

The pkg program is designed to be highly flexible, with each subcommand having many options. You can establish customized, but consistent behavior for most programs with the system-wide configuration file for pkg, located in /usr/local/etc/pkg.conf.

The file contains commented-out defaults for pkg. Just by reading that file, you can learn a lot about how pkg behaves. The configuration is written in universal configuration language (UCL) and there is plenty of commented-out configuration options and quite a few aliases. Variables can be set to an integer, a string, or a Boolean value:

#PKG_DBDIR = "/var/db/pkg";
#PKG_CACHEDIR = "/var/cache/pkg";
#PORTSDIR = "/usr/ports";
#INDEXDIR = "";
#INDEXFILE = "INDEX-10";        # Autogenerated
#HANDLE_RC_SCRIPTS = false;
#DEFAULT_ALWAYS_YES = false;
#ASSUME_ALWAYS_YES = false;
. . .

You can define aliases for pkg subcommands in pkg.conf. At the bottom of pkg.conf, you’ll find a section labeled ALIAS. When you find yourself repeatedly running complex commands, you should add aliases.

For more information on the file format and options, you can refer to the pkg.conf(5) man page:

man pkg.conf

Finding packages

Now that you have a package manager installed, you can install packages. If you are a sys-admin, you are familiar with the fact that different operating systems assign different names to packaged versions of the same software. A package for Apache web server on FreeBSD, for example, will have a completely different name than the packaged Apache on different Linux distributions. So, before you can install anything, you’ll need to figure out what the name of the package you want to install is.

The FreeBSD Project offers several sets of packages in a public repository, and they are updated every few days. There are currently over 25,000 packages.

For example, let's try to search for Apache web server:

pkg search apache
# apache24-2.4.38                Version 2.4.x of Apache web server

It will find all packages with apache in their names. This will return a long list, but what you are looking for is the apache24 package. There is a short description of every package. This should help you when deciding what package to install, but it's not always simple.

Some searches can generate hundreds of results. You will need to utilize different command line options to trim or adjust the search results. Consult the pkg-search man page or help page pkg help search to learn more about common search options.

If you’re not sure whether a package is what you really want you can use the following command to look up details of the package:

pkg search -R apache24

# name: "apache24"
# origin: "www/apache24"
# version: "2.4.38"
# comment: "Version 2.4.x of Apache web server"
# maintainer: "apache@FreeBSD.org"
# www: "https://httpd.apache.org/"
# abi: "FreeBSD:12:amd64"
# arch: "freebsd:12:x86:64"
# prefix: "/usr/local"
# . . .
# . . .

This command will give you a lot of useful information about the package.

Installing packages

To install software, use the install subcommand and the name of a package to install:

pkg install apache24

When you install packages with pkg install, pkg consults the local package catalog, then downloads the requested package from the repository at pkg.FreeBSD.org. Once the package is installed, it’s registered in an SQLite database kept in /var/db/pkg/local.sqlite. Take care not to delete this file, otherwise, your system will lose track of which packages have been installed. If the software has dependencies, pkg will figure them out and install them along with the base package. Packages installed as dependencies are called automatic packages.

The package manager has the ability to just download packages over the internet and save them in one location on the disk. This allows you to install them at another time. You can use the pkg fetch command to download the package without installing it:

pkg fetch nginx

This command will fetch just Nginx without its dependencies. You can use the -d flag to grab all the dependencies as well as the named package:

pkg fetch -d nginx

The packages are downloaded to the package cache directory /var/cache/pkg. After you have fetched packages, pkg will add them to this directory. You can list files to see what it contains:

ls /var/cache/pkg

Now, to install a downloaded package after a fetch, run pkg install normally. The installation process uses the cached files rather than the downloaded ones.

Over time, the package cache directory can grow big. The pkg clean command removes any cached packages that have been replaced by newer versions, as well as any package files that are no longer in the repository:

pkg clean

If you want to remove all cached packages, use the -a flag:

pkg clean -a

If you want to clean the package cache automatically after each package install or upgrade, set the pkg.conf option AUTOCLEAN to true.

Obtaining information about installed packages

If you forget which packages you’ve installed on a system you can use pkg info to get a complete list of installed software:

pkg info
# atk-2.28.1                     GNOME accessibility toolkit (ATK)
# avahi-app-0.7_2                Service discovery on a local network
# ca_root_nss-3.42.1             Root certificate bundle from the Mozilla Project
# . . .
# . . .

If you want more information about an installed package, use pkg info and the package name. This shows the package installation details in a human-friendly report:

pkg info nginx
# nginx-1.14.2_3,2
# Name           : nginx
# Version        : 1.14.2_3,2
# . . .
# . . .

You can see a lot of useful information like the version of the software, the time of software installation, software license, compile-time flags and more. Check the pkg-info man page for the complete details.

Removing packages

To uninstall binary packages use the pkg delete subcommand. It’s also available as pkg remove:

pkg delete nginx
# or
pkg remove nginx

You will get a list of packages to be removed and how much space this will free up.

If you remove a package that other packages depend on, pkg removes the depending packages as well.

Locking packages

There may be a time when you want a package on your server to never upgrade. When you lock a package, pkg won’t upgrade, downgrade, uninstall or reinstall it. It applies the same rules to the package’s dependencies and the programs it depends on.

Use pkg lock to lock a package:

pkg lock openssl

This openssl package is now locked.

To list all currently locked packages on the system, use the -l flag:

pkg lock -l

To remove the lock use the pkg unlock command:

pkg unlock openssl

To lock or unlock all packages on the system at once, use the -a flag:

pkg lock -a
pkg unlock -a

Package repositories

Package repositories are supported by pkg, which are named collections of packages. You can add, remove, enable, and disable repositories. You should configure each repository in its own file using UCL format. Official FreeBSD repositories belong in the /etc/pkg directory. FreeBSD ships with the repo "FreeBSD" enabled. You’ll find its configuration file in /etc/pkg/FreeBSD.conf:

FreeBSD: {
  url: "pkg+http://pkg.FreeBSD.org/${ABI}/quarterly",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}

You can add and remove repositories as needed. As /etc/pkg is reserved for official FreeBSD repositories, you’ll need another directory. The traditional location is /usr/local/etc/pkg/repos. If you want to use a different directory, you’ll need to set a location in pkg.conf with the REPO_DIRS option. The local repository directory doesn’t exist by default, so you’ll need to create it with mkdir -p /usr/local/etc/pkg/repos. Put your own repository configurations in that directory.

Example pkg subcommands

This section will list some of the most frequently used subcommands that you will most likely use when administering a FreeBSD server:

# Installs a package without asking any questions
pkg install -y package

# Makes a backup of the local package database
pkg backup

# Lists all installed packages
pkg info

# Shows extended information for a package
pkg info package

# Searches package repository
pkg search -i package

# Shows packages with known security vulnerabilities
pkg audit -F

# Shows which package owns the named file
pkg which file

# Removes unused packages
pkg autoremove

# Uninstalls a package
pkg delete package

# Removes cached packages from /var/cache/pkg 
pkg clean -ay

# Updates local copy of the package catalog
pkg update

# Upgrades installed packages to their latest version
pkg upgrade

# Checks the integrity of all your packages
pkg check -saq

# Verifies that a package's files are unaltered
pkg check -s nginx

# Shows what files came with the package
pkg info -l nginx

# Lists non-automatic packages
pkg prime-list

Important files and directories

• The pkg configuration file - /usr/local/etc/pkg.conf
• Directory reserved for official FreeBSD repositories - /etc/pkg
• FreeBSD repository file - /etc/pkg/FreeBSD.conf
• Traditional location for custom repositories - /usr/local/etc/pkg/repos
• Package cache directory - /var/cache/pkg
• SQLite database - /var/db/pkg/local.sqlite

Summary

FreeBSD provides two complementary technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source and packages, for installing from pre-built binaries. As FreeBSD is shifting the system more decisively toward universal package management, try to manage third-party software with pkg to the extent possible. Avoid using ports unless the software you want has no packaged version or you need to customize compile-time options.