The aria2 proxy options are built for HTTP, and on a build server that is their strength. --all-proxy sends aria2's HTTP, HTTPS and FTP downloads through one proxy, which is exactly what a pipeline pulling Linux images from a mirror needs when policy requires egress through a named exit. The BitTorrent side is a different story. aria2 can send announces to an HTTP tracker through the proxy and nothing else: peers are always contacted directly, and DHT and UDP trackers bypass any proxy. This guide covers both halves, so the egress statement for an aria2 job says what it actually does.
aria2 is a GPL-2.0 command-line downloader for HTTP, FTP, SFTP, BitTorrent and Metalink, with a JSON-RPC interface that other tools build on. The current release is 1.37.0, from 15 November 2023. Facts below are from aria2's manual, its issue tracker and its source; we did not run aria2 for this article.
Decide which half of aria2 the job uses
Before writing flags into a pipeline, answer three things in the change request:
- Is the job an HTTP download or a torrent? If a project publishes both, the mirror is almost always the better choice on managed infrastructure: one transfer, a checksum to verify, and no upload.
- If a torrent, is peer-to-peer egress permitted from this host? With aria2 that traffic will leave from the host's own address whatever proxy is set.
- What is the source? A distribution image, an open-source release, a dataset. Record the URL.
Peer-to-peer traffic for lawful content is fine on our residential exits and on dedicated ISP and datacenter addresses with no traffic meter, though aria2's peers would not use either. Our acceptable use policy prohibits using a ProxyForge exit to share material without the right to distribute it.
What a proxy can and cannot do for aria2
- Metering applies to what crosses the proxy. For a mirror download through
--all-proxy, that is the file, once. For a torrent, aria2's peers do not use the proxy, so the payload is not metered by us and is not masked either. How we count a gigabyte is in the FAQ. - No UDP, from either side. aria2 has "no proxy support for UDP traffic", and our gateways should be treated as TCP only for SOCKS5 anyway, with UDP relay unverified. An HTTP proxy, which is all aria2 speaks, cannot carry UDP.
- No encryption is added. The proxy relays what aria2 sends. HTTPS stays protected by TLS end to end, and anything that is not TLS is readable on the hop to the proxy.
- Anything outside the proxy shows the host's address. For aria2 that is every BitTorrent peer connection, DHT and UDP trackers.
- For copyright exposure, a proxy is the wrong control. Torrent client projects point users to a VPN; qBittorrent's wiki states it directly. The control that holds is the content.
The proxy flags
From the manual:
| Flag | Applies to |
|---|---|
--all-proxy=PROXY |
"Use a proxy server for all protocols" |
--http-proxy, --https-proxy, --ftp-proxy |
One protocol each |
--all-proxy-user, --all-proxy-passwd |
Credentials for --all-proxy |
--proxy-method=get or tunnel |
How requests are sent to the proxy |
The proxy format is [http://][USER:PASSWORD@]HOST[:PORT]. There is no socks5://: the manual never mentions SOCKS, and the "Support Socks proxies" issue has been open since 2013. Use the HTTP endpoint of our gateway with aria2.
Credentials on a command line are visible to other users of the host in the process list, and often end up in CI logs. Prefer authenticating the build host by IP allowlist, so the flags carry no password; IP allowlist vs username and password covers when that works and when it does not.
What the BitTorrent side does with a proxy
The maintainer's answer in the issue tracker is short: "aria2 can connect to tcp tracker via HTTP proxy. There is no proxy support for UDP traffic." aria2's source fills in the rest. PeerInitiateConnectionCommand.cc opens peer connections with establishConnection(getPeer()->getIPAddress(), ...), directly to the peer's own address.
| Traffic | Through --all-proxy |
|---|---|
| HTTP tracker announces | Yes |
| Peer connections | No, direct |
| DHT | No, direct |
| UDP trackers | No, direct |
The manual adds that --enable-dht "also enables UDP tracker support". Turning DHT off with --enable-dht=false therefore removes both of the UDP paths the manual ties to that flag; the capture below confirms nothing else is sent. Peers still connect directly, so the only way to keep an aria2 host's BitTorrent traffic inside the proxy is not to give it torrents.
A build-server pattern that fits
The pattern aria2 suits on managed infrastructure is the mirror download with a checksum. With the host allowlisted on our gateway:
aria2c --all-proxy="http://PROXY_HOST:PROXY_PORT" \
"https://MIRROR_HOST/path/to/image.iso" \
"https://MIRROR_HOST/path/to/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
The image crosses the proxy once, nothing is seeded, and the checksum file proves the bytes are the publisher's. Where the publisher signs the checksum file, verify the signature too. If the job does not actually need a named exit, drop the proxy and pull from the mirror directly; per-GB metering on a large image buys nothing in that case. The same request through curl is in our curl proxy guide.
Showing the difference on the host
To evidence both halves for a reviewer, run each once on a test host and watch the host's traffic outside the proxy:
sudo tcpdump -ni any 'not (host PROXY_IP and tcp port PROXY_PORT) and not port 22 and not net 127.0.0.0/8'
During the mirror download above, the capture should stay quiet. During a lawful torrent run with the same --all-proxy, it will not: TCP to peer addresses and, unless DHT is off, UDP to many addresses. In parallel, ss -tnp | grep aria2c lists the peer connections and their remote addresses. That second capture is the expected result, and attaching it to the review prevents anyone assuming the proxy covers the torrent. Confirm the exit address of the mirror path with the proxy checker.
Pipeline checklist
- Mirror download used where the project publishes one; torrent use justified otherwise
-
--all-proxypointed at the HTTP endpoint, with the host allowlisted - No proxy password on the command line or in CI logs
- Checksum, and signature where published, verified after download
- If torrents are used: peer-to-peer egress approved,
--enable-dht=falseset, and the review states peers go direct - Capture of each path attached
aria2 and Transmission are the two clients in this series that can only proxy tracker requests. See torrent client proxy support compared for the clients that can proxy peers.