Aria2 Setup on Ubuntu

Introduction

aria2 is a utility for downloading files. The supported protocols are HTTP(S), FTP, SFTP, BitTorrent, and Metalink. aria2 can download a file from multiple sources/protocols and tries to utilize your maximum download bandwidth. It supports downloading a file from HTTP(S)/FTP/SFTP and BitTorrent at the same time, while the data downloaded from HTTP(S)/FTP/SFTP is uploaded to the BitTorrent swarm. Using Metalink’s chunk checksums, aria2 automatically validates chunks of data while downloading a file like BitTorrent.

What interfaces are available ?

Aria2 is a simple text based, command line interface. If you have used wget or curl in an xterm then aria2 looks very similar. Pass the aira2c command a url or torrent file and the program will start downloading the file. You will see status messages about the download speed and any notices or errors the program encounters. We really like the simplified interface as it is easy to use in a “screen” or “tmux” session.
A browser based Web GUI is also available. Take a look at the webui-aria2 project and AriaNG. webui-aria2 offers a very nice minimalist real time interface to aria2 running in daemon mode. AriaNg is a modern web frontend making aria2 easier to use.

aria2 package install

The install of aria2 is quite simple and can be downloaded by most package managers.

sudo apt install aria2

the aria2.conf configuration file

The following is the aria2.conf configuration file we use and it needs to be placed in $HOME/.aria2/aria2.conf . We recommend using a config file so you do not have to keep adding command line arguments for every download. We find aria2 is quite friendly to those wishing to customize the client. The configuration file may look long, but we tried to add insights and comments as best we could.

#
## aria2 config
#
# file path = $HOME/.aria2/aria2.conf

## File save settings ##

# Download directory. Absolute path or relative path can be used, default: current startup location
dir=$HOME/Download

# Disk cache, 0 is to disable cache, default: 16M
# The role of the disk cache is to temporarily store the downloaded data blocks in memory, and then write them to the hard disk in a centralized manner to reduce disk I/O, improve read and write performance, and prolong hard disk life.
# It is recommended to increase appropriately when there is enough free memory, but do not exceed the remaining free memory space.
# This value only determines the upper limit, and the actual memory usage depends on other factors such as network speed (bandwidth) and device performance.
disk-cache=64M

# File preallocation method, optional: none, prealloc, trunc, falloc, default: prealloc
# Pre-allocation can effectively reduce disk fragmentation, improve disk read and write performance, and extend disk life for mechanical hard disks.
# The mechanical hard disk uses ext4 (with extended support), btrfs, xfs or NTFS (only MinGW compiled version) and other file systems are recommended to be set to falloc
# If it cannot be downloaded, it will prompt "fallocate failed.cause: Operation not supported, it means it is not supported", please set it to none
# "prealloc" allocation speed is slow, "trunc" has no practical effect and is not recommended.
# SSDs do not need to be pre-allocated, it is only recommended to set it to none , otherwise it may cause double file size data to be written, thus affecting the lifespan.
file-allocation=none

# File preallocation size limit. Files smaller than the size of this option do not pre-allocate space, the unit is K or M, default: 5M
no-file-allocation-limit=64M

# http
continue=true

# Always try to resume uploading from a breakpoint, if it fails to resume uploading from a breakpoint, the download will be terminated, default: true
always-resume=false

# The URI value that does not support breakpoint resuming, it takes effect when always-resume=false.
# When this value is reached, the download will start from the beginning. When the value is 0, the download will start from the beginning when all URIs do not support resuming.
max-resume-failure-tries=0

# Get server file time, default: false
remote-time=true


## Progress save settings ##

# Read download tasks from session file
input-file=$HOME/.aria2/aria2.session

# Session file save path
# Aria2 will save `error/incomplete` download tasks to session file when exiting or at specified interval
save-session=$HOME/.aria2/aria2.session

# The interval (seconds) to save the session after the task state changes, 0 is only saved when the process exits normally, default: 0
# In order to save the task status in time and prevent the task from being lost, this value is only recommended to be set to 1
save-session-interval=1

# The interval (seconds) for automatically saving the progress of the task to the control file (*.aria2), 0 is to save only when the process exits normally, default: 60
# This value also indirectly affects how often cached data is written to disk from memory
# If you want to reduce disk IOPS (number of reads and writes per second), increase the interval
# If you want to save as much download progress as possible when unexpectedly exiting abnormally, reduce the interval time
# Abnormal exit: process crash, system crash, SIGKILL signal, device power off, etc.
auto-save-interval=20

# Force save, save information to session file even if the task is completed, default: false
# When enabled, the .aria2 file will be retained after the task is completed. If the file is removed and the task exists, it will be downloaded again after restarting.
# The list of completed tasks after shutdown will be cleared after restart.
force-save=false


## Download connection settings ##

# File not found retries, default: 0 (disabled)
# The number of retries will also be recorded when retrying, so you also need to set the max-tries option
max-file-not-found=10

# Maximum number of attempts, 0 means unlimited, default: 5
max-tries=0

# Retry wait time (seconds), default: 0 (disabled)
retry-wait=10

# Connection timeout (seconds). Default: 60
connect-timeout=10

# Timeout time (seconds). Default: 60
timeout=10

# Maximum number of simultaneous download tasks, can be modified at runtime, default: 5
max-concurrent-downloads=5

# The maximum number of connection threads for a single server, which can be specified when adding tasks, default: 1
# The maximum value is 16, and is limited by the value set by the maximum number of connection threads per task (split).
max-connection-per-server=16

# The maximum number of connection threads for a single task, which can be specified when adding tasks, default: 5
split=64

# The minimum segment size of the file, it can be specified when adding, the value range is 1M-1024M, the default: 20M
# For example, the value of this item is 10M, when the file is 20MB, it will be divided into two parts and downloaded from two sources, and if the file is 15MB, only one source will be used to download.
# Theoretically, the smaller the value, the more download segments will be used, the greater the actual number of threads that can be obtained, and the faster the download speed, but it is limited by the policy of the downloaded file server.
min-split-size=4M

# HTTP/FTP download segment size, all segments must be multiples of this value, the minimum value is 1M, the default: 1M
piece-length=1M

# Allow shard size changes. Default: false
# false: will abort the download when the shard size is different from the control file
# true: continue downloading if part of the download progress is lost
allow-piece-length-change=true

# Minimum download speed limit. When the download speed is lower than or equal to the value of this option, close the connection, this option has nothing to do with BT download. unit K or M , default: 0 (unlimited)
lowest-speed-limit=0

# Global maximum download speed limit, can be modified at runtime, default: 0 (unlimited)
max-overall-download-limit=0

# Download speed limit for single task, default: 0 (unlimited)
max-download-limit=0

# disable IPv6, default: false
disable-ipv6=true

# GZip support, default: false
http-accept-gzip=true

# URI reuse, default: true
reuse-uri=false

# disable netrc support, default: false
no-netrc=true

# Allow overwriting, redownloading from scratch when the associated control file (.aria2) does not exist. Default: false
allow-overwrite=false

# File auto-rename, this option is only valid in HTTP(S)/FTP download. The new filename has a dot and a number (1..9999) after the name and before the extension. Default: true
auto-file-renaming=true

# Use UTF-8 to handle Content-Disposition, default: false
content-disposition-default-utf8=true

# Minimum TLS version, optional: TLSv1.1, TLSv1.2, TLSv1.3 Default: TLSv1.2
#min-tls-version=TLSv1.2


## BT/PT download settings ##

# BT listening port (TCP), default: 6881-6999
# For devices directly connected to the external network, such as VPS, be sure to configure firewall and security group policies to allow this port inbound
# For devices in the internal network environment, such as NAS, in addition to firewall settings, you need to set the external network port on the router to forward to this port
listen-port=51413

# DHT network and UDP tracker listening port (UDP), default: 6881-6999
# Due to different protocols, you can use the same port as the BT listening port, which is convenient for configuring firewall and port forwarding policies.
dht-listen-port=51413

# Enable IPv4 DHT function, PT download (private torrent) will be automatically disabled, default: true
enable-dht=true

# Enable IPv6 DHT function, PT download (private torrent) will be automatically disabled, default: false
# Enabling in environments without IPv6 support may cause DHT to malfunction
enable-dht6=false

# Specify IP addresses in BT and DHT networks
# Usage scenario: If the home broadband does not have a public network IP, you can forward the BT and DHT listening ports to a server with a public network IP. Fill in the server's IP here to increase the BT download rate.
#bt-external-ip=

# IPv4 DHT file path, default: $HOME/.aria2/dht.dat
dht-file-path=$HOME/.aria2/dht.dat

# IPv6 DHT file path, default: $HOME/.aria2/dht6.dat
dht-file-path6=$HOME/.aria2/dht6.dat

# IPv4 DHT network boot node
dht-entry-point=dht.transmissionbt.com:6881

# IPv6 DHT network boot node
dht-entry-point6=dht.transmissionbt.com:6881

# Local node discovery, PT download (private torrent) will be automatically disabled Default: false
bt-enable-lpd=true

# Specify the interface used for local node discovery, possible values: interface, IP address
# If this option is not specified, the default interface is selected.
#bt-lpd-interface=

# Enable node exchange, PT download (private torrent) will be automatically disabled, default: true
enable-peer-exchange=true

# BT download the maximum number of connections (single task), which can be modified at runtime. 0 means no limit, default: 55
# Ideally, the more the number of connections, the faster the download, but in reality, only a small number of connected seeders have fast upload speeds, and the rest are slow or do not upload.
# If there is no limit, when downloading a very popular torrent or the number of tasks is very large, the process may crash or the network may be blocked due to too many connections.
# Process crash: If the CPU performance of the device is average, the CPU usage is too high due to too many connections, and the Aria2 process will be forcibly terminated due to insufficient resources.
# Network congestion: In the intranet environment, even if the download does not occupy the full bandwidth, other devices will not be able to access the Internet normally. It is caused by the forwarding performance bottleneck of ancient low-performance routers.
bt-max-peers=128

# BT downloads the expected speed value (single task), which can be modified during runtime. Units K or M . Default: 50K
# When the BT download speed is lower than the value of this option, the number of connections will be temporarily increased to obtain faster download speed, but the premise is that there are more seeders available for connection.
# There is no upper limit to temporarily increase the number of connections in the actual measurement, but it will not increase infinitely like no limit, and will make reasonable dynamic adjustments according to the algorithm.
bt-request-peer-speed-limit=10M

# Global maximum upload speed limit, can be modified at runtime, default: 0 (unlimited)
# Setting too low may affect BT download speed
max-overall-upload-limit=2M

# upload speed limit for single task, default: 0 (unlimited)
max-upload-limit=0

# Minimum share rate. Stop seeding when the sharing rate of seeds reaches the value set by this option, 0 means seeding all the time, default: 1.0
# It is strongly recommended that you set this option to a value greater than or equal to 1.0
seed-ratio=1.0

# Minimum seeding time (minutes). Set to 0 to stop seeding after the BT task download is complete.
seed-time=0

# Check file hash before seeding, default: true
bt-hash-check-seed=true

# When continuing the previous BT task, no need to check again, default: false
bt-seed-unverified=false

# BT tracker server connection timeout (seconds). Default: 60
# After the connection is established, this option has no effect, the value of the bt-tracker-timeout option will be used
bt-tracker-connect-timeout=10

# BT tracker server timeout (seconds). Default: 60
bt-tracker-timeout=10

# BT server connection interval (seconds). Default: 0 (auto)
#bt-tracker-interval=0

# BT download prioritizes the beginning or end of the download file
bt-prioritize-piece=head=32M,tail=32M

# Save the torrent file (.torrent) uploaded via WebUI(RPC), default: true
# All options related to saving torrent files are recommended to be turned on. If you do not save torrent files, there is a risk of task loss.
# Custom temporary download directory via RPC may not hold torrent files.
rpc-save-upload-metadata=true

# Download torrent files (.torrent) to start downloading automatically, default: true, optional: false|mem
# true: save torrent file
# false: download torrent files only
# mem: keep the seed in memory
follow-torrent=true

# Pause the task after the torrent file is downloaded, default: false
# After the follow-torrent option is turned on, downloading torrent files or magnetism will automatically start the download task for downloading, and when this option is turned on at the same time, related tasks will be created and paused.
pause-metadata=false

# Save the magnet link metadata as a torrent file (.torrent), default: false
bt-save-metadata=true

# Load saved metadata file (.torrent), default: false
bt-load-saved-metadata=true

# Delete unselected files in the BT download task, default: false
bt-remove-unselected-file=true

# BT forced encryption, default: false
# This option is equivalent to the shortcut opening of the latter two options (bt-require-crypto=true, bt-min-crypto-level=arc4), but will not modify the values ​​of these two options.
bt-force-encryption=true

# BT encryption requirements, default: false
# When enabled, refuse to establish a connection with the old BitTorrent handshake protocol (\19BitTorrent protocol), always use the obfuscated handshake.
#bt-require-crypto=true

# BT minimum encryption level, optional: plain (plain text), arc4 (encryption), default: plain
#bt-min-crypto-level=arc4

# Detach only seed tasks, default: false
# Exclude the tasks that have been downloaded and are being seeded from the tasks being downloaded, and start waiting for the next task in the list.
bt-detach-seed-only=true


## User Agent Masquerading ##

# Custom User Agent
user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36 Edg/93.0.961.47

# BT client masquerading
# PT download needs to keep the two parameters of user-agent and peer-agent consistent
# Some PT stations have a special ban mechanism for Aria2, client camouflage may not be effective, and there is a risk of account ban.
#user-agent=Deluge 1.3.15
peer-agent=Deluge 1.3.15
peer-id-prefix=-DE13F0-


## Execute additional commands ##

# The command to execute after the download stops
# Fired from downloading to delete, error, complete. Pause is marked as not starting the download, so it's not relevant for this.
#on-download-stop=

# The command to execute after the download is complete
# If this item is not defined, execute the command executed after the download is stopped (on-download-stop)
#on-download-complete=

# The command to execute after download error
# If this item is not defined, execute the command executed after the download is stopped (on-download-stop)
#on-download-error=

# The command to be executed after the download is paused
#on-download-pause=

# The command to execute after the download starts
#on-download-start=

# The command to execute after the BT download is complete
#on-bt-download-complete=


## RPC settings ##

# Enable JSON-RPC/XML-RPC server, default: false
enable-rpc=true

# Accept all remote requests, default: false
rpc-allow-origin-all=true

# Allow external access, default: false
rpc-listen-all=true

# RPC listening port, default: 6800
rpc-listen-port=6800

# RPC key
rpc-secret=yourtoken

# RPC max request size
rpc-max-request-size=10M

# RPC service SSL/TLS encryption, default: false
# After enabling encryption, you must use https or wss protocol to connect
# It is not recommended to enable it. It is recommended to use a web server reverse proxy, such as Nginx and Caddy, which is more flexible.
#rpc-secure=false

# Certificate file (.pem/.crt) when SSL/TLS encryption is enabled in RPC service
#rpc-certificate=/root/.aria2/xxx.pem

# The private key file (.key) when SSL/TLS encryption is enabled in the RPC service
#rpc-private-key=/root/.aria2/xxx.key

# Event polling method, optional: epoll, kqueue, port, poll, select, different systems have different default values
#event-poll=select


## advanced options ##

# Enable asynchronous DNS functionality. Default: true
#async-dns=true

# Specify a list of asynchronous DNS servers, or read from /etc/resolv.conf if not specified.
#async-dns-server=8.8.8.8,1.1.1.1

# Specify a single network interface, possible values: interface, IP address, hostname
# If the interface has multiple IP addresses, it is recommended to specify the IP address.
# It is known that specifying the network interface will affect the functional scenarios of connections that rely on local RPC, that is, the Aria2 server cannot communicate with the Aria2 server through localhost and 127.0.0.1.
#interface=

# Specify multiple network interfaces, and separate multiple values ​​with commas (,).
# This is ignored when using the interface option.
#multiple-interface=


## log settings ##

# Log file save path, ignore or set to empty to not save, default: not save
#log=

# Log level, optional debug, info, notice, warn, error . Default: debug
#log-level=warn

# Console log level, optional debug, info, notice, warn, error, default: notice
console-log-level=notice

# Quiet mode, disable log output in console, default: false
quiet=false

# Download progress summary output interval (seconds), 0 is to disable output. Default: 60
summary-interval=0

## BitTorrent trackers ##
bt-tracker=

### EOF ###

Using aria2 as a Daemon

To use aria2 as a daemon, you should write a systemd user unit. For example: aria2cd.service

[Unit]
Description=aria2 Daemon

[Service]
Type=forking
ExecStart=/usr/bin/aria2c --conf-path=/path/to/conf

[Install]
WantedBy=default.target

Startup aria2 daemnon:

systemctl --user enable aria2.service
systemctl --user start aria2.service

How do I use aria2c ?

There are many examples of how to run aria2 on the aria2 documents and aria2 wiki. We suggest you check their pages after you are done here. The documents assume you have not setup an aria2.conf configuration file yet and shows each line with command line arguments. Since we have already setup a aria2.conf file all of our preferred configuration options are already set; there is no need to use command line arguments. Aria2 is now incredibly easy to use by simply passing a URL, a bittorrent URL, a magnet link or pre-downloaded bit torrent file. Here are some examples.

Exampls

HTTP/FTP Segmented Downloads¶

Download a file

aria2c "http://host/file.zip"

Note: To stop a download, press Ctrl-C. You can resume the transfer by running aria2c with the same argument in the same directory. You can change URIs as long as they are pointing to the same file.

Download a file from two different HTTP servers

aria2c "http://host/file.zip" "http://mirror/file.zip"

Download files listed in a text file concurrently

aria2c -ifiles.txt -j2

Note: -j option specifies the number of parallel downloads.

Download several local metalink files

aria2c -j2 file1.metalink file2.metalink

Download only selected files

aria2c --select-file=1-4,8 file.metalink

Note: The index is printed to the console using -S option.

BitTorrent Download¶

Download files using a remote BitTorrent file

aria2c --follow-torrent=mem "http://host/file.torrent"

Download using a local torrent file

aria2c --max-upload-limit=40K file.torrent

Download using BitTorrent Magnet URI

aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"

Note:Don’t forget to quote BitTorrent Magnet URIs which include & characters with single(') or double(") quotes when specifying URIs on the command-line.
Only download specific files (usually called “selected download”)

aria2c --select-file=1-4,8 file.torrent

Note: The index is printed to the console using -S option.
Download a .torrent file, but do not download the torrent

aria2c --follow-torrent=false "http://host/file.torrent"

Specify the output file name
To specify the output file name for BitTorrent downloads, you need to know the index of file in the torrent (see --show-files). For example, the output looks like this:

To save ‘dist/base-2.6.18.iso’ in ‘/tmp/mydir/base.iso’ and ‘dist/driver-2.6.18.iso’ in ‘/tmp/dir/driver.iso’, use the following command:

aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent

Examples of RPC

aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP interfaces that offer basically the same functionality. aria2 also provides JSON-RPC over WebSocket. JSON-RPC over WebSocket uses the same method signatures and response format as JSON-RPC over HTTP, but additionally provides server-initiated notifications.
Http:

curl http://localhost:6800/jsonrpc -d '{"jsonrcp":"2.0","id":"someID","method":"aria2.addUri","params":["token:ariatest",["http://m.gettywallpapers.com/wp-content/uploads/2020/01/Wallpaper-Naruto-2.jpg"],{"out":"test.jpg"}]}'

Torrent magnet:

curl --location --request POST 'http://localhost:6800/jsonrpc' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{"jsonrpc":"2.0","id":"qwer","method":"aria2.addUri","params":["token:yourtoken",["magnet:?xt=xxxx"],{"select-file":"65,71,76"}]}'

Download Torrent file only:

curl --location --request POST 'http://localhost:6800/jsonrpc' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{"jsonrpc":"2.0","id":"qwer","method":"aria2.addUri","params":["token:yourtoken",["magnet:?xt=xxxx"],{"bt-metadata-only":"true","bt-save-metadata":"true","summary-interval":"0","file-allocation":"none"}]}'