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 li‐
15 brary. The client and library is written in C++ with emphasis on speed
16 and efficiency, while delivering equivalent features to those found in
17 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 0 - 9 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 F Add a temporary name based regex filter to the current view.
85 DOWNLOAD VIEW KEYS
87 -> View torrent file list. Use the space-bar to change the file
88 priority and * to change the priority of all files. Use / to
89 collapse the directories. OUTDATED
90 1 | 2 Adjust max uploads.
92 3 | 4 Adjust min peers.
94 5 | 6 Adjust max peers.
96 u Display transfering blocks.
98 i Display chunk rarity.
100 o Display the tracker list. Cycle the trackers in a group with the
102 space-bar.
103 p View peer and torrent information.
105 t | T Initiate tracker request. Use capital T to force the request,
107 ignoring the "min interval" set by the tracker.
108 k Disconnect peer.
110 * Choke/Snub peer.
112
114 -b a.b.c.d
115 Bind listening socket and outgoing connections to this network
116 interface address.
117 -d directory
119 Set the default download directory. Defaults to "./".
120 -h Display help and exit.
122 -i a.b.c.d
124 Set the address reported to the tracker.
125 -n Don't load ~/.rtorrent.rc on startup.
127 -o key1=opt1,...
129 -O key=opt
131 Set any number of options, see the SETTINGS section. The options
132 given here override the resource files. Use capital -O to allow
133 comma in the option.
134 -p a-b Try to open a listening port in the range a up to and including
136 b.
137 -s directory
139 Session management will be enabled and the torrent files for all
140 open downloads will be stored in this directory. Only one in‐
141 stance of rtorrent should be used with each session directory,
142 though at the moment no locking is done. An empty string will
143 disable the session directory.
144
146 bind = a.b.c.d
147 Bind listening socket and outgoing connections to this network
148 interface address.
149 ip = a.b.c.d
151 ip = hostname
153 Set the address reported to the tracker.
154 port_range = a-b
156 Try to open a listening port in the range a up to and including
157 b.
158 port_random = yes | no
160 Open the listening port at a random position in the port range.
161 check_hash = yes | no
163 Perform hash check on torrents that have finished downloading.
164 directory = directory
166 Set the default download directory. Defaults to "./".
167 session = directory
169 Session management will be enabled and the torrent files for all
170 open downloads will be stored in this directory. Only one in‐
171 stance of rtorrent can be used per session directory. An empty
172 string will disable the session directory.
173 http_proxy = url
175 Use a http proxy. Use an empty string to disable.
176 encoding_list = encoding
178 Add a preferred filename encoding to the list. The encodings are
179 attempted in the order they are inserted, if none match the tor‐
180 rent default is used.
181 encryption = option,...
183 Set how rtorrent should deal with encrypted Bittorrent connec‐
184 tions. By default, encryption is disabled, equivalent to speci‐
185 fying the option none. Alternatively, any number of the follow‐
186 ing options may be specified:
187 allow_incoming (allow incoming encrypted connections), try_out‐
189 going (use encryption for outgoing connections), require (dis‐
190 able unencrypted handshakes), require_RC4 (also disable plain‐
191 text transmission after the initial encrypted handshake), en‐
192 able_retry (if the initial outgoing connection fails, retry with
193 encryption turned on if it was off or off if it was on), pre‐
194 fer_plaintext (choose plaintext when peer offers a choice be‐
195 tween plaintext transmission and RC4 encryption, otherwise RC4
196 will be used).
197 peer_exchange = yes | no
199 Enable/disable peer exchange for torrents that aren't marked
200 private. Disabled by default.
201 schedule = id,start,interval,command
203 Call command every interval seconds, starting from start. An in‐
204 terval of zero calls the task once, while a start of zero calls
205 it immediately. Currently command is forwarded to the option
206 handler. start and interval may optionally use a time format,
207 dd:hh:mm:ss. F.ex to start a task every day at 18:00, use
208 18:00:00,24:00:00.
209 schedule_remove = id
211 Delete id from the scheduler.
212 start_tied =
214 Start torrents that are tied to filenames that have been re-
215 added.
216 stop_untied =
218 close_untied =
220 remove_untied =
222 Stop, close or remove the torrents that are tied to filenames
223 that have been deleted. Clear the association with the 'U' key.
224 close_low_diskspace = space
226 Close any active torrents on filesystems with less than space
227 diskspace left. Use with the schedule option. A default sched‐
228 uled event with id low_diskspace is set to 500Mb.
229 load = file
231 load_verbose = file
233 load_start = file
235 load_start_verbose = file
237 Load and possibly start a file, or possibly multiple files by
238 using the wild-card "*". This is meant for use with schedule,
239 though ensure that the start is non-zero. The loaded file will
240 be tied to the filename provided.
241 import = file
243 try_import = file
245 Load a resource file. try_import does not throw torrent::in‐
246 put_error exception on bad input.
247 stop_on_ratio = min_ratio
249 stop_on_ratio = min_ratio,min_upload
251 stop_on_ratio = min_ratio,min_upload,max_ratio
253 Stop torrents when they reach the given upload ratio min_ratio
254 in percent. If the optional min_upload is given, require a total
255 upload amount of this many bytes as well. If the optional
256 max_ratio is given, stop the torrent when reaching this ratio
257 regardless of the total upload amount. Exclude certain torrent
258 by pressing Shift+I in the downlist list. Use with the schedule
259 option.
260 on_insert = id,command
262 on_erase = id,command
264 on_open = id,command
266 on_close = id,command
268 on_start = id,command
270 on_stop = id,command
272 on_hash_queued = id,command
274 on_hash_removed = id,command
276 on_hash_done = id,command
278 on_finished = id,command
280 Call a command on a download when its state changes. Only a sub‐
281 set of commands are available.
282
284 upload_rate = KB
285 download_rate = KB
287 Set the maximum global uploand and download rates.
288 min_peers = value
290 max_peers = value
292 Set the minimum and maximum number of peers to allow in each
293 download.
294 min_peers_seed = value
296 max_peers_seed = value
298 Set the minimum nad maximum number of peers to allow while seed‐
299 ing, or -1 (default) to use max_peers.
300 max_uploads = value
302 Set the maximum number of simultaneous uploads per download.
303 max_uploads_div = value
305 max_downloads_div = value
307 Change the divider used to calculate the max upload and download
308 slots to use when the throttle is changed. Disable by setting 0.
309 max_uploads_global = value
311 max_downloads_global = value
313 Max upload and download slots allowed. Disable by setting 0.
314 throttle_up = name, upload_rate
316 throttle_down = name, download_rate
318 Define secondary throttle and/or set the given upload or down‐
319 load rate. Attach to a download with the d.set_throt‐
320 tle_name=name command or switch throttles with Ctrl-T. Download
321 must be stopped when changing throttles. Note that secondary
322 throttles only work if the global upload/download is throttled.
323 Setting a download to use the NULL throttle makes the download
324 unthrottled even when there is a global throttle. Note that this
325 special case bypasses the global throttle entirely, and as such
326 its rate and transfer amounts are not included in the global
327 statistics.
328 throttle_ip = name, host
330 throttle_ip = name, network/prefix
332 throttle_ip = name, start, end
334 Use the given secondary throttle for a host, CIDR network or IP
335 range. All peers with a matching IP will use this throttle in‐
336 stead of the global throttle or a custom download throttle. The
337 name may be NULL to make these peers unthrottled, with the same
338 caveats as explained above.
339
341 Tracker related settings.
342 enable_trackers = yes
344 Set to no to disable all tracker requests. Useful for disabling
345 rtorrent with the schedule command.
346 tracker_dump = filename
348 Dump tracker requests to filename, disable by supplying an empty
349 string. Only torrents loaded while tracker_dump contains a non-
350 empty string will be logged at the moment, although disabling it
351 will work as expected.
352 tracker_numwant = number
354 Set the numwant field sent to the tracker, which indicates how
355 many peers we want. A negative value disables this feature.
356 use_udp_trackers = yes
358 Use UDP trackers. Disable if you are behind a firewall, etc,
359 that does not allow connections to UDP trackers.
360 dht = disabled|off|auto|on
362 Support for querying the distributed hash table (DHT) to find
363 peers for trackerless torrents or when all trackers are down.
364 Set to disable to completely disable DHT, off (default) to en‐
365 able DHT but to not start the DHT server, auto to automatically
366 start and stop the DHT server as needed or on for permanently
367 keeping the DHT server running. When set to automatic, the DHT
368 server will start up when the first non-private torrent is
369 started, and will stop 15-30 minutes after the last non-private
370 torrent is stopped (or when rTorrent quits). For DHT to work, a
371 session directory must be set (for saving the DHT cache).
372 dht_port = number
374 Set the UDP listen port for DHT. Defaults to 6881.
375 dht_add_node = host[:port]
377 Not intended for use in the configuration file but as one-time
378 option in the client or on the command line to bootstrap an
379 empty DHT node table. Contacts the given node and attempts to
380 bootstrap from it if it replies. The port is optional, with
381 port 6881 being used by default.
382 http_capath = path
384 http_cacert = filename
386 Set the certificates to use in http requests. See Curl's CUR‐
387 LOPT_CAPATH and CURLOPT_CAINFO options for further information.
388
390 Display related settings.
391 view_add = name
393 Create a new view.
394 view_sort = name
396 view_sort = name,seconds
398 Sort a view according the the criteria set by view_sort_current.
399 If the optional argument is supplied, the view is not sorted if
400 a change happened during the last seconds. This command is meant
401 to be used with schedule.
402 view_sort_new = name,...
404 view_sort_current = name,...
406 Set the sorting criteria for when new elements inserted or
407 view_sort is called. The list can contain any number of crite‐
408 ria, including zero, from the following:
409 name, name_reverse, stopped, started, complete, incomplete,
411 state_changed, state_changed_reverse
412 key_layout = qwerty|azerty|qwertz|dvorak
414 Change the key-bindings.
415
417 File-system related settings.
418 max_file_size = size
420 Set the maximum size a file can have. Disable by passing -1.
421 split_file_size = size
423 Split files in a torrent larger than size into seperate files.
424 Disable by passing -1.
425 split_suffix = string
427 Set the suffix used on split files. Defaults to .part.
428
430 Settings that require a download as a target, the options need to be
431 called through f.ex on_finished.
432 create_link = type,path,suffix
434 delete_link = type,path,suffix
436 Create or delete a symbolic link. The link path is the concate‐
437 nation of path, the result of the type on the download, and suf‐
438 fix.
439 Available types are; base_path uses the base path of the down‐
441 load, base_filename uses the base filename of the download, tied
442 uses the path of the file the download is tied to, see
443 start_tied.
444
446 This list contains settings users shouldn't need to touch, some may
447 even cause crashes or similar if incorrectly set.
448 hash_read_ahead = MB
450 Configure how far ahead we ask the kernel to read when doing
451 hash checking. The hash checker uses madvise(..., MADV_WILLNEED)
452 for the requests.
453 hash_interval = ms
455 Interval between attempts to check the hash when the chunk is
456 not in memory, in milliseconds.
457 hash_max_tries = tries
459 Number of attempts to check the hash while using the mincore
460 status, before forcing. Overworked systems might need lower val‐
461 ues to get a decent hash checking rate.
462 safe_sync = yes|no
464 Always use MS_SYNC rather than MS_ASYNC when syncing chunks.
465 This may be nessesary in case of filesystem bugs like NFS in
466 linux ~2.6.13.
467 max_open_files = value
469 Number of files to simultaneously keep open. LibTorrent dynami‐
470 cally opens and closes files as necessary when mapping files to
471 memory. Default is based on sysconf(_SC_OPEN_MAX). You probably
472 only think you know what this option does, so don't touch it.
473 max_open_sockets = value
475 Number of network sockets to simultaneously keep open. This
476 value is set to a reasonable value based on
477 sysconf(_SC_OPEN_MAX).
478 max_open_http = value
480 Number of sockets to simultaneously keep open. This value is set
481 to 32 by default.
482 max_memory_usage = bytes
484 Set the max amount of memory space used to mapping file chunks.
485 This may also be set using ulimit -m where 3/4 will be allocated
486 to file chunks.
487 send_buffer_size = value
489 receive_buffer_size = value
491 Adjust the send and receive buffer size for socket.
492 umask = 0022
494 Set the umask for this process, which is applied to all files
495 created by the program.
496 cwd = directory
498 Changes the working directory of the process using chdir.
499 session_on_completion = yes
501 Controls if the session torrent is saved when a torrent fin‐
502 ishes. By default on.
503 session_lock = yes
505 Controls if a lock file is created in the session directory on
506 startup.
507 session_save =
509 Save the session files for all downloads.
510 tos = default|lowdelay|throughput|reliability|mincost
512 tos = hex
514 Change the TOS of peer connections, by default set to through‐
515 put. If the option is set to default then the system default TOS
516 is used. A hex value may be used for non-standard settings.
517 handshake_log = yes
519 Enable logging of the peer handshake. This generates a large
520 number of log messages, but may be useful to debug connection
521 problems.
522
524 Jari "Rakshasa" Sundell <jaris@ifi.uio.no>
525BitTorrent client for ncurses 14 May 2009 RTORRENT(1)