mirror of https://github.com/aria2/aria2
337 lines
12 KiB
Plaintext
337 lines
12 KiB
Plaintext
aria2 - The ultra fast download utility
|
|
=======================================
|
|
:Author: Tatsuhiro Tsujikawa
|
|
:Email: t-tujikawa_at_users_dot_sourceforge_dot_net
|
|
|
|
Disclaimer
|
|
----------
|
|
This program comes with no warranty.
|
|
You must use this program at your own risk.
|
|
|
|
Introduction
|
|
------------
|
|
aria2 is a utility for downloading files. The supported protocols are
|
|
HTTP(S), FTP, 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 and
|
|
BitTorrent at the same time, while the data downloaded from
|
|
HTTP(S)/FTP is uploaded to the BitTorrent swarm. Using Metalink's
|
|
chunk checksums, aria2 automatically validates chunks of data while
|
|
downloading a file like BitTorrent.
|
|
|
|
The project page is located at http://aria2.sourceforge.net/.
|
|
|
|
See http://aria2.sourceforge.net/aria2c.1.html[aria2 Online Manual]
|
|
and http://sourceforge.net/apps/trac/aria2/wiki/UsageExample[the usage
|
|
example] to learn how to use aria2.
|
|
|
|
Features
|
|
--------
|
|
|
|
Here is a list of features:
|
|
|
|
* Command-line interface
|
|
* Download files through HTTP(S)/FTP/BitTorrent
|
|
* Segmented downloading
|
|
* Metalink version 4 (RFC 5854) support(HTTP/FTP/BitTorrent)
|
|
* Metalink version 3.0 support(HTTP/FTP/BitTorrent)
|
|
* Metalink/HTTP (RFC 6249) support
|
|
* HTTP/1.1 implementation
|
|
* HTTP Proxy support
|
|
* HTTP BASIC authentication support
|
|
* HTTP Proxy authentication support
|
|
* Well-known environment variables for proxy: http_proxy, https_proxy,
|
|
ftp_proxy, all_proxy and no_proxy
|
|
* HTTP gzip, deflate content encoding support
|
|
* Verify peer using given trusted CA certificate in HTTPS
|
|
* Client certificate authentication in HTTPS
|
|
* Chunked transfer encoding support
|
|
* Load Cookies from file using the Firefox3 format, Chromium/Google Chrome
|
|
and the Mozilla/Firefox
|
|
(1.x/2.x)/Netscape format.
|
|
* Save Cookies in the Mozilla/Firefox (1.x/2.x)/Netscape format.
|
|
* Custom HTTP Header support
|
|
* Persistent Connections support
|
|
* FTP through HTTP Proxy
|
|
* Download/Upload speed throttling
|
|
* BitTorrent extensions: Fast extension, DHT, PEX, MSE/PSE, Multi-Tracker
|
|
* BitTorrent http://getright.com/seedtorrent.html[WEB-Seeding]. aria2
|
|
requests chunks more than piece size to reduce the request
|
|
overhead. It also supports pipelined requests with piece size.
|
|
* BitTorrent Local Peer Discovery
|
|
* Rename/change the directory structure of BitTorrent downloads
|
|
completely
|
|
* JSON-RPC (over HTTP and WebSocket)/XML-RPC interface
|
|
* Run as a daemon process
|
|
* Selective download in multi-file torrent/Metalink
|
|
* Chunk checksum validation in Metalink
|
|
* Can disable segmented downloading in Metalink
|
|
* Netrc support
|
|
* Configuration file support
|
|
* Download URIs found in a text file or stdin and the destination directory and
|
|
output filename can be specified optionally
|
|
* Parameterized URI support
|
|
* IPv6 support
|
|
|
|
How to get source code
|
|
----------------------
|
|
|
|
We maintain the source code at Github:
|
|
https://github.com/tatsuhiro-t/aria2
|
|
|
|
To download the latest source code, run following command:
|
|
|
|
------------------------------------------------
|
|
git clone git://github.com/tatsuhiro-t/aria2.git
|
|
------------------------------------------------
|
|
|
|
This will create aria2 directory in your current directory and source
|
|
files are stored there.
|
|
|
|
Dependency
|
|
----------
|
|
|
|
.External Library Dependency
|
|
[options="header"]
|
|
|====================================================
|
|
|features |dependency
|
|
|HTTPS |GnuTLS or OpenSSL
|
|
|BitTorrent |libnettle+libgmp or libgcrypt or OpenSSL
|
|
|Metalink |libxml2 or Expat.
|
|
|Checksum |libnettle or libgcrypt or OpenSSL
|
|
|gzip, deflate in HTTP |zlib
|
|
|Async DNS |C-Ares
|
|
|Firefox3/Chromium cookie|libsqlite3
|
|
|XML-RPC |libxml2 or Expat.
|
|
|====================================================
|
|
|
|
Note;;
|
|
|
|
libxml2 has precedence over Expat if both libraries are installed.
|
|
If you prefer Expat, run configure with \--without-libxml2.
|
|
|
|
Note;;
|
|
|
|
GnuTLS has precedence over OpenSSL if both libraries are installed.
|
|
If you prefer OpenSSL, run configure with \--without-gnutls
|
|
\--with-openssl.
|
|
|
|
Note;;
|
|
|
|
libnettle has precedence over libgcrypt if both libraries are
|
|
installed. If you prefer libgcrypt, run configure with
|
|
\--without-libnettle \--with-libgcrypt. If OpenSSL is selected over
|
|
GnuTLS, neither libnettle nor libgcrypt will be used.
|
|
|
|
A user can have one of the following configurations for SSL and crypto
|
|
libraries:
|
|
|
|
* libgcrypt
|
|
* libnettle
|
|
* OpenSSL
|
|
* GnuTLS + libgcrypt
|
|
* GnuTLS + libnettle
|
|
|
|
You can disable BitTorrent, Metalink support by providing
|
|
\--disable-bittorrent, \--disable-metalink respectively to configure
|
|
script.
|
|
|
|
In order to enable async DNS support, you need c-ares.
|
|
|
|
* c-ares: http://daniel.haxx.se/projects/c-ares/
|
|
|
|
How to build
|
|
------------
|
|
In order to build aria2 from the source package, you need following
|
|
development packages(package name may vary depending on the
|
|
distribution you use):
|
|
|
|
* libgnutls-dev (Required for HTTPS, BitTorrent, Checksum support)
|
|
* nettle-dev (Required for BitTorrent, Checksum support)
|
|
* libgmp-dev (Required for BitTorrent)
|
|
* libc-ares-dev (Required for async DNS support)
|
|
* libxml2-dev (Required for Metalink support)
|
|
* zlib1g-dev (Required for gzip, deflate decoding support in HTTP)
|
|
* libsqlite3-dev (Required for Firefox3/Chromium cookie support)
|
|
|
|
You can use libgcrypt-dev instead of nettle-dev and libgmp-dev:
|
|
|
|
* libgpg-error-dev (Required for BitTorrent, Checksum support)
|
|
* libgcrypt-dev (Required for BitTorrent, Checksum support)
|
|
|
|
You can use libssl-dev instead of
|
|
libgnutls-dev, nettle-dev, libgmp-dev, libgpg-error-dev and libgcrypt-dev:
|
|
|
|
* libssl-dev (Required for HTTPS, BitTorrent, Checksum support)
|
|
|
|
You can use libexpat1-dev instead of libxml2-dev:
|
|
|
|
* libexpat1-dev (Required for Metalink support)
|
|
|
|
You may also need pkg-config to detect the above mentioned libraries.
|
|
|
|
On Fedora you need the following packages:
|
|
gcc, gcc-c++, kernel-devel, libgcrypt-devel, libgcrypt-devel, libxml2-devel, openssl-devel
|
|
|
|
If you downloaded source code from git repository, you have to run
|
|
following command to generate configure script and other files
|
|
necessary to build the program:
|
|
|
|
---------------
|
|
$ autoreconf -i
|
|
---------------
|
|
|
|
If you are building aria2 for Mac OS X, take a look at
|
|
build_osx_release.sh, which builds OSX universal binary DMG.
|
|
|
|
The quickest way to build aria2 is just type following commands:
|
|
|
|
-------------
|
|
$ ./configure
|
|
$ make
|
|
-------------
|
|
|
|
The configure script checks available libraries and enables the features
|
|
as much as possible because all the features are enabled by default.
|
|
|
|
Since 1.1.0, aria2 checks the certificate of HTTPS servers by default.
|
|
If you build with HTTPS support, I recommend to supply the path to the
|
|
CA bundle file. For example, in Debian the path to CA bundle file is
|
|
'/etc/ssl/certs/ca-certificates.crt' (in ca-certificates package). This
|
|
may vary depending on your distribution. You can give it to
|
|
configure script using \--with-ca-bundle option:
|
|
|
|
-------------------------------------------------------------------
|
|
$ ./configure --with-ca-bundle='/etc/ssl/certs/ca-certificates.crt'
|
|
$ make
|
|
-------------------------------------------------------------------
|
|
|
|
Without \--with-ca-bundle option, you will encounter the error when
|
|
accessing HTTPS servers because the certificate cannot be verified
|
|
without CA bundle. In such case, you can specify the CA bundle file
|
|
using aria2's \--ca-certificate option. If you don't have CA bundle
|
|
file installed, then the last resort is disable the certificate
|
|
validation using \--check-certificate=false.
|
|
|
|
The executable is 'aria2c' in src directory.
|
|
|
|
aria2 uses CppUnit for automated unit testing. To run the unit test:
|
|
|
|
------------
|
|
$ make check
|
|
------------
|
|
|
|
BitTorrrent
|
|
-----------
|
|
About filename
|
|
~~~~~~~~~~~~~~
|
|
The filename of the downloaded file is determined as follows:
|
|
|
|
single-file mode::
|
|
If "name" key is present in .torrent file, filename is the value
|
|
of "name" key. Otherwise, filename is the basename of .torrent
|
|
file appended by ".file". For example, .torrent file is
|
|
"test.torrrent", then filename is "test.torrent.file". The
|
|
directory to store the downloaded file can be specified by -d
|
|
option.
|
|
|
|
multi-file mode::
|
|
The complete directory/file structure mentioned in .torrent file
|
|
is created. The directory to store the top directory of
|
|
downloaded files can be specified by -d option.
|
|
|
|
Before download starts, a complete directory structure is created if
|
|
needed. By default, aria2 opens at most 100 files mentioned in
|
|
.torrent file, and directly writes to and reads from these files.
|
|
The number of files to open simultaneously can be controlled by
|
|
\--bt-max-open-files option.
|
|
|
|
DHT
|
|
~~~
|
|
|
|
aria2 supports mainline compatible DHT. By default, the routing table
|
|
for IPv4 DHT is saved to $HOME/.aria2/dht.dat and the routing table
|
|
for IPv6 DHT is saved to $HOME/.aria2/dht6.dat. aria2 uses same port
|
|
number to listen on for both IPv4 and IPv6 DHT.
|
|
|
|
Other things should be noted
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
* -o option is used to change the filename of .torrent file itself,
|
|
not a filename of a file in .torrent file. For this purpose, use
|
|
--index-out option instead.
|
|
* The port numbers that aria2 uses by default are 6881-6999 for TCP
|
|
and UDP.
|
|
* aria2 doesn't configure port-forwarding automatically. Please
|
|
configure your router or firewall manually.
|
|
* The maximum number of peers is 55. This limit may be exceeded when
|
|
download rate is low. This download rate can be adjusted using
|
|
\--bt-request-peer-speed-limit option.
|
|
* As of release 0.10.0, aria2 stops sending request message after
|
|
selective download completes.
|
|
|
|
Metalink
|
|
--------
|
|
|
|
The current implementation supports HTTP(S)/FTP/BitTorrent. The other
|
|
P2P protocols are ignored. Both Metalink4 and Metalink version 3.0
|
|
documents are supported.
|
|
|
|
For checksum verification, md5, sha-1, sha-224, sha-256, sha-384 and
|
|
sha-512 are supported. If multiple hash algorithms are provided, aria2
|
|
uses stronger one. If whole file checksum verification fails, aria2
|
|
doesn't retry the download and just exits with non-zero return code.
|
|
|
|
The supported user preferences are version, language, location,
|
|
protocol and os.
|
|
|
|
If chunk checksums are provided in Metalink file, aria2 automatically
|
|
validates chunks of data during download. This behavior can be turned
|
|
off by a command-line option.
|
|
|
|
If signature is included in a Metalink file, aria2 saves it as a file
|
|
after the completion of the download. The filename is download
|
|
filename + ".sig". If same file already exists, the signature file is
|
|
not saved.
|
|
|
|
In Metalink4, multi-file torrent could appear in metalink:metaurl
|
|
element. Since aria2 cannot download 2 same torrents at the same
|
|
time, aria2 groups files in metalink:file element which has same
|
|
BitTorrent metaurl and downloads them from a single BitTorrent swarm.
|
|
This is basically multi-file torrent download with file selection, so
|
|
the adjacent files which is not in Metalink document but shares same
|
|
piece with selected file are also created.
|
|
|
|
If relative URI is specified in metalink:url or metalink:metaurl
|
|
element, aria2 uses the URI of Metalink file as base URI to resolve
|
|
the relative URI. If relative URI is found in Metalink file which is
|
|
read from local disk, aria2 uses the value of --metalink-base-uri
|
|
option as base URI. If this option is not specified, the relative URI
|
|
will be ignored.
|
|
|
|
Metalink/HTTP
|
|
-------------
|
|
|
|
The current implementation only uses rel=duplicate links only. aria2
|
|
understands Digest header fields and check whether it matches the
|
|
digest value from other sources. If it differs, drop connection.
|
|
aria2 also uses this digest value to perform checksum verification
|
|
after download finished. aria2 recognizes geo value. To tell aria2
|
|
which location you prefer, you can use --metalink-location option.
|
|
|
|
netrc
|
|
-----
|
|
netrc support is enabled by default for HTTP(S)/FTP. To disable netrc
|
|
support, specify -n command-line option. Your .netrc file should have
|
|
correct permissions(600).
|
|
|
|
References
|
|
----------
|
|
* http://aria2.sourceforge.net/aria2c.1.html[aria2 Online Manual]
|
|
* http://aria2.sourceforge.net/
|
|
* http://sourceforge.net/apps/trac/aria2/wiki
|
|
* https://github.com/tatsuhiro-t/aria2
|
|
* http://tools.ietf.org/html/rfc5854
|
|
* http://tools.ietf.org/html/rfc6249
|
|
* http://tools.ietf.org/html/rfc6455
|