Learn Aria2 - Proxy & Networking

#Introduction

In episodes 10 and 11 you handled BitTorrent and metalink, then took control of where files are stored — directories, names, and output structure. Up to that point, one assumption always stood still: aria2's connections go straight to the destination server. In the real world this assumption is often wrong. Corporate offices, universities, and some ISPs force all traffic through a gateway called a proxy — and if you don't know how to talk to it, your downloads hang in silence.

Episode 12 opens up the network layer that until now you've taken for granted: how aria2 finds its way to the server, whether or not it goes through a proxy, which interface it exits from, and how DNS helps determine the speed of the parallel connections we've been building since episode 5.

#Proxy: The Receptionist at the Gate

Imagine an office with one reception desk. All packages go in and out through that desk; the receptionist decides which package may leave, where to, and sometimes keeps a copy so it doesn't need to be ordered twice. A proxy works exactly like that: an intermediary that receives your requests, relays them to the destination server, then forwards the replies back. It's used for filtering (blocking certain domains), caching (keeping copies to save bandwidth), and audit (recording all access).

Because aria2 often runs automatically and in automation, understanding the proxy isn't an add-on — it's a prerequisite. Without correct configuration, every download behind a corporate firewall will fail with an unhelpful message.

#aria2 Does Not Read Environment Proxies

This is one of the most deceptive differences from other download tools: aria2 does not read environment variables like http_proxy or https_proxy. You can export http_proxy all day and aria2 will keep ignoring it. Every proxy must be specified explicitly through options. This is also good news: your download behavior can be predicted and won't silently change because of the environment.

#Four Options, One Format

aria2 distinguishes traffic destinations with four options, all accepting the http://host:port format (with user:pass@ when authentication is needed):

When none of the first three options is set and --all-proxy is absent, aria2 connects directly without an intermediary. Most cases only need --all-proxy — one line covering HTTP, HTTPS, and FTP at the same time.

#`--all-proxy`: Set Once for Everything

all-proxy.sh

aria2c --all-proxy="http://proxy.contoh.local:8080" \
  https://cdn.example.com/file.zip

This single option replaces three options at once. --all-proxy is also a convenient catch-all: because it works for all protocols, one proxy value applies to HTTP, HTTPS, and FTP downloads without repeating the configuration in every command.

#Sorting Destinations: HTTP, HTTPS, and FTP

Sometimes each protocol has its own path — for example HTTP and HTTPS go through a corporate proxy while FTP goes through a dedicated one. That's where the three specific options win:

aria2c --http-proxy="http://proxy.contoh.local:8080" \
  --https-proxy="http://proxy.contoh.local:8080" \
  https://cdn.example.com/file.zip

Notice the small detail above: FTP often has its own proxy, because FTP traffic is frequently directed to a dedicated gateway. When you mix protocols in one invocation, per-protocol options give the most precise control.

#`--no-proxy`: Per-Host Exceptions

Forcing all traffic through a proxy can sometimes get in the way — especially for internal hosts already reachable directly. The --no-proxy option lists exceptions: hosts to reach without an intermediary.

no-proxy.sh

aria2c --all-proxy="http://proxy.contoh.local:8080" \
  --no-proxy="localhost,127.0.0.1,192.168.1.0/24" \
  http://nas.contoh.local/film.mkv

--no-proxy accepts a comma-separated list: host names, domain names, or network addresses with a subnet mask — and * means all hosts. Note that these exceptions are per-invocation; for standing patterns, put them in the configuration file so they aren't rewritten in every command.

Tip

Because aria2 doesn't read environment proxies, the best habit is writing all proxy options in the aria2.conf file (episode 9) with http-proxy, https-proxy, ftp-proxy, all-proxy, and no-proxy. One file, valid for every invocation.

#Proxy Authentication

Many corporate proxies don't just let anyone through — they demand proof of identity. When a proxy requires authentication, it replies with status 407 Proxy Authentication Required, and aria2 needs credentials. Two ways to provide them:

proxy-auth.sh

aria2c --all-proxy="http://proxy.contoh.local:8080" \
  --proxy-user=budi --proxy-passwd=rahasia \
  https://cdn.example.com/file.zip

Credentials can also be embedded directly in the proxy URL: --all-proxy="http://budi:rahasia@proxy.contoh.local:8080". Both are valid, but the warning from episode 9 still applies: never write literal passwords on the command line or in files that enter git — shell history and git history are never truly clean. For scripts, read credentials from the environment or from a configuration file with locked-down permissions.

#Choosing the Outbound Path: `--interface` and `--bind-address`

On machines with many interfaces — a laptop with both wifi and ethernet, a server with several NICs — aria2 picks an outbound address automatically. Two options give manual control:

interface.sh

aria2c --interface=eth0 https://cdn.example.com/file.zip

bind-address.sh

aria2c --bind-address=10.0.1.20 https://cdn.example.com/file.zip

--interface=eth0 accepts an interface name, an IP address, or a hostname; --bind-address=10.0.1.20 only accepts an IP address. Practical uses: forcing egress through an interface with lots of bandwidth, or through an IP registered in the destination server's allowlist. These choices are rarely needed on a laptop, but they make a real difference in production environments with complex routing.

#`--reuse-uri`: When Sources Run Dry

On multi-mirror downloads (especially the metalink from episode 11), aria2 has an interesting choice when all URIs appear to fail: --reuse-uri. By default (false), aria2 won't reuse a URI that has already failed — it looks for another source not yet tried. With --reuse-uri=true, it's willing to try an old URI again when no other options remain.

reuse-uri.sh

aria2c --reuse-uri=true file.metalink

It's like searching for water in a desert: by default aria2 moves to the next well when one is dry; with --reuse-uri=true, it's willing to draw again from the old well if all the others are spent. The default is already right for most cases — enable it only if you know the old source has recovered.

#DNS: Behind the Speed of Parallel Connections

Before a single byte moves, the domain name must be translated into an IP address — the job of DNS (Domain Name System). This stage determines speed and reliability more than you might think, especially since episode 5 you've been pulling downloads from many connections at once.

Parallel connections aren't purely a client matter — the destination server also sets limits. If the host has only one IP address, all your connections pile onto the same address, and the server or ISP may throttle. If the host uses a CDN with many IP addresses, aria2 spreads connections across several IPs at once — one reason why CDN downloads feel far faster.

Two options strengthen aria2's DNS side:

--async-dns=true (default) — DNS resolution runs asynchronously, not blocking other connections while waiting for a resolver answer.
--dns-timeout=SEC — the resolver wait limit. Without a reasonable bound, a hung resolution can stall a download for hours.

dns-options.sh

aria2c --async-dns=true --dns-timeout=5 \
  -x 16 -s 16 https://cdn.example.com/distro.iso

Important

If raising -x doesn't increase speed, don't rush to raise it again — first check whether the destination server has only one IP. Switching the source to a mirror or CDN with many addresses usually gives a bigger speed jump than adding connections to the same server.

#Closing

Episode 12 dissected the network layer you'd been taking for granted: going through a proxy with --http-proxy, --https-proxy, --ftp-proxy, and --all-proxy, bypassing it per host with --no-proxy, authenticating to the proxy with --proxy-user and --proxy-passwd, choosing the outbound path with --interface and --bind-address, understanding --reuse-uri, and DNS's role in parallel connection speed.

The key thing to remember: the network path isn't destiny — it's configuration. Every layer between aria2 and the server can be controlled, and every uncontrolled layer is an invisible point of failure.

In the next episode, episode 13, we climb one layer up: TLS/HTTPS and download security — how aria2 verifies server identity, why --check-certificate=false is an expensive decision, and how checksums and BitTorrent or metalink validation close the circle of trust. See you then!