Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
280 lines (186 sloc) 7.1 KB

Commands Reference

The reference chapter lists all relevant XMLRPC and ‘private’ commands provided by rTorrent with a short explanation. See the :doc:`scripting` on how to combine them into meaningful command sequences, and :ref:`xmlrpc-api` for some general hints on using the XMLRPC API

Use the search box in the sidebar to find specific commands, or the :ref:`search`. The :ref:`generated index <genindex>` also lists all the command names.

Important

All d.* commands take an info hash as the first argument when called over the XML-RPC API, to uniquely identify the target object. ‘Target’ is the term used for that 1st parameter in error messages and so on.

d.name = ‹hash› ≫ string ‹name›

When called within configuration methods or in a Ctrl-X prompt, the target is implicit. It is explicit and must be provided for all XMLRPC calls, with very few exceptions like the xmlrpc-c built-ins.

Also note that :command:`rtxmlrpc` has some magic that adds this to any command ending in .multicall or .multicall.filtered, from the time this change was introduced. :term:`d.multicall2` came later and thus needs an explicit target, and it is a bit of a mess. Changing this to be consistent is a breaking change, and might happen sometime in the future.

The following are similar, but incomplete resources:

Download Items and Attributes

Scripting

Logging, Files, and OS

Network (Sockets, HTTP, XMLRPC)

Bittorrent Protocol

User Interface

Miscellaneous

TODO (Groups)

  • choke_group
  • file
  • group
  • group2
  • keys
  • ratio
  • scheduler
.. glossary::

    directory.default
    directory.default.set
    directory
    encoding.add
    encoding_list

        **TODO**



.. glossary::

    trackers.disable
    trackers.enable
    trackers.numwant
    trackers.numwant.set
    trackers.use_udp
    trackers.use_udp.set

        **TODO**

    trackers.alias.items

        Returns all the mappings in the form ``«domain»=«alias»`` as a list.

        Note that domains that were not explicitly defined so far, but shown
        previously, are also contained in the list, with an empty alias. So to
        create a list for you to fill in the aliases, scroll through all your
        items on ``main`` or ``trackers``, so you can dump the domains of all
        loaded items.

        Example that prints all the domains and their aliases as commands that
        define them:

        .. code-block:: shell

            rtxmlrpc trackers.alias.items \
                | sed -r -e 's/=/, "/' -e 's/^/trackers.alias.set_key = /' -e 's/$/"/' \
                | tee ~/rtorrent/rtorrent.d/tracker-aliases.rc

        This also dumps them into the ``tracker-aliases.rc`` file to persist
        your mappings, and also make them easily editable. To reload edited
        alias definitions, use this:

        .. code-block:: shell

            rtxmlrpc "try_import=,~/rtorrent/rtorrent.d/tracker-aliases.rc"


    trackers.alias.set_key

        Sets an alias that replaces the given domain, when displayed on the
        right of the collapsed canvas.

        .. rubric:: Configuration Example

        .. code-block:: ini

            trackers.alias.set_key = bttracker.debian.org, Debian


TODO (singles)

.. glossary::

    print
    add_peer
    bind
    catch
    check_hash
    connection_leech
    connection_seed
    download_rate
    encoding_list
    encryption
    ip
    key_layout
    max_downloads
    max_downloads_div
    max_downloads_global
    max_memory_usage
    max_peers
    max_peers_seed
    max_uploads
    max_uploads_div
    max_uploads_global
    min_downloads
    min_peers
    min_peers_seed
    min_uploads
    on_ratio
    port_random
    port_range
    proxy_address
    scgi_local
    scgi_port
    torrent_list_layout
    upload_rate
    fi.filename_last
    fi.is_file
    file.append
    keys.layout
    keys.layout.set

        **TODO**


‘Intermediate’ Commands

The intermediate commands are kept around as aliases for ‘new’ ones – at least for the time being. Probably best avoided.

Avoiding the deprecated commands is a must, these will disappear at some time.

.. glossary::

    method.use_deprecated
    method.use_deprecated.set

        .. code-block:: ini

            method.use_deprecated ≫ bool (0 or 1)
            method.use_deprecated.set = ‹0 or 1› ≫ bool ‹current› (0 or 1)

        The default is ``true``.
        The undocumented ``-D`` command line options sets this to ``false``
        with a ``Disabled deprecated commands`` console message.

    method.use_intermediate
    method.use_intermediate.set

        .. code-block:: ini

            method.use_intermediate ≫ value (0 … 2)
            method.use_intermediate.set = ‹0 … 2› ≫ value ‹current› (0 … 2)

        The default is 1 (allow everywhere), values other than 1 or 2 are treated like 0.
        The undocumented ``-I`` command line options sets this to 0
        with a ``Disabled intermediate commands`` console message,
        while ``-K`` sets it to 2,
        printing ``Allowing intermediate commands without xmlrpc``.


All the command aliases can be found in these three source files: command_local.cc, command_throttle.cc, and main.cc. Search for REDIRECT using grep.

These are called intermediate:

  • executeexecute2 (ignore both, just use execute.throw)
  • scheduleschedule2
  • schedule_removeschedule_remove2
  • group.‹name›.viewgroup2.‹name›.view
  • group.‹name›.view.setgroup2.‹name›.view.set
  • group.‹name›.ratio.mingroup2.‹name›.ratio.min
  • group.‹name›.ratio.min.setgroup2.‹name›.ratio.min.set
  • group.‹name›.ratio.maxgroup2.‹name›.ratio.max
  • group.‹name›.ratio.max.setgroup2.‹name›.ratio.max.set
  • group.‹name›.ratio.uploadgroup2.‹name›.ratio.upload
  • group.‹name›.ratio.upload.setgroup2.‹name›.ratio.upload.set

rTorrent 0.9.7 adds some missing group.seeding.* command aliases.

Standard Configuration Sets