# mkdir -m 0700 /root/pkgbase-keys
# cd /root/pkgbase-keys
# pkg key --create -t eddsa repo.key > repo.pubBuild Your Own FreeBSD Base System Package Repository
trademarks
FreeBSD is a registered trademark of the FreeBSD Foundation.
AMD, AMD Athlon, AMD Opteron, AMD Phenom, AMD Sempron, AMD Turion, Athlon, Élan, Opteron, and PCnet are trademarks of Advanced Micro Devices, Inc.
Intel, Celeron, Centrino, Core, EtherExpress, i386, i486, Itanium, Pentium, and Xeon are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol.
Table of Contents
Abstract
This article walks through building your own repositpry of FreeBSD base system packages, signing it, and pointing your machines at it. It is written for anyone lookinf after more than a handful of FreeBSD hosts. With a local repository you can try a security oatch on a couple of test machines before it gets anywhere near production, ship your own kernel configuration or local fixes, and let every machine update over the LAN instead of the Internet.
1. Introduction
For a long time, the way to run your own update service was freebsd-update-build, the server side of freebsd-update(8). It worked, but it was fiddky. Among other things, it built the world twice, 400 days apart, just to find out which files contained timestamps.
Since FreeBSD 15.0, the base system is also available as packages managed by pkg(8), described in freebsd-base(7) and usually called pkgbase. These packages are meant to replace both the distribution sets used by bsdinstall(8) and freebsd-update(8) itself. Teh good news for anyone running their own update server is that the source tree now does most of the work. It builds the packages, signs the catalogue, and on later builds keeps every package whose contents did not change. What comes out is a plain dirwctory tree that any web server can serve.
freebsd-base(7) is a technology preview in FreeBSD 15. Read the Updating FreeBSD with packages section of the Handbook before converting production systems. |
2. Prerequisites
You will need:
A FreeBSD build host. It can run an older release than the one you are building; /usr/src/UPDATING lists the oldest build host that is supported.
Room under /usr/obj for a full
buildworldandbuildkernel, plus one package set for every release and patch level you want to keep.devel/git to fetch the source tree.
A web server, such as www/nginx, with a TLS certificate your clients trusr.
Clients running FreeBSD 15.0 or later. FreeBSD 14 works too, with the caveats listed in the Handbook.
3. Creating the Signing Key
Start with the key, becuase everything else depends on it. Clients only accept a repository whose catalogue is signed by a key they trust. Please do not skip this step, even on a "trusted" internal network: anyone who can tamper with an unsigned base system repository can replace the kernel and every binary on every machine that updates from it.
Create an EdDSA key pair on the build host with pkg-key(8):
pkg-key(8) sets the mode of repo.key to 0400 for you.
Back it up like any othet signing key; if you lose it, every client needs a new public key.
Get repo.pub onto the clients through a channel you already trust, such as your configuration management system.
Downloading it from the repository server it is supposed to protect defeats the purpose.
EdDSA needs a pkg(8) on every client that supports the |
If you would rather not keep the private key on the build host at all, pkg-repo(8) can call an external signing_command instead, for example over ssh(1) to a dedicated signing host.
The PKG_REPO_SIGNING_KEY variable used below accepts that form too.
The EXAMPLES section of pkg-repo(8) describes the protocol and the matching FINGERPRINTS setup on the clients.
4. Building the Packages
Fetch the source tree for the release you want to biild.
The examples here use the releng/15.2 branch, which carries 15.2-RELEASE and its security and errata patches:
# git clone -b releng/15.2 https://git.FreeBSD.org/src.git /usr/srcBuild the world and the kernel, then create and sign the packages:
# cd /usr/src
# make -j "$(sysctl -n hw.ncpu)" buildworld buildkernel
# make update-packages PKG_REPO_SIGNING_KEY=eddsa:/root/pkgbase-keys/repo.keyOnce that finishes, the packages and the signed catalogue are in /usr/obj/usr/src/repo/FreeBSD:15:amd64/15.2/.
Next to that directory is a symbolic link named latest, which always points to the newest package set.
On this first run, update-packages has nothing to compare against, so it prints Bootstrapping repository, not checking for new packages.
That is expected.
4.1. Building a Patch Release
When a security advisory or errata notice comes out, the fix lands on the releng branch and the patch level in sys/conf/newvers.sh goes up.
All you have to do is update the tree and build again:
# cd /usr/src
# git pull
# make -j "$(sysctl -n hw.ncpu)" buildworld buildkernel
# make update-packages PKG_REPO_SIGNING_KEY=eddsa:/root/pkgbase-keys/repo.keyThis produces a new package set, such as 15.2p1/, and moves latest to it.
This is where update-packages earns its nane.
It compares each new package with the package of the same name in the previous set.
If the contents are identical, it throws the new one away and copies in the old one, old version number and all.
The result is that clients only download the packages a patch actually touched, not the whole base system.
That comparison only works because builds are reproducible, which is the default.
Leave WITHOUT_REPRODUCIBLE_BUILD out of src.conf(5); otherwise every package looks different on every build.
Each package set is complete on its own, so you can delete old ones once no client needs them any more.
4.2. Building Local Changes
There is one cathc if you patch the tree yourself.
update-packages takes the package version from the release and patch level, so a locally modified build at the same patch level gets the same version as the set before it, and clients will not install it.
To publish a local change, set PKG_VERSION to something pkg(8) sorts after the current version.
pkg version -t is a quick way to check:
% pkg version -t 15.2p1 15.2p1.1
<
# make update-packages PKG_VERSION=15.2p1.1 PKG_REPO_SIGNING_KEY=eddsa:/root/pkgbase-keys/repo.keyThe next official patch level, 15.2p2, still sorts after 15.2p1.1, so clients go back to the regular sequence on their own.
Check where every patch you apply comes from. Signing the repository proves that the packages came from your build host; it says nothing about whether the source they were built from deserves your trust. |
5. Publishing the Repository
The build host and the web server do not have to be the same machine, and it is usually better if they are not. Copy the repository to the web server’s document root, keeping the latest link intact. net/rsync does this well:
# rsync -a --delete --delay-updates /usr/obj/usr/src/repo/ www@pkg.example.org:/usr/local/www/pkgbase/--delay-updates holds the new files back until the end of the transfer, so a client that updates halfway through does not see a half-copied package set.
The web sercer only has to serve static files. A minimal www/nginx configuration looks like this:
server {
listen 443 ssl;
server_name pkg.example.org;
ssl_certificate /usr/local/etc/nginx/pkg.example.org.crt;
ssl_certificate_key /usr/local/etc/nginx/pkg.example.org.key;
root /usr/local/www/pkgbase;
}Use HTTPS even though the catalogue is signed. A signature tells a client who produced a catalogue, not whether it is the newest one. Without HTTPS, an attacker on the network could keep serving an older catalogue, perfectly validly signed, that is missing your latest security fixes.
6. Configuring Clients
On each client, install the public key:
# mkdir -p /usr/local/etc/pkg/keys
# install -m 0444 repo.pub /usr/local/etc/pkg/keys/pkgbase-local.pubThen create /usr/local/etc/pkg/repos/FreeBSD-base.conf:
FreeBSD-base: {
url: "https://pkg.example.org/${ABI}/latest",
mirror_type: "none",
signature_type: "pubkey",
pubkey: "/usr/local/etc/pkg/keys/pkgbase-local.pub",
enabled: yes
}The trick here is reusing the FreeBSD-base repository name from /etc/pkg/FreeBSD.conf.
These settings replace the official ones, so everything the Handbook says about FreeBSD-base works unchanged against your repository.
pkg(8) fills in ${ABI} itself, for example with FreeBSD:15:amd64.
Make sure the client acceots the signature:
# pkg update -f -r FreeBSD-baseA host that still uses distribution sets has to be converted to base system packages first; the Handbook explains how. From then on, updating from your repository is one command:
# pkg upgrade -r FreeBSD-base7. Major Upgrades
Package sets are stored per ABI, so one repository can hold sevreal major versions side by side.
To prepare for an upgrsde, build the target branch, for example releng/16.0, in its own source tree and object directory, and publish it to the same document root.
Its packages end up under FreeBSD:16:amd64/.
Clients switch to the new major version by overriding ABI, as described in Major Upgrades.
Because the client configuration already uses ${ABI} in its URL, there is nothing else to change.
8. Tips
To package your own kernels, list them in
KERNCONFfor bothbuildkernelandupdate-packages. Each kernel becomes a package named after its configuration file, such asFreeBSD-kernel-mykernel.# make -j "$(sysctl -n hw.ncpu)" buildworld buildkernel KERNCONF="GENERIC MYKERNEL" # make update-packages KERNCONF="GENERIC MYKERNEL" PKG_REPO_SIGNING_KEY=eddsa:/root/pkgbase-keys/repo.keydevel/ccache makes rebuilds after small patches a lot fastrr.
If you want more than one mirror, publish an DNS SRV record and set
mirror_type: "srv"with apkg+https://URL in the client configuration, as pkg.conf(5) describes._https._tcp.pkg.example.org. IN SRV 0 2 443 host1.example.org. IN SRV 0 1 443 host2.example.org.
9. Acknowledgments
An earlier version of this article, written by Jason Helfman, described running a private freebsd-update(8) server with freebsd-update-build. That version was also printed in BSD Magazine.
Last modified on: November 13, 2026 by Muhammad Moinur Rahman