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

```
pkg -vv | grep -E '^  [A-Za-z0-9_-]+: \{'
```

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

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

Swap `quarterly` for `latest` to track rolling packages. Packages are still checked against FreeBSD's keys in `/usr/share/keys/pkg`.

> [!WARNING]
>
> **Two rules for FreeBSD `pkg`**
>
> 1. **Use plain `http://`, not `pkg+http://`:** `pkg` on FreeBSD 15 rejects the `pkg+` scheme unless `mirror_type` is `srv`.
> 2. **Set `mirror_type: "none"`:** Leaving `mirror_type: "srv"` queries DNS `SRV` records and bypasses the cache.

### Caching `pkg audit` vulnerability checks (`VuXML`)

For `pkg audit`, fetch the FreeBSD vulnerability database through `/vuxml/` (cached for 1 hour):

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

---

## 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`)

```
sed -i 's|http://deb.debian.org/|http://pkg-cache.home.lan/|' /etc/apt/sources.list.d/debian.sources
apt-get update
```

```
sed -i 's|http://deb.debian.org/|http://pkg-cache.home.lan/|' /etc/apt/sources.list
apt-get update
```

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

```
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
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`):

```
curl -sI http://pkg-cache.home.lan/FreeBSD:15:amd64/quarterly/meta.conf | grep -i x-cache-status
# First request:  X-Cache-Status: MISS
# Second request: X-Cache-Status: HIT
```
