How to Manage Packages with pkg Binary Package Manager on FreeBSD 12

FreeBSD is an open-source Unix-like operating system used to power modern servers, desktops, and embedded platforms. A large community has continually developed it for more than thirty years. Its advanced networking, security, and storage features have made FreeBSD the platform of choice for many of the busiest web sites and most pervasive embedded networking and storage devices. Giants like Netflix, Yahoo!, WhatsApp, BBC, and Sony use FreeBSD in some form. The FreeBSD system is not as widely known as Linux mainly because Linux has focused for many years on the Desktop and the FreeBSD project has tended to be more server-based.

In this tutorial, you will learn about binary package management via pkg on FreeBSD 12 operating system which is the most recent version at the time this article is being written. Most of the stuff also applies to the earlier FreeBSD 11 version.

Prerequisites

  • FreeBSD 12 operating system
  • Access to root or sudo account

Ports and Packages

On the FreeBSD system, we have two different methods to install add-on software: via ports and via pre-configured packages that most users will choose 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 want.

Packages are pre-compiled software, and they are the result of building ports, using the options the port maintainer believes 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. They are what most users will use. FreeBSD packaging system is called package, or just pkg. Package information gets stored in an SQLite database that you can query about package data.

Another significant information 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 unusual.

The FreeBSD package manager - pkg

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

Here is how you would install acme.sh package on FreeBSD:

pkg install acme.sh

You can feed the command with -y to avoid 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:

pkg delete acme.sh

Use pkg help for a quick reference on the available subcommands, or pkg help command 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. You need to install it. 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 press Y and ENTER on your keyboard and package management tool installation will start. After packaging system 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, but that's rarely used, maybe only in system setup scripts. pkg knows how to install and update itself and other packages.

How to search for packages

Now that you have a package manager installed, you can install packages. If you are a system administrator, you are familiar with the fact that different operating systems assign different names to packaged versions of the same software. A package for Apache webserver 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's the name of the package you want to install.

FreeBSD's list of available applications is growing all the time. 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 webserver.

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 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 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 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: "[email protected]"
# 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.

How to install new packages with pkg

To install software use pkg's 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.

pkg has the ability to just download packages over the internet, save them in one location on the disk, and you can 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 the Nginx package 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 stick 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.

How to configure pkg

The pkg program is designed to be highly flexible. Each subcommand has a whole bunch of 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.

pkg.conf 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 are 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

How to view information about installed packages

If you forget which packages you’ve installed on a system you can use pkg info command 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 a version of the software, the time of software installation, software license, compile-time flags, etc. See the pkg-info man page for the complete details.

How to remove packages

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

pkg delete nginx
# or
pkg remove nginx

You’ll get a list of packages to be removed and how much space they’ll free up.

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

How to lock 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

pkg supports package repositories, 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 /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 commands

In this section, I will list some of the most commonly used subcommands that you will most likely use when administering the 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

Conclusion

FreeBSD implements two companion technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source, and packages, for installing from pre-built binaries. But as FreeBSD is moving the system more decisively toward universal package management, you should try to manage third-party software with pkg as much as possible. Avoid using ports unless the software you want has no packagized version or you need to customize compile-time options.

Share this page:

Suggested articles

0 Comment(s)

Add comment