From 4a5f2b6f9f189ed67e51054e40b5073a2abeb509 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sun, 22 Apr 2012 21:21:26 +0900 Subject: [PATCH] Use Sphinx for aria2 manual page documentation. The source files for manual pages are placed under doc/manual-src. The built manual pages are placed under doc/manual. When installed, manual pages are placed under $(docdir)/manual/. --- configure.ac | 6 +- doc/Makefile.am | 16 +- doc/manual-src/Makefile.am | 1 + doc/manual-src/en/Makefile.am | 156 ++ doc/manual-src/en/aria2c.rst | 3893 ++++++++++++++++++++++++++++++++ doc/manual-src/en/conf.py.in | 215 ++ doc/manual-src/en/index.rst | 14 + doc/manual-src/ru/Makefile.am | 157 ++ doc/manual-src/ru/aria2c.rst | 4011 +++++++++++++++++++++++++++++++++ doc/manual-src/ru/conf.py.in | 215 ++ doc/manual-src/ru/index.rst | 14 + 11 files changed, 8683 insertions(+), 15 deletions(-) create mode 100644 doc/manual-src/Makefile.am create mode 100644 doc/manual-src/en/Makefile.am create mode 100644 doc/manual-src/en/aria2c.rst create mode 100644 doc/manual-src/en/conf.py.in create mode 100644 doc/manual-src/en/index.rst create mode 100644 doc/manual-src/ru/Makefile.am create mode 100644 doc/manual-src/ru/aria2c.rst create mode 100644 doc/manual-src/ru/conf.py.in create mode 100644 doc/manual-src/ru/index.rst diff --git a/configure.ac b/configure.ac index e21ff692..b2a5358b 100644 --- a/configure.ac +++ b/configure.ac @@ -579,7 +579,11 @@ AC_CONFIG_FILES([Makefile intl/Makefile lib/Makefile doc/Makefile - doc/ru/Makefile + doc/manual-src/Makefile + doc/manual-src/en/Makefile + doc/manual-src/en/conf.py + doc/manual-src/ru/Makefile + doc/manual-src/ru/conf.py deps/Makefile]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index 72be15e5..a91a2ab4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,5 @@ -SUBDIRS = ru -man_MANS = aria2c.1 -EXTRA_DIST = $(man_MANS) -dist_doc_DATA = aria2c.1.html aria2c.1.asciidoc +SUBDIRS = manual-src + doc_xmlrpcdir = $(docdir)/xmlrpc dist_doc_xmlrpc_DATA = xmlrpc/aria2mon \ xmlrpc/aria2rpc \ @@ -9,13 +7,3 @@ dist_doc_xmlrpc_DATA = xmlrpc/aria2mon \ doc_bashcompletiondir = $(docdir)/bash_completion dist_doc_bashcompletion_DATA = bash_completion/README.txt \ bash_completion/aria2c - -if HAVE_A2X -aria2c.1: aria2c.1.asciidoc - @A2X@ -f manpage aria2c.1.asciidoc -endif # HAVE_A2X - -if HAVE_ASCIIDOC -aria2c.1.html: aria2c.1.asciidoc - @ASCIIDOC@ -d manpage -b xhtml11 -a toc -a max-width=55em aria2c.1.asciidoc -endif # HAVE_ASCIIDOC diff --git a/doc/manual-src/Makefile.am b/doc/manual-src/Makefile.am new file mode 100644 index 00000000..45c01778 --- /dev/null +++ b/doc/manual-src/Makefile.am @@ -0,0 +1 @@ +SUBDIRS = en ru diff --git a/doc/manual-src/en/Makefile.am b/doc/manual-src/en/Makefile.am new file mode 100644 index 00000000..4bf9b1d6 --- /dev/null +++ b/doc/manual-src/en/Makefile.am @@ -0,0 +1,156 @@ +# Makefile for Sphinx documentation +# +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = ../../manual/en + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +# Configurations for aria2. +man_MANS = $(BUILDDIR)/man/aria2c.1 +HTML = $(BUILDDIR)/html +EXTRA_DIST = $(man_MANS) $(HTML) +HTMLINSTALLDIR = $(docdir)/manual/en + +# Copy $(BUILDDIR)/html recursively to the install dir. Since Automake +# does not provide this feature, we do it ourselves. +install-data-local: + mkdir -p $(HTMLINSTALLDIR) && \ + cp -r $(BUILDDIR)/html $(HTMLINSTALLDIR) && \ + rm -f $(HTMLINSTALLDIR)/html/.buildinfo + +uninstall-local: + -rm -rf $(HTMLINSTALLDIR) + +dist-hook: + -rm -f $(distdir)/$(BUILDDIR)/html/.buildinfo + +$(man_MANS): aria2c.rst + $(MAKE) man + +$(HTML): aria2c.rst + $(MAKE) html + +# Autogenerated rules by sphinx-quickstart + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/aria2.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/aria2.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/aria2" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/aria2" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/manual-src/en/aria2c.rst b/doc/manual-src/en/aria2c.rst new file mode 100644 index 00000000..f0e038b8 --- /dev/null +++ b/doc/manual-src/en/aria2c.rst @@ -0,0 +1,3893 @@ +aria2c(1) +========= + +SYNOPSIS +-------- +**aria2c** [] [|||] ... + +DESCRIPTION +----------- + +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. + +OPTIONS +------- + +Basic Options +~~~~~~~~~~~~~ +.. option:: -d, --dir= + + The directory to store the downloaded file. + +.. option:: -i, --input-file= + + Downloads URIs found in FILE. You can specify multiple URIs for a single + entity: separate URIs on a single line using the TAB character. + Reads input from stdin when ``-`` is specified. + Additionally, options can be specified after each line of + URI. This optional line must start with one or more white spaces and have + one option per single line. + See `Input File`_ subsection for details. + See also :option:`--deferred-input` option. + +.. option:: -l, --log= + + The file name of the log file. If ``-`` is specified, log is written to + stdout. If empty string("") is specified, log is not written to file. + +.. option:: -j, --max-concurrent-downloads= + + Set maximum number of parallel downloads for every static (HTTP/FTP) URI, + torrent and metalink. See also :option:`--split <-s>` option. + Default: ``5`` + +.. option:: -V, --check-integrity[=true|false] + + Check file integrity by validating piece hashes or a hash of entire + file. This option has effect only in BitTorrent, Metalink downloads + with checksums or HTTP(S)/FTP downloads with + :option:`--checksum` option. If + piece hashes are provided, this option can detect damaged portions + of a file and re-download them. If a hash of entire file is + provided, hash check is only done when file has been already + download. This is determined by file length. If hash check fails, + file is re-downloaded from scratch. If both piece hashes and a hash + of entire file are provided, only piece hashes are used. Default: + ``false`` + +.. option:: -c, --continue[=true|false] + + Continue downloading a partially downloaded file. + Use this option to resume a download started by a web browser or another + program which downloads files sequentially from the beginning. + Currently this option is only applicable to HTTP(S)/FTP downloads. + +.. option:: -h, --help[=|] + + The help messages are classified with tags. A tag starts with + ``#``. For example, type ``--help=#http`` to get the usage for the + options tagged with ``#http``. If non-tag word is given, print the + usage for the options whose name includes that word. Available + Values: ``#basic`` , ``#advanced`` , ``#http`` , ``#https`` , ``#ftp`` , + ``#metalink`` , ``#bittorrent`` , ``#cookie`` , ``#hook`` , ``#file`` , ``#rpc`` , + ``#checksum`` , ``#experimental`` , ``#deprecated`` , ``#help`` , ``#all`` + Default: ``#basic`` + +HTTP/FTP Options +~~~~~~~~~~~~~~~~ +.. option:: --all-proxy= + + Use this proxy server for all protocols. To erase previously + defined proxy, use "". You can override this setting and specify a + proxy server for a particular protocol using :option:`--http-proxy`, + :option:`--https-proxy` and :option:`--ftp-proxy` options. This affects all URIs. + The format of PROXY is ``[http://][USER:PASSWORD@]HOST[:PORT]``. + See also `ENVIRONMENT`_ section. + + .. note:: + + If user and password are embedded in proxy URI and they are also + specified by *--{http,https,ftp,all}-proxy-{user,passwd}* options, + those appeared later have precedence. For example, you have + ``http-proxy-user=myname``, ``http-proxy-passwd=mypass`` in aria2.conf and + you specify ``--http-proxy="http://proxy"`` in command-line, then you get + HTTP proxy ``http://proxy`` with user ``myname`` and password + ``mypass``. + + Another example: if you specified in command-line + ``--http-proxy="http://user:pass@proxy" --http-proxy-user="myname" + --http-proxy-passwd="mypass"``, then you will get HTTP proxy + ``http://proxy`` with user ``myname`` and password ``mypass``. + + One more example: if you specified in command-line ``--http-proxy-user="myname" + --http-proxy-passwd="mypass" --http-proxy="http://user:pass@proxy"``, + then you get HTTP proxy ``http://proxy`` with user ``user`` and password + ``pass``. + +.. option:: --all-proxy-passwd= + + Set password for :option:`--all-proxy` option. + +.. option:: --all-proxy-user= + + Set user for :option:`--all-proxy` option. + +.. option:: --checksum== + + Set checksum. TYPE is hash type. The supported hash type is listed + in ``Hash Algorithms`` in ``aria2c -v``. DIGEST is hex digest. For + example, setting sha-1 digest looks like this: + ``sha-1=0192ba11326fe2298c8cb4de616f4d4140213838`` This option applies + only to HTTP(S)/FTP downloads. + +.. option:: --connect-timeout= + + Set the connect timeout in seconds to establish connection to + HTTP/FTP/proxy server. After the connection is established, this + option makes no effect and :option:`--timeout <-t>` option is used instead. + Default: ``60`` + +.. option:: --dry-run[=true|false] + + If ``true`` is given, aria2 just checks whether the remote file is + available and doesn't download data. This option has effect on + HTTP/FTP download. BitTorrent downloads are canceled if ``true`` is + specified. Default: ``false`` + +.. option:: --lowest-speed-limit= + + Close connection if download speed is lower than or equal to this + value(bytes per sec). + ``0`` means aria2 does not have a lowest speed limit. + You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + This option does not affect BitTorrent downloads. + Default: ``0`` + +.. option:: -x, --max-connection-per-server= + + The maximum number of connections to one server for each download. + Default: ``1`` + +.. option:: --max-file-not-found= + + If aria2 receives "file not found" status from the remote HTTP/FTP + servers NUM times without getting a single byte, then force the + download to fail. Specify ``0`` to disable this option. This options is + effective only when using HTTP/FTP servers. + Default: ``0`` + +.. option:: -m, --max-tries= + + Set number of tries. ``0`` means unlimited. + See also :option:`--retry-wait`. + Default: ``5`` + +.. option:: -k, --min-split-size= + + aria2 does not split less than 2*SIZE byte range. For example, + let's consider downloading 20MiB file. If SIZE is 10M, aria2 can + split file into 2 range [0-10MiB) and [10MiB-20MiB) and download it + using 2 sources(if :option:`--split <-s>` >= 2, of course). If SIZE is 15M, + since 2*15M > 20MiB, aria2 does not split file and download it using + 1 source. You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + Possible Values: ``1M`` -``1024M`` Default: ``20M`` + +.. option:: -n, --no-netrc[=true|false] + + Disables netrc support. netrc support is enabled by default. + + .. note:: + + netrc file is only read at the startup if + :option:`--no-netrc <-n>` is ``false``. + So if :option:`--no-netrc <-n>` is ``true`` at the startup, + no netrc is available throughout the session. + You cannot get netrc enabled even if you send + :option:`--no-netrc=false <-n>` using + :func:`aria2.changeGlobalOption`. + +.. option:: --no-proxy= + + Specify comma separated hostnames, domains and network address with + or without CIDR block where proxy should not be used. + + .. note:: + + For network address with CIDR block, both IPv4 and IPv6 addresses work. Current + implementation does not resolve hostname in URI to compare network + address specified in :option:`--no-proxy`. So it is only effecive if URI has + numeric IP addresses. + +.. option:: -o, --out= + + The file name of the downloaded file. When :option:`--force-sequential <-Z>` option is used, this + option is ignored. + + .. note:: + + In Metalink or BitTorrent download you cannot specify file name. + The file name specified here is only used when the URIs fed to aria2 + are done by command line without :option:`--input-file <-i>`, :option:`--force-sequential <-Z>` option. For example: + + .. code-block:: console + + $ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip" + +.. option:: --proxy-method= + + Set the method to use in proxy request. METHOD is either ``get`` or + ``tunnel``. HTTPS downloads always use ``tunnel`` regardless of this + option. + Default: ``get`` + +.. option:: -R, --remote-time[=true|false] + + Retrieve timestamp of the remote file from the remote HTTP/FTP + server and if it is available, apply it to the local file. + Default: ``false`` + +.. option:: --reuse-uri[=true|false] + + Reuse already used URIs if no unused URIs are left. + Default: ``true`` + +.. option:: --retry-wait= + + Set the seconds to wait between retries. With SEC > 0, aria2 will + retry download when the HTTP server returns 503 response. Default: + ``0`` + +.. option:: --server-stat-of= + + Specify the filename to which performance profile of the servers is + saved. You can load saved data using :option:`--server-stat-if` option. See + `Server Performance Profile`_ + subsection below for file format. + +.. option:: --server-stat-if= + + Specify the filename to load performance profile of the servers. The + loaded data will be used in some URI selector such as ``feedback``. + See also :option:`--uri-selector` option. See + `Server Performance Profile`_ + subsection below for file format. + +.. option:: --server-stat-timeout= + + Specifies timeout in seconds to invalidate performance profile of + the servers since the last contact to them. + Default: ``86400`` (24hours) + +.. option:: -s, --split= + + Download a file using N connections. If more than N URIs are given, + first N URIs are used and remaining URIs are used for backup. If + less than N URIs are given, those URIs are used more than once so + that N connections total are made simultaneously. The number of + connections to the same host is restricted by + :option:`--max-connection-per-server <-x>` option. + See also :option:`--min-split-size <-k>` option. + Default: ``5`` + + .. note:: + + Some Metalinks regulate the number of servers to connect. aria2 + strictly respects them. This means that if Metalink defines the + maxconnections attribute lower than N, then aria2 uses the + value of maxconnections attribute instead of N. + +.. option:: --stream-piece-selector= + + Specify piece selection algorithm used in HTTP/FTP download. Piece + means fixed length segment which is downloaded in parallel in + segmented download. If ``default`` is given, aria2 selects piece so + that it reduces the number of establishing connection. This is + reasonable default behaviour because establishing connection is an + expensive operation. If ``inorder`` is given, aria2 selects piece + which has minimum index. Index=0 means first of the file. This will + be useful to view movie while downloading it. + :option:`--enable-http-pipelining` option may + be useful to reduce reconnection overhead. Please note that aria2 + honors + :option:`--min-split-size <-k>` option, + so it will be necessary to specify a reasonable value to + :option:`--min-split-size <-k>` option. + If ``geom`` is given, at the beginning aria2 selects piece which has + minimum index like ``inorder`` , but it exponentially increasingly + keeps space from previously selected piece. This will reduce the + number of establishing connection and at the same time it will + download the beginning part of the file first. This will be useful + to view movie while downloading it. + Default: ``default`` + +.. option:: -t, --timeout= + + Set timeout in seconds. + Default: ``60`` + +.. option:: --uri-selector= + + Specify URI selection algorithm. The possible values are ``inorder`` , + ``feedback`` and ``adaptive``. If ``inorder`` is given, URI is tried in + the order appeared in the URI list. If ``feedback`` is given, aria2 + uses download speed observed in the previous downloads and choose + fastest server in the URI list. This also effectively skips dead + mirrors. The observed download speed is a part of performance + profile of servers mentioned in :option:`--server-stat-of` and + :option:`--server-stat-if` options. If ``adaptive`` is given, selects one of + the best mirrors for the first and reserved connections. For + supplementary ones, it returns mirrors which has not been tested + yet, and if each of them has already been tested, returns mirrors + which has to be tested again. Otherwise, it doesn't select anymore + mirrors. Like ``feedback`` , it uses a performance profile of servers. + Default: ``feedback`` + +HTTP Specific Options +~~~~~~~~~~~~~~~~~~~~~ +.. option:: --ca-certificate= + + Use the certificate authorities in FILE to verify the peers. + The certificate file must be in PEM format and can contain multiple CA + certificates. + Use :option:`--check-certificate` option to enable verification. + +.. option:: --certificate= + + Use the client certificate in FILE. + The certificate must be in PEM format. + You may use :option:`--private-key` option to specify the private key. + +.. option:: --check-certificate[=true|false] + + Verify the peer using certificates specified in :option:`--ca-certificate` option. + Default: ``true`` + +.. option:: --http-accept-gzip[=true|false] + + Send ``Accept: deflate, gzip`` request header and inflate response if + remote server responds with ``Content-Encoding: gzip`` or + ``Content-Encoding: deflate``. Default: ``false`` + + .. note:: + + Some server responds with ``Content-Encoding: gzip`` for files which + itself is gzipped file. aria2 inflates them anyway because of the + response header. + +.. option:: --http-auth-challenge[=true|false] + + Send HTTP authorization header only when it is requested by the + server. If ``false`` is set, then authorization header is always sent + to the server. There is an exception: if username and password are + embedded in URI, authorization header is always sent to the server + regardless of this option. Default: ``false`` + +.. option:: --http-no-cache[=true|false] + + Send Cache-Control: no-cache and Pragma: no-cache header to avoid + cached content. If ``false`` is given, these headers are not sent + and you can add Cache-Control header with a directive you like + using :option:`--header` option. Default: ``true`` + +.. option:: --http-user= + + Set HTTP user. This affects all URIs. + +.. option:: --http-passwd= + + Set HTTP password. This affects all URIs. + +.. option:: --http-proxy= + + Use this proxy server for HTTP. To erase previously defined proxy, + use "". See also :option:`--all-proxy` option. This affects all URIs. The + format of PROXY is ``[http://][USER:PASSWORD@]HOST[:PORT]`` + +.. option:: --http-proxy-passwd= + + Set password for :option:`--http-proxy` option. + +.. option:: --http-proxy-user= + + Set user for :option:`--http-proxy` option. + +.. option:: --https-proxy= + + Use this proxy server for HTTPS. To erase previously defined proxy, + use "". See also :option:`--all-proxy` option. This affects all URIs. The + format of PROXY is ``[http://][USER:PASSWORD@]HOST[:PORT]`` + +.. option:: --https-proxy-passwd= + + Set password for :option:`--https-proxy` option. + +.. option:: --https-proxy-user= + + Set user for :option:`--https-proxy` option. + +.. option:: --private-key= + + Use the private key in FILE. + The private key must be decrypted and in PEM format. + The behavior when encrypted one is given is undefined. + See also :option:`--certificate` option. + +.. option:: --referer= + + Set Referer. This affects all URIs. + +.. option:: --enable-http-keep-alive[=true|false] + + Enable HTTP/1.1 persistent connection. + Default: ``true`` + +.. option:: --enable-http-pipelining[=true|false] + + Enable HTTP/1.1 pipelining. + Default: ``false`` + + .. note:: + + In performance perspective, there is usually no advantage to enable + this option. + +.. option:: --header=
+ + Append HEADER to HTTP request header. + You can use this option repeatedly to specify more than one header: + + .. code-block:: console + + $ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file" + +.. option:: --load-cookies= + + Load Cookies from FILE using the Firefox3 format (SQLite3), + Chromium/Google Chrome (SQLite3) and the + Mozilla/Firefox(1.x/2.x)/Netscape format. + + .. note:: + + If aria2 is built without libsqlite3, then it doesn't support Firefox3 + and Chromium/Google Chrome cookie format. + +.. option:: --save-cookies= + + Save Cookies to FILE in Mozilla/Firefox(1.x/2.x)/ Netscape + format. If FILE already exists, it is overwritten. Session Cookies + are also saved and their expiry values are treated as 0. Possible + Values: ``/path/to/file`` + +.. option:: --use-head[=true|false] + + Use HEAD method for the first request to the HTTP server. + Default: ``false`` + + +.. option:: -U, --user-agent= + + Set user agent for HTTP(S) downloads. + Default: ``aria2/$VERSION`` , $VERSION is replaced by package version. + +FTP Specific Options +~~~~~~~~~~~~~~~~~~~~ +.. option:: --ftp-user= + + Set FTP user. This affects all URIs. + Default: ``anonymous`` + +.. option:: --ftp-passwd= + + Set FTP password. This affects all URIs. + If user name is embedded but password is missing in URI, aria2 tries + to resolve password using .netrc. If password is found in .netrc, + then use it as password. If not, use the password specified in this + option. + Default: ``ARIA2USER@`` + +.. option:: -p, --ftp-pasv[=true|false] + + Use the passive mode in FTP. + If ``false`` is given, the active mode will be used. + Default: ``true`` + +.. option:: --ftp-proxy= + + Use this proxy server for FTP. To erase previously defined proxy, + use "". See also :option:`--all-proxy` option. This affects all URIs. The + format of PROXY is ``[http://][USER:PASSWORD@]HOST[:PORT]`` + +.. option:: --ftp-proxy-passwd= + + Set password for :option:`--ftp-proxy` option. + +.. option:: --ftp-proxy-user= + + Set user for :option:`--ftp-proxy` option. + +.. option:: --ftp-type= + + Set FTP transfer type. TYPE is either ``binary`` or ``ascii``. + Default: ``binary`` + +.. option:: --ftp-reuse-connection[=true|false] + + Reuse connection in FTP. + Default: ``true`` + +BitTorrent/Metalink Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --select-file=... + + Set file to download by specifying its index. + You can find the file index using the :option:`--show-files <-S>` option. + Multiple indexes can be specified by using ``,``, for example: ``3,6``. + You can also use ``-`` to specify a range: ``1-5``. + ``,`` and ``-`` can be used together: ``1-5,8,9``. + When used with the -M option, index may vary depending on the query + (see *--metalink-\** options). + + .. note:: + + In multi file torrent, the adjacent files specified by this option may + also be downloaded. This is by design, not a bug. + A single piece may include several files or part of files, and aria2 + writes the piece to the appropriate files. + +.. option:: -S, --show-files[=true|false] + + Print file listing of .torrent, .meta4 and .metalink file and exit. + In case of .torrent file, additional information + (infohash, piece length, etc) is also printed. + +BitTorrent Specific Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: --bt-enable-lpd[=true|false] + + Enable Local Peer Discovery. If a private flag is set in a torrent, + aria2 doesn't use this feature for that download even if ``true`` is + given. Default: ``false`` + +.. option:: --bt-exclude-tracker=[,...] + + Comma separated list of BitTorrent tracker's announce URI to + remove. You can use special value ``*`` which matches all URIs, thus + removes all announce URIs. When specifying ``*`` in shell + command-line, don't forget to escape or quote it. See also + :option:`--bt-tracker` option. + +.. option:: --bt-external-ip= + + Specify the external IP address to report to a BitTorrent + tracker. Although this function is named ``external``, it can accept + any kind of IP addresses. IPADDRESS must be a numeric IP address. + +.. option:: --bt-hash-check-seed[=true|false] + + If ``true`` is given, after hash check using :option:`--check-integrity <-V>` option and + file is complete, continue to seed file. If you want to check file + and download it only when it is damaged or incomplete, set this + option to ``false``. This option has effect only on BitTorrent download. + Default: ``true`` + +.. option:: --bt-lpd-interface= + + Use given interface for Local Peer Discovery. If this option is not + specified, the default interface is chosen. You can specify + interface name and IP address. Possible Values: interface, IP + addres + +.. option:: --bt-max-open-files= + + Specify maximum number of files to open in each BitTorrent download. + Default: ``100`` + +.. option:: --bt-max-peers= + + Specify the maximum number of peers per torrent. ``0`` means + unlimited. See also :option:`--bt-request-peer-speed-limit` option. + Default: ``55`` + +.. option:: --bt-metadata-only[=true|false] + + Download metadata only. The file(s) described in metadata will not + be downloaded. This option has effect only when BitTorrent Magnet + URI is used. See also :option:`--bt-save-metadata` option. Default: ``false`` + +.. option:: --bt-min-crypto-level=plain|arc4 + + Set minimum level of encryption method. + If several encryption methods are provided by a peer, aria2 chooses the lowest + one which satisfies the given level. + Default: ``plain`` + +.. option:: --bt-prioritize-piece=head[=],tail[=] + + Try to download first and last pieces of each file first. This is + useful for previewing files. The argument can contain 2 keywords: + ``head`` and ``tail``. To include both keywords, they must be separated + by comma. These keywords can take one parameter, SIZE. For example, + if ``head=`` is specified, pieces in the range of first SIZE bytes + of each file get higher priority. ``tail=`` means the range of + last SIZE bytes of each file. SIZE can include ``K`` or ``M`` (1K = 1024, + 1M = 1024K). If SIZE is omitted, SIZE=1M is used. + +.. option:: --bt-remove-unselected-file[=true|false] + + Removes the unselected files when download is completed in + BitTorrent. To selecting files, use + :option:`--select-file` option. If it is + not used, all files are assumed to be selected. Please use this + option with care because it will actually remove files from your + disk. + Default: ``false`` + +.. option:: --bt-require-crypto[=true|false] + + If true is given, aria2 doesn't accept and establish connection with legacy + BitTorrent handshake(\19BitTorrent protocol). + Thus aria2 always uses Obfuscation handshake. + Default: ``false`` + +.. option:: --bt-request-peer-speed-limit= + + If the whole download speed of every torrent is lower than SPEED, + aria2 temporarily increases the number of peers to try for more + download speed. Configuring this option with your preferred download + speed can increase your download speed in some cases. + You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + Default: ``50K`` + +.. option:: --bt-save-metadata[=true|false] + + Save metadata as .torrent file. This option has effect only when + BitTorrent Magnet URI is used. The filename is hex encoded info + hash with suffix .torrent. The directory to be saved is the same + directory where download file is saved. If the same file already + exists, metadata is not saved. See also :option:`--bt-metadata-only` + option. Default: ``false`` + +.. option:: --bt-seed-unverified[=true|false] + + Seed previously downloaded files without verifying piece hashes. + Default: ``false`` + +.. option:: --bt-stop-timeout= + + Stop BitTorrent download if download speed is 0 in consecutive SEC + seconds. If ``0`` is given, this feature is disabled. Default: ``0`` + +.. option:: --bt-tracker=[,...] + + Comma separated list of additional BitTorrent tracker's announce + URI. These URIs are not affected by :option:`--bt-exclude-tracker` option + because they are added after URIs in :option:`--bt-exclude-tracker` option are + removed. + +.. option:: --bt-tracker-connect-timeout= + + Set the connect timeout in seconds to establish connection to + tracker. After the connection is established, this option makes no + effect and :option:`--bt-tracker-timeout` option is used instead. Default: + ``60`` + +.. option:: --bt-tracker-interval= + + Set the interval in seconds between tracker requests. This + completely overrides interval value and aria2 just uses this value + and ignores the min interval and interval value in the response of + tracker. If ``0`` is set, aria2 determines interval based on the + response of tracker and the download progress. Default: ``0`` + +.. option:: --bt-tracker-timeout= + + Set timeout in seconds. Default: ``60`` + +.. option:: --dht-entry-point=: + + Set host and port as an entry point to IPv4 DHT network. + +.. option:: --dht-entry-point6=: + + Set host and port as an entry point to IPv6 DHT network. + +.. option:: --dht-file-path= + + Change the IPv4 DHT routing table file to PATH. + Default: ``$HOME/.aria2/dht.dat`` + +.. option:: --dht-file-path6= + + Change the IPv6 DHT routing table file to PATH. + Default: ``$HOME/.aria2/dht6.dat`` + +.. option:: --dht-listen-addr6= + + Specify address to bind socket for IPv6 DHT. It should be a global + unicast IPv6 address of the host. + +.. option:: --dht-listen-port=... + + Set UDP listening port for both IPv4 and IPv6 DHT. + Multiple ports can be specified by using ``,``, for example: ``6881,6885``. + You can also use ``-`` to specify a range: ``6881-6999``. ``,`` and ``-`` can be used + together. + Default: ``6881-6999`` + + .. note:: + + Make sure that the specified ports are open for incoming UDP traffic. + +.. option:: --dht-message-timeout= + + Set timeout in seconds. Default: ``10`` + +.. option:: --enable-dht[=true|false] + + Enable IPv4 DHT functionality. If a private flag is set in a + torrent, aria2 doesn't use DHT for that download even if ``true`` is + given. Default: ``true`` + +.. option:: --enable-dht6[=true|false] + + Enable IPv6 DHT functionality. If a private flag is set in a + torrent, aria2 doesn't use DHT for that download even if ``true`` is + given. Use :option:`--dht-listen-port` option to specify port number to + listen on. See also :option:`--dht-listen-addr6` option. + +.. option:: --enable-peer-exchange[=true|false] + + Enable Peer Exchange extension. If a private flag is set in a torrent, this + feature is disabled for that download even if ``true`` is given. + Default: ``true`` + +.. option:: --follow-torrent=true|false|mem + + If ``true`` or ``mem`` is specified, when a file whose suffix is ``.torrent`` or content + type is ``application/x-bittorrent`` is downloaded, aria2 parses it as a torrent + file and downloads files mentioned in it. + If ``mem`` is specified, a torrent file is not written to the disk, but is just + kept in memory. + If ``false`` is specified, the action mentioned above is not taken. + Default: ``true`` + +.. option:: -O, --index-out== + + Set file path for file with index=INDEX. You can find the file index + using the :option:`--show-files <-S>` option. PATH is a relative path to the + path specified in :option:`--dir <-d>` option. You can use this option multiple + times. Using this option, you can specify the output filenames of + BitTorrent downloads. + +.. option:: --listen-port=... + + Set TCP port number for BitTorrent downloads. + Multiple ports can be specified by using ``,``, for example: ``6881,6885``. + You can also use ``-`` to specify a range: ``6881-6999``. + ``,`` and ``-`` can be used together: ``6881-6889,6999``. + Default: ``6881-6999`` + + .. note:: + + Make sure that the specified ports are open for incoming TCP traffic. + +.. option:: --max-overall-upload-limit= + + Set max overall upload speed in bytes/sec. + ``0`` means unrestricted. + You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + To limit the upload speed per torrent, use :option:`--max-upload-limit <-u>` option. + Default: ``0`` + +.. option:: -u, --max-upload-limit= + + Set max upload speed per each torrent in bytes/sec. + ``0`` means unrestricted. + You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + To limit the overall upload speed, use :option:`--max-overall-upload-limit` option. + Default: ``0`` + +.. option:: --peer-id-prefix= + + Specify the prefix of peer ID. The peer ID in + BitTorrent is 20 byte length. If more than 20 + bytes are specified, only first 20 bytes are + used. If less than 20 bytes are specified, random + byte data are added to make its length 20 bytes. + Default: ``aria2/$VERSION-`` , $VERSION is replaced by package version. + +.. option:: --seed-ratio= + + Specify share ratio. Seed completed torrents until share ratio reaches + RATIO. + You are strongly encouraged to specify equals or more than ``1.0`` here. + Specify ``0.0`` if you intend to do seeding regardless of share ratio. + If :option:`--seed-time` option is specified along with this option, seeding ends when + at least one of the conditions is satisfied. + Default: ``1.0`` + +.. option:: --seed-time= + + Specify seeding time in minutes. Also see the :option:`--seed-ratio` option. + + .. note:: + + Specifying :option:`--seed-time=0 <--seed-time>` disables seeding after download completed. + +.. option:: -T, --torrent-file= + + The path to the .torrent file. You are not required to use this + option because you can specify .torrent files without :option:`--torrent-file <-T>`. + +Metalink Specific Options +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --follow-metalink=true|false|mem + + If ``true`` or ``mem`` is specified, when a file whose suffix is ``.meta4`` or ``.metalink`` or content + type of ``application/metalink4+xml`` or ``application/metalink+xml`` is downloaded, aria2 parses it as a metalink + file and downloads files mentioned in it. + If ``mem`` is specified, a metalink file is not written to the disk, but is just + kept in memory. + If ``false`` is specified, the action mentioned above is not taken. + Default: ``true`` + +.. option:: --metalink-base-uri= + + Specify base URI to resolve relative URI in metalink:url and + metalink:metaurl element in a metalink file stored in local disk. If + URI points to a directory, URI must end with ``/``. + +.. option:: -M, --metalink-file= + + The file path to .meta4 and .metalink file. Reads input from stdin when ``-`` is + specified. You are not required to use this option because you can + specify .metalink files without :option:`--metalink-file <-M>`. + +.. option:: --metalink-language= + + The language of the file to download. + +.. option:: --metalink-location=[,...] + + The location of the preferred server. + A comma-delimited list of locations is acceptable, for example, ``jp,us``. + +.. option:: --metalink-os= + + The operating system of the file to download. + +.. option:: --metalink-version= + + The version of the file to download. + +.. option:: --metalink-preferred-protocol= + + Specify preferred protocol. + The possible values are ``http`` , ``https`` , ``ftp`` and ``none``. + Specify ``none`` to disable this feature. + Default: ``none`` + +.. option:: --metalink-enable-unique-protocol[=true|false] + + If ``true`` is given and several protocols are available for a mirror in a + metalink file, aria2 uses one of them. + Use :option:`--metalink-preferred-protocol` option to specify the preference of + protocol. + Default: ``true`` + +RPC Options +~~~~~~~~~~~ + +.. option:: --enable-rpc[=true|false] + + Enable JSON-RPC/XML-RPC server. It is strongly recommended to set username + and password using :option:`--rpc-user` and :option:`--rpc-passwd` + option. See also :option:`--rpc-listen-port` option. Default: ``false`` + +.. option:: --pause[=true|false] + + Pause download after added. This option is effective only when + :option:`--enable-rpc=true <--enable-rpc>` is given. + Default: ``false`` + + +.. option:: --rpc-allow-origin-all[=true|false] + + Add Access-Control-Allow-Origin header field with value ``*`` to the + RPC response. + Default: ``false`` + +.. option:: --rpc-listen-all[=true|false] + + Listen incoming JSON-RPC/XML-RPC requests on all network interfaces. If false + is given, listen only on local loopback interface. Default: ``false`` + +.. option:: --rpc-listen-port= + + Specify a port number for JSON-RPC/XML-RPC server to listen to. Possible + Values: ``1024`` -``65535`` Default: ``6800`` + +.. option:: --rpc-max-request-size= + + Set max size of JSON-RPC/XML-RPC request. If aria2 detects the request is + more than SIZE bytes, it drops connection. Default: ``2M`` + +.. option:: --rpc-passwd= + + Set JSON-RPC/XML-RPC password. + +.. option:: --rpc-user= + + Set JSON-RPC/XML-RPC user. + +Advanced Options +~~~~~~~~~~~~~~~~ +.. option:: --allow-overwrite[=true|false] + + Restart download from scratch if the corresponding control file + doesn't exist. See also :option:`--auto-file-renaming` option. Default: + ``false`` + +.. option:: --allow-piece-length-change[=true|false] + + If false is given, aria2 aborts download when a piece length is different + from one in a control file. + If true is given, you can proceed but some download progress will be lost. + Default: ``false`` + +.. option:: --always-resume[=true|false] + + Always resume download. If ``true`` is given, aria2 always tries to + resume download and if resume is not possible, aborts download. If + ``false`` is given, when all given URIs do not support resume or aria2 + encounters ``N`` URIs which does not support resume (``N`` is the value + specified using :option:`--max-resume-failure-tries` option), aria2 + downloads file from scratch. See :option:`--max-resume-failure-tries` + option. Default: ``true`` + +.. option:: --async-dns[=true|false] + + Enable asynchronous DNS. + Default: ``true`` + +.. option:: --async-dns-server=[,...] + + Comma separated list of DNS server address used in asynchronous DNS + resolver. Usually asynchronous DNS resolver reads DNS server + addresses from ``/etc/resolv.conf``. When this option is used, it uses + DNS servers specified in this option instead of ones in + ``/etc/resolv.conf``. You can specify both IPv4 and IPv6 address. This + option is useful when the system does not have ``/etc/resolv.conf`` and + user does not have the permission to create it. + +.. option:: --auto-file-renaming[=true|false] + + Rename file name if the same file already exists. + This option works only in HTTP(S)/FTP download. + The new file name has a dot and a number(1..9999) appended. + Default: ``true`` + +.. option:: --auto-save-interval= + + Save a control file(\*.aria2) every SEC seconds. + If ``0`` is given, a control file is not saved during download. aria2 saves a + control file when it stops regardless of the value. + The possible values are between ``0`` to ``600``. + Default: ``60`` + +.. option:: --conditional-get[=true|false] + + Download file only when the local file is older than remote + file. This function only works with HTTP(S) downloads only. It does + not work if file size is specified in Metalink. It also ignores + Content-Disposition header. If a control file exists, this option + will be ignored. This function uses If-Modified-Since header to get + only newer file conditionally. When getting modification time of + local file, it uses user supplied filename(see :option:`--out <-o>` option) or + filename part in URI if :option:`--out <-o>` is not specified. + To overwrite existing file, :option:`--allow-overwrite` is required. + Default: ``false`` + +.. option:: --conf-path= + + Change the configuration file path to PATH. + Default: ``$HOME/.aria2/aria2.conf`` + +.. option:: -D, --daemon[=true|false] + + Run as daemon. The current working directory will be changed to ``/`` + and standard input, standard output and standard error will be + redirected to ``/dev/null``. Default: ``false`` + +.. option:: --deferred-input[=true|false] + + If ``true`` is given, aria2 does not read all URIs and options from file + specified by :option:`--input-file <-i>` option at startup, + but it reads one by one when it + needs later. This may reduce memory usage if input file contains a + lot of URIs to download. If ``false`` is given, aria2 reads all URIs + and options at startup. + Default: ``false`` + +.. option:: --disable-ipv6[=true|false] + + Disable IPv6. This is useful if you have to use broken DNS and want + to avoid terribly slow AAAA record lookup. Default: ``false`` + +.. option:: --download-result= + + This option changes the way ``Download Results`` is formatted. If OPT + is ``default`` , print GID, status, average download speed and + path/URI. If multiple files are involved, path/URI of first + requested file is printed and remaining ones are omitted. If OPT is + ``full`` , print GID, status, average download speed, percentage of + progress and path/URI. The percentage of progress and path/URI are + printed for each requested file in each row. + Default: ``default`` + +.. option:: --enable-async-dns6[=true|false] + + Enable IPv6 name resolution in asynchronous DNS resolver. This + option will be ignored when :option:`--async-dns=false. <--async-dns>` + Default: ``false`` + +.. option:: --event-poll= + + Specify the method for polling events. The possible values are + ``epoll`` , ``kqueue`` , ``port`` , ``poll`` and ``select``. For each ``epoll`` , + ``kqueue`` , ``port`` and ``poll`` , it is available if system supports it. + ``epoll`` is available on recent Linux. ``kqueue`` is available on + various \*BSD systems including Mac OS X. ``port`` is available on Open + Solaris. The default value may vary depending on the system you use. + +.. option:: --file-allocation= + + Specify file allocation method. + ``none`` doesn't pre-allocate file space. ``prealloc`` pre-allocates file space + before download begins. This may take some time depending on the size of the + file. + If you are using newer file systems such as ext4 + (with extents support), btrfs, xfs or NTFS(MinGW build only), ``falloc`` is + your best choice. It allocates large(few GiB) + files almost instantly. Don't use ``falloc`` with + legacy file systems such as ext3 and FAT32 because it takes + almost same time as ``prealloc`` and it blocks aria2 + entirely until allocation finishes. ``falloc`` may + not be available if your system doesn't have + :manpage:`posix_fallocate(3)` function. + Possible Values: ``none`` , ``prealloc`` , ``falloc`` + Default: ``prealloc`` + +.. option:: --hash-check-only[=true|false] + + If ``true`` is given, after hash check using + :option:`--check-integrity <-V>` option, + abort download whether or not download is complete. + Default: ``false`` + +.. option:: --human-readable[=true|false] + + Print sizes and speed in human readable format (e.g., 1.2Ki, 3.4Mi) + in the console readout. Default: ``true`` + +.. option:: --interface= + + Bind sockets to given interface. You can specify interface name, IP + address and hostname. + Possible Values: interface, IP address, hostname + + .. note:: + + If an interface has multiple addresses, it is highly recommended to + specify IP address explicitly. See also :option:`--disable-ipv6`. If your + system doesn't have :manpage:`getifaddrs(3)`, this option doesn't accept interface + name. + +.. option:: --max-download-result= + + Set maximum number of download result kept in memory. The download + results are completed/error/removed downloads. The download results + are stored in FIFO queue and it can store at most NUM download + results. When queue is full and new download result is created, + oldest download result is removed from the front of the queue and + new one is pushed to the back. Setting big number in this option may + result high memory consumption after thousands of + downloads. Specifying 0 means no download result is kept. Default: + ``1000`` + +.. option:: --max-resume-failure-tries= + + When used with :option:`--always-resume=false, <--always-resume>` aria2 downloads file from + scratch when aria2 detects ``N`` number of URIs that does not support + resume. If ``N`` is ``0`` , aria2 downloads file from scratch when all + given URIs do not support resume. See :option:`--always-resume` option. + Default: ``0`` + +.. option:: --log-level= + + Set log level to output. + LEVEL is either ``debug`` , ``info`` , ``notice`` , ``warn`` or ``error``. + Default: ``debug`` + +.. option:: --on-bt-download-complete= + + For BitTorrent, a command specified in :option:`--on-download-complete` is + called after download completed and seeding is over. On the other + hand, this option set the command to be executed after download + completed but before seeding. + See `Event Hook`_ for more details about COMMAND. + Possible Values: ``/path/to/command`` + +.. option:: --on-download-complete= + + Set the command to be executed after download completed. See + See `Event Hook`_ for more details about COMMAND. + See also :option:`--on-download-stop` option. + Possible Values: ``/path/to/command`` + +.. option:: --on-download-error= + + Set the command to be executed after download aborted due to error. + See `Event Hook`_ for more details about COMMAND. + See also :option:`--on-download-stop` option. Possible Values: + ``/path/to/command`` + +.. option:: --on-download-pause= + + Set the command to be executed after download was paused. + See `Event Hook`_ for more details about COMMAND. + Possible Values: ``/path/to/command`` + +.. option:: --on-download-start= + + Set the command to be executed after download got started. + See `Event Hook`_ for more details about COMMAND. + Possible Values: ``/path/to/command`` + +.. option:: --on-download-stop= + + Set the command to be executed after download stopped. You can override + the command to be executed for particular download result using + :option:`--on-download-complete` and :option:`--on-download-error`. If they are + specified, command specified in this option is not executed. + See `Event Hook`_ for more details about COMMAND. + Possible Values: ``/path/to/command`` + +.. option:: --piece-length= + + Set a piece length for HTTP/FTP downloads. This is the boundary when + aria2 splits a file. All splits occur at multiple of this + length. This option will be ignored in BitTorrent downloads. It + will be also ignored if Metalink file contains piece hashes. + Default: ``1M`` + + .. note:: + + The possible usecase of :option:`--piece-length` + option is change the request range in one HTTP pipelined request. + To enable HTTP pipelining use + :option:`--enable-http-pipelining`. + +.. option:: --show-console-readout[=true|false] + + Show console readout. Default: ``true`` + +.. option:: --summary-interval= + + Set interval in seconds to output download progress summary. + Setting ``0`` suppresses the output. + Default: ``60`` + + .. note:: + + In multi file torrent downloads, the files adjacent forward to the specified files + are also allocated if they share the same piece. + +.. option:: -Z, --force-sequential[=true|false] + + Fetch URIs in the command-line sequentially and download each URI in a + separate session, like the usual command-line download utilities. + Default: ``false`` + +.. option:: --max-overall-download-limit= + + Set max overall download speed in bytes/sec. ``0`` means + unrestricted. You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). To + limit the download speed per download, use :option:`--max-download-limit` + option. Default: ``0`` + +.. option:: --max-download-limit= + + Set max download speed per each download in bytes/sec. ``0`` means + unrestricted. You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). To + limit the overall download speed, use :option:`--max-overall-download-limit` + option. Default: ``0`` + +.. option:: --no-conf[=true|false] + + Disable loading aria2.conf file. + +.. option:: --no-file-allocation-limit= + + No file allocation is made for files whose size is smaller than SIZE. + You can append ``K`` or ``M`` (1K = 1024, 1M = 1024K). + Default: ``5M`` + +.. option:: -P, --parameterized-uri[=true|false] + + Enable parameterized URI support. + You can specify set of parts: ``http://{sv1,sv2,sv3}/foo.iso``. + Also you can specify numeric sequences with step counter: + ``http://host/image[000-100:2].img``. + A step counter can be omitted. + If all URIs do not point to the same file, such as the second example above, + -Z option is required. + Default: ``false`` + +.. option:: -q, --quiet[=true|false] + + Make aria2 quiet (no console output). + Default: ``false`` + +.. option:: --realtime-chunk-checksum[=true|false] + + Validate chunk of data by calculating checksum while downloading a file if + chunk checksums are provided. + Default: ``true`` + + +.. option:: --remove-control-file[=true|false] + + Remove control file before download. Using with + :option:`--allow-overwrite=true, <--allow-overwrite>` download always starts from + scratch. This will be useful for users behind proxy server which + disables resume. + +.. option:: --save-session= + + Save error/unfinished downloads to FILE on exit. You can pass this + output file to aria2c with :option:`--input-file <-i>` option on restart. Please note that + downloads added by :func:`aria2.addTorrent` and + :func:`aria2.addMetalink` + RPC method and whose metadata could not be saved as a file are not saved. + Downloads removed using + :func:`aria2.remove` and + :func:`aria2.forceRemove` + will not be saved. + +.. option:: --stop= + + Stop application after SEC seconds has passed. + If ``0`` is given, this feature is disabled. + Default: ``0`` + +.. option:: --stop-with-process= + + Stop application when process PID is not running. This is useful if + aria2 process is forked from a parent process. The parent process + can fork aria2 with its own pid and when parent process exits for + some reason, aria2 can detect it and shutdown itself. + +.. option:: --truncate-console-readout[=true|false] + + Truncate console readout to fit in a single line. + Default: ``true`` + +.. option:: -v, --version + + Print the version number, copyright and the configuration information and + exit. + +Options That Take An Optional Argument +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The options that have its argument surrounded by square brackets([]) +take an optional argument. Usually omiting the argument is evaluated to ``true``. +If you use short form of these options(such as ``-V``) and give +an argument, then the option name and its argument should be concatenated(e.g. +``-Vfalse``). If any spaces are inserted between the option name and the argument, +the argument will be treated as URI and usually this is not what you expect. + +URI, MAGNET, TORRENT_FILE, METALINK_FILE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify multiple URIs in command-line. Unless you specify +:option:`--force-sequential <-Z>` option, all URIs must point to the same file or downloading will +fail. + +You can specify arbitrary number of BitTorrent Magnet URI. Please note +that they are always treated as a separate download. Both hex encoded +40 characters Info Hash and Base32 encoded 32 characters Info Hash are +supported. The multiple ``tr`` parameters are supported. Because +BitTorrent Magnet URI is likely to contain ``&`` character, it is highly +recommended to always quote URI with single(``'``) or double(``"``) quotation. +It is strongly recommended to enable DHT especially when ``tr`` +parameter is missing. See http://www.bittorrent.org/beps/bep_0009.html +for more details about BitTorrent Magnet URI. + +You can also specify arbitrary number of torrent files and Metalink +documents stored on a local drive. Please note that they are always +treated as a separate download. Both Metalink4 and Metalink version +3.0 are supported. + +You can specify both torrent file with -T option and URIs. By doing +this, you can download a file from both torrent swarm and HTTP(S)/FTP +server at the same time, while the data from HTTP(S)/FTP are uploaded +to the torrent swarm. For single file torrents, URI can be a complete +URI pointing to the resource or if URI ends with /, name in torrent +file in torrent is added. For multi-file torrents, name and path are +added to form a URI for each file. + +.. note:: + + Make sure that URI is quoted with single(``'``) or double(``"``) quotation if it + contains ``&`` or any characters that have special meaning in shell. + +Resuming Download +~~~~~~~~~~~~~~~~~ + +Usually, you can resume transfer by just issuing same command(aria2c +URI) if the previous transfer is made by aria2. + +If the previous transfer is made by a browser or wget like sequential +download manager, then use :option:`--continue <-c>` option to continue the transfer. + +Event Hook +~~~~~~~~~~ + +aria2 provides options to specify arbitrary command after specific event +occurred. Currently following options are available: +:option:`--on-bt-download-complete`, +:option:`--on-download-pause`, +:option:`--on-download-complete`. +:option:`--on-download-start`, +:option:`--on-download-error`, +:option:`--on-download-stop`. + +aria2 passes 3 arguments to specified command when it is executed. +These arguments are: GID, the number of files and file path. For +HTTP, FTP downloads, usually the number of files is 1. BitTorrent +download can contain multiple files. +If number of files is more than one, file path is first one. In +other words, this is the value of path key of first struct whose +selected key is true in the response of +:func:`aria2.getFiles` +RPC method. +If you want to get all file paths, consider to use JSON-RPC/XML-RPC. Please +note that file path may change during download in HTTP because of +redirection or Content-Disposition header. + +Let's see an example of how arguments are passed to command: + +.. code-block:: console + + $ cat hook.sh + #!/bin/sh + echo "Called with [$1] [$2] [$3]" + $ aria2c --on-download-complete hook.sh http://example.org/file.iso + Called with [1] [1] [/path/to/file.iso] + + +EXIT STATUS +----------- + +Because aria2 can handle multiple downloads at once, it encounters +lots of errors in a session. aria2 returns the following exit status +based on the last error encountered. + +0 + If all downloads were successful. + +1 + If an unknown error occurred. + +2 + If time out occurred. + +3 + If a resource was not found. + +4 + If aria2 saw the specfied number of "resource not found" error. + See :option:`--max-file-not-found` option). + +5 + If a download aborted because download speed was too slow. + See :option:`--lowest-speed-limit` option) + +6 + If network problem occurred. + +7 + If there were unfinished downloads. This error is only reported if + all finished downloads were successful and there were unfinished + downloads in a queue when aria2 exited by pressing :kbd:`Ctrl-C` by an user + or sending TERM or INT signal. + +8 + If remote server did not support resume when resume was required to + complete download. + +9 + If there was not enough disk space available. + +10 + If piece length was different from one in .aria2 control file. See + :option:`--allow-piece-length-change` option. + +11 + If aria2 was downloading same file at that moment. + +12 + If aria2 was downloading same info hash torrent at that moment. + +13 + If file already existed. See :option:`--allow-overwrite` option. + +14 + If renaming file failed. See :option:`--auto-file-renaming` option. + +15 + If aria2 could not open existing file. + +16 + If aria2 could not create new file or truncate existing file. + +17 + If file I/O error occurred. + +18 + If aria2 could not create directory. + +19 + If name resolution failed. + +20 + If aria2 could not parse Metalink document. + +21 + If FTP command failed. + +22 + If HTTP response header was bad or unexpected. + +23 + If too many redirections occurred. + +24 + If HTTP authorization failed. + +25 + If aria2 could not parse bencoded file(usually .torrent file). + +26 + If .torrent file was corrupted or missing information that aria2 needed. + +27 + If Magnet URI was bad. + +28 + If bad/unrecognized option was given or unexpected option argument + was given. + +29 + If the remote server was unable to handle the request due to a + temporary overloading or maintenance. + +30 + If aria2 could not parse JSON-RPC request. + +.. note:: + + An error occurred in a finished download will not be reported + as exit status. + +ENVIRONMENT +----------- +aria2 recognizes the following environment variables. + +``http_proxy [http://][USER:PASSWORD@]HOST[:PORT]`` + Specify proxy server for use in HTTP. + Overrides http-proxy value in configuration file. + The command-line option :option:`--http-proxy` overrides this value. + +``https_proxy [http://][USER:PASSWORD@]HOST[:PORT]`` + Specify proxy server for use in HTTPS. + Overrides https-proxy value in configuration file. + The command-line option :option:`--https-proxy` overrides this value. + +``ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT]`` + Specify proxy server for use in FTP. + Overrides ftp-proxy value in configuration file. + The command-line option :option:`--ftp-proxy` overrides this value. + +``all_proxy [http://][USER:PASSWORD@]HOST[:PORT]`` + Specify proxy server for use if no protocol-specific proxy is specified. + Overrides all-proxy value in configuration file. + The command-line option :option:`--all-proxy` overrides this value. + +.. note:: + + Although aria2 accepts ``ftp://`` and ``https://`` scheme in proxy URI, it + simply assumes that ``http://`` is specified and does not change its + behavior based on the specified scheme. + +``no_proxy [DOMAIN,...]`` + Specify comma-separated hostname, domains and network address with + or without CIDR block to which proxy should not be used. Overrides + no-proxy value in configuration file. The command-line option + :option:`--no-proxy` overrides this value. + +FILES +----- +aria2.conf +~~~~~~~~~~ + +By default, aria2 parses ``$HOME/.aria2/aria2.conf`` as a configuraiton +file. You can specify the path to configuration file using +:option:`--conf-path` option. If you don't want to use the configuraitonf +file, use :option:`--no-conf` option. + +The configuration file is a text file and has 1 option per each +line. In each line, you can specify name-value pair in the format: +``NAME=VALUE``, where name is the long command-line option name without +``--`` prefix. You can use same syntax for the command-line option. The +lines beginning ``#`` are treated as comments:: + + # sample configuration file for aria2c + listen-port=60000 + dht-listen-port=60000 + seed-ratio=1.0 + max-upload-limit=50K + ftp-pasv=true + + +dht.dat +~~~~~~~~ + +By default, the routing table of IPv4 DHT is saved to the path +``$HOME/.aria2/dht.dat`` and the routing table of IPv6 DHT is saved to +the path ``$HOME/.aria2/dht6.dat``. + +Netrc +~~~~~ + +Netrc support is enabled by default for HTTP(S)/FTP. To disable netrc +support, specify :option:`--no-netrc <-n>` option. Your .netrc file should have correct +permissions(600). + +If machine name starts ``.``, aria2 performs domain-match instead of +exact match. This is an extension of aria2. For example of domain +match, imagine the following .netrc entry:: + + machine .example.org login myid password mypasswd + + +``aria2.example.org`` domain-matches ``.example.org`` and uses ``myid`` and +``mypasswd``. + +Some domain-match example follow: ``example.net`` does not domain-match +``.example.org``. ``example.org`` does not domain-match ``.example.org`` +because of preceding ``.``. If you want to match ``example.org``, specify +``example.org``. + +Control File +~~~~~~~~~~~~ + +aria2 uses a control file to track the progress of a download. A +control file is placed in the same directory as the downloading file +and its filename is the filename of downloading file with ``.aria2`` +appended. For example, if you are downloading file.zip, then the +control file should be file.zip.aria2. (There is a exception for this +naming convention. If you are downloading a multi torrent, its +control file is the "top directory" name of the torrent with ``.aria2`` +appended. The "top directory" name is a value of "name" key in "info" +directory in a torrent file.) + +Usually a control file is deleted once download completed. If aria2 +decides that download cannot be resumed(for example, when downloading +a file from a HTTP server which doesn't support resume), a control +file is not created. + +Normally if you lose a control file, you cannot resume download. But +if you have a torrent or metalink with chunk checksums for the file, +you can resume the download without a control file by giving -V option +to aria2c in command-line. + +Input File +~~~~~~~~~~ + +The input file can contain a list of URIs for aria2 to download. You +can specify multiple URIs for a single entity: separate URIs on a +single line using the TAB character. + +Each line is treated as if it is provided in command-line argument. +Therefore they are affected by :option:`--force-sequential <-Z>` and :option:`--parameterized-uri <-P>` options. + +Since URIs in the input file are directly read by aria2, they must not +be quoted with single(``'``) or double(``"``) quotation. + +Lines starting with ``#`` are treated as comments and skipped. + +Additionally, the following options can be specified after each line +of URIs. These optional lines must start with white space(s). + +.. hlist:: + :columns: 3 + + * :option:`all-proxy <--all-proxy>` + * :option:`all-proxy-passwd <--all-proxy-passwd>` + * :option:`all-proxy-user <--all-proxy-user>` + * :option:`allow-overwrite <--allow-overwrite>` + * :option:`allow-piece-length-change <--allow-piece-length-change>` + * :option:`always-resume <--always-resume>` + * :option:`async-dns <--async-dns>` + * :option:`auto-file-renaming <--auto-file-renaming>` + * :option:`bt-enable-lpd <--bt-enable-lpd>` + * :option:`bt-exclude-tracker <--bt-exclude-tracker>` + * :option:`bt-external-ip <--bt-external-ip>` + * :option:`bt-hash-check-seed <--bt-hash-check-seed>` + * :option:`bt-max-open-files <--bt-max-open-files>` + * :option:`bt-max-peers <--bt-max-peers>` + * :option:`bt-metadata-only <--bt-metadata-only>` + * :option:`bt-min-crypto-level <--bt-min-crypto-level>` + * :option:`bt-prioritize-piece <--bt-prioritize-piece>` + * :option:`bt-request-peer-speed-limit <--bt-request-peer-speed-limit>` + * :option:`bt-require-crypto <--bt-require-crypto>` + * :option:`bt-save-metadata <--bt-save-metadata>` + * :option:`bt-seed-unverified <--bt-seed-unverified>` + * :option:`bt-stop-timeout <--bt-stop-timeout>` + * :option:`bt-tracker <--bt-tracker>` + * :option:`bt-tracker-connect-timeout <--bt-tracker-connect-timeout>` + * :option:`bt-tracker-interval <--bt-tracker-interval>` + * :option:`bt-tracker-timeout <--bt-tracker-timeout>` + * :option:`bt-remove-unselected-file <--bt-remove-unselected-file>` + * :option:`check-integrity <-V>` + * :option:`conditional-get <--conditional-get>` + * :option:`connect-timeout <--connect-timeout>` + * :option:`continue <-c>` + * :option:`dir <-d>` + * :option:`dry-run <--dry-run>` + * :option:`enable-async-dns6 <--enable-async-dns6>` + * :option:`enable-http-keep-alive <--enable-http-keep-alive>` + * :option:`enable-http-pipelining <--enable-http-pipelining>` + * :option:`enable-peer-exchange <--enable-peer-exchange>` + * :option:`file-allocation <--file-allocation>` + * :option:`follow-metalink <--follow-metalink>` + * :option:`follow-torrent <--follow-torrent>` + * :option:`ftp-passwd <--ftp-passwd>` + * :option:`ftp-pasv <-p>` + * :option:`ftp-proxy <--ftp-proxy>` + * :option:`ftp-proxy-passwd <--ftp-proxy-passwd>` + * :option:`ftp-proxy-user <--ftp-proxy-user>` + * :option:`ftp-reuse-connection <--ftp-reuse-connection>` + * :option:`ftp-type <--ftp-type>` + * :option:`ftp-user <--ftp-user>` + * :option:`header <--header>` + * :option:`http-accept-gzip <--http-accept-gzip>` + * :option:`http-auth-challenge <--http-auth-challenge>` + * :option:`http-no-cache <--http-no-cache>` + * :option:`http-passwd <--http-passwd>` + * :option:`http-proxy <--http-proxy>` + * :option:`http-proxy-passwd <--http-proxy-passwd>` + * :option:`http-proxy-user <--http-proxy-user>` + * :option:`http-user <--http-user>` + * :option:`https-proxy <--https-proxy>` + * :option:`https-proxy-passwd <--https-proxy-passwd>` + * :option:`https-proxy-user <--https-proxy-user>` + * :option:`index-out <-O>` + * :option:`lowest-speed-limit <--lowest-speed-limit>` + * :option:`max-connection-per-server <-x>` + * :option:`max-download-limit <--max-download-limit>` + * :option:`max-file-not-found <--max-file-not-found>` + * :option:`max-resume-failure-tries <--max-resume-failure-tries>` + * :option:`max-tries <-m>` + * :option:`max-upload-limit <-u>` + * :option:`metalink-enable-unique-protocol <--metalink-enable-unique-protocol>` + * :option:`metalink-language <--metalink-language>` + * :option:`metalink-location <--metalink-location>` + * :option:`metalink-os <--metalink-os>` + * :option:`metalink-preferred-protocol <--metalink-preferred-protocol>` + * :option:`metalink-version <--metalink-version>` + * :option:`min-split-size <-k>` + * :option:`no-file-allocation-limit <--no-file-allocation-limit>` + * :option:`no-netrc <-n>` + * :option:`no-proxy <--no-proxy>` + * :option:`out <-o>` + * :option:`parameterized-uri <-P>` + * :option:`proxy-method <--proxy-method>` + * :option:`realtime-chunk-checksum <--realtime-chunk-checksum>` + * :option:`referer <--referer>` + * :option:`remote-time <-R>` + * :option:`remove-control-file <--remove-control-file>` + * :option:`reuse-uri <--reuse-uri>` + * :option:`seed-ratio <--seed-ratio>` + * :option:`seed-time <--seed-time>` + * :option:`select-file <--select-file>` + * :option:`split <-s>` + * :option:`timeout <-t>` + * :option:`use-head <--use-head>` + * :option:`user-agent <-U>` + * :option:`retry-wait <--retry-wait>` + * :option:`metalink-base-uri <--metalink-base-uri>` + * :option:`pause <--pause>` + * :option:`stream-piece-selector <--stream-piece-selector>` + * :option:`hash-check-only <--hash-check-only>` + * :option:`checksum <--checksum>` + * :option:`piece-length <--piece-length>` + * :option:`uri-selector <--uri-selector>` + +These options have exactly same meaning of the ones in the +command-line options, but it just applies to the URIs it belongs to. +Please note that for options in input file ``--`` prefix must be +stripped. + +For example, the content of uri.txt is:: + + http://server/file.iso http://mirror/file.iso + dir=/iso_images + out=file.img + http://foo/bar + + +If aria2 is executed with ``-i uri.txt -d /tmp`` options, then +``file.iso`` is saved as ``/iso_images/file.img`` and it is downloaded +from \http://server/file.iso and \http://mirror/file.iso. The file +``bar`` is downloaded from \http://foo/bar and saved as ``/tmp/bar``. + +In some cases, :option:`out <-o>` parameter has no effect. +See note of :option:`--out <-o>` +option for the restrictions. + +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: + +``host`` + Hostname of the server. Required. + +``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. + +``sc_avg_speed`` + The average download speed observed in the previous download in + bytes per sec. This value is only updated if the download is done in + single connection environment and only used by + AdaptiveURISelector. Optional. + +``mc_avg_speed`` + The average download speed observed in the previous download in + bytes per sec. This value is only updated if the download is done in + multi connection environment and only used by + AdaptiveURISelector. Optional. + +``counter`` + How many times the server is used. Currently this value is only used + by AdaptiveURISelector. Optional. + +``last_updated`` + Last contact time in GMT with this server, specified in the seconds + since the Epoch(00:00:00 on January 1, 1970, UTC). Required. + +``status`` + 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 the above; they are simply +ignored. + +An example follows:: + + host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK + host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR + + +RPC INTERFACE +------------- + +aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP and they +basically have the same functionality. aria2 also provides JSON-RPC +over WebSocket. JSON-RPC over WebSocket uses same method signatures +and response format with JSON-RPC over HTTP, but it additionally has +server-initiated notifications. See `JSON-RPC over WebSocket`_ section for details. + +The request path of JSON-RPC interface (for both over HTTP and over +WebSocket) is ``/jsonrpc``. The request path of XML-RPC interface is +``/rpc``. + +The WebSocket URI for JSON-RPC over WebSocket is +``ws://HOST:PORT/jsonrpc``. + +The implemented JSON-RPC is based on +JSON-RPC 2.0 , and +supports HTTP POST and GET (JSONP). Using WebSocket as a transport is +the original extension of aria2. + +The JSON-RPC interface does not support notification in HTTP, but the +RPC server will send the notification in WebSocket. It also does not +support floating point number. The character encoding must be UTF-8. + +When reading following document for JSON-RPC, interpret struct as JSON +object. + +Terminology +~~~~~~~~~~~ + +GID + GID(or gid) is the key to manage each download. Each download has an + unique GID. Currently GID looks like an integer, but don't treat it + as integer because it may be changed to another type in the future + release. Please note that GID is session local and not persisted + when aria2 exits. + +Methods +~~~~~~~ + +All code examples come from Python2.7 interpreter. + + +.. function:: aria2.addUri(uris[, options[, position]]) + + + + + + This method adds new HTTP(S)/FTP/BitTorrent Magnet URI. *uris* is of + type array and its element is URI which is of type string. For + BitTorrent Magnet URI, *uris* must have only one element and it should + be BitTorrent Magnet URI. URIs in *uris* must point to the same file. + If you mix other URIs which point to another file, aria2 does not + complain but download may fail. *options* is of type struct and its + members are a pair of option name and value. See :ref:`rpc_options` below for + more details. If *position* is given as an integer starting from 0, + the new download is inserted at *position* in the waiting queue. If + *position* is not given or *position* is larger than the size of the + queue, it is appended at the end of the queue. This method returns + GID of registered download. + + **JSON-RPC Example** + + + The following example adds \http://example.org/file to aria2:: + + >>> import urllib2, json + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addUri', + ... 'params':[['http://example.org/file']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":"1"}' + + + **XML-RPC Example** + + + The following example adds \http://example.org/file to aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addUri(['http://example.org/file']) + '1' + + + The following example adds 2 sources and some options:: + + >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'], + dict(dir="/tmp")) + '2' + + + The following example adds a download and insert it to the front of + waiting downloads:: + + >>> s.aria2.addUri(['http://example.org/file'], {}, 0) + '3' + + + +.. function:: aria2.addTorrent(torrent[, uris[, options[, position]]]) + + + + + + This method adds BitTorrent download by uploading .torrent file. If + you want to add BitTorrent Magnet URI, use :func:`aria2.addUri` method + instead. *torrent* is of type base64 which contains Base64-encoded + .torrent file. *uris* is of type array and its element is URI which + is of type string. *uris* is used for Web-seeding. For single file + torrents, URI can be a complete URI pointing to the resource or if URI + ends with /, name in torrent file is added. For multi-file torrents, + name and path in torrent are added to form a URI for each file. + *options* is of type struct and its members are a pair of option name + and value. See :ref:`rpc_options` below for more details. If *position* is + given as an integer starting from 0, the new download is inserted at + *position* in the waiting queue. If *position* is not given or + *position* is larger than the size of the queue, it is appended at the + end of the queue. This method returns GID of registered download. + The uploaded data is saved as a file named hex string of SHA-1 hash of data + plus ".torrent" in the directory specified by :option:`--dir <-d>` + option. + The example of filename is 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. + If same file already exists, it is overwritten. + If the file cannot be saved successfully, + the downloads added by this method are not saved by + :option:`--save-session`. + + **JSON-RPC Example** + + + The following example adds local file file.torrent to aria2:: + + >>> import urllib2, json, base64 + >>> torrent = base64.b64encode(open('file.torrent').read()) + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf', + ... 'method':'aria2.addTorrent', 'params':[torrent]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"asdf","jsonrpc":"2.0","result":"6"}' + + + **XML-RPC Example** + + + The following example adds local file file.torrent to aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read())) + '6' + + + +.. function:: aria2.addMetalink(metalink[, options[, position]]) + + + + + + This method adds Metalink download by uploading .metalink file. + *metalink* is of type base64 which contains Base64-encoded .metalink + file. *options* is of type struct and its members are a pair of + option name and value. See :ref:`rpc_options` below for more details. If + *position* is given as an integer starting from 0, the new download is + inserted at *position* in the waiting queue. If *position* is not + given or *position* is larger than the size of the queue, it is + appended at the end of the queue. This method returns array of GID of + registered download. + The uploaded data is saved as a file named hex string of SHA-1 hash of data + plus ".metalink" in the directory specified by :option:`--dir <-d>` + option. + The example of filename is 0a3893293e27ac0490424c06de4d09242215f0a6.metalink. + If same file already exists, it is overwritten. + If the file cannot be saved successfully, + the downloads added by this method are not saved by + :option:`--save-session`. + + **JSON-RPC Example** + + + The following example adds local file file.meta4 to aria2:: + + >>> import urllib2, json, base64 + >>> metalink = base64.b64encode(open('file.meta4').read()) + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addMetalink', 'params':[metalink]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":["8"]}' + + + **XML-RPC Example** + + + The following example adds local file file.meta4 to aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4').read())) + ['8'] + + + +.. function:: aria2.remove(gid) + + + + + + This method removes the download denoted by *gid*. *gid* is of type + string. If specified download is in progress, it is stopped at + first. The status of removed download becomes ``"removed"``. This method + returns GID of removed download. + + **JSON-RPC Example** + + + The following example removes download whose GID is "3":: + + >>> import urllib2, json + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.remove', 'params':['3']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":"3"}' + + + **XML-RPC Example** + + + The following example removes download whose GID is "3":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.remove('3') + '3' + + + +.. function:: aria2.forceRemove(gid) + + + + + + This method removes the download denoted by *gid*. This method + behaves just like :func:`aria2.remove` except that this method removes + download without any action which takes time such as contacting + BitTorrent tracker. + + +.. function:: aria2.pause(gid) + + + + + + This method pauses the download denoted by *gid*. *gid* is of type + string. The status of paused download becomes ``"paused"``. If the + download is active, the download is placed on the first position of + waiting queue. As long as the status is ``"paused"``, the download is not + started. To change status to ``"waiting"``, use :func:`aria2.unpause` method. + This method returns GID of paused download. + + +.. function:: aria2.pauseAll() + + + + + + This method is equal to calling :func:`aria2.pause` for every active/waiting + download. This methods returns ``"OK"`` for success. + + +.. function:: aria2.forcePause(pid) + + + + + + This method pauses the download denoted by *gid*. This method + behaves just like :func:`aria2.pause` except that this method pauses + download without any action which takes time such as contacting + BitTorrent tracker. + + +.. function:: aria2.forcePauseAll() + + + + + + This method is equal to calling :func:`aria2.forcePause` for every + active/waiting download. This methods returns ``"OK"`` for success. + + +.. function:: aria2.unpause(gid) + + + + + + This method changes the status of the download denoted by *gid* from + ``"paused"`` to ``"waiting"``. This makes the download eligible to restart. + *gid* is of type string. This method returns GID of unpaused + download. + + +.. function:: aria2.unpauseAll() + + + + + + This method is equal to calling :func:`aria2.unpause` for every active/waiting + download. This methods returns ``"OK"`` for success. + + +.. function:: aria2.tellStatus(gid[, keys]) + + + + + + This method returns download progress of the download denoted by + *gid*. *gid* is of type string. *keys* is array of string. If it is + specified, the response contains only keys in *keys* array. If *keys* + is empty or not specified, the response contains all keys. This is + useful when you just want specific keys and avoid unnecessary + transfers. For example, ``aria2.tellStatus("1", ["gid", "status"])`` + returns *gid* and 'status' key. The response is of type struct and it + contains following keys. The value type is string. + + ``gid`` + GID of this download. + + ``status`` + ``"active"`` for currently downloading/seeding entry. ``"waiting"`` for the + entry in the queue; download is not started. ``"paused"`` for the + paused entry. ``"error"`` for the stopped download because of + error. ``"complete"`` for the stopped and completed download. ``"removed"`` + for the download removed by user. + + ``totalLength`` + Total length of this download in bytes. + + ``completedLength`` + Completed length of this download in bytes. + + ``uploadLength`` + Uploaded length of this download in bytes. + + ``bitfield`` + Hexadecimal representation of the download progress. The highest bit + corresponds to piece index 0. The set bits indicate the piece is + available and unset bits indicate the piece is missing. The spare + bits at the end are set to zero. When download has not started yet, + this key will not be included in the response. + + ``downloadSpeed`` + Download speed of this download measured in bytes/sec. + + ``uploadSpeed`` + Upload speed of this download measured in bytes/sec. + + ``infoHash`` + InfoHash. BitTorrent only. + + ``numSeeders`` + The number of seeders the client has connected to. BitTorrent only. + + ``pieceLength`` + Piece length in bytes. + + ``numPieces`` + The number of pieces. + + ``connections`` + The number of peers/servers the client has connected to. + + ``errorCode`` + The last error code occurred in this download. The value is of type + string. The error codes are defined in `EXIT STATUS`_ section. This value is only available for + stopped/completed downloads. + + ``followedBy`` + List of GIDs which are generated by the consequence of this + download. For example, when aria2 downloaded Metalink file, it + generates downloads described in it(see :option:`--follow-metalink` + option). This value is useful to track these auto generated + downloads. If there is no such downloads, this key will not + be included in the response. + + ``belongsTo`` + GID of a parent download. Some downloads are a part of another + download. For example, if a file in Metalink has BitTorrent + resource, the download of .torrent is a part of that file. If this + download has no parent, this key will not be included in the + response. + + ``dir`` + Directory to save files. This key is not available for stopped + downloads. + + ``files`` + Returns the list of files. The element of list is the same struct + used in :func:`aria2.getFiles` method. + + + ``bittorrent`` + Struct which contains information retrieved from .torrent + file. BitTorrent only. It contains following keys. + + ``announceList`` + List of lists of announce URI. If .torrent file contains announce + and no announce-list, announce is converted to announce-list + format. + + ``comment`` + The comment for the torrent. comment.utf-8 is used if available. + + ``creationDate`` + The creation time of the torrent. The value is an integer since + the Epoch, measured in seconds. + + ``mode`` + File mode of the torrent. The value is either 'single' or 'multi'. + + ``info`` + Struct which contains data from Info dictionary. It contains + following keys. + + ``name`` + name in info dictionary. name.utf-8 is used if available. + + **JSON-RPC Example** + + + The following example gets information about download whose GID is + "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.tellStatus', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'bitfield': u'0000000000', + u'completedLength': u'901120', + u'connections': u'1', + u'dir': u'/downloads', + u'downloadSpeed': u'15158', + u'files': [{u'index': u'1', + u'length': u'34896138', + u'completedLength': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}], + u'gid': u'1', + u'numPieces': u'34', + u'pieceLength': u'1048576', + u'status': u'active', + u'totalLength': u'34896138', + u'uploadLength': u'0', + u'uploadSpeed': u'0'}} + + + The following example gets information specifying keys you are + interested in:: + + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.tellStatus', + ... 'params':['1', ['gid', + ... 'totalLength', + ... 'completedLength']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'completedLength': u'5701632', + u'gid': u'1', + u'totalLength': u'34896138'}} + + + **XML-RPC Example** + + + The following example gets information about download whose GID is + "1":: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.tellStatus('1') + >>> pprint(r) + {'bitfield': 'ffff80', + 'completedLength': '34896138', + 'connections': '0', + 'dir': '/downloads', + 'downloadSpeed': '0', + 'errorCode': '0', + 'files': [{'index': '1', + 'length': '34896138', + 'completedLength': '34896138', + 'path': '/downloads/file', + 'selected': 'true', + 'uris': [{'status': 'used', + 'uri': 'http://example.org/file'}]}], + 'gid': '1', + 'numPieces': '17', + 'pieceLength': '2097152', + 'status': 'complete', + 'totalLength': '34896138', + 'uploadLength': '0', + 'uploadSpeed': '0'} + + + The following example gets information specifying keys you are + interested in:: + + >>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength']) + >>> pprint(r) + {'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'} + + + +.. function:: aria2.getUris(gid) + + + + + + This method returns URIs used in the download denoted by *gid*. *gid* + is of type string. The response is of type array and its element is of + type struct and it contains following keys. The value type is string. + + ``uri`` + URI + + ``status`` + 'used' if the URI is already used. 'waiting' if the URI is waiting + in the queue. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getUris', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'status': u'used', + u'uri': u'http://example.org/file'}]} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getUris('1') + >>> pprint(r) + [{'status': 'used', 'uri': 'http://example.org/file'}] + + + +.. function:: aria2.getFiles(gid) + + + + + + This method returns file list of the download denoted by *gid*. *gid* + is of type string. The response is of type array and its element is of + type struct and it contains following keys. The value type is string. + + ``index`` + Index of file. Starting with 1. This is the same order with the + files in multi-file torrent. + + ``path`` + File path. + + ``length`` + File size in bytes. + + ``completedLength`` + Completed length of this file in bytes. Please note that it is + possible that sum of completedLength is less than completedLength in + :func:`aria2.tellStatus` method. + This is because completedLength in + :func:`aria2.getFiles` + only calculates completed pieces. On the other hand, completedLength + in + :func:`aria2.tellStatus` takes into account + of partially completed piece. + + ``selected`` + ``"true"`` if this file is selected by :option:`--select-file` option. If + :option:`--select-file` is not specified or this is single torrent or no + torrent download, this value is always ``"true"``. Otherwise ``"false"``. + + ``uris`` + Returns the list of URI for this file. The element of list is the + same struct used in :func:`aria2.getUris` method. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getFiles', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'index': u'1', + u'length': u'34896138', + u'completedLength': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}]} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getFiles('1') + >>> pprint(r) + [{'index': '1', + 'length': '34896138', + 'completedLength': '34896138', + 'path': '/downloads/file', + 'selected': 'true', + 'uris': [{'status': 'used', + 'uri': 'http://example.org/file'}]}] + + + +.. function:: aria2.getPeers(gid) + + + + + + This method returns peer list of the download denoted by *gid*. *gid* + is of type string. This method is for BitTorrent only. The response + is of type array and its element is of type struct and it contains + following keys. The value type is string. + + ``peerId`` + Percent-encoded peer ID. + + ``ip`` + IP address of the peer. + + ``port`` + Port number of the peer. + + ``bitfield`` + Hexadecimal representation of the download progress of the peer. The + highest bit corresponds to piece index 0. The set bits indicate the + piece is available and unset bits indicate the piece is missing. The + spare bits at the end are set to zero. + + ``amChoking`` + ``"true"`` if this client is choking the peer. Otherwise ``"false"``. + + ``peerChoking`` + ``"true"`` if the peer is choking this client. Otherwise ``"false"``. + + ``downloadSpeed`` + Download speed (byte/sec) that this client obtains from the peer. + + ``uploadSpeed`` + Upload speed(byte/sec) that this client uploads to the peer. + + ``seeder`` + ``"true"`` is this client is a seeder. Otherwise ``"false"``. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getPeers', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'amChoking': u'true', + u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff', + u'downloadSpeed': u'10602', + u'ip': u'10.0.0.9', + u'peerChoking': u'false', + u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + u'port': u'6881', + u'seeder': u'true', + u'uploadSpeed': u'0'}, + {u'amChoking': u'false', + u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + u'downloadSpeed': u'8654', + u'ip': u'10.0.0.30', + u'peerChoking': u'false', + u'peerId': u'bittorrent client758', + u'port': u'37842', + u'seeder': u'false', + u'uploadSpeed': u'6890'}]} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getPeers('1') + >>> pprint(r) + [{'amChoking': 'true', + 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff', + 'downloadSpeed': '10602', + 'ip': '10.0.0.9', + 'peerChoking': 'false', + 'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + 'port': '6881', + 'seeder': 'true', + 'uploadSpeed': '0'}, + {'amChoking': 'false', + 'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + 'downloadSpeed': '8654', + 'ip': '10.0.0.30', + 'peerChoking': 'false', + 'peerId': 'bittorrent client758', + 'port': '37842', + 'seeder': 'false, + 'uploadSpeed': '6890'}] + + + +.. function:: aria2.getServers(gid) + + + + + + This method returns currently connected HTTP(S)/FTP servers of the download denoted by *gid*. *gid* is of type string. The response + is of type array and its element is of type struct and it contains + following keys. The value type is string. + + ``index`` + Index of file. Starting with 1. This is the same order with the + files in multi-file torrent. + + ``servers`` + The list of struct which contains following keys. + + ``uri`` + URI originally added. + + ``currentUri`` + This is the URI currently used for downloading. If redirection is + involved, currentUri and uri may differ. + + ``downloadSpeed`` + Download speed (byte/sec) + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getServers', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'index': u'1', + u'servers': [{u'currentUri': u'http://example.org/file', + u'downloadSpeed': u'10467', + u'uri': u'http://example.org/file'}]}]} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getServers('1') + >>> pprint(r) + [{'index': '1', + 'servers': [{'currentUri': 'http://example.org/dl/file', + 'downloadSpeed': '20285', + 'uri': 'http://example.org/file'}]}] + + + +.. function:: aria2.tellActive([keys]) + + + + + + This method returns the list of active downloads. The response is of + type array and its element is the same struct returned by + :func:`aria2.tellStatus` method. For *keys* parameter, please refer to + :func:`aria2.tellStatus` method. + + +.. function:: aria2.tellWaiting(offset, num, [keys]) + + + + + + This method returns the list of waiting download, including paused + downloads. *offset* is of type integer and specifies the offset from + the download waiting at the front. *num* is of type integer and + specifies the number of downloads to be returned. For *keys* + parameter, please refer to :func:`aria2.tellStatus` method. + + If *offset* is a positive integer, this method returns downloads in the + range of [*offset*, *offset* + *num*). + + *offset* can be a negative integer. *offset* == -1 points last + download in the waiting queue and *offset* == -2 points the download + before the last download, and so on. The downloads in the response are + in reversed order. + + For example, imagine that three downloads "A","B" and "C" are waiting + in this order. aria2.tellWaiting(0, 1) returns + ["A"]. aria2.tellWaiting(1, 2) returns ["B", "C"]. + aria2.tellWaiting(-1, 2) returns ["C", "B"]. + + The response is of type array and its element is the same struct + returned by :func:`aria2.tellStatus` method. + + +.. function:: aria2.tellStopped(offset, num, [keys]) + + + + + + This method returns the list of stopped download. *offset* is of type + integer and specifies the offset from the oldest download. *num* is of + type integer and specifies the number of downloads to be returned. + For *keys* parameter, please refer to :func:`aria2.tellStatus` method. + + *offset* and *num* have the same semantics as :func:`aria2.tellWaiting` + method. + + The response is of type array and its element is the same struct + returned by :func:`aria2.tellStatus` method. + + +.. function:: aria2.changePosition(gid, pos, how) + + + + + + This method changes the position of the download denoted by + *gid*. *pos* is of type integer. *how* is of type string. If *how* is + ``"POS_SET"``, it moves the download to a position relative to the + beginning of the queue. If *how* is ``"POS_CUR"``, it moves the download + to a position relative to the current position. If *how* is ``"POS_END"``, + it moves the download to a position relative to the end of the + queue. If the destination position is less than 0 or beyond the end of + the queue, it moves the download to the beginning or the end of the + queue respectively. The response is of type integer and it is the + destination position. + + For example, if GID#1 is placed in position 3, ``aria2.changePosition('1', + -1, 'POS_CUR')`` will change its position to 2. Additional + ``aria2.changePosition('1', 0, 'POS_SET')`` will change its position to 0(the + beginning of the queue). + + **JSON-RPC Example** + + + The following example moves the download whose GID is "3" to the + front of the waiting queue:: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changePosition', + ... 'params':['3', 0, 'POS_SET']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0} + + + **XML-RPC Example** + + + The following example moves the download whose GID is "3" to the + front of the waiting queue:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changePosition('3', 0, 'POS_SET') + 0 + + + +.. function:: aria2.changeUri(gid, fileIndex, delUris, addUris[, position]) + + + + + + This method removes URIs in *delUris* from and appends URIs in + *addUris* to download denoted by *gid*. *delUris* and *addUris* are + list of string. A download can contain multiple files and URIs are + attached to each file. *fileIndex* is used to select which file to + remove/attach given URIs. *fileIndex* is 1-based. *position* is used + to specify where URIs are inserted in the existing waiting URI + list. *position* is 0-based. When *position* is omitted, URIs are + appended to the back of the list. This method first execute removal + and then addition. *position* is the position after URIs are removed, + not the position when this method is called. When removing URI, if + same URIs exist in download, only one of them is removed for each URI + in *delUris*. In other words, there are three URIs + ``http://example.org/aria2`` and you want remove them all, you have to + specify (at least) 3 ``http://example.org/aria2`` in *delUris*. This + method returns a list which contains 2 integers. The first integer is + the number of URIs deleted. The second integer is the number of URIs + added. + + **JSON-RPC Example** + + + The following example adds 1 URI \http://example.org/file to the file + whose index is "1" and belongs to the download whose GID is "2":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changeUri', + ... 'params':['2', 1, [], ['http://example.org/file']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]} + + + **XML-RPC Example** + + + The following example adds 1 URI \http://example.org/file to the file + whose index is "1" and belongs to the download whose GID is "2":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changeUri('2', 1, [], ['http://example.org/file']) + [0, 1] + + + +.. function:: aria2.getOption(gid) + + + + + + This method returns options of the download denoted by *gid*. The + response is of type struct. Its key is the name of option. The value + type is string. Note that this method does not return options which + have no default value and have not been set by the command-line + options, configuration files or RPC methods. + + **JSON-RPC Example** + + + The following example gets options of the download whose GID is "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getOption', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'allow-overwrite': u'false', + u'allow-piece-length-change': u'false', + u'always-resume': u'true', + u'async-dns': u'true', + ... + + + **XML-RPC Example** + + + The following example gets options of the download whose GID is "1":: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getOption('1') + >>> pprint(r) + {'allow-overwrite': 'false', + 'allow-piece-length-change': 'false', + 'always-resume': 'true', + 'async-dns': 'true', + .... + + + +.. function:: aria2.changeOption(gid, options) + + + + + + This method changes options of the download denoted by *gid* + dynamically. *gid* is of type string. *options* is of type struct. + The following options are available for active downloads: + + * :option:`bt-max-peers <--bt-max-peers>` + * :option:`bt-request-peer-speed-limit <--bt-request-peer-speed-limit>` + * :option:`bt-remove-unselected-file <--bt-remove-unselected-file>` + * :option:`max-download-limit <--max-download-limit>` + * :option:`max-upload-limit <-u>` + + For waiting or paused downloads, in addition to the above options, + options listed in `Input File`_ subsection are available, + except for following options: + :option:`dry-run <--dry-run>`, + :option:`metalink-base-uri <--metalink-base-uri>`, + :option:`parameterized-uri <-P>`, + :option:`pause <--pause>` and + :option:`piece-length <--piece-length>`. + This method returns ``"OK"`` for success. + + **JSON-RPC Example** + + + The following example sets + :option:`max-download-limit <--max-download-limit>` option to ``"20K"`` for + the download whose GID is "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changeOption', + ... 'params':['1', {'max-download-limit':'10K'}]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} + + + **XML-RPC Example** + + + The following example sets + :option:`max-download-limit <--max-download-limit>` option to ``"20K"`` for + the download whose GID is "1":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changeOption('1', {'max-download-limit':'20K'}) + 'OK' + + + +.. function:: aria2.getGlobalOption() + + + + + + This method returns global options. The response is of type + struct. Its key is the name of option. The value type is string. + Note that this method does not return options which have no default + value and have not been set by the command-line options, configuration + files or RPC methods. Because global options are used as a template + for the options of newly added download, the response contains keys + returned by :func:`aria2.getOption` method. + + +.. function:: aria2.changeGlobalOption(options) + + + + + + This method changes global options dynamically. *options* is of type + struct. + The following options are available: + + * :option:`download-result <--download-result>` + * :option:`log <-l>` + * :option:`log-level <--log-level>` + * :option:`max-concurrent-downloads <-j>` + * :option:`max-download-result <--max-download-result>` + * :option:`max-overall-download-limit <--max-overall-download-limit>` + * :option:`max-overall-upload-limit <--max-overall-upload-limit>` + * :option:`save-cookies <--save-cookies>` + * :option:`save-session <--save-session>` + * :option:`server-stat-of <--server-stat-of>` + + In addition to them, options listed in `Input File`_ subsection + are available, except for following options: + :option:`checksum <--checksum>`, + :option:`index-out <-O>`, + :option:`out <-o>`, + :option:`pause <--pause>` and + :option:`select-file <--select-file>`. + + Using :option:`log <-l>` option, you can dynamically start logging or + change log file. To stop logging, give empty string("") as a parameter + value. Note that log file is always opened in append mode. This method + returns ``"OK"`` for success. + + +.. function:: aria2.getGlobalStat() + + + + + + This method returns global statistics such as overall download and + upload speed. The response is of type struct and contains following + keys. The value type is string. + + ``downloadSpeed`` + Overall download speed (byte/sec). + + ``uploadSpeed`` + Overall upload speed(byte/sec). + + ``numActive`` + The number of active downloads. + + ``numWaiting`` + The number of waiting downloads. + + ``numStopped`` + The number of stopped downloads. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getGlobalStat'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'downloadSpeed': u'21846', + u'numActive': u'2', + u'numStopped': u'0', + u'numWaiting': u'0', + u'uploadSpeed': u'0'}} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getGlobalStat() + >>> pprint(r) + {'downloadSpeed': '23136', + 'numActive': '2', + 'numStopped': '0', + 'numWaiting': '0', + 'uploadSpeed': '0'} + + + +.. function:: aria2.purgeDownloadResult() + + + + + + This method purges completed/error/removed downloads to free memory. + This method returns ``"OK"``. + + +.. function:: aria2.removeDownloadResult(gid) + + + + + + This method removes completed/error/removed download denoted by *gid* + from memory. This method returns ``"OK"`` for success. + + **JSON-RPC Example** + + + The following example removes the download result of the download + whose GID is "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.removeDownloadResult', + ... 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} + + + **XML-RPC Example** + + + The following example removes the download result of the download + whose GID is "1":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.removeDownloadResult('1') + 'OK' + + + +.. function:: aria2.getVersion() + + + + + + This method returns version of the program and the list of enabled + features. The response is of type struct and contains following keys. + + ``version`` + Version number of the program in string. + + ``enabledFeatures`` + List of enabled features. Each feature name is of type string. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getVersion'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'enabledFeatures': [u'Async DNS', + u'BitTorrent', + u'Firefox3 Cookie', + u'GZip', + u'HTTPS', + u'Message Digest', + u'Metalink', + u'XML-RPC'], + u'version': u'1.11.0'}} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getVersion() + >>> pprint(r) + {'enabledFeatures': ['Async DNS', + 'BitTorrent', + 'Firefox3 Cookie', + 'GZip', + 'HTTPS', + 'Message Digest', + 'Metalink', + 'XML-RPC'], + 'version': '1.11.0'} + + + +.. function:: aria2.getSessionInfo() + + + + + + This method returns session information. + The response is of type struct and contains following key. + + ``sessionId`` + Session ID, which is generated each time when aria2 is invoked. + + **JSON-RPC Example** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getSessionInfo'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}} + + + **XML-RPC Example** + :: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.getSessionInfo() + {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'} + + + +.. function:: aria2.shutdown() + + + + + + This method shutdowns aria2. This method returns ``"OK"``. + + +.. function:: aria2.forceShutdown() + + + + + + This method shutdowns :func:`aria2. This method behaves like aria2.shutdown` + except that any actions which takes time such as contacting BitTorrent + tracker are skipped. This method returns ``"OK"``. + + +.. function:: system.multicall(methods) + + + + + + This methods encapsulates multiple method calls in a single request. + *methods* is of type array and its element is struct. The struct + contains two keys: ``methodName`` and ``params``. ``methodName`` is the + method name to call and ``params`` is array containing parameters to the + method. This method returns array of responses. The element of array + will either be a one-item array containing the return value of each + method call or struct of fault element if an encapsulated method call + fails. + + **JSON-RPC Example** + + + In the following example, we add 2 downloads. First one is + \http://example.org/file and second one is file.torrent:: + + >>> import urllib2, json, base64 + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'system.multicall', + ... 'params':[[{'methodName':'aria2.addUri', + ... 'params':[['http://example.org']]}, + ... {'methodName':'aria2.addTorrent', + ... 'params':[base64.b64encode(open('file.torrent').read())]}]]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'1'], [u'2']]} + + + JSON-RPC also supports Batch request described in JSON-RPC 2.0 Specification:: + + >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addUri', + ... 'params':[['http://example.org']]}, + ... {'jsonrpc':'2.0', 'id':'asdf', + ... 'method':'aria2.addTorrent', + ... 'params':[base64.b64encode(open('file.torrent').read())]}]) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'1'}, + {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'2'}] + + + **XML-RPC Example** + + + In the following example, we add 2 downloads. First one is + \http://example.org/file and second one is file.torrent:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> mc = xmlrpclib.MultiCall(s) + >>> mc.aria2.addUri(['http://example.org/file']) + >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read())) + >>> r = mc() + >>> tuple(r) + ('2', '3') + + +Error Handling +~~~~~~~~~~~~~~ + +In JSON-RPC, aria2 returns JSON object which contains error code in +code and the error message in message. + +In XML-RPC, aria2 returns faultCode=1 and the error message in +faultString. + +.. _rpc_options: + +Options +~~~~~~~ + +Same options for :option:`--input-file <-i>` list are available. See `Input File`_ subsection for complete list of options. + +In the option struct, name element is option name(without preceding +``--``) and value element is argument as string. + +JSON-RPC Example +^^^^^^^^^^^^^^^^ +:: + + {'split':'1', 'http-proxy':'http://proxy/'} + + +XML-RPC Example +^^^^^^^^^^^^^^^ +.. code-block:: xml + + + + split + 1 + + + http-proxy + http://proxy/ + + + + +:option:`header <--header>` and :option:`index-out <-O>` +option are allowed multiple times in +command-line. Since name should be unique in struct(many XML-RPC +library implementation uses hash or dict for struct), single string is +not enough. To overcome this situation, they can take array as value +as well as string. + +JSON-RPC Example +^^^^^^^^^^^^^^^^ +:: + + {'header':['Accept-Language: ja', 'Accept-Charset: utf-8']} + + +XML-RPC Example +^^^^^^^^^^^^^^^ +.. code-block:: xml + + + + header + + + + Accept-Language: ja + Accept-Charset: utf-8 + + + + + + + +Following example adds a download with 2 options: dir and header. +header option has 2 values, so it uses a list:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> opts = dict(dir='/tmp', + ... header=['Accept-Language: ja', + ... 'Accept-Charset: utf-8']) + >>> s.aria2.addUri(['http://example.org/file'], opts) + '1' + + +JSON-RPC using HTTP GET +~~~~~~~~~~~~~~~~~~~~~~~ + +The JSON-RPC interface also supports request via HTTP GET. +The encoding scheme in GET parameters is based on JSON-RPC over HTTP Specification [2008-1-15(RC1)]. +The encoding of GET parameters are follows:: + + /jsonrpc?method=METHOD_NAME&id=ID¶ms=BASE64_ENCODED_PARAMS + + +The ``method`` and ``id`` are always treated as JSON string and their +encoding must be UTF-8. + +For example, The encoded string of aria2.tellStatus('3') with id='foo' +looks like this:: + + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D + + +The ``params`` parameter is Base64-encoded JSON array which usually +appears in ``params`` attribute in JSON-RPC request object. In the +above example, the params is ['3'], therefore:: + + ['3'] --(Base64)--> WyIzIl0= --(Percent Encode)--> WyIzIl0%3D + + +The JSON-RPC interface supports JSONP. You can specify the callback +function in 'jsoncallback' parameter:: + + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D&jsoncallback=cb + + +For Batch request, ``method`` and ``id`` parameter must not be specified. +Whole request must be specified in ``params`` parameter. For example, +Batch request:: + + [{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'}, + {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}] + + +will be encoded like this:: + + /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D + + +JSON-RPC over WebSocket +~~~~~~~~~~~~~~~~~~~~~~~ + +JSON-RPC over WebSocket uses same method signatures and response +format with JSON-RPC over HTTP. The supported WebSocket version is 13 +which is detailed in :rfc:`6455`. + +To send a RPC request to the RPC server, send serialized JSON string +in Text frame. The response from the RPC server is delivered also in +Text frame. + +The RPC server will send the notification to the client. The +notification is unidirectional, therefore the client which received +the notification must not respond to it. The method signature of +notification is much like a normal method request but lacks id +key. The value associated by the params key is the data which this +notification carries. The format of this value varies depending on the +notification method. Following notification methods are defined. + + +.. function:: aria2.onDownloadStart(event) + + + This notification will be sent if a download is started. + The *event* is of type struct and it contains following keys. + The value type is string. + + ``gid`` + GID of the download. + + +.. function:: aria2.onDownloadPause(event) + + + This notification will be sent if a download is paused. The *event* + is the same struct of the *event* argument of + :func:`aria2.onDownloadStart` method. + + +.. function:: aria2.onDownloadStop(event) + + + This notification will be sent if a download is stopped by the user. + The *event* is the same struct of the *event* argument of + :func:`aria2.onDownloadStart` method. + + +.. function:: aria2.onDownloadComplete(event) + + + This notification will be sent if a download is completed. In + BitTorrent downloads, this notification is sent when the download is + completed and seeding is over. The *event* is the same struct of the + *event* argument of + :func:`aria2.onDownloadStart` method. + + +.. function:: aria2.onDownloadError(event) + + + This notification will be sent if a download is stopped due to error. + The *event* is the same struct of the *event* argument of + :func:`aria2.onDownloadStart` method. + + +.. function:: aria2.onBtDownloadComplete(event) + + + This notification will be sent if a download is completed in + BitTorrent (but seeding may not be over). The *event* is the same struct + of the *event* argument of + :func:`aria2.onDownloadStart` method. + +Sample XML-RPC Client Code +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following Ruby script adds ``http://localhost/aria2.tar.bz2`` to +aria2c operated on localhost with option :option:`--dir=/downloads <-d>` and +prints its reponse: + +.. code-block:: ruby + + #!/usr/bin/env ruby + + require 'xmlrpc/client' + require 'pp' + + client=XMLRPC::Client.new2("http://localhost:6800/rpc") + + options={ "dir" => "/downloads" } + result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options) + + pp result + + +If you are a Python lover, you can use xmlrpclib(for Python3.x, use +xmlrpc.client instead) to interact with aria2:: + + import xmlrpclib + from pprint import pprint + + s = xmlrpclib.ServerProxy("http://localhost:6800/rpc") + r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"}) + pprint(r) + + +EXAMPLE +------- + +HTTP/FTP Segmented Download +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Download a file +^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host/file.zip" + + +.. note:: + + To stop a download, press :kbd:`Ctrl-C`. You can resume the transfer by running aria2c with the same argument in the same directory. You can change URIs as long as they are pointing to the same file. + +Download a file from 2 different HTTP servers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host/file.zip" "http://mirror/file.zip" + + +Download a file from 1 host using 2 connections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -x2 -k1M "http://host/file.zip" + + +Download a file from HTTP and FTP servers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host1/file.zip" "ftp://host2/file.zip" + + +Download files listed in a text file concurrently +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -ifiles.txt -j2 + +.. note:: + + -j option specifies the number of parallel downloads. + +Using proxy +^^^^^^^^^^^ +For HTTP: + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" "http://host/file" + + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file" + + +For FTP: + +.. code-block:: console + + $ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file" + + +.. note:: + + See :option:`--http-proxy`, :option:`--https-proxy`, :option:`--ftp-proxy`, :option:`--all-proxy` and + :option:`--no-proxy` for details. You can specify proxy in the environment + variables. See `ENVIRONMENT`_ section. + +Proxy with authorization +^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file" + + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file" + + +Metalink Download +~~~~~~~~~~~~~~~~~ +Download files with remote Metalink +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --follow-metalink=mem "http://host/file.metalink" + + +Download using a local metalink file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -p --lowest-speed-limit=4000 file.metalink + +.. note:: + + To stop a download, press :kbd:`Ctrl-C`. + You can resume the transfer by running aria2c with the same argument in the same + directory. + +Download several local metalink files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j2 file1.metalink file2.metalink + + +Download only selected files using index +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --select-file=1-4,8 file.metalink + +.. note:: + + The index is printed to the console using -S option. + +Download a file using a local .metalink file with user preference +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink + + +BitTorrent Download +~~~~~~~~~~~~~~~~~~~ +Download files from remote BitTorrent file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --follow-torrent=mem "http://host/file.torrent" + + +Download using a local torrent file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-upload-limit=40K file.torrent + +.. note:: + + --max-upload-limit specifies the max of upload rate. + +.. note:: + + To stop a download, press :kbd:`Ctrl-C`. You can resume the transfer by running aria2c with the same argument in the same directory. + +Download using BitTorrent Magnet URI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2" + + +.. note:: + + Don't forget to quote BitTorrent Magnet URI which includes ``&`` + character with single(``'``) or double(``"``) quotation. + +Download 2 torrents +^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j2 file1.torrent file2.torrent + + +Download a file using torrent and HTTP/FTP server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file" + +.. note:: + + Downloading multi file torrent with HTTP/FTP is not supported. + +Download only selected files using index(usually called "selectable download") +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --select-file=1-4,8 file.torrent + +.. note:: + + The index is printed to the console using -S option. + +Specify output filename +^^^^^^^^^^^^^^^^^^^^^^^ + +To specify output filename for BitTorrent downloads, you need to know +the index of file in torrent file using :option:`--show-files <-S>` option. For example, the +output looks like this:: + + idx|path/length + ===+====================== + 1|dist/base-2.6.18.iso + |99.9MiB + ---+---------------------- + 2|dist/driver-2.6.18.iso + |169.0MiB + ---+---------------------- + + +To save 'dist/base-2.6.18.iso' in '/tmp/mydir/base.iso' and +'dist/driver-2.6.18.iso' in '/tmp/dir/driver.iso', use the following +command: + +.. code-block:: console + + $ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent + + +Change the listening port for incoming peer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --listen-port=7000-7001,8000 file.torrent + +.. note:: + + Since aria2 doesn't configure firewall or router for port forwarding, it's up + to you to do it manually. + +Specify the condition to stop program after torrent download finished +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent + + +.. note:: + + In the above example, the program exits when the 120 minutes has elapsed since download completed or seed ratio reaches 1.0. + +Throttle upload speed +^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-upload-limit=100K file.torrent + + +Enable IPv4 DHT +^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --enable-dht --dht-listen-port=6881 file.torrent + +.. note:: + + DHT uses udp port. Since aria2 doesn't configure firewall or router for port + forwarding, it's up to you to do it manually. + +Enable IPv6 DHT +^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR --enable-async-dns6 + +.. note:: + + If aria2c is not built with c-ares, :option:`--enable-async-dns6` is + unnecessary. aria2 shares same port between IPv4 and IPv6 DHT. + +Add and remove tracker URI +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Removes all tracker announce URIs described in file.torrent and use +``http://tracker1/announce`` and ``http://tracker2/announce`` instead: + +.. code-block:: console + + $ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent + + +More advanced HTTP features +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Load cookies +^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --load-cookies=cookies.txt "http://host/file.zip" + +.. note:: + + You can use Firefox/Mozilla/Chromium's cookie file without modification. + +Resume download started by web browsers or another programs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -c -s2 "http://host/partiallydownloadedfile.zip" + + +Client certificate authorization for SSL/TLS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file + +.. note:: + + The file specified in :option:`--private-key` must be decrypted. The behavior when + encrypted one is given is undefined. + +Verify peer in SSL/TLS using given CA certificates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file + + +And more advanced features +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Throttle download speed +^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-download-limit=100K file.metalink + + +Repair a damaged download +^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -V file.metalink + +.. note:: + + Repairing damaged downloads can be done efficiently when used with + BitTorrent or Metalink with chunk checksums. + +Drop connection if download speed is lower than specified value +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --lowest-speed-limit=10K file.metalink + + +Parameterized URI support +^^^^^^^^^^^^^^^^^^^^^^^^^ +You can specify set of parts: + +.. code-block:: console + + $ aria2c -P "http://{host1,host2,host3}/file.iso" + + +You can specify numeric sequence: + +.. code-block:: console + + $ aria2c -Z -P "http://host/image[000-100].png" + + +.. note:: + + -Z option is required if the all URIs don't point to the same file, such as the above example. + +You can specify step counter: + +.. code-block:: console + + $ aria2c -Z -P "http://host/image[A-Z:2].png" + + +Verify checksum +^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file + + +Parallel downloads of arbitrary number of URI,metalink,torrent +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink + + +BitTorrent Encryption +^^^^^^^^^^^^^^^^^^^^^ +Encrypt whole payload using ARC4: + +.. code-block:: console + + $ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent + + +SEE ALSO +-------- +Project Web Site: http://aria2.sourceforge.net/ + +aria2 Wiki: http://sourceforge.net/apps/trac/aria2/wiki + +Metalink Homepage: http://www.metalinker.org/ + +The Metalink Download Description Format: :rfc:`5854` + +COPYRIGHT +--------- +Copyright (C) 2006, 2011 Tatsuhiro Tsujikawa + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +In addition, as a special exception, the copyright holders give +permission to link the code of portions of this program with the +OpenSSL library under certain conditions as described in each +individual source file, and distribute linked combinations +including the two. +You must obey the GNU General Public License in all respects +for all of the code used other than OpenSSL. If you modify +file(s) with this exception, you may extend this exception to your +version of the file(s), but you are not obligated to do so. If you +do not wish to do so, delete this exception statement from your +version. If you delete this exception statement from all source +files in the program, then also delete it here. diff --git a/doc/manual-src/en/conf.py.in b/doc/manual-src/en/conf.py.in new file mode 100644 index 00000000..36a9992c --- /dev/null +++ b/doc/manual-src/en/conf.py.in @@ -0,0 +1,215 @@ +# -*- coding: utf-8 -*- +# +# aria2 documentation build configuration file, created by +# sphinx-quickstart on Tue Apr 10 21:34:06 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'aria2' +# copyright = u'2012, Tatsuhiro Tsujikawa' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '@PACKAGE_VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@PACKAGE_VERSION@' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = False + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'aria2doc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'aria2.tex', u'aria2 Documentation', + u'Tatsuhiro Tsujikawa', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('aria2c', 'aria2c', u'The ultra fast download utility', [], 1) +] diff --git a/doc/manual-src/en/index.rst b/doc/manual-src/en/index.rst new file mode 100644 index 00000000..42acc204 --- /dev/null +++ b/doc/manual-src/en/index.rst @@ -0,0 +1,14 @@ +.. aria2 documentation master file, created by + sphinx-quickstart on Tue Apr 10 21:34:06 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Aria2 Manual +============ + +Contents: + +.. toctree:: + :maxdepth: 3 + + aria2c diff --git a/doc/manual-src/ru/Makefile.am b/doc/manual-src/ru/Makefile.am new file mode 100644 index 00000000..67352dab --- /dev/null +++ b/doc/manual-src/ru/Makefile.am @@ -0,0 +1,157 @@ +# Makefile for Sphinx documentation +# +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = ../../manual/ru + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +# Configurations for aria2. +mandir = @mandir@/ru +man_MANS = $(BUILDDIR)/man/aria2c.1 +HTML = $(BUILDDIR)/html +EXTRA_DIST = $(man_MANS) $(HTML) +HTMLINSTALLDIR = $(docdir)/manual/ru + +# Copy $(BUILDDIR)/html recursively to the install dir. Since Automake +# does not provide this feature, we do it ourselves. +install-data-local: + mkdir -p $(HTMLINSTALLDIR) && \ + cp -r $(BUILDDIR)/html $(HTMLINSTALLDIR) && \ + rm -f $(HTMLINSTALLDIR)/html/.buildinfo + +uninstall-local: + -rm -rf $(HTMLINSTALLDIR) + +dist-hook: + -rm -f $(distdir)/$(BUILDDIR)/html/.buildinfo + +$(man_MANS): aria2c.rst + $(MAKE) man + +$(HTML): aria2c.rst + $(MAKE) html + +# Autogenerated rules by sphinx-quickstart + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/aria2.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/aria2.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/aria2" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/aria2" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/manual-src/ru/aria2c.rst b/doc/manual-src/ru/aria2c.rst new file mode 100644 index 00000000..17669b77 --- /dev/null +++ b/doc/manual-src/ru/aria2c.rst @@ -0,0 +1,4011 @@ +aria2c(1) +========= + +ОБЗОР +----- +**aria2c** [<ПАРАМЕТРЫ>] [|||] ... + +ОПИСАНИЕ +-------- + +aria2 - это утилита для загрузки файлов. Поддерживаемые протоколы: HTTP(S), +FTP, BitTorrent и Metalink. Для загрузки файла, aria2 может использовать +разные источники/протоколы и пытается максимально использовать пропускную +способность канала. Есть поддержка загрузки файла по протоколам HTTP(S)/FTP +и BitTorrent одновременно, пока данные загружаются по HTTP(S)/FTP, они тут +же могут выгружаться в BitTorrent-рой. Используя контрольные суммы блока +данных для Metalink, aria2 автоматически проверяет части данных, которые +загружаются по BitTorrent. + +ПАРАМЕТРЫ +--------- + +Основные параметры +~~~~~~~~~~~~~~~~~~ +.. option:: -d, --dir= + + Каталог для сохранения загруженных файлов. + +.. option:: -i, --input-file= + + Загрузить URI, найденные в файле FILE. Вы можете указать несколько URI для одного + объекта: разделяйте URI в строке, используя символ TAB (табуляция). Когда + указано ``-`` , ввод считывается из stdin (стандартный поток ввода). Дополнительные + параметры можно указывать после каждой строки с URI. Эта необязательная строка + должна начинаться с одного или нескольких пробелов и содержать один параметр. + Смотрите подраздел `Входной файл`_ для детальных пояснений. + Также смотрите параметр :option:`--deferred-input`. + +.. option:: -l, --log= + + Имя файла для журнала событий. Если указан ``-`` , то журнал событий будет + записан в stdout (стандартный поток вывода). Если указана пустая + строка (""), то журнал событий не будет записан в файл. + +.. option:: -j, --max-concurrent-downloads= + + Задать максимальное количество параллельных загрузок для каждого + статического (HTTP/FTP) URI, torrent и metalink. Смотрите также + параметр :option:`--split <-s>`. + По умолчанию: ``5`` + +.. option:: -V, --check-integrity[=true|false] + + Проверить целостность файла путем подтверждения хэшей блоков или хэша + полного файла. Этот параметр влияет лишь на BitTorrent, Metalink + или HTTP(S)/FTP загрузки с параметром :option:`--checksum`. + Параметр может обнаружить поврежденные части файла и перезагрузить их. + Если есть хэш полного файла, то проверка выполняется только, когда файл + уже полностью загружен. Момент полной загрузки определяется по размеру файла. Если + проверка хэша завершилась неудачно, то файл будет перезагружен с + нуля. Если есть хэши блоков и хэш полного файла, то будут + использоваться только хэши блоков. + По умолчанию: ``false`` + +.. option:: -c, --continue[=true|false] + + Продолжить загрузку частично загруженного файла. + Используйте этот параметр, чтобы возобновить загрузку, + начатую в веб-браузере или в другой программе, которая загружает + файлы последовательно сначала. Сейчас этот параметр можно + использовать только для HTTP(S)/FTP-загрузок. + По умолчанию: ``false`` + +.. option:: -h, --help[=|] + + Справочное сообщение определяется метками (TAG). Метки начинаются + с ``#``. Например, ``--help=#http`` даст справку по параметрам, + помеченным меткой ``#http``. Если задано слово (KEYWORD), не + являющееся меткой, то будет выведена справка по параметрам, + содержащих это слово. Возможные значения: ``#basic`` , ``#advanced`` , + ``#http`` , ``#https`` , ``#ftp`` , ``#metalink`` , ``#bittorrent`` , ``#cookie`` , + ``#hook`` , ``#file`` , ``#rpc`` , ``#checksum`` , ``#experimental`` , + ``#deprecated`` , ``#help`` , ``#all``. + По умолчанию: ``#basic`` + +Параметры HTTP/FTP +~~~~~~~~~~~~~~~~~~ +.. option:: --all-proxy= + + Использовать указанный прокси-сервер для всех протоколов. Для стирания + ранее определенного адреса используйте "". Вы можете отменить эту + установку и указать прокси-сервер для отдельного протокола, используя + параметры :option:`--http-proxy`, + :option:`--https-proxy` и + :option:`--ftp-proxy`. Влияет на все URI. + Формат PROXY - ``[http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]``. + Смотрите также раздел `ОКРУЖЕНИЕ`_. + + .. note:: + + Если пользователь и пароль вставлены в URI-прокси и они также указаны в + параметрах *--{http,https,ftp,all}-proxy-{user,passwd}*, то приоритетным + будет самое последнее. Например, у вас ``http-proxy-user="myname"``, + ``http-proxy-passwd="mypass"`` в aria2.conf и вы указали + ``--http-proxy="http://proxy"`` в командной строке, тогда запрос к HTTP-прокси + ``http://proxy`` будет с пользователем ``myname`` и паролем ``mypass``. + + Другой пример: если вы указали в командной строке + ``--http-proxy="http://user:pass@proxy" --http-proxy-user="myname" + --http-proxy-passwd="mypass"``, тогда запрос к HTTP-прокси ``http://proxy`` + будет с пользователем ``myname`` и паролем ``mypass``. + + Еще один пример: если вы + указали в командной строке ``--http-proxy-user="myname" + --http-proxy-passwd="mypass" --http-proxy="http://user:pass@proxy"``, тогда + запрос к HTTP-прокси ``http://proxy`` будет с пользователем ``user`` и паролем + ``pass``. + +.. option:: --all-proxy-passwd= + + Задать пароль для параметра :option:`--all-proxy`. + +.. option:: --all-proxy-user= + + Задать пользователя для параметра :option:`--all-proxy`. + +.. option:: --checksum== + + Задать контрольную сумму. TYPE - тип хэша. Поддерживаемые типы хэшей + перечислены в ``Алгоритмы хэширования`` при ``aria2c -v``. + DIGEST - шестнадцатеричное значение хэша. Например, указание значения + sha-1 хэша выглядит так: + ``sha-1=0192ba11326fe2298c8cb4de616f4d4140213838`` + Этот параметр применим только к HTTP(S)/FTP загрузкам. + +.. option:: --connect-timeout= + + Задать в соединении время ожидания в секундах для установки + подключения к HTTP/FTP/прокси-серверу. После установки + подключения этот параметр не имеет значения, и вместо него + используется параметр :option:`--timeout <-t>`. + По умолчанию: ``60`` + +.. option:: --dry-run[=true|false] + + Если задано ``true`` , aria2 только проверяет, является ли удаленный + файл доступным и не загружает данные. Этот параметр влияет на + HTTP/FTP-загрузку. BitTorrent-загрузки отменяются, если указано + ``true``. + По умолчанию: ``false`` + +.. option:: --lowest-speed-limit= + + Закрывать соединение, если скорость загрузки меньше чем или равна + значению SPEED (байт в секунду). ``0`` означает, что aria2 не имеет + нижнего ограничения скорости. Вы можете добавить ``K`` или ``M`` + (1K = 1024, 1M = 1024K). Этот параметр не влияет на + BitTorrent-загрузки. + По умолчанию: ``0`` + +.. option:: -x, --max-connection-per-server= + + Максимально количество соединений с одним сервером для каждой + загрузки. + По умолчанию: ``1`` + +.. option:: --max-file-not-found= + + Если aria2 получает статус "file not found" (файл не найден) с + удаленных HTTP/FTP-серверов NUM раз без получения, хотя бы одного байта, + тогда принудительно отказывается от загрузки. Укажите ``0`` , чтобы + отключить этот параметр. Этот параметр действенен только, когда + используются HTTP/FTP-серверы. + По умолчанию: ``0`` + +.. option:: -m, --max-tries= + + Задать количество попыток. ``0`` означает неограниченно. + Смотрите также :option:`--retry-wait`. + По умолчанию: ``5`` + +.. option:: -k, --min-split-size= + + aria2 не разбивает на части меньше чем 2*SIZE байт. Например, + нужно загрузить файл размером 20МиБ. Если SIZE задать 10M, то + aria2 может разбить файл на части в 2-ух диапазонах [0-10МиБ) и + [10МиБ-20МиБ) и загрузить его, используя 2 источника + (если :option:`--split <-s>` >= 2, конечно же). + Если SIZE задать 15M, т.к. 2*15M > 20MiB, aria2 не разобьет файл + на части и загрузит его, используя 1 источник. Вы можете + добавить ``K`` или ``M`` (1K = 1024, 1M = 1024K). Возможные значения: + ``1M`` -``1024M``. + По умолчанию: ``20M`` + +.. option:: -n, --no-netrc[=true|false] + + Отключить поддержку netrc. Поддержка netrc по умолчанию + включена. + + .. note:: + + Файл netrc считывается только при запуске, если :option:`--no-netrc <-n>` задан как ``false``. Так что если :option:`--no-netrc <-n>` задан как ``true`` при загрузке, то netrc недоступен на + протяжении всей сессии. Вы не сможете получить доступ к netrc, даже если + отправите :option:`--no-netrc=false, <-n>` используя + :func:`aria2.changeGlobalOption`. + +.. option:: --no-proxy= + + Укажите через запятую имена хостов, домены и сетевые адреса + с CIDR-блоком, или без него, для которых не будет использоваться прокси. + + .. note:: + + CIDR-блок (метод IP-адресации, например 192.168.0.20/24) работает с IPv4- и + IPv6-адресами. Текущая реализация не разрешает имена хостов в URI для + сравнения сетевых адресов указанных в + :option:`--no-proxy`. Таким образом, это эффективно, только если в URI есть + IP-адреса. + +.. option:: -o, --out= + + Сохранить загруженный файл под указанным именем. Если используется + параметр :option:`--force-sequential <-Z>`, то данный параметр + игнорируется. + + .. note:: + + В Metalink или BitTorrent загрузках вы не можете указать имя файла. Имя + файла указывается здесь, только когда используются URI и aria2 с командной + строкой без параметров :option:`--input-file <-i>`, + :option:`--force-sequential <-Z>`. Например: + + .. code-block:: console + + $ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip" + +.. option:: --proxy-method= + + Задать метод для использования в прокси-запросах. METHOD один + из двух: ``get`` или ``tunnel``. HTTPS-загрузки всегда используют ``tunnel`` , + не обращая внимания на этот параметр. + По умолчанию: ``get`` + +.. option:: -R, --remote-time[=true|false] + + Извлекать временную метку файла с удаленного HTTP/FTP-сервера и, + если это доступно, применить ее к локальному файлу. + По умолчанию: ``false`` + +.. option:: --reuse-uri[=true|false] + + Повторно использовать уже использованные URI, если + не осталось неиспользованных URI. + По умолчанию: ``true`` + +.. option:: --retry-wait= + + Задать в секундах интервал ожидания между повторными попытками. + При SEC > 0, если HTTP-сервер возвращает ответ 503, aria2 будет + снова пытаться загрузить. + По умолчанию: ``0`` + +.. option:: --server-stat-of= + + Указать имя файла, в который сохраняется профиль функционирования + сервера. Вы можете загрузить сохраненные данные, используя параметр + :option:`--server-stat-if`. Формат файла + смотрите ниже в подразделе + `Профиль функционирования сервера`_. + +.. option:: --server-stat-if= + + Указать имя файла для загрузки профиля функционирования сервера. + Загруженные данные будут использованы в некоторых URI селекторах, таких + как ``feedback``. Смотрите также параметр + :option:`--uri-selector`. Формат файла смотрите + ниже в подразделе + `Профиль функционирования сервера`_. + +.. option:: --server-stat-timeout= + + Указывает время ожидания в секундах, для того, чтобы сделать + недействительным профиль функционирования сервера, с тех пор, + как состоялся последний контакт с ним. + По умолчанию: ``86400`` (24 часа) + +.. option:: -s, --split= + + Загружать файл, используя N соединений. Если задано более чем N URI, + будут использоваться первые N URI, а оставшиеся URI будут в резерве. + Если задано менее чем N URI, то URI будут использованы более одного раза, + так чтобы были задействованы все N соединений одновременно. Количество + соединений к одному и тому же хосту ограничивается параметром + :option:`--max-connection-per-server <-x>`. + Смотрите также параметр :option:`--min-split-size <-k>`. + По умолчанию: ``5`` + + .. note:: + + Некоторые Metalink регламентируют количество серверов для соединения. aria2 + строго соблюдает это. Это значит, что если Metalink определяет атрибут + maxconnections меньше чем N, то aria2 использует значение атрибута + maxconnections вместо N. + +.. option:: --stream-piece-selector= + + Указать алгоритм выбора блока, который используется в HTTP/FTP-загрузке. + Блок - означает сегмент фиксированной длины, который загружается + параллельно, в разделенной на части, загрузке. Если задано ``default`` , + то aria2 выберет блок так, чтобы это уменьшило количество установленных + подключений. Это разумное поведение по умолчанию, поскольку установка + подключения очень затратная операция. Если задано ``inorder`` , то aria2 + выберет блок, который имеет минимальный индекс. Index=0 означает первый + из файла. Это будет полезно при просмотре фильма, в то время как он + загружается. Параметр + :option:`--enable-http-pipelining` может + быть полезен для снижения накладных расходов при повторном подключении. + Обратите внимание, что aria2 принимает на обработку параметр + :option:`--min-split-size <-k>`, так что необходимо + будет указать разумное значение параметра + :option:`--min-split-size <-k>`. + Если задано ``geom`` , то aria2 вначале выберет блок с минимальным + индексом, как при ``inorder`` , однако она сохранит + экспоненциально большую область от ранее выбранного блока. + Это уменьшит количество установленных подключений и в то же + время это позволит в первую очередь загрузить начало файла. + Это будет полезно при просмотре фильма, в то время как он + загружается. + По умолчанию: ``default`` + +.. option:: -t, --timeout= + + Задать время ожидания в секундах. + По умолчанию: ``60`` + +.. option:: --uri-selector= + + Указать алгоритм выбора URI. Возможные значения: ``inorder`` , ``feedback`` + и ``adaptive``. Если задано ``inorder`` , то URI проверяются в порядке + представления в списке URI. Если задано ``feedback`` , aria2 использует + скорость загрузки, которая наблюдалась в предыдущих загрузках, и выбирает + самый быстрый сервер в списке URI. Это также эффективно исключает мертвые + зеркала. Наблюдаемая скорость загрузки является частью профиля + функционирования сервера, упомянутой в параметрах + :option:`--server-stat-of` и + :option:`--server-stat-if`. Если задано ``adaptive`` , + выбирается одно из лучших зеркал для первого и резервного соединений. + Дополнительно, возвращаются зеркала, которые пока не были проверены, и, + если каждое из них уже проверено, возвращаются зеркала, которые должны + быть проверены снова. Иначе зеркала больше не выбираются. + Подобно ``feedback`` , используются профиль функционирования сервера. + По умолчанию: ``feedback`` + +Специфические параметры HTTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --ca-certificate= + + Использовать сертификат авторизации в FILE для проверки узлов. + Сертификат должен быть в PEM-формате и содержать многоразовые + CA-сертификаты. Используйте параметр + :option:`--check-certificate`, чтобы + разрешить проверку. + +.. option:: --certificate= + + Использовать клиентский сертификат в FILE. Сертификат + должен быть в PEM-формате. Вы можете использовать + параметр :option:`--private-key`, + чтобы указать закрытый ключ. + +.. option:: --check-certificate[=true|false] + + Проверять каждый из используемых сертификатов, которые + указаны в параметре :option:`--ca-certificate`. + По умолчанию: ``true`` + +.. option:: --http-accept-gzip[=true|false] + + Посылать ``Accept: deflate, gzip`` в запросе-заголовке и добавлять в ответ, + если удаленный сервер ответит ``Content-Encoding: gzip`` или + ``Content-Encoding: deflate``. + По умолчанию: 'false + + .. note:: + + Некоторые серверы отвечают ``Content-Encoding: gzip`` для файлов, которые сами + по себе сжаты (gzipped). aria2 добавляет их, так или иначе, из-за заголовка + ответа. + +.. option:: --http-auth-challenge[=true|false] + + Отправлять заголовок HTTP-авторизации только тогда, когда он запрошен + с сервера. Если задано ``false`` , тогда заголовок авторизации всегда + отправляется на сервер. Существует исключение: если имя пользователя + и пароль являются встроенными в URI, то заголовок авторизации всегда + отправляется на сервер, независимо от этого параметра. + По умолчанию: ``false`` + +.. option:: --http-no-cache[=true|false] + + Отправлять заголовок Cache-Control: no-cache и Pragma: no-cache, + чтобы избежать кэширования содержимого. Если задано ``false`` , то эти + заголовки не посылаются, и вы можете добавить любую директиву к + заголовку Cache-Control с помощью параметра + :option:`--header`. + По умолчанию: ``true`` + +.. option:: --http-user= + + Задать пользователя для HTTP. Влияет на все URI. + +.. option:: --http-passwd= + + Задать пароль для HTTP. Влияет на все URI. + +.. option:: --http-proxy= + + Использовать указанный прокси-сервер для HTTP. Ранее указанный адрес + можно стереть, указав "". Смотрите также параметр + :option:`--all-proxy`. Влияет на все URI. + Формат PROXY - ``[http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]``. + +.. option:: --http-proxy-passwd= + + Задать пароль для параметра :option:`--http-proxy`. + +.. option:: --http-proxy-user= + + Задать пользователя для параметра :option:`--http-proxy`. + +.. option:: --https-proxy= + + Использовать указанный прокси-сервер для HTTPS. Ранее указанный + адрес можно стереть, указав "". Смотрите также параметр + :option:`--all-proxy`. Влияет на все URI. + Формат PROXY - ``[http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]``. + +.. option:: --https-proxy-passwd= + + Задать пароль для параметра :option:`--https-proxy`. + +.. option:: --https-proxy-user= + + Задать пользователя для параметра :option:`--https-proxy`. + +.. option:: --private-key= + + Использовать закрытый ключ в FILE. Закрытый ключ должен + быть дешифрованным и в PEM-формате. Режим работы с исходно + зашифрованным закрытым ключом не определен. Смотрите также + параметр :option:`--certificate`. + +.. option:: --referer= + + Задать источника запроса. Влияет на все URI. + +.. option:: --enable-http-keep-alive[=true|false] + + Включить HTTP/1.1 постоянное соединение. + По умолчанию: ``true`` + +.. option:: --enable-http-pipelining[=true|false] + + Включить конвейерную обработку HTTP/1.1. + По умолчанию: ``false`` + + .. note:: + + С точки зрения производительности, как правило, нет преимущества от + включения этого параметра. + +.. option:: --header=
+ + Добавлять HEADER к HTTP запросу-заголовку. Вы можете использовать + этот параметр повторно, чтоб указать более одного заголовка: + + .. code-block:: console + + $ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file" + +.. option:: --load-cookies= + + Загружать куки-файл из FILE, используя форматы Firefox3 (SQLite3), + Chromium/Google Chrome (SQLite3) и Mozilla/Firefox(1.x/2.x)/Netscape. + + .. note:: + + Если aria2 собрана без libsqlite3, то форматы куки-файлов Firefox3 и + Chromium/Google Chrome не поддерживаются. + +.. option:: --save-cookies= + + Сохранить куки в FILE формате Mozilla/Firefox(1.x/2.x)/Netscape. + Если FILE уже существует, то он будет перезаписан. Куки-сессия также + сохранится, и значение ее окончания будет трактоваться как 0. + Возможные значения: ``/путь/к/файлу`` + +.. option:: --use-head[=true|false] + + Использовать метод HEAD для первого запроса к HTTP серверу. + По умолчанию: ``false`` + + +.. option:: -U, --user-agent= + + Задать клиентское приложение для HTTP(S)-загрузок. + По умолчанию: ``aria2/$VERSION`` , $VERSION заменяется на версию пакета. + +Специфические параметры FTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --ftp-user= + + Задать пользователя для FTP. + Влияет на все URI. + По умолчанию: ``anonymous`` + +.. option:: --ftp-passwd= + + Задать пароль для FTP. Влияет на все URI. Если имя пользователя + встроено, но пароль отсутствует в URI, то aria2 пытается использовать + пароль из .netrc. Если пароль найден в .netrc, то он используется. + Если нет, используется пароль, указанный в этом параметре. + По умолчанию: ``ARIA2USER@`` + +.. option:: -p, --ftp-pasv[=true|false] + + Использовать пассивный режим FTP. Если задано ``false`` , + то будет использован активный режим. + По умолчанию: ``true`` + +.. option:: --ftp-proxy= + + Использовать указанный прокси-сервер для FTP. Ранее указанный адрес + можно стереть, указав "". Смотрите также параметр + :option:`--all-proxy`. Влияет на все URI. + Формат PROXY - ``[http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]`` + +.. option:: --ftp-proxy-passwd= + + Задать пароль для параметра :option:`--ftp-proxy`. + +.. option:: --ftp-proxy-user= + + Задать пользователя для параметра :option:`--ftp-proxy`. + +.. option:: --ftp-type= + + Задать тип передачи для FTP. TYPE может быть один из + двух: ``binary`` или ``ascii``. + По умолчанию: ``binary`` + +.. option:: --ftp-reuse-connection[=true|false] + + Повторно использовать FTP соединение. + По умолчанию: ``true`` + +Параметры BitTorrent/Metalink +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --select-file=... + + Задать файл для загрузки по заданному индексу. Вы можете найти + индекс файла, используя параметр :option:`--show-files <-S>`. + Составной индекс можно указать, используя ``,``, например: ``3,6``. + Вы можете также использовать ``-``, чтобы указать диапазон: ``1-5``. + ``,`` и ``-`` могут быть использованы вместе: ``1-5,8,9``. + Когда используется с параметром -M, индекс может сильно зависеть + от запроса (смотрите параметры *--metalink-\**). + + .. note:: + + В многофайловом торренте, смежные файлы, указанные в этом параметре также + могут быть загружены. Это не ошибка, а особенность утилиты. Одиночный блок + данных может включать несколько файлов или часть файла, и aria2 запишет блок + данных соответствующего файла. + +.. option:: -S, --show-files[=true|false] + + Вывести список файлов из .torrent, .meta4 или .metalink и + выйти. Для файла .torrent будет выведена более детальная + информация (информация по хэшу, размер блока и др.). + +Специфические параметры BitTorrent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: --bt-enable-lpd[=true|false] + + Включить поиск локальных пиров. Если в torrent-файле установлен + приватный признак, то aria2 не будет использовать эту возможность, + даже если задано ``true``. + По умолчанию: ``false`` + +.. option:: --bt-exclude-tracker=[,...] + + Разделенный запятыми список URI анонса BitTorrent-трекера, + которые будут исключены. Вы можете использовать специальное + значение ``*``, которое соответствует всем URI, таким образом, + исключаются все URI анонса. При указании ``*`` в оболочке + командной строке, не забывайте, экранировать или брать в кавычки. + Смотрите также параметр :option:`--bt-tracker`. + +.. option:: --bt-external-ip= + + Указать внешний IP-адрес BitTorrent-трекера для отчета. + Не смотря на то, что эта функция названа ``external`` (``внешний``), + она может принимать любой IP-адрес. IPADDRESS должен быть числовым + IP-адресом. + +.. option:: --bt-hash-check-seed[=true|false] + + Если задано ``true`` , то после проверки хэша с использованием параметра + :option:`--check-integrity <-V>`, и когда файл + загружен полностью, продолжается раздача файла. Если вы хотите + проверить файл и загрузить его только если он поврежден или не загружен + полностью, то задайте этот параметр как ``false``. Этот параметр влияет + лишь на BitTorrent-загрузки. + По умолчанию: ``true`` + +.. option:: --bt-lpd-interface= + + Использовать для поиска локальных пиров заданный интерфейс. Если этот + параметр не указан, используется интерфейс по умолчанию. Можно указать + имя интерфейса и IP-адрес. Возможные значения: интерфейс, IP-адрес. + +.. option:: --bt-max-open-files= + + Указать максимальное количество файлов для открытия в каждой + BitTorrent-загрузке. + По умолчанию: ``100`` + +.. option:: --bt-max-peers= + + Указать максимальное количество узлов для каждого торрента. + ``0`` означает неограниченно. Смотрите также параметр + :option:`--bt-request-peer-speed-limit`. + По умолчанию: ``55`` + +.. option:: --bt-metadata-only[=true|false] + + Загрузить только метаданные. Файл(ы), описывающий метаданные не + должен быть загружен. Этот параметр эффективен, только если + используется BitTorrent Magnet-ссылка. Смотрите также параметр + :option:`--bt-save-metadata`. + По умолчанию: ``false`` + +.. option:: --bt-min-crypto-level=plain|arc4 + + Задать минимальный уровень метода шифрования. Если узел поддерживает + несколько методов шифрования, aria2 выбирает наименьший, который + удовлетворяет заданный уровень. + По умолчанию: ``plain`` + +.. option:: --bt-prioritize-piece=head[=],tail[=] + + Пытаться загрузить сначала первую и последнюю части каждого файла. + Это бывает полезно для предварительного просмотра файлов. Аргумент + может содержать 2 ключевых слова: ``head`` и ``tail``. Для включения + обоих, необходимо разделить их запятой. Ключевые слова принимают + один параметр, SIZE. Например, если указано ``head=``, части, в + пределах первых SIZE байт каждого файла, получат повышенный + приоритет. ``tail=`` обозначает диапазон из последних SIZE байт + каждого файла. SIZE может включать букву ``K`` или ``M`` для обозначения + размера в килобайтах или мегабайтах, соответственно + (1K = 1024, 1M = 1024K). Если SIZE пропущено, то будет использовано + по умолчанию значение: SIZE=1M. + +.. option:: --bt-remove-unselected-file[=true|false] + + Удалить невыбранные файлы, когда завершена загрузка в + BitTorrent. Для выбора файлов используйте параметр + :option:`--select-file`. Если не + использовался этот параметр, то предполагается, что все файлы + выбраны. Пожалуйста, используйте этот параметр внимательно, + так как это фактически удалит файлы с вашего диска. + По умолчанию: ``false`` + +.. option:: --bt-require-crypto[=true|false] + + Если задано ``true`` , aria2 не принимает и не устанавливает соединение с + унаследованным BitTorrent handshake-сообщением (рукопожатие) + (BitTorrent протокол). Таким образом, aria2 всегда использует обфускацию + handshake-сообщения. + По умолчанию: ``false`` + +.. option:: --bt-request-peer-speed-limit= + + Если итоговая скорость загрузки каждого торрента, ниже чем SPEED, + aria2 временно увеличивает количество узлов, пытаясь увеличить + скорость загрузки. Настройка этого параметра с выбранной вами + скоростью загрузки может, в некоторых случаях, увеличить вашу + скорость загрузки. Вы можете добавить ``K`` или ``M`` (1K = 1024, 1M = 1024K). + По умолчанию: ``50K`` + +.. option:: --bt-save-metadata[=true|false] + + Сохранить метаданные как файл .torrent. Этот параметр + эффективен только если используется BitTorrent Magnet-ссылка. + Имя файла шестнадцатеричное представление хэша с расширением + .torrent. Файл сохранится в каталог, в тот же самый, куда + сохранится загружаемый файл. Если тот же самый файл уже + существует, метаданные не сохранятся. Смотрите также параметр + :option:`--bt-metadata-only`. + По умолчанию: ``false`` + +.. option:: --bt-seed-unverified[=true|false] + + Раздавать первоначально загруженные файлы без проверки хэшей блоков. + По умолчанию: ``false`` + +.. option:: --bt-stop-timeout= + + Остановить BitTorrent загрузку, если скорость загрузки равна 0 на + протяжении SEC секунд. Если задано ``0`` , то эта возможность не будет + использоваться. + По умолчанию: ``0`` + +.. option:: --bt-tracker=[,...] + + Разделенный запятыми список дополнительных URI анонса + BitTorrent-трекеров. На эти URI не действует параметр + :option:`--bt-exclude-tracker`, + потому что они добавляются после URI, указанных в параметре + :option:`--bt-exclude-tracker`, + которые исключаются. + +.. option:: --bt-tracker-connect-timeout= + + Задать время ожидания в секундах для установки соединения с трекером. + После установки соединения, это параметр станет не действительным, + а вместо него будет использован + :option:`--bt-tracker-timeout`. + По умолчанию: ``60`` + +.. option:: --bt-tracker-interval= + + Задать интервал в секундах между запросами трекера. Это полностью + отменяет значение интервала и aria2 использует только это значение + и игнорирует минимальный интервал и значение интервала в ответе + трекера. Если задан ``0`` , aria2 определяет интервал, основываясь на + ответе трекера и прогрессе загрузки. + По умолчанию: ``0`` + +.. option:: --bt-tracker-timeout= + + Задать время ожидания в секундах. + По умолчанию: ``60`` + +.. option:: --dht-entry-point=: + + Задать хост и порт, как точку входа в IPv4 DHT сеть. + +.. option:: --dht-entry-point6=: + + Задать хост и порт, как точку входа в IPv6 DHT сеть. + +.. option:: --dht-file-path= + + Заменять файл таблицы маршрутизации IPv4 DHT на PATH. + По умолчанию: ``$HOME/.aria2/dht.dat`` + +.. option:: --dht-file-path6= + + Заменять файл таблицы маршрутизации IPv6 DHT на PATH. + По умолчанию: ``$HOME/.aria2/dht.dat`` + +.. option:: --dht-listen-addr6= + + Указать адрес привязки сокета для IPv6 DHT. Он должен быть глобальным + IPv6 unicast-адресом хоста. + +.. option:: --dht-listen-port=... + + Задать прослушиваемый UDP-порт для обоих IPv4 и IPv6 DHT. Несколько портов можно + указать через ``,``, например: ``6881,6885``. Вы также можете использовать ``-`` + чтобы указать диапазон: ``6881-6999``. ``,`` и ``-`` могут быть использованы + вместе. + По умолчанию: ``6881-6999`` + + .. note:: + + Удостоверьтесь, что указанные порты открыты для входящего UDP-трафика. + +.. option:: --dht-message-timeout= + + Задать время ожидания в секундах. + По умолчанию: ``10`` + +.. option:: --enable-dht[=true|false] + + Включить IPv4 DHT функциональность. Если в torrent-файле задан + приватный признак, aria2 не будет использовать DHT для загрузки, + даже если установлен ``true``. + По умолчанию: ``true`` + +.. option:: --enable-dht6[=true|false] + + Включить IPv6 DHT функциональность. Если в torrent-файле задан + приватный признак, aria2 не будет использовать DHT для загрузки, + даже если установлен ``true``. Используйте параметр + :option:`--dht-listen-port` для указания + прослушиваемого порта. Смотрите также параметр + :option:`--dht-listen-addr6`. + +.. option:: --enable-peer-exchange[=true|false] + + Включить расширение BitTorrent-протокола для обмена списками участников. + Если в torrent-файле задан приватный признак, то эта возможность будет + отключена, даже если установлен ``true``. + По умолчанию: ``true`` + +.. option:: --follow-torrent=true|false|mem + + Если указать ``true`` или ``mem`` , тогда загруженный файл, расширение + которого - ``.torrent`` или mime-тип - ``application/x-bittorrent``, + aria2 анализирует как torrent-файл и загружает файлы, указанные в нем. + Если указано ``mem`` , тогда torrent-файл не записывается на диск, + а содержится в памяти. Если указано ``false`` , действия, упомянутые + выше, не совершаются. + По умолчанию: ``true`` + +.. option:: -O, --index-out== + + Задать путь к файлу PATH с индексом INDEX. Вы можете найти индекс файла, + используя параметр :option:`--show-files <-S>`. PATH + является относительным путем к тому, который указан в параметре + :option:`--dir <-d>`. Вы можете использовать этот параметр + много раз. Используйте этот параметр, когда хотите указать имена + выходных файлов для BitTorrent-загрузок. + +.. option:: --listen-port=... + + Задать номер TCP-порта для BitTorrent-загрузок. Несколько портов можно + указать, используя ``,``, например: ``6881,6885``. Вы также можете + использовать ``-``, чтобы указать диапазон: ``6881-6999``. ``,`` и ``-`` + могут быть использованы вместе: ``6881-6889,6999``. + По умолчанию: ``6881-6999`` + + .. note:: + + Удостоверьтесь, что указанные порты открыты для входящего TCP-трафика. + +.. option:: --max-overall-upload-limit= + + Задать максимальную общую скорость отдачи в байтах/сек. + ``0`` значит неограниченно. Вы можете добавить + ``K`` или ``M`` (1K = 1024, 1M = 1024K). Чтобы ограничить скорость + отдачи для узла торрента, используйте параметр + :option:`--max-upload-limit <-u>`. + По умолчанию: ``0`` + +.. option:: -u, --max-upload-limit= + + Задать максимальную скорость отдачи каждого узла торрента в байтах/сек. + ``0`` значит неограниченно. Вы можете добавить + ``K`` или ``M`` (1K = 1024, 1M = 1024K). Чтобы ограничить + общую скорость отдачи, используйте параметр + :option:`--max-overall-upload-limit`. + По умолчанию: ``0`` + +.. option:: --peer-id-prefix= + + Указать префикс для ID узла. ID узла в BitTorrent + имеет размер 20 байт. Если будет указано более 20 байт, + то только первые 20 будут использоваться, если будет + указано меньше 20, то они будут дополнены случайными + данными до 20 байт. + По умолчанию: ``aria2/$VERSION`` , $VERSION заменяется на версию пакета. + +.. option:: --seed-ratio= + + Указать рейтинг. Сидировать завершенные торренты, пока рейтинг + не станет больше RATIO. Очень рекомендуется указать тут равный + или больший ``1.0``. Указать ``0.0`` , если вы планируете сидировать + независимо от рейтинга. Если указан параметр + :option:`--seed-time` вместе с этим + параметром, сидирование закончится тогда, когда хотя бы одно + условие будет удовлетворено. + По умолчанию: ``1.0`` + +.. option:: --seed-time= + + Указать время сидирования (раздачи) в минутах. + Смотрите также параметр :option:`--seed-ratio`. + + .. note:: + + Указанный :option:`--seed-time=0 <--seed-time>` отключает + сидирование после завершения загрузки. + +.. option:: -T, --torrent-file= + + Путь к файлу .torrent. Вы не обязаны использовать этот параметр, т.к. + файл .torrent можно указать без :option:`--torrent-file <-T>`. + +Специфические параметры Metalink +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --follow-metalink=true|false|mem + + Если указано ``true`` или ``mem`` и когда загруженный файл имеет расширение + ``.meta4`` или ``.metalink``, или mime-тип ``application/metalink4+xml`` + или ``application/metalink+xml``, aria2 считает его metalink-файлом и + загружает упомянутые в нем файлы. Если указано ``mem`` , то metalink-файл + не сохраняется на диск, а просто хранится в памяти. Если указано ``false`` , + то вышеприведенная операция не производится. + По умолчанию: ``true`` + +.. option:: --metalink-base-uri= + + Указать основной URI для разрешения относительных URI в элементе + metalink:url и metalink:metaurl в metalink-файле, сохраненном на + локальном диске. Если URI указывает на каталог, то URI должен + заканчиваться на ``/``. + +.. option:: -M, --metalink-file= + + Путь к файлу .meta4 и .metalink. Читает ввод из stdin, если в качестве + имени файла указано ``-``. Вы не обязаны использовать этот параметр, + т.к. файлы .metalink можно указать без :option:`--metalink-file <-M>`. + +.. option:: --metalink-language= + + Язык файла для загрузки. + +.. option:: --metalink-location=[,...] + + Местонахождение предпочитаемого сервера. Список, разделенный запятыми, + допустимых местонахождений, например, ``jp,us``. + +.. option:: --metalink-os= + + Целевая операционная система файла для загрузки. + +.. option:: --metalink-version= + + Версия файла для загрузки. + +.. option:: --metalink-preferred-protocol= + + Указать предпочитаемый протокол. Возможные значения: ``http`` , ``https`` , ``ftp`` + и ``none``. Указать ``none`` для отключения этой возможности. + По умолчанию: ``none`` + +.. option:: --metalink-enable-unique-protocol[=true|false] + + Если задано ``true`` , а в metalink-файле доступно несколько + протоколов, то aria2 использует один из них. Используйте параметр + :option:`--metalink-preferred-protocol`, + чтобы указать предпочитаемый протокол. + По умолчанию: ``true`` + +Параметры RPC +~~~~~~~~~~~~~ + +.. option:: --enable-rpc[=true|false] + + Включить JSON-RPC/XML-RPC-сервер. Настоятельно рекомендуется указать + имя пользователя и пароль, используя параметры + :option:`--rpc-user` и :option:`--rpc-passwd`. + Смотрите также параметр :option:`--rpc-listen-port`. + По умолчанию: ``false`` + +.. option:: --pause[=true|false] + + Приостановка загрузки после добавления. Этот параметр действенен + только, когда задан :option:`--enable-rpc=true. <--enable-rpc>` + По умолчанию: ``false`` + + +.. option:: --rpc-allow-origin-all[=true|false] + + Добавить заголовок Access-Control-Allow-Origin со значением ``*`` в RPC-ответе. + По умолчанию: ``false`` + +.. option:: --rpc-listen-all[=true|false] + + Слушать входящие JSON-RPC/XML-RPC-запросы на всех сетевых интерфейсах. + Если указано ``false`` , слушать только на локальном петлевом + интерфейсе (loopback). + По умолчанию: ``false`` + +.. option:: --rpc-listen-port= + + Указать номер порта, для прослушивания JSON-RPC/XML-RPC-сервером. + Возможные значения: ``1024`` -``65535``. + По умолчанию: ``6800`` + +.. option:: --rpc-max-request-size= + + Задать максимальный размер JSON-RPC/XML-RPC-запроса. + Если aria2 выявит запрос с размером большим, чем SIZE байт, + тогда соединение будет отклонено. + По умолчанию: ``2M`` + +.. option:: --rpc-passwd= + + Задать JSON-RPC/XML-RPC пароль. + +.. option:: --rpc-user= + + Задать JSON-RPC/XML-RPC пользователя. + +Дополнительные параметры +~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: --allow-overwrite[=true|false] + + Повторно запустить загрузку с нуля, если соответствующий контрольный + файл отсутствует. Смотрите также параметр + :option:`--auto-file-renaming`. + По умолчанию: ``false`` + +.. option:: --allow-piece-length-change[=true|false] + + Если задано ``false`` , aria2 прерывает загрузку, когда длина блока + отлична от той, которая находится в контрольном файле. Если задано + ``true`` , вы можете продолжать, однако некоторый прогресс загрузки + будет потерян. + По умолчанию: ``false`` + +.. option:: --always-resume[=true|false] + + Всегда возобновлять загрузку. Если задано ``true`` , aria2 всегда пытается + возобновить загрузку и если это не возможно, прерывает ее. + Если задано ``false`` , тогда для всех заданных URI не поддерживается + возобновление загрузки, или aria2 столкнется с невозможностью + возобновления загрузки URI ``N`` -ое количество раз + (значение ``N`` указывается в параметре + + то aria2 будет загружать файл с нуля. Смотрите параметр + :option:`--max-resume-failure-tries`. + По умолчанию: ``true`` + +.. option:: --async-dns[=true|false] + + Включить асинхронный DNS. + По умолчанию: ``true`` + +.. option:: --async-dns-server=[,...] + + Разделенный запятыми список адресов DNS-серверов, которые используют + асинхронный DNS-преобразователь. Обычно асинхронный DNS-преобразователь + читает адреса DNS-серверов из ``/etc/resolv.conf``. Когда используется + этот параметр, то используются DNS-серверы, указанные в параметре вместо + указанных в ``/etc/resolv.conf``. Вы можете указать оба IPv4 и IPv6 адреса. + Этот параметр полезен, когда в системе нет ``/etc/resolv.conf`` и у + пользователя нет прав на его создание. + +.. option:: --auto-file-renaming[=true|false] + + Переименовать файл, если такой уже существует. + Этот параметр работает только для HTTP(S)/FTP-загрузок. + К имени файла будет добавлена точка и число от 1 до 9999. + По умолчанию: ``true`` + +.. option:: --auto-save-interval= + + Сохранять контрольный файл (\*.aria2) каждые SEC секунд. + Если задано ``0`` , тогда контрольный файл не сохраняется на + протяжении загрузки. aria2 сохраняет контрольный файл тогда, + когда останавливается, не смотря на значение. + Возможные значения: от ``0`` до ``600``. + По умолчанию: ``60`` + +.. option:: --conditional-get[=true|false] + + Загружать файл только когда локальный файл старше, чем удаленный. + Эта функция работает только для HTTP(S)-загрузок. Это не работает, + если размер файла указан в Metalink. Это также игнорирует заголовок + Content-Disposition. Если контрольный файл существует, то этот + параметр игнорируется. Эта функция использует заголовок + If-Modified-Since, как условие для получения только нового файла. + При получении времени модификации локального файла, используется + указанное пользователем имя файла + (см. параметр :option:`--out <-o>`) или часть имени файла в + URI, если :option:`--out <-o>` не указан. Для перезаписи + существующего файла необходим параметр + :option:`--allow-overwrite`. + По умолчанию: ``false`` + +.. option:: --conf-path= + + Сменить путь к файлу конфигурации на PATH. + По умолчанию: ``$HOME/.aria2/aria2.conf`` + +.. option:: -D, --daemon[=true|false] + + Запустить как демон (фоновый процесс). Текущий рабочий каталог + будет заменен на ``/`` , а стандартный ввод, стандартный вывод, + стандартный вывод ошибок будут перенаправлены на ``/dev/null``. + По умолчанию: ``false`` + +.. option:: --deferred-input[=true|false] + + Если задано ``true`` , aria2 при запуске не считывает все URI и параметры + из файла, указанного в параметре :option:`--input-file <-i>`, а + считывает их позже отдельно, когда это нужно. Это может сократить + использование памяти, если во входном файле содержится много URI для + загрузки. Если задано ``false`` , aria2 при запуске считывает все URI + и параметры. + По умолчанию: ``false`` + +.. option:: --disable-ipv6[=true|false] + + Отключить IPv6. Это полезно, если вы используете поврежденный DNS + и хотите избежать ужасно медленного поиска AAAA-записи. + По умолчанию: ``false`` + +.. option:: --download-result= + + Этот параметр изменяет формат сообщения ``Результаты загрузки``. Если OPT + задан как ``default`` , то отображается GID, статус, средняя скорость загрузки и + путь/URI. Если загружается множество файлов, то отобразиться путь/URI первого + запрашиваемого файла, а остальные пропускаются. Если OPT задан как ``full`` , + то отображается GID, статус, средняя скорость загрузки, процент прогресса и + путь/URI. Процент прогресса и путь/URI отобразиться для каждого + запрашиваемого файла в отдельной строке. + По умолчанию: ``default`` + +.. option:: --enable-async-dns6[=true|false] + + Включить IPv6 разрешение имен в асинхронном DNS-преобразователе. + Этот параметр будет игнорироваться, если + :option:`--async-dns=false. <--async-dns>` + По умолчанию: ``false`` + +.. option:: --event-poll= + + Указать метод опроса событий. Возможные значения: ``epoll`` , ``kqueue`` , + ``port`` , ``poll`` и ``select``. Каждый метод ``epoll`` , ``kqueue`` , ``port`` и + ``poll`` доступен, если система поддерживает его. ``epoll`` доступен в + современных дистрибутивах Linux. ``kqueue`` доступен в различных + \*BSD-системах, включая Mac OS X. ``port`` доступен в Open Solaris. + Значение по умолчанию может изменяться в зависимости от системы, + которую вы используете. + +.. option:: --file-allocation= + + Указать метод резервирования места для файла. ``none`` не происходит + предварительное резервирование места для файла. ``prealloc`` - предварительное + резервирование места для файла перед началом загрузки. Это может + продолжаться некоторое время, в зависимости от размера файла. Если вы + используете новые файловые системы, наподобие ext4 (с поддержкой экстентов), + btrfs, xfs или NTFS (только сборка MinGW) тогда лучше выбрать ``falloc``. + Так как они резервируют место под большие (на несколько Гигабайт) файлы + почти мгновенно. Не используйте ``falloc`` вместе с наследными файловыми + системами, такими как ext3 и FAT32, потому что это будет продолжаться + почти столько же времени, как и ``prealloc`` , а также полностью заблокирует + aria2, пока не закончится резервирование места. ``falloc`` может быть + недоступным, если ваша система не содержит функцию :manpage:`posix_fallocate(3)`. + Возможные значения: ``none`` , ``prealloc`` , ``falloc``. + По умолчанию: ``prealloc`` + +.. option:: --hash-check-only[=true|false] + + Если задано ``true`` , то после проверки хэша, используя параметр + :option:`--check-integrity <-V>`, + загрузка прервётся, в любом случае загрузка завершится. + По умолчанию: ``false`` + +.. option:: --human-readable[=true|false] + + Выводить на консоль размеры и скорость в удобочитаемом формате + (например, 1.2Ки, 3.4Ми). + По умолчанию: ``true`` + +.. option:: --interface= + + Привязать сокеты к заданному интерфейсу. Вы можете указать имя + интерфейса, IP-адрес и имя хоста. Возможные значения: имя + интерфейса (например, eth0), IP-адрес (например, 192.168.0.12), + имя хоста (например, myhost). + + .. note:: + + Если интерфейс имеет несколько адресов, то настоятельно рекомендуется + указать IP-адрес явно. Смотрите также + :option:`--disable-ipv6`. Если ваша система не имеет :manpage:`getifaddrs(3)`, это параметр не + принимает имя интерфейса. + +.. option:: --max-download-result= + + Задать максимальное количество результатов загрузок, которые находятся + в памяти. Результаты загрузок - завершенные/ошибка/удаленные загрузки. + Результаты загрузок хранятся FIFO очереди, в которой может хранится NUM + результатов загрузок. Когда очередь заполнена и появляется новый + результат загрузки, то старейший результат загрузки удаляется из начала + очереди, а новый добавляется в конец. Указание большого числа в этом + параметре может привести к высокому потреблению памяти после тысяч + загрузок. Значение 0 отключит сохранение результата загрузки. + По умолчанию: ``1000`` + +.. option:: --max-resume-failure-tries= + + Если параметр :option:`--always-resume=false, <--always-resume>` aria2 + загрузит файл с нуля, при обнаружении ``N`` -го URI, не поддерживающего + возобновление. Если ``N`` =``0`` , то aria2 загрузит файл с нуля, когда все + URI не поддерживают возобновление. Смотрите параметр + :option:`--always-resume`. + По умолчанию: ``0`` + +.. option:: --log-level= + + Задать уровень вывода журнала событий. LEVEL может + быть: ``debug`` , ``info`` , ``notice`` , ``warn`` или ``error``. + По умолчанию: ``debug`` + +.. option:: --on-bt-download-complete= + + Для BitTorrent, в :option:`--on-download-complete` + указывается команда, которая вызывается после завершение загрузки и окончания + сидирования. С другой стороны, этот параметр определяет команду, которая + будет выполнена после завершения загрузки, но до сидирования. + Смотрите раздел `Перехват сообщения`_ для более подробной + информации о COMMAND. Возможные значения: ``/путь/к/команде`` + +.. option:: --on-download-complete= + + Задать команду, которая будет выполнена после завершения загрузки. + Смотрите раздел `Перехват сообщения`_ для более + подробной информации о COMMAND. Смотрите также параметр + :option:`--on-download-stop`. + Возможные значения: ``/путь/к/команде`` + +.. option:: --on-download-error= + + Задать команду, которая будет выполнена после того, как загрузка будет + прервана из-за ошибки. Смотрите раздел `Перехват сообщения`_ + для более подробной информации о COMMAND. Смотрите также параметр + :option:`--on-download-stop`. Возможные + значения: ``/путь/к/команде`` + +.. option:: --on-download-pause= + + Задать команду, которая будет выполнена после того, как + загрузка будет приостановлена. Смотрите раздел + `Перехват сообщения`_ для более подробной + информации о COMMAND. Возможные значения: ``/путь/к/команде`` + +.. option:: --on-download-start= + + Задать команду, которая будет выполнена после того, как + началась загрузка. Смотрите раздел `Перехват сообщения`_ + для более подробной информации о COMMAND. Возможные + значения: ``/путь/к/команде`` + +.. option:: --on-download-stop= + + Задать команду, которая будет выполнена после того, как загрузка + остановлена. Вы можете изменить команду, которая будет выполнятся + при определенном результате загрузки, используя параметры + :option:`--on-download-complete` и :option:`--on-download-error`. + Если они указаны, то команда, определенная в этом параметре не + будет выполнятся. Смотрите раздел `Перехват сообщения`_ + для более подробной информации о COMMAND. Возможные + значения: ``/путь/к/команде`` + +.. option:: --piece-length= + + Задать длину блока для HTTP/FTP-загрузок. Это является границей, когда + aria2 разделяет файл на части. Все разделения происходят многократно по + этой длине. Этот параметр будет игнорироваться при BitTorrent-загрузках. + Также будет игнорироваться, если Metalink-файл содержит хэши блоков. + По умолчанию: ``1M`` + + .. note:: + + Возможный вариант использования параметра + :option:`--piece-length` - изменение диапазона запроса в одном конвейерном + HTTP-запросе. Для включения конвейерной обработки HTTP используйте + :option:`--enable-http-pipelining`. + +.. option:: --show-console-readout[=true|false] + + Показывать консольный вывод. + По умолчанию: ``true`` + +.. option:: --summary-interval= + + Задать интервал в секундах до вывода сообщения о прогрессе + загрузки. Установка ``0`` запрещает вывод. + По умолчанию: ``60`` + + .. note:: + + В загрузках многофайлового торрента, по определенным смежным файлам также, + которые размещены в части одного блока. + +.. option:: -Z, --force-sequential[=true|false] + + Получить URI в последовательности командной строки и загрузить каждое + URI в отдельной сессии, как в обычных утилитах загрузки командной + строки. + По умолчанию: ``false`` + +.. option:: --max-overall-download-limit= + + Задать максимальную общую скорость загрузки в байтах/сек. ``0`` значит + неограниченно. Вы можете добавить ``K`` или ``M`` (1K = 1024, 1M = 1024K). + Чтобы ограничить скорость загрузки для узла, используйте параметр + :option:`--max-download-limit`. + По умолчанию: ``0`` + +.. option:: --max-download-limit= + + Установить максимальную скорость каждого узла загрузки в байтах/сек. ``0`` + значит неограниченно. Вы можете добавить ``K`` или ``M`` (1K = 1024, 1M = 1024K). + Чтобы ограничить общую скорость загрузки, используйте параметр + :option:`--max-overall-download-limit`. + По умолчанию: ``0`` + +.. option:: --no-conf[=true|false] + + Отключить загрузку файла aria2.conf. + +.. option:: --no-file-allocation-limit= + + Не резервируется место для файлов, размер которых меньше SIZE. + Вы можете добавить ``K`` или ``M`` (1K = 1024, 1M = 1024K). + По умолчанию: ``5M`` + +.. option:: -P, --parameterized-uri[=true|false] + + Включить поддержку параметризованных URI. Вы можете указать набор + частей: ``http://{sv1,sv2,sv3}/foo.iso``. Также вы можете указать + числовую последовательность с шагом + счетчика: ``http://host/image[000-100:2].img``. Шагом счетчика + можно пренебречь. Если все URI не указывают на такой же файл, как + во втором приведенном выше примере, то необходим параметр -Z. + По умолчанию: ``false`` + +.. option:: -q, --quiet[=true|false] + + Сделать aria2 молчаливой (без консольного вывода). + По умолчанию: ``false`` + +.. option:: --realtime-chunk-checksum[=true|false] + + Подтверждать правильность блока данных путем вычисления контрольной суммы + во время загрузки файла, если предусмотрена контрольная сумма блоков. + По умолчанию: ``true`` + + +.. option:: --remove-control-file[=true|false] + + Удалять контрольный файл перед загрузкой. При использовании с + :option:`--allow-overwrite=true <--allow-overwrite>` файл + всегда загружается с нуля. Это может понадобиться пользователям + за прокси-сервером, не поддерживающим возобновление загрузки. + +.. option:: --save-session= + + Сохранять ошибочные/незаконченные загрузки в FILE при выходе. Вы можете + передать этот выходной файл aria2c с параметром :option:`--input-file <-i>` при перезапуске. Обратите внимание, что + загрузки, добавленные через RPC-методы + :func:`aria2.addTorrent`, :func:`aria2.addMetalink` + и чьи метаданные не могут быть сохранены как файл, не будут сохраняться. + Загрузки, удаленные с использованием :func:`aria2.remove` и + :func:`aria2.forceRemove` не будут сохранены. + +.. option:: --stop= + + Останавливать программу после того как пройдет + SEC секунд. Если задано ``0`` , эта возможность будет + отключена. + По умолчанию: ``0`` + +.. option:: --stop-with-process= + + Остановить приложение, когда процесс с идентификационный номером PID + не работает. Это полезно, если процесс aria2 запущен из родительского + процесса. Родительский процесс может запустить aria2 со своим + идентификационным номером и когда он (процесс) завершиться по какой-то + причине, aria2 может обнаружить это и самостоятельно завершиться. + +.. option:: --truncate-console-readout[=true|false] + + Укорачивать консольный вывод, чтобы он поместился в + одну строку. + По умолчанию: ``true`` + +.. option:: -v, --version + + Вывести номер версии, информацию об авторских + правах, конфигурации и выйти. + +Параметры, которые принимают аргументы +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Параметры, которые имеют значения в квадратных скобках ([]), могут принимать +дополнительные (необязательные) аргументы. Обычно отсутствие аргумента +эквивалентно ``true``. Если вы используется короткую форму параметров +(например, ``-V``) и указываете аргумент, то имя параметра и его аргумент +должны быть объедены (например, ``-Vfalse``). Если будут вставлены пробелы +между именем параметра и аргументом, то аргумент будет обрабатываться как +URI, и это не то, что обычно вы ожидаете. + +URI, MAGNET-ССЫЛКА, TORRENT-ФАЙЛ, METALINK-ФАЙЛ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Вы можете перечислить несколько URI в командной строке. Пока вы не указали +параметр :option:`--force-sequential <-Z>`, все URI должны указывать +на один и тот же файл или загрузка завершиться не удачно. + +Вы можете указать произвольное количество BitTorrent Magnet URI. Обратите +внимание, что они всегда будут обрабатываться как отдельная +загрузка. Поддерживаются оба Info Hash (Информация о хэше), как +закодированный 40 шестнадцатеричными символами, так и закодированный 32 +символами Base32-кодировки. Поддерживаются составные параметры ``tr``. Т.к. в +BitTorrent Magnet URI возможно присутствие символа ``&``, то настоятельно +рекомендуется всегда заключать URI в одиночные(``'``) или двойные(``"``) +кавычки. Так же настоятельно рекомендуется включить DHT, особенно когда +параметр ``tr`` не указан. Смотрите +http://www.bittorrent.org/beps/bep_0009.html для детальной информации по +BitTorrent Magnet URI. + +Вы также можете указать произвольное количество torrent-файлов и +Metalink-документов, которые хранятся на локальном диске. Обратите внимание, +что они всегда будут обрабатываться как отдельная загрузка. Поддерживаются +оба формата: Metalink4 и Metalink версии 3.0. + +Вы можете указать вместе, torrent-файл с параметром -T и URI. Сделав это, вы +можете загружать файл, используя torrent-рой и HTTP(S)/FTP-сервер +одновременно, пока данные из HTTP(S)/FTP выгружаются в torrent-рой. Для +однофайловых торрентов, URI может быть завершенным, который указывает на +ресурс, или же если заканчиваться символом /, тогда name (имя) в +torrent-файле будет добавлено. Для многофайловых торентов, name (имя) и path +(путь) в torrent-файле будут добавлены из URI для каждого файла. + +.. note:: + + Удостоверьтесь, что URI заключен в одинарные(') или двойные(``"``) кавычки, если + есть символ ``&`` или любые символы, которые имеют особое значение в командной + оболочке. + +Возобновление загрузки +~~~~~~~~~~~~~~~~~~~~~~ + +Обычно, вы можете возобновить передачу, только запустив ту же самую команду +(aria2c URI), которая выполнялась при предыдущей передаче, созданной aria2. + +Если предыдущая передача создана веб-браузером или wget-подобным менеджером +загрузки, тогда используйте параметр :option:`--continue <-c>` для +продолжения передачи. + +Перехват сообщения +~~~~~~~~~~~~~~~~~~ + +aria2 предоставляет параметры, в которых указываются произвольные команды, +выполняемые после наступления определенного события. В настоящее время +доступны следующие параметры: +:option:`--on-bt-download-complete`, +:option:`--on-download-pause`, +:option:`--on-download-complete`. +:option:`--on-download-start`, +:option:`--on-download-error`, +:option:`--on-download-stop`. + +aria2 передает 3 аргумента указанной команды, которая выполняется. Это +аргументы: GID, количество файлов и путь к файлу. Для HTTP-, FTP-загрузок, +обычно количество файлов - 1. BitTorrent загрузка может содержать множество +файлов. Если число файлов больше чем один, то путь к файлу будет для +первого. Другими словами, это значение параметра path в первой структуре, +определенный параметр которой имеет значение true (истина), в ответе +RPC-метода :func:`aria2.getFiles`. Если вы хотите +получить все пути к файлам, то рассмотрите использование +JSON-RPC/XML-RPC. Обратите внимание, что путь к файлу может меняться в +процессе загрузки по HTTP из-за перенаправления или заголовка +Content-Disposition. + +Посмотрите пример, как аргументы передаются команде: + +.. code-block:: console + + $ cat hook.sh + #!/bin/sh + echo "Called with [$1] [$2] [$3]" + $ aria2c --on-download-complete hook.sh http://example.org/file.iso + Called with [1] [1] [/path/to/file.iso] + + +КОДЫ ЗАВЕРШЕНИЯ +--------------- + +Поскольку aria2 может обрабатывать несколько загрузок одновременно, она +сталкивается с множеством ошибок в сессии. aria2 возвращает следующий код +завершения, основанный на последней встретившейся ошибке. + +0 + Если все загрузки завершились успешно. + +1 + Если произошла неизвестная ошибка. + +2 + Если время истекло. + +3 + Если ресурс не был найден. + +4 + Если aria2 получила определенное число ошибок "ресурс не найден". Смотрите + параметр :option:`--max-file-not-found`. + +5 + Если загрузка прервана, поскольку скорость загрузки была слишком + медленной. Смотрите параметр + :option:`--lowest-speed-limit`. + +6 + Если произошла проблема с сетью. + +7 + Если были не завершенные загрузки. Эта ошибка только появляется, только если + все завершенные загрузки были успешны и были не завершенные загрузки в + очереди, когда aria2 завершилась по нажатию :kbd:`Ctrl-C` пользователем или при + отправке сигнала TERM или INT. + +8 + Если удаленный сервер не поддерживает возобновление, когда оно было указано + как обязательное для завершения загрузки. + +9 + Если было не достаточно доступного места на диске. + +10 + Если размер блока был отличным от указанного контрольном файле + .aria2. Смотрите параметр + :option:`--allow-piece-length-change`. + +11 + Если aria2 был загружен один и тот же файл в тот момент. + +12 + Если aria2 загрузила торрент с одним и тем же хэшем в этот момент. + +13 + Если файл уже существует. Смотрите параметр + :option:`--allow-overwrite`. + +14 + Если не удалось переименование. Смотрите параметр + :option:`--auto-file-renaming`. + +15 + Если aria2 не смогла открыть существующий файл. + +16 + Если aria2 не смогла создать новый файл или обрезать существующий файл. + +17 + Если произошла ошибка чтения/записи файла. + +18 + Если aria2 не смогла создать каталог. + +19 + Если не удалось разрешение имен (DNS). + +20 + Если aria2 не смогла проанализировать Metalink-документ. + +21 + Если FTP-команда не удалась. + +22 + Если HTTP-заголовок ответа был испорчен или неожиданным. + +23 + Если произошло слишком много перенаправлений. + +24 + Если HTTP-авторизация не удалась. + +25 + Если aria2 не смогла проанализировать закодированный файл (обычно + .torrent-файл). + +26 + Если файл .torrent был испорчен или потеряна информация, которая необходима + aria2. + +27 + Если Magnet-ссылка была плохой. + +28 + Если был задан плохой/неопознанный параметр или неожиданный аргумент к нему. + +29 + Если удаленный сервер не смог обработать запрос из-за временной перегрузки + или регламентных работ. + +30 + Если aria2 не смогла проанализировать JSON-RPC-запрос. + +.. note:: + + Ошибка, произошедшая в завершенной загрузке, не будет передана как код + завершения. + +ОКРУЖЕНИЕ +--------- +aria2 распознает следующие переменные окружения. + +``http_proxy [http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]`` + Указать прокси-сервер для использования в HTTP. Заменяет значение http-proxy + в конфигурационном файле. Параметр + :option:`--http-proxy` в командной строке заменяет эту переменную. + +``https_proxy [http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]`` + Указать прокси-сервер для использования в HTTPS. Заменяет значение + https-proxy в конфигурационном файле. Параметр + :option:`--https-proxy` в командной строке заменяет эту переменную. + +``ftp_proxy [http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]`` + Указать прокси-сервер для использования в FTP. Заменяет значение ftp-proxy в + конфигурационном файле. Параметр :option:`--ftp-proxy` в + командной строке заменяет эту переменную. + +``all_proxy [http://][ПОЛЬЗОВАТЕЛЬ:ПАРОЛЬ@]ХОСТ[:ПОРТ]`` + Указать прокси-сервер для использования, если не указан конкретный протокол + для прокси. Заменяет значение all-proxy в конфигурационном файле. Параметр + :option:`--all-proxy` в командной строке заменяет эту + переменную. + +.. note:: + + Не смотря на то, что aria2 допускает ``ftp://`` и ``https://`` схемы прокси в URI, + она просто предполагает, что определен ``http://`` и не меняет своего поведения, + основанного на определенной схеме. + +``no_proxy [ДОМЕН,...]`` + Указать, разделенные запятыми, имена хостов, доменов и сетевых адресов с + CIDR-блоком, или без него, для которых прокси использоваться не + будет. Заменяет значение no-proxy в конфигурационном файле. Параметр + :option:`--no-proxy` в командной строке заменяет эту + переменную. + +ФАЙЛЫ +----- +aria2.conf +~~~~~~~~~~ + +По умолчанию, aria2 анализирует ``$HOME/.aria2/aria2.conf`` как +конфигурационный файл. Вы можете указать путь к конфигурационному файлу в +параметре :option:`--conf-path`. Если вы не хотите +использовать конфигурационный файл, используйте параметр +:option:`--no-conf`. + +Конфигурационный файл - это текстовый файл, содержащий один параметр в +строке. В каждой строке, вы можете указать пары имя-значение в формате: +ИМЯ=ЗНАЧЕНИЕ, где имя - это длинный параметр командной строки, без префикса +``--``. Вы можете использовать тот же синтаксис, что и для параметра командной +строки. Строки начинающиеся с ``#`` рассматриваются как комментарии:: + + # sample configuration file for aria2c + listen-port=60000 + dht-listen-port=60000 + seed-ratio=1.0 + max-upload-limit=50K + ftp-pasv=true + + +dht.dat +~~~~~~~~ + +By default, the routing table of IPv4 DHT is saved to the path +``$HOME/.aria2/dht.dat`` and the routing table of IPv6 DHT is saved to +the path ``$HOME/.aria2/dht6.dat``. + +Netrc +~~~~~ + +Поддержка Netrc включена по умолчанию для HTTP(S)/FTP. Для отключения +поддержки netrc, укажите параметр :option:`--no-netrc <-n>`. Ваш файл +.netrc должен иметь соответствующие права (600). + +Если имя машины (machine) начинается с ``.``, то aria2 выполняет доменное +сопоставление вместо точного соответствия. Это расширение aria2. Пример +доменного сопоставления, представьте себе следующие содержимое .netrc:: + + machine .example.org login myid password mypasswd + + +Домен ``aria2.example.org`` сопоставляется с ``.example.org`` и используется +``myid`` и ``mypasswd``. + +Примеры некоторых доменных сопоставлений: домен ``example.net`` не сопоставим +с ``.example.org``. Домен ``example.org`` не сопоставим ``.example.org`` из-за +предшествующей ``.``. Если вы хотите соответствия ``example.org``, то точно +укажите - ``example.org``. + +Контрольный файл +~~~~~~~~~~~~~~~~ + +aria2 использует контрольный файл для отслеживания прогресса +загрузки. Контрольный файл размещается в том же каталоге, что и загружаемый +файл, и имеет имя, как у загружаемого файла с добавлением +``.aria2``. Например, если file.zip загружаемый файл, тогда контрольный файл +будет file.zip.aria2. (Существует исключение для этого именования. При +загрузке торрента с множеством файлов, контрольный файл будет в "корневом +каталоге" с именем торрента и добавлением ``.aria2``. Имя "корневого каталога" +- значение ключа "name" в "info" внутри torrent-файла.) + +Обычно контрольный файл удаляется после завершения загрузки. Если aria2 +решает, что загрузка не может быть возобновлена (например, когда загружается +файл с HTTP-сервера, который не поддерживает возобновление), контрольный +файл не создается. + +Обычно, если вы потеряете контрольный файл, вы не сможете возобновить +загрузку. Но если у вас есть torrent или metalink файлы с контрольными +суммами блоков данных, вы сможете возобновить загрузку без контрольного +файла, указав параметр -V в командной строке aria2c. + +Входной файл +~~~~~~~~~~~~ + +Входной файл может содержать список URI для загрузки aria2. Вы можете +указать несколько URI для одного объекта, разделяя URI, в одной строке, +табуляцией. + +Каждая строка рассматривается, как аргумент командой строки. Следовательно, +на них влияют параметры :option:`--force-sequential <-Z>` и +:option:`--parameterized-uri <-P>`. + +Так как aria2 непосредственно читает URI из входного файла, то они не должны +быть указаны с одинарными(') или двойными(") кавычками. + +Строка, которая начинается с ``#`` обрабатывается как комментарий и +пропускается. + +Кроме того, следующие параметры могут быть определены после каждой строки с +URI. Эти дополнительные строки должны начинаться с пробела(ов). + +.. hlist:: + :columns: 3 + + * :option:`all-proxy <--all-proxy>` + * :option:`all-proxy-passwd <--all-proxy-passwd>` + * :option:`all-proxy-user <--all-proxy-user>` + * :option:`allow-overwrite <--allow-overwrite>` + * :option:`allow-piece-length-change <--allow-piece-length-change>` + * :option:`always-resume <--always-resume>` + * :option:`async-dns <--async-dns>` + * :option:`auto-file-renaming <--auto-file-renaming>` + * :option:`bt-enable-lpd <--bt-enable-lpd>` + * :option:`bt-exclude-tracker <--bt-exclude-tracker>` + * :option:`bt-external-ip <--bt-external-ip>` + * :option:`bt-hash-check-seed <--bt-hash-check-seed>` + * :option:`bt-max-open-files <--bt-max-open-files>` + * :option:`bt-max-peers <--bt-max-peers>` + * :option:`bt-metadata-only <--bt-metadata-only>` + * :option:`bt-min-crypto-level <--bt-min-crypto-level>` + * :option:`bt-prioritize-piece <--bt-prioritize-piece>` + * :option:`bt-request-peer-speed-limit <--bt-request-peer-speed-limit>` + * :option:`bt-require-crypto <--bt-require-crypto>` + * :option:`bt-save-metadata <--bt-save-metadata>` + * :option:`bt-seed-unverified <--bt-seed-unverified>` + * :option:`bt-stop-timeout <--bt-stop-timeout>` + * :option:`bt-tracker <--bt-tracker>` + * :option:`bt-tracker-connect-timeout <--bt-tracker-connect-timeout>` + * :option:`bt-tracker-interval <--bt-tracker-interval>` + * :option:`bt-tracker-timeout <--bt-tracker-timeout>` + * :option:`bt-remove-unselected-file <--bt-remove-unselected-file>` + * :option:`check-integrity <-V>` + * :option:`conditional-get <--conditional-get>` + * :option:`connect-timeout <--connect-timeout>` + * :option:`continue <-c>` + * :option:`dir <-d>` + * :option:`dry-run <--dry-run>` + * :option:`enable-async-dns6 <--enable-async-dns6>` + * :option:`enable-http-keep-alive <--enable-http-keep-alive>` + * :option:`enable-http-pipelining <--enable-http-pipelining>` + * :option:`enable-peer-exchange <--enable-peer-exchange>` + * :option:`file-allocation <--file-allocation>` + * :option:`follow-metalink <--follow-metalink>` + * :option:`follow-torrent <--follow-torrent>` + * :option:`ftp-passwd <--ftp-passwd>` + * :option:`ftp-pasv <-p>` + * :option:`ftp-proxy <--ftp-proxy>` + * :option:`ftp-proxy-passwd <--ftp-proxy-passwd>` + * :option:`ftp-proxy-user <--ftp-proxy-user>` + * :option:`ftp-reuse-connection <--ftp-reuse-connection>` + * :option:`ftp-type <--ftp-type>` + * :option:`ftp-user <--ftp-user>` + * :option:`header <--header>` + * :option:`http-accept-gzip <--http-accept-gzip>` + * :option:`http-auth-challenge <--http-auth-challenge>` + * :option:`http-no-cache <--http-no-cache>` + * :option:`http-passwd <--http-passwd>` + * :option:`http-proxy <--http-proxy>` + * :option:`http-proxy-passwd <--http-proxy-passwd>` + * :option:`http-proxy-user <--http-proxy-user>` + * :option:`http-user <--http-user>` + * :option:`https-proxy <--https-proxy>` + * :option:`https-proxy-passwd <--https-proxy-passwd>` + * :option:`https-proxy-user <--https-proxy-user>` + * :option:`index-out <-O>` + * :option:`lowest-speed-limit <--lowest-speed-limit>` + * :option:`max-connection-per-server <-x>` + * :option:`max-download-limit <--max-download-limit>` + * :option:`max-file-not-found <--max-file-not-found>` + * :option:`max-resume-failure-tries <--max-resume-failure-tries>` + * :option:`max-tries <-m>` + * :option:`max-upload-limit <-u>` + * :option:`metalink-enable-unique-protocol <--metalink-enable-unique-protocol>` + * :option:`metalink-language <--metalink-language>` + * :option:`metalink-location <--metalink-location>` + * :option:`metalink-os <--metalink-os>` + * :option:`metalink-preferred-protocol <--metalink-preferred-protocol>` + * :option:`metalink-version <--metalink-version>` + * :option:`min-split-size <-k>` + * :option:`no-file-allocation-limit <--no-file-allocation-limit>` + * :option:`no-netrc <-n>` + * :option:`no-proxy <--no-proxy>` + * :option:`out <-o>` + * :option:`parameterized-uri <-P>` + * :option:`proxy-method <--proxy-method>` + * :option:`realtime-chunk-checksum <--realtime-chunk-checksum>` + * :option:`referer <--referer>` + * :option:`remote-time <-R>` + * :option:`remove-control-file <--remove-control-file>` + * :option:`reuse-uri <--reuse-uri>` + * :option:`seed-ratio <--seed-ratio>` + * :option:`seed-time <--seed-time>` + * :option:`select-file <--select-file>` + * :option:`split <-s>` + * :option:`timeout <-t>` + * :option:`use-head <--use-head>` + * :option:`user-agent <-U>` + * :option:`retry-wait <--retry-wait>` + * :option:`metalink-base-uri <--metalink-base-uri>` + * :option:`pause <--pause>` + * :option:`stream-piece-selector <--stream-piece-selector>` + * :option:`hash-check-only <--hash-check-only>` + * :option:`checksum <--checksum>` + * :option:`piece-length <--piece-length>` + * :option:`uri-selector <--uri-selector>` + +Эти параметры имеют точно такой же смысл, что параметры командной строки, но +это применимо только к URI, к которым они принадлежат. Обратите внимание, +что параметры во входном файле не должны иметь префикс ``--``. + +Например, такое содержимое uri.txt:: + + http://server/file.iso http://mirror/file.iso + dir=/iso_images + out=file.img + http://foo/bar + + +Если aria2 выполняется с параметрами ``-i uri.txt -d /tmp``, +а загрузка происходит с +\http://server/file.iso и \http://mirror/file.iso, то ``file.iso`` сохранится +как ``/iso_images/file.img``. Файл ``bar`` загрузится с http://foo/bar и +сохранится как ``/tmp/bar``. + +В некоторых случаях, параметр :option:`out <-o>` не имеет никакого +эффекта. Смотрите примечание по ограничениям параметра +:option:`--out <-o>`. + +Профиль функционирования сервера +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Этот раздел описывает формат профиля функционирования сервера. Это открытый +текстовый файл, каждая строка которого имеет несколько пар ИМЯ=ЗНАЧЕНИЕ, +разделенных запятыми. В настоящее время распознаются следующие ИМЕНА: + +``host`` + Хост-имя сервера. Обязательно. + +``protocol`` + Протокол для этого профиля, такие как ftp, http. Обязательно. + +``dl_speed`` + Средняя скорость загрузки, которая наблюдалась при предыдущей загрузке, в + байт/секунду. Обязательно. + +``sc_avg_speed`` + Средняя скорость загрузки, которая наблюдалась при предыдущей загрузке, в + байт/секунду. Это значение обновляется, только если загрузка произведена при + одном соединении и только с использованием + AdaptiveURISelector. Необязательно. + +``mc_avg_speed`` + Средняя скорость загрузки, которая наблюдалась при предыдущей загрузке, в + байт/секунду. Это значение обновляется, только если загрузка произведена при + нескольких соединениях и только с использованием + AdaptiveURISelector. Необязательно. + +``counter`` + Сколько раз использовался сервер. В настоящее время это значение + используется только при AdaptiveURISelector. Необязательно. + +``last_updated`` + Время связи, в GMT, с этим сервером, указывается в секундах, начиная с + 00:00:00 1 Января, 1970, UTC. Обязательно. + +``status`` + ERROR, когда сервер не доступен из-за неисправности или тайм-аута. Иначе - + OK. + +Эти поля должны быть в одной строке. Последовательность полей не имеет +значения. Вы можете размещать пары, отличные от перечисленных выше; они +будут просто игнорироваться. + +Например, следующим образом:: + + host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK + host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR + + +RPC-ИНТЕРФЕЙС +------------- + +aria2 обеспечивает JSON-RPC через HTTP и XML-RPC через HTTP, они в основном +имеют одинаковые функции. aria2 также обеспечивает JSON-RPC через +WebSocket. JSON-RPC через WebSocket использует тот же самый метод сигнатур и +формат ответа как у JSON-RPC через HTTP, но дополнительно имеет сервер, +инициирующий уведомления. Смотрите подробности в разделе +`JSON-RPC через WebSocket`_. + +Путь запроса к JSON-RPC-интерфейсу (для через HTTP и через WebSocket) - +``/jsonrpc``. Путь запроса к XML-RPC-интерфейсу - ``/rpc``. + +WebSocket URI для JSON-RPC через WebSocket является ``ws://HOST:PORT/jsonrpc``. + +Реализованный JSON-RPC основан на спецификации +JSON-RPC 2.0 и поддерживает HTTP POST и +GET (JSONP). Использование WebSocket как транспорта является начальным +расширением aria2. + +JSON-RPC-интерфейс не поддерживает уведомления в HTTP, но RPC-сервер будет +отправлять уведомления в WebSocket. Он также не поддерживает числа с +плавающей точкой. Символы должны быть в кодировке UTF-8. + +В следующем документе о JSON-RPC, описана структура JSON-объекта. + +Терминология +~~~~~~~~~~~~ + +GID + GID (или gid) - это ключ, для управления каждой загрузкой. Каждая загрузка + имеет уникальный GID. В настоящее время GID представлен как целое число, но + обрабатывается как не целое число, т.к. он может быть изменен на другой тип + в будущих версиях. Обратите внимание, что GID существует в локальной сессии + и не сохраняется при завершении работы aria2. + +Методы +~~~~~~ + +Весь код в примерах написан на Python2.7. + + +.. function:: aria2.addUri(uris[, options[, position]]) + + + + + + Этот метод добавляет новый HTTP(S)/FTP/BitTorrent Magnet URI. Параметр + *uris* имеет тип массив, элемент которого имеет тип строка и содержит + URI. Для BitTorrent Magnet URI, *uris* должен содержать только один элемент, + и он должен быть BitTorrent Magnet URI. URI в параметре *uris* должны + указывать на один и тот же файл. Если вы смешивайте другие URI, указывающие + на другой файл, то aria2 не сообщит об этом, но и загрузка может неудачно + завершаться. Параметр *options* имеет тип структура, элементы которой + являются парой имя и значение. Смотрите ниже :ref:`rpc_options` для более подробной информации. Если параметр *position* задан + как целое число, начиная с 0, то новая загрузка будет вставлена на позицию + *position* в очередь ожидания. Если параметр *position* не задан или больше + чем размер очереди, то загрузка будет добавлена в конец очереди. Этот метод + возвращает GID зарегистрированной загрузки. + + **Пример JSON-RPC** + + + Следующий пример добавляет \http://example.org/file в aria2:: + + >>> import urllib2, json + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addUri', + ... 'params':[['http://example.org/file']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":"1"}' + + + **Пример XML-RPC** + + + Следующий пример добавляет \http://example.org/file в aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addUri(['http://example.org/file']) + '1' + + + Следующий пример добавляет два источника и некоторые параметры:: + + >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'], + dict(dir="/tmp")) + '2' + + + Следующий пример добавляет загрузку и вставляет ее перед ожидающими + загрузками:: + + >>> s.aria2.addUri(['http://example.org/file'], {}, 0) + '3' + + + +.. function:: aria2.addTorrent(torrent[, uris[, options[, position]]]) + + + + + + Этот метод добавляет BitTorrent-загрузку путем загрузки .torrent-файла. Если + вы хотите добавить BitTorrent Magnet URI, взамен используйте метод + :func:`aria2.addUri`. Параметр *torrent* имеет тип + base64, с содержанием Base64-кодировки + .в .torrent-файле. Параметр *uris* имеет тип массив, элемент которого имеет тип строка и содержит URI. + Параметр *uris* используется для Web-сидирования. Для однофайловых + торрентов, URI может быть завершенным, который указывает на ресурс, или же + если заканчиваться символом /, тогда будет добавлено имя из + torrent-файла. Для многофайловых торентов, имя и путь в торренте будут + добавлены из URI для каждого файла. Параметр *options* имеет тип структура, + элементы которой являются парой имя и значение. Смотрите ниже + :ref:`rpc_options` для более подробной информации. Если + параметр *position* задан как целое число, начиная с 0, то новая загрузка + будет вставлена на позицию *position* в очередь ожидания. Если параметр + *position* не задан или больше чем размер очереди, то загрузка будет + добавлена в конец очереди. Этот метод возвращает GID зарегистрированной + загрузки. Загруженные данные сохраняются в файл с именем шестнадцатеричной + строки SHA-1-хэша этих данных плюс ".torrent", в каталог указанный в + параметре :option:`--dir <-d>`. Например, имя файла + 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. Если этот файл существует, + то он будет перезаписан. Если файл не может быть успешно сохранен, то + загрузки, добавленные этим методом, не сохраняются при помощи параметра + :option:`--save-session`. + + **Пример JSON-RPC** + + + Следующий пример добавляет локальный файл file.torrent в aria2:: + + >>> import urllib2, json, base64 + >>> torrent = base64.b64encode(open('file.torrent').read()) + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf', + ... 'method':'aria2.addTorrent', 'params':[torrent]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"asdf","jsonrpc":"2.0","result":"6"}' + + + **Пример XML-RPC** + + + Следующий пример добавляет локальный файл file.torrent в aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read())) + '6' + + + +.. function:: aria2.addMetalink(metalink[, options[, position]]) + + + + + + Этот метод добавляет Metalink-загрузку путем загрузки + .metalink-файла. Параметр *metalink* имеет тип base64, с содержанием + Base64-кодировки в .metalink-файле. Параметр *options* имеет тип структура, + элементы которой являются парой имя-значение. Смотрите ниже + :ref:`rpc_options` для более подробной информации. Если + параметр *position* задан как целое число, начиная с 0, то новая загрузка + будет вставлена на позицию *position* в очередь ожидания. Если параметр + *position* не задан или больше чем размер очереди, то загрузка будет + добавлена в конец очереди. Этот метод возвращает GID зарегистрированной + загрузки. Загруженные данные сохраняются в файл с именем шестнадцатеричной + строки SHA-1-хэша этих данных плюс ".metalink", в каталог указанный в + параметре :option:`--dir <-d>`. Например, имя файла + 0a3893293e27ac0490424c06de4d09242215f0a6.metalink. Если этот файл + существует, то он будет перезаписан. Если файл не может быть успешно + сохранен, то загрузки, добавленные этим методом, не сохраняются при помощи + параметра :option:`--save-session`. + + **Пример JSON-RPC** + + + Следующий пример добавляет локальный файл file.meta4 в aria2:: + + >>> import urllib2, json, base64 + >>> metalink = base64.b64encode(open('file.meta4').read()) + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addMetalink', 'params':[metalink]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":["8"]}' + + + **Пример XML-RPC** + + + Следующий пример добавляет локальный файл file.meta4 в aria2:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4').read())) + ['8'] + + + +.. function:: aria2.remove(gid) + + + + + + Этот метод удаляет загрузку, которая обозначена *gid*. Параметр *gid* имеет + тип строка. Если указана загрузка, которая загружается в данный момент, то + сначала она остановится. Статус удаления станет ``"removed"`` (удаленно). Этот + метод возвращает GID удаленной загрузки. + + **Пример JSON-RPC** + + + Следующий пример удаляет загрузку, GID которой "3":: + + >>> import urllib2, json + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.remove', 'params':['3']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> c.read() + '{"id":"qwer","jsonrpc":"2.0","result":"3"}' + + + **Пример XML-RPC** + + + Следующий пример удаляет загрузку, GID которой "3":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.remove('3') + '3' + + + +.. function:: aria2.forceRemove(gid) + + + + + + Этот метод удаляет загрузку, которая обозначена *gid*. Метод действует + подобно :func:`aria2.remove`, за исключением того, что + метод удаляет загрузку без каких-либо действий, которые требует времени, + например связь с BitTorrent-трекером. + + +.. function:: aria2.pause(gid) + + + + + + Этот метод приостанавливает загрузку, которая обозначена *gid*. Параметр + *gid* имеет тип строки. Статус приостановки станет ``"paused"`` + (приостановлено). Если загрузка активна, то загрузка переместится на первую + позицию в очередь ожидания. Пока статус ``"paused"``, загрузка не начнется. Для + смены статуса на ``"waiting"``, используйте метод + :func:`aria2.unpause`. Этот метод возвращает GID приостановленной загрузки. + + +.. function:: aria2.pauseAll() + + + + + + Этот метод эквивалентен по вызову :func:`aria2.pause`, + для каждой активной/ожидающей закачки. Этот метод возвращает ``"OK"``, в случае + успеха. + + +.. function:: aria2.forcePause(pid) + + + + + + Этот метод приостанавливает загрузку, которая обозначена *gid*. Метод + действует подобно :func:`aria2.pause`, за исключением + того, что метод приостанавливает загрузку без каких-либо действий, которые + требует времени, например связь с BitTorrent-трекером. + + +.. function:: aria2.forcePauseAll() + + + + + + Этот метод эквивалентен по вызову + :func:`aria2.forcePause`, для каждой активной/ожидающей закачки. Этот метод + возвращает ``"OK"``, в случае успеха. + + +.. function:: aria2.unpause(gid) + + + + + + Этот метод изменяет статус загрузки, которая обозначена 'gid', с ``"paused"`` на + ``"waiting"``. Это позволяет перезапускать загрузку. Значение ключа *gid* имеет + тип строки. Этот метод возвращает GID, снятой с паузы, загрузки. + + +.. function:: aria2.unpauseAll() + + + + + + Этот метод эквивалентен по вызову + :func:`aria2.unpause`, для каждой активной/ожидающей закачки. Этот метод + возвращает ``"OK"``, в случае успеха. + + +.. function:: aria2.tellStatus(gid[, keys]) + + + + + + Этот метод возвращает состояние загрузки, которая обозначена *gid*. Параметр + *gid* имеет тип строка. Параметр *keys* имеет тип массив строк. Если *keys* + указан, то ответ содержит определенные значения в массиве *keys*. Если + *keys* пустой или не указан, то ответ содержит все значения. Это полезно, + если вы хотите использовать определенные параметры, чтобы исключить + множество пересылок. Например, + ``aria2.tellStatus("1", ["gid", "status"])`` возвратит *gid* и + 'status'. Ответ имеет тип структура и содержит следующие поля. Поле имеет + тип строка. + + ``gid`` + GID этой загрузки. + + ``status`` + ``"active"`` - загружаемая/сидируемая в данный момент. ``"waiting"`` - ожидающая в + очереди; загрузка не началась. ``"paused"`` - приостановленная. ``"error"`` - + остановленная, т.к. произошла ошибка. ``"complete"`` - остановленная и + завершенная загрузка. ``"removed"`` - удаленная пользователем загрузка. + + ``totalLength`` + Общий объем загрузки в байтах. + + ``completedLength`` + Загруженный объем загрузки в байтах. + + ``uploadLength`` + Выгруженный объем загрузки в байтах. + + ``bitfield`` + Шестнадцатеричное представление процесса загрузки. Старший бит соответствует + блоку с индексом 0. Бит устанавливается, если блок доступен и не + устанавливается, если блок отсутствует. Запасные биты в конце + устанавливаются в 0. Если загрузка еще не начался, этот значение не будет + включено в ответ. + + ``downloadSpeed`` + Скорость загрузки в байт/сек. + + ``uploadSpeed`` + Скорость выгрузки в байт/сек. + + ``infoHash`` + Информация о хэше (InfoHash). Только для BitTorrent. + + ``numSeeders`` + Количество сидов, к которым подключен клиент. Только для BitTorrent. + + ``pieceLength`` + Размер блока в байтах. + + ``numPieces`` + Количество блоков. + + ``connections`` + Количество пиров/серверов, к которым подключен клиент. + + ``errorCode`` + Последний код ошибки, которая произошла при загрузке. Значение имеет тип + строки. Коды ошибок определены в разделе `КОДЫ ЗАВЕРШЕНИЯ`_. Это значение доступно только для остановленных/завершенных + загрузок. + + ``followedBy`` + Список с GID, которые сгенерированы в результате запуска этой + загрузки. Например, когда aria2 загружает Metalink-файл, то это генерирует + загрузки, описанные в нем (см. параметр + :option:`--follow-metalink`). Это значение полезно для отслеживания автоматически + сгенерированных загрузок. Если таких загрузок нет, то значение не будет + включено в ответ. + + ``belongsTo`` + GID родительской загрузки. Некоторые загрузки являются частью другой + загрузки. Например, если файл в Metalink содержит BitTorrent-ответ, загрузка + .torrent будет частью этого файла. Если эта загрузка не имеет родительской + загрузки, то значение не будет включено в ответ. + + ``dir`` + Каталог для сохранения файлов. Этот параметр не доступен для остановленных + загрузок. + + ``files`` + Возвращает список файлов. Элемент списка - это структура, такая же, что и в + методе :func:`aria2.getFiles`. + + + ``bittorrent`` + Структура, в которой содержится информация, извлеченная из + .torrent-файла. Только для BitTorrent. Содержит следующие поля. + + ``announceList`` + Список списков URI анонса. Если .torrent-файл содержит анонс, а не + список-анонс, то анонс конвертируется в формат списка-анонса. + + ``comment`` + Комментарий по торренту. Используется comment.utf-8, если доступно. + + ``creationDate`` + Время создания торрента. Значение является целым числом, с начала века, + измеряется в секундах. + + ``mode`` + Файловый режим торрента. Значение одно из двух: 'single' (одиночный) или + 'multi' (множественный). + + ``info`` + Структура, которая содержит данные из раздела Info. Она содержит следующие + поля. + + ``name`` + имя в разделе info. Используется name.utf-8, если доступно. + + **Пример JSON-RPC** + + + Следующий пример получает информацию о загрузке, GID которой "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.tellStatus', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'bitfield': u'0000000000', + u'completedLength': u'901120', + u'connections': u'1', + u'dir': u'/downloads', + u'downloadSpeed': u'15158', + u'files': [{u'index': u'1', + u'length': u'34896138', + u'completedLength': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}], + u'gid': u'1', + u'numPieces': u'34', + u'pieceLength': u'1048576', + u'status': u'active', + u'totalLength': u'34896138', + u'uploadLength': u'0', + u'uploadSpeed': u'0'}} + + + Следующий пример получает информацию об определенных полях, который вас + интересуют:: + + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.tellStatus', + ... 'params':['1', ['gid', + ... 'totalLength', + ... 'completedLength']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'completedLength': u'5701632', + u'gid': u'1', + u'totalLength': u'34896138'}} + + + **Пример XML-RPC** + + + Следующий пример получает информацию о загрузке, GID которой "1":: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.tellStatus('1') + >>> pprint(r) + {'bitfield': 'ffff80', + 'completedLength': '34896138', + 'connections': '0', + 'dir': '/downloads', + 'downloadSpeed': '0', + 'errorCode': '0', + 'files': [{'index': '1', + 'length': '34896138', + 'completedLength': '34896138', + 'path': '/downloads/file', + 'selected': 'true', + 'uris': [{'status': 'used', + 'uri': 'http://example.org/file'}]}], + 'gid': '1', + 'numPieces': '17', + 'pieceLength': '2097152', + 'status': 'complete', + 'totalLength': '34896138', + 'uploadLength': '0', + 'uploadSpeed': '0'} + + + Следующий пример получает информацию об определенных полях, который вас + интересуют:: + + >>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength']) + >>> pprint(r) + {'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'} + + + +.. function:: aria2.getUris(gid) + + + + + + Этот метод возвращает URI, используемые в загрузке, которая обозначена + *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип массив, а элемент - + тип структура и содержит следующие поля. Поле имеет тип строка. + + ``uri`` + URI + + ``status`` + 'used', если URI уже использован. 'waiting', если URI ожидает в очереди. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getUris', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'status': u'used', + u'uri': u'http://example.org/file'}]} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getUris('1') + >>> pprint(r) + [{'status': 'used', 'uri': 'http://example.org/file'}] + + + +.. function:: aria2.getFiles(gid) + + + + + + Этот метод возвращает список файлов загрузки, которая обозначена + *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип массив, а элемент - + тип структура и содержит следующие поля. Поле имеет тип строка. + + ``index`` + Индекс файла. Начинается с 1. Последовательность файлов такая же, что и в + многофайловом торренте. + + ``path`` + Путь к файлу. + + ``length`` + Размер файла в байта. + + ``completedLength`` + Загруженный объем файла в байтах. Обратите внимание, что вполне возможно, + что сумма completedLength меньше чем в методе + :func:`aria2.tellStatus`. Это потому, что completedLength в + :func:`aria2.getFiles` считаются только завершенные + блоки. С другой стороны, completedLength в + :func:`aria2.tellStatus` учитывает частично завершенные блоки. + + ``selected`` + ``"true"`` - если этот файл выбран параметром + :option:`--select-file`. Если параметр + :option:`--select-file` не указан или это однофайловый торрент или загрузка не + торрент, то это значение всегда будет ``"true"``. Иначе ``"false"``. + + ``uris`` + Возвращает список URI для этого файла. Элемент списка такая же структура, + что используется в методе :func:`aria2.getUris`. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getFiles', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'index': u'1', + u'length': u'34896138', + u'completedLength': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}]} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getFiles('1') + >>> pprint(r) + [{'index': '1', + 'length': '34896138', + 'completedLength': '34896138', + 'path': '/downloads/file', + 'selected': 'true', + 'uris': [{'status': 'used', + 'uri': 'http://example.org/file'}]}] + + + +.. function:: aria2.getPeers(gid) + + + + + + Этот метод возвращает список пиров загрузки, которая обозначена + *gid*. Параметр *gid* имеет тип строка. Этот метод только для + BitTorrent. Ответ имеет тип массив, а элемент - тип структура и содержит + следующие поля. Поле имеет тип строка. + + ``peerId`` + Закодированное ID пира. + + ``ip`` + IP-адрес пира. + + ``port`` + Номер порта пира. + + ``bitfield`` + Шестнадцатеричное представление процесса загрузки. Старший бит соответствует + блоку с индексом 0. Бит устанавливается, если блок доступен и не + устанавливается, если блок отсутствует. Запасные биты в конце + устанавливаются в 0. + + ``amChoking`` + ``"true"`` - если этот клиент блокирует пира. Иначе ``"false"``. + + ``peerChoking`` + ``"true"`` - если пир блокирует этого клиента. Иначе ``"false"``. + + ``downloadSpeed`` + Скорость загрузки (байт/сек), с которой этот клиент получает от пира. + + ``uploadSpeed`` + Скорость выгрузки (байт/сек), с которой этот клиент отдает пиру. + + ``seeder`` + ``"true"`` - если этот клиент является сидом. Иначе ``"false"``. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getPeers', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'amChoking': u'true', + u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff', + u'downloadSpeed': u'10602', + u'ip': u'10.0.0.9', + u'peerChoking': u'false', + u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + u'port': u'6881', + u'seeder': u'true', + u'uploadSpeed': u'0'}, + {u'amChoking': u'false', + u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + u'downloadSpeed': u'8654', + u'ip': u'10.0.0.30', + u'peerChoking': u'false', + u'peerId': u'bittorrent client758', + u'port': u'37842', + u'seeder': u'false', + u'uploadSpeed': u'6890'}]} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getPeers('1') + >>> pprint(r) + [{'amChoking': 'true', + 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff', + 'downloadSpeed': '10602', + 'ip': '10.0.0.9', + 'peerChoking': 'false', + 'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + 'port': '6881', + 'seeder': 'true', + 'uploadSpeed': '0'}, + {'amChoking': 'false', + 'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + 'downloadSpeed': '8654', + 'ip': '10.0.0.30', + 'peerChoking': 'false', + 'peerId': 'bittorrent client758', + 'port': '37842', + 'seeder': 'false, + 'uploadSpeed': '6890'}] + + + +.. function:: aria2.getServers(gid) + + + + + + Этот метод возвращает текущие подключенные HTTP(S)/FTP-серверы загрузки, + которая обозначена *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип + массив, а элемент - тип структура и содержит следующие поля. Поле имеет тип + строка. + + ``index`` + Индекс файла. Начинается с 1. Последовательность файлов такая же, что и в + многофайловом торренте. + + ``servers`` + Список структур, которые содержат следующие поля. + + ``uri`` + Первоначально добавленный URI. + + ``currentUri`` + Это URI в настоящее время используется для загрузки. Если происходит + перенаправление, currentUri и uri могут отличаться. + + ``downloadSpeed`` + Скорость загрузки (байт/сек) + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getServers', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': [{u'index': u'1', + u'servers': [{u'currentUri': u'http://example.org/file', + u'downloadSpeed': u'10467', + u'uri': u'http://example.org/file'}]}]} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getServers('1') + >>> pprint(r) + [{'index': '1', + 'servers': [{'currentUri': 'http://example.org/dl/file', + 'downloadSpeed': '20285', + 'uri': 'http://example.org/file'}]}] + + + +.. function:: aria2.tellActive([keys]) + + + + + + Этот метод возвращает список активных загрузок. Ответ имеет тип массив и его + элемент такая же структура, которая возвращается методом + :func:`aria2.tellStatus`. За разъяснениями о + параметре 'keys', обратитесь к методу + :func:`aria2.tellStatus`. + + +.. function:: aria2.tellWaiting(offset, num, [keys]) + + + + + + Этот метод возвращает список ожидающих загрузок, включая приостановленные + загрузки. *offset* имеет целочисленный тип и указывает смещение, начиная от + ожидающей загрузки. *num* имеет целочисленный тип и указывает число + возвращаемых загрузок. За разъяснениями о параметре 'keys', обратитесь к + методу :func:`aria2.tellStatus`. + + Если смещение положительное целое число, то этот метод возвращает загрузки в + диапазоне [*offset*, *offset*+*num*). + + *offset* может быть отрицательным целым числом. *offset* == -1 указывает на + последнею загрузку, которая ожидает в очереди, а *offset* == -2 указывает на + загрузку перед последней, и так далее. Загрузки в ответе находятся в + обратном порядке. + + Например, допустим, что есть три загрузки "A","B" и "C", в этом порядке, + которые ожидают. aria2.tellWaiting(0, 1) возвратит + ["A"]. aria2.tellWaiting(1, 2) возвратит ["B", "C"]. aria2.tellWaiting(-1, + 2) возвратит ["C", "B"]. + + Ответ имеет тип массив и его элемент такая же структура, которая + возвращается методом :func:`aria2.tellStatus`. + + +.. function:: aria2.tellStopped(offset, num, [keys]) + + + + + + Этот метод возвращает список остановленных загрузок. *offset* имеет + целочисленный тип и указывает смещение, начиная с самой старой + загрузки. *num* имеет целочисленный тип и указывает число возвращаемых + загрузок. За разъяснениями о параметре 'keys', обратитесь к методу + :func:`aria2.tellStatus`. + + *offset* и *num* имеют такую же семантику, как и в методе + :func:`aria2.tellWaiting`. + + Ответ имеет тип массив и его элемент такая же структура, которая + возвращается методом :func:`aria2.tellStatus`. + + +.. function:: aria2.changePosition(gid, pos, how) + + + + + + Этот метод меняет позицию загрузки, которая обозначена *gid*. *pos* имеет + целочисленный тип. *how* имеет тип строка. Если *how* - ``"POS_SET"``, то это + переместит загрузку на позицию, относительно начала очереди. Если *how* - + ``"POS_CUR"``, это переместит загрузку на позицию, относительно текущей + позиции. Если *how* - ``"POS_END"``, это переместит загрузку на позицию, + относительно конца очереди. Если целевая позиция меньше чем 0 или за + пределами конца очереди, это переместит загрузку в начало или конец очереди + соответственно. Ответ имеет целочисленный тип и является целевой позицией. + + Например, если GID#1 размещается на позиции 3, ``aria2.changePosition('1', -1, 'POS_CUR')`` изменит его позицию на 2. Дополнительно ``aria2.changePosition('1', 0, 'POS_SET')`` изменит его позицию на 0 (начало очереди). + + **Пример JSON-RPC** + + + Следующий пример перемещает загрузку, GID которой "3", в начало очереди + ожидания:: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changePosition', + ... 'params':['3', 0, 'POS_SET']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0} + + + **Пример XML-RPC** + + + Следующий пример перемещает загрузку, GID которой "3", в начало очереди + ожидания:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changePosition('3', 0, 'POS_SET') + 0 + + + +.. function:: aria2.changeUri(gid, fileIndex, delUris, addUris[, position]) + + + + + + Этот метод удаляет URI в *delUris* из загрузки и добавляет URI в *addUris* к + загрузке, которая обозначена *gid*. *delUris* и *addUris* являются списком + строк. Загрузка может содержать несколько файлов и URI прилагаются к каждому + файлу. *fileIndex* используется, чтобы выбрать файл для удаления/подключения + заданных URI. *fileIndex* начинается с 1. *position* используется для + указания, куда будут вставлены URI в существующем списке ожидающих + URI. *position* начинается с 0. Когда *position* пропущено, URI добавляются + в конец списка. Этот метод сначала выполняет удаление, а потом + добавление. *position* это позиция после URI, которые будут удалены, а не + позиция, когда метод вызывается. При удалении URI, если одинаковые URI + существуют в загрузке, только один из них будет удален, для каждого URI в + *delUris*. Другими словами, есть три URI ``http://example.org/aria2`` и вы + хотите удалить их все, вы должны указать (по крайней мере) 3 + ``http://example.org/aria2`` в *delUris*. Этот метод возвращает список, + который содержит 2 целых числа. Первое - количество удаленных URI. Второе - + количество добавленных URI. + + **Пример JSON-RPC** + + + Следующий пример добавляет 1 URI \http://example.org/file к файлу с индексом + "1", принадлежащий загрузке, GID которой "2":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changeUri', + ... 'params':['2', 1, [], ['http://example.org/file']]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]} + + + **Пример XML-RPC** + + + Следующий пример добавляет 1 URI \http://example.org/file к файлу с индексом + "1", принадлежащий загрузке, GID которой "2":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changeUri('2', 1, [], ['http://example.org/file']) + [0, 1] + + + +.. function:: aria2.getOption(gid) + + + + + + Этот метод возвращает параметры загрузки, которая обозначена *gid*. Ответ + имеет тип структура. Ее поля - это название параметра. Поле имеет тип + строка. Обратите внимание, что этот метод не возвращает параметры, которые + не имеют значение по умолчанию и не были заданы параметрами командной + строки, конфигурационными файлами или RPC-методами. + + **Пример JSON-RPC** + + + Следующий пример получает параметры загрузки, GID которой "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getOption', 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'allow-overwrite': u'false', + u'allow-piece-length-change': u'false', + u'always-resume': u'true', + u'async-dns': u'true', + ... + + + **Пример XML-RPC** + + + Следующий пример получает параметры загрузки, GID которой "1":: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getOption('1') + >>> pprint(r) + {'allow-overwrite': 'false', + 'allow-piece-length-change': 'false', + 'always-resume': 'true', + 'async-dns': 'true', + .... + + + +.. function:: aria2.changeOption(gid, options) + + + + + + Этот метод изменяет динамически параметры загрузки, которая обозначена + *gid*. *gid* имеет тип строка. *options* имеет тип структура. Доступны + следующие параметры для активных загрузок: + + * :option:`bt-max-peers <--bt-max-peers>` + * :option:`bt-request-peer-speed-limit <--bt-request-peer-speed-limit>` + * :option:`bt-remove-unselected-file <--bt-remove-unselected-file>` + * :option:`max-download-limit <--max-download-limit>` + * :option:`max-upload-limit <-u>` + + Для ожидающих или приостановленных загрузок, в дополнение к выше + перечисленным параметрам, доступны параметры, перечисленные в подразделе + `Входной файл`_, исключая следующие параметры: + :option:`dry-run <--dry-run>`, + :option:`metalink-base-uri <--metalink-base-uri>`, + :option:`parameterized-uri <-P>`, :option:`pause <--pause>` и + :option:`piece-length <--piece-length>`. Этот метод возвращает ``"OK"``, в + случае успеха. + + **Пример JSON-RPC** + + + Следующий пример устанавливает параметр + :option:`max-download-limit <--max-download-limit>` в ``"20K"`` для загрузки, GID которой "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.changeOption', + ... 'params':['1', {'max-download-limit':'10K'}]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} + + + **Пример XML-RPC** + + + Следующий пример устанавливает параметр + :option:`max-download-limit <--max-download-limit>` в ``"20K"`` для загрузки, GID которой "1":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.changeOption('1', {'max-download-limit':'20K'}) + 'OK' + + + +.. function:: aria2.getGlobalOption() + + + + + + Этот метод возвращает глобальные параметры. Ответ имеет тип структура. Ее + поля - это название параметра. Поле имеет тип строка. Обратите внимание, что + этот метод не возвращает параметры, которые не имеют значение по умолчанию и + не были заданы параметрами командной строки, конфигурационными файлами или + RPC-методами. Так как глобальные параметры используются в качестве шаблона + для вновь добавляемой загрузки, ответ содержит поля возвращаемые методом + :func:`aria2.getOption`. + + +.. function:: aria2.changeGlobalOption(options) + + + + + + Этот метод изменяет динамически глобальные параметры. *options* имеет тип + структура. Доступны следующие параметры: + + * :option:`download-result <--download-result>` + * :option:`log <-l>` + * :option:`log-level <--log-level>` + * :option:`max-concurrent-downloads <-j>` + * :option:`max-download-result <--max-download-result>` + * :option:`max-overall-download-limit <--max-overall-download-limit>` + * :option:`max-overall-upload-limit <--max-overall-upload-limit>` + * :option:`save-cookies <--save-cookies>` + * :option:`save-session <--save-session>` + * :option:`server-stat-of <--server-stat-of>` + + В дополнение к ним, параметры перечисленные в подразделе `Входной файл`_, исключая следующие параметры: + :option:`checksum <--checksum>`, :option:`index-out <-O>`, + :option:`out <-o>`, :option:`pause <--pause>` и + :option:`select-file <--select-file>`. + + Используя параметр :option:`log <-l>`, вы можете динамически + начинать вести журнал событий или изменять файл журнала событий. Чтобы + остановить ведение журнала событий, задайте пустую строку ("") в качестве + значения параметра. Обратите внимание, что файл журнала событий всегда + открыт в режиме добавления. Этот метод возвращает ``"OK"``, в случае успеха. + + +.. function:: aria2.getGlobalStat() + + + + + + Этот метод возвращает глобальную статистику по скорости загрузки и скорости + отдачи. Ответ имеет тип структура и содержит следующие поля. Поле имеет тип + строка. + + ``downloadSpeed`` + Общая скорость загрузки (байт/сек). + + ``uploadSpeed`` + Общая скорость отдачи (байт/сек). + + ``numActive`` + Количество активных загрузок. + + ``numWaiting`` + Количество ожидающих загрузок. + + ``numStopped`` + Количество остановленных загрузок. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getGlobalStat'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'downloadSpeed': u'21846', + u'numActive': u'2', + u'numStopped': u'0', + u'numWaiting': u'0', + u'uploadSpeed': u'0'}} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getGlobalStat() + >>> pprint(r) + {'downloadSpeed': '23136', + 'numActive': '2', + 'numStopped': '0', + 'numWaiting': '0', + 'uploadSpeed': '0'} + + + +.. function:: aria2.purgeDownloadResult() + + + + + + Этот метод очищает, для освобождения памяти, завершенные/ошибка/удаленные + загрузки. Метод возвращает ``"OK"``. + + +.. function:: aria2.removeDownloadResult(gid) + + + + + + Этот метод удаляет из памяти завершенную/ошибка/удаленную загрузку, которая + обозначена *gid*. Метод возвращает ``"OK"``, в случае успеха. + + **Пример JSON-RPC** + + + Следующий пример удаляет результат загрузки, GID которой "1":: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.removeDownloadResult', + ... 'params':['1']}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} + + + **Пример XML-RPC** + + + Следующий пример удаляет результат загрузки, GID которой "1":: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.removeDownloadResult('1') + 'OK' + + + +.. function:: aria2.getVersion() + + + + + + Этот метод возвращает версию программы и список включенных + возможностей. Ответ имеет тип структура и содержит следующие поля. + + ``version`` + Номер версии программы в строке. + + ``enabledFeatures`` + Список включенных возможностей. Каждое имя возможности имеет тип строка. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getVersion'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'enabledFeatures': [u'Async DNS', + u'BitTorrent', + u'Firefox3 Cookie', + u'GZip', + u'HTTPS', + u'Message Digest', + u'Metalink', + u'XML-RPC'], + u'version': u'1.11.0'}} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> from pprint import pprint + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> r = s.aria2.getVersion() + >>> pprint(r) + {'enabledFeatures': ['Async DNS', + 'BitTorrent', + 'Firefox3 Cookie', + 'GZip', + 'HTTPS', + 'Message Digest', + 'Metalink', + 'XML-RPC'], + 'version': '1.11.0'} + + + +.. function:: aria2.getSessionInfo() + + + + + + Этот метод возвращает информацию о сессии. Ответ имеет тип структура и + содержит следующие поля. + + ``sessionId`` + ID сессии, которое генерируется каждый раз, при запуске aria2. + + **Пример JSON-RPC** + :: + + >>> import urllib2, json + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.getSessionInfo'}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', + u'jsonrpc': u'2.0', + u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}} + + + **Пример XML-RPC** + :: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> s.aria2.getSessionInfo() + {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'} + + + +.. function:: aria2.shutdown() + + + + + + Этот метод закрывает aria2. Метод возвращает ``"OK"``. + + +.. function:: aria2.forceShutdown() + + + + + + Этот метод закрывает aria2. Метод действует подобно + :func:`aria2.shutdown`, за исключением того, что + метод выполняется без каких-либо действий, которые требует времени, связь с + BitTorrent-трекером пропускается. Метод возвращает ``"OK"``. + + +.. function:: system.multicall(methods) + + + + + + Этот метод объединяет несколько вызовов методов в один запрос. *methods* + имеет тип массив, а элемент является структурой. Структура содержит два + поля: ``methodName`` и ``params``. ``methodName`` - это имя вызываемого метода, а + ``params`` - содержит параметры к методу. Метод возвращает массив + ответов. Элемент массива будет одним из двух: массивом из одного элемента, + который содержит возвращаемое значение, для каждого вызываемого метода или + структурой с ошибками в полях, если вызов объединенного метода завершился + неудачно. + + **Пример JSON-RPC** + + + В следующем примере мы добавляем 2 загрузки. Первая - + \http://example.org/file и вторая - один file.torrent:: + + >>> import urllib2, json, base64 + >>> from pprint import pprint + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'system.multicall', + ... 'params':[[{'methodName':'aria2.addUri', + ... 'params':[['http://example.org']]}, + ... {'methodName':'aria2.addTorrent', + ... 'params':[base64.b64encode(open('file.torrent').read())]}]]}) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'1'], [u'2']]} + + + JSON-RPC также поддерживает пакетный запрос, который описывается в + спецификации JSON-RPC 2.0:: + + >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer', + ... 'method':'aria2.addUri', + ... 'params':[['http://example.org']]}, + ... {'jsonrpc':'2.0', 'id':'asdf', + ... 'method':'aria2.addTorrent', + ... 'params':[base64.b64encode(open('file.torrent').read())]}]) + >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) + >>> pprint(json.loads(c.read())) + [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'1'}, + {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'2'}] + + + **Пример XML-RPC** + + + В следующем примере мы добавляем 2 загрузки. Первая - + \http://example.org/file и вторая - один file.torrent:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> mc = xmlrpclib.MultiCall(s) + >>> mc.aria2.addUri(['http://example.org/file']) + >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read())) + >>> r = mc() + >>> tuple(r) + ('2', '3') + + +Обработка ошибок +~~~~~~~~~~~~~~~~ + +В JSON-RPC, aria2 возвращает JSON-объект, который содержит код ошибки в коде +и сообщение об ошибке в сообщении. + +В XML-RPC, aria2 возвращает faultCode=1 и сообщение об ошибке в faultString. + +.. _rpc_options: + +Параметры +~~~~~~~~~ + +Такие же параметры, что доступны для +:option:`--input-file <-i>`. Смотрите подраздел `Входной файл`_ для полного +списка параметров. + +В структуре, имя элемента - это имя параметра (без ``--``), а значение +элемента - аргумент в виде строки. + +Пример JSON-RPC +^^^^^^^^^^^^^^^ +:: + + {'split':'1', 'http-proxy':'http://proxy/'} + + +Пример XML-RPC +^^^^^^^^^^^^^^ +.. code-block:: xml + + + + split + 1 + + + http-proxy + http://proxy/ + + + + +Параметры :option:`header <--header>` и :option:`index-out <-O>` +допускают нескольких определений в +командной строке. Поскольку имя должно быть уникальным в структуре +(многие реализации библиотеки XML-RPC использует хэш или словарь +для структуры), одной строки не достаточно. Для преодоления этой +ситуации, они могут взять массив в качестве значения, а также строку. + +Пример JSON-RPC +^^^^^^^^^^^^^^^ +:: + + {'header':['Accept-Language: ja', 'Accept-Charset: utf-8']} + + +Пример XML-RPC +^^^^^^^^^^^^^^ +.. code-block:: xml + + + + header + + + + Accept-Language: ja + Accept-Charset: utf-8 + + + + + + + +Следующий пример добавляет загрузку с двумя параметрами: dir и +header. Параметр header имеет 2 значения, поэтому используется список:: + + >>> import xmlrpclib + >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') + >>> opts = dict(dir='/tmp', + ... header=['Accept-Language: ja', + ... 'Accept-Charset: utf-8']) + >>> s.aria2.addUri(['http://example.org/file'], opts) + '1' + + +JSON-RPC используя HTTP GET +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +JSON-RPC-интерфейс также поддерживает запрос через HTTP GET. Схема +кодирования в GET параметров основанных на +JSON-RPC +через HTTP Спецификация [2008-1-15(RC1)]. Кодирование параметров через GET +следующие:: + + /jsonrpc?method=METHOD_NAME&id=ID¶ms=BASE64_ENCODED_PARAMS + + +``method`` и ``id`` всегда обрабатывается как JSON-строка и они должны быть в +кодировке UTF-8. + +Например, закодированная строка aria2.tellStatus('3') с id='foo' выглядит +так:: + + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D + + +Параметр ``params`` - это JSON-массив в Base64-кодировке, который обычно +появляется в атрибуте ``params`` в JSON-RPC-запросе объекта. В примере выше, +params - ['3'], следовательно:: + + ['3'] --(Base64)--> WyIzIl0= --(Percent Encode)--> WyIzIl0%3D + + +JSON-RPC-интерфейс поддерживает JSONP. Вы можете определить функцию +обратного вызова в параметре 'jsoncallback':: + + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D&jsoncallback=cb + + +Для пакетного запроса, параметры ``method`` и ``id`` не должны быть +указаны. Полный запрос должен быть определен в параметре ``params``. Например, +пакетный запрос:: + + [{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'}, + {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}] + + +должен кодироваться так:: + + /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D + + +JSON-RPC через WebSocket +~~~~~~~~~~~~~~~~~~~~~~~~ + +JSON-RPC через WebSocket использует тот же самый метод сигнатур и формат +ответа как у JSON-RPC через HTTP. Поддерживаемый WebSocket, версия 13, +детально описан в :rfc:`6455`. + +Для отправки RPC-запроса на RPC-сервер, надо отправлять преобразованную в +последовательную форму JSON-строку в текстовом фрейме. Ответ от RPC-сервера +также доставляется в текстовом фрейме. + +RPC-сервер отправит уведомление клиенту. Уведомление является +однонаправленным, поэтому клиент, который получил уведомление, не должен +отвечать на него. Метод сигнатуры уведомления такой же, как нормальный метод +запроса, но отсутствует идентификатор ключа. Значение, связанное с ключом +params, является данными, которые переносит это уведомление. Формат этого +значения варьируется в зависимости от метода уведомления. Определены +следующие методы уведомления. + + +.. function:: aria2.onDownloadStart(event) + + + Это уведомление будет оправлено, если загрузка запущена. Параметр *event* + имеет тип структура и содержит следующие поля. Поле имеет тип строка. + + ``gid`` + GID загрузки. + + +.. function:: aria2.onDownloadPause(event) + + + Это уведомление будет оправлено, если загрузка приостановлена. *event* - + такая же структура, как параметр *event* в методе + :func:`aria2.onDownloadStart`. + + +.. function:: aria2.onDownloadStop(event) + + + Это уведомление будет оправлено, если загрузка остановлена + пользователем. *event* - такая же структура, как параметр *event* в методе + :func:`aria2.onDownloadStart`. + + +.. function:: aria2.onDownloadComplete(event) + + + Это уведомление будет оправлено, если загрузка завершена. В + BitTorrent-загрузках, это уведомление отправляется, когда загрузка завершена + и сидирование окончено. *event* - такая же структура, как параметр *event* в + методе :func:`aria2.onDownloadStart`. + + +.. function:: aria2.onDownloadError(event) + + + Это уведомление будет оправлено, если загрузка остановлена из-за + ошибки. *event* - такая же структура, как параметр *event* в методе + :func:`aria2.onDownloadStart`. + + +.. function:: aria2.onBtDownloadComplete(event) + + + Это уведомление будет оправлено, если загрузка в BitTorrent завершена (но + сидирование может быть не окончено). *event* - такая же структура, как + параметр *event* в методе + :func:`aria2.onDownloadStart`. + +Пример кода XML-RPC-клиента +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Следующий Ruby-скрипт добавляет ``http://localhost/aria2.tar.bz2``, с +параметром :option:`--dir=/downloads, <-d>` в aria2c, которая +работает на localhost и отображает ответ: + +.. code-block:: ruby + + #!/usr/bin/env ruby + + require 'xmlrpc/client' + require 'pp' + + client=XMLRPC::Client.new2("http://localhost:6800/rpc") + + options={ "dir" => "/downloads" } + result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options) + + pp result + + +Если вы любитель Python, то можете использовать xmlrpclib(для Python3.x, +используйте взамен xmlrpc.client) для взаимодействия с aria2:: + + import xmlrpclib + from pprint import pprint + + s = xmlrpclib.ServerProxy("http://localhost:6800/rpc") + r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"}) + pprint(r) + + +ПРИМЕРЫ +------- + +Загрузка по HTTP/FTP +~~~~~~~~~~~~~~~~~~~~ +Загрузка файла +^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host/file.zip" + + +.. note:: + + Для остановки загрузки, нажмите :kbd:`Ctrl-C`. Вы можете возобновить передачу, + запустив aria2c с теми же аргументами в том же каталоге. Вы можете изменить + URI, если они указывают на тот же самый файл. + +Загрузка файла с 2-ух разных HTTP-серверов +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host/file.zip" "http://mirror/file.zip" + + +Загрузка файла с одно хоста, используя 2 соединения +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -x2 -k1M "http://host/file.zip" + + +Загрузка файла с HTTP- и FTP-серверов +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "http://host1/file.zip" "ftp://host2/file.zip" + + +Одновременная загрузка файлов, перечисленных в текстовом файле +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -ifiles.txt -j2 + +.. note:: + + Параметр -j указывает количество параллельных загрузок. + +Использование прокси-сервера +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Для HTTP: + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" "http://host/file" + + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file" + + +Для FTP: + +.. code-block:: console + + $ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file" + + +.. note:: + + Смотрите для подробностей :option:`--http-proxy`, + :option:`--https-proxy`, + :option:`--ftp-proxy`, :option:`--all-proxy` и + :option:`--no-proxy`. Вы можете указать прокси в + переменных окружения. Смотрите раздел `ОКРУЖЕНИЕ`_. + +Прокси-сервер с авторизацией +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file" + + +.. code-block:: console + + $ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file" + + +Загрузка Metalink +~~~~~~~~~~~~~~~~~ +Загрузка файлов с удаленного Metalink +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --follow-metalink=mem "http://host/file.metalink" + + +Загрузка, используя локальный metalink-файл +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -p --lowest-speed-limit=4000 file.metalink + +.. note:: + + Для остановки загрузки, нажмите :kbd:`Ctrl-C`. Вы можете возобновить передачу, + запустив aria2c с теми же аргументами в том же каталоге. + +Загрузка нескольких локальных metalink-файлов +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j2 file1.metalink file2.metalink + + +Загрузка только выбранных файлов, используя индекс +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --select-file=1-4,8 file.metalink + +.. note:: + + Индекс выводится на консоль при использовании параметра -S. + +Загрузка файла, используя локальный .metalink-файл с пользовательскими настройками +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink + + +Загрузка BitTorrent +~~~~~~~~~~~~~~~~~~~ +Загрузка файлов из удаленного BitTorrent-файла +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --follow-torrent=mem "http://host/file.torrent" + + +Загрузка, используя локальный torrent-файл +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-upload-limit=40K file.torrent + +.. note:: + + --max-upload-limit определяет максимальную скорость отдачи. + +.. note:: + + Для остановки загрузки, нажмите :kbd:`Ctrl-C`. Вы можете возобновить передачу, + запустив aria2c с теми же аргументами в том же каталоге. + +Загрузка, используя BitTorrent Magnet URI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2" + + +.. note:: + + Не забывайте заключать BitTorrent Magnet URI, в которой есть символ ``&``, в + одиночные(``'``) или двойные(``"``) кавычки. + +Загрузка 2-х торрентов +^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j2 file1.torrent file2.torrent + + +Загрузка файла, используя торрент и HTTP/FTP-сервер +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file" + +.. note:: + + Загрузка многофайлового торрента через HTTP/FTP не поддерживается. + +Загрузка только выбранных файлов, используя индекс (обычно называют "выборочная загрузка") +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --select-file=1-4,8 file.torrent + +.. note:: + + Индекс выводится на консоль при использовании параметра -S. + +Указание имени выходного файла +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Для указания выходного имени файла в BitTorrent-загрузках, вам нужно узнать +индекс файла в torrent-файле, используя параметр +:option:`--show-files <-S>`. Например, результат выглядит следующим образом:: + + idx|path/length + ===+====================== + 1|dist/base-2.6.18.iso + |99.9MiB + ---+---------------------- + 2|dist/driver-2.6.18.iso + |169.0MiB + ---+---------------------- + + +Сохраняет 'dist/base-2.6.18.iso' в '/tmp/mydir/base.iso' и +'dist/driver-2.6.18.iso' в '/tmp/dir/driver.iso', при использовании +следующей команды: + +.. code-block:: console + + $ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent + + +Изменение прослушиваемого порта для входящих соединений от пиров +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --listen-port=7000-7001,8000 file.torrent + +.. note:: + + Т.к. aria2 не настраивает брандмауэр или маршрутизатор для перенаправления + портов, вам решать, как это сделать вручную. + +Указать условие остановки программы после завершения загрузки торрента +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent + + +.. note:: + + В приведенном выше примере, программа завершается через 120 минут после + завершения загрузки или при достижении рейтинга сидирования 1.0. + +Регулировка скорости отдачи +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-upload-limit=100K file.torrent + + +Включить IPv4 DHT +^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --enable-dht --dht-listen-port=6881 file.torrent + +.. note:: + + DHT использует udp-порт. Так как aria2 не настраивает брандмауэр или + маршрутизатор для перенаправления портов, вам решать как это сделать + вручную. + +Включить IPv6 DHT +^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --enable-dht6 --dht-listen-port=6881 + --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR --enable-async-dns6 + +.. note:: + + Если aria2c не собрана с c-ares, то :option:`--enable-async-dns6` + не нужен. aria2 разделяет один и тот же порт между IPv4 и IPv6 DHT. + +Добавить и удалить URI трекера +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Удалить все URI анонса трекеров, описанных в file.torrent и +взамен использовать ``http://tracker1/announce`` и ``http://tracker2/announce``: + +.. code-block:: console + + $ aria2c --bt-exclude-tracker="*" + --bt-tracker="http://tracker1/announce,http://tracker2/announce" + file.torrent + + +Больше расширенных возможностей для HTTP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Загрузить куки +^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --load-cookies=cookies.txt "http://host/file.zip" + +.. note:: + + Вы можете использовать без изменения cookie-файл Firefox/Mozilla/Chromium. + +Возобновление загрузки, которая начата в браузере или другой программе +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -c -s2 "http://host/partiallydownloadedfile.zip" + + +Клиентский сертификат авторизации для SSL/TLS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file + +.. note:: + + Указанный в :option:`--private-key` файл должен быть + расшифрован. Режим работы с исходно зашифрованным закрытым ключом не + определен. + +Проверить узел при SSL/TLS, используя исходные CA-сертификаты +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file + + +И еще больше расширенных возможностей +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Регулировка скорости загрузки +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --max-download-limit=100K file.metalink + + +Исправить поврежденную загрузку +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -V file.metalink + +.. note:: + + При использовании BitTorrent или Metalink с контрольными суммами блоков + данных можно эффективно исправлять поврежденные загрузки. + +Отклонить соединение, если скорость загрузки меньше чем определенное значение +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --lowest-speed-limit=10K file.metalink + + +Поддержка параметризованных URI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Вы можете определить набор частей: + +.. code-block:: console + + $ aria2c -P "http://{host1,host2,host3}/file.iso" + + +Вы можете определить числовую последовательность: + +.. code-block:: console + + $ aria2c -Z -P "http://host/image[000-100].png" + + +.. note:: + + Параметр -Z необходим, если все URI не указывают на один и тот же файл, как + в примере указанном выше. + +Вы можете определить шаг счетчика: + +.. code-block:: console + + $ aria2c -Z -P "http://host/image[A-Z:2].png" + + +Проверка контрольной суммы +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file + + +Параллельные загрузки с произвольным числом URI, metalink, torrent +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: console + + $ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink + + +Шифрование BitTorrent +^^^^^^^^^^^^^^^^^^^^^ +Шифровать всю полезную нагрузку используя ARC4: + +.. code-block:: console + + $ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent + + +СМОТРИТЕ ТАКЖЕ +-------------- +Веб-сайт проекта: http://aria2.sourceforge.net/ + +Вики aria2: http://sourceforge.net/apps/trac/aria2/wiki + +Домашняя страница Metalink: http://www.metalinker.org/ + +Описание формата Metalink: :rfc:`5854` + +АВТОРСКОЕ ПРАВО +--------------- +Авторское право (C) 2006, 2011 Tatsuhiro Tsujikawa + +Эта программа является свободным программным обеспечением; вы можете +распространять его и/или изменять его в соответствии с условиями лицензии +GNU General Public License, опубликованной Free Software Foundation; либо +License версии 2, либо (по вашему выбору) любой более поздней версии. + +Эта программа распространяется в надежде, что она будет полезной, но БЕЗ +КАКИХ-ЛИБО ГАРАНТИЙ, даже без подразумеваемых гарантий КОММЕРЧЕСКОЙ ЦЕННОСТИ +или ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ. См. GNU General Public License для +более подробной информации. + +Вы должны получить копию GNU General Public License вместе с этой +программой; если нет, напишите в Free Software Foundation, Inc., 51 Franklin +Street, Fifth Floor, Boston, MA 02110-1301 USA + +Кроме того, в качестве особого исключения, владельцы авторских прав дают +разрешение на ссылку части кода этой программы с библиотекой OpenSSL при +определенных условиях, как описано в каждом отдельном исходном файле, а +также распространять эту комбинацию вместе. Вы должны подчиняться GNU +General Public License во всех отношениях для всего используемого кода, +кроме OpenSSL. Если вы измените файл(ы) с этим исключением, вы можете +расширить это исключение для вашей версии файла(ов), но вы не обязаны делать +это. Если вы не хотите сделать это, удалите это заявление об исключении из +вашей версии. Если вы удалите это заявление об исключении из всех исходных +файлов в программе, то удалить его и здесь. + +АВТОР ПЕРЕВОДА +-------------- +ITriskTI + +Если вы нашли ошибку, неточность в переводе или считаете, что переведено +неправильно, тогда, пожалуйста, сообщите мне на e-mail. + +ПРИМЕЧАНИЕ +---------- +Эта страница руководства может содержать не обязательно самую последнюю информацию. +Если есть некоторые противоречия между этой страницей руководства и фактическим +программным обеспечением, пожалуйста, обращайтесь к английской версии страницы +руководства. diff --git a/doc/manual-src/ru/conf.py.in b/doc/manual-src/ru/conf.py.in new file mode 100644 index 00000000..7566cea6 --- /dev/null +++ b/doc/manual-src/ru/conf.py.in @@ -0,0 +1,215 @@ +# -*- coding: utf-8 -*- +# +# aria2 documentation build configuration file, created by +# sphinx-quickstart on Tue Apr 10 21:34:06 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'aria2' +# copyright = u'2012, Tatsuhiro Tsujikawa' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '@PACKAGE_VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@PACKAGE_VERSION@' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = False + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'aria2doc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'aria2.tex', u'aria2 Documentation', + u'Tatsuhiro Tsujikawa', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('aria2c', 'aria2c', u'сверхбыстрая утилита загрузки', [], 1) +] diff --git a/doc/manual-src/ru/index.rst b/doc/manual-src/ru/index.rst new file mode 100644 index 00000000..42acc204 --- /dev/null +++ b/doc/manual-src/ru/index.rst @@ -0,0 +1,14 @@ +.. aria2 documentation master file, created by + sphinx-quickstart on Tue Apr 10 21:34:06 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Aria2 Manual +============ + +Contents: + +.. toctree:: + :maxdepth: 3 + + aria2c