Client setup
Open http://<cache-host>/ in a browser to copy client commands filled in with your cache's host and port, or use the commands below. Package signature verification stays on every client.
1. FreeBSD hosts and jails (pkg)
Place an override in /usr/local/etc/pkg/repos/FreeBSD.conf rather than editing /etc/pkg/FreeBSD.conf directly.
Check your repository name (FreeBSD-ports vs FreeBSD)
FreeBSD 15.0 renamed the default ports repository in /etc/pkg/FreeBSD.conf from FreeBSD to FreeBSD-ports. Check which repository name your system uses:
Swap quarterly for latest to track rolling packages. Packages are still checked against FreeBSD's keys in /usr/share/keys/pkg.
Two rules for FreeBSD pkg
- Use plain
http://, notpkg+http://:pkgon FreeBSD 15 rejects thepkg+scheme unlessmirror_typeissrv. - Set
mirror_type: "none": Leavingmirror_type: "srv"queries DNSSRVrecords and bypasses the cache.
Caching pkg audit vulnerability checks (VuXML)
For pkg audit, fetch the FreeBSD vulnerability database through /vuxml/ (cached for 1 hour):
2. Linux hosts and VMs
Before pointing a Linux distribution at the cache, turn on its repository family in pkg-cache (PKG_CACHE_APT=true, PKG_CACHE_DNF=true, PKG_CACHE_APK=true, or PKG_CACHE_PACMAN=true). When a family is off, pkg-cache returns 404 naming the variable to enable.
Debian (apt, PKG_CACHE_APT=true)
Ubuntu (apt, PKG_CACHE_APT=true)
Covers amd64 (archive.ubuntu.com), security.ubuntu.com, and arm64 (ports.ubuntu.com/ubuntu-ports):
sed -i -e 's|http://archive.ubuntu.com/ubuntu/|http://pkg-cache.home.lan/ubuntu/|' \
-e 's|http://security.ubuntu.com/ubuntu/|http://pkg-cache.home.lan/ubuntu-security/|' \
-e 's|http://ports.ubuntu.com/ubuntu-ports/|http://pkg-cache.home.lan/ubuntu-ports/|' \
/etc/apt/sources.list.d/ubuntu.sources
apt-get update
Fedora and EPEL (dnf, PKG_CACHE_DNF=true)
Comment out metalink= and set baseurl= to your cache:
sed -i -e 's|^metalink=|#metalink=|' \
-e 's|^#baseurl=http://download.example/pub/fedora/linux|baseurl=http://pkg-cache.home.lan/fedora|' \
/etc/yum.repos.d/fedora.repo /etc/yum.repos.d/fedora-updates.repo
dnf makecache
Packages are still checked against Fedora's keys. The fedora-cisco-openh264 repository is Cisco's and keeps going straight to Cisco.
Once epel-release is installed:
sed -i -e 's|^metalink=|#metalink=|' \
-e 's|^#baseurl=https://download.example/pub/epel|baseurl=http://pkg-cache.home.lan/epel|' \
/etc/yum.repos.d/epel.repo
dnf makecache
Only EPEL comes through the cache; AlmaLinux, Rocky, or RHEL's own repositories go to their mirrors as before.
Alpine (apk, PKG_CACHE_APK=true)
sed -i 's|https://dl-cdn.alpinelinux.org/alpine|http://pkg-cache.home.lan/alpine|' /etc/apk/repositories
apk update
Packages are still checked against Alpine's keys.
Arch Linux (pacman, PKG_CACHE_PACMAN=true)
echo 'Server = http://pkg-cache.home.lan/archlinux/$repo/os/$arch' > /etc/pacman.d/mirrorlist
pacman -Syu
Packages are still checked against the Arch keyring.
3. Using the cache in a Containerfile
In a Containerfile, make the distribution's setup command above the first RUN instruction, before anything is installed.
4. Verifying cache hits from a client
Every proxied response includes an X-Cache-Status HTTP header (MISS, HIT, REVALIDATED, EXPIRED, STALE, or UPDATING):