mirror of
https://github.com/aria2/aria2.git
synced 2024-12-29 14:14:53 +00:00
8cac61a25f
Removed SERVER PERFORMANCE PROFILE and Configuration file section because same documents are available in man page. Added References section. * README
233 lines
8.5 KiB
Plaintext
233 lines
8.5 KiB
Plaintext
aria2 - The ultra fast download utility
|
|
=======================================
|
|
:Author: Tatsuhiro Tsujikawa
|
|
:Email: 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.
|
|
|
|
Here is a list of features.
|
|
|
|
* Command-line interface
|
|
* Download files through HTTP(S)/FTP/BitTorrent
|
|
* Segmented downloading
|
|
* Metalink version 3.0 support(HTTP/FTP/BitTorrent)
|
|
* 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 and 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
|
|
* 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
|
|
|
|
Dependency
|
|
----------
|
|
|
|
.External Library Dependency
|
|
[frame="all", grid="all"]
|
|
`--------------------`---------------------------
|
|
features dependency
|
|
-------------------------------------------------
|
|
HTTPS GnuTLS or OpenSSL
|
|
BitTorrent GnuTLS+Libgcrypt or OpenSSL
|
|
Metalink libxml2 or Expat.
|
|
Checksum GnuTLS+Libgcrypt or OpenSSL
|
|
gzip, deflate in HTTP zlib
|
|
Async DNS C-Ares
|
|
Firefox3 cookie libsqlite3
|
|
-------------------------------------------------
|
|
|
|
Note;;
|
|
GNU TLS has precedence over OpenSSL if both libraries are installed.
|
|
If you prefer OpenSSL, run configure with \--without-gnutls.
|
|
|
|
Note;;
|
|
libxml2 has precedence over Expat if both libraries are installed.
|
|
If you prefer Expat, run configure with \--without-libxml2.
|
|
|
|
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)
|
|
* libgpg-error-dev (Required for BitTorrent, Checksum support)
|
|
* libgcrypt-dev (Required for BitTorrent, Checksum support)
|
|
* libc-ares-dev (Required for async DNS support)
|
|
* libxml2-dev (Required for Metalink support)
|
|
* libz1g-dev (Required for gzip, deflate decoding support in HTTP)
|
|
* libsqlite3-dev (Required for Firefox3 cookie support)
|
|
|
|
You can use libssl-dev instead of
|
|
libgnutls-dev,libgpg-error-dev,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)
|
|
|
|
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 varies depending on the distributions. 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 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.
|
|
|
|
In the default behavior, before download starts, a complete directory
|
|
structure is created if needed. By default, aria2 opens at most 100
|
|
files mentioned in .torrent file, directly writes to and reads from
|
|
these files. The number of files to open simultaneously can be
|
|
controlled by \--bt-max-open-files option.
|
|
|
|
If \--direct-file-mapping option set to be false, aria2 creates
|
|
temporary file in the store directory. The length of this file is the
|
|
sum of length of the files in .torrent file, so at least 2 times more
|
|
disk space than the file size itself is required. Writing and reading
|
|
are done against this file. After download completes, aria2 creates
|
|
complete directory structure if needed, and copies whole file or a
|
|
part of it to the destination.
|
|
|
|
DHT
|
|
~~~
|
|
As of release 0.13.0, aria2 supports DHT. By default, the routing
|
|
table is saved to $HOME/.aria2/dht.dat.
|
|
|
|
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.
|
|
* 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.
|
|
|
|
For checksum checking, MD5, SHA1, SHA256 are supported. If multiple
|
|
hash algorithms are provided, aria2 uses SHA1. If checksum checking is
|
|
failed, 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.
|
|
|
|
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
|
|
----------
|
|
* man aria2c
|
|
* http://aria2.sourceforge.net/
|
|
* https://apps.sourceforge.net/trac/aria2/wiki
|