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

EXIT STATUS

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

ENVIRONMENT

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

FILES

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

RPC INTERFACE

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

MISC

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

EXAMPLE

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

SEE ALSO

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