2009-05-27 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>

Updated README for 1.4.0 release. Use new table syntax of
	asciidoc.
	* README
This commit is contained in:
Tatsuhiro Tsujikawa 2009-05-26 15:53:39 +00:00
parent 1c1ec3bd6d
commit 861ada066f
3 changed files with 174 additions and 142 deletions

View File

@ -1,3 +1,9 @@
2009-05-27 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
Updated README for 1.4.0 release. Use new table syntax of
asciidoc.
* README
2009-05-27 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
Documented --xml-rpc-max-request-size option in man page.

26
README
View File

@ -37,6 +37,7 @@ Here is a list of features.
* Chunked transfer encoding support
* Load Cookies from file using the Firefox3 format 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
@ -46,6 +47,7 @@ Here is a list of features.
(single-file torrent only)
* Rename/change the directory structure of BitTorrent downloads
completely
* XML-RPC interface
* Run as a daemon process
* Selective download in multi-file torrent/Metalink
* Chunk checksum validation in Metalink
@ -60,18 +62,18 @@ 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
-------------------------------------------------
[options="header"]
|=================================================
|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
|XML-RPC |libxml2 or Expat.
|=================================================
Note;;
GNU TLS has precedence over OpenSSL if both libraries are installed.

View File

@ -3,7 +3,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.2.7" />
<meta name="generator" content="AsciiDoc 8.4.4" />
<title>aria2 - The ultra fast download utility</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
@ -110,11 +111,13 @@ div#footer-badges {
padding-bottom: 0.5em;
}
div#preamble,
div#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-right: 10%;
margin-top: 1.5em;
margin-bottom: 1.5em;
}
@ -156,9 +159,6 @@ div.sidebarblock > div.content {
padding: 0.5em;
}
div.listingblock {
margin-right: 0%;
}
div.listingblock > div.content {
border: 1px solid silver;
background: #f4f4f4;
@ -167,6 +167,7 @@ div.listingblock > div.content {
div.quoteblock {
padding-left: 2.0em;
margin-right: 10%;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
@ -175,6 +176,7 @@ div.quoteblock > div.attribution {
div.verseblock {
padding-left: 2.0em;
margin-right: 10%;
}
div.verseblock > div.content {
white-space: pre;
@ -218,6 +220,7 @@ dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
@ -226,12 +229,28 @@ dd > *:first-child {
ul, ol {
list-style-position: outside;
}
div.olist > ol {
ol.arabic {
list-style-type: decimal;
}
div.olist2 > ol {
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
div.tableblock > table {
border: 3px solid #527bbd;
@ -243,22 +262,53 @@ thead {
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
div.hlist {
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hlist td {
div.hdlist tr {
padding-bottom: 15px;
}
td.hlist1 {
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hlist2 {
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
@media print {
div#footer-badges { display: none; }
@ -330,16 +380,7 @@ div.exampleblock-content {
/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
/* Because IE6 child selector is broken. */
div.olist2 ol {
list-style-type: lower-alpha;
}
div.olist2 div.olist ol {
list-style-type: decimal;
}
</style>
<title>aria2 - The ultra fast download utility</title>
</head>
<body>
<div id="header">
@ -349,21 +390,21 @@ div.olist2 div.olist ol {
</div>
<h2 id="_disclaimer">1. Disclaimer</h2>
<div class="sectionbody">
<div class="para"><p>This program comes with no warranty.
<div class="paragraph"><p>This program comes with no warranty.
You must use this program at your own risk.</p></div>
</div>
<h2 id="_introduction">2. Introduction</h2>
<div class="sectionbody">
<div class="para"><p>aria2 is a utility for downloading files. The supported protocols are
<div class="paragraph"><p>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
HTTP(S)/FTP is uploaded to the BitTorrent swarm. Using Metalink&#8217;s
chunk checksums, aria2 automatically validates chunks of data while
downloading a file like BitTorrent.</p></div>
<div class="para"><p>Here is a list of features.</p></div>
<div class="ilist"><ul>
<div class="paragraph"><p>Here is a list of features.</p></div>
<div class="ulist"><ul>
<li>
<p>
Command-line interface
@ -438,6 +479,11 @@ Load Cookies from file using the Firefox3 format and the Mozilla/Firefox
</li>
<li>
<p>
Save Cookies in the Mozilla/Firefox (1.x/2.x)/Netscape format.
</p>
</li>
<li>
<p>
Custom HTTP Header support
</p>
</li>
@ -475,6 +521,11 @@ Rename/change the directory structure of BitTorrent downloads
</li>
<li>
<p>
XML-RPC interface
</p>
</li>
<li>
<p>
Run as a daemon process
</p>
</li>
@ -520,83 +571,56 @@ Parameterized URI support
<div class="sectionbody">
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table: External Library Dependency</caption>
<col width="240" />
<col width="320" />
<caption class="title">External Library Dependency</caption>
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left">
features
</th>
<th align="left">
dependency
</th>
</tr>
<tr>
<th align="left" valign="top">features </th>
<th align="left" valign="top">dependency</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td align="left">
HTTPS
</td>
<td align="left">
GnuTLS or OpenSSL
</td>
</tr>
<tr>
<td align="left">
BitTorrent
</td>
<td align="left">
GnuTLS+Libgcrypt or OpenSSL
</td>
</tr>
<tr>
<td align="left">
Metalink
</td>
<td align="left">
libxml2 or Expat.
</td>
</tr>
<tr>
<td align="left">
Checksum
</td>
<td align="left">
GnuTLS+Libgcrypt or OpenSSL
</td>
</tr>
<tr>
<td align="left">
gzip, deflate in HTTP
</td>
<td align="left">
zlib
</td>
</tr>
<tr>
<td align="left">
Async DNS
</td>
<td align="left">
C-Ares
</td>
</tr>
<tr>
<td align="left">
Firefox3 cookie
</td>
<td align="left">
libsqlite3
</td>
</tr>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">HTTPS</p></td>
<td align="left" valign="top"><p class="table">GnuTLS or OpenSSL</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">BitTorrent</p></td>
<td align="left" valign="top"><p class="table">GnuTLS+Libgcrypt or OpenSSL</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Metalink</p></td>
<td align="left" valign="top"><p class="table">libxml2 or Expat.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Checksum</p></td>
<td align="left" valign="top"><p class="table">GnuTLS+Libgcrypt or OpenSSL</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">gzip, deflate in HTTP</p></td>
<td align="left" valign="top"><p class="table">zlib</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Async DNS</p></td>
<td align="left" valign="top"><p class="table">C-Ares</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Firefox3 cookie</p></td>
<td align="left" valign="top"><p class="table">libsqlite3</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">XML-RPC</p></td>
<td align="left" valign="top"><p class="table">libxml2 or Expat.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="vlist"><dl>
<dt>
<div class="dlist"><dl>
<dt class="hdlist1">
Note
</dt>
<dd>
@ -605,7 +629,7 @@ Note
If you prefer OpenSSL, run configure with --without-gnutls.
</p>
</dd>
<dt>
<dt class="hdlist1">
Note
</dt>
<dd>
@ -615,11 +639,11 @@ Note
</p>
</dd>
</dl></div>
<div class="para"><p>You can disable BitTorrent, Metalink support by providing
<div class="paragraph"><p>You can disable BitTorrent, Metalink support by providing
--disable-bittorrent, --disable-metalink respectively to configure
script.</p></div>
<div class="para"><p>In order to enable async DNS support, you need c-ares.</p></div>
<div class="ilist"><ul>
<div class="paragraph"><p>In order to enable async DNS support, you need c-ares.</p></div>
<div class="ulist"><ul>
<li>
<p>
c-ares: <a href="http://daniel.haxx.se/projects/c-ares/">http://daniel.haxx.se/projects/c-ares/</a>
@ -629,10 +653,10 @@ c-ares: <a href="http://daniel.haxx.se/projects/c-ares/">http://daniel.haxx.se/p
</div>
<h2 id="_how_to_build">4. How to build</h2>
<div class="sectionbody">
<div class="para"><p>In order to build aria2 from the source package, you need following
<div class="paragraph"><p>In order to build aria2 from the source package, you need following
development packages(package name may vary depending on the
distribution you use):</p></div>
<div class="ilist"><ul>
<div class="ulist"><ul>
<li>
<p>
libgnutls-dev (Required for HTTPS, BitTorrent, Checksum support)
@ -669,32 +693,32 @@ libsqlite3-dev (Required for Firefox3 cookie support)
</p>
</li>
</ul></div>
<div class="para"><p>You can use libssl-dev instead of
<div class="paragraph"><p>You can use libssl-dev instead of
libgnutls-dev,libgpg-error-dev,libgcrypt-dev:</p></div>
<div class="ilist"><ul>
<div class="ulist"><ul>
<li>
<p>
libssl-dev (Required for HTTPS, BitTorrent, Checksum support)
</p>
</li>
</ul></div>
<div class="para"><p>You can use libexpat1-dev instead of libxml2-dev:</p></div>
<div class="ilist"><ul>
<div class="paragraph"><p>You can use libexpat1-dev instead of libxml2-dev:</p></div>
<div class="ulist"><ul>
<li>
<p>
libexpat1-dev (Required for Metalink support)
</p>
</li>
</ul></div>
<div class="para"><p>The quickest way to build aria2 is just type following commands:</p></div>
<div class="paragraph"><p>The quickest way to build aria2 is just type following commands:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ ./configure
$ make</tt></pre>
</div></div>
<div class="para"><p>The configure script checks available libraries and enables the features
<div class="paragraph"><p>The configure script checks available libraries and enables the features
as much as possible because all the features are enabled by default.</p></div>
<div class="para"><p>Since 1.1.0, aria2 checks the certificate of HTTPS servers by default.
<div class="paragraph"><p>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
<em>/etc/ssl/certs/ca-certificates.crt</em> (in ca-certificates package). This
@ -705,14 +729,14 @@ configure script using --with-ca-bundle option:</p></div>
<pre><tt>$ ./configure --with-ca-bundle='/etc/ssl/certs/ca-certificates.crt'
$ make</tt></pre>
</div></div>
<div class="para"><p>Without --with-ca-bundle option, you will encounter the error when
<div class="paragraph"><p>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
using aria2&#8217;s --ca-certificate option. If you don&#8217;t have CA bundle
file installed, then the last resort is disable the certificate
validation using --check-certificate=false.</p></div>
<div class="para"><p>The executable is <em>aria2c</em> in src directory.</p></div>
<div class="para"><p>aria2 uses CppUnit for automated unit testing. To run the unit test:</p></div>
<div class="paragraph"><p>The executable is <em>aria2c</em> in src directory.</p></div>
<div class="paragraph"><p>aria2 uses CppUnit for automated unit testing. To run the unit test:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ make check</tt></pre>
@ -721,9 +745,9 @@ validation using --check-certificate=false.</p></div>
<h2 id="_bittorrrent">5. BitTorrrent</h2>
<div class="sectionbody">
<h3 id="_about_filename">5.1. About filename</h3><div style="clear:left"></div>
<div class="para"><p>The filename of the downloaded file is determined as follows:</p></div>
<div class="vlist"><dl>
<dt>
<div class="paragraph"><p>The filename of the downloaded file is determined as follows:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
single-file mode
</dt>
<dd>
@ -736,7 +760,7 @@ single-file mode
option.
</p>
</dd>
<dt>
<dt class="hdlist1">
multi-file mode
</dt>
<dd>
@ -747,16 +771,16 @@ multi-file mode
</p>
</dd>
</dl></div>
<div class="para"><p>Before download starts, a complete directory structure is created if
<div class="paragraph"><p>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.</p></div>
<h3 id="_dht">5.2. DHT</h3><div style="clear:left"></div>
<div class="para"><p>As of release 0.13.0, aria2 supports DHT. By default, the routing
<div class="paragraph"><p>As of release 0.13.0, aria2 supports DHT. By default, the routing
table is saved to $HOME/.aria2/dht.dat.</p></div>
<h3 id="_other_things_should_be_noted">5.3. Other things should be noted</h3><div style="clear:left"></div>
<div class="ilist"><ul>
<div class="ulist"><ul>
<li>
<p>
-o option is used to change the filename of .torrent file itself,
@ -771,7 +795,7 @@ The port numbers that aria2 uses by default are 6881-6999 for TCP
</li>
<li>
<p>
aria2 doesn't configure port-forwarding automatically. Please
aria2 doesn&#8217;t configure port-forwarding automatically. Please
configure your router or firewall manually.
</p>
</li>
@ -792,31 +816,31 @@ As of release 0.10.0, aria2 stops sending request message after
</div>
<h2 id="_metalink">6. Metalink</h2>
<div class="sectionbody">
<div class="para"><p>The current implementation supports HTTP(S)/FTP/BitTorrent. The other
<div class="paragraph"><p>The current implementation supports HTTP(S)/FTP/BitTorrent. The other
P2P protocols are ignored.</p></div>
<div class="para"><p>For checksum verification, MD5, SHA1, and SHA256 are supported. If
<div class="paragraph"><p>For checksum verification, MD5, SHA1, and SHA256 are supported. If
multiple hash algorithms are provided, aria2 uses SHA1. If whole file
checksum verification fails, aria2 doesn't retry the download and just
checksum verification fails, aria2 doesn&#8217;t retry the download and just
exits with non-zero return code.</p></div>
<div class="para"><p>The supported user preferences are version, language, location,
<div class="paragraph"><p>The supported user preferences are version, language, location,
protocol and os.</p></div>
<div class="para"><p>If chunk checksums are provided in Metalink file, aria2 automatically
<div class="paragraph"><p>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.</p></div>
<div class="para"><p>If signature is included in a Metalink file, aria2 saves it as a file
<div class="paragraph"><p>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.</p></div>
</div>
<h2 id="_netrc">7. netrc</h2>
<div class="sectionbody">
<div class="para"><p>netrc support is enabled by default for HTTP(S)/FTP. To disable netrc
<div class="paragraph"><p>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).</p></div>
</div>
<h2 id="_references">8. References</h2>
<div class="sectionbody">
<div class="ilist"><ul>
<div class="ulist"><ul>
<li>
<p>
man aria2c
@ -836,7 +860,7 @@ man aria2c
</div>
<div id="footer">
<div id="footer-text">
Last updated 2009-04-28 22:20:49 JST
Last updated 2009-05-27 00:49:50 JST
</div>
</div>
</body>