Securing aria2 RPC with a Secret Token

This article provides a straightforward guide on how to secure the aria2 Remote Procedure Call (RPC) interface by implementing a secret authorization token. You will learn how to configure the token in your configuration file, apply it via the command line, and use it to authenticate your client connections, preventing unauthorized access to your download manager.

Why Secure the aria2 RPC Interface?

By default, the aria2 RPC interface allows external applications or web frontends (like AriaNg) to control your downloads. If left unprotected, anyone who discovers your RPC port can exploit it to download malicious files onto your system or view your private data. Implementing a secret token ensures that only authorized clients can issue commands to your aria2 daemon.

Step 1: Generate a Strong Secret Token

Before configuring aria2, you need a strong, random string to act as your password. You can generate a secure token using your terminal:

openssl rand -hex 16

Copy the resulting alphanumeric string. You will use this as your RPC secret.

Step 2: Configure aria2 with the Secret Token

You can enforce the token either through a configuration file or directly via the command line.

Method A: Using a Configuration File (Recommended)

Open your aria2.conf file and add the rpc-secret directive. If you haven’t enabled the RPC server yet, make sure to include those settings as well.

# Enable the RPC server
enable-rpc=true
rpc-listen-all=true

# Set the secret authorization token
rpc-secret=YOUR_GENERATED_SECRET_TOKEN

Replace YOUR_GENERATED_SECRET_TOKEN with the string you generated in the first step. Save the file and restart your aria2 service to apply the changes.

Method B: Using the Command Line

If you run aria2 directly from the terminal, you can pass the token as an argument when starting the daemon:

aria2c --enable-rpc=true --rpc-listen-all=true --rpc-secret="YOUR_GENERATED_SECRET_TOKEN"

Step 3: Connect Your Client Using the Token

Once the secret token is active, any client attempting to connect to aria2 must provide it to authenticate successfully.

Connecting via Web Frontends (e.g., AriaNg)

Open your aria2 web interface.
Navigate to the AriaNg Settings or RPC Configuration menu.
Locate the field labeled Aria2 RPC Secret Token (sometimes just called Token).
Paste your secret token into this field.
Reload the page. The connection status should change to “Connected.”

Connecting via JSON-RPC (API Requests)

If you are interacting with the aria2 API programmatically, you must include the token in the payload parameters. The token must be prefixed with token:.

Here is an example of a JSON-RPC request payload to add a download:

{
  "jsonrpc": "2.0",
  "id": "qwer",
  "method": "aria2.addUri",
  "params": [
    "token:YOUR_GENERATED_SECRET_TOKEN",
    ["https://example.com/file.zip"]
  ]
}

By ensuring the token: prefix accompanies your secret string in every API call, aria2 will validate and process your requests securely.