RTORRENT(1)

📦
version 0.16.17 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 RTORRENT(1) — bestie, let's talk 💅

ok so this is the manual for rtorrent. grab a snack 🍓, put your hair up, we're doing the whole thing. no skipping. i said what i said. 💖

✨ NAME ✨

rtorrent — a BitTorrent client for ncurses. iconic. that's the whole vibe. 👑

✨ SYNOPSIS ✨

rtorrent [ -h ] [ -n ] [ -o key1=opt1,... ] [ -O key=opt ] [ URL | FILE ... ]

✨ DESCRIPTION ✨

so like, rtorrent is a BitTorrent client for ncurses, and it runs on the libtorrent library. the client AND the library are written in C++ and they are obsessed with speed and efficiency — main character energy, fr — while still delivering all the features you'd find in those GUI-based clients, except in an ncurses client. slay. 💅

lowkey important: most of the options below have their own default unit, and on top of that they also support the B, K, M and G suffixes. so you have options, literally. ✨

⌨️ KEYBOARD CONTROL ⌨️

🎀 GLOBAL KEYS 🎀

  • ^q — initiate shutdown. press it again to force the shutdown and skip sending the stop signal to trackers. (that second press is the "ok bye for real" press 🫶)
  • up | down | left | right — the arrow keys. they're here.
  • ^P | ^N | ^B | ^F — select entries or change windows. the right arrow key or ^F is often used for viewing details about the selected entry, while the left arrow key or ^B often returns you to the previous screen. it's giving "back button but make it keystrokes". 🦋
  • a | s | d — increase the upload throttle by 1/5/50 KB.
  • A | S | D — increase the download throttle by 1/5/50 KB.
  • z | x | c — decrease the upload throttle by 1/5/50 KB.
  • Z | X | C — decrease the download throttle by 1/5/50 KB.
lowercase = up-up-up, capital = down-down-down. no cap, that's the pattern. 🧚

🌸 MAIN VIEW KEYS 🌸

  • -> — view download.
  • 1 - 7 — change view.
  • ^S — start download. go girl go.
  • ^D — stop an active download, or remove a stopped download.
  • ^K — close a torrent and its files.
  • ^E — set the 'create/resize queued' flags on all files in a torrent. this is necessary if the underlying files in a torrent have been deleted or truncated, and thus rtorrent must recreate them.
  • ^R — initiate hash check of torrent.
  • ^O — change the destination directory of the download. 🚨 the torrent must be closed first.
  • ^X — call commands or change settings.
  • ^B — set download to perform initial seeding. ⚠️ only use this when you are the first and only seeder so far for the download. like, genuinely only then.
  • + | - — change the priority of the download.
  • backspace — add torrent using an URL or file path. use tab to view directory content and do auto-complete. king behavior 🫶
  • l — view log. exit by pressing the space-bar.
  • U — delete the file the torrent is tied to, and clear the association.
  • I — toggle whether torrent ignores ratio settings.

🦋 DOWNLOAD VIEW KEYS 🦋

  • -> — view torrent file list. use the space-bar to change the file priority and * to change the priority of all files. use / to collapse the directories. OUTDATED.
  • 1 | 2 — adjust max uploads.
  • 3 | 4 — adjust min peers.
  • 5 | 6 — adjust max peers.
  • u — display transferring blocks.
  • i — display chunk rarity.
  • o — display the tracker list. cycle the trackers in a group with the space-bar.
  • p — view peer and torrent information.
  • t | T — initiate tracker request. use capital T to force the request, ignoring the "min interval" set by the tracker. periodt.
  • k — disconnect peer.
  • * — choke/snub peer.

💜 OPTIONS 💜

  • -b a.b.c.d — bind listening socket and outgoing connections to this network interface address.
  • -d directory — set the default download directory. defaults to "./".
  • -h — display help and exit.
  • -i a.b.c.d — set the address reported to the tracker.
  • -n — don't load ~/.rtorrent.rc on startup.
  • -o key1=opt1,... — set any number of options, see the SETTINGS section. the options given here override the resource files.
  • -O key=opt — same deal, but with capital -O you're allowed to have a comma inside the option. set any number of options, see the SETTINGS section, and again: these override the resource files.
  • -p a-b — try to open a listening port in the range a up to and including b.
  • -s directory — session management will be enabled and the torrent files for all open downloads will be stored in this directory. ⚠️ only one instance of rtorrent should be used with each session directory, though at the moment no locking is done. an empty string will disable the session directory.

🌈 GENERAL SETTINGS 🌈

  • bind = a.b.c.d — bind listening socket and outgoing connections to this network interface address.
  • ip = a.b.c.d — set the address reported to the tracker.
  • ip = hostname — set the address reported to the tracker.
  • port_range = a-b — try to open a listening port in the range a up to and including b.
  • port_random = yes | no — open the listening port at a random position in the port range.
  • check_hash = yes | no — perform hash check on torrents that have finished downloading.
  • directory = directory — set the default download directory. defaults to "./".
  • session = directory — session management will be enabled and the torrent files for all open downloads will be stored in this directory. 🫨 only one instance of rtorrent can be used per session directory. an empty string will disable the session directory.
  • http_proxy = url — use a http proxy. use an empty string to disable.
  • encoding_list = encoding — add a preferred filename encoding to the list. the encodings are attempted in the order they are inserted, and if none match, the torrent default is used.
  • encryption = option,... — set how rtorrent should deal with encrypted Bittorrent connections. by default, encryption is disabled, which is equivalent to specifying the option none. alternatively, any number of the following options may be specified:
    • allow_incoming (allow incoming encrypted connections)
    • try_outgoing (use encryption for outgoing connections)
    • require (disable unencrypted handshakes)
    • require_RC4 (also disable plaintext transmission after the initial encrypted handshake)
    • enable_retry (if the initial outgoing connection fails, retry with encryption turned on if it was off or off if it was on)
    • prefer_plaintext (choose plaintext when peer offers a choice between plaintext transmission and RC4 encryption, otherwise RC4 will be used)
  • peer_exchange = yes | no — enable/disable peer exchange for torrents that aren't marked private. disabled by default.
  • start_tied = — start torrents that are tied to filenames that have been re-added.
  • stop_untied = — stop the torrents that are tied to filenames that have been deleted. clear the association with the 'U' key.
  • close_untied = — close the torrents that are tied to filenames that have been deleted. clear the association with the 'U' key.
  • remove_untied = — remove the torrents that are tied to filenames that have been deleted. clear the association with the 'U' key.
  • close_low_diskspace = space — close any active torrents on filesystems with less than space diskspace left. use with the schedule option. a default scheduled event with id low_diskspace is set to 500Mb.
  • load = file — load a file, or possibly multiple files by using the wild-card "*". this is meant for use with schedule, though ensure that the start is non-zero. the loaded file will be tied to the filename provided. ✨
  • load_verbose = file — load a file, or possibly multiple files by using the wild-card "*". this is meant for use with schedule, though ensure that the start is non-zero. the loaded file will be tied to the filename provided. ✨
  • load_start = file — load and possibly start a file, or possibly multiple files by using the wild-card "*". this is meant for use with schedule, though ensure that the start is non-zero. the loaded file will be tied to the filename provided. ✨
  • load_start_verbose = file — load and possibly start a file, or possibly multiple files by using the wild-card "*". this is meant for use with schedule, though ensure that the start is non-zero. the loaded file will be tied to the filename provided. ✨
  • import = file — load a resource file.
  • try_import = file — load a resource file. the difference? try_import does not throw torrent::input_error exception on bad input. 🫶

🔥 THROTTLE SETTINGS 🔥

  • upload_rate = KB — set the maximum global upland rate. (yes bestie, "upload".)
  • download_rate = KB — set the maximum global download rate.
  • set_upload_rate = TODO — set the maximum global upland rate.
  • set_download_rate = TODO — set the maximum global download rate.
  • min_peers = value — set the minimum number of peers to allow in each download.
  • max_peers = value — set the maximum number of peers to allow in each download.
  • min_peers_seed = value — set the minimum number of peers to allow while seeding, or -1 (default) to use max_peers.
  • max_peers_seed = value — set the maximum number of peers to allow while seeding, or -1 (default) to use max_peers.
  • max_uploads = value — set the maximum number of simultaneous uploads per upload.
  • max_downloads = value — set the maximum number of simultaneous downloads per download.
  • min_uploads = value — set the minimum number of simultaneous uploads per upload.
  • min_downloads = value — set the minimum number of simultaneous downloads per download.
  • max_uploads_div = value — change the divider used to calculate the max upload slots to use when the throttle is changed. disable by setting 0.
  • max_downloads_div = value — change the divider used to calculate the max download slots to use when the throttle is changed. disable by setting 0.
  • set_max_uploads_div = value — change the divider used to calculate the max upload slots to use when the throttle is changed. disable by setting 0.
  • set_max_downloads_div = value — change the divider used to calculate the max download slots to use when the throttle is changed. disable by setting 0.
  • max_uploads_global = value — max upload slots allowed. disable by setting 0.
  • max_downloads_global = value — max download slots allowed. disable by setting 0.
  • set_max_uploads_global = value — max upload slots allowed. disable by setting 0.
  • set_max_downloads_global = value — max download slots allowed. disable by setting 0.
  • throttle_up = name, upload_rate — define secondary throttle and/or set the given upload rate. attach to a download with the d.set_throttle_name=name command or switch throttles with Ctrl+T. 🚨 the download must be stopped when changing throttles. note that secondary throttles only work if the global upload/download is throttled. setting a download to use the NULL throttle makes the download unthrottled even when there is a global throttle — but heads up, this special case bypasses the global throttle entirely, and as such its rate and transfer amounts are not included in the global statistics. 💀
  • throttle_down = name, download_rate — define secondary throttle and/or set the given download rate. attach to a download with the d.set_throttle_name=name command or switch throttles with Ctrl+T. 🚨 the download must be stopped when changing throttles. note that secondary throttles only work if the global upload/download is throttled. setting a download to use the NULL throttle makes the download unthrottled even when there is a global throttle — and again, that special case bypasses the global throttle entirely, so its rate and transfer amounts are not included in the global statistics. 💀
  • throttle_ip = name, host — use the given secondary throttle for a host. all peers with a matching IP will use this throttle instead of the global throttle or a custom download throttle. the name may be NULL to make these peers unthrottled, with the same caveats as explained above.
  • throttle_ip = name, network/prefix — use the given secondary throttle for a CIDR network. all peers with a matching IP will use this throttle instead of the global throttle or a custom download throttle. the name may be NULL to make these peers unthrottled, with the same caveats as explained above.
  • throttle_ip = name, start, end — use the given secondary throttle for an IP range. all peers with a matching IP will use this throttle instead of the global throttle or a custom download throttle. the name may be NULL to make these peers unthrottled, with the same caveats as explained above.

tracker related settings. 💅

  • enable_trackers = yes — set to no to disable all tracker requests. useful for disabling rtorrent with the schedule command.
  • tracker_dump = filename — dump tracker requests to filename, disable by supplying an empty string. 📌 at the moment, only torrents loaded while tracker_dump contains a non-empty string will be logged, although disabling it will work as expected.
  • tracker_numwant = number — set the numwant field sent to the tracker, which indicates how many peers we want. a negative value disables this feature.
  • use_udp_trackers = yes — use UDP trackers. disable if you are behind a firewall, etc, that does not allow connections to UDP trackers.
  • http_capath = path — set the certificates to use in http requests. see Curl's CURLOPT_CAPATH option for further information.
  • http_cacert = filename — set the certificates to use in http requests. see Curl's CURLOPT_CAINFO option for further information.

Okay bestie, these are all about the Distributed Hash Table vibes. DHT said "I can find peers without a tracker" and honestly? Iconic.

  • dht = disable|off|auto|on — This one controls whether we query the distributed hash table (DHT) to find peers for trackerless torrents or when all trackers are down. Set it to disable to completely disable DHT, off (the default) to enable DHT but not start the DHT server, auto to automatically start and stop the DHT server as needed, or on to permanently keep the DHT server running. When set to automatic, the DHT server starts up when the first non-private torrent is started, and stops 15-30 minutes after the last non-private torrent is stopped (or when rTorrent quits). For DHT to work, a session directory must be set (for saving the DHT cache). 💅
  • dht_port = number — Set the UDP listen port for DHT. Defaults to 6881.
  • dht_add_node = host[:port] — Not intended for use in the config file, but as a one-time option in the client or on the command line to bootstrap an empty DHT node table. It contacts the given node and attempts to bootstrap from it if it replies. The port is optional, with port 6881 being used by default.
  • dht_statistics = TODO — TODO
  • set_dht_port = TODO — TODO
  • set_dht_throttle = TODO — TODO

💖 USER-INTERFACE SETTINGS 💖

Display related settings, aka the glow-up for your screen.

  • view_add = name — Create a new view.
  • view_sort = name
  • view_sort = name,seconds — Sort a view according to the criteria set by view_sort_current. If the optional argument is supplied, the view is not sorted if a change happened during the last seconds. This command is meant to be used with schedule.
  • view_sort_new = name,...
  • view_sort_current = name,... — Set the sorting criteria for when new elements are inserted or view_sort is called. The list can contain any number of criteria, including zero, from the following: name, name_reverse, stopped, started, complete, incomplete, state_changed, state_changed_reverse.
  • key_layout = qwerty|azerty|qwertz|dvorak — Change the key-bindings.

🦋 FILE-SYSTEM SETTINGS 🦋

File-system related settings, because files deserve boundaries too.

  • max_file_size = size — Set the maximum size a file can have. Disable by passing -1.
  • split_file_size = size — Split files in a torrent larger than size into separate files. Disable by passing -1.
  • split_suffix = string — Set the suffix used on split files. Defaults to .part.

🌸 DOWNLOAD SETTINGS 🌸

Settings that require a download as a target. The options need to be called through f.ex. on_finished.

  • create_link = type,path,suffix
  • delete_link = type,path,suffix — Create or delete a symbolic link. The link path is the concatenation of path, the result of the type on the download, and suffix.

Available types are; base_path uses the base path of the download, base_filename uses the base filename of the download, tied uses the path of the file the download is tied to, see start_tied.

💀 ADVANCED SETTINGS 💀

This list contains settings users shouldn't need to touch, some may even cause crashes or similar if incorrectly set. Be careful, bestie. 🫶
  • hash_read_ahead = MB — Configure how far ahead we ask the kernel to read when doing hash checking. The hash checker uses madvise(..., MADV_WILLNEED) for the requests.
  • hash_interval = ms — Interval between attempts to check the hash when the chunk is not in memory, in milliseconds.
  • hash_max_tries = tries — Number of attempts to check the hash while using the mincore status, before forcing. Overworked systems might need lower values to get a decent hash checking rate.
  • safe_sync = yes|no — Always use MS_SYNC rather than MS_ASYNC when syncing chunks. This may be nessesary in case of filesystem bugs like NFS in linux ~2.6.13.
  • max_open_files = value — Number of files to simultaneously keep open. LibTorrent dynamically opens and closes files as necessary when mapping files to memory. Default is based on sysconf(_SC_OPEN_MAX). You probably only think you know what this option does, so don't touch it. 😭
  • max_open_sockets = value — Number of network sockets to simultaneously keep open. This value is set to a reasonable value based on sysconf(_SC_OPEN_MAX).
  • max_open_http = value — Number of sockets to simultaneously keep open. This value is set to 32 by default.
  • max_memory_usage = bytes — Set the max amount of memory space used to mapping file chunks. This may also be set using ulimit -m where 3/4 will be allocated to file chunks.
  • send_buffer_size = value — Adjust the send and receive buffer size for socket.
  • receive_buffer_size = value — Adjust the send and receive buffer size for socket.
  • umask = 0022 — Set the umask for this process, which is applied to all files created by the program.
  • cwd = directory — Changes the working directory of the process using chdir.
  • session_on_completion = yes — Controls if the session torrent is saved when a torrent finishes. By default on.
  • session_lock = yes — Controls if a lock file is created in the session directory on startup.
  • session_save = — Save the session files for all downloads.
  • tos = default|lowdelay|throughput|reliability|mincost — Change the TOS of peer connections, by default set to throughput. If the option is set to default then the system default TOS is used. A hex value may be used for non-standard settings.
  • tos = hex — Change the TOS of peer connections, by default set to throughput. If the option is set to default then the system default TOS is used. A hex value may be used for non-standard settings.
  • handshake_log = yes — Enable logging of the peer handshake. This generates a large number of log messages, but may be useful to debug connection problems.

👑 AUTHORS 👑

Jari "Rakshasa" Sundell <jaris@ifi.uio.no>

Okay so that's the whole manual, bestie. This masterpiece is from the BitTorrent client for ncurses, dated 25 February 2015, and it's RTORRENT(1). Slay. 💖✨

📦 where this page comes from