[![Daemonless Package Cache](<https://daemonless.io/pkg-cache/logo.svg>)](<https://daemonless.io/pkg-cache/logo.svg>)

FreeBSD amd64 · arm64  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.

[Install](<#install>) [Setup and ZFS guide](<https://daemonless.io/pkg-cache/setup/index.md>) [Client commands](<#clients>) [Image spec](<https://daemonless.io/images/pkg-cache/index.md>)

http://pkg-cache.home.lan/: Live stats and client setup Light and dark theme

**P**ACKAGE 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

**FreeBSD**pkg · 8,910 requests, 86 % from here, 34.1 GB served

On

**Debian and Ubuntu**apt · 2,140 requests, 81 % from here, 9.6 GB served

On

**Fedora and EPEL**dnf · 1,120 requests, 79 % from here, 3.8 GB served

On

**Alpine**apk · 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 ·

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

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

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

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 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 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

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

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](<https://daemonless.io/pkg-cache/clients/index.md>) 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](<https://fjord.daemonless.io>)** 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](<https://daemonless.io/pkg-cache/setup/index.md>) and the [Daemonless pkg cache image page](<https://daemonless.io/images/pkg-cache/index.md>).

```
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](<https://daemonless.io/images/pkg-cache/index.md>) 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>/`.

FreeBSD and Linux setup, ZFS dataset creation, cache sizing, and all `PKG_*` environment variables.

Client commands for FreeBSD 14 and 15 (`FreeBSD-ports`, `pkg audit`), Debian, Ubuntu, Fedora, EPEL, Alpine, Arch, and `Containerfile` builds.

Upstream mirror selection, why redirecting mirrors bypass caches, `/stats.json` and `/healthz` schemas, log rotation, and common fixes.

Downloadable Podman Compose, AppJail Director, and Bastille bundles with path and port placeholders.

**Open source (`BSD-2-Clause`)**: built on `nginx` (`nginx-base` on FreeBSD, Linux (Alpine) with `nginx` and `s6` on Linux).
