How to Use `poudriere` for Bulk Package Builds on FreeBSD

Introduction

FreeBSD is a powerful and versatile Unix-like operating system known for its stability, performance, and advanced features. One of its key strengths is its package management system, which allows users to easily install, update, and remove software. While the FreeBSD project provides pre-built binary packages, there are cases where users may need to build packages from source—whether for customization, testing, or maintaining a local package repository.

poudriere is the official FreeBSD tool for bulk package building. It provides a robust and efficient way to compile packages in clean jail environments, ensuring consistency and reliability. This article provides a comprehensive guide on setting up and using poudriere for bulk package builds on FreeBSD.

Table of Contents

1. What is poudriere?
2. Why Use poudriere?
3. Installing poudriere
4. Configuring poudriere
   • Setting Up ZFS (Recommended)
   • Basic Configuration
   • Creating Build Jails
5. Building Packages with poudriere
   • Selecting Ports Tree
   • Defining Package Sets
   • Starting a Build
6. Managing Builds
   • Checking Build Status
   • Handling Failed Builds
   • Updating Jails and Ports
7. Hosting a Local Package Repository
8. Automating Builds with Cron
9. Best Practices
10. Conclusion

1. What is poudriere?

poudriere is a tool designed to build FreeBSD packages in clean, isolated environments called “jails.” It ensures that builds are reproducible and free from host system contamination. Key features include:

• Parallel builds – Compiles multiple packages simultaneously.
• ZFS integration – Efficiently manages build environments using snapshots.
• Customization – Allows defining build options (make.conf, src.conf).
• Logging & reporting – Provides detailed logs for debugging failed builds.
• Repository creation – Generates a package repository for distribution.

2. Why Use poudriere?

There are several reasons to use poudriere:

• Custom packages – Modify build options (e.g., enabling features).
• Testing – Verify package builds before committing changes.
• Local repositories – Maintain private package mirrors for multiple machines.
• Security – Isolated builds prevent contamination from the host system.
• Reproducibility – Ensures consistent builds across different systems.

3. Installing poudriere

poudriere is available in the FreeBSD ports tree and can be installed via pkg:

pkg install poudriere

Alternatively, build it from ports:

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

4. Configuring poudriere

Setting Up ZFS (Recommended)

For optimal performance, use ZFS. If your system uses ZFS, create a dataset for poudriere:

zfs create -o mountpoint=/usr/local/poudriere zroot/poudriere

Basic Configuration

The main configuration file is /usr/local/etc/poudriere.conf. Edit it:

vi /usr/local/etc/poudriere.conf

Example settings:

ZPOOL=zroot
BASEFS=/usr/local/poudriere
DISTFILES_CACHE=/usr/ports/distfiles
USE_PORTLINT=yes

Creating Build Jails

poudriere requires a jail for building packages. Create one for a specific FreeBSD release:

poudriere jail -c -j 14amd64 -v 14.0-RELEASE -a amd64

• -j: Jail name (14amd64).
• -v: FreeBSD version (14.0-RELEASE).
• -a: Architecture (amd64).

5. Building Packages with poudriere

Selecting Ports Tree

poudriere needs a ports tree. Create and update one:

poudriere ports -c -p latest
poudriere ports -u -p latest

Defining Package Sets

You can build all packages or specify a list. Create a package list:

vi /usr/local/etc/poudriere.d/pkglist

Example:

www/nginx
databases/postgresql15-server
security/openssl

Starting a Build

Run a bulk build:

poudriere bulk -j 14amd64 -p latest -f /usr/local/etc/poudriere.d/pkglist

• -j: Jail name.
• -p: Ports tree name.
• -f: Package list file.

6. Managing Builds

Checking Build Status

Monitor ongoing builds:

poudriere status

View logs for failed packages:

poudriere logs -j 14amd64 -p latest -n <port-name>

Handling Failed Builds

Investigate failures by reviewing logs. Common fixes:

• Missing dependencies.
• Build options conflicts.
• Outdated ports tree.

Updating Jails and Ports

Keep jails and ports updated:

poudriere jail -u -j 14amd64
poudriere ports -u -p latest

7. Hosting a Local Package Repository

After a successful build, packages are stored in:

/usr/local/poudriere/data/packages/14amd64-default

To serve them via HTTP, use nginx or apache:

pkg install nginx
service nginx enable
service nginx start

Add a symlink:

ln -s /usr/local/poudriere/data/packages/14amd64-default /usr/local/www/nginx/packages

Configure clients to use the repo by editing /usr/local/etc/pkg/repos/local.conf:

local: {
    url: "http://<your-server-ip>/packages/",
    enabled: yes
}

8. Automating Builds with Cron

To schedule regular builds, add a cron job:

crontab -e

Add:

0 3 * * * /usr/local/bin/poudriere bulk -j 14amd64 -p latest -f /usr/local/etc/poudriere.d/pkglist

This runs builds daily at 3 AM.

9. Best Practices

• Use ZFS – Improves performance with snapshots.
• Keep ports updated – Avoid build failures due to outdated sources.
• Monitor disk space – Builds consume significant storage.
• Test before production – Verify packages in a staging environment.
• Document custom options – Track changes in make.conf.

10. Conclusion

poudriere is an essential tool for FreeBSD users who need to build custom packages or maintain local repositories. By leveraging clean jails, ZFS snapshots, and parallel builds, it ensures efficient and reliable package compilation. Whether for personal use or enterprise deployment, mastering poudriere enhances FreeBSD’s flexibility and power.

By following this guide, you should now have a functional poudriere setup capable of bulk-building packages, managing repositories, and automating builds. For further details, consult the official poudriere man pages (man poudriere) and FreeBSD documentation.

Additional Resources

• FreeBSD Handbook: Poudriere
• Poudriere GitHub Repository
• FreeBSD Ports Collection