apt-cacher-rs

July 20, 2026 ยท View on GitHub

Version info License: MIT

apt-cacher-rs is a simple caching proxy daemon for Debian-style repositories. It is inspired by and an alternative to apt-cacher and apt-cacher-ng.

Build the Debian package

Before you can create a Debian package, the following commands must be run once to install the necessary dependencies:

apt-get -y install dpkg-dev
cargo install cargo-deb

Then run the following command to build the Debian package in target/debian/apt-cacher-rs.deb:

cargo deb

Build container image

apt-cacher-rs can be easily run inside a container.

Build an image with the following command based on the in-tree Dockerfile:

podman build -t apt-cacher-rs:dev -f Dockerfile .

The image expects a volume mounted at /data to store the database and cached files. You must also provide a configuration file via a mount on /app/apt-cacher-rs.conf: the entrypoint passes this path explicitly, so the file must exist, and the built-in defaults do not permit any mirrors anyway. For example you can start a container via:

podman run -p 3142:3142/tcp --read-only --rm -v apt-cacher-rs-data:/data:nodev,noexec,nosuid -v /srv/apt-cacher-rs.conf:/app/apt-cacher-rs.conf:ro apt-cacher-rs:dev

The image's ENTRYPOINT hard-codes --config-file=/app/apt-cacher-rs.conf, --cache-path=/data/cache and --database-path=/data/apt-cacher-rs.db; any extra arguments passed to podman run are appended after these flags. To use different paths, override the entrypoint via --entrypoint.

Command-line options

The most relevant flags (see apt-cacher-rs --help for the full list):

  • --config-file=<PATH>: path to the configuration file (default /etc/apt-cacher-rs/apt-cacher-rs.conf). If the default file is missing the built-in defaults are used; a missing non-default file is an error.
  • --cache-path=<PATH>: overrides the cache_directory field from the configuration file (or its default).
  • --database-path=<PATH>: overrides the database_path field from the configuration file (or its default).

How to use

Install the Debian package via dpkg on a local network server and add the following configuration file on every client system that should utilize the proxy:

/etc/apt/apt.conf.d/30proxy

Acquire::http::Proxy "http://<proxy_ip>:3142/";

If your sources contain HTTPS repositories you would like to cache as well, change their URL scheme to http:// to cache their packages. Note that connections from the client to the proxy are unencrypted (but all packages are by default verified by apt(8) after download to have a valid GPG signature).

Web interface

apt-cacher-rs contains a minimal web interface for some statistics at http://<proxy-ip>:3142/, and important logs can be viewed at http://<proxy-ip>:3142/logs.

Cleanup

Packages in the cache that are no longer referenced by any known upstream repository are pruned every 24h, unless they have been downloaded less than 3 days ago. The list of known upstream repositories is gathered by inspecting proxied package list requests (i.e. by apt update). The cleanup can also be manually triggered by sending the signal USR2 to the apt-cacher-rs process.

apt-cacher-rs also reacts to these maintenance signals:

  • USR1: reopen the active log file (when logging to a file)

Crate features

apt-cacher-rs exposes several optional cargo features (the default set is mmap, tls_rustls, sendfile):

  • mmap (default): serve cached files via memory-mapped I/O (memmap2).
  • sendfile (default): serve cached files to clients with zero-copy sendfile(2).
  • tls_rustls (default): use rustls as the TLS backend for upstream connections.
  • tls_hyper: use the system-provided TLS implementation (hyper-tls/native TLS) instead of rustls; disable default features when enabling this.
  • webpki-roots: bundle Mozilla's CA root set with rustls instead of relying on the system trust store.
  • splice: proxy upstream responses to clients using splice(2) (implies sendfile).
  • ktls: offload TLS encryption to the kernel via kTLS (implies splice and tls_rustls). Requires Linux >= 4.17 (kernel TLS receive offload) with the tls kernel module available (auto-loaded on first use; modprobe tls if module loading is restricted). TLS 1.3 and AES-256-GCM need >= 5.1, ChaCha20-Poly1305 >= 5.11. Recommended: >= 6.0 (reworked RX path and the TLS_RX_EXPECT_NO_PAD optimization, used when available).

Security

The proxy interface should not be made publicly available to the internet or completely untrusted clients. That could lead to Denial of Service issues, like congesting the network traffic or exhausting the filesystem's capacity.

License

MIT License