Deploying pkgproxy

pkgproxy works without any configuration. This page covers what you can change if you need to. When something does not work, see docs/troubleshooting.md.

Where the cache lives

The snap keeps its cache in /var/snap/pkgproxy/common/cache, so the cache survives snap updates. There is one directory for each kind of download: apt, snap, go, docker and lxd.

Disk space

pkgproxy never deletes anything from its cache on its own, so the cache only grows. du -sh /var/snap/pkgproxy/common/cache/* shows how much each kind of download takes. To free the space a kind takes, stop pkgproxy, remove its directory and start pkgproxy again:

sudo snap stop pkgproxy
sudo rm -rf /var/snap/pkgproxy/common/cache/docker
sudo snap start pkgproxy

Clients download what is gone again the next time they need it. A full disk shows up as failed downloads with errors in the log; see docs/troubleshooting.md. Removing lxd also replaces the certificate of the LXD port, so run pkgproxyctl setup lxd-remote | sh again afterwards. Leave stats.json in place unless you also want to reset the statistics.

Changing settings

With the snap, change a setting with a snap option:

sudo snap set pkgproxy revalidate-ttl=10m

pkgproxy restarts to use the new value, and snap set rejects invalid values. sudo snap unset pkgproxy revalidate-ttl goes back to the default, and snap get pkgproxy shows what you have set.

Without the snap, use a command-line flag of the same name, such as pkgproxy -revalidate-ttl 10m, or an environment variable named PKGPROXY_ followed by the name in capitals with - replaced by _, such as PKGPROXY_REVALIDATE_TTL=10m. A flag wins over the environment. pkgproxy refuses to start if a value is invalid, and says which one. pkgproxy -help lists every flag.

Settings

Times are written like 90s, 10m or 1h30m.

Working offline

pkgproxy can stop contacting mirrors and registries:

• offline: pkgproxy serves only what it has cached and contacts nothing. Package lists are not refreshed. What is not cached fails quickly, without asking clients to wait (apt still makes its own retries, after 1, 2 and 4 seconds). Use it on a machine without network, or for a build that must see exactly what was cached.
• store-overloaded: pkgproxy stays online, but a mirror, store or registry that fails, times out or asks it to slow down is left alone for a while and tried again later. Meanwhile pkgproxy serves what it has cached.
• never, the default: pkgproxy goes online as needed.

With the snap, switch with either of these; they change the same setting, which is kept when pkgproxy restarts:

sudo snap set pkgproxy offline-mode=offline
pkgproxyctl offline mode store-overloaded

Neither restarts pkgproxy. pkgproxyctl offline on and pkgproxyctl offline off are short for the modes offline and never, and pkgproxyctl offline shows the mode.

Without the snap, pkgproxyctl offline switches the running pkgproxy until it restarts, and says so. Start pkgproxy with -offline-mode, or PKGPROXY_OFFLINE_MODE, to keep a mode. -offline is short for -offline-mode offline; pkgproxy refuses to start if the two name different modes.

apt older than 3.1.3, such as the apt of Ubuntu 24.04, can hang in apt update when one source fails and the others work, as a source that is not cached does while pkgproxy is offline (LP: #2003851). pkgproxyctl setup apt adds Acquire::Retries::Delay "false"; to /etc/apt/apt.conf.d/99pkgproxy on such a machine, so apt retries at once instead; pkgproxyctl setup apt -undo removes it with the rest. The apt configuration that setup lxd and setup snapcraft give LXD containers always has it, as one file serves every container.

Going offline with the machine

On Linux, pkgproxy goes offline by itself while the machine it runs on is offline, for example a laptop in airplane mode, and comes back when the machine does. The auto-offline setting chooses what counts as offline:

• network, the default: pkgproxy goes offline while the machine has no network at all: no route to the internet, which is what airplane mode, a pulled cable or a Wi-Fi network out of reach all lead to. Airplane mode with a cable plugged in, or with Wi-Fi turned back on in flight, is not offline.
• airplane-mode: pkgproxy goes offline while every radio (Wi-Fi, Bluetooth, mobile broadband) is off, whatever other network the machine has. A machine without radios is never in airplane mode. pkgproxy looks at the radios every few seconds, so one switched off without anything else changing is noticed within about ten seconds.
• off: pkgproxy goes offline only when you tell it to.

To turn going offline by itself off, run:

sudo snap set pkgproxy auto-offline=off

sudo snap unset pkgproxy auto-offline goes back to the default. Without the snap, start pkgproxy with -auto-offline off. Going offline by itself works on Linux only; elsewhere the default is off.

A change has to last five seconds before pkgproxy acts on it, so a network that drops for a moment, on resume or when roaming between access points, does not take it offline. While it is offline this way, pkgproxyctl offline says why, and which mode applies again once the machine is back. That mode is the setting above: going offline by itself does not change offline-mode. To go online anyway, run pkgproxyctl offline off or choose a mode; that holds until the machine next goes offline.

This follows the network of the machine, or container, pkgproxy runs in, which can take pkgproxy offline when you do not expect it:

• A network that only reaches a local mirror, with no route to the internet, counts as no network for network. Set auto-offline=off on such an isolated network.
• pkgproxy in a container sees only the container’s routes: it keeps its network when the host loses its own, and goes offline when the container has no default route, whatever the host has.

A network that is up but gets nowhere, such as a captive portal, does not count as offline, and is what store-overloaded is for.

After changing a port

If you change addr or lxd-tls-addr, run the pkgproxyctl setup commands from the README again so your tools use the new port. They ask pkgproxy which ports it uses. If pkgproxy is not running, they use the default ports, unless you pass -addr or -lxd-tls-addr.

Removing a cached file early

apt package lists are refreshed every few minutes on their own. To throw one away right now, or to throw away a package, give pkgproxyctl cache invalidate the http:// address apt downloads it from, with dists/ or pool/ in its path:

pkgproxyctl cache invalidate http://deb.debian.org/debian/dists/bookworm/InRelease

This works for apt only. The other kinds of download need it less:

• Snaps, Go modules, LXD images and Docker image layers are checked against their published hashes before pkgproxy keeps them, so a broken download is never kept.
• What changes over time (snap information, Go module version lists, LXD image lists and Docker tags) is checked again after snap-revalidate-ttl, go-revalidate-ttl, lxd-revalidate-ttl and docker-revalidate-ttl, five minutes by default. In offline mode it is not checked at all.
• To drop everything of one kind right now, remove its directory as shown in Disk space.

Running pkgproxy without the snap

The snap is the easiest way to run pkgproxy, but it is a single Go program you can also build yourself, with Go installed:

go install gitlab.com/zygoon/pkgproxy/cmd/pkgproxy@latest
ln -s pkgproxy "$(go env GOPATH)/bin/pkgproxyctl"

pkgproxyctl is the same program under another name. Run pkgproxy as root, from a system service of your own. It keeps its cache in /var/cache/pkgproxy (change that with -cache-dir) and the sockets pkgproxyctl talks to in /run/pkgproxy. One of them, stats.sock, serves the statistics behind pkgproxyctl stats to your own scripts too; see docs/statsapi.md.