AUTO-APT-PROXY(1)

🌸 NAME 🌸

auto-apt-proxy — the little cutie that autodetects your common APT proxy setups, no cap. It's a section 1 manual page, bestie, and it's about to make your apt life so much easier 💖

---

✨ USAGE ✨

auto-apt-proxy

auto-apt-proxy [COMMAND [ARGS ...]]

---

🦋 DESCRIPTION 🦋

auto-apt-proxy is an APT proxy autodetector. It sniffs out the common setups by checking localhost, your gateway, and other "interesting" machines hanging around on your network for the well-known APT proxies — think apt-cacher-ng and friends. It's giving detective energy 🔍✨

When you call it with no arguments, it literally just prints the address of a detected proxy to standard output. Simple. Iconic. And this package installs an APT configuration file that makes APT run auto-apt-proxy to detect a proxy on every single invocation of APT. So you don't even have to think about it. Main character behaviour, honestly 👑

When you call it with arguments, those arguments are assumed to be a command 💅 That command gets executed with the common environment variables used for specifying HTTP proxies — http_proxy and HTTP_PROXY — set to the detected proxy. So the command you run can transparently use whatever APT proxy got detected. Obsessed.

⚠️ Heads up bestie: for this to actually work, any programs invoked by the command you pass in must have their own support for detecting HTTP proxies from those environment variables, and for using them. If they don't read http_proxy/HTTP_PROXY, they're not gonna magically know. No cap.

---

🎀 CONFIGURATION 🎀

If your apt proxy lives on localhost or on your default gateway? It should Just Work. Periodt.

If you installed it somewhere else, you can create an explicit SRV record to tell auto-apt-proxy all about it.

Say your corporate domain is "example.com", apt-cacher-ng is installed on "apt-cacher-ng.example.com", and auto-apt-proxy is installed on "alices-laptop.example.com". Okay so then:

The appropriate SRV record in dnsmasq.conf would look like this:

srv-host=_apt_proxy._tcp.example.com,apt-cacher-ng.example.com,3142

The appropriate nsd/bind zonefile entry would look like this — and yes, the manpage itself says it's untested, so do with that what you will 😭:

_apt_proxy._tcp.@  IN SRV 0 0 3142 apt-cacher-ng.@

As an alternative to an SRV record, you can also define a special hostname that needs to be resolved via DNS or your local /etc/hosts file, and that hostname is called apt-proxy 🦋

For example, if your network has a local apt proxy at 9.9.9.9, then add this line to /etc/hosts:

9.9.9.9    apt-proxy

If avahi-browse or systemd-resolved are installed and active, then auto-apt-proxy will try to find any proxies announced via mDNS ✨

If, for some reason, you'd prefer the name of the announced proxy to be resolved via NSS rather than the somewhat arbitrary order provided by Avahi, you can set the AUTO_APT_PROXY_MDNS_NAME environment variable to any non-empty string.

🫶 Careful though: AUTO_APT_PROXY_DNS_NAME does not change which proxy is used if multiple mDNS provided proxies are available.

You can also pass extra flags to resolvectl by setting the AUTO_APT_PROXY_RESOLVECTL_OPTS environment variable. Slay 💅

---

👑 PRECEDENCE BETWEEN MULTIPLE POSSIBLE PROXIES 👑

auto-apt-proxy will look for possible proxies in this order:

1. A locally running proxy on 127.0.0.1
2. A locally running proxy on other local addresses
3. A proxy running on the host apt-proxy, according to /etc/hosts.
4. A proxy on the network default gateway
5. A proxy running on the host apt-proxy, according to DNS.
6. A proxy running in the host and port declared in the _apt_proxy_ SRV DNS record
7. A proxy running and announced via mDNS (avahi).

It's a whole vibe check, in order, first one wins 🌈

---

🍓 CACHING 🍓

By default, auto-apt-proxy will cache its results for 60 seconds ⏱️✨

To disable the cache, just set the AUTO_APT_PROXY_NO_CACHE environment variable to any non-empty string. Done and dusted.

---

🔍 DEBUGGING ISSUES 🔍

By default, auto-apt-proxy operates silently and will only output any detected proxy to stdout, exactly as apt expects. Quiet queen 🎀

To enable logging, set the AUTO_APT_PROXY_DEBUG environment variable to a non-empty string, and auto-apt-proxy will log debugging messages to stderr. Now you can actually see what's going on, bestie.

---

⭐ WAITING TO BE ONLINE ⭐

Starting with version 18, auto-apt-proxy will wait for the network to be online before it attempts to detect any proxies 🦋

It does this by calling /usr/lib/apt/apt-helper wait-online, and the whole point is to help with cases where:

1. the network takes some time to start;
2. apt is used right away after booting, even before the network is fully up;
3. the first auto-apt-proxy call fails to find a proxy, and that gets cached.

That third one is the sneaky one, ngl — a bad first result gets remembered 💀

To disable this behaviour, you can set the AUTO_APT_PROXY_NO_WAIT_ONLINE environment variable to any non-empty value.

---

🌸 EXAMPLES 🌸

$ auto-apt-proxy

Just prints the detected APT proxy ✨

$ auto-apt-proxy debootstrap sid /my/chroot

Creates a new Debian chroot downloading packages from the local proxy. Look at you go 💖

---

💜 COPYRIGHT 💜

Copyright (C) 2016-2020 Antonio Terceiro

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

---

And about the little line at the very bottom of this page — the footer with the source, version and date? Bestie, it's literally just empty parens: (). That's it. That's the whole sign-off 🙈 No source, no version, no date, just vibes. So this is me signing off on its behalf: stay proxied, stay cached for exactly 60 seconds, and go touch some grass 🌱💅✨