From c674f54cf49dacff366764408d4b9808b347e767 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Mon, 1 Dec 2008 16:49:23 +0000 Subject: [PATCH] 2008-12-02 Tatsuhiro Tsujikawa Fixed typos and updated doc. * README --- ChangeLog | 5 ++ README | 175 ++++++++++++++++++++++++----------------------- README.html | 191 +++++++++++++++++++++++++++++----------------------- 3 files changed, 203 insertions(+), 168 deletions(-) diff --git a/ChangeLog b/ChangeLog index e6117c78..822f55e5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-12-02 Tatsuhiro Tsujikawa + + Fixed typos and updated doc. + * README + 2008-12-02 Tatsuhiro Tsujikawa Fixed typos diff --git a/README b/README index f7dd06ef..1c3be329 100644 --- a/README +++ b/README @@ -10,15 +10,14 @@ 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. -It 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. +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. @@ -30,7 +29,11 @@ Here is a list of features. * 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. @@ -39,13 +42,14 @@ Here is a list of features. * FTP through HTTP Proxy * Download/Upload speed throttling * BitTorrent extensions: Fast extension, DHT, PEX, MSE/PSE, Multi-Tracker -* Run as a daemon process. +* 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 +* Download URIs found in a text file or stdin and the destination directory and + output filename can be specified optionally * Parameterized URI support Dependency @@ -73,17 +77,19 @@ 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. +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 +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): +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) @@ -93,7 +99,8 @@ packages(package name may vary depending on the distribution you use): * 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: +You can use libssl-dev instead of +libgnutls-dev,libgpg-error-dev,libgcrypt-dev: * libssl-dev (Required for HTTPS, BitTorrent, Checksum support) @@ -123,80 +130,84 @@ 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. + 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. + 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, 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 can be controlled by "--bt-max-open-files" 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 is 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. +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. +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. -* As of release 0.10.0, aria2 stops sending request message after selective - download completes, +* -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/FTP/BitTorrent. -The other P2P protocols are ignored. +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. +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. +The supported user preferences are version, language, location, +protocol and os. -If chunk checksums are provided in Metalink file, aria2 automatically validate -a chunk of file while downloading it. This behavior can be turned off by -a command-line option. +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 -download completed. -The filename is download filename + ".sig". If same file already exists, the -signature file is not saved. +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). +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). SERVER PERFORMANCE PROFILE -------------------------- -This section describes the format of server performance profile. -The file is plain text and each line has several NAME=VALUE pair, delimited by -comma. -Currently following NAMEs are recognized: +This section describes the format of server performance profile. The +file is plain text and each line has several NAME=VALUE pair, +delimited by comma. Currently following NAMEs are recognized: host:: Hostname of the server. Required. @@ -205,19 +216,20 @@ protocol:: Protocol for this profile, such as ftp, http. Required. dl_speed:: - The average download speed observed in the previous download in bytes per sec. - Required. + The average download speed observed in the previous download in + bytes per sec. Required. last_updated:: - Last contact time in GMT with this server, specified in the seconds from the - Epoch. Required. + Last contact time in GMT with this server, specified in the seconds + from the Epoch. Required. status:: - ERROR is set when server cannot be reached or out-of-service or timeout - occurred. Otherwise, OK is set. + ERROR is set when server cannot be reached or out-of-service or + timeout occurred. Otherwise, OK is set. -Those fields must exist in one line. The order of the fields is not significant. -You can put pairs other than above; they are simply ignored. +Those fields must exist in one line. The order of the fields is not +significant. You can put pairs other than above but they are simply +ignored. An example is follow: -------------------------------------------------------------------------------- @@ -227,18 +239,15 @@ host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR Configuration file ------------------ -Configuration file must be placed under $HOME/.aria2 and must be named as -aria2.conf. -In each line, there is 1 parameter whose syntax is name=value pair, -where name is the long command-line option name without '--' prefix. -The lines beginning '#' are treated as comments. +Configuration file must be placed under $HOME/.aria2 and must be named +as aria2.conf. In each line, there is 1 parameter whose syntax is +name=value pair, where name is the long command-line option name +without '--' prefix. The lines beginning '#' are treated as comments. Example: -------------------------------------- # sample configuration file for aria2c -file-allocation=prealloc listen-port=60000 seed-ratio=1.0 max-upload-limit=40K -ftp-pasv=true --------------------------------------- diff --git a/README.html b/README.html index c217c601..851e9942 100644 --- a/README.html +++ b/README.html @@ -354,15 +354,14 @@ You must use this program at your own risk.

2. Introduction

-

aria2 is a utility for downloading files. The supported protocols are HTTP(S), -FTP, BitTorrent, and Metalink. -It 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.

+

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.

  • @@ -407,11 +406,27 @@ 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

    • @@ -448,7 +463,7 @@ BitTorrent extensions: Fast extension, DHT, PEX, MSE/PSE, Multi-Tracker

  • -Run as a daemon process. +Run as a daemon process

  • @@ -478,7 +493,8 @@ Configuration file support

  • -Download URIs found in a text file or stdin +Download URIs found in a text file or stdin and the destination directory and + output filename can be specified optionally

  • @@ -587,9 +603,10 @@ Note

-

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

+

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.

4. 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):

+

In order to build aria2 from the source package, you need following +development packages(package name may vary depending on the +distribution you use):

  • @@ -639,7 +657,8 @@ libsqlite3-dev (Required for Firefox3 cookie support)

-

You can use libssl-dev instead of libgnutls-dev,libgpg-error-dev,libgcrypt-dev:

+

You can use libssl-dev instead of +libgnutls-dev,libgpg-error-dev,libgcrypt-dev:

  • @@ -678,11 +697,12 @@ 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. + 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.

    @@ -690,88 +710,91 @@ 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. + 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, 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 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 is 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.

+

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.

5.2. DHT

-

As of release 0.13.0, aria2 supports DHT. By default, the routing table is saved -to $HOME/.aria2/dht.dat.

+

As of release 0.13.0, aria2 supports DHT. By default, the routing +table is saved to $HOME/.aria2/dht.dat.

5.3. 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. +-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. +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. +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. +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, +As of release 0.10.0, aria2 stops sending request message after + selective download completes.

6. Metalink

-

The current implementation supports HTTP/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 validate -a chunk of file while downloading it. 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 -download completed. -The filename is download filename + ".sig". If same file already exists, the -signature file is not saved.

+

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.

7. 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).

+

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).

8. SERVER PERFORMANCE PROFILE

-

This section describes the format of server performance profile. -The file is plain text and each line has several NAME=VALUE pair, delimited by -comma. -Currently following NAMEs are recognized:

+

This section describes the format of server performance profile. The +file is plain text and each line has several NAME=VALUE pair, +delimited by comma. Currently following NAMEs are recognized:

host @@ -794,8 +817,8 @@ dl_speed

- The average download speed observed in the previous download in bytes per sec. - Required. + The average download speed observed in the previous download in + bytes per sec. Required.

@@ -803,8 +826,8 @@ last_updated

- Last contact time in GMT with this server, specified in the seconds from the - Epoch. Required. + Last contact time in GMT with this server, specified in the seconds + from the Epoch. Required.

@@ -812,13 +835,14 @@ status

- ERROR is set when server cannot be reached or out-of-service or timeout - occurred. Otherwise, OK is set. + ERROR is set when server cannot be reached or out-of-service or + timeout occurred. Otherwise, OK is set.

-

Those fields must exist in one line. The order of the fields is not significant. -You can put pairs other than above; they are simply ignored.

+

Those fields must exist in one line. The order of the fields is not +significant. You can put pairs other than above but they are simply +ignored.

An example is follow:

@@ -828,25 +852,22 @@ host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR<

9. Configuration file

-

Configuration file must be placed under $HOME/.aria2 and must be named as -aria2.conf. -In each line, there is 1 parameter whose syntax is name=value pair, -where name is the long command-line option name without — prefix. -The lines beginning # are treated as comments.

+

Configuration file must be placed under $HOME/.aria2 and must be named +as aria2.conf. In each line, there is 1 parameter whose syntax is +name=value pair, where name is the long command-line option name +without — prefix. The lines beginning # are treated as comments.

Example:

# sample configuration file for aria2c
-file-allocation=prealloc
 listen-port=60000
 seed-ratio=1.0
-max-upload-limit=40K
-ftp-pasv=true
+max-upload-limit=40K