ZNHOO Whatever you are, be a good one!

aria2 + webui

aria2 is a Linux command line counterpart of Windows Thunder/IDM, which supports URL, BT/PT, metalink etc. Make it simple, configure a GUI like Webui-aria2 or YAAW based on its builtin RPC (JSON or XML) support.

Installation on PC

# echo "net-misc/aria2 bittorrent metalink xmlrpc" > /etc/portage/package.use/aria2
# emerge -avt aria2
  1. If you prefer XML RPC to default JSON RPC, enable xmlrpc scripts USEs.
  2. We can invoke aria2 command - aria2c.

    Refer to official examples.

  3. To fully utilize functionalities, we can:
    1. Enable RPC and daemon;
    2. Put common arguments in configuration file;
    3. Install webui-aria2 and enable directurl;
    4. Set alias for different configurations.

Installation on OpenWRT



  1. If you don't bother remembering arguments like me, speicify the common ones in $HOME/.aria2/aria2.conf or $XDG_CONFIG_HOME/aria2/aria2.conf.
  2. You can also specify a different configuration on command line by --conf-path.
  3. Current version is 1.15.2 and limited:
    1. ${HOME} or ~ cannot be parsed in configuration file. Use absolute path.
    2. Doesn't support default $XDG_CONFIG_HOME/aria2/aria2.conf location. Use --conf-path.
    3. More options are only available in newer versions:
# https://1024coder.com/topic/15
# https://gist.github.com/aa65535/5e956c4eb4f451ddec29
# http://aria2c.com/usage.html
# http://blog.binux.me/2012/12/aria2-examples/
# Version 1.15.2 does not support ${HOME} or ~ in .conf

# Log

# Disk
# Allocates file space before download begins
# This may take some time depending on file size
# and filesystem
# NTFS: falloc; Ext3/4: trunc
# Refer to `dir' option
# >= 1.16

# Concurrency
# Resume a download started by a web browser or another program
# which downloads files sequentially from the beginning
# maximum downloads
# maximum connections to one server per download
# connections/threads per download 
# split if file >= 2*5M=10M
# overall limit
# Avoid terribly slow AAAA record lookup

# Session
# >= 1.16.1

# If used in OpenWRT, use 'true'
# Customize port number if the default is occupied
# better but >= 1.18.4


# schedulled command; useful in OpenWRT

PT camouflage

  1. PT sites (mainly those on campus) forbid aria2. We should disguise it behaving like a normal uTorrent.
# PT camouflage
# https://www.librehat.com/aria2-camouflage-utorrent-pt-download/
# http://tieba.baidu.com/p/2894158631
# http://kzpu.com/archives/3526.html
# No this option in 1.15.2


Version 1.15.2 does not recognize default $XDG_CONFIG_HOME/aria2/aria2.conf location. Use --conf-path.

$ aria2c --conf-path=${HOME}/.config/aria2/aria2.conf

Make sure rpc-listen-port is allowed on host by iptables (on OpenWRT or PC). If --rpc-listen-all is True, aria2 listens incoming JSON-RPC/XML-RPC requests on all network interfaces. We can strict incoming requests to a specific interface by -d host-ip.

# iptables -t filter -A INPUT -p tcp --dport 6800 -j ACCEPT
# iptables -t filter -A INPUT -p tcp -m tcp -d host-ip --dport 6800 -j ACCEPT
# iptables -t nat -A WANPREROUTING -p tcp --dport 6800 -j DNAT --to-destination host-ip:6800
# iptables -t filter -A INPUT -p tcp -m tcp -d host-ip --dport 6800 -j ACCEPT


Refer to webui_aria2c. Remember that we set enable-rpc=true above to manage aria2 on RPC interface. For example, you configure aria2 at home OpenWRT. You are in office and would like to file an AV download by webui interface.


git clone

$ cd ~/workspace/
$ git clone --depth=1 https://github.com/ziahamza/webui-aria2.git
$ cd webui-aria2

Public URL

Visit Public URL and fill in Settings -> Connection Settings.

RPC connection

  1. The easiest way: visit the Public URL.

    If you don't trust the public URL like me, install webui manually.

  2. Open index.html in browser if cloned on access PC.
  3. Use Python simplehttpserver to host the cloned webui. RPC listens at 6800 and we can set HTTP Server listens at 6801.

    This is similar to the Pbulic URL but hosted by our own. You'd better host the webui HTTP Server on PC, public IP (i.e. on VPS) or even on OpenWRT.

    $ cd ~/workspace/webui-aria2
    $ python3 -m http.server 6801 >/dev/null 2>&1&
    $ python2 -m SimpleHTTPServer 6801 >/dev/null 2>&1&

    Browse http://localhost:6801 or http://ip_address_of_server:6801.

Connection Settings

  1. If you access webui by index.html or locally hosted HTTP Server, set user, pass, host etc. in configuration.js permanently.

    $ cd ~/workspace/webui-aria2
    $ nano -w configuration.js

    These values can be changed on the webui HTML page afterwards.

  2. If webui is hosted on public IP (VPS/OpenWRT), don't set those variables as it can be compromised. For example, if someone got your router IP and webui HTTP Server port, he could access to your aria2 daemon.

    Instead, leave the configuration.js alone and fill in values on webui page (like a web page logon).


  1. This feature allows users to download files that they download from aria2 directly from the webui dashboard.
  2. Suppose aria2 is downloading on OpenWRT, directurl generates clickable link to downloaded files on webui. Simplest way is to use Python to setup a HTTP server like the hosting webui page. webui listens at 6801 and we can let directurl listens at 6802.
  3. This time, the HTTP Server must be hosted on -d, --dir.

    $ cd ~/Downloads/
    $ python3 -m http.server 6802 >/dev/null 2>&1&
    $ python2 -m SimpleHTTPServer 6802 >/dev/null 2>&1&
  4. To test, just browse http://serverip:6802.

    It should get a directory listing. Any browser errors and something hasn't been done properly, check IP/PORT etc.

  5. Depend on your needs, set directURL to 'http://localhost:6802/' in configuration.js. Or set Settings -> Connection Settings -> Enter base URL on webui page.

    Make sure have the / on the end

  6. After that, all downloaded file can be dragged to local computer (PC in use) on webui page.
  7. [to be confirmed] Make sure port 6802 is also allowed by iptables.

The simplest Directurl is file:///${HOME}/Downloads/.


By default, everything works fine. But if aria2 does not work, check ports 6800, 6801, 6802, 6881-6999 etc. are allowed in Iptables.

  1. rpc-listen-port: default 6800;
  2. webui and directurl HTTP Servers ports: 6801 and 6802;
  3. listen-port: default TCP ports 6881-6999;
  4. dht-listen-port: default UDP ports 6881-6999.

In the OUTPUT chain, TCP/UDP 6881-6999 MUST be accepted:

-A OUTPUT -p tcp -m tcp --dport 6881:6999 -m conntrack --ctstate NEW -j ACCEPT
-A OUTPUT -p udp -m udp --dport 6881:6999 -m conntrack --ctstate NEW -j ACCEPT

For the INPUT chain, it depends.


  1. aria2 and webui are on the same host (OpenWRT/PC/VPS etc.).
  2. They are on different hosts. For instance, aria2 is on OpenWRT while webui is hosted on VPS or PC.
  3. If webui is on PC, I think there is no need to set up a separate HTTP Server for webui or directurl. We can just open the index.html from browser bookmark. And we can access our downloaded files directly on local PC.
  4. We can add init script to load aria2 on boot (OpenWRT).

The following setting is to run both aria2 and webui on PC.

Alias on PC

We need different set of arguments for different downloads. For example, to download PT resources, we should camouflage aria2 as uTorrent. But options for PT impact BT download performance. We can set an alias for PT by --conf-path.

$ nano -w ~/.bashrc
alias aria2='aria2c --conf-path=${HOME}/.config/aria2/aria2.conf'
alias aria2='aria2c --conf-path=${HOME}/.config/aria2/aria2.conf; cd ${HOME}/Downloads/; python3 -m http.server 6802 >/dev/null 2>&1&'
alias aria2='aria2c --conf-path=${HOME}/.config/aria2/aria2.conf; cd ${HOME}/workspace/webui-aria2/; python3 -m http.server 6801 >/dev/null 2>&1& cd ${HOME}/Downloads/; python3 -m http.server 6802 >/dev/null 2>&1&'
alias aria2pt='aria2c --conf-path=${HOME}/.config/aria2/aria2pt.conf'
$ source ~/.bashrc

Launch on PC

  1. Launch RPC daemon

    $ type aria2c aria2 aria2pt
    $ aria2
  2. Open webui index.html file or access http://localhost:6802.


  1. Magnet zero speed.

    When downloading magnet files, there is no speed. This is due ot lack in dht entry point. Details refer to issue 504, dht bootstrap nodes, and aria2 and magnet links

    Set --dht-entry-point as dht.transmissionbt.com, router.utorrent.com or router.bittorrent.com. Port is 6881.

Browser plugins


  1. Plugins for BaiduYun.
  2. Plugins to lauch aria2.


  1. VPS下使用aria2进行BT下载及其WebUi配置
  2. Aria2的配置文件 & 启动脚本
  3. Aria2 & YAAW 使用说明
  4. aria2配置示例
  5. Aria2伪装uTorrent进行PT下载
  6. aria2亦可以用于PT下载
  7. Aria2伪装uTorrent进行PT下载
  8. webui config