Skip to content

FreeBSD FreeBSD amd64 · arm64 Linux Linux amd64 · arm64 Caches pkg · apt · dnf · apk · pacman

Package Cache

MISS · 20 jails pulling pkg.FreeBSD.org over WAN → HIT · Served from local LAN · 365d cached · verified

Pull every package once. Serve it to your hosts, jails, VMs, and container builds over your LAN.

Caching proxy appliance for FreeBSD pkg (including pkg audit VuXML) and Linux apt, dnf, apk, and pacman. No nginx.conf to write, a live stats page with copy-paste client commands on port 80, and package signature verification kept on every client.

http://pkg-cache.home.lan/: Live stats and client setup Light and dark theme
PACKAGE CACHE stats.json · healthz
All good: caching FreeBSD, Debian and Ubuntu, Fedora and EPEL, Alpine; 84 % of requests served from here.
Served from cache
84%
10,492 of 12,490 requests
Bandwidth saved
48.2 GB
9.4 GB fetched upstream in 1,998 requests
Disk
18.6 GBused
37 % of 50.0 GB · 4,120 files
What it caches
FreeBSDpkg · 8,910 requests, 86 % from here, 34.1 GB served
On
Debian and Ubuntuapt · 2,140 requests, 81 % from here, 9.6 GB served
On
Fedora and EPELdnf · 1,120 requests, 79 % from here, 3.8 GB served
On
Alpineapk · 320 requests, 88 % from here, 712 MB served
On
Recent requests
HIT FreeBSD:15:amd64/latest/All/llvm19-19.1.7.pkg 284.6 MB
HIT debian/pool/main/p/python3.13/libpython3.13_amd64.deb 2.1 MB
HIT fedora/updates/43/Everything/x86_64/Packages/podman.rpm 15.8 MB
REVALIDATED FreeBSD:15:amd64/latest/packagesite.tzst 7.9 MB
MISS alpine/v3.23/main/aarch64/busybox-1.37.0-r9.apk 518 KB

Open http://<cache-host>/ in a browser for live hit rates, top clients, and pre-filled client setup commands · View first-boot UI screenshot

Platforms

Runs on FreeBSD and Linux

One multi-OS manifest tag, ghcr.io/daemonless/pkg-cache:latest, resolves to a FreeBSD jail image or a Linux container on both amd64 and arm64.

FreeBSD FreeBSD

amd64arm64

Built on FreeBSD nginx-base. Put /cache on a ZFS dataset and serve packages to hosts, jails, and Containerfile builds on your network.

fjord Podman + ocijail AppJail Director Bastille

Linux Linux

amd64arm64

Built on Linux (Alpine) with nginx and s6, running the same startup config renderer, repository switches, log rotator, and stats landing page on amd64 and arm64.

fjord Podman

Repositories

One cache for FreeBSD and Linux

FreeBSD pkg and pkg audit are active by default. Set one environment variable per family to cache Linux packages alongside FreeBSD.

FreeBSD FreeBSD

On by default

Caches quarterly and latest binary packages across FreeBSD releases and ABIs (amd64, aarch64), plus the pkg audit vulnerability database (vuxml.freebsd.org).

/${ABI}/quarterly /${ABI}/latest /vuxml/

Debian Debian and Ubuntu

PKG_CACHE_APT=true

Proxies apt repositories including security channels and ubuntu-ports (arm64), keeping .deb pools and by-hash indexes for a year while refreshing dists/ every minute.

/debian/ /debian-security/ /ubuntu/ /ubuntu-security/ /ubuntu-ports/

Fedora Fedora and EPEL

PKG_CACHE_DNF=true

Proxies dnf RPM packages and checksummed repodata/ for 365 days while revalidating repomd.xml every minute.

/fedora/ /epel/

Alpine Linux Alpine Linux

PKG_CACHE_APK=true

Proxies Alpine apk repositories, caching versioned .apk packages for 365 days and refreshing APKINDEX.tar.gz every minute.

/alpine/

Arch Linux Arch Linux

PKG_CACHE_PACMAN=true

Serves as pacman's local mirror, caching .pkg.tar.* archives and .sig files for 365 days while refreshing .db and .files every minute.

/archlinux/

Containerfiles

First RUN

In a Containerfile, put the distribution's setup command in the first RUN instruction, before anything is installed, so image builds pull cached packages over your LAN.

Containerfile

How it works

Cached packages, fresh indexes, verified signatures

Public mirrors often send Cache-Control: no-cache or redirect clients away, while generic proxies can serve stale package indexes. Package Cache sets separate rules for package files and metadata.

01 / Immutable packages

Cached for 365 days

*.pkg · *.deb · *.rpm · *.apk · *.zst

Package filenames include their version and are immutable once published. The first machine pulls upstream (MISS); later requests get a local HIT, with automatic LRU eviction at PKG_CACHE_SIZE.

02 / Live indexes and lock coalescing

1-minute metadata and stale fallback

proxy_cache_lock · use_stale 5xx

Catalogs (packagesite.tzst, dists/, repomd.xml, APKINDEX.tar.gz) refresh after 1 minute using If-Modified-Since. When several machines fetch the same uncached file at once, proxy_cache_lock sends one upstream download and serves cached copies during upstream 5xx errors.

03 / End-to-end verification

Client signatures stay enabled

/usr/share/keys/pkg · GPG · pacman-key

Signature checking stays on every client. FreeBSD pkg fingerprints, Debian and Ubuntu apt keys, Fedora RPM GPG keys, Alpine keys, and the Arch keyring verify packages on the client before install.

Client setup

Point hosts, jails, and builds at the cache

Open http://<cache-host>/ in a browser for commands filled in with your cache's address, or copy them below. See Client setup for full details.

Drop /usr/local/etc/pkg/repos/FreeBSD.conf on any FreeBSD host or jail. Use FreeBSD-ports on FreeBSD 15 (check pkg -vv) or FreeBSD on FreeBSD 14, and use plain http:// with mirror_type: "none":

mkdir -p /usr/local/etc/pkg/repos
cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<'EOF'
FreeBSD-ports: {
  url: "http://pkg-cache.home.lan/${ABI}/quarterly",
  mirror_type: "none",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}
EOF
pkg update

Fetch the pkg audit vulnerability database through the cache too:

echo 'VULNXML_SITE = "http://pkg-cache.home.lan/vuxml/vuln.xml.xz";' >> /usr/local/etc/pkg.conf

Turn on PKG_CACHE_APT=true on the cache, then point apt at it:

# Debian 12 and later (/etc/apt/sources.list.d/debian.sources)
sed -i 's|http://deb.debian.org/|http://pkg-cache.home.lan/|' /etc/apt/sources.list.d/debian.sources
apt-get update
# Ubuntu 24.04 and later (archive, security, and 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

Turn on PKG_CACHE_DNF=true on the cache (with a non-redirecting PKG_FEDORA_UPSTREAM mirror), then switch dnf from metalink to baseurl:

# Fedora
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
# EPEL (AlmaLinux, Rocky, RHEL)
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

Turn on PKG_CACHE_APK=true or PKG_CACHE_PACMAN=true on the cache:

# Alpine (apk)
sed -i 's|https://dl-cdn.alpinelinux.org/alpine|http://pkg-cache.home.lan/alpine|' /etc/apk/repositories
apk update
# Arch Linux (pacman)
echo 'Server = http://pkg-cache.home.lan/archlinux/$repo/os/$arch' > /etc/pacman.d/mirrorlist
pacman -Syu

Install

Deploy on FreeBSD or Linux

Mount persistent /config and /cache directories, publish port 80, and open http://<cache-host>/.

  1. Open fjord on your FreeBSD or Linux host.
  2. Find Daemonless pkg cache in the catalog and click Install.
  3. Turn on any Linux repository switches (PKG_CACHE_APT, PKG_CACHE_DNF, PKG_CACHE_APK, PKG_CACHE_PACMAN) in Settings if you also cache Linux machines, then open http://<host-ip>/.
services:
  pkg-cache:
    image: ghcr.io/daemonless/pkg-cache:latest
    container_name: pkg-cache
    restart: unless-stopped

    environment:
      - TZ=UTC
      - PKG_UPSTREAM=pkg.FreeBSD.org
      - PKG_CACHE_SIZE=50g
      - SKIP_CHOWN=true
      - PKG_LOG_MAX_SIZE=50m
      - PKG_CACHE_APT=${PKG_CACHE_APT:-false}
      - PKG_CACHE_DNF=${PKG_CACHE_DNF:-false}
      - PKG_CACHE_APK=${PKG_CACHE_APK:-false}
      - PKG_CACHE_PACMAN=${PKG_CACHE_PACMAN:-false}

    volumes:
      - /containers/pkg-cache:/config
      - /containers/pkg-cache/cache:/cache

    ports:
      - 80:80

Start it with podman-compose up -d, then open http://<server>:80. For FreeBSD pf port forwarding, boot auto-start (restart: always), interactive path placeholders, and AppJail Director or Bastille bundles, see the Host setup guide and the Daemonless pkg cache image page.

podman run -d --name pkg-cache \
  --restart always \
  -p 80:80 \
  -e PKG_UPSTREAM=pkg.FreeBSD.org \
  -e PKG_CACHE_SIZE=50g \
  -v /containers/pkg-cache:/config \
  -v /containers/pkg-cache/cache:/cache \
  ghcr.io/daemonless/pkg-cache:latest

See the Daemonless pkg cache image page for AppJail Director and Bastille deployment files.

Documentation

Setup and operations guides

Storage sizing, ZFS setup, client commands for FreeBSD and Linux, mirror selection, and /stats.json monitoring.

1

Size `/cache`

Default PKG_CACHE_SIZE is 50g (about 10G per FreeBSD release and architecture; give it more with Linux families on).

2

Start the appliance

Deploy on port 80 with persistent /config and /cache volumes.

3

Pick mirrors

Point PKG_UPSTREAM and optional Linux mirror variables at non-redirecting mirrors near you.

4

Point your clients

Run the client command for each machine or Containerfile, then watch hits at http://<cache-host>/.