Skip to main content
Lionz IPTV Downloader uses aria2 as its download manager. Aria2 is a lightweight, multi-protocol & multi-source command-line download utility.

​
RPC Connection

The application connects to aria2 via its JSON-RPC interface. Configure the connection in your .env file:
​
ARIA2_RPC_HOST
string
default:"http://localhost"
The host URL of the aria2 RPC server.Example: http://localhost, http://192.168.1.100
​
ARIA2_RPC_PORT
integer
default:"6800"
The port number aria2 RPC is listening on. Must match rpc-listen-port in aria2.conf.
​
ARIA2_RPC_SECRET
string
RPC secret token for authentication. Must match rpc-secret in aria2.conf.
Set this to a secure random string to prevent unauthorized access to aria2.
​
ARIA2_DOWNLOAD_ROOT
string
default:"storage/app/public/downloads"
Root directory for downloaded files. Must match the dir setting in aria2.conf.
This path must be accessible to both aria2 and the web application.

​
Example RPC Configuration

.env
ARIA2_RPC_HOST=http://localhost
ARIA2_RPC_PORT=6800
ARIA2_RPC_SECRET=MySecureSecretToken123
ARIA2_DOWNLOAD_ROOT=./storage/app/public/downloads

​
Aria2 Configuration File

The aria2.conf file contains aria2’s download and RPC settings. Default location: ./aria2.conf

​
Basic Settings

​
dir
string
default:"./storage/app/public/downloads"
Directory to store downloaded files.
Must match ARIA2_DOWNLOAD_ROOT environment variable.
​
input-file
string
default:"./bootstrap/cache/aria2.session"
Path to session file for resuming downloads after restart.
​
save-session
string
default:"./bootstrap/cache/aria2.session"
Save error/unfinished downloads to this file on exit.
​
save-session-interval
integer
default:"60"
Save session every N seconds. Set to 0 to save only on exit.
​
max-concurrent-downloads
integer
default:"5"
Maximum number of parallel downloads.
Increase this value if you have high bandwidth and want to download multiple files simultaneously.
​
continue
boolean
default:"true"
Continue downloading partially downloaded files.
​
max-overall-download-limit
string
default:"0"
Maximum overall download speed in bytes/sec. 0 means unrestricted.Example: 1M (1 MB/s), 512K (512 KB/s)
​
max-download-limit
string
default:"0"
Maximum download speed per download in bytes/sec. 0 means unrestricted.
​
quiet
boolean
default:"false"
Suppress console output from aria2.

​
Advanced Settings

​
allow-overwrite
boolean
default:"true"
Restart download from scratch if control file doesn’t exist.
​
allow-piece-length-change
boolean
default:"true"
Allow downloads to proceed even if piece length differs from control file.
​
always-resume
boolean
default:"true"
Always try to resume downloads. Abort if resume is not possible.
​
async-dns
boolean
default:"false"
Enable asynchronous DNS resolution.
​
auto-file-renaming
boolean
default:"true"
Automatically rename files if the same filename exists.
​
content-disposition-default-utf8
boolean
default:"true"
Handle Content-Disposition header as UTF-8 instead of ISO-8859-1.
​
disk-cache
string
default:"64M"
Disk cache size. Data is cached in memory up to this size.Example: 16M, 64M, 128M
Larger cache can improve performance but uses more memory.
​
file-allocation
string
default:"falloc"
File allocation method.Options:
  • none - No pre-allocation
  • prealloc - Pre-allocate before download (slow)
  • falloc - Fast allocation (recommended for ext4, btrfs, xfs, NTFS)
  • trunc - Use ftruncate() system call
​
no-file-allocation-limit
string
default:"8M"
Don’t allocate space for files smaller than this size.

​
RPC Settings

​
enable-rpc
boolean
default:"true"
required
Enable JSON-RPC/XML-RPC server.
This must be true for the application to communicate with aria2.
​
rpc-allow-origin-all
boolean
default:"true"
Add Access-Control-Allow-Origin header with value * to RPC responses.
​
rpc-listen-all
boolean
default:"true"
Listen on all network interfaces. Set to false to listen only on localhost.
Set to false and use rpc-secret if aria2 is accessible from the internet.
​
rpc-listen-port
integer
default:"6800"
Port for JSON-RPC/XML-RPC server. Must match ARIA2_RPC_PORT in .env.Range: 1024-65535
​
rpc-secret
string
RPC secret authorization token. Must match ARIA2_RPC_SECRET in .env.
Required for secure RPC access. Use a strong random string.
​
rpc-secure
boolean
default:"false"
Enable SSL/TLS encryption for RPC. Requires rpc-certificate and rpc-private-key.

​
HTTP/FTP Settings

​
max-connection-per-server
integer
default:"16"
Maximum connections to a single server per download.
Higher values can increase download speed but may be throttled by some servers.
​
min-split-size
string
default:"8M"
Minimum size to split downloads into chunks.Range: 1M - 1024M
​
split
integer
default:"32"
Download files using N connections. Limited by max-connection-per-server.
​
user-agent
string
default:"Transmission/2.77"
User agent string for HTTP(S) downloads.
Set to mimic a BitTorrent client to avoid throttling from some sources.

​
BitTorrent Settings

​
listen-port
string
default:"50101-50109"
TCP port range for BitTorrent downloads.Example: 6881-6999, 50101-50109
​
seed-ratio
float
default:"0.1"
Seed completed torrents until this share ratio is reached. 0.0 means unlimited.
​
seed-time
integer
default:"0"
Seeding time in minutes. 0 disables seeding after download.
​
enable-dht
boolean
default:"true"
Enable IPv4 DHT functionality and UDP tracker support.
​
enable-dht6
boolean
default:"true"
Enable IPv6 DHT functionality.
​
dht-listen-port
string
default:"50101-50109"
UDP port range for DHT and UDP tracker.
​
dht-entry-point
string
default:"dht.transmissionbt.com:6881"
Entry point to IPv4 DHT network.
​
dht-entry-point6
string
default:"dht.transmissionbt.com:6881"
Entry point to IPv6 DHT network.
​
enable-peer-exchange
boolean
default:"true"
Enable Peer Exchange (PEX) extension.
​
peer-id-prefix
string
default:"-TR2770-"
Prefix for peer ID. Mimics Transmission 2.77.
​
peer-agent
string
default:"Transmission/2.77"
Client version string for BitTorrent extended handshake.
​
bt-tracker
string
Comma-separated list of additional BitTorrent tracker announce URIs.
The default configuration includes a comprehensive list of public trackers for better peer discovery.

​
Starting Aria2

Start aria2 with the configuration file: 
aria2c --conf-path=aria2.conf
Or start as a daemon: 
aria2c --conf-path=aria2.conf -D

​
Example Configuration

aria2.conf
# Basic Settings
dir=./storage/app/public/downloads
input-file=./bootstrap/cache/aria2.session
save-session=./bootstrap/cache/aria2.session
save-session-interval=60
max-concurrent-downloads=5
continue=true

# Advanced Settings
allow-overwrite=true
auto-file-renaming=true
disk-cache=64M
file-allocation=falloc

# RPC Settings
enable-rpc=true
rpc-allow-origin-all=true
rpc-listen-all=true
rpc-listen-port=6800
rpc-secret=MySecureSecretToken123

# HTTP/FTP Settings
max-connection-per-server=16
min-split-size=8M
split=32
user-agent=Transmission/2.77

# BitTorrent Settings
listen-port=50101-50109
seed-ratio=0.1
seed-time=0
enable-dht=true
enable-peer-exchange=true
peer-id-prefix=-TR2770-
peer-agent=Transmission/2.77

​
Verifying Connection

After starting aria2, verify the RPC connection: 
curl http://localhost:6800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test",
    "method": "aria2.getVersion",
    "params": ["token:MySecureSecretToken123"]
  }'
You should receive a JSON response with aria2 version information.

Build docs developers (and LLMs) love

Get started for freeTalk to us