Learn Aria2 - RPC Security & Authentication

#Introduction

In episode 13 you made sure the server you talk to really is the server you intend — the other party's identity was verified. Now it's your side's turn: since episode 3, you've known aria2 can run as a daemon and be controlled through the RPC interface. That interface is a remote control — and an unlocked remote control is an invitation to anyone who can reach it.

Episode 14 covers how to lock the RPC door: tokens, user and password, interface limits, firewalls, and the right remote access patterns. Security isn't just about a strong key; it's about a strong key that's never left lying on the table.

#Why RPC Needs a Security Gate

RPC isn't just an information window — it's full control. Through RPC, anyone who can send a request can tell aria2 to add downloads, change the storage directory, remove downloads, and schedule jobs. Because aria2 writes files to disk, this control means the ability to write files to the system — equivalent to handing strangers the keys to your house.

By default, the RPC daemon only listens on 127.0.0.1 — only processes on the same machine can reach it. That's the first layer, but not enough: other processes running as the same user, or other services on the machine, can talk without asking permission. That's why the second layer must be explicit authentication.

#--rpc-secret: One Token for Every Door

The simplest and most recommended way to lock RPC is a secret token:

aria2c --enable-rpc \
  --rpc-secret="r4h4s1a-panjang-acak-123" \
  --rpc-listen-port=6800

--rpc-secret=TOKEN requires every JSON-RPC request to carry the token — covered in detail in episode 15. The token must be long and random, because it's the only password between the daemon and its clients. Once set, requests without the token are rejected before any command runs.

#--rpc-user and --rpc-passwd

Besides the token, aria2 offers a user and password pair based on HTTP Basic Authentication:

aria2c --enable-rpc \
  --rpc-user=admin --rpc-passwd=rahasia \
  --rpc-listen-port=6800

--rpc-user=admin and --rpc-passwd=rahasia work as an identity pair: the username asserts who, the password proves that it is. The difference from --rpc-secret is in the shape: user and password are two separate values, while a token is one value that's easier to rotate. That's why --rpc-secret is the primary choice for modern integrations — one string, one source of truth, replaced without resetting a username.

#Don't Open to Every Interface: --rpc-listen-all

The default --rpc-listen-all=false makes aria2 listen only on loopback — no other network card can reach it. This is the option most often misused:

# DANGEROUS: listens on all interfaces without restrictions
aria2c --enable-rpc --rpc-secret="rahasia-panjang-acak" \
  --rpc-listen-all=true

--rpc-listen-all=true makes the daemon listen on all network interfaces. This isn't an innocent "so other devices can reach it" decision — it opens a door that used to be loopback-only. Run without authentication and the entire local network can control the daemon. Even with authentication active, every open interface expands the attack surface.

#Binding to a Specific Interface

If cross-host access is genuinely needed, don't open every interface — pick one. The --rpc-listen-interface option binds the daemon to a specific interface or address:

aria2c --enable-rpc --rpc-secret="rahasia-panjang-acak" \
  --rpc-listen-interface=eth1

--rpc-listen-interface=eth1 ensures the daemon only listens on the interface you designate — for example the internal network interface, not the one facing the internet. It's like placing the reception desk on the right floor rather than in a lobby open to the street.

#Firewall: The Second Defense Layer

Authentication rejects people without a key; the firewall rejects people who never reach the door. Two different layers, both worth installing. For access from a trusted LAN, limit the RPC port to a specific subnet:

sudo ufw allow from 192.168.1.0/24 to any port 6800 proto tcp

The rule above only allows traffic to port 6800 from the 192.168.1.0/24 subnet — everything else is blocked before reaching the daemon. The firewall changes "anyone may try" into "only this network may try". A strict firewall and a strong token is the real layered defense.

#Correct Remote Access: Don't Expose to the Internet

The most common pattern for a download daemon on a server: it's accessed from a user's laptop. The biggest temptation is --rpc-listen-all=true with no protection so it can be reached from anywhere. That's a flawed pattern, because the token travels as plain text without TLS — anyone on the network path can read it.

The correct patterns for access from another machine:

1. SSH tunnel — a single command opens an encrypted tunnel from your local machine to the daemon:

ssh -N -L 6800:localhost:6800 user@server-download

2. Once the tunnel is active, http://127.0.0.1:6800/jsonrpc on your local machine reaches through to the daemon on the server — without opening any port to the internet.
3. For comfortable web access, put an HTTPS reverse proxy (nginx or caddy) in front of 127.0.0.1:6800 — we'll build the production pattern more deeply in the production setup episode later.

#The Secure RPC Checklist

A summary of the decisions you should make every time you turn on an RPC daemon:

• Keep the daemon on loopback (--rpc-listen-all=false) unless you genuinely need network access.
• Always set --rpc-secret with a long, random token — not rahasia or password.
• If you need LAN access, combine --rpc-listen-interface with per-subnet firewall rules.
• Never expose the RPC port to the internet; use an SSH tunnel or HTTPS reverse proxy.
• Store the secret in aria2.conf with 600 permissions, not as a literal on the command line or in a repo.

#Closing

Episode 14 locked the RPC door from every direction: understanding why RPC needs authentication, using --rpc-secret as the primary token, meeting --rpc-user and --rpc-passwd, rejecting --rpc-listen-all=true without reason, restricting with --rpc-listen-interface and the firewall, and running the correct remote access patterns via SSH tunnel or HTTPS reverse proxy.

The key thing to remember: RPC is a remote control, not an information box — treat it that way. A locked door in the wrong place is still the wrong door, as long as it's open to everyone.

In the next episode, episode 15, the door is locked — time to learn the language spoken behind it: RPC JSON-RPC & XML-RPC — request and response structure, core methods, event notifications, and direct interaction with curl and jq for script integration. See you then!