1RTORRENT(1) RTORRENT(1)
2
6 rtorrent - a BitTorrent client for ncurses
7
9 rtorrent [ -h ] [ -n ] [ -o key1=opt1,... ] [ -O key=opt ] [ URL | FILE
10 ... ]
11
14 rtorrent is a BitTorrent client for ncurses, using the libtorrent
15 library. The client and library is written in C++ with emphasis on
16 speed and efficiency, while delivering equivalent features to those
17 found in GUI based clients in an ncurses client.
18 Most of the options below have their own default unit in addition to
20 supporting B, K, M and G suffixes.
21
23 GLOBAL KEYS
24 ^q Initiate shutdown, press again to force the shutdown and skip
25 sending the stop signal to trackers.
26 up | down | left | right arrow keys
28 ^P | ^N | ^B | ^F
30 Select entries or change windows. The right arrow key or ^F is
31 often used for viewing details about the selected entry, while
32 the left arrow key or ^B often returns to the previous screen.
33 a | s | d
35 Increase the upload throttle by 1/5/50 KB.
36 A | S | D
38 Increase the download throttle by 1/5/50 KB.
39 z | x | c
41 Decrease the upload throttle by 1/5/50 KB.
42 Z | X | C
44 Decrease the download throttle by 1/5/50 KB.
45 MAIN VIEW KEYS
47 -> View download.
48 1 - 7 Change view.
50 ^S Start download.
52 ^D Stop an active download, or remove a stopped download.
54 ^K Close a torrent and its files.
56 ^E Set the 'create/resize queued' flags on all files in a torrent.
58 This is necessary if the underlying files in a torrent have been
59 deleted or truncated, and thus rtorrent must recreate them.
60 ^R Initiate hash check of torrent.
62 ^O Change the destination directory of the download. The torrent
64 must be closed.
65 ^X Call commands or change settings.
67 ^B Set download to perform initial seeding. Only use when you are
69 the first and only seeder so far for the download.
70 + | - Change the priority of the download.
72 backspace
74 Add torrent using an URL or file path. Use tab to view directory
75 content and do auto-complete.
76 l View log. Exit by pressing the space-bar.
78 U Delete the file the torrent is tied to, and clear the associa‐
80 tion.
81 I Toggle whether torrent ignores ratio settings.
83 DOWNLOAD VIEW KEYS
85 -> View torrent file list. Use the space-bar to change the file
86 priority and * to change the priority of all files. Use / to
87 collapse the directories. OUTDATED
88 1 | 2 Adjust max uploads.
90 3 | 4 Adjust min peers.
92 5 | 6 Adjust max peers.
94 u Display transfering blocks.
96 i Display chunk rarity.
98 o Display the tracker list. Cycle the trackers in a group with the
100 space-bar.
101 p View peer and torrent information.
103 t | T Initiate tracker request. Use capital T to force the request,
105 ignoring the "min interval" set by the tracker.
106 k Disconnect peer.
108 * Choke/Snub peer.
110
112 -b a.b.c.d
113 Bind listening socket and outgoing connections to this network
114 interface address.
115 -d directory
117 Set the default download directory. Defaults to "./".
118 -h Display help and exit.
120 -i a.b.c.d
122 Set the address reported to the tracker.
123 -n Don't load ~/.rtorrent.rc on startup.
125 -o key1=opt1,...
127 -O key=opt
129 Set any number of options, see the SETTINGS section. The options
130 given here override the resource files. Use capital -O to allow
131 comma in the option.
132 -p a-b Try to open a listening port in the range a up to and including
134 b.
135 -s directory
137 Session management will be enabled and the torrent files for all
138 open downloads will be stored in this directory. Only one
139 instance of rtorrent should be used with each session directory,
140 though at the moment no locking is done. An empty string will
141 disable the session directory.
142
144 bind = a.b.c.d
145 Bind listening socket and outgoing connections to this network
146 interface address.
147 ip = a.b.c.d
149 ip = hostname
151 Set the address reported to the tracker.
152 port_range = a-b
154 Try to open a listening port in the range a up to and including
155 b.
156 port_random = yes | no
158 Open the listening port at a random position in the port range.
159 check_hash = yes | no
161 Perform hash check on torrents that have finished downloading.
162 directory = directory
164 Set the default download directory. Defaults to "./".
165 session = directory
167 Session management will be enabled and the torrent files for all
168 open downloads will be stored in this directory. Only one
169 instance of rtorrent can be used per session directory. An empty
170 string will disable the session directory.
171 http_proxy = url
173 Use a http proxy. Use an empty string to disable.
174 encoding_list = encoding
176 Add a preferred filename encoding to the list. The encodings are
177 attempted in the order they are inserted, if none match the tor‐
178 rent default is used.
179 encryption = option,...
181 Set how rtorrent should deal with encrypted Bittorrent connec‐
182 tions. By default, encryption is disabled, equivalent to speci‐
183 fying the option none. Alternatively, any number of the follow‐
184 ing options may be specified:
185 allow_incoming (allow incoming encrypted connections), try_out‐
187 going (use encryption for outgoing connections), require (dis‐
188 able unencrypted handshakes), require_RC4 (also disable plain‐
189 text transmission after the initial encrypted handshake),
190 enable_retry (if the initial outgoing connection fails, retry
191 with encryption turned on if it was off or off if it was on),
192 prefer_plaintext (choose plaintext when peer offers a choice
193 between plaintext transmission and RC4 encryption, otherwise RC4
194 will be used).
195 peer_exchange = yes | no
197 Enable/disable peer exchange for torrents that aren't marked
198 private. Disabled by default.
199 schedule = id,start,interval,command
201 Call command every interval seconds, starting from start. An
202 interval of zero calls the task once, while a start of zero
203 calls it immediately. Currently command is forwarded to the
204 option handler. start and interval may optionally use a time
205 format, dd:hh:mm:ss. F.ex to start a task every day at 18:00,
206 use 18:00:00,24:00:00.
207 schedule_remove = id
209 Delete id from the scheduler.
210 start_tied =
212 Start torrents that are tied to filenames that have been re-
213 added.
214 stop_untied =
216 close_untied =
218 remove_untied =
220 Stop, close or remove the torrents that are tied to filenames
221 that have been deleted. Clear the association with the 'U' key.
222 close_low_diskspace = space
224 Close any active torrents on filesystems with less than space
225 diskspace left. Use with the schedule option. A default sched‐
226 uled event with id low_diskspace is set to 500Mb.
227 load = file
229 load_verbose = file
231 load_start = file
233 load_start_verbose = file
235 Load and possibly start a file, or possibly multiple files by
236 using the wild-card "*". This is meant for use with schedule,
237 though ensure that the start is non-zero. The loaded file will
238 be tied to the filename provided.
239 import = file
241 try_import = file
243 Load a resource file. try_import does not throw tor‐
244 rent::input_error exception on bad input.
245 stop_on_ratio = min_ratio
247 stop_on_ratio = min_ratio,min_upload
249 stop_on_ratio = min_ratio,min_upload,max_ratio
251 Stop torrents when they reach the given upload ratio min_ratio
252 in percent. If the optional min_upload is given, require a total
253 upload amount of this many bytes as well. If the optional
254 max_ratio is given, stop the torrent when reaching this ratio
255 regardless of the total upload amount. Exclude certain torrent
256 by pressing Shift+I in the downlist list. Use with the schedule
257 option.
258 on_insert = id,command
260 on_erase = id,command
262 on_open = id,command
264 on_close = id,command
266 on_start = id,command
268 on_stop = id,command
270 on_hash_queued = id,command
272 on_hash_removed = id,command
274 on_hash_done = id,command
276 on_finished = id,command
278 Call a command on a download when its state changes. Only a sub‐
279 set of commands are available.
280
282 upload_rate = KB
283 download_rate = KB
285 Set the maximum global uploand and download rates.
286 min_peers = value
288 max_peers = value
290 Set the minimum and maximum number of peers to allow in each
291 download.
292 min_peers_seed = value
294 max_peers_seed = value
296 Set the minimum nad maximum number of peers to allow while seed‐
297 ing, or -1 (default) to use max_peers.
298 max_uploads = value
300 Set the maximum number of simultaneous uploads per download.
301 max_uploads_div = value
303 max_downloads_div = value
305 Change the divider used to calculate the max upload and download
306 slots to use when the throttle is changed. Disable by setting 0.
307 max_uploads_global = value
309 max_downloads_global = value
311 Max upload and download slots allowed. Disable by setting 0.
312 throttle_up = name, upload_rate
314 throttle_down = name, download_rate
316 Define secondary throttle and/or set the given upload or down‐
317 load rate. Attach to a download with the d.set_throt‐
318 tle_name=name command or switch throttles with Ctrl-T. Download
319 must be stopped when changing throttles. Note that secondary
320 throttles only work if the global upload/download is throttled.
321 Setting a download to use the NULL throttle makes the download
322 unthrottled even when there is a global throttle. Note that this
323 special case bypasses the global throttle entirely, and as such
324 its rate and transfer amounts are not included in the global
325 statistics.
326 throttle_ip = name, host
328 throttle_ip = name, network/prefix
330 throttle_ip = name, start, end
332 Use the given secondary throttle for a host, CIDR network or IP
333 range. All peers with a matching IP will use this throttle
334 instead of the global throttle or a custom download throttle.
335 The name may be NULL to make these peers unthrottled, with the
336 same caveats as explained above.
337
339 Tracker related settings.
340 enable_trackers = yes
342 Set to no to disable all tracker requests. Useful for disabling
343 rtorrent with the schedule command.
344 tracker_dump = filename
346 Dump tracker requests to filename, disable by supplying an empty
347 string. Only torrents loaded while tracker_dump contains a non-
348 empty string will be logged at the moment, although disabling it
349 will work as expected.
350 tracker_numwant = number
352 Set the numwant field sent to the tracker, which indicates how
353 many peers we want. A negative value disables this feature.
354 use_udp_trackers = yes
356 Use UDP trackers. Disable if you are behind a firewall, etc,
357 that does not allow connections to UDP trackers.
358 dht = disabled|off|auto|on
360 Support for querying the distributed hash table (DHT) to find
361 peers for trackerless torrents or when all trackers are down.
362 Set to disable to completely disable DHT, off (default) to
363 enable DHT but to not start the DHT server, auto to automati‐
364 cally start and stop the DHT server as needed or on for perma‐
365 nently keeping the DHT server running. When set to automatic,
366 the DHT server will start up when the first non-private torrent
367 is started, and will stop 15-30 minutes after the last non-pri‐
368 vate torrent is stopped (or when rTorrent quits). For DHT to
369 work, a session directory must be set (for saving the DHT
370 cache).
371 dht_port = number
373 Set the UDP listen port for DHT. Defaults to 6881.
374 dht_add_node = host[:port]
376 Not intended for use in the configuration file but as one-time
377 option in the client or on the command line to bootstrap an
378 empty DHT node table. Contacts the given node and attempts to
379 bootstrap from it if it replies. The port is optional, with
380 port 6881 being used by default.
381 http_capath = path
383 http_cacert = filename
385 Set the certificates to use in http requests. See Curl's CUR‐
386 LOPT_CAPATH and CURLOPT_CAINFO options for further information.
387
389 Display related settings.
390 view_add = name
392 Create a new view.
393 view_sort = name
395 view_sort = name,seconds
397 Sort a view according the the criteria set by view_sort_current.
398 If the optional argument is supplied, the view is not sorted if
399 a change happened during the last seconds. This command is meant
400 to be used with schedule.
401 view_sort_new = name,...
403 view_sort_current = name,...
405 Set the sorting criteria for when new elements inserted or
406 view_sort is called. The list can contain any number of crite‐
407 ria, including zero, from the following:
408 name, name_reverse, stopped, started, complete, incomplete,
410 state_changed, state_changed_reverse
411 key_layout = qwerty|azerty|qwertz|dvorak
413 Change the key-bindings.
414
416 File-system related settings.
417 max_file_size = size
419 Set the maximum size a file can have. Disable by passing -1.
420 split_file_size = size
422 Split files in a torrent larger than size into seperate files.
423 Disable by passing -1.
424 split_suffix = string
426 Set the suffix used on split files. Defaults to .part.
427
429 Settings that require a download as a target, the options need to be
430 called through f.ex on_finished.
431 create_link = type,path,suffix
433 delete_link = type,path,suffix
435 Create or delete a symbolic link. The link path is the concate‐
436 nation of path, the result of the type on the download, and suf‐
437 fix.
438 Available types are; base_path uses the base path of the down‐
440 load, base_filename uses the base filename of the download, tied
441 uses the path of the file the download is tied to, see
442 start_tied.
443
445 This list contains settings users shouldn't need to touch, some may
446 even cause crashes or similar if incorrectly set.
447 hash_read_ahead = MB
449 Configure how far ahead we ask the kernel to read when doing
450 hash checking. The hash checker uses madvise(..., MADV_WILLNEED)
451 for the requests.
452 hash_interval = ms
454 Interval between attempts to check the hash when the chunk is
455 not in memory, in milliseconds.
456 hash_max_tries = tries
458 Number of attempts to check the hash while using the mincore
459 status, before forcing. Overworked systems might need lower val‐
460 ues to get a decent hash checking rate.
461 safe_sync = yes|no
463 Always use MS_SYNC rather than MS_ASYNC when syncing chunks.
464 This may be nessesary in case of filesystem bugs like NFS in
465 linux ~2.6.13.
466 max_open_files = value
468 Number of files to simultaneously keep open. LibTorrent dynami‐
469 cally opens and closes files as necessary when mapping files to
470 memory. Default is based on sysconf(_SC_OPEN_MAX). You probably
471 only think you know what this option does, so don't touch it.
472 max_open_sockets = value
474 Number of network sockets to simultaneously keep open. This
475 value is set to a reasonable value based on
476 sysconf(_SC_OPEN_MAX).
477 max_open_http = value
479 Number of sockets to simultaneously keep open. This value is set
480 to 32 by default.
481 max_memory_usage = bytes
483 Set the max amount of memory space used to mapping file chunks.
484 This may also be set using ulimit -m where 3/4 will be allocated
485 to file chunks.
486 send_buffer_size = value
488 receive_buffer_size = value
490 Adjust the send and receive buffer size for socket.
491 umask = 0022
493 Set the umask for this process, which is applied to all files
494 created by the program.
495 cwd = directory
497 Changes the working directory of the process using chdir.
498 session_on_completion = yes
500 Controls if the session torrent is saved when a torrent fin‐
501 ishes. By default on.
502 session_lock = yes
504 Controls if a lock file is created in the session directory on
505 startup.
506 session_save =
508 Save the session files for all downloads.
509 tos = default|lowdelay|throughput|reliability|mincost
511 tos = hex
513 Change the TOS of peer connections, by default set to through‐
514 put. If the option is set to default then the system default TOS
515 is used. A hex value may be used for non-standard settings.
516 handshake_log = yes
518 Enable logging of the peer handshake. This generates a large
519 number of log messages, but may be useful to debug connection
520 problems.
521
523 Jari "Rakshasa" Sundell <jaris@ifi.uio.no>
524BitTorrent client for ncurses 14 May 2009 RTORRENT(1)