Updated: September 10, 2021


Step 1: Using the Ports Collection to Install Poudriere:

  • All commands in this section should be run as root, using the su(1) command will work. You’ll need to start by installing git:

# pkg install git

  • Then, use git to clone the ports collection into /usr/ports:

# git clone https://git.freebsd.org/ports.git /usr/ports

  • Next, build and install Poudriere from the ports collection using:

# cd /usr/ports/ports-mgmt/poudriere

# make install clean

  • Prompts will appear throughout the installation process, stick with the default settings and install the port.

Step 2: Configuring Poudriere

  • Poudriere is an extremely powerful tool designed for package production, but can also be used to bulk manage ports. In order to do so, a few small tweaks will need to be made to the configuration before moving forward.
  • First, copy and move the configuration file to the correct location with:

# cd /usr/local/etc

# cp poudriere.conf.sample poudriere.conf

  • Then use the ee(1) text editor to edit the copied configuration file:

# ee poudriere.conf

  • Arrow keys can be used to navigate down to the line:

FREEBSD_HOST=_PROTO_://_CHANGE_THIS_

  • Edit the above line, so it instead looks like this: (backspace to delete text)

FREEBSD_HOST=ftp://ftp.freebsd.org

  • Type ESCAPE and then ENTER twice to exit and save changes to the configuration file.

Step 3: Set Up a Poudriere Jail

  • Before continuing, Poudriere will need to fetch and extract its own version of the FreeBSD ports collection. In order to do this, run:

# rehash

# poudriere ports -c

  • A FreeBSD jail will need to be set up for Poudriere to perform bulk functions. This can be done with the commands:

# mkdir /usr/local/poudriere

# poudriere jail -c -j 91x64 -v 12.1-RELEASE -a amd64

  • In the above command, 91x64 identifies the jail, while 12.1-RELEASE identifies the FreeBSD version to use. These can be tweaked if a different name or FreeBSD version is required. Just remember to also replace them in the rest of this guide.

Step 4: Creating a Bulk List of Ports

  • Before continuing, run the following:

# cd poudriere.d

# echo WITH_PKGNG=YES >> 91x64-make.conf

  • The next step will be to create a list of ports for poudriere to compile and maintain, a wide range of ports are available in the FreeBSD ports collection, and poudriere can be used to manage them all. Start with:

# cd /usr/local/etc

# ee poudriere-list

  • As before, use the ee(1) text editor to edit the file, adding a list of ports for poudriere to manage. Above is an example image including Firefox, the i3 windows manager, irssi, and tmux. Ports can be added to the list by using the port origin (category/name).
  • Type ESCAPE and then ENTER twice to exit and save changes to the configuration file.

Step 5: Configuring Poudriere Installation Options

This step is optional unless manual configuration is needed.

  • While poudriere can be used to automate bulk port management, it still allows users to manually configure each port. However, this step can be done before installation instead of having to be present for the entirety of the process. If, for instance, the user wants to edit tmux(1), use the command:

# poudriere options  -c sysutils/tmux

  • Then, using the installation prompts (arrows keys to navigate, space to select) the port can be manually edited. This process can be done for each port that poudriere manages.

Step 6: Using Poudriere to Manage Ports

  • With configuration complete, installing the entire list of ports can be done with just one command:

# poudriere bulk -j 91x64 -f poudriere-list

  • Poudriere will take some time to complete the bulk process,  but unlike manually building and installing ports, it can do all the work without needing user inputs. Poudriere also offers a text-based visual display of the installation process. It will allow users to have greater control over their ports without sacrificing automation.
  • If an update is needed to the port list, poudriere can update the port collection with the commands:

# cd /usr/local/etc

# poudriere bulk -j 91x64 -f poudriere-list