1ARIA2C(1)                            aria2                           ARIA2C(1)
2
3
4

NAME

6       aria2c - The ultra fast download utility
7

SYNOPSIS

9       aria2c [<OPTIONS>] [<URI>|<MAGNET>|<TORRENT_FILE>|<METALINK_FILE>] ...
10

DESCRIPTION

12       aria2  is  a utility for downloading files. The supported protocols are
13       HTTP(S), FTP, SFTP, BitTorrent, and Metalink. aria2 can download a file
14       from multiple sources/protocols and tries to utilize your maximum down‐
15       load bandwidth. It supports downloading a file from  HTTP(S)/FTP  /SFTP
16       and  BitTorrent  at  the  same  time,  while  the  data downloaded from
17       HTTP(S)/FTP/SFTP is uploaded to the BitTorrent  swarm.  Using  Metalink
18       chunk  checksums,  aria2  automatically  validates chunks of data while
19       downloading a file.
20

OPTIONS

22       NOTE:
23          Most FTP related options are  applicable  to  SFTP  as  well.   Some
24          options are not effective against SFTP (e.g., --ftp-pasv)
25
26   Basic Options
27       -d, --dir=<DIR>
28              The directory to store the downloaded file.
29
30       -i, --input-file=<FILE>
31              Downloads  the  URIs  listed  in  FILE. You can specify multiple
32              sources for a single entity by putting multiple URIs on a single
33              line  separated by the TAB character.  Additionally, options can
34              be specified after each URI line. Option lines must  start  with
35              one  or more white space characters (SPACE or TAB) and must only
36              contain one option per line.  Input files can use gzip  compres‐
37              sion.   When  FILE  is specified as -, aria2 will read the input
38              from stdin.  See the Input File  subsection  for  details.   See
39              also  the  --deferred-input option.  See also the --save-session
40              option.
41
42       -l, --log=<LOG>
43              The file name of the log file. If - is specified, log is written
44              to  stdout.  If empty string("") is specified, or this option is
45              omitted, no log is written to disk at all.
46
47       -j, --max-concurrent-downloads=<N>
48              Set the maximum number of parallel  downloads  for  every  queue
49              item.  See also the --split option.  Default: 5
50
51              NOTE:
52                 --max-concurrent-downloads  limits  the number of items which
53                 are downloaded concurrently.   --split  and  --min-split-size
54                 affect  the  number of connections inside each item.  Imagine
55                 that you have an input file (see  --input-file  option)  like
56                 this:
57
58                     http://example.com/foo
59                     http://example.com/bar
60
61                 Here  is  2  download  items.  aria2 can download these items
62                 concurrently if the value more than or equal 2  is  given  to
63                 --max-concurrent-downloads.   In  each download item, you can
64                 configure the number  of  connections  using  --split  and/or
65                 --min-split-size, etc.
66
67       -V, --check-integrity [true|false]
68              Check  file  integrity  by  validating piece hashes or a hash of
69              entire file.  This option has effect only  in  BitTorrent,  Met‐
70              alink  downloads  with  checksums  or HTTP(S)/FTP downloads with
71              --checksum option.  If piece hashes are  provided,  this  option
72              can  detect damaged portions of a file and re-download them.  If
73              a hash of entire file is provided, hash check is only done  when
74              file  has  been  already  download.  This  is determined by file
75              length. If hash check fails, file is re-downloaded from scratch.
76              If  both  piece  hashes  and a hash of entire file are provided,
77              only piece hashes are used. Default: false
78
79       -c, --continue [true|false]
80              Continue downloading a  partially  downloaded  file.   Use  this
81              option  to resume a download started by a web browser or another
82              program which downloads files sequentially from  the  beginning.
83              Currently  this  option  is only applicable to HTTP(S)/FTP down‐
84              loads.
85
86       -h, --help[=<TAG>|<KEYWORD>]
87              The help messages are classified with tags. A tag starts with #.
88              For  example, type --help=#http to get the usage for the options
89              tagged with #http. If non-tag word is given, print the usage for
90              the  options  whose  name includes that word.  Available Values:
91              #basic, #advanced, #http, #https, #ftp, #metalink,  #bittorrent,
92              #cookie,  #hook,  #file, #rpc, #checksum, #experimental, #depre‐
93              cated, #help, #all Default: #basic
94
95   HTTP/FTP/SFTP Options
96       --all-proxy=<PROXY>
97              Use a proxy server for all protocols.  To override a  previously
98              defined  proxy,  use "".  You also can override this setting and
99              specify  a  proxy  server  for  a  particular   protocol   using
100              --http-proxy,   --https-proxy  and  --ftp-proxy  options.   This
101              affects   all   downloads.    The    format    of    PROXY    is
102              [http://][USER:PASSWORD@]HOST[:PORT].  See also ENVIRONMENT sec‐
103              tion.
104
105              NOTE:
106                 If user and password are embedded in proxy URI and  they  are
107                 also  specified by --{http,https,ftp,all}-proxy-{user,passwd}
108                 options, those specified later override  prior  options.  For
109                 example,    if    you    specified    http-proxy-user=myname,
110                 http-proxy-passwd=mypass  in  aria2.conf  and  you  specified
111                 --http-proxy="http://proxy"  on  the command-line, then you'd
112                 get HTTP proxy http://proxy with  user  myname  and  password
113                 mypass.
114
115                 Another   example:  if  you  specified  on  the  command-line
116                 --http-proxy="http://user:pass@proxy"
117                 --http-proxy-user="myname" --http-proxy-passwd="mypass", then
118                 you'd get HTTP proxy http://proxy with user myname and  pass‐
119                 word mypass.
120
121                 One   more   example:   if   you  specified  in  command-line
122                 --http-proxy-user="myname"       --http-proxy-passwd="mypass"
123                 --http-proxy="http://user:pass@proxy",  then  you'd  get HTTP
124                 proxy http://proxy with user user and password pass.
125
126       --all-proxy-passwd=<PASSWD>
127              Set password for --all-proxy option.
128
129       --all-proxy-user=<USER>
130              Set user for --all-proxy option.
131
132       --checksum=<TYPE>=<DIGEST>
133              Set checksum. TYPE is hash type.  The  supported  hash  type  is
134              listed  in  Hash  Algorithms in aria2c -v. DIGEST is hex digest.
135              For   example,   setting   sha-1   digest   looks   like   this:
136              sha-1=0192ba11326fe2298c8cb4de616f4d4140213838    This    option
137              applies only to HTTP(S)/FTP downloads.
138
139       --connect-timeout=<SEC>
140              Set the connect timeout in seconds to  establish  connection  to
141              HTTP/FTP/proxy server. After the connection is established, this
142              option makes no effect and --timeout  option  is  used  instead.
143              Default: 60
144
145       --dry-run [true|false]
146              If  true  is given, aria2 just checks whether the remote file is
147              available and doesn't download data. This option has  effect  on
148              HTTP/FTP download.  BitTorrent downloads are canceled if true is
149              specified.  Default: false
150
151       --lowest-speed-limit=<SPEED>
152              Close connection if download speed is lower  than  or  equal  to
153              this value(bytes per sec).  0 means aria2 does not have a lowest
154              speed limit.  You can append K or M (1K =  1024,  1M  =  1024K).
155              This option does not affect BitTorrent downloads.  Default: 0
156
157       -x, --max-connection-per-server=<NUM>
158              The  maximum  number of connections to one server for each down‐
159              load.  Default: 1
160
161       --max-file-not-found=<NUM>
162              If aria2 receives  "file  not  found"  status  from  the  remote
163              HTTP/FTP  servers  NUM times without getting a single byte, then
164              force the download to fail. Specify 0 to  disable  this  option.
165              This options is effective only when using HTTP/FTP servers.  The
166              number of retry attempt is counted  toward  --max-tries,  so  it
167              should be configured too.
168
169              Default: 0
170
171       -m, --max-tries=<N>
172              Set  number of tries. 0 means unlimited.  See also --retry-wait.
173              Default: 5
174
175       -k, --min-split-size=<SIZE>
176              aria2 does not split less than 2*SIZE byte range.  For  example,
177              let's consider downloading 20MiB file. If SIZE is 10M, aria2 can
178              split file into 2 range [0-10MiB) and [10MiB-20MiB) and download
179              it using 2 sources(if --split >= 2, of course).  If SIZE is 15M,
180              since 2*15M > 20MiB, aria2 does not split file and  download  it
181              using  1 source.  You can append K or M (1K = 1024, 1M = 1024K).
182              Possible Values: 1M -1024M Default: 20M
183
184       --netrc-path=<FILE>
185              Specify the path to the netrc file.  Default: $(HOME)/.netrc
186
187              NOTE:
188                 Permission of the .netrc file must be  600.   Otherwise,  the
189                 file will be ignored.
190
191       -n, --no-netrc [true|false]
192              Disables netrc support. netrc support is enabled by default.
193
194              NOTE:
195                 netrc  file  is  only  read  at  the startup if --no-netrc is
196                 false.  So if --no-netrc is true at the startup, no netrc  is
197                 available  throughout  the  session.   You  cannot  get netrc
198                 enabled   even   if   you   send    --no-netrc=false    using
199                 aria2.changeGlobalOption().
200
201       --no-proxy=<DOMAINS>
202              Specify  a  comma separated list of host names, domains and net‐
203              work addresses with or without a  subnet  mask  where  no  proxy
204              should be used.
205
206              NOTE:
207                 For  network addresses with a subnet mask, both IPv4 and IPv6
208                 addresses work.  The current implementation does not  resolve
209                 the  host  name in an URI to compare network addresses speci‐
210                 fied in --no-proxy. So  it  is  only  effective  if  URI  has
211                 numeric IP addresses.
212
213       -o, --out=<FILE>
214              The  file name of the downloaded file.  It is always relative to
215              the   directory   given   in    --dir    option.     When    the
216              --force-sequential option is used, this option is ignored.
217
218              NOTE:
219                 You  cannot  specify  a  file name for Metalink or BitTorrent
220                 downloads.  The file name specified here is  only  used  when
221                 the URIs fed to aria2 are given on the command line directly,
222                 but not when using --input-file, --force-sequential option.
223
224                 Example:
225
226                     $ aria2c -o myfile.zip "http://mirror1/file.zip" "http://mirror2/file.zip"
227
228       --proxy-method=<METHOD>
229              Set the method to use in proxy request.  METHOD is either get or
230              tunnel.  HTTPS  downloads  always  use tunnel regardless of this
231              option.  Default: get
232
233       -R, --remote-time [true|false]
234              Retrieve timestamp of the remote file from the  remote  HTTP/FTP
235              server  and  if  it  is  available,  apply it to the local file.
236              Default: false
237
238       --reuse-uri [true|false]
239              Reuse already used URIs if no unused URIs  are  left.   Default:
240              true
241
242       --retry-wait=<SEC>
243              Set  the  seconds  to  wait between retries. When SEC > 0, aria2
244              will  retry  downloads  when  the  HTTP  server  returns  a  503
245              response. Default: 0
246
247       --server-stat-of=<FILE>
248              Specify  the  file  name  to  which  performance  profile of the
249              servers is saved. You can load saved data using --server-stat-if
250              option. See Server Performance Profile subsection below for file
251              format.
252
253       --server-stat-if=<FILE>
254              Specify the  file  name  to  load  performance  profile  of  the
255              servers.  The loaded data will be used in some URI selector such
256              as feedback.  See also --uri-selector option. See Server Perfor‐
257              mance Profile subsection below for file format.
258
259       --server-stat-timeout=<SEC>
260              Specifies  timeout  in seconds to invalidate performance profile
261              of the servers since the last contact to them.   Default:  86400
262              (24hours)
263
264       -s, --split=<N>
265              Download  a  file  using N connections.  If more than N URIs are
266              given, first N URIs are used and remaining  URIs  are  used  for
267              backup.  If less than N URIs are given, those URIs are used more
268              than once so that N connections total are  made  simultaneously.
269              The  number of connections to the same host is restricted by the
270              --max-connection-per-server    option.      See     also     the
271              --min-split-size option.  Default: 5
272
273              NOTE:
274                 Some  Metalinks  regulate  the  number of servers to connect.
275                 aria2 strictly respects them.  This means  that  if  Metalink
276                 defines the maxconnections attribute lower than N, then aria2
277                 uses the value of this lower value instead of N.
278
279       --stream-piece-selector=<SELECTOR>
280              Specify piece selection algorithm  used  in  HTTP/FTP  download.
281              Piece means fixed length segment which is downloaded in parallel
282              in segmented download. If default is given, aria2 selects  piece
283              so  that  it reduces the number of establishing connection. This
284              is reasonable default behavior because  establishing  connection
285              is  an  expensive operation.  If inorder is given, aria2 selects
286              piece which has minimum index. Index=0 means first of the  file.
287              This  will  be  useful  to  view  movie  while  downloading  it.
288              --enable-http-pipelining option may be useful to reduce  re-con‐
289              nection    overhead.     Please    note    that   aria2   honors
290              --min-split-size option, so it will be necessary  to  specify  a
291              reasonable  value  to  --min-split-size  option.   If  random is
292              given,   aria2   selects   piece   randomly.    Like    inorder,
293              --min-split-size  option  is  honored.  If geom is given, at the
294              beginning aria2 selects  piece  which  has  minimum  index  like
295              inorder, but it exponentially increasingly keeps space from pre‐
296              viously selected piece. This will reduce the  number  of  estab‐
297              lishing  connection  and  at  the same time it will download the
298              beginning part of the file first. This will be  useful  to  view
299              movie while downloading it.  Default: default
300
301       -t, --timeout=<SEC>
302              Set timeout in seconds.  Default: 60
303
304       --uri-selector=<SELECTOR>
305              Specify   URI  selection  algorithm.  The  possible  values  are
306              inorder, feedback and adaptive.  If inorder  is  given,  URI  is
307              tried  in  the  order  appeared in the URI list.  If feedback is
308              given, aria2 uses download speed observed in the previous  down‐
309              loads  and  choose  fastest  server  in  the URI list. This also
310              effectively skips dead mirrors. The observed download speed is a
311              part   of   performance   profile   of   servers   mentioned  in
312              --server-stat-of and --server-stat-if options.  If  adaptive  is
313              given,  selects  one  of  the  best  mirrors  for  the first and
314              reserved connections.  For supplementary ones, it  returns  mir‐
315              rors  which  has  not  been  tested yet, and if each of them has
316              already been tested, returns mirrors  which  has  to  be  tested
317              again.  Otherwise, it doesn't select anymore mirrors. Like feed‐
318              back, it uses a performance profile of servers.  Default:  feed‐
319              back
320
321   HTTP Specific Options
322       --ca-certificate=<FILE>
323              Use  the  certificate  authorities  in FILE to verify the peers.
324              The certificate file must be in PEM format and can contain  mul‐
325              tiple CA certificates.  Use --check-certificate option to enable
326              verification.
327
328              NOTE:
329                 If you build with OpenSSL or the  recent  version  of  GnuTLS
330                 which has gnutls_certificate_set_x509_system_trust() function
331                 and the library is properly configured  to  locate  the  sys‐
332                 tem-wide CA certificates store, aria2 will automatically load
333                 those certificates at the startup.
334
335              NOTE:
336                 WinTLS and AppleTLS do not support this option.  Instead  you
337                 will have to import the certificate into the OS trust store.
338
339       --certificate=<FILE>
340              Use  the  client  certificate  in  FILE. The certificate must be
341              either in PKCS12 (.p12, .pfx) or in PEM format.
342
343              PKCS12 files must contain the certificate, a key and  optionally
344              a  chain  of  additional  certificates. Only PKCS12 files with a
345              blank import password can be opened!
346
347              When using  PEM,  you  have  to  specify  the  private  key  via
348              --private-key as well.
349
350              NOTE:
351                 WinTLS  does  not support PEM files at the moment. Users have
352                 to use PKCS12 files.
353
354              NOTE:
355                 AppleTLS users should use  the  KeyChain  Access  utility  to
356                 import  the  client certificate and get the SHA-1 fingerprint
357                 from the Information dialog corresponding  to  that  certifi‐
358                 cate.   To  start aria2c use --certificate=<SHA-1>.  Alterna‐
359                 tively PKCS12 files are also supported. PEM  files,  however,
360                 are not supported.
361
362       --check-certificate [true|false]
363              Verify the peer using certificates specified in --ca-certificate
364              option.  Default: true
365
366       --http-accept-gzip [true|false]
367              Send Accept: deflate, gzip request header and  inflate  response
368              if  remote  server  responds with Content-Encoding: gzip or Con‐
369              tent-Encoding: deflate.  Default: false
370
371              NOTE:
372                 Some server responds with Content-Encoding:  gzip  for  files
373                 which  itself  is  gzipped  file.  aria2 inflates them anyway
374                 because of the response header.
375
376       --http-auth-challenge [true|false]
377              Send HTTP authorization header only when it is requested by  the
378              server.  If  false  is  set, then authorization header is always
379              sent to the server.  There is an exception:  if  user  name  and
380              password  are  embedded  in  URI, authorization header is always
381              sent to the server regardless of this option.  Default: false
382
383       --http-no-cache [true|false]
384              Send Cache-Control: no-cache  and  Pragma:  no-cache  header  to
385              avoid  cached content.  If false is given, these headers are not
386              sent and you can add Cache-Control header with a  directive  you
387              like using --header option. Default: false
388
389       --http-user=<USER>
390              Set HTTP user. This affects all URIs.
391
392       --http-passwd=<PASSWD>
393              Set HTTP password. This affects all URIs.
394
395       --http-proxy=<PROXY>
396              Use  a  proxy server for HTTP.  To override a previously defined
397              proxy, use "".  See also the --all-proxy option.   This  affects
398              all http downloads.  The format of PROXY is [http://][USER:PASS‐
399              WORD@]HOST[:PORT]
400
401       --http-proxy-passwd=<PASSWD>
402              Set password for --http-proxy.
403
404       --http-proxy-user=<USER>
405              Set user for --http-proxy.
406
407       --https-proxy=<PROXY>
408              Use a proxy server for HTTPS. To override a  previously  defined
409              proxy,  use  "".  See also the --all-proxy option.  This affects
410              all https download.  The format of PROXY is [http://][USER:PASS‐
411              WORD@]HOST[:PORT]
412
413       --https-proxy-passwd=<PASSWD>
414              Set password for --https-proxy.
415
416       --https-proxy-user=<USER>
417              Set user for --https-proxy.
418
419       --private-key=<FILE>
420              Use  the private key in FILE.  The private key must be decrypted
421              and in PEM format.  The behavior when encrypted one is given  is
422              undefined.  See also --certificate option.
423
424       --referer=<REFERER>
425              Set  an  http  referrer  (Referer).  This affects all http/https
426              downloads.  If * is given, the download URI is also used as  the
427              referrer.   This  may  be  useful  when  used  together with the
428              --parameterized-uri option.
429
430       --enable-http-keep-alive [true|false]
431              Enable HTTP/1.1 persistent connection.  Default: true
432
433       --enable-http-pipelining [true|false]
434              Enable HTTP/1.1 pipelining.  Default: false
435
436              NOTE:
437                 In performance perspective, there is usually no advantage  to
438                 enable this option.
439
440       --header=<HEADER>
441              Append  HEADER  to HTTP request header.  You can use this option
442              repeatedly to specify more than one header:
443
444                 $ aria2c --header="X-A: b78" --header="X-B: 9J1" "http://host/file"
445
446       --load-cookies=<FILE>
447              Load Cookies from FILE  using  the  Firefox3  format  (SQLite3),
448              Chromium/Google   Chrome   (SQLite3)   and   the   Mozilla/Fire‐
449              fox(1.x/2.x)/Netscape format.
450
451              NOTE:
452                 If aria2 is built without libsqlite3, then it doesn't support
453                 Firefox3 and Chromium/Google Chrome cookie format.
454
455       --save-cookies=<FILE>
456              Save  Cookies to FILE in Mozilla/Firefox(1.x/2.x)/ Netscape for‐
457              mat. If FILE already exists, it is overwritten. Session  Cookies
458              are also saved and their expiry values are treated as 0.  Possi‐
459              ble Values: /path/to/file
460
461       --use-head [true|false]
462              Use HEAD method for  the  first  request  to  the  HTTP  server.
463              Default: false
464
465       -U, --user-agent=<USER_AGENT>
466              Set  user agent for HTTP(S) downloads.  Default: aria2/$VERSION,
467              $VERSION is replaced by package version.
468
469   FTP/SFTP Specific Options
470       --ftp-user=<USER>
471              Set FTP user. This affects all URIs.  Default: anonymous
472
473       --ftp-passwd=<PASSWD>
474              Set FTP password. This affects all URIs.  If user name is embed‐
475              ded but password is missing in URI, aria2 tries to resolve pass‐
476              word using .netrc. If password is found in .netrc, then  use  it
477              as  password. If not, use the password specified in this option.
478              Default: ARIA2USER@
479
480       -p, --ftp-pasv [true|false]
481              Use the passive mode in FTP.  If false is given, the active mode
482              will be used.  Default: true
483
484              NOTE:
485                 This option is ignored for SFTP transfer.
486
487       --ftp-proxy=<PROXY>
488              Use  a  proxy  server for FTP.  To override a previously defined
489              proxy, use "".  See also the --all-proxy option.   This  affects
490              all  ftp downloads.  The format of PROXY is [http://][USER:PASS‐
491              WORD@]HOST[:PORT]
492
493       --ftp-proxy-passwd=<PASSWD>
494              Set password for --ftp-proxy option.
495
496       --ftp-proxy-user=<USER>
497              Set user for --ftp-proxy option.
498
499       --ftp-type=<TYPE>
500              Set FTP transfer type. TYPE is either binary or ascii.  Default:
501              binary
502
503              NOTE:
504                 This option is ignored for SFTP transfer.
505
506       --ftp-reuse-connection [true|false]
507              Reuse connection in FTP.  Default: true
508
509       --ssh-host-key-md=<TYPE>=<DIGEST>
510              Set  checksum  for  SSH  host public key. TYPE is hash type. The
511              supported hash type is sha-1 or md5. DIGEST is hex  digest.  For
512              example:  sha-1=b030503d4de4539dc7885e6f0f5e256704edf4c3.   This
513              option can be used to validate server's public key when SFTP  is
514              used. If this option is not set, which is default, no validation
515              takes place.
516
517   BitTorrent/Metalink Options
518       --select-file=<INDEX>...
519              Set file to download by specifying its index.  You can find  the
520              file  index using the --show-files option.  Multiple indexes can
521              be specified by using ,, for example: 3,6.  You can also  use  -
522              to specify a range: 1-5.  , and - can be used together: 1-5,8,9.
523              When used with the -M option, index may vary  depending  on  the
524              query (see --metalink-* options).
525
526              NOTE:
527                 In  multi  file torrent, the adjacent files specified by this
528                 option may also be downloaded. This is by design, not a  bug.
529                 A  single  piece  may include several files or part of files,
530                 and aria2 writes the piece to the appropriate files.
531
532       -S, --show-files [true|false]
533              Print file listing of ".torrent", ".meta4" and ".metalink"  file
534              and  exit.   In  case of ".torrent" file, additional information
535              (infohash, piece length, etc) is also printed.
536
537   BitTorrent Specific Options
538       --bt-detach-seed-only [true|false]
539              Exclude seed only  downloads  when  counting  concurrent  active
540              downloads  (See -j option).  This means that if -j3 is given and
541              this option is turned on and 3 downloads are active and  one  of
542              those enters seed mode, then it is excluded from active download
543              count (thus it becomes 2), and  the  next  download  waiting  in
544              queue gets started. But be aware that seeding item is still rec‐
545              ognized as active download in RPC method.  Default: false
546
547       --bt-enable-hook-after-hash-check [true|false]
548              Allow hook command invocation after hash check (see  -V  option)
549              in  BitTorrent  download.  By default, when hash check succeeds,
550              the command given by --on-bt-download-complete is  executed.  To
551              disable this action, give false to this option.  Default: true
552
553       --bt-enable-lpd [true|false]
554              Enable Local Peer Discovery.  If a private flag is set in a tor‐
555              rent, aria2 doesn't use this feature for that download  even  if
556              true is given.  Default: false
557
558       --bt-exclude-tracker=<URI>[,...]
559              Comma  separated  list  of  BitTorrent tracker's announce URI to
560              remove. You can use special value * which matches all URIs, thus
561              removes  all  announce  URIs.  When  specifying  * in shell com‐
562              mand-line, don't  forget  to  escape  or  quote  it.   See  also
563              --bt-tracker option.
564
565       --bt-external-ip=<IPADDRESS>
566              Specify  the  external  IP address to use in BitTorrent download
567              and DHT.  It may be sent to BitTorrent tracker.  For  DHT,  this
568              option  should be set to report that local node is downloading a
569              particular torrent.  This is critical to use DHT  in  a  private
570              network. Although this function is named external, it can accept
571              any kind of IP addresses.
572
573       --bt-force-encryption [true|false]
574              Requires BitTorrent message payload encryption with arc4.   This
575              is        a        shorthand        of       --bt-require-crypto
576              --bt-min-crypto-level=arc4.  This option  does  not  change  the
577              option  value  of  those options.  If true is given, deny legacy
578              BitTorrent handshake and  only  use  Obfuscation  handshake  and
579              always encrypt message payload.  Default: false
580
581       --bt-hash-check-seed [true|false]
582              If  true  is  given,  after  hash  check using --check-integrity
583              option and file is complete, continue to seed file. If you  want
584              to  check file and download it only when it is damaged or incom‐
585              plete, set this option to false.  This option has effect only on
586              BitTorrent download.  Default: true
587
588       --bt-load-saved-metadata [true|false]
589              Before  getting  torrent metadata from DHT when downloading with
590              magnet link, first try to read file saved by  --bt-save-metadata
591              option.   If  it  is  successful, then skip downloading metadata
592              from DHT.  Default: false
593
594       --bt-lpd-interface=<INTERFACE>
595              Use given interface for Local Peer Discovery. If this option  is
596              not  specified, the default interface is chosen. You can specify
597              interface name and IP address.  Possible Values:  interface,  IP
598              address
599
600       --bt-max-open-files=<NUM>
601              Specify  maximum  number  of files to open in multi-file BitTor‐
602              rent/Metalink download globally.  Default: 100
603
604       --bt-max-peers=<NUM>
605              Specify the maximum number of peers per torrent.  0 means unlim‐
606              ited.   See also --bt-request-peer-speed-limit option.  Default:
607              55
608
609       --bt-metadata-only [true|false]
610              Download meta data only. The file(s) described in meta data will
611              not  be  downloaded. This option has effect only when BitTorrent
612              Magnet  URI  is  used.  See  also   --bt-save-metadata   option.
613              Default: false
614
615       --bt-min-crypto-level=plain|arc4
616              Set  minimum  level of encryption method.  If several encryption
617              methods are provided by a peer, aria2  chooses  the  lowest  one
618              which satisfies the given level.  Default: plain
619
620       --bt-prioritize-piece=head[=<SIZE>],tail[=<SIZE>]
621              Try  to  download first and last pieces of each file first. This
622              is useful for previewing files. The argument can contain 2  key‐
623              words:  head  and  tail.  To include both keywords, they must be
624              separated by comma. These keywords can take one parameter, SIZE.
625              For example, if head=<SIZE> is specified, pieces in the range of
626              first SIZE bytes of each file get higher priority.   tail=<SIZE>
627              means  the  range  of  last  SIZE  bytes  of each file. SIZE can
628              include K or M (1K = 1024, 1M =  1024K).  If  SIZE  is  omitted,
629              SIZE=1M is used.
630
631       --bt-remove-unselected-file [true|false]
632              Removes  the unselected files when download is completed in Bit‐
633              Torrent. To select files, use --select-file option. If it is not
634              used,  all  files  are  assumed  to be selected. Please use this
635              option with care because it will actually remove files from your
636              disk.  Default: false
637
638       --bt-require-crypto [true|false]
639              If  true is given, aria2 doesn't accept and establish connection
640              with legacy BitTorrent handshake(\19BitTorrent protocol).   Thus
641              aria2 always uses Obfuscation handshake.  Default: false
642
643       --bt-request-peer-speed-limit=<SPEED>
644              If  the  whole  download  speed  of  every torrent is lower than
645              SPEED, aria2 temporarily increases the number of  peers  to  try
646              for  more download speed. Configuring this option with your pre‐
647              ferred download speed can increase your download speed  in  some
648              cases.  You can append K or M (1K = 1024, 1M = 1024K).  Default:
649              50K
650
651       --bt-save-metadata [true|false]
652              Save meta data as ".torrent" file. This option has  effect  only
653              when  BitTorrent  Magnet  URI  is  used.   The  file name is hex
654              encoded info hash with suffix ".torrent". The  directory  to  be
655              saved is the same directory where download file is saved. If the
656              same file already exists, meta  data  is  not  saved.  See  also
657              --bt-metadata-only option. Default: false
658
659       --bt-seed-unverified [true|false]
660              Seed previously downloaded files without verifying piece hashes.
661              Default: false
662
663       --bt-stop-timeout=<SEC>
664              Stop BitTorrent download if download speed is 0  in  consecutive
665              SEC  seconds. If 0 is given, this feature is disabled.  Default:
666              0
667
668       --bt-tracker=<URI>[,...]
669              Comma separated list of additional BitTorrent tracker's announce
670              URI.  These URIs are not affected by --bt-exclude-tracker option
671              because they are added after URIs in --bt-exclude-tracker option
672              are removed.
673
674       --bt-tracker-connect-timeout=<SEC>
675              Set  the  connect  timeout in seconds to establish connection to
676              tracker. After the connection is established, this option  makes
677              no  effect  and  --bt-tracker-timeout  option  is  used instead.
678              Default: 60
679
680       --bt-tracker-interval=<SEC>
681              Set the interval in seconds between tracker requests. This  com‐
682              pletely  overrides interval value and aria2 just uses this value
683              and ignores the min interval and interval value in the  response
684              of  tracker. If 0 is set, aria2 determines interval based on the
685              response of tracker and the download progress.  Default: 0
686
687       --bt-tracker-timeout=<SEC>
688              Set timeout in seconds. Default: 60
689
690       --dht-entry-point=<HOST>:<PORT>
691              Set host and port as an entry point to IPv4 DHT network.
692
693       --dht-entry-point6=<HOST>:<PORT>
694              Set host and port as an entry point to IPv6 DHT network.
695
696       --dht-file-path=<PATH>
697              Change the IPv4  DHT  routing  table  file  to  PATH.   Default:
698              $HOME/.aria2/dht.dat         if        present,        otherwise
699              $XDG_CACHE_HOME/aria2/dht.dat.
700
701       --dht-file-path6=<PATH>
702              Change the IPv6  DHT  routing  table  file  to  PATH.   Default:
703              $HOME/.aria2/dht6.dat        if        present,        otherwise
704              $XDG_CACHE_HOME/aria2/dht6.dat.
705
706       --dht-listen-addr6=<ADDR>
707              Specify address to bind socket for IPv6 DHT.   It  should  be  a
708              global unicast IPv6 address of the host.
709
710       --dht-listen-port=<PORT>...
711              Set  UDP listening port used by DHT(IPv4, IPv6) and UDP tracker.
712              Multiple ports  can  be  specified  by  using  ,,  for  example:
713              6881,6885.   You can also use - to specify a range: 6881-6999. ,
714              and - can be used together.  Default: 6881-6999
715
716              NOTE:
717                 Make sure that the specified ports are open for incoming  UDP
718                 traffic.
719
720       --dht-message-timeout=<SEC>
721              Set timeout in seconds. Default: 10
722
723       --enable-dht [true|false]
724              Enable  IPv4 DHT functionality. It also enables UDP tracker sup‐
725              port. If a private flag is set in a torrent, aria2  doesn't  use
726              DHT for that download even if true is given.  Default: true
727
728       --enable-dht6 [true|false]
729              Enable  IPv6  DHT  functionality.  If a private flag is set in a
730              torrent, aria2 doesn't use DHT for that download even if true is
731              given.  Use  --dht-listen-port  option to specify port number to
732              listen on. See also --dht-listen-addr6 option.
733
734       --enable-peer-exchange [true|false]
735              Enable Peer Exchange extension. If a private flag is  set  in  a
736              torrent, this feature is disabled for that download even if true
737              is given.  Default: true
738
739       --follow-torrent=true|false|mem
740              If true or mem is specified, when a file whose suffix  is  .tor‐
741              rent  or content type is application/x-bittorrent is downloaded,
742              aria2 parses it as a torrent file and downloads files  mentioned
743              in  it.   If  mem is specified, a torrent file is not written to
744              the disk, but is just kept in memory.  If  false  is  specified,
745              the  .torrent  file is downloaded to the disk, but is not parsed
746              as a torrent and its contents are not downloaded.  Default: true
747
748       -O, --index-out=<INDEX>=<PATH>
749              Set file path for file with index=INDEX. You can find  the  file
750              index using the --show-files option.  PATH is a relative path to
751              the path specified in --dir option. You can use this option mul‐
752              tiple  times. Using this option, you can specify the output file
753              names of BitTorrent downloads.
754
755       --listen-port=<PORT>...
756              Set TCP port number for BitTorrent  downloads.   Multiple  ports
757              can  be  specified by using ,,  for example: 6881,6885.  You can
758              also use - to specify a range: 6881-6999.  , and - can  be  used
759              together: 6881-6889,6999.  Default: 6881-6999
760
761              NOTE:
762                 Make  sure that the specified ports are open for incoming TCP
763                 traffic.
764
765       --max-overall-upload-limit=<SPEED>
766              Set max overall  upload  speed  in  bytes/sec.   0  means  unre‐
767              stricted.   You  can  append K or M (1K = 1024, 1M = 1024K).  To
768              limit the  upload  speed  per  torrent,  use  --max-upload-limit
769              option.  Default: 0
770
771       -u, --max-upload-limit=<SPEED>
772              Set  max  upload  speed  per each torrent in bytes/sec.  0 means
773              unrestricted.  You can append K or M (1K = 1024,  1M  =  1024K).
774              To      limit      the     overall     upload     speed,     use
775              --max-overall-upload-limit option.  Default: 0
776
777       --peer-id-prefix=<PEER_ID_PREFIX>
778              Specify the prefix of peer ID. The peer ID in BitTorrent  is  20
779              byte  length. If more than 20 bytes are specified, only first 20
780              bytes are used. If less than 20 bytes are specified, random byte
781              data are added to make its length 20 bytes.
782
783              Default: A2-$MAJOR-$MINOR-$PATCH-, $MAJOR, $MINOR and $PATCH are
784              replaced by major, minor and patch version number  respectively.
785              For instance, aria2 version 1.18.8 has prefix ID A2-1-18-8-.
786
787       --peer-agent=<PEER_AGENT>
788              Specify  the string used during the bitorrent extended handshake
789              for the peer's client version.
790
791              Default: aria2/$MAJOR.$MINOR.$PATCH, $MAJOR, $MINOR  and  $PATCH
792              are  replaced  by  major, minor and patch version number respec‐
793              tively.  For instance,  aria2  version  1.18.8  has  peer  agent
794              aria2/1.18.8.
795
796       --seed-ratio=<RATIO>
797              Specify  share  ratio. Seed completed torrents until share ratio
798              reaches RATIO.  You are strongly encouraged to specify equals or
799              more  than  1.0  here.   Specify 0.0 if you intend to do seeding
800              regardless of share ratio.  If --seed-time option  is  specified
801              along  with  this  option, seeding ends when at least one of the
802              conditions is satisfied.  Default: 1.0
803
804       --seed-time=<MINUTES>
805              Specify seeding time  in  (fractional)  minutes.  Also  see  the
806              --seed-ratio option.
807
808              NOTE:
809                 Specifying --seed-time=0 disables seeding after download com‐
810                 pleted.
811
812       -T, --torrent-file=<TORRENT_FILE>
813              The path to the ".torrent" file.  You are not  required  to  use
814              this  option  because  you  can specify ".torrent" files without
815              --torrent-file.
816
817   Metalink Specific Options
818       --follow-metalink=true|false|mem
819              If true or mem is specified, when a file whose suffix is  .meta4
820              or  .metalink  or  content  type of application/metalink4+xml or
821              application/metalink+xml is downloaded, aria2  parses  it  as  a
822              metalink  file  and  downloads files mentioned in it.  If mem is
823              specified, a metalink file is not written to the  disk,  but  is
824              just  kept in memory.  If false is specified, the .metalink file
825              is downloaded to the disk, but is not parsed as a metalink  file
826              and its contents are not downloaded.  Default: true
827
828       --metalink-base-uri=<URI>
829              Specify  base  URI  to  resolve relative URI in metalink:url and
830              metalink:metaurl element in a  metalink  file  stored  in  local
831              disk. If URI points to a directory, URI must end with /.
832
833       -M, --metalink-file=<METALINK_FILE>
834              The file path to ".meta4" and ".metalink" file. Reads input from
835              stdin when - is specified.  You are not  required  to  use  this
836              option   because  you  can  specify  ".metalink"  files  without
837              --metalink-file.
838
839       --metalink-language=<LANGUAGE>
840              The language of the file to download.
841
842       --metalink-location=<LOCATION>[,...]
843              The location of the preferred server.  A comma-delimited list of
844              locations is acceptable, for example, jp,us.
845
846       --metalink-os=<OS>
847              The operating system of the file to download.
848
849       --metalink-version=<VERSION>
850              The version of the file to download.
851
852       --metalink-preferred-protocol=<PROTO>
853              Specify  preferred  protocol.   The  possible  values  are http,
854              https, ftp and none.  Specify  none  to  disable  this  feature.
855              Default: none
856
857       --metalink-enable-unique-protocol [true|false]
858              If  true is given and several protocols are available for a mir‐
859              ror  in  a  metalink  file,  aria2  uses  one  of   them.    Use
860              --metalink-preferred-protocol  option  to specify the preference
861              of protocol.  Default: true
862
863   RPC Options
864       --enable-rpc [true|false]
865              Enable JSON-RPC/XML-RPC server.  It is strongly  recommended  to
866              set  secret  authorization token using --rpc-secret option.  See
867              also --rpc-listen-port option.  Default: false
868
869       --pause [true|false]
870              Pause download after added. This option is effective  only  when
871              --enable-rpc=true is given.  Default: false
872
873       --pause-metadata [true|false]
874              Pause  downloads created as a result of metadata download. There
875              are 3 types of metadata  downloads  in  aria2:  (1)  downloading
876              .torrent  file.  (2)  downloading  torrent metadata using magnet
877              link. (3) downloading metalink file.  These  metadata  downloads
878              will generate downloads using their metadata. This option pauses
879              these subsequent downloads. This option is effective  only  when
880              --enable-rpc=true is given.  Default: false
881
882       --rpc-allow-origin-all [true|false]
883              Add Access-Control-Allow-Origin header field with value * to the
884              RPC response.  Default: false
885
886       --rpc-certificate=<FILE>
887              Use the certificate in FILE for RPC server. The certificate must
888              be either in PKCS12 (.p12, .pfx) or in PEM format.
889
890              PKCS12  files must contain the certificate, a key and optionally
891              a chain of additional certificates. Only  PKCS12  files  with  a
892              blank import password can be opened!
893
894              When  using  PEM,  you  have  to  specify  the  private  key via
895              --rpc-private-key as well. Use  --rpc-secure  option  to  enable
896              encryption.
897
898              NOTE:
899                 WinTLS  does  not support PEM files at the moment. Users have
900                 to use PKCS12 files.
901
902              NOTE:
903                 AppleTLS users should use  the  KeyChain  Access  utility  to
904                 first  generate  a  self-signed  SSL-Server certificate, e.g.
905                 using the wizard, and get  the  SHA-1  fingerprint  from  the
906                 Information dialog corresponding to that new certificate.  To
907                 start aria2c with --rpc-secure use --rpc-certificate=<SHA-1>.
908                 Alternatively  PKCS12  files  are  also supported. PEM files,
909                 however, are not supported.
910
911       --rpc-listen-all [true|false]
912              Listen incoming JSON-RPC/XML-RPC requests on all network  inter‐
913              faces.  If  false is given, listen only on local loopback inter‐
914              face.  Default: false
915
916       --rpc-listen-port=<PORT>
917              Specify a port number for JSON-RPC/XML-RPC server to listen  to.
918              Possible Values: 1024 -65535 Default: 6800
919
920       --rpc-max-request-size=<SIZE>
921              Set  max  size of JSON-RPC/XML-RPC request. If aria2 detects the
922              request is more than SIZE bytes, it drops  connection.  Default:
923              2M
924
925       --rpc-passwd=<PASSWD>
926              Set JSON-RPC/XML-RPC password.
927
928              WARNING:
929                 --rpc-passwd option will be deprecated in the future release.
930                 Migrate to --rpc-secret option as soon as possible.
931
932       --rpc-private-key=<FILE>
933              Use the private key in FILE for RPC  server.   The  private  key
934              must  be decrypted and in PEM format. Use --rpc-secure option to
935              enable encryption. See also --rpc-certificate option.
936
937       --rpc-save-upload-metadata [true|false]
938              Save the uploaded torrent or metalink meta data in the directory
939              specified  by --dir option. The file name consists of SHA-1 hash
940              hex string of meta data plus extension. For torrent, the  exten‐
941              sion  is  '.torrent'. For metalink, it is '.meta4'.  If false is
942              given to this option, the downloads added by  aria2.addTorrent()
943              or  aria2.addMetalink()  will  not  be  saved  by --save-session
944              option. Default: true
945
946       --rpc-secret=<TOKEN>
947              Set RPC  secret  authorization  token.  Read  RPC  authorization
948              secret token to know how this option value is used.
949
950       --rpc-secure [true|false]
951              RPC  transport  will  be  encrypted by SSL/TLS.  The RPC clients
952              must use https  scheme  to  access  the  server.  For  WebSocket
953              client,    use    wss    scheme.   Use   --rpc-certificate   and
954              --rpc-private-key options to specify the server certificate  and
955              private key.
956
957       --rpc-user=<USER>
958              Set JSON-RPC/XML-RPC user.
959
960              WARNING:
961                 --rpc-user  option  will be deprecated in the future release.
962                 Migrate to --rpc-secret option as soon as possible.
963
964   Advanced Options
965       --allow-overwrite [true|false]
966              Restart download from scratch if the corresponding control  file
967              doesn't  exist.  See also --auto-file-renaming option.  Default:
968              false
969
970       --allow-piece-length-change [true|false]
971              If false is given, aria2 aborts download when a piece length  is
972              different from one in a control file.  If true is given, you can
973              proceed but some download progress will be lost.  Default: false
974
975       --always-resume [true|false]
976              Always resume download. If true is given, aria2 always tries  to
977              resume  download and if resume is not possible, aborts download.
978              If false is given, when all given URIs do not support resume  or
979              aria2  encounters N URIs which does not support resume (N is the
980              value specified using --max-resume-failure-tries option),  aria2
981              downloads  file  from  scratch.   See --max-resume-failure-tries
982              option. Default: true
983
984       --async-dns [true|false]
985              Enable asynchronous DNS.  Default: true
986
987       --async-dns-server=<IPADDRESS>[,...]
988              Comma separated list of DNS server address used in  asynchronous
989              DNS resolver. Usually asynchronous DNS resolver reads DNS server
990              addresses from /etc/resolv.conf. When this option  is  used,  it
991              uses  DNS  servers  specified  in this option instead of ones in
992              /etc/resolv.conf. You can specify both IPv4  and  IPv6  address.
993              This   option   is   useful   when  the  system  does  not  have
994              /etc/resolv.conf and user does not have the permission to create
995              it.
996
997       --auto-file-renaming [true|false]
998              Rename  file  name if the same file already exists.  This option
999              works only in HTTP(S)/FTP download.  The new file name has a dot
1000              and  a  number(1..9999)  appended after the name, but before the
1001              file extension, if any.  Default: true
1002
1003       --auto-save-interval=<SEC>
1004              Save a control file(*.aria2) every SEC seconds.  If 0 is  given,
1005              a  control file is not saved during download. aria2 saves a con‐
1006              trol file when it stops regardless of the value.   The  possible
1007              values are between 0 to 600.  Default: 60
1008
1009       --conditional-get [true|false]
1010              Download  file  only  when  the  local file is older than remote
1011              file. This function only works with HTTP(S) downloads only.   It
1012              does  not  work  if  file size is specified in Metalink. It also
1013              ignores Content-Disposition header.  If a control  file  exists,
1014              this  option  will  be  ignored.   This  function  uses If-Modi‐
1015              fied-Since header to get only  newer  file  conditionally.  When
1016              getting  modification  time of local file, it uses user supplied
1017              file name (see --out option) or file name part in URI  if  --out
1018              is not specified.  To overwrite existing file, --allow-overwrite
1019              is required.  Default: false
1020
1021       --conf-path=<PATH>
1022              Change  the  configuration  file   path   to   PATH.    Default:
1023              $HOME/.aria2/aria2.conf    if   present,   otherwise   $XDG_CON‐
1024              FIG_HOME/aria2/aria2.conf.
1025
1026       --console-log-level=<LEVEL>
1027              Set log level to output to  console.   LEVEL  is  either  debug,
1028              info, notice, warn or error.  Default: notice
1029
1030       --content-disposition-default-utf8 [true|false]
1031              Handle  quoted  string  in  Content-Disposition  header as UTF-8
1032              instead of ISO-8859-1, for example, the filename parameter,  but
1033              not the extended version filename*.  Default: false
1034
1035       -D, --daemon [true|false]
1036              Run  as daemon. The current working directory will be changed to
1037              / and standard input, standard output and standard error will be
1038              redirected to /dev/null. Default: false
1039
1040       --deferred-input [true|false]
1041              If  true is given, aria2 does not read all URIs and options from
1042              file specified by --input-file option at startup, but  it  reads
1043              one  by one when it needs later. This may reduce memory usage if
1044              input file contains a lot of URIs  to  download.   If  false  is
1045              given,  aria2  reads  all URIs and options at startup.  Default:
1046              false
1047
1048              WARNING:
1049                 --deferred-input option will be disabled when  --save-session
1050                 is used together.
1051
1052       --disable-ipv6 [true|false]
1053              Disable  IPv6.  This is useful if you have to use broken DNS and
1054              want to avoid terribly slow AAAA record lookup. Default: false
1055
1056       --disk-cache=<SIZE>
1057              Enable disk cache. If SIZE is 0, the  disk  cache  is  disabled.
1058              This  feature  caches the downloaded data in memory, which grows
1059              to at most SIZE bytes. The cache storage is  created  for  aria2
1060              instance  and  shared by all downloads. The one advantage of the
1061              disk cache is reduce the disk I/O because the data  are  written
1062              in  larger  unit  and it is reordered by the offset of the file.
1063              If hash checking is involved and the data are cached in  memory,
1064              we don't need to read them from the disk.  SIZE can include K or
1065              M (1K = 1024, 1M = 1024K). Default: 16M
1066
1067       --download-result=<OPT>
1068              This option changes the way Download Results  is  formatted.  If
1069              OPT  is  default,  print GID, status, average download speed and
1070              path/URI. If multiple files  are  involved,  path/URI  of  first
1071              requested  file  is  printed and remaining ones are omitted.  If
1072              OPT is full, print GID, status, average download speed, percent‐
1073              age  of  progress  and  path/URI. The percentage of progress and
1074              path/URI are printed for each requested file in  each  row.   If
1075              OPT is hide, Download Results is hidden.  Default: default
1076
1077       --dscp=<DSCP>
1078              Set  DSCP value in outgoing IP packets of BitTorrent traffic for
1079              QoS. This parameter sets only DSCP bits in TOS field of IP pack‐
1080              ets,   not   the   whole   field.   If   you  take  values  from
1081              /usr/include/netinet/ip.h divide them  by  4  (otherwise  values
1082              would be incorrect, e.g. your CS1 class would turn into CS4). If
1083              you take commonly used values from RFC, network  vendors'  docu‐
1084              mentation, Wikipedia or any other source, use them as they are.
1085
1086       --rlimit-nofile=<NUM>
1087              Set  the  soft  limit  of open file descriptors.  This open will
1088              only have effect when:
1089
1090                 a. The system supports it (posix)
1091
1092                 b. The limit does not exceed the hard limit.
1093
1094                 c. The specified limit is larger than the current soft limit.
1095
1096              This is equivalent to setting nofile via ulimit, except that  it
1097              will never decrease the limit.
1098
1099              This  option  is only available on systems supporting the rlimit
1100              API.
1101
1102       --enable-color [true|false]
1103              Enable color output for a terminal.  Default: true
1104
1105       --enable-mmap [true|false]
1106              Map files into memory. This option may  not  work  if  the  file
1107              space is not pre-allocated. See --file-allocation.
1108
1109              Default: false
1110
1111       --event-poll=<POLL>
1112              Specify  the method for polling events.  The possible values are
1113              epoll, kqueue, port, poll and select.  For each  epoll,  kqueue,
1114              port  and poll, it is available if system supports it.  epoll is
1115              available on recent Linux. kqueue is available on  various  *BSD
1116              systems  including  Mac OS X. port is available on Open Solaris.
1117              The default value may vary depending on the system you use.
1118
1119       --file-allocation=<METHOD>
1120              Specify file allocation method.  none doesn't pre-allocate  file
1121              space. prealloc pre-allocates file space before download begins.
1122              This may take some time depending on the size of the  file.   If
1123              you are using newer file systems such as ext4 (with extents sup‐
1124              port), btrfs, xfs or NTFS(MinGW build only), falloc is your best
1125              choice.  It  allocates  large(few  GiB)  files almost instantly.
1126              Don't use falloc with legacy file systems such as ext3 and FAT32
1127              because  it  takes  almost  same  time as prealloc and it blocks
1128              aria2 entirely until allocation  finishes.  falloc  may  not  be
1129              available  if  your system doesn't have posix_fallocate(3) func‐
1130              tion.  trunc uses ftruncate(2) system call or  platform-specific
1131              counterpart to truncate a file to a specified length.
1132
1133              Possible Values: none, prealloc, trunc, falloc Default: prealloc
1134
1135              WARNING:
1136                 Using  trunc seemingly allocates disk space very quickly, but
1137                 what it actually does is that it sets file length metadata in
1138                 file  system,  and does not allocate disk space at all.  This
1139                 means that it does not help avoiding fragmentation.
1140
1141              NOTE:
1142                 In multi file torrent downloads, the files  adjacent  forward
1143                 to  the  specified files are also allocated if they share the
1144                 same piece.
1145
1146       --force-save [true|false]
1147              Save download with --save-session option even if the download is
1148              completed  or  removed.  This  option also saves control file in
1149              that situations. This may be useful to save  BitTorrent  seeding
1150              which is recognized as completed state.  Default: false
1151
1152       --save-not-found [true|false]
1153              Save  download  with  --save-session option even if the file was
1154              not found on the server. This option also saves control file  in
1155              that situations.  Default: true
1156
1157       --gid=<GID>
1158              Set  GID  manually.  aria2  identifies  each  download by the ID
1159              called GID. The GID must be hex string of  16  characters,  thus
1160              [0-9a-fA-F]  are allowed and leading zeros must not be stripped.
1161              The GID all 0 is reserved and must not be used. The GID must  be
1162              unique,  otherwise  error  is  reported  and the download is not
1163              added.  This option is useful when restoring the sessions  saved
1164              using --save-session option. If this option is not used, new GID
1165              is generated by aria2.
1166
1167       --hash-check-only [true|false]
1168              If true is  given,  after  hash  check  using  --check-integrity
1169              option,  abort  download  whether  or  not download is complete.
1170              Default: false
1171
1172       --human-readable [true|false]
1173              Print sizes and speed in human  readable  format  (e.g.,  1.2Ki,
1174              3.4Mi) in the console readout. Default: true
1175
1176       --interface=<INTERFACE>
1177              Bind sockets to given interface. You can specify interface name,
1178              IP address  and  host  name.   Possible  Values:  interface,  IP
1179              address, host name
1180
1181              NOTE:
1182                 If  an  interface has multiple addresses, it is highly recom‐
1183                 mended  to  specify   IP   address   explicitly.   See   also
1184                 --disable-ipv6.   If  your system doesn't have getifaddrs(3),
1185                 this option doesn't accept interface name.
1186
1187       --keep-unfinished-download-result [true|false]
1188              Keep unfinished  download  results  even  if  doing  so  exceeds
1189              --max-download-result.   This  is useful if all unfinished down‐
1190              loads must be saved in session file (see --save-session option).
1191              Please  keep  in mind that there is no upper bound to the number
1192              of unfinished download result to keep.  If that is  undesirable,
1193              turn this option off.  Default: true
1194
1195       --max-download-result=<NUM>
1196              Set  maximum number of download result kept in memory. The down‐
1197              load results are completed/error/removed downloads. The download
1198              results  are  stored  in FIFO queue and it can store at most NUM
1199              download results. When queue is full and new download result  is
1200              created, oldest download result is removed from the front of the
1201              queue and new one is pushed to the back. Setting big  number  in
1202              this  option  may result high memory consumption after thousands
1203              of downloads. Specifying 0 means no  download  result  is  kept.
1204              Note  that unfinished downloads are kept in memory regardless of
1205              this option value. See --keep-unfinished-download-result option.
1206              Default: 1000
1207
1208       --max-mmap-limit=<SIZE>
1209              Set  the  maximum  file  size  to enable mmap (see --enable-mmap
1210              option). The file size is determined by the  sum  of  all  files
1211              contained in one download. For example, if a download contains 5
1212              files, then file size is the total size of those files. If  file
1213              size is strictly greater than the size specified in this option,
1214              mmap will be disabled.  Default: 9223372036854775807
1215
1216       --max-resume-failure-tries=<N>
1217              When used with --always-resume=false, aria2 downloads file  from
1218              scratch  when  aria2 detects N number of URIs that does not sup‐
1219              port resume. If N is 0, aria2 downloads file from  scratch  when
1220              all  given  URIs  do  not  support  resume.  See --always-resume
1221              option.  Default: 0
1222
1223       --min-tls-version=<VERSION>
1224              Specify minimum SSL/TLS version  to  enable.   Possible  Values:
1225              TLSv1.1, TLSv1.2, TLSv1.3 Default: TLSv1.2
1226
1227       --multiple-interface=<INTERFACES>
1228              Comma  separated list of interfaces to bind sockets to. Requests
1229              will be splited among the interfaces to  achieve  link  aggrega‐
1230              tion.  You  can specify interface name, IP address and hostname.
1231              If --interface is used, this option will be  ignored.   Possible
1232              Values: interface, IP address, hostname
1233
1234       --log-level=<LEVEL>
1235              Set  log  level to output.  LEVEL is either debug, info, notice,
1236              warn or error.  Default: debug
1237
1238       --on-bt-download-complete=<COMMAND>
1239              For BitTorrent, a command specified in --on-download-complete is
1240              called  after  download  completed  and  seeding is over. On the
1241              other hand, this option set the command  to  be  executed  after
1242              download  completed but before seeding.  See Event Hook for more
1243              details about COMMAND.  Possible Values: /path/to/command
1244
1245       --on-download-complete=<COMMAND>
1246              Set the command to be executed after  download  completed.   See
1247              Event   Hook   for   more   details  about  COMMAND.   See  also
1248              --on-download-stop option.  Possible Values: /path/to/command
1249
1250       --on-download-error=<COMMAND>
1251              Set the command to be executed after  download  aborted  due  to
1252              error.  See Event Hook for more details about COMMAND.  See also
1253              --on-download-stop option.  Possible Values: /path/to/command
1254
1255       --on-download-pause=<COMMAND>
1256              Set the command to be executed after download was  paused.   See
1257              Event  Hook  for  more  details about COMMAND.  Possible Values:
1258              /path/to/command
1259
1260       --on-download-start=<COMMAND>
1261              Set the command to be executed after download got started.   See
1262              Event  Hook  for  more  details about COMMAND.  Possible Values:
1263              /path/to/command
1264
1265       --on-download-stop=<COMMAND>
1266              Set the command to be executed after download stopped.  You  can
1267              override  the  command  to  be  executed for particular download
1268              result using --on-download-complete and --on-download-error.  If
1269              they are specified, command specified in this option is not exe‐
1270              cuted.  See Event Hook for more details about COMMAND.  Possible
1271              Values: /path/to/command
1272
1273       --optimize-concurrent-downloads [true|false|<A>:<B>]
1274              Optimizes  the  number  of concurrent downloads according to the
1275              bandwidth available. aria2 uses the download speed  observed  in
1276              the previous downloads to adapt the number of downloads launched
1277              in parallel according to the rule N  =  A  +  B  Log10(speed  in
1278              Mbps).  The coefficients A and B can be customized in the option
1279              arguments with A and B separated by a colon. The default  values
1280              (A=5,  B=25)  lead  to  using  typically 5 parallel downloads on
1281              1Mbps networks and above 50 on 100Mbps networks. The  number  of
1282              parallel downloads remains constrained under the maximum defined
1283              by the --max-concurrent-downloads parameter.  Default: false
1284
1285       --piece-length=<LENGTH>
1286              Set a piece length for HTTP/FTP downloads. This is the  boundary
1287              when  aria2  splits a file. All splits occur at multiple of this
1288              length. This option will be ignored in BitTorrent downloads.  It
1289              will  be  also  ignored  if Metalink file contains piece hashes.
1290              Default: 1M
1291
1292              NOTE:
1293                 The possible use case of --piece-length option is change  the
1294                 request  range in one HTTP pipelined request.  To enable HTTP
1295                 pipelining use --enable-http-pipelining.
1296
1297       --show-console-readout [true|false]
1298              Show console readout. Default: true
1299
1300       --stderr [true|false]
1301              Redirect all console output that would be otherwise  printed  in
1302              stdout to stderr.  Default: false
1303
1304       --summary-interval=<SEC>
1305              Set  interval  in  seconds  to output download progress summary.
1306              Setting 0 suppresses the output.  Default: 60
1307
1308       -Z, --force-sequential [true|false]
1309              Fetch URIs in the command-line sequentially  and  download  each
1310              URI  in a separate session, like the usual command-line download
1311              utilities.  Default: false
1312
1313       --max-overall-download-limit=<SPEED>
1314              Set max overall download speed  in  bytes/sec.   0  means  unre‐
1315              stricted.   You  can  append K or M (1K = 1024, 1M = 1024K).  To
1316              limit the download speed per download, use  --max-download-limit
1317              option.  Default: 0
1318
1319       --max-download-limit=<SPEED>
1320              Set  max  download speed per each download in bytes/sec. 0 means
1321              unrestricted.  You can append K or M (1K = 1024,  1M  =  1024K).
1322              To     limit     the     overall     download     speed,     use
1323              --max-overall-download-limit option.  Default: 0
1324
1325       --no-conf [true|false]
1326              Disable loading aria2.conf file.
1327
1328       --no-file-allocation-limit=<SIZE>
1329              No file allocation is made for files whose size is smaller  than
1330              SIZE.   You can append K or M (1K = 1024, 1M = 1024K).  Default:
1331              5M
1332
1333       -P, --parameterized-uri [true|false]
1334              Enable parameterized URI support.  You can specify set of parts:
1335              http://{sv1,sv2,sv3}/foo.iso.   Also  you  can  specify  numeric
1336              sequences with step  counter:  http://host/image[000-100:2].img.
1337              A  step counter can be omitted.  If all URIs do not point to the
1338              same file, such as  the  second  example  above,  -Z  option  is
1339              required.  Default: false
1340
1341       -q, --quiet [true|false]
1342              Make aria2 quiet (no console output).  Default: false
1343
1344       --realtime-chunk-checksum [true|false]
1345              Validate chunk of data by calculating checksum while downloading
1346              a file if chunk checksums are provided.  Default: true
1347
1348       --remove-control-file [true|false]
1349              Remove   control    file    before    download.    Using    with
1350              --allow-overwrite=true,  download  always  starts  from scratch.
1351              This will be useful for users behind proxy server which disables
1352              resume.
1353
1354       --save-session=<FILE>
1355              Save  error/unfinished  downloads to FILE on exit.  You can pass
1356              this output file to aria2c with --input-file option on  restart.
1357              If  you  like the output to be gzipped append a .gz extension to
1358              the  file  name.   Please   note   that   downloads   added   by
1359              aria2.addTorrent()  and aria2.addMetalink() RPC method and whose
1360              meta data could not be saved as a file are not saved.  Downloads
1361              removed using aria2.remove() and aria2.forceRemove() will not be
1362              saved. GID is also saved with gid, but there are  some  restric‐
1363              tions, see below.
1364
1365              NOTE:
1366                 Normally, GID of the download itself is saved. But some down‐
1367                 loads use meta data (e.g., BitTorrent and Metalink). In  this
1368                 case, there are some restrictions.
1369
1370                 magnet URI, and followed by torrent download
1371                        GID of BitTorrent meta data download is saved.
1372
1373                 URI to torrent file, and followed by torrent download
1374                        GID of torrent file download is saved.
1375
1376                 URI   to  metalink  file,  and  followed  by  file  downloads
1377                 described in metalink file
1378                        GID of metalink file download is saved.
1379
1380                 local torrent file
1381                        GID of torrent download is saved.
1382
1383                 local metalink file
1384                        Any meaningful GID is not saved.
1385
1386       --save-session-interval=<SEC>
1387              Save  error/unfinished  downloads  to  a   file   specified   by
1388              --save-session  option  every  SEC  seconds. If 0 is given, file
1389              will be saved only when aria2 exits. Default: 0
1390
1391       --socket-recv-buffer-size=<SIZE>
1392              Set the maximum socket receive buffer in  bytes.   Specifying  0
1393              will  disable this option. This value will be set to socket file
1394              descriptor using SO_RCVBUF socket option with setsockopt() call.
1395              Default: 0
1396
1397       --stop=<SEC>
1398              Stop  application  after SEC seconds has passed.  If 0 is given,
1399              this feature is disabled.  Default: 0
1400
1401       --stop-with-process=<PID>
1402              Stop application when process PID is not running.  This is  use‐
1403              ful if aria2 process is forked from a parent process. The parent
1404              process can fork aria2 with its own pid and when parent  process
1405              exits for some reason, aria2 can detect it and shutdown itself.
1406
1407       --truncate-console-readout [true|false]
1408              Truncate console readout to fit in a single line.  Default: true
1409
1410       -v, --version
1411              Print the version number, copyright and the configuration infor‐
1412              mation and exit.
1413
1414   Notes for Options
1415   Optional arguments
1416       The options that have its argument surrounded  by  square  brackets([])
1417       take  an  optional argument. Usually omitting the argument is evaluated
1418       to true.  If you use short form of these options(such as -V)  and  give
1419       an  argument,  then the option name and its argument should be concate‐
1420       nated(e.g.  -Vfalse). If any spaces are  inserted  between  the  option
1421       name  and the argument, the argument will be treated as URI and usually
1422       this is not what you expect.
1423
1424   Units (K and M)
1425       Some options takes K and M to conveniently represent 1024  and  1048576
1426       respectively.   aria2 detects these characters in case-insensitive way.
1427       In other words, k and m can be used as well as K and M respectively.
1428
1429   URI, MAGNET, TORRENT_FILE, METALINK_FILE
1430       You can specify multiple URIs  in  command-line.   Unless  you  specify
1431       --force-sequential  option,  all  URIs  must  point to the same file or
1432       downloading will fail.
1433
1434       You can specify arbitrary number of BitTorrent Magnet URI. Please  note
1435       that  they are always treated as a separate download.  Both hex encoded
1436       40 characters Info Hash and Base32 encoded 32 characters Info Hash  are
1437       supported.  The  multiple tr parameters are supported.  Because BitTor‐
1438       rent Magnet URI is likely to contain & character, it is  highly  recom‐
1439       mended  to  always quote URI with single(') or double(") quotation.  It
1440       is strongly recommended to enable DHT especially when tr  parameter  is
1441       missing.   See  http://www.bittorrent.org/beps/bep_0009.html  for  more
1442       details about BitTorrent Magnet URI.
1443
1444       You can also specify arbitrary number of  torrent  files  and  Metalink
1445       documents  stored  on  a  local drive. Please note that they are always
1446       treated as a separate download. Both Metalink4 and Metalink version 3.0
1447       are supported.
1448
1449       You  can  specify  both  torrent file with -T option and URIs. By doing
1450       this,  you  can  download  a  file  from   both   torrent   swarm   and
1451       HTTP(S)/FTP/SFTP   server  at  the  same  time,  while  the  data  from
1452       HTTP(S)/FTP/SFTP are uploaded to the torrent swarm.   For  single  file
1453       torrents,  URI can be a complete URI pointing to the resource or if URI
1454       ends with /, name in torrent file in torrent is added.  For  multi-file
1455       torrents, name and path are added to form a URI for each file.
1456
1457       NOTE:
1458          Make  sure  that URI is quoted with single(') or double(") quotation
1459          if it contains & or any characters  that  have  special  meaning  in
1460          shell.
1461
1462   Resuming Download
1463       Usually,  you  can resume transfer by just issuing same command (aria2c
1464       URI) if the previous transfer is made by aria2.
1465
1466       If the previous transfer is made by a browser or wget  like  sequential
1467       download manager, then use --continue option to continue the transfer.
1468
1469   Event Hook
1470       aria2  provides  options  to  specify  arbitrary command after specific
1471       event   occurred.   Currently   following   options   are    available:
1472       --on-bt-download-complete, --on-download-pause, --on-download-complete.
1473       --on-download-start, --on-download-error, --on-download-stop.
1474
1475       aria2 passes 3 arguments to specified  command  when  it  is  executed.
1476       These arguments are: GID, the number of files and file path.  For HTTP,
1477       FTP, and SFTP downloads, usually the number of files is 1.   BitTorrent
1478       download  can  contain multiple files.  If number of files is more than
1479       one, file path is first one.  In other words, this is the value of path
1480       key  of  first  struct  whose  selected  key is true in the response of
1481       aria2.getFiles() RPC method.  If you want to get all file  paths,  con‐
1482       sider  to  use JSON-RPC/XML-RPC.  Please note that file path may change
1483       during download in HTTP because of redirection  or  Content-Disposition
1484       header.
1485
1486       Let's see an example of how arguments are passed to command:
1487
1488          $ cat hook.sh
1489          #!/bin/sh
1490          echo "Called with [$1] [$2] [$3]"
1491          $ aria2c --on-download-complete hook.sh http://example.org/file.iso
1492          Called with [1] [1] [/path/to/file.iso]
1493

EXIT STATUS

1495       Because aria2 can handle multiple downloads at once, it encounters lots
1496       of errors in a session.  aria2 returns the following exit status  based
1497       on the last error encountered.
1498
1499       0      If all downloads were successful.
1500
1501       1      If an unknown error occurred.
1502
1503       2      If time out occurred.
1504
1505       3      If a resource was not found.
1506
1507       4      If aria2 saw the specified number of "resource not found" error.
1508              See --max-file-not-found option.
1509
1510       5      If a download aborted because download speed was too slow.   See
1511              --lowest-speed-limit option.
1512
1513       6      If network problem occurred.
1514
1515       7      If  there were unfinished downloads. This error is only reported
1516              if all finished downloads were successful and there were  unfin‐
1517              ished  downloads in a queue when aria2 exited by pressing Ctrl-C
1518              by an user or sending TERM or INT signal.
1519
1520       8      If remote server did not support resume when resume was required
1521              to complete download.
1522
1523       9      If there was not enough disk space available.
1524
1525       10     If  piece  length was different from one in .aria2 control file.
1526              See --allow-piece-length-change option.
1527
1528       11     If aria2 was downloading same file at that moment.
1529
1530       12     If aria2 was downloading same info hash torrent at that moment.
1531
1532       13     If file already existed. See --allow-overwrite option.
1533
1534       14     If renaming file failed. See --auto-file-renaming option.
1535
1536       15     If aria2 could not open existing file.
1537
1538       16     If aria2 could not create new file or truncate existing file.
1539
1540       17     If file I/O error occurred.
1541
1542       18     If aria2 could not create directory.
1543
1544       19     If name resolution failed.
1545
1546       20     If aria2 could not parse Metalink document.
1547
1548       21     If FTP command failed.
1549
1550       22     If HTTP response header was bad or unexpected.
1551
1552       23     If too many redirects  occurred.
1553
1554       24     If HTTP authorization failed.
1555
1556       25     If aria2 could  not  parse  bencoded  file  (usually  ".torrent"
1557              file).
1558
1559       26     If  ".torrent"  file  was  corrupted or missing information that
1560              aria2 needed.
1561
1562       27     If Magnet URI was bad.
1563
1564       28     If bad/unrecognized option was given or unexpected option  argu‐
1565              ment was given.
1566
1567       29     If  the  remote server was unable to handle the request due to a
1568              temporary overloading or maintenance.
1569
1570       30     If aria2 could not parse JSON-RPC request.
1571
1572       31     Reserved.  Not used.
1573
1574       32     If checksum validation failed.
1575
1576       NOTE:
1577          An error occurred in a finished download will  not  be  reported  as
1578          exit status.
1579

ENVIRONMENT

1581       aria2 recognizes the following environment variables.
1582
1583       http_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1584              Specify  proxy  server  for  use  in HTTP.  Overrides http-proxy
1585              value  in   configuration   file.    The   command-line   option
1586              --http-proxy overrides this value.
1587
1588       https_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1589              Specify  proxy  server  for use in HTTPS.  Overrides https-proxy
1590              value  in   configuration   file.    The   command-line   option
1591              --https-proxy overrides this value.
1592
1593       ftp_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1594              Specify  proxy server for use in FTP.  Overrides ftp-proxy value
1595              in configuration  file.   The  command-line  option  --ftp-proxy
1596              overrides this value.
1597
1598       all_proxy [http://][USER:PASSWORD@]HOST[:PORT]
1599              Specify  proxy  server  for use if no protocol-specific proxy is
1600              specified.  Overrides all-proxy  value  in  configuration  file.
1601              The command-line option --all-proxy overrides this value.
1602
1603       NOTE:
1604          Although  aria2  accepts ftp:// and https:// scheme in proxy URI, it
1605          simply assumes that http:// is specified and  does  not  change  its
1606          behavior based on the specified scheme.
1607
1608       no_proxy [DOMAIN,...]
1609              Specify  a  comma-separated list of host names, domains and net‐
1610              work addresses with or without a  subnet  mask  where  no  proxy
1611              should  be  used.  Overrides the no-proxy value in configuration
1612              file.  The command-line option --no-proxy overrides this value.
1613

FILES

1615   aria2.conf
1616       By    default,    aria2    checks    whether    the     legacy     path
1617       $HOME/.aria2/aria2.conf  is  present,  otherwise  it  parses  $XDG_CON‐
1618       FIG_HOME/aria2/aria2.conf as its configuration file.  You  can  specify
1619       the  path to configuration file using --conf-path option.  If you don't
1620       want to use the configuration file, use --no-conf option.
1621
1622       The configuration file is a text file and has 1 option per  each  line.
1623       In   each  line,  you  can  specify  name-value  pair  in  the  format:
1624       NAME=VALUE, where name is the long command-line option name without  --
1625       prefix.  You can use same syntax for the command-line option. The lines
1626       beginning # are treated as comments:
1627
1628          # sample configuration file for aria2c
1629          listen-port=60000
1630          dht-listen-port=60000
1631          seed-ratio=1.0
1632          max-upload-limit=50K
1633          ftp-pasv=true
1634
1635       NOTE:
1636          The confidential information such as user/password might be included
1637          in  the  configuration  file.  It is recommended to change file mode
1638          bits of the configuration file (e.g., chmod 600 aria2.conf), so that
1639          other user cannot see the contents of the file.
1640
1641       The  environment  variables,  such  as  ${HOME}, are expanded by shell.
1642       This means that those variables used  in  configuration  file  are  not
1643       expanded.  However, it is useful to ${HOME} to refer user's home direc‐
1644       tory in configuration file to specify  file  paths.   Therefore,  aria2
1645       expands  ${HOME}  found  in  the following option values to user's home
1646       directory:
1647
1648       · ca-certificate
1649
1650       · certificate
1651
1652       · dht-file-path
1653
1654       · dht-file-path6
1655
1656       · dir
1657
1658       · input-file
1659
1660       · load-cookies
1661
1662       · log
1663
1664       · metalink-file
1665
1666       · netrc-path
1667
1668       · on-bt-download-complete
1669
1670       · on-download-complete
1671
1672       · on-download-error
1673
1674       · on-download-start
1675
1676       · on-download-stop
1677
1678       · on-download-pause
1679
1680       · out
1681
1682       · private-key
1683
1684       · rpc-certificate
1685
1686       · rpc-private-key
1687
1688       · save-cookies
1689
1690       · save-session
1691
1692       · server-stat-if
1693
1694       · server-stat-of
1695
1696       · torrent-file
1697
1698       Note that this expansion occurs even if the above options are  used  in
1699       the  command-line.  This means that expansion may occur 2 times: first,
1700       shell and then aria2c.
1701
1702   dht.dat
1703       Unless    the    legacy    file    paths    $HOME/.aria2/dht.dat    and
1704       $HOME/.aria2/dht6.dat are pointing to existing files, the routing table
1705       of IPv4 DHT is saved to the path $XDG_CACHE_HOME/aria2/dht.dat and  the
1706       routing    table    of    IPv6    DHT    is    saved    to   the   path
1707       $XDG_CACHE_HOME/aria2/dht6.dat.
1708
1709   Netrc
1710       Netrc support is enabled by default for HTTP(S)/FTP/SFTP.   To  disable
1711       netrc support, specify --no-netrc option.  Your .netrc file should have
1712       correct permissions(600).
1713
1714       If machine name starts ., aria2 performs domain-match instead of  exact
1715       match.  This  is  an  extension  of aria2. For example of domain match,
1716       imagine the following .netrc entry:
1717
1718          machine .example.org login myid password mypasswd
1719
1720       aria2.example.org  domain-matches  .example.org  and  uses   myid   and
1721       mypasswd.
1722
1723       Some  domain-match  example  follow:  example.net does not domain-match
1724       .example.org. example.org does not domain-match .example.org because of
1725       preceding .. If you want to match example.org, specify example.org.
1726
1727   Control File
1728       aria2  uses a control file to track the progress of a download.  A con‐
1729       trol file is placed in the same directory as the downloading  file  and
1730       its  file  name  is  the  file  name  of  downloading  file with .aria2
1731       appended.  For example, if you are downloading file.zip, then the  con‐
1732       trol  file  should  be  file.zip.aria2.  (There is a exception for this
1733       naming convention.  If you are downloading a multi torrent, its control
1734       file  is  the "top directory" name of the torrent with .aria2 appended.
1735       The "top directory" name is a value of "name" key in  "info"  directory
1736       in a torrent file.)
1737
1738       Usually  a  control  file is deleted once download completed.  If aria2
1739       decides that download cannot be resumed(for example, when downloading a
1740       file  from  a HTTP server which doesn't support resume), a control file
1741       is not created.
1742
1743       Normally if you lose a control file, you cannot resume  download.   But
1744       if  you  have  a torrent or metalink with chunk checksums for the file,
1745       you can resume the download without a control file by giving -V  option
1746       to aria2c in command-line.
1747
1748   Input File
1749       The  input  file can contain a list of URIs for aria2 to download.  You
1750       can specify multiple URIs for a single entity: separate URIs on a  sin‐
1751       gle line using the TAB character.
1752
1753       Each  line  is  treated  as if it is provided in command-line argument.
1754       Therefore    they    are    affected    by    --force-sequential    and
1755       --parameterized-uri options.
1756
1757       Since  URIs in the input file are directly read by aria2, they must not
1758       be quoted with single(') or double(") quotation.
1759
1760       Lines starting with # are treated as comments and skipped.
1761
1762       Additionally, the following options can be specified after each line of
1763       URIs. These optional lines must start with white space(s).
1764
1765         · all-proxy
1766
1767         · all-proxy-passwd
1768
1769         · all-proxy-user
1770
1771         · allow-overwrite
1772
1773         · allow-piece-length-change
1774
1775         · always-resume
1776
1777         · async-dns
1778
1779         · auto-file-renaming
1780
1781         · bt-enable-hook-after-hash-check
1782
1783         · bt-enable-lpd
1784
1785         · bt-exclude-tracker
1786
1787         · bt-external-ip
1788
1789         · bt-force-encryption
1790
1791         · bt-hash-check-seed
1792
1793         · bt-load-saved-metadata
1794
1795         · bt-max-peers
1796
1797         · bt-metadata-only
1798
1799         · bt-min-crypto-level
1800
1801         · bt-prioritize-piece
1802
1803         · bt-remove-unselected-file
1804
1805         · bt-request-peer-speed-limit
1806
1807         · bt-require-crypto
1808
1809         · bt-save-metadata
1810
1811         · bt-seed-unverified
1812
1813         · bt-stop-timeout
1814
1815         · bt-tracker
1816
1817         · bt-tracker-connect-timeout
1818
1819         · bt-tracker-interval
1820
1821         · bt-tracker-timeout
1822
1823         · check-integrity
1824
1825         · checksum
1826
1827         · conditional-get
1828
1829         · connect-timeout
1830
1831         · content-disposition-default-utf8
1832
1833         · continue
1834
1835         · dir
1836
1837         · dry-run
1838
1839         · enable-http-keep-alive
1840
1841         · enable-http-pipelining
1842
1843         · enable-mmap
1844
1845         · enable-peer-exchange
1846
1847         · file-allocation
1848
1849         · follow-metalink
1850
1851         · follow-torrent
1852
1853         · force-save
1854
1855         · ftp-passwd
1856
1857         · ftp-pasv
1858
1859         · ftp-proxy
1860
1861         · ftp-proxy-passwd
1862
1863         · ftp-proxy-user
1864
1865         · ftp-reuse-connection
1866
1867         · ftp-type
1868
1869         · ftp-user
1870
1871         · gid
1872
1873         · hash-check-only
1874
1875         · header
1876
1877         · http-accept-gzip
1878
1879         · http-auth-challenge
1880
1881         · http-no-cache
1882
1883         · http-passwd
1884
1885         · http-proxy
1886
1887         · http-proxy-passwd
1888
1889         · http-proxy-user
1890
1891         · http-user
1892
1893         · https-proxy
1894
1895         · https-proxy-passwd
1896
1897         · https-proxy-user
1898
1899         · index-out
1900
1901         · lowest-speed-limit
1902
1903         · max-connection-per-server
1904
1905         · max-download-limit
1906
1907         · max-file-not-found
1908
1909         · max-mmap-limit
1910
1911         · max-resume-failure-tries
1912
1913         · max-tries
1914
1915         · max-upload-limit
1916
1917         · metalink-base-uri
1918
1919         · metalink-enable-unique-protocol
1920
1921         · metalink-language
1922
1923         · metalink-location
1924
1925         · metalink-os
1926
1927         · metalink-preferred-protocol
1928
1929         · metalink-version
1930
1931         · min-split-size
1932
1933         · no-file-allocation-limit
1934
1935         · no-netrc
1936
1937         · no-proxy
1938
1939         · out
1940
1941         · parameterized-uri
1942
1943         · pause
1944
1945         · pause-metadata
1946
1947         · piece-length
1948
1949         · proxy-method
1950
1951         · realtime-chunk-checksum
1952
1953         · referer
1954
1955         · remote-time
1956
1957         · remove-control-file
1958
1959         · retry-wait
1960
1961         · reuse-uri
1962
1963         · rpc-save-upload-metadata
1964
1965         · seed-ratio
1966
1967         · seed-time
1968
1969         · select-file
1970
1971         · split
1972
1973         · ssh-host-key-md
1974
1975         · stream-piece-selector
1976
1977         · timeout
1978
1979         · uri-selector
1980
1981         · use-head
1982
1983         · user-agent
1984
1985       These options have exactly same meaning of the ones in the command-line
1986       options, but it just applies to the URIs it belongs  to.   Please  note
1987       that for options in input file -- prefix must be stripped.
1988
1989       For example, the content of uri.txt is:
1990
1991          http://server/file.iso http://mirror/file.iso
1992            dir=/iso_images
1993            out=file.img
1994          http://foo/bar
1995
1996       If  aria2 is executed with -i uri.txt -d /tmp options, then file.iso is
1997       saved   as   /iso_images/file.img   and   it   is    downloaded    from
1998       http://server/file.iso  and  http://mirror/file.iso.   The  file bar is
1999       downloaded from http://foo/bar and saved as /tmp/bar.
2000
2001       In some cases, out parameter has no effect.  See note of  --out  option
2002       for the restrictions.
2003
2004   Server Performance Profile
2005       This  section  describes the format of server performance profile.  The
2006       file is plain text and each line has several NAME=VALUE pair, delimited
2007       by comma.  Currently following NAMEs are recognized:
2008
2009       host   Host name of the server. Required.
2010
2011       protocol
2012              Protocol for this profile, such as ftp, http. Required.
2013
2014       dl_speed
2015              The  average download speed observed in the previous download in
2016              bytes per sec.  Required.
2017
2018       sc_avg_speed
2019              The average download speed observed in the previous download  in
2020              bytes  per  sec.  This  value is only updated if the download is
2021              done in single connection environment and  only  used  by  Adap‐
2022              tiveURISelector. Optional.
2023
2024       mc_avg_speed
2025              The  average download speed observed in the previous download in
2026              bytes per sec. This value is only updated  if  the  download  is
2027              done  in  multi  connection  environment  and only used by Adap‐
2028              tiveURISelector. Optional.
2029
2030       counter
2031              How many times the server is used. Currently this value is  only
2032              used by AdaptiveURISelector.  Optional.
2033
2034       last_updated
2035              Last contact time in GMT with this server, specified in the sec‐
2036              onds  since  the  Epoch(00:00:00  on  January  1,  1970,   UTC).
2037              Required.
2038
2039       status ERROR  is set when server cannot be reached or out-of-service or
2040              timeout occurred. Otherwise, OK is set.
2041
2042       Those fields must exist in one line. The order of  the  fields  is  not
2043       significant.  You  can  put pairs other than the above; they are simply
2044       ignored.
2045
2046       An example follows:
2047
2048          host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=OK
2049          host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
2050

RPC INTERFACE

2052       aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP interfaces that
2053       offer  basically  the same functionality.  aria2 also provides JSON-RPC
2054       over WebSocket. JSON-RPC over WebSocket uses the same method signatures
2055       and  response  format  as JSON-RPC over HTTP, but additionally provides
2056       server-initiated notifications. See JSON-RPC over WebSocket section for
2057       more information.
2058
2059       The request path of the JSON-RPC interface (for both over HTTP and over
2060       WebSocket) is /jsonrpc.  The request path of the XML-RPC  interface  is
2061       /rpc.
2062
2063       The  WebSocket  URI for JSON-RPC over WebSocket is ws://HOST:PORT/json‐
2064       rpc. If you enabled  SSL/TLS  encryption,  use  wss://HOST:PORT/jsonrpc
2065       instead.
2066
2067       The    implemented    JSON-RPC    is   based   on   JSON-RPC   2.0   <‐
2068       http://jsonrpc.org/specification>,  and  supports  HTTP  POST  and  GET
2069       (JSONP).  The WebSocket transport is an aria2 extension.
2070
2071       The  JSON-RPC  interface  does not support notifications over HTTP, but
2072       the RPC server will send notifications over WebSocket. It also does not
2073       support floating point numbers. The character encoding must be UTF-8.
2074
2075       When  reading  the  following  documentation  for  JSON-RPC,  interpret
2076       structs as JSON objects.
2077
2078   Terminology
2079       GID
2080          The GID (or gid) is a key to manage  each  download.  Each  download
2081          will  be  assigned  a unique GID. The GID is stored as 64-bit binary
2082          value in aria2.  For RPC access, it is represented as a  hex  string
2083          of 16 characters (e.g., 2089b05ecca3d829). Normally, aria2 generates
2084          this GID for each download, but the user can specify  GIDs  manually
2085          using  the  --gid  option.  When  querying downloads by GID, you can
2086          specify only the prefix of a GID as long as it is unique among  oth‐
2087          ers.
2088
2089   RPC authorization secret token
2090       As  of  1.18.4, in addition to HTTP basic authorization, aria2 provides
2091       RPC method-level authorization. In a future release, HTTP basic  autho‐
2092       rization will be removed and RPC method-level authorization will become
2093       mandatory.
2094
2095       To use RPC method-level authorization, the user has to specify  an  RPC
2096       secret  authorization token using the --rpc-secret option. For each RPC
2097       method call, the caller has to include the token prefixed with  token:.
2098       Even  when  the --rpc-secret option is not used, if the first parameter
2099       in the RPC method is a string and starts with token:, it  will  removed
2100       from the parameter list before the request is being processed.
2101
2102       For example, if the RPC secret authorization token is $$secret$$, call‐
2103       ing aria2.addUri RPC method would have to look like this:
2104
2105          aria2.addUri("token:$$secret$$", ["http://example.org/file"])
2106
2107       The system.multicall RPC method is treated specially. Since the XML-RPC
2108       specification  only  allows  a  single  array  as  a parameter for this
2109       method, we don't specify the token in the call.  Instead,  each  nested
2110       method  call  has  to  provide  the  token  as  the  first parameter as
2111       described above.
2112
2113       NOTE:
2114          The secret token validation in aria2 is designed to take at least  a
2115          certain  amount  of  time to mitigate brute-force/dictionary attacks
2116          against the RPC interface. Therefore it  is  recommended  to  prefer
2117          Batch or system.multicall requests when appropriate.
2118
2119          system.listMethods  and  system.listNotifications  can  be  executed
2120          without token. Since they just  return  available  methods/notifica‐
2121          tions,  they  do  not  alter  anything,  they're safe without secret
2122          token.
2123
2124   Methods
2125       All code examples are compatible with the Python 2.7 interpreter.   For
2126       information  on  the  secret  parameter,  see  RPC authorization secret
2127       token.
2128
2129       aria2.addUri([secret], uris[, options[, position]])
2130              This  method  adds  a  new  download.  uris  is  an   array   of
2131              HTTP/FTP/SFTP/BitTorrent  URIs  (strings)  pointing  to the same
2132              resource.  If you mix URIs pointing to different resources, then
2133              the download may fail or be corrupted without aria2 complaining.
2134              When adding BitTorrent Magnet URIs, uris must have only one ele‐
2135              ment  and  it  should  be  BitTorrent  Magnet URI.  options is a
2136              struct and its members are pairs of option name and value.   See
2137              Options  below  for more details.  If position is given, it must
2138              be an integer starting from 0. The new download will be inserted
2139              at  position  in  the  waiting  queue. If position is omitted or
2140              position is larger than the current size of the queue,  the  new
2141              download  is  appended  to  the  end  of the queue.  This method
2142              returns the GID of the newly registered download.
2143
2144              JSON-RPC Example
2145
2146              The following example adds http://example.org/file:
2147
2148                 >>> import urllib2, json
2149                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2150                 ...                       'method':'aria2.addUri',
2151                 ...                       'params':[['http://example.org/file']]})
2152                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2153                 >>> c.read()
2154                 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2155
2156              XML-RPC Example
2157
2158              The following example adds http://example.org/file:
2159
2160                 >>> import xmlrpclib
2161                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2162                 >>> s.aria2.addUri(['http://example.org/file'])
2163                 '2089b05ecca3d829'
2164
2165              The following example adds a new download with two  sources  and
2166              some options:
2167
2168                 >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
2169                                     dict(dir="/tmp"))
2170                 'd2703803b52216d1'
2171
2172              The  following  example  adds  a  download and inserts it to the
2173              front of the queue:
2174
2175                 >>> s.aria2.addUri(['http://example.org/file'], {}, 0)
2176                 'ca3d829cee549a4d'
2177
2178       aria2.addTorrent([secret], torrent[, uris[, options[, position]]])
2179              This method adds a BitTorrent download by uploading a ".torrent"
2180              file.   If  you  want  to  add  a BitTorrent Magnet URI, use the
2181              aria2.addUri() method instead.  torrent must be a base64-encoded
2182              string  containing the contents of the ".torrent" file.  uris is
2183              an array of URIs (string). uris is used  for  Web-seeding.   For
2184              single  file torrents, the URI can be a complete URI pointing to
2185              the resource; if URI ends with /, name in torrent file is added.
2186              For  multi-file  torrents, name and path in torrent are added to
2187              form a URI for each file.  options is a struct and  its  members
2188              are  pairs of option name and value.  See Options below for more
2189              details.  If position is given, it must be an  integer  starting
2190              from  0.  The  new  download will be inserted at position in the
2191              waiting queue. If position is omitted or position is larger than
2192              the  current  size of the queue, the new download is appended to
2193              the end of the queue.  This method returns the GID of the  newly
2194              registered download.  If --rpc-save-upload-metadata is true, the
2195              uploaded data is saved as a file named  as  the  hex  string  of
2196              SHA-1 hash of data plus ".torrent" in the directory specified by
2197              --dir    option.     E.g.    a    file     name     might     be
2198              0a3893293e27ac0490424c06de4d09242215f0a6.torrent.    If  a  file
2199              with the same name already exists, it is  overwritten!   If  the
2200              file  cannot be saved successfully or --rpc-save-upload-metadata
2201              is false, the downloads added by this method are  not  saved  by
2202              --save-session.
2203
2204              The following examples add local file file.torrent.
2205
2206              JSON-RPC Example
2207
2208                 >>> import urllib2, json, base64
2209                 >>> torrent = base64.b64encode(open('file.torrent').read())
2210                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
2211                 ...                       'method':'aria2.addTorrent', 'params':[torrent]})
2212                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2213                 >>> c.read()
2214                 '{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2215
2216              XML-RPC Example
2217
2218                 >>> import xmlrpclib
2219                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2220                 >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
2221                 '2089b05ecca3d829'
2222
2223       aria2.addMetalink([secret], metalink[, options[, position]])
2224              This  method adds a Metalink download by uploading a ".metalink"
2225              file.  metalink is a base64-encoded string  which  contains  the
2226              contents  of  the ".metalink" file.  options is a struct and its
2227              members are pairs of option name and value.  See  Options  below
2228              for  more  details.  If position is given, it must be an integer
2229              starting from 0. The new download will be inserted  at  position
2230              in  the  waiting  queue.  If  position is omitted or position is
2231              larger than the current size of the queue, the new  download  is
2232              appended  to the end of the queue.  This method returns an array
2233              of    GIDs    of     newly     registered     downloads.      If
2234              --rpc-save-upload-metadata  is  true, the uploaded data is saved
2235              as a file named hex string of SHA-1 hash  of  data  plus  ".met‐
2236              alink"  in the directory specified by --dir option.  E.g. a file
2237              name might be 0a3893293e27ac0490424c06de4d09242215f0a6.metalink.
2238              If  a file with the same name already exists, it is overwritten!
2239              If    the    file    cannot    be    saved    successfully    or
2240              --rpc-save-upload-metadata is false, the downloads added by this
2241              method are not saved by --save-session.
2242
2243              The following examples add local file file.meta4.
2244
2245              JSON-RPC Example
2246
2247                 >>> import urllib2, json, base64
2248                 >>> metalink = base64.b64encode(open('file.meta4').read())
2249                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2250                 ...                       'method':'aria2.addMetalink',
2251                 ...                       'params':[metalink]})
2252                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2253                 >>> c.read()
2254                 '{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}'
2255
2256              XML-RPC Example
2257
2258                 >>> import xmlrpclib
2259                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2260                 >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4', mode='rb').read()))
2261                 ['2089b05ecca3d829']
2262
2263       aria2.remove([secret], gid)
2264              This method removes the download denoted by  gid  (string).   If
2265              the specified download is in progress, it is first stopped.  The
2266              status of the removed download  becomes  removed.   This  method
2267              returns GID of removed download.
2268
2269              The     following    examples    remove    a    download    with
2270              GID#2089b05ecca3d829.
2271
2272              JSON-RPC Example
2273
2274                 >>> import urllib2, json
2275                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2276                 ...                       'method':'aria2.remove',
2277                 ...                       'params':['2089b05ecca3d829']})
2278                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2279                 >>> c.read()
2280                 '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
2281
2282              XML-RPC Example
2283
2284                 >>> import xmlrpclib
2285                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2286                 >>> s.aria2.remove('2089b05ecca3d829')
2287                 '2089b05ecca3d829'
2288
2289       aria2.forceRemove([secret], gid)
2290              This method removes the download denoted by  gid.   This  method
2291              behaves just like aria2.remove() except that this method removes
2292              the download without performing any  actions  which  take  time,
2293              such  as  contacting BitTorrent trackers to unregister the down‐
2294              load first.
2295
2296       aria2.pause([secret], gid)
2297              This method pauses the download denoted by  gid  (string).   The
2298              status  of  paused download becomes paused.  If the download was
2299              active, the download is placed in the front  of  waiting  queue.
2300              While  the  status  is  paused, the download is not started.  To
2301              change status to waiting, use the aria2.unpause() method.   This
2302              method returns GID of paused download.
2303
2304       aria2.pauseAll([secret])
2305              This   method  is  equal  to  calling  aria2.pause()  for  every
2306              active/waiting download. This methods returns OK.
2307
2308       aria2.forcePause([secret], gid)
2309              This method pauses the download denoted  by  gid.   This  method
2310              behaves  just  like aria2.pause() except that this method pauses
2311              downloads without performing any actions which take  time,  such
2312              as  contacting  BitTorrent  trackers  to unregister the download
2313              first.
2314
2315       aria2.forcePauseAll([secret])
2316              This method is equal to  calling  aria2.forcePause()  for  every
2317              active/waiting download. This methods returns OK.
2318
2319       aria2.unpause([secret], gid)
2320              This  method  changes  the status of the download denoted by gid
2321              (string) from paused to waiting, making the download eligible to
2322              be restarted.  This method returns the GID of the unpaused down‐
2323              load.
2324
2325       aria2.unpauseAll([secret])
2326              This method is equal to calling aria2.unpause() for every paused
2327              download. This methods returns OK.
2328
2329       aria2.tellStatus([secret], gid[, keys])
2330              This  method returns the progress of the download denoted by gid
2331              (string).  keys is  an  array  of  strings.  If  specified,  the
2332              response  contains only keys in the keys array. If keys is empty
2333              or omitted, the response contains all keys. This is useful  when
2334              you  just  want  specific  keys and avoid unnecessary transfers.
2335              For example, aria2.tellStatus("2089b05ecca3d829", ["gid",  "sta‐
2336              tus"])  returns the gid and status keys only.  The response is a
2337              struct and contains following keys. Values are strings.
2338
2339              gid    GID of the download.
2340
2341              status active  for  currently   downloading/seeding   downloads.
2342                     waiting  for  downloads  in  the  queue;  download is not
2343                     started.  paused for paused downloads.  error  for  down‐
2344                     loads  that were stopped  because of error.  complete for
2345                     stopped and completed downloads.  removed for  the  down‐
2346                     loads removed by user.
2347
2348              totalLength
2349                     Total length of the download in bytes.
2350
2351              completedLength
2352                     Completed length of the download in bytes.
2353
2354              uploadLength
2355                     Uploaded length of the download in bytes.
2356
2357              bitfield
2358                     Hexadecimal  representation of the download progress. The
2359                     highest bit corresponds to the piece at index 0. Any  set
2360                     bits  indicate  loaded  pieces, while unset bits indicate
2361                     not yet loaded and/or missing pieces. Any  overflow  bits
2362                     at  the  end  are set to zero.  When the download was not
2363                     started yet,  this  key  will  not  be  included  in  the
2364                     response.
2365
2366              downloadSpeed
2367                     Download speed of this download measured in bytes/sec.
2368
2369              uploadSpeed
2370                     Upload speed of this download measured in bytes/sec.
2371
2372              infoHash
2373                     InfoHash. BitTorrent only.
2374
2375              numSeeders
2376                     The  number of seeders aria2 has connected to. BitTorrent
2377                     only.
2378
2379              seeder true if the local endpoint is a seeder. Otherwise  false.
2380                     BitTorrent only.
2381
2382              pieceLength
2383                     Piece length in bytes.
2384
2385              numPieces
2386                     The number of pieces.
2387
2388              connections
2389                     The number of peers/servers aria2 has connected to.
2390
2391              errorCode
2392                     The  code  of  the  last error for this item, if any. The
2393                     value is a string. The error codes  are  defined  in  the
2394                     EXIT  STATUS  section.   This value is only available for
2395                     stopped/completed downloads.
2396
2397              errorMessage
2398                     The (hopefully) human readable error  message  associated
2399                     to errorCode.
2400
2401              followedBy
2402                     List  of  GIDs  which are generated as the result of this
2403                     download. For example, when aria2  downloads  a  Metalink
2404                     file,  it  generates  downloads described in the Metalink
2405                     (see the --follow-metalink option). This value is  useful
2406                     to  track  auto-generated downloads. If there are no such
2407                     downloads, this key will not be included in the response.
2408
2409              following
2410                     The reverse link for followedBy.  A download included  in
2411                     followedBy has this object's GID in its following value.
2412
2413              belongsTo
2414                     GID  of  a  parent download. Some downloads are a part of
2415                     another download.  For example, if a file in  a  Metalink
2416                     has  BitTorrent  resources,  the  downloads of ".torrent"
2417                     files are parts of that parent.  If this download has  no
2418                     parent, this key will not be included in the response.
2419
2420              dir    Directory to save files.
2421
2422              files  Returns  the list of files. The elements of this list are
2423                     the same structs used in aria2.getFiles() method.
2424
2425              bittorrent
2426                     Struct which  contains  information  retrieved  from  the
2427                     .torrent  (file).  BitTorrent only. It contains following
2428                     keys.
2429
2430                     announceList
2431                            List of lists of announce  URIs.  If  the  torrent
2432                            contains  announce  and no announce-list, announce
2433                            is converted to the announce-list format.
2434
2435                     comment
2436                            The comment of the torrent. comment.utf-8 is  used
2437                            if available.
2438
2439                     creationDate
2440                            The  creation time of the torrent. The value is an
2441                            integer since the epoch, measured in seconds.
2442
2443                     mode   File mode of the torrent. The value is either sin‐
2444                            gle or multi.
2445
2446                     info   Struct  which  contains data from Info dictionary.
2447                            It contains following keys.
2448
2449                            name   name in info dictionary. name.utf-8 is used
2450                                   if available.
2451
2452              verifiedLength
2453                     The  number  of  verified number of bytes while the files
2454                     are being hash checked.  This key exists only  when  this
2455                     download is being hash checked.
2456
2457              verifyIntegrityPending
2458                     true  if this download is waiting for the hash check in a
2459                     queue.  This key exists only when this download is in the
2460                     queue.
2461
2462              JSON-RPC Example
2463
2464              The  following  example  gets  information about a download with
2465              GID#2089b05ecca3d829:
2466
2467                 >>> import urllib2, json
2468                 >>> from pprint import pprint
2469                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2470                 ...                       'method':'aria2.tellStatus',
2471                 ...                       'params':['2089b05ecca3d829']})
2472                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2473                 >>> pprint(json.loads(c.read()))
2474                 {u'id': u'qwer',
2475                  u'jsonrpc': u'2.0',
2476                  u'result': {u'bitfield': u'0000000000',
2477                              u'completedLength': u'901120',
2478                              u'connections': u'1',
2479                              u'dir': u'/downloads',
2480                              u'downloadSpeed': u'15158',
2481                              u'files': [{u'index': u'1',
2482                                          u'length': u'34896138',
2483                                          u'completedLength': u'34896138',
2484                                          u'path': u'/downloads/file',
2485                                          u'selected': u'true',
2486                                          u'uris': [{u'status': u'used',
2487                                                     u'uri': u'http://example.org/file'}]}],
2488                              u'gid': u'2089b05ecca3d829',
2489                              u'numPieces': u'34',
2490                              u'pieceLength': u'1048576',
2491                              u'status': u'active',
2492                              u'totalLength': u'34896138',
2493                              u'uploadLength': u'0',
2494                              u'uploadSpeed': u'0'}}
2495
2496              The following example gets only specific keys:
2497
2498                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2499                 ...                       'method':'aria2.tellStatus',
2500                 ...                       'params':['2089b05ecca3d829',
2501                 ...                                 ['gid',
2502                 ...                                  'totalLength',
2503                 ...                                  'completedLength']]})
2504                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2505                 >>> pprint(json.loads(c.read()))
2506                 {u'id': u'qwer',
2507                  u'jsonrpc': u'2.0',
2508                  u'result': {u'completedLength': u'5701632',
2509                              u'gid': u'2089b05ecca3d829',
2510                              u'totalLength': u'34896138'}}
2511
2512              XML-RPC Example
2513
2514              The following example gets information  about  a  download  with
2515              GID#2089b05ecca3d829:
2516
2517                 >>> import xmlrpclib
2518                 >>> from pprint import pprint
2519                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2520                 >>> r = s.aria2.tellStatus('2089b05ecca3d829')
2521                 >>> pprint(r)
2522                 {'bitfield': 'ffff80',
2523                  'completedLength': '34896138',
2524                  'connections': '0',
2525                  'dir': '/downloads',
2526                  'downloadSpeed': '0',
2527                  'errorCode': '0',
2528                  'files': [{'index': '1',
2529                             'length': '34896138',
2530                             'completedLength': '34896138',
2531                             'path': '/downloads/file',
2532                             'selected': 'true',
2533                             'uris': [{'status': 'used',
2534                                       'uri': 'http://example.org/file'}]}],
2535                  'gid': '2089b05ecca3d829',
2536                  'numPieces': '17',
2537                  'pieceLength': '2097152',
2538                  'status': 'complete',
2539                  'totalLength': '34896138',
2540                  'uploadLength': '0',
2541                  'uploadSpeed': '0'}
2542
2543              The following example gets only specific keys:
2544
2545                 >>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength'])
2546                 >>> pprint(r)
2547                 {'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}
2548
2549       aria2.getUris([secret], gid)
2550              This method returns the URIs used in the download denoted by gid
2551              (string).  The response is an array of structs and  it  contains
2552              following keys.  Values are string.
2553
2554              uri    URI
2555
2556              status 'used'  if  the  URI  is  in use. 'waiting' if the URI is
2557                     still waiting in the queue.
2558
2559              JSON-RPC Example
2560
2561                 >>> import urllib2, json
2562                 >>> from pprint import pprint
2563                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2564                 ...                       'method':'aria2.getUris',
2565                 ...                       'params':['2089b05ecca3d829']})
2566                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2567                 >>> pprint(json.loads(c.read()))
2568                 {u'id': u'qwer',
2569                  u'jsonrpc': u'2.0',
2570                  u'result': [{u'status': u'used',
2571                               u'uri': u'http://example.org/file'}]}
2572
2573              XML-RPC Example
2574
2575                 >>> import xmlrpclib
2576                 >>> from pprint import pprint
2577                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2578                 >>> r = s.aria2.getUris('2089b05ecca3d829')
2579                 >>> pprint(r)
2580                 [{'status': 'used', 'uri': 'http://example.org/file'}]
2581
2582       aria2.getFiles([secret], gid)
2583              This method returns the file list of the download denoted by gid
2584              (string).   The  response  is  an array of structs which contain
2585              following keys.  Values are strings.
2586
2587              index  Index of the file, starting at 1, in the  same  order  as
2588                     files appear in the multi-file torrent.
2589
2590              path   File path.
2591
2592              length File size in bytes.
2593
2594              completedLength
2595                     Completed length of this file in bytes.  Please note that
2596                     it is possible that sum of completedLength is  less  than
2597                     the  completedLength  returned  by the aria2.tellStatus()
2598                     method.    This    is    because    completedLength    in
2599                     aria2.getFiles()  only  includes completed pieces. On the
2600                     other hand, completedLength  in  aria2.tellStatus()  also
2601                     includes partially completed pieces.
2602
2603              selected
2604                     true if this file is selected by --select-file option. If
2605                     --select-file is not specified  or  this  is  single-file
2606                     torrent  or  not a torrent download at all, this value is
2607                     always true. Otherwise false.
2608
2609              uris   Returns a list of URIs for this file. The element type is
2610                     the same struct used in the aria2.getUris() method.
2611
2612              JSON-RPC Example
2613
2614                 >>> import urllib2, json
2615                 >>> from pprint import pprint
2616                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2617                 ...                       'method':'aria2.getFiles',
2618                 ...                       'params':['2089b05ecca3d829']})
2619                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2620                 >>> pprint(json.loads(c.read()))
2621                 {u'id': u'qwer',
2622                  u'jsonrpc': u'2.0',
2623                  u'result': [{u'index': u'1',
2624                               u'length': u'34896138',
2625                               u'completedLength': u'34896138',
2626                               u'path': u'/downloads/file',
2627                               u'selected': u'true',
2628                               u'uris': [{u'status': u'used',
2629                                          u'uri': u'http://example.org/file'}]}]}
2630
2631              XML-RPC Example
2632
2633                 >>> import xmlrpclib
2634                 >>> from pprint import pprint
2635                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2636                 >>> r = s.aria2.getFiles('2089b05ecca3d829')
2637                 >>> pprint(r)
2638                 [{'index': '1',
2639                   'length': '34896138',
2640                   'completedLength': '34896138',
2641                   'path': '/downloads/file',
2642                   'selected': 'true',
2643                   'uris': [{'status': 'used',
2644                             'uri': 'http://example.org/file'}]}]
2645
2646       aria2.getPeers([secret], gid)
2647              This  method returns a list peers of the download denoted by gid
2648              (string).  This method is for BitTorrent only.  The response  is
2649              an  array of structs and contains the following keys. Values are
2650              strings.
2651
2652              peerId Percent-encoded peer ID.
2653
2654              ip     IP address of the peer.
2655
2656              port   Port number of the peer.
2657
2658              bitfield
2659                     Hexadecimal representation of the  download  progress  of
2660                     the  peer.  The  highest  bit corresponds to the piece at
2661                     index 0. Set bits indicate the  piece  is  available  and
2662                     unset  bits indicate the piece is missing. Any spare bits
2663                     at the end are set to zero.
2664
2665              amChoking
2666                     true if aria2 is choking the peer. Otherwise false.
2667
2668              peerChoking
2669                     true if the peer is choking aria2. Otherwise false.
2670
2671              downloadSpeed
2672                     Download speed (byte/sec) that this client  obtains  from
2673                     the peer.
2674
2675              uploadSpeed
2676                     Upload  speed(byte/sec)  that  this client uploads to the
2677                     peer.
2678
2679              seeder true if this peer is a seeder. Otherwise false.
2680
2681              JSON-RPC Example
2682
2683                 >>> import urllib2, json
2684                 >>> from pprint import pprint
2685                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2686                 ...                       'method':'aria2.getPeers',
2687                 ...                       'params':['2089b05ecca3d829']})
2688                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2689                 >>> pprint(json.loads(c.read()))
2690                 {u'id': u'qwer',
2691                  u'jsonrpc': u'2.0',
2692                  u'result': [{u'amChoking': u'true',
2693                               u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff',
2694                               u'downloadSpeed': u'10602',
2695                               u'ip': u'10.0.0.9',
2696                               u'peerChoking': u'false',
2697                               u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2698                               u'port': u'6881',
2699                               u'seeder': u'true',
2700                               u'uploadSpeed': u'0'},
2701                              {u'amChoking': u'false',
2702                               u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2703                               u'downloadSpeed': u'8654',
2704                               u'ip': u'10.0.0.30',
2705                               u'peerChoking': u'false',
2706                               u'peerId': u'bittorrent client758',
2707                               u'port': u'37842',
2708                               u'seeder': u'false',
2709                               u'uploadSpeed': u'6890'}]}
2710
2711              XML-RPC Example
2712
2713                 >>> import xmlrpclib
2714                 >>> from pprint import pprint
2715                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2716                 >>> r = s.aria2.getPeers('2089b05ecca3d829')
2717                 >>> pprint(r)
2718                 [{'amChoking': 'true',
2719                   'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
2720                   'downloadSpeed': '10602',
2721                   'ip': '10.0.0.9',
2722                   'peerChoking': 'false',
2723                   'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
2724                   'port': '6881',
2725                   'seeder': 'true',
2726                   'uploadSpeed': '0'},
2727                  {'amChoking': 'false',
2728                   'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
2729                   'downloadSpeed': '8654',
2730                   'ip': '10.0.0.30',
2731                   'peerChoking': 'false',
2732                   'peerId': 'bittorrent client758',
2733                   'port': '37842',
2734                   'seeder': 'false,
2735                   'uploadSpeed': '6890'}]
2736
2737       aria2.getServers([secret], gid)
2738              This method returns currently connected HTTP(S)/FTP/SFTP servers
2739              of  the  download  denoted  by  gid (string). The response is an
2740              array of structs and contains the  following  keys.  Values  are
2741              strings.
2742
2743              index  Index  of  the  file, starting at 1, in the same order as
2744                     files appear in the multi-file metalink.
2745
2746              servers
2747                     A list of structs which contain the following keys.
2748
2749                     uri    Original URI.
2750
2751                     currentUri
2752                            This is the URI currently used for downloading. If
2753                            redirection  is  involved,  currentUri and uri may
2754                            differ.
2755
2756                     downloadSpeed
2757                            Download speed (byte/sec)
2758
2759              JSON-RPC Example
2760
2761                 >>> import urllib2, json
2762                 >>> from pprint import pprint
2763                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2764                 ...                       'method':'aria2.getServers',
2765                 ...                       'params':['2089b05ecca3d829']})
2766                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2767                 >>> pprint(json.loads(c.read()))
2768                 {u'id': u'qwer',
2769                  u'jsonrpc': u'2.0',
2770                  u'result': [{u'index': u'1',
2771                               u'servers': [{u'currentUri': u'http://example.org/file',
2772                                             u'downloadSpeed': u'10467',
2773                                             u'uri': u'http://example.org/file'}]}]}
2774
2775              XML-RPC Example
2776
2777                 >>> import xmlrpclib
2778                 >>> from pprint import pprint
2779                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2780                 >>> r = s.aria2.getServers('2089b05ecca3d829')
2781                 >>> pprint(r)
2782                 [{'index': '1',
2783                   'servers': [{'currentUri': 'http://example.org/dl/file',
2784                                'downloadSpeed': '20285',
2785                                'uri': 'http://example.org/file'}]}]
2786
2787       aria2.tellActive([secret][, keys])
2788              This method returns a list of active downloads.  The response is
2789              an   array   of   the   same   structs   as   returned   by  the
2790              aria2.tellStatus() method.  For the keys parameter, please refer
2791              to the aria2.tellStatus() method.
2792
2793       aria2.tellWaiting([secret], offset, num[, keys])
2794              This  method  returns  a  list  of  waiting downloads, including
2795              paused ones.  offset is an integer and specifies the offset from
2796              the download waiting at the front.  num is an integer and speci‐
2797              fies the max. number of downloads to be returned.  For the  keys
2798              parameter, please refer to the aria2.tellStatus() method.
2799
2800              If  offset  is a positive integer, this method returns downloads
2801              in the range of [offset, offset + num).
2802
2803              offset can be a negative integer. offset == -1 points last down‐
2804              load  in  the waiting queue and offset == -2 points the download
2805              before the last download, and so on. Downloads in  the  response
2806              are in reversed order then.
2807
2808              For example, imagine three downloads "A","B" and "C" are waiting
2809              in  this   order.   aria2.tellWaiting(0,   1)   returns   ["A"].
2810              aria2.tellWaiting(1,  2)  returns  ["B",  "C"].  aria2.tellWait‐
2811              ing(-1, 2) returns ["C", "B"].
2812
2813              The response is an array of the  same  structs  as  returned  by
2814              aria2.tellStatus() method.
2815
2816       aria2.tellStopped([secret], offset, num[, keys])
2817              This  method  returns a list of stopped downloads.  offset is an
2818              integer and specifies the offset from the least recently stopped
2819              download.   num  is  an integer and specifies the max. number of
2820              downloads to be returned.  For the keys parameter, please  refer
2821              to the aria2.tellStatus() method.
2822
2823              offset  and  num  have  the  same  semantics as described in the
2824              aria2.tellWaiting() method.
2825
2826              The response is an array of the same structs as returned by  the
2827              aria2.tellStatus() method.
2828
2829       aria2.changePosition([secret], gid, pos, how)
2830              This  method changes the position of the download denoted by gid
2831              in the queue.  pos is an integer.  how is a string.  If  how  is
2832              POS_SET,  it  moves  the  download to a position relative to the
2833              beginning of the queue.  If how is POS_CUR, it moves  the  down‐
2834              load  to  a position relative to the current position. If how is
2835              POS_END, it moves the download to a position relative to the end
2836              of  the  queue.  If  the  destination position is less than 0 or
2837              beyond the end of the queue, it moves the download to the begin‐
2838              ning  or  the  end of the queue respectively. The response is an
2839              integer denoting the resulting position.
2840
2841              For example, if GID#2089b05ecca3d829 is currently in position 3,
2842              aria2.changePosition('2089b05ecca3d829',   -1,  'POS_CUR')  will
2843              change  its  position  to  2.   Additionally   aria2.changePosi‐
2844              tion('2089b05ecca3d829',  0, 'POS_SET') will change its position
2845              to 0 (the beginning of the queue).
2846
2847              The following examples move the download GID#2089b05ecca3d829 to
2848              the front of the queue.
2849
2850              JSON-RPC Example
2851
2852                 >>> import urllib2, json
2853                 >>> from pprint import pprint
2854                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2855                 ...                       'method':'aria2.changePosition',
2856                 ...                       'params':['2089b05ecca3d829', 0, 'POS_SET']})
2857                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2858                 >>> pprint(json.loads(c.read()))
2859                 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0}
2860
2861              XML-RPC Example
2862
2863                 >>> import xmlrpclib
2864                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2865                 >>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
2866                 0
2867
2868       aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])
2869              This  method  removes  the  URIs in delUris from and appends the
2870              URIs in addUris to download denoted by gid. delUris and  addUris
2871              are  lists of strings. A download can contain multiple files and
2872              URIs are attached to each file.  fileIndex  is  used  to  select
2873              which  file  to  remove/attach given URIs. fileIndex is 1-based.
2874              position is used to specify  where  URIs  are  inserted  in  the
2875              existing waiting URI list. position is 0-based. When position is
2876              omitted, URIs are appended to the back of the list.  This method
2877              first  executes  the  removal and then the addition. position is
2878              the position after URIs are removed, not the position when  this
2879              method  is called.  When removing an URI, if the same URIs exist
2880              in download, only one  of  them  is  removed  for  each  URI  in
2881              delUris.  In  other  words, if there are three URIs http://exam
2882              ple.org/aria2 and you want remove them all, you have to  specify
2883              (at  least)  3 http://example.org/aria2 in delUris.  This method
2884              returns a list which contains two integers. The first integer is
2885              the  number of URIs deleted. The second integer is the number of
2886              URIs added.
2887
2888              The following examples add the  URI  http://example.org/file  to
2889              the   file  whose  index  is  1  and  belongs  to  the  download
2890              GID#2089b05ecca3d829.
2891
2892              JSON-RPC Example
2893
2894                 >>> import urllib2, json
2895                 >>> from pprint import pprint
2896                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2897                 ...                       'method':'aria2.changeUri',
2898                 ...                       'params':['2089b05ecca3d829', 1, [],
2899                                                     ['http://example.org/file']]})
2900                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2901                 >>> pprint(json.loads(c.read()))
2902                 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]}
2903
2904              XML-RPC Example
2905
2906                 >>> import xmlrpclib
2907                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2908                 >>> s.aria2.changeUri('2089b05ecca3d829', 1, [],
2909                                       ['http://example.org/file'])
2910                 [0, 1]
2911
2912       aria2.getOption([secret], gid)
2913              This method returns options of the download denoted by gid.  The
2914              response  is  a struct where keys are the names of options.  The
2915              values are strings.  Note  that  this  method  does  not  return
2916              options which have no default value and have not been set on the
2917              command-line, in configuration files or RPC methods.
2918
2919              The   following   examples   get   options   of   the   download
2920              GID#2089b05ecca3d829.
2921
2922              JSON-RPC Example
2923
2924                 >>> import urllib2, json
2925                 >>> from pprint import pprint
2926                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2927                 ...                       'method':'aria2.getOption',
2928                 ...                       'params':['2089b05ecca3d829']})
2929                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
2930                 >>> pprint(json.loads(c.read()))
2931                 {u'id': u'qwer',
2932                  u'jsonrpc': u'2.0',
2933                  u'result': {u'allow-overwrite': u'false',
2934                              u'allow-piece-length-change': u'false',
2935                              u'always-resume': u'true',
2936                              u'async-dns': u'true',
2937                  ...
2938
2939              XML-RPC Example
2940
2941                 >>> import xmlrpclib
2942                 >>> from pprint import pprint
2943                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
2944                 >>> r = s.aria2.getOption('2089b05ecca3d829')
2945                 >>> pprint(r)
2946                 {'allow-overwrite': 'false',
2947                  'allow-piece-length-change': 'false',
2948                  'always-resume': 'true',
2949                  'async-dns': 'true',
2950                  ....
2951
2952       aria2.changeOption([secret], gid, options)
2953              This  method  changes  options  of  the  download denoted by gid
2954              (string) dynamically.  options is a struct.  The options  listed
2955              in  Input  File  subsection  are available, except for following
2956              options:
2957
2958              · dry-run
2959
2960              · metalink-base-uri
2961
2962              · parameterized-uri
2963
2964              · pause
2965
2966              · piece-length
2967
2968              · rpc-save-upload-metadata
2969
2970              Except for the following options, changing the other options  of
2971              active  download  makes it restart (restart itself is managed by
2972              aria2, and no user intervention is required):
2973
2974              · bt-max-peers
2975
2976              · bt-request-peer-speed-limit
2977
2978              · bt-remove-unselected-file
2979
2980              · force-save
2981
2982              · max-download-limit
2983
2984              · max-upload-limit
2985
2986              This method returns OK for success.
2987
2988              The following examples set the max-download-limit option to  20K
2989              for the download GID#2089b05ecca3d829.
2990
2991              JSON-RPC Example
2992
2993                 >>> import urllib2, json
2994                 >>> from pprint import pprint
2995                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
2996                 ...                       'method':'aria2.changeOption',
2997                 ...                       'params':['2089b05ecca3d829',
2998                 ...                                 {'max-download-limit':'10K'}]})
2999                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3000                 >>> pprint(json.loads(c.read()))
3001                 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
3002
3003              XML-RPC Example
3004
3005                 >>> import xmlrpclib
3006                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3007                 >>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
3008                 'OK'
3009
3010       aria2.getGlobalOption([secret])
3011              This  method  returns  the  global  options.   The response is a
3012              struct. Its keys are the names of options.  Values are  strings.
3013              Note  that  this  method  does  not return options which have no
3014              default value and have not been set on the command-line, in con‐
3015              figuration files or RPC methods. Because global options are used
3016              as a template for the options  of  newly  added  downloads,  the
3017              response contains keys returned by the aria2.getOption() method.
3018
3019       aria2.changeGlobalOption([secret], options)
3020              This  method  changes  global options dynamically.  options is a
3021              struct.  The following options are available:
3022
3023              · bt-max-open-files
3024
3025              · download-result
3026
3027              · keep-unfinished-download-result
3028
3029              · log
3030
3031              · log-level
3032
3033              · max-concurrent-downloads
3034
3035              · max-download-result
3036
3037              · max-overall-download-limit
3038
3039              · max-overall-upload-limit
3040
3041              · optimize-concurrent-downloads
3042
3043              · save-cookies
3044
3045              · save-session
3046
3047              · server-stat-of
3048
3049              In addition, options listed in the  Input  File  subsection  are
3050              available,  except  for  following options: checksum, index-out,
3051              out, pause and select-file.
3052
3053              With the log option, you can dynamically start logging or change
3054              log  file.  To  stop logging, specify an empty string("") as the
3055              parameter value. Note that log file is always opened  in  append
3056              mode. This method returns OK for success.
3057
3058       aria2.getGlobalStat([secret])
3059              This  method returns global statistics such as the overall down‐
3060              load and upload speeds. The response is a  struct  and  contains
3061              the following keys. Values are strings.
3062
3063              downloadSpeed
3064                     Overall download speed (byte/sec).
3065
3066              uploadSpeed
3067                     Overall upload speed(byte/sec).
3068
3069              numActive
3070                     The number of active downloads.
3071
3072              numWaiting
3073                     The number of waiting downloads.
3074
3075              numStopped
3076                     The  number  of stopped downloads in the current session.
3077                     This value is capped by the --max-download-result option.
3078
3079              numStoppedTotal
3080                     The number of stopped downloads in  the  current  session
3081                     and not capped by the --max-download-result option.
3082
3083              JSON-RPC Example
3084
3085                 >>> import urllib2, json
3086                 >>> from pprint import pprint
3087                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3088                 ...                       'method':'aria2.getGlobalStat'})
3089                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3090                 >>> pprint(json.loads(c.read()))
3091                 {u'id': u'qwer',
3092                  u'jsonrpc': u'2.0',
3093                  u'result': {u'downloadSpeed': u'21846',
3094                              u'numActive': u'2',
3095                              u'numStopped': u'0',
3096                              u'numWaiting': u'0',
3097                              u'uploadSpeed': u'0'}}
3098
3099              XML-RPC Example
3100
3101                 >>> import xmlrpclib
3102                 >>> from pprint import pprint
3103                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3104                 >>> r = s.aria2.getGlobalStat()
3105                 >>> pprint(r)
3106                 {'downloadSpeed': '23136',
3107                  'numActive': '2',
3108                  'numStopped': '0',
3109                  'numWaiting': '0',
3110                  'uploadSpeed': '0'}
3111
3112       aria2.purgeDownloadResult([secret])
3113              This  method  purges  completed/error/removed  downloads to free
3114              memory.  This method returns OK.
3115
3116       aria2.removeDownloadResult([secret], gid)
3117              This method removes a completed/error/removed  download  denoted
3118              by gid from memory. This method returns OK for success.
3119
3120              The  following  examples remove the download result of the down‐
3121              load GID#2089b05ecca3d829.
3122
3123              JSON-RPC Example
3124
3125                 >>> import urllib2, json
3126                 >>> from pprint import pprint
3127                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3128                 ...                       'method':'aria2.removeDownloadResult',
3129                 ...                       'params':['2089b05ecca3d829']})
3130                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3131                 >>> pprint(json.loads(c.read()))
3132                 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'}
3133
3134              XML-RPC Example
3135
3136                 >>> import xmlrpclib
3137                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3138                 >>> s.aria2.removeDownloadResult('2089b05ecca3d829')
3139                 'OK'
3140
3141       aria2.getVersion([secret])
3142              This method returns the version of aria2 and the list of enabled
3143              features. The response is a struct and contains following keys.
3144
3145              version
3146                     Version number of aria2 as a string.
3147
3148              enabledFeatures
3149                     List  of  enabled  features.  Each  feature is given as a
3150                     string.
3151
3152              JSON-RPC Example
3153
3154                 >>> import urllib2, json
3155                 >>> from pprint import pprint
3156                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3157                 ...                       'method':'aria2.getVersion'})
3158                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3159                 >>> pprint(json.loads(c.read()))
3160                 {u'id': u'qwer',
3161                  u'jsonrpc': u'2.0',
3162                  u'result': {u'enabledFeatures': [u'Async DNS',
3163                                                   u'BitTorrent',
3164                                                   u'Firefox3 Cookie',
3165                                                   u'GZip',
3166                                                   u'HTTPS',
3167                                                   u'Message Digest',
3168                                                   u'Metalink',
3169                                                   u'XML-RPC'],
3170                              u'version': u'1.11.0'}}
3171
3172              XML-RPC Example
3173
3174                 >>> import xmlrpclib
3175                 >>> from pprint import pprint
3176                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3177                 >>> r = s.aria2.getVersion()
3178                 >>> pprint(r)
3179                 {'enabledFeatures': ['Async DNS',
3180                                      'BitTorrent',
3181                                      'Firefox3 Cookie',
3182                                      'GZip',
3183                                      'HTTPS',
3184                                      'Message Digest',
3185                                      'Metalink',
3186                                      'XML-RPC'],
3187                  'version': '1.11.0'}
3188
3189       aria2.getSessionInfo([secret])
3190              This method returns session  information.   The  response  is  a
3191              struct and contains following key.
3192
3193              sessionId
3194                     Session  ID,  which  is generated each time when aria2 is
3195                     invoked.
3196
3197              JSON-RPC Example
3198
3199                 >>> import urllib2, json
3200                 >>> from pprint import pprint
3201                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3202                 ...                       'method':'aria2.getSessionInfo'})
3203                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3204                 >>> pprint(json.loads(c.read()))
3205                 {u'id': u'qwer',
3206                  u'jsonrpc': u'2.0',
3207                  u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}}
3208
3209              XML-RPC Example
3210
3211                 >>> import xmlrpclib
3212                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3213                 >>> s.aria2.getSessionInfo()
3214                 {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}
3215
3216       aria2.shutdown([secret])
3217              This method shuts down aria2.  This method returns OK.
3218
3219       aria2.forceShutdown([secret])
3220              This  method  shuts  down  aria2().  This  method  behaves  like
3221              :func:'aria2.shutdown` without performing any actions which take
3222              time, such as contacting BitTorrent trackers to unregister down‐
3223              loads first.  This method returns OK.
3224
3225       aria2.saveSession([secret])
3226              This method saves the current session to a file specified by the
3227              --save-session option. This method returns OK if it succeeds.
3228
3229       system.multicall(methods)
3230              This methods encapsulates multiple  method  calls  in  a  single
3231              request.   methods  is an array of structs.  The structs contain
3232              two keys: methodName and params.  methodName is the method  name
3233              to  call and params is array containing parameters to the method
3234              call.  This method returns an array of responses.  The  elements
3235              will  be  either a one-item array containing the return value of
3236              the method call or a struct of fault element if an  encapsulated
3237              method call fails.
3238
3239              In  the following examples, we add 2 downloads. The first one is
3240              http://example.org/file and the second one is file.torrent.
3241
3242              JSON-RPC Example
3243
3244                 >>> import urllib2, json, base64
3245                 >>> from pprint import pprint
3246                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3247                 ...                       'method':'system.multicall',
3248                 ...                       'params':[[{'methodName':'aria2.addUri',
3249                 ...                                   'params':[['http://example.org']]},
3250                 ...                                  {'methodName':'aria2.addTorrent',
3251                 ...                                   'params':[base64.b64encode(open('file.torrent').read())]}]]})
3252                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3253                 >>> pprint(json.loads(c.read()))
3254                 {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]}
3255
3256              JSON-RPC additionally supports Batch requests  as  described  in
3257              the JSON-RPC 2.0 Specification:
3258
3259                 >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer',
3260                 ...                        'method':'aria2.addUri',
3261                 ...                        'params':[['http://example.org']]},
3262                 ...                       {'jsonrpc':'2.0', 'id':'asdf',
3263                 ...                        'method':'aria2.addTorrent',
3264                 ...                        'params':[base64.b64encode(open('file.torrent').read())]}])
3265                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3266                 >>> pprint(json.loads(c.read()))
3267                 [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'},
3268                  {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}]
3269
3270              XML-RPC Example
3271
3272                 >>> import xmlrpclib
3273                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3274                 >>> mc = xmlrpclib.MultiCall(s)
3275                 >>> mc.aria2.addUri(['http://example.org/file'])
3276                 >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
3277                 >>> r = mc()
3278                 >>> tuple(r)
3279                 ('2089b05ecca3d829', 'd2703803b52216d1')
3280
3281       system.listMethods()
3282              This method returns all the available RPC methods in an array of
3283              string.  Unlike other methods,  this  method  does  not  require
3284              secret token.  This is safe because this method just returns the
3285              available method names.
3286
3287              JSON-RPC Example
3288
3289                 >>> import urllib2, json
3290                 >>> from pprint import pprint
3291                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3292                 ...                       'method':'system.listMethods'})
3293                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3294                 >>> pprint(json.loads(c.read()))
3295                 {u'id': u'qwer',
3296                  u'jsonrpc': u'2.0',
3297                  u'result': [u'aria2.addUri',
3298                              u'aria2.addTorrent',
3299                 ...
3300
3301              XML-RPC Example
3302
3303                 >>> import xmlrpclib
3304                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3305                 >>> s.system.listMethods()
3306                 ['aria2.addUri', 'aria2.addTorrent', ...
3307
3308       system.listNotifications()
3309              This method returns all the available RPC  notifications  in  an
3310              array  of  string.   Unlike  other methods, this method does not
3311              require secret token.  This is safe  because  this  method  just
3312              returns the available notifications names.
3313
3314              JSON-RPC Example
3315
3316                 >>> import urllib2, json
3317                 >>> from pprint import pprint
3318                 >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
3319                 ...                       'method':'system.listNotifications'})
3320                 >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
3321                 >>> pprint(json.loads(c.read()))
3322                 {u'id': u'qwer',
3323                  u'jsonrpc': u'2.0',
3324                  u'result': [u'aria2.onDownloadStart',
3325                              u'aria2.onDownloadPause',
3326                 ...
3327
3328              XML-RPC Example
3329
3330                 >>> import xmlrpclib
3331                 >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3332                 >>> s.system.listNotifications()
3333                 ['aria2.onDownloadStart', 'aria2.onDownloadPause', ...
3334
3335   Error Handling
3336       Over JSON-RPC, aria2 returns a JSON object which contains an error code
3337       in code and the error message in message.
3338
3339       Over XML-RPC, aria2 returns faultCode=1 and the error message in fault‐
3340       String.
3341
3342   Options
3343       The  same options as for --input-file are available. See the Input File
3344       subsection for a complete list of options.
3345
3346       In the option struct, the name element is the option name (without  the
3347       preceding --) and the value element is the argument as a string.
3348
3349   JSON-RPC Example
3350          {'split':'1', 'http-proxy':'http://proxy/'}
3351
3352   XML-RPC Example
3353          <struct>
3354            <member>
3355              <name>split</name>
3356              <value><string>1</string></value>
3357            </member>
3358            <member>
3359              <name>http-proxy</name>
3360              <value><string>http://proxy/</string></value>
3361            </member>
3362          </struct>
3363
3364       The header and index-out options are allowed multiple times on the com‐
3365       mand-line. Since the name should be unique in a  struct  (many  XML-RPC
3366       library implementations use a hash or dict for struct), a single string
3367       is not enough. To overcome this limitation, you may use an array as the
3368       value as well as a string.
3369
3370   JSON-RPC Example
3371          {'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}
3372
3373   XML-RPC Example
3374          <struct>
3375            <member>
3376              <name>header</name>
3377              <value>
3378                <array>
3379                  <data>
3380                    <value><string>Accept-Language: ja</string></value>
3381                    <value><string>Accept-Charset: utf-8</string></value>
3382                  </data>
3383                </array>
3384              </value>
3385            </member>
3386          </struct>
3387
3388       The following example adds a download with two options: dir and header.
3389       The header option requires two values, so it uses a list:
3390
3391          >>> import xmlrpclib
3392          >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
3393          >>> opts = dict(dir='/tmp',
3394          ...             header=['Accept-Language: ja',
3395          ...                     'Accept-Charset: utf-8'])
3396          >>> s.aria2.addUri(['http://example.org/file'], opts)
3397          '1'
3398
3399   JSON-RPC using HTTP GET
3400       The JSON-RPC interface also supports requests via HTTP GET.  The encod‐
3401       ing  scheme in GET parameters is based on JSON-RPC over HTTP Specifica‐
3402       tion [2008-1-15(RC1)].  The encoding of GET parameters are follows:
3403
3404          /jsonrpc?method=METHOD_NAME&id=ID&params=BASE64_ENCODED_PARAMS
3405
3406       The method and id are always treated as JSON string and their  encoding
3407       must be UTF-8.
3408
3409       For example, The encoded string of aria2.tellStatus('2089b05ecca3d829')
3410       with id='foo' looks like this:
3411
3412          /jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3413
3414       The params parameter is Base64-encoded JSON array which usually appears
3415       in  params attribute in JSON-RPC request object.  In the above example,
3416       the params is ["2089b05ecca3d829"], therefore:
3417
3418          ["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0=
3419                       --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D
3420
3421       The JSON-RPC interface also supports JSONP. You can specify  the  call‐
3422       back function in the jsoncallback parameter:
3423
3424          /jsonrpc?method=aria2.tellStatus&id=foo&params=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb
3425
3426       For Batch requests, the method and id parameters must not be specified.
3427       The whole request must be specified in the params parameter. For  exam‐
3428       ple, a Batch request:
3429
3430          [{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'},
3431           {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}]
3432
3433       must be encoded like this:
3434
3435          /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D
3436
3437   JSON-RPC over WebSocket
3438       JSON-RPC over WebSocket uses same method signatures and response format
3439       as JSON-RPC over HTTP. The supported WebSocket version is 13  which  is
3440       detailed in RFC 6455.
3441
3442       To  send a RPC request to the RPC server, send a serialized JSON string
3443       in a Text frame. The response from the RPC server is delivered also  in
3444       a Text frame.
3445
3446   Notifications
3447       The RPC server might send notifications to the client. Notifications is
3448       unidirectional, therefore the client which  receives  the  notification
3449       must  not respond to it. The method signature of a notification is much
3450       like a normal method request but lacks the id key.  The  value  of  the
3451       params  key  is the data which this notification carries. The format of
3452       the value varies depending on the notification method. Following  noti‐
3453       fication methods are defined.
3454
3455       aria2.onDownloadStart(event)
3456              This  notification will be sent when a download is started.  The
3457              event is of type struct and it  contains  following  keys.   The
3458              value type is string.
3459
3460              gid    GID of the download.
3461
3462       aria2.onDownloadPause(event)
3463              This  notification  will be sent when a download is paused.  The
3464              event  is  the  same   struct   as   the   event   argument   of
3465              aria2.onDownloadStart() method.
3466
3467       aria2.onDownloadStop(event)
3468              This notification will be sent when a download is stopped by the
3469              user.  The event is the same struct as  the  event  argument  of
3470              aria2.onDownloadStart() method.
3471
3472       aria2.onDownloadComplete(event)
3473              This notification will be sent when a download is complete.  For
3474              BitTorrent downloads, this notification is sent when  the  down‐
3475              load  is  complete  and  seeding  is over. The event is the same
3476              struct of the event argument of aria2.onDownloadStart() method.
3477
3478       aria2.onDownloadError(event)
3479              This notification will be sent when a download is stopped due to
3480              an error.  The event is the same struct as the event argument of
3481              aria2.onDownloadStart() method.
3482
3483       aria2.onBtDownloadComplete(event)
3484              This notification will be sent when a torrent download  is  com‐
3485              plete  but  seeding  is  still  going on.  The event is the same
3486              struct as the event argument of aria2.onDownloadStart() method.
3487
3488   Sample XML-RPC Client Code
3489       The following Ruby script adds http://localhost/aria2.tar.bz2 to aria2c
3490       (running  on localhost) with option --dir=/downloads and prints the RPC
3491       response:
3492
3493          #!/usr/bin/env ruby
3494
3495          require 'xmlrpc/client'
3496          require 'pp'
3497
3498          client=XMLRPC::Client.new2("http://localhost:6800/rpc")
3499
3500          options={ "dir" => "/downloads" }
3501          result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)
3502
3503          pp result
3504
3505       If you are a Python lover, you can use  xmlrpclib  (Python3  uses  xml‐
3506       rpc.client instead) to interact with aria2:
3507
3508          import xmlrpclib
3509          from pprint import pprint
3510
3511          s = xmlrpclib.ServerProxy("http://localhost:6800/rpc")
3512          r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"})
3513          pprint(r)
3514

MISC

3516   Console Readout
3517       While  downloading files, aria2 prints a readout to the console to show
3518       the progress of the downloads. The console readout looks like this:
3519
3520          [#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s]
3521
3522       This section describes what these numbers and strings mean.
3523
3524       #NNNNNN
3525              The first 6 characters of the GID as a hex string. The GID is an
3526              unique  ID for each download, internal to aria2. The GID is par‐
3527              ticularly useful when  interacting  with  aria2  using  the  RPC
3528              interface.
3529
3530       X/Y(Z%)
3531              Completed  length,  the  total  file length and its progress. If
3532              --select-file is used, this is the sum of selected files.
3533
3534       SEED   Share ratio when the aria2 is seeding a finished torrent.
3535
3536       CN     The number of connections aria2 has established.
3537
3538       SD     The number of seeders aria2 is connected to.
3539
3540       DL     Download speed (bytes per second).
3541
3542       UL     Upload speed (bytes per  second)  and  the  number  of  uploaded
3543              bytes.
3544
3545       ETA    Expected time to finish the download.
3546
3547       When  more  than  one  download is in progress, some of the information
3548       described above will be omitted in order to show information  for  sev‐
3549       eral downloads. And the overall download and upload speeds are shown at
3550       the beginning of the line.
3551
3552       When aria2 is allocating file space or validating checksums,  it  addi‐
3553       tionally prints the progress of these operations:
3554
3555       FileAlloc
3556              GID, already allocated length and total length in bytes.
3557
3558       Checksum
3559              GID, already validated length and total length in bytes.
3560

EXAMPLE

3562   HTTP/FTP Segmented Downloads
3563   Download a file
3564          $ aria2c "http://host/file.zip"
3565
3566       NOTE:
3567          To  stop  a  download,  press Ctrl-C. You can resume the transfer by
3568          running aria2c with the same argument in the same directory. You can
3569          change URIs as long as they are pointing to the same file.
3570
3571   Download a file from two different HTTP servers
3572          $ aria2c "http://host/file.zip" "http://mirror/file.zip"
3573
3574   Download a file from one host using multiple connections
3575          $ aria2c -x2 -k1M "http://host/file.zip"
3576
3577       NOTE:
3578          The -x option specified the number of allowed connections, while the
3579          -k option specified the size of chunks.
3580
3581   Download a file from HTTP and FTP servers at the same time
3582          $ aria2c "http://host1/file.zip" "ftp://host2/file.zip"
3583
3584   Download files listed in a text file concurrently
3585          $ aria2c -ifiles.txt -j2
3586
3587       NOTE:
3588          -j option specifies the number of parallel downloads.
3589
3590   Using a proxy
3591       For HTTP:
3592
3593          $ aria2c --http-proxy="http://proxy:8080" "http://host/file"
3594
3595          $ aria2c --http-proxy="http://proxy:8080" --no-proxy="localhost,127.0.0.1,192.168.0.0/16" "http://host/file"
3596
3597       For FTP:
3598
3599          $ aria2c --ftp-proxy="http://proxy:8080" "ftp://host/file"
3600
3601       NOTE:
3602          See  --http-proxy,  --https-proxy,  --ftp-proxy,   --all-proxy   and
3603          --no-proxy  for  details.   You can specify proxy in the environment
3604          variables. See ENVIRONMENT section.
3605
3606   Using a Proxy with authorization
3607          $ aria2c --http-proxy="http://username:password@proxy:8080" "http://host/file"
3608
3609          $ aria2c --http-proxy="http://proxy:8080" --http-proxy-user="username" --http-proxy-passwd="password" "http://host/file"
3610
3611   Metalink Download
3612   Download files with remote Metalink
3613          $ aria2c --follow-metalink=mem "http://host/file.metalink"
3614
3615   Download using a local metalink file
3616          $ aria2c -p --lowest-speed-limit=4000 file.metalink
3617
3618       NOTE:
3619          To stop a download, press Ctrl-C.  You can resume  the  transfer  by
3620          running aria2c with the same argument in the same directory.
3621
3622   Download several local metalink files
3623          $ aria2c -j2 file1.metalink file2.metalink
3624
3625   Download only selected files
3626          $ aria2c --select-file=1-4,8 file.metalink
3627
3628       NOTE:
3629          The index is printed to the console using -S option.
3630
3631   Download a file using a local metalink file with user preference
3632          $ aria2c --metalink-location=jp,us --metalink-version=1.1 --metalink-language=en-US file.metalink
3633
3634   BitTorrent Download
3635   Download files using a remote BitTorrent file
3636          $ aria2c --follow-torrent=mem "http://host/file.torrent"
3637
3638   Download using a local torrent file
3639          $ aria2c --max-upload-limit=40K file.torrent
3640
3641       NOTE:
3642          --max-upload-limit specifies the max of upload rate.
3643
3644       NOTE:
3645          To  stop a download, press Ctrl-C. You can resume the transfer later
3646          by running aria2c with the same argument in the same directory.
3647
3648   Download using BitTorrent Magnet URI
3649          $ aria2c "magnet:?xt=urn:btih:248D0A1CD08284299DE78D5C1ED359BB46717D8C&dn=aria2"
3650
3651       NOTE:
3652          Don't forget to quote BitTorrent Magnet URIs which include & charac‐
3653          ters  with single(') or double(") quotes when specifying URIs on the
3654          command-line.
3655
3656   Download 2 torrents
3657          $ aria2c -j2 file1.torrent file2.torrent
3658
3659   Download a file via torrent and HTTP/FTP server in parallel
3660          $ aria2c -Ttest.torrent "http://host1/file" "ftp://host2/file"
3661
3662   Only download specific files (usually called selected download )
3663          $ aria2c --select-file=1-4,8 file.torrent
3664
3665       NOTE:
3666          The index is printed to the console using -S option.
3667
3668   Download a .torrent file, but do not download the torrent
3669          $ aria2c --follow-torrent=false "http://host/file.torrent"
3670
3671   Specify the output file name
3672       To specify the output file name for BitTorrent downloads, you  need  to
3673       know  the index of file in the torrent (see --show-files). For example,
3674       the output looks like this:
3675
3676          idx|path/length
3677          ===+======================
3678            1|dist/base-2.6.18.iso
3679             |99.9MiB
3680          ---+----------------------
3681            2|dist/driver-2.6.18.iso
3682             |169.0MiB
3683          ---+----------------------
3684
3685       To   save   'dist/base-2.6.18.iso'   in    '/tmp/mydir/base.iso'    and
3686       'dist/driver-2.6.18.iso'  in  '/tmp/dir/driver.iso',  use the following
3687       command:
3688
3689          $ aria2c --dir=/tmp --index-out=1=mydir/base.iso --index-out=2=dir/driver.iso file.torrent
3690
3691   Change the listening ports for incoming peer connections
3692          $ aria2c --listen-port=7000-7001,8000 file.torrent
3693
3694       NOTE:
3695          Since aria2 doesn't configure firewalls or routers for port forward‐
3696          ing, it's up to you to do so manually.
3697
3698   Specify conditions to stop seeding after torrent downloads finish
3699          $ aria2c --seed-time=120 --seed-ratio=1.0 file.torrent
3700
3701       NOTE:
3702          In  the  above  example, the program stops seeding after 120 minutes
3703          since download completed or seed ratio reaches 1.0.
3704
3705   Throttle upload speed
3706          $ aria2c --max-upload-limit=100K file.torrent
3707
3708   Enable IPv4 DHT
3709          $ aria2c --enable-dht --dht-listen-port=6881 file.torrent
3710
3711       NOTE:
3712          DHT uses UDP. Since aria2 doesn't configure firewalls or routers for
3713          port forwarding, it's up to you to do it manually.
3714
3715   Enable IPv6 DHT
3716          $ aria2c --enable-dht6 --dht-listen-port=6881 --dht-listen-addr6=YOUR_GLOBAL_UNICAST_IPV6_ADDR
3717
3718       NOTE:
3719          aria2 uses the same ports as IPv4 for IPv6.
3720
3721   Add and remove tracker URIs
3722       Ignore  all  tracker  announce  URIs  defined  in  file.torrent and use
3723       http://tracker1/announce and http://tracker2/announce instead:
3724
3725          $ aria2c --bt-exclude-tracker="*" --bt-tracker="http://tracker1/announce,http://tracker2/announce" file.torrent
3726
3727   More advanced HTTP features
3728   Load cookies
3729          $ aria2c --load-cookies=cookies.txt "http://host/file.zip"
3730
3731       NOTE:
3732          You can use Firefox/Mozilla/Chromium's cookie files without  modifi‐
3733          cation.
3734
3735   Resume download started by web browsers or other programs
3736          $ aria2c -c -s2 "http://host/partiallydownloadedfile.zip"
3737
3738       NOTE:
3739          This  will  only  work  when the initial download was not multi-seg‐
3740          mented.
3741
3742   Client certificate authorization for SSL/TLS
3743       Specify a PKCS12 file as follows:
3744
3745          $ aria2c --certificate=/path/to/mycert.p12
3746
3747       NOTE:
3748          The file specified in  --certificate  must  be  contain  one  PKCS12
3749          encoded certificate and key. The password must be blank.
3750
3751       Alternatively,  if PEM files are supported, use a command like the fol‐
3752       lowing:
3753
3754          $ aria2c --certificate=/path/to/mycert.pem --private-key=/path/to/mykey.pem https://host/file
3755
3756       NOTE:
3757          The file specified in --private-key must be decrypted. The  behavior
3758          when encrypted one is given is undefined.
3759
3760   Verify SSL/TLS servers using given CA certificates
3761          $ aria2c --ca-certificate=/path/to/ca-certificates.crt --check-certificate https://host/file
3762
3763       NOTE:
3764          This option is only available when aria2 was compiled against GnuTLS
3765          or OpenSSL.  WinTLS and AppleTLS will always use the system certifi‐
3766          cate  store. Instead of `--ca-certificate install the certificate in
3767          that store.
3768
3769   RPC
3770   Encrypt RPC traffic with SSL/TLS
3771       Specify a server PKC12 file:
3772
3773          $ aria2c --enable-rpc --rpc-certificate=/path/to/server.p12 --rpc-secure
3774
3775       NOTE:
3776          The file specified in --rpc-certificate must be contain  one  PKCS12
3777          encoded certificate and key. The password must be blank.
3778
3779       Alternatively, when PEM files are supported (GnuTLS and OpenSSL), spec‐
3780       ify the server certificate file and private key file as follows:
3781
3782          $ aria2c --enable-rpc --rpc-certificate=/path/to/server.crt --rpc-private-key=/path/to/server.key --rpc-secure
3783
3784   And more advanced features
3785   Throttle the download speed
3786       Per-download:
3787
3788          $ aria2c --max-download-limit=100K file.metalink
3789
3790       Overall:
3791
3792          $ aria2c --max-overall-download-limit=100K file.metalink
3793
3794   Repair a damaged download
3795          $ aria2c -V file.metalink
3796
3797       NOTE:
3798          Repairing damaged downloads can be done efficiently when  used  with
3799          BitTorrent or Metalink with chunk checksums.
3800
3801   Drop connections if download speed is lower than a specified limit
3802          $ aria2c --lowest-speed-limit=10K file.metalink
3803
3804   Parameterized URI support
3805       You can specify set of parts:
3806
3807          $ aria2c -P "http://{host1,host2,host3}/file.iso"
3808
3809       You can specify numeric sequence:
3810
3811          $ aria2c -Z -P "http://host/image[000-100].png"
3812
3813       NOTE:
3814          The  -Z option is required if the URIs don't point to the same file,
3815          such as in the above example.
3816
3817       You can specify step counter:
3818
3819          $ aria2c -Z -P "http://host/image[A-Z:2].png"
3820
3821   Verifying checksums
3822          $ aria2c --checksum=sha-1=0192ba11326fe2298c8cb4de616f4d4140213837 http://example.org/file
3823
3824   Parallel downloads of an arbitrary number of URIs, metalink, torrent
3825          $ aria2c -j3 -Z "http://host/file1" file2.torrent file3.metalink
3826
3827   BitTorrent Encryption
3828       Encrypt the whole payload using ARC4 (obfuscation):
3829
3830          $ aria2c --bt-min-crypto-level=arc4 --bt-require-crypto=true file.torrent
3831

SEE ALSO

3833       Project Web Site: https://aria2.github.io/
3834
3835       Metalink Homepage: http://www.metalinker.org/
3836
3837       The Metalink Download Description Format: RFC 5854
3838
3840       Copyright (C) 2006, 2015 Tatsuhiro Tsujikawa
3841
3842       This program is free software; you can redistribute it and/or modify it
3843       under  the  terms of the GNU General Public License as published by the
3844       Free Software Foundation; either version 2 of the License, or (at  your
3845       option) any later version.
3846
3847       This  program  is  distributed  in the hope that it will be useful, but
3848       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
3849       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
3850       Public License for more details.
3851
3852       You should have received a copy of the GNU General Public License along
3853       with this program; if not, write to the Free Software Foundation, Inc.,
3854       51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
3855
3856       In addition, as a special exception, the copyright holders give permis‐
3857       sion  to  link  the  code  of portions of this program with the OpenSSL
3858       library under certain conditions as described in each individual source
3859       file,  and  distribute linked combinations including the two.  You must
3860       obey the GNU General Public License in all respects for all of the code
3861       used  other  than  OpenSSL.  If you modify file(s) with this exception,
3862       you may extend this exception to your version of the file(s),  but  you
3863       are  not  obligated to do so.  If you do not wish to do so, delete this
3864       exception statement from your version.  If you  delete  this  exception
3865       statement  from  all  source  files in the program, then also delete it
3866       here.
3867
3868
3869
3870
38711.35.0                           Oct 06, 2019                        ARIA2C(1)
Impressum