Ubuntu — Apt-Cacher NG Package Cache

Apt-Cacher NG is a caching proxy for apt packages. All machines on your LAN point to it — the first machine that downloads a package stores it in the cache, every subsequent download is served locally. Useful in a homelab with multiple VMs or bare-metal hosts running Ubuntu/Debian.

How It Works

Clients do not change their package sources — they keep archive.ubuntu.com and friends. Instead, apt is told to send its HTTP requests through a proxy. Apt-Cacher NG receives the request, fetches the package from the real mirror on first demand, stores it, and serves every later request for the same file from disk. Ten VMs running apt upgrade after patch day download each package from the internet exactly once.

This proxy design has one structural limitation: HTTPS cannot be cached. TLS encrypts the connection end-to-end precisely so that nobody in the middle can read or alter it — which is exactly what a caching proxy would need to do. For HTTPS repositories (Docker, Microsoft, HashiCorp), Apt-Cacher NG can only open a blind tunnel (PassThroughPattern) or be bypassed entirely. That is fine in practice: the bulk of traffic — the main Ubuntu/Debian mirrors — is plain HTTP, secured not by TLS but by GPG signatures on the package indexes, which apt verifies regardless of how the bytes arrived.

Pre-requisites

One dedicated Ubuntu host to act as the cache server (the VM running your other services is fine)
All clients on the same LAN or subnet
Ports: 3142/tcp (apt-cacher-ng)

Server Setup

Install

sudo apt update
sudo apt install apt-cacher-ng -y
sudo systemctl enable --now apt-cacher-ng

Verify:

sudo systemctl status apt-cacher-ng

Active: active (running)

Configure `/etc/apt-cacher-ng/acng.conf`

The defaults work out of the box. These are the settings worth reviewing:

sudo nano /etc/apt-cacher-ng/acng.conf

Key options (uncomment or adjust as needed):

# Cache location — keep the default unless you have a separate data volume
CacheDir: /var/cache/apt-cacher-ng

# Port — default 3142, leave it
Port: 3142

# Bind to a specific interface to avoid exposing on all adapters
# Replace with your server's LAN IP
BindAddress: 192.168.1.10 localhost

# Max cache size in MB — 0 means unlimited
# Set a limit if disk space is a concern (example: 50 GB)
CacheSizeMax: 50000

# HTTPS passthrough — see section below

After changes, restart:

sudo systemctl restart apt-cacher-ng

HTTPS Passthrough

Apt-Cacher NG cannot cache HTTPS traffic — it can only tunnel it. Add a PassThroughPattern for any HTTPS repositories your clients use:

sudo nano /etc/apt-cacher-ng/acng.conf

# Allow HTTPS tunneling for common repositories
PassThroughPattern: (security\.ubuntu\.com|packages\.microsoft\.com|download\.docker\.com|apt\.releases\.hashicorp\.com):443

Note

HTTPS content is tunneled, not cached. Only HTTP repositories (the majority of Ubuntu/Debian mirrors) benefit from caching. Adding specific domains keeps the passthrough explicit and auditable.

Restart after editing:

sudo systemctl restart apt-cacher-ng

Firewall (UFW)

Allow port 3142 from your LAN only:

sudo ufw allow from 192.168.1.0/24 to any port 3142 proto tcp
sudo ufw reload

Client Configuration

On every machine that should use the cache, create a one-line proxy config file:

echo 'Acquire::http::Proxy "http://192.168.1.10:3142";' | \
  sudo tee /etc/apt/apt.conf.d/01proxy

Replace 192.168.1.10 with the IP of your cache server.

For HTTPS repositories, tell apt to connect directly (not through the proxy):

cat <<'EOF' | sudo tee /etc/apt/apt.conf.d/01proxy
Acquire::http::Proxy "http://192.168.1.10:3142";
Acquire::https::Proxy "DIRECT";
EOF

Test

sudo apt update

Watch the cache server's log to confirm traffic is being received:

sudo tail -f /var/log/apt-cacher-ng/apt-cacher.log

On a cache hit you will see HIT next to the package URL; on a first download you will see MISS followed by the download — subsequent clients get HIT.

Web Interface

Apt-Cacher NG ships a built-in stats and management page:

http://192.168.1.10:3142/acng-report.html

From here you can:

View cache statistics and hit rate
Trigger manual cache expiration (removes stale index files)
Import locally-downloaded .deb files into the cache

Maintenance

Expire stale files

Cached index files (.InRelease, Packages.gz) become stale over time. Expire them via the web interface or from the command line:

sudo apt-get -o Acquire::http::Proxy="http://localhost:3142" \
  -o Acquire::http::No-Cache=true update

The server automatically cleans up unneeded files during normal operation. For a manual purge of the entire cache:

sudo systemctl stop apt-cacher-ng
sudo rm -rf /var/cache/apt-cacher-ng/*
sudo systemctl start apt-cacher-ng

Check cache size

du -sh /var/cache/apt-cacher-ng/

Common Issues

Symptom	Cause	Fix
`apt update` slow / hangs	Cache server unreachable	Check `systemctl status apt-cacher-ng`, verify UFW rule
`Hash Sum mismatch` errors	Stale index files in cache	Use the web interface to expire cache, or run `sudo apt clean` on the client
HTTPS repositories fail	Missing `PassThroughPattern`	Add the domain to `PassThroughPattern` in `acng.conf` and restart
Port 3142 not reachable from clients	Wrong `BindAddress`	Set `BindAddress` to your server's LAN IP (not just `localhost`)
Client downloads directly, ignores proxy	`/etc/apt/apt.conf.d/01proxy` missing or wrong path	Verify file exists and contains the correct proxy line