Update aria2c.rst

doc/manual-src/ru/aria2c.rst

@@ -655,7 +655,7 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
 .. option:: --bt-max-open-files=<NUM>
 
   Указать глобально максимальное количество файлов для открытия в многофайловой
-  BitTorrent-загрузке.
+  BitTorrent/Metalink-загрузке.
   По умолчанию: ``100``
 
 .. option:: --bt-max-peers=<NUM>
@@ -989,10 +989,8 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
 .. option:: --enable-rpc[=true|false]
 
   Включить JSON-RPC/XML-RPC-сервер. Настоятельно рекомендуется указать
-  имя пользователя и пароль, используя параметры
-  :option:`--rpc-user` и :option:`--rpc-passwd`.
-  Смотрите также параметр :option:`--rpc-listen-port`.
-  По умолчанию: ``false``
+  секретный маркер авторизации, используя параметр :option:`--rpc-secret`.
+  Смотрите также параметр :option:`--rpc-listen-port`. По умолчанию: ``false``
 
 .. option:: --pause[=true|false]
 
@@ -1056,6 +1054,12 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
 
   Задать JSON-RPC/XML-RPC пароль.
 
+  .. Warning::
+
+    Параметр :option:`--rpc-passwd` будет устаревшим в будущих
+    версиях. Перейдите на использование параметра :option:`--rpc-secret`
+    как можно скорее.
+
 .. option:: --rpc-private-key=<FILE>
 
   Использовать закрытый ключ в FILE для RPC-сервера. Закрытый ключ должен
@@ -1074,6 +1078,11 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
   сохраняться при помощи параметра :option:`--save-session`.
   По умолчанию: ``false``
 
+.. option:: --rpc-secret=<TOKEN>
+
+   Задать секретный маркер RPC-авторизации. Читайте :ref:`rpc_auth`,
+   чтобы узнать, как использовать значение этого параметра.
+
 .. option:: --rpc-secure[=true|false]
 
   RPC-транспорт будет зашифрован с использованием SSL/TLS. RPC-клиенты должны
@@ -1086,6 +1095,12 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
 
   Задать JSON-RPC/XML-RPC пользователя.
 
+  .. Warning::
+
+    Параметр :option:`--rpc-user` будет устаревшим в будущих
+    версиях. Перейдите на использование параметра :option:`--rpc-secret`
+    как можно скорее.
+
 Дополнительные параметры
 ~~~~~~~~~~~~~~~~~~~~~~~~
 .. option:: --allow-overwrite[=true|false]
@@ -1219,6 +1234,21 @@ FTP, BitTorrent и Metalink. Для загрузки файла, aria2 може
   запрашиваемого файла в отдельной строке.
   По умолчанию: ``default``
 
+.. option:: --dscp=<DSCP>
+
+  Задать значение DSCP в исходящих IP-пакетах BitTorrent-трафика для
+  QoS. Этот параметр изменяет только DSCP-биты в поле ToS IP-пакетов, а
+  не всё поле. Если вы берёте значения из */usr/include/netinet/ip.h*,
+  то делите их на 4 (иначе значения будут неверными, например,
+  ваш класс ``CS1`` превратится в ``CS4``). Если берёте обычно используемые
+  значения из RFC, документации сетевых производителей, Википедии или других
+  источников, то используйте их как есть.
+
+.. option:: --enable-color[=true|false]
+
+  Включить цветной вывод для терминала.
+  По умолчанию: ``true``
+
 .. option:: --enable-mmap[=true|false]
 
    Отображение файлов в память. Этот параметр может не работать,
@@ -1665,13 +1695,12 @@ RPC-метода :func:`aria2.getFiles`. Если вы хотите получи
   Если ресурс не был найден.
 
 4
-  Если aria2 получила определенное число ошибок "ресурс не найден". Смотрите
-  параметр :option:`--max-file-not-found`.
+  Если aria2 получила определенное число ошибок "ресурс не найден".
+  Смотрите параметр :option:`--max-file-not-found`.
 
 5
-  Если загрузка прервана, поскольку скорость загрузки была слишком
-  медленной. Смотрите параметр 
-  :option:`--lowest-speed-limit`.
+  Если загрузка прервана, поскольку скорость загрузки была слишком медленной.
+  Смотрите параметр :option:`--lowest-speed-limit`.
 
 6
   Если произошла проблема с сетью.
@@ -1738,8 +1767,7 @@ RPC-метода :func:`aria2.getFiles`. Если вы хотите получи
   Если HTTP-авторизация не удалась.
 
 25
-  Если aria2 не смогла проанализировать закодированный файл (обычно
-  файл ".torrent").
+  Если aria2 не смогла проанализировать закодированный файл (обычно файл ".torrent").
 
 26
   Если файл ".torrent" был испорчен или потеряна информация, которая необходима
@@ -2126,13 +2154,42 @@ GID
   При запросе загрузки по GID, вы можете задать префикс GID пока он
   является уникальным префиксом среди других.
 
+.. _rpc_auth:
+
+RPC-авторизация по секретному маркеру
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Начиная с 1.18.4, в дополнение к базовой HTTP-авторизации, aria2
+обеспечивает method-level RPC-авторизацию. В будущих версиях, базовая
+HTTP-авторизация будет удалена и method-level RPC-авторизация станет
+обязательной.
+
+Чтобы использовать method-level RPC-авторизацию, пользователь должен указать
+секретный маркер RPC-авторизации, используя параметр
+:option:`--rpc-secret`. Для каждого вызова RPC-метода, вызывающий должен
+включать маркер с префиксом ``token:``. Если параметр :option:`--rpc-secret`
+не используется, а первым параметром в RPC-методе является строка и
+начинается с ``token:``, то ``token:`` удаляется из параметра метода перед
+обработкой.
+
+Например, если секретный маркер RPC-авторизации - ``$$secret$$``, то
+вызываемый RPC-метод `aria2.addUri` будет выглядеть следующим образом:
+
+  aria2.addUri("token::$$secret$$", ["http://example.org/file"])
+
+RPC-метод `system.multicall` обрабатывается особым образом. Поскольку
+спецификация XML-RPC позволяет использовать только один массив в качестве
+параметра для этого метода, мы не указываем маркер в его вызове. Вместо
+этого каждый вложенный вызов метода должен обеспечивать маркер в качестве
+первого параметра, как описано выше.
+
 Методы
 ~~~~~~
 
-Весь код в примерах написан на Python2.7.
+Весь код в примерах написан на Python2.7. О параметре *secret* смотрите
+:ref:`rpc_auth`.
 
-
-.. function:: aria2.addUri(uris[, options[, position]])
+.. function:: aria2.addUri([secret], uris[, options[, position]])
 
   Этот метод добавляет новый HTTP(S)/FTP/BitTorrent Magnet URI. Параметр
   *uris* имеет тип массив, элемент которого имеет тип строка и содержит
@@ -2181,7 +2238,7 @@ GID
     >>> s.aria2.addUri(['http://example.org/file'], {}, 0)
     'ca3d829cee549a4d'
 
-.. function:: aria2.addTorrent(torrent[, uris[, options[, position]]])
+.. function:: aria2.addTorrent([secret], torrent[, uris[, options[, position]]])
 
   Этот метод добавляет BitTorrent-загрузку путем загрузки .torrent-файла.
   Если вы хотите добавить BitTorrent Magnet URI, взамен используйте метод
@@ -2232,7 +2289,7 @@ GID
     >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read()))
     '2089b05ecca3d829'
 
-.. function:: aria2.addMetalink(metalink[, options[, position]])
+.. function:: aria2.addMetalink([secret], metalink[, options[, position]])
 
   Этот метод добавляет Metalink-загрузку путем загрузки .metalink-файла.
   Параметр *metalink* имеет тип base64, с содержанием
@@ -2276,7 +2333,7 @@ GID
     >>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4').read()))
     ['2089b05ecca3d829']
 
-.. function:: aria2.remove(gid)
+.. function:: aria2.remove([secret], gid)
 
   Этот метод удаляет загрузку, которая обозначена *gid*. Параметр *gid* имеет
   тип строка. Если указана загрузка, которая загружается в данный момент, то
@@ -2306,14 +2363,14 @@ GID
     >>> s.aria2.remove('2089b05ecca3d829')
     '2089b05ecca3d829'
 
-.. function:: aria2.forceRemove(gid)
+.. function:: aria2.forceRemove([secret], gid)
 
   Этот метод удаляет загрузку, которая обозначена *gid*. Метод действует
   подобно :func:`aria2.remove`, за исключением того, что
   метод удаляет загрузку без каких-либо действий, которые требует времени,
   например связь с BitTorrent-трекером.
 
-.. function:: aria2.pause(gid)
+.. function:: aria2.pause([secret], gid)
 
   Этот метод приостанавливает загрузку, которая обозначена *gid*. Параметр
   *gid* имеет тип строки. Статус приостановки станет ``paused``
@@ -2322,36 +2379,36 @@ GID
   смены статуса на ``waiting``, используйте метод :func:`aria2.unpause`.
   Этот метод возвращает GID приостановленной загрузки.
 
-.. function:: aria2.pauseAll()
+.. function:: aria2.pauseAll([secret])
 
   Этот метод эквивалентен по вызову :func:`aria2.pause`, для каждой
   активной/ожидающей закачки. Этот метод возвращает ``OK``, в случае
   успеха.
 
-.. function:: aria2.forcePause(pid)
+.. function:: aria2.forcePause([secret], pid)
 
   Этот метод приостанавливает загрузку, которая обозначена *gid*. Метод
   действует подобно :func:`aria2.pause`, за исключением
   того, что метод приостанавливает загрузку без каких-либо действий, которые
   требует времени, например связь с BitTorrent-трекером.
 
-.. function:: aria2.forcePauseAll()
+.. function:: aria2.forcePauseAll([secret])
 
   Этот метод эквивалентен по вызову :func:`aria2.forcePause`, для каждой
   активной/ожидающей закачки. Этот метод возвращает ``OK``, в случае успеха.
 
-.. function:: aria2.unpause(gid)
+.. function:: aria2.unpause([secret], gid)
 
   Этот метод изменяет статус загрузки, которая обозначена 'gid', с ``paused`` на
   ``waiting``. Это позволяет перезапускать загрузку. Значение ключа *gid* имеет
   тип строки. Этот метод возвращает GID, снятой с паузы, загрузки.
 
-.. function:: aria2.unpauseAll()
+.. function:: aria2.unpauseAll([secret])
 
   Этот метод эквивалентен по вызову :func:`aria2.unpause`, для каждой
   активной/ожидающей закачки. Этот метод возвращает ``OK``, в случае успеха.
 
-.. function:: aria2.tellStatus(gid[, keys])
+.. function:: aria2.tellStatus([secret], gid[, keys])
 
   Этот метод возвращает состояние загрузки, которая обозначена *gid*. Параметр
   *gid* имеет тип строка. Параметр *keys* имеет тип массив строк. Если *keys*
@@ -2548,7 +2605,7 @@ GID
     >>> pprint(r)
     {'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'}
 
-.. function:: aria2.getUris(gid)
+.. function:: aria2.getUris([secret], gid)
 
   Этот метод возвращает URI, используемые в загрузке, которая обозначена
   *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип массив, а элемент -
@@ -2585,7 +2642,7 @@ GID
     >>> pprint(r)
     [{'status': 'used', 'uri': 'http://example.org/file'}]
 
-.. function:: aria2.getFiles(gid)
+.. function:: aria2.getFiles([secret], gid)
 
   Этот метод возвращает список файлов загрузки, которая обозначена
   *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип массив, а элемент -
@@ -2655,7 +2712,7 @@ GID
       'uris': [{'status': 'used',
                 'uri': 'http://example.org/file'}]}]
 
-.. function:: aria2.getPeers(gid)
+.. function:: aria2.getPeers([secret], gid)
 
   Этот метод возвращает список пиров загрузки, которая обозначена
   *gid*. Параметр *gid* имеет тип строка. Этот метод только для
@@ -2750,7 +2807,7 @@ GID
       'seeder': 'false,
       'uploadSpeed': '6890'}]
 
-.. function:: aria2.getServers(gid)
+.. function:: aria2.getServers([secret], gid)
 
   Этот метод возвращает текущие подключенные HTTP(S)/FTP-серверы загрузки,
   которая обозначена *gid*. Параметр *gid* имеет тип строка. Ответ имеет тип
@@ -2804,7 +2861,7 @@ GID
                    'downloadSpeed': '20285',
                    'uri': 'http://example.org/file'}]}]
 
-.. function:: aria2.tellActive([keys])
+.. function:: aria2.tellActive([secret], [keys])
 
   Этот метод возвращает список активных загрузок. Ответ имеет тип массив и его
   элемент такая же структура, которая возвращается методом
@@ -2812,7 +2869,7 @@ GID
   параметре 'keys', обратитесь к методу 
   :func:`aria2.tellStatus`.
 
-.. function:: aria2.tellWaiting(offset, num, [keys])
+.. function:: aria2.tellWaiting([secret], offset, num, [keys])
 
   Этот метод возвращает список ожидающих загрузок, включая приостановленные
   загрузки. *offset* имеет целочисленный тип и указывает смещение, начиная от
@@ -2836,7 +2893,7 @@ GID
   Ответ имеет тип массив и его элемент такая же структура, которая
   возвращается методом :func:`aria2.tellStatus`.
 
-.. function:: aria2.tellStopped(offset, num, [keys])
+.. function:: aria2.tellStopped([secret], offset, num, [keys])
 
   Этот метод возвращает список остановленных загрузок. *offset* имеет
   целочисленный тип и указывает смещение, начиная с самой старой
@@ -2850,7 +2907,7 @@ GID
   Ответ имеет тип массив и его элемент такая же структура, которая
   возвращается методом :func:`aria2.tellStatus`.
 
-.. function:: aria2.changePosition(gid, pos, how)
+.. function:: aria2.changePosition([secret], gid, pos, how)
 
   Этот метод меняет позицию загрузки, которая обозначена *gid*. *pos* имеет
   целочисленный тип. *how* имеет тип строка. Если *how* - ``POS_SET``, то это
@@ -2892,7 +2949,7 @@ GID
     >>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')
     0
 
-.. function:: aria2.changeUri(gid, fileIndex, delUris, addUris[, position])
+.. function:: aria2.changeUri([secret], gid, fileIndex, delUris, addUris[, position])
 
   Этот метод удаляет URI в *delUris* из загрузки и добавляет URI в *addUris* к
   загрузке, которая обозначена *gid*. *delUris* и *addUris* являются списком
@@ -2938,7 +2995,7 @@ GID
                           ['http://example.org/file'])
     [0, 1]
 
-.. function:: aria2.getOption(gid)
+.. function:: aria2.getOption([secret], gid)
 
   Этот метод возвращает параметры загрузки, которая обозначена *gid*. Ответ
   имеет тип структура. Ее поля - это название параметра. Поле имеет тип
@@ -2982,7 +3039,7 @@ GID
      'async-dns': 'true',
      ....
 
-.. function:: aria2.changeOption(gid, options)
+.. function:: aria2.changeOption([secret], gid, options)
 
   Этот метод изменяет динамически параметры загрузки, которая обозначена
   *gid*. *gid* имеет тип строка. *options* имеет тип структура. Доступны
@@ -3031,7 +3088,7 @@ GID
     >>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'})
     'OK'
 
-.. function:: aria2.getGlobalOption()
+.. function:: aria2.getGlobalOption([secret])
 
   Этот метод возвращает глобальные параметры. Ответ имеет тип структура. Ее
   поля - это название параметра. Поле имеет тип строка. Обратите внимание, что
@@ -3041,7 +3098,7 @@ GID
   для вновь добавляемой загрузки, ответ содержит поля возвращаемые методом
   :func:`aria2.getOption`.
 
-.. function:: aria2.changeGlobalOption(options)
+.. function:: aria2.changeGlobalOption([secret], options)
 
   Этот метод изменяет динамически глобальные параметры. *options* имеет тип
   структура. Доступны следующие параметры:
@@ -3069,7 +3126,7 @@ GID
   значения параметра. Обратите внимание, что файл журнала событий всегда
   открыт в режиме добавления. Этот метод возвращает ``OK``, в случае успеха.
 
-.. function:: aria2.getGlobalStat()
+.. function:: aria2.getGlobalStat([secret])
 
   Этот метод возвращает глобальную статистику по скорости загрузки и скорости
   отдачи. Ответ имеет тип структура и содержит следующие поля. Поле имеет тип
@@ -3088,7 +3145,12 @@ GID
     Количество ожидающих загрузок.
 
   ``numStopped``
-    Количество остановленных загрузок.
+    Количество остановленных загрузок в текущей сессии. Это значение
+    ограничено параметром :option:`--max-download-result`.
+
+  ``numStoppedTotal``
+    Количество остановленных загрузок в текущей сессии и не
+    ограничено параметром :option:`--max-download-result`.
 
   **Пример JSON-RPC**
   ::
@@ -3121,12 +3183,12 @@ GID
      'numWaiting': '0',
      'uploadSpeed': '0'}
 
-.. function:: aria2.purgeDownloadResult()
+.. function:: aria2.purgeDownloadResult([secret])
 
   Этот метод очищает, для освобождения памяти, завершенные/ошибка/удаленные
   загрузки. Метод возвращает ``OK``.
 
-.. function:: aria2.removeDownloadResult(gid)
+.. function:: aria2.removeDownloadResult([secret], gid)
 
   Этот метод удаляет из памяти завершенную/ошибка/удаленную загрузку, которая
   обозначена *gid*. Метод возвращает ``OK``, в случае успеха.
@@ -3155,7 +3217,7 @@ GID
     >>> s.aria2.removeDownloadResult('2089b05ecca3d829')
     'OK'
 
-.. function:: aria2.getVersion()
+.. function:: aria2.getVersion([secret])
 
   Этот метод возвращает версию программы и список включенных
   возможностей. Ответ имеет тип структура и содержит следующие поля.
@@ -3205,7 +3267,7 @@ GID
                          'XML-RPC'],
      'version': '1.11.0'}
 
-.. function:: aria2.getSessionInfo()
+.. function:: aria2.getSessionInfo([secret])
 
   Этот метод возвращает информацию о сессии. Ответ имеет тип структура и
   содержит следующие поля.
@@ -3234,11 +3296,11 @@ GID
     >>> s.aria2.getSessionInfo()
     {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}
 
-.. function:: aria2.shutdown()
+.. function:: aria2.shutdown([secret])
 
   Этот метод закрывает aria2. Метод возвращает ``OK``.
 
-.. function:: aria2.forceShutdown()
+.. function:: aria2.forceShutdown([secret])
 
   Этот метод закрывает aria2. Метод действует подобно
   :func:`aria2.shutdown`, за исключением того, что