When you need software that isn’t in the official repo or community repo, you can build it yourself. OPNsense provides tools.git, the same toolkit they use internally for building packages, ports, and release images.
Note: This guide is for OPNsense 26.x (FreeBSD 14.x). The old Poudriere approach documented on the OPNsense forum (2021, for OPNsense 21.1) no longer works. The OPNsense lead developer has confirmed they don’t use Poudriere internally.
Why Not Poudriere?
The forum tutorial “Making OPNsense more useful with custom-built packages” by kraileth (February 2021) was an excellent resource for its time. It explained how to use Poudriere with OPNsense 21.1 (FreeBSD 12.1 / HardenedBSD 12.1).
However, things changed:
pkg 1.16+ broke Poudriere compatibility. Builds fail at the packaging phase with pkg-1.16.3.pkg: No such file or directory.
mimugmail confirmed: “Poudriere currently doesn’t work with pkg 1.16, it only works with the build tools from OPNsense itself right now.”
Franco (OPNsense lead dev) added: “Changes in pkg 1.17 are a bit destructive… Situations like these are why we do not use poudriere.”
The official way is OPNsense’s tools.git.
Architecture
┌─────────────────────────┐ ┌──────────────────────┐│ FreeBSD 14 Build VM │ │ OPNsense Firewall ││ │ │ ││ /usr/tools (git) │ │ pkg repo pointing ││ /usr/ports (git) │──▶──│ to build VM via ││ /usr/src (git) │ │ HTTP or NFS ││ │ │ ││ make ports → packages │ │ pkg install <pkg> │└─────────────────────────┘ └──────────────────────┘
You build on a separate machine (or VM), never directly on your production firewall. The build machine needs:
FreeBSD 14.3-RELEASE (amd64)
At least 40 GB disk
At least 8 GB RAM
Root access
Setting Up the Build Machine
Install FreeBSD 14.3-RELEASE on a VM or spare machine. Then:
This pulls src.git, ports.git, core.git, and plugins.git:
make update
To use a specific OPNsense version (e.g., 26.7):
make update VERSION=26.7
Alternative directory: If you don’t want to use /usr, set ROOTDIR:
mkdir -p /tmp/opnsensecd /tmp/opnsensegit clone https://github.com/opnsense/toolscd toolsenv ROOTDIR=/tmp/opnsense make update
Building Individual Packages
The tools support targeted rebuilds:
# Build a single portmake ports-curl# Build multiple portsmake ports-curl,nginx,git# Build a pluginmake plugins-os-caddy# Build multiple pluginsmake plugins-os-caddy,os-traefik
For a full ports build (all packages):
make ports
Warning: A full ports build takes hours and requires significant disk space. For a few custom packages, use targeted builds.
Build Options
Control ports build behavior with PORTSENV:
Option
Default
Purpose
BATCH=no
yes
Drop to shell after each build failure for debugging
DEPEND=no
yes
Don’t rebuild dependent plugins/core
DISTFILES=no
yes
Don’t use prefetched distfiles
MISMATCH=no
yes
Don’t rebuild packages with version mismatch
PRUNE=no
yes
Skip ports integrity check before rebuild
Example:
make ports-curl PORTSENV="DEPEND=no PRUNE=no"
You can also override the ports list:
make ports PORTSLIST="security/openssl www/nginx"
Adding Custom Ports
The OPNsense ports tree is at /usr/ports (cloned from opnsense/ports.git). It’s a HardenedBSD ports tree with OPNsense-specific patches.
To add a port not already in the tree:
cd /usr/ports# Find the port categoryls -d */your-package-name
If the port doesn’t exist in the OPNsense ports tree, you need to bring it in from FreeBSD ports. This is the make skim workflow:
# Review and copy upstream changes for used portsmake skim-used# Copy unused upstream changesmake skim-unused# Do bothmake skim
For specific port syncing between branches:
make sync-category/port
Custom Package Lists
Create a package list file for bulk builds:
# Create a list of packages to buildcat > /usr/tools/my-packages.txt << 'EOF'www/nginxnet/tailscalesysutils/htopEOF# Build from the listmake ports PORTSLIST_FILE=my-packages.txt
Where Build Output Goes
Built packages are stored under the sets directory:
make print-SETSDIR
The packages are organized as a pkg repository, ready to be served.
Serving Your Custom Repository
Option 1: HTTP Server on Build Machine
Install a lightweight web server on the build machine:
pkg install nginx
Configure it to serve the packages directory. Then on your OPNsense box, add a repo config:
For one-off installs, copy the .txz file and install directly:
# On OPNsensepkg add /path/to/package-version.txz
Building for a Specific OPNsense Version
The tools use git tags to determine the target version. To build for a specific release:
# Show current version infomake info# Build for version 26.7make ports VERSION=26.7
Additional Build Commands
# Build the base system (userland + bootloader)make base# Build kernel and modulesmake kernel# Build pluginsmake plugins# Build core packagemake core# Create DVD image (not needed for custom packages)make dvd# Run regression testsmake test# Audit packages for vulnerabilitiesmake audit
Troubleshooting
“Unsupported system version”
If the ports tree complains about your FreeBSD version: