How to Use HTTP Basic Authentication in aria2?

This article provides a straightforward guide on how to authenticate with a server that requires HTTP Basic Authentication when using the aria2 command-line download utility. You will learn the exact command-line syntax, how to handle special characters in credentials, and alternative methods for securely passing your username and password to prevent them from exposing in your terminal history.

The Standard Command-Line Syntax

The quickest way to pass HTTP Basic Authentication credentials in aria2 is by embedding them directly into the URL. This follows the standard URI scheme for user information.

aria2c "http://username:password@example.com/file.zip"

Important Note: Always wrap the URL in quotes to prevent the terminal shell from misinterpreting special characters like & or ? that might be present in the URL or your password.

Handling Special Characters in Passwords

If your username or password contains special characters (such as @, :, /, or spaces), passing them directly into the URL will break the command. To fix this, you must URL-encode (percent-encode) those specific characters.

For example, if your password is P@ss:word:

• @ becomes %40
• : becomes %3A

Your command would then look like this:

aria2c "http://username:P%40ss%3Aword@example.com/file.zip"

Alternative: Using the HTTP User and Password Options

If you prefer not to include your credentials directly inside the URL string, aria2 provides dedicated command-line flags. This keeps the URL clean and can make scripting easier.

You can use the --http-user and --http-passwd options explicitly:

aria2c --http-user="your_username" --http-passwd="your_password" "http://example.com/file.zip"

Security Best Practice: Hiding Credentials from Shell History

Entering passwords directly into the terminal leaves them visible in your shell history file (e.g., .bash_history). To avoid this security risk, you can use an external configuration file or input file.

Step 1: Create an Input File

Create a plain text file, for example downloads.txt, and define the URL and the required authentication options on separate lines beneath it:

http://example.com/file.zip
  http-user=your_username
  http-passwd=your_password

Step 2: Run aria2 with the Input File

Execute aria2 by pointing it to your input file using the -i flag:

aria2c -i downloads.txt

Using this method ensures your sensitive credentials remain protected from shoulder-surfing and terminal logging.