Skip to content

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.

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