1 .\" This manpage has been automatically generated by docbook2man 

     2 .\" from a DocBook document.  This tool can be found at:

     3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 

     4 .\" Please send any bug reports, improvements, comments, patches, 

     5 .\" etc. to Steve Cheng <[email protected]>.

     6 .TH "RTORRENT" "1" "07 May 2008" "BitTorrent client for ncurses" ""

     7 

     8 .SH NAME

     9 rtorrent \- a BitTorrent client for ncurses

    10 .SH SYNOPSIS

    11 

    12 \fBrtorrent\fR [ \fB-h\fR ] [ \fB-n\fR ] [ \fB-o key1=opt1,...\fR ] [ \fB-O key=opt\fR ] [ \fBURL | FILE\fR\fI ...\fR ]

    13 

    14 .SH "DESCRIPTION"

    15 .PP

    16 \fBrtorrent\fR is a BitTorrent client for ncurses, using

    17 the \fBlibtorrent\fR library. The client and library is

    18 written in C++ with emphasis on speed and efficiency, while delivering

    19 equivalent features to those found in GUI based clients in an ncurses

    20 client.

    21 .PP

    22 Most of the options below have their own default unit in addition to

    23 supporting B, K, M and G suffixes.

    24 .SH "KEYBOARD CONTROL"

    25 .PP

    26 .SS "GLOBAL KEYS"

    27 .TP

    28 \fB^q\fR

    29 Initiate shutdown, press again to force the shutdown and

    30 skip sending the stop signal to trackers.

    31 .TP

    32 \fBup | down | left | right arrow keys\fR

    33 .TP

    34 \fB^P | ^N | ^B | ^F\fR

    35 Select entries or change windows. The right arrow key or ^F is often

    36 used for viewing details about the selected entry, while the left

    37 arrow key or ^B often returns to the previous screen.

    38 .TP

    39 \fBa | s | d\fR

    40 Increase the upload throttle by 1/5/50 KB.

    41 .TP

    42 \fBA | S | D\fR

    43 Increase the download throttle by 1/5/50 KB.

    44 .TP

    45 \fBz | x | c\fR

    46 Decrease the upload throttle by 1/5/50 KB.

    47 .TP

    48 \fBZ | X | C\fR

    49 Decrease the download throttle by 1/5/50 KB.

    50 .SS "MAIN VIEW KEYS"

    51 .TP

    52 \fB->\fR

    53 View download.

    54 .TP

    55 \fB1 - 7\fR

    56 Change view.

    57 .TP

    58 \fB^S\fR

    59 Start download.

    60 .TP

    61 \fB^D\fR

    62 Stop an active download, or remove a stopped download.

    63 .TP

    64 \fB^K\fR

    65 Close a torrent and its files.

    66 .TP

    67 \fB^E\fR

    68 Set the 'create/resize queued' flags on all files in a torrent. This

    69 is necessary if the underlying files in a torrent have been deleted or

    70 truncated, and thus rtorrent must recreate them.

    71 .TP

    72 \fB^R\fR

    73 Initiate hash check of torrent.

    74 .TP

    75 \fB^O\fR

    76 Change the destination directory of the download. The torrent must be

    77 closed.

    78 .TP

    79 \fB^X\fR

    80 Call commands or change settings.

    81 .TP

    82 \fB^B\fR

    83 Set download to perform initial seeding. Only use when

    84 you are the first and only seeder so far for the download.

    85 .TP

    86 \fB+ | -\fR

    87 Change the priority of the download.

    88 .TP

    89 \fBbackspace\fR

    90 Add torrent using an URL or file path. Use

    91 \fBtab\fR to view directory content and do

    92 auto-complete.

    93 .TP

    94 \fBl\fR

    95 View log. Exit by pressing the space-bar.

    96 .TP

    97 \fBU\fR

    98 Delete the file the torrent is tied to, and clear the association.

    99 .TP

   100 \fBI\fR

   101 Toggle whether torrent ignores ratio settings.

   102 .SS "DOWNLOAD VIEW KEYS"

   103 .TP

   104 \fB->\fR

   105 View torrent file list. Use the space-bar to change the file priority

   106 and \fB*\fR to change the priority of all

   107 files. Use \fB/\fR to collapse the directories. OUTDATED

   108 .TP

   109 \fB1 | 2\fR

   110 Adjust max uploads.

   111 .TP

   112 \fB3 | 4\fR

   113 Adjust min peers.

   114 .TP

   115 \fB5 | 6\fR

   116 Adjust max peers.

   117 .TP

   118 \fBu\fR

   119 Display transfering blocks.

   120 .TP

   121 \fBi\fR

   122 Display chunk rarity.

   123 .TP

   124 \fBo\fR

   125 Display the tracker list. Cycle the trackers in a group with the

   126 space-bar.

   127 .TP

   128 \fBp\fR

   129 View peer and torrent information.

   130 .TP

   131 \fBt | T\fR

   132 Initiate tracker request. Use capital T to force the request, ignoring

   133 the "min interval" set by the tracker.

   134 .TP

   135 \fBk\fR

   136 Disconnect peer.

   137 .TP

   138 \fB*\fR

   139 Choke/Snub peer.

   140 .SH "OPTIONS"

   141 .TP

   142 \fB-b \fIa.b.c.d\fB\fR

   143 Bind listening socket and outgoing connections to this network

   144 interface address.

   145 .TP

   146 \fB-d \fIdirectory\fB\fR

   147 Set the default download directory. Defaults to "./".

   148 .TP

   149 \fB-h\fR

   150 Display help and exit.

   151 .TP

   152 \fB-i \fIa.b.c.d\fB\fR

   153 Set the address reported to the tracker.

   154 .TP

   155 \fB-n\fR

   156 Don't load ~/.rtorrent.rc on startup.

   157 .TP

   158 \fB-o key1=opt1,...\fR

   159 .TP

   160 \fB-O key=opt\fR

   161 Set any number of options, see the SETTINGS section. The options given

   162 here override the resource files. Use capital \fB-O\fR

   163 to allow comma in the option.

   164 .TP

   165 \fB-p \fIa-b\fB\fR

   166 Try to open a listening port in the range \fBa\fR up to

   167 and including \fBb\fR\&.

   168 .TP

   169 \fB-s \fIdirectory\fB\fR

   170 Session management will be enabled and the torrent files for all open

   171 downloads will be stored in this directory. Only one instance of

   172 rtorrent should be used with each session directory, though at the

   173 moment no locking is done. An empty string will disable the session

   174 directory.

   175 .SH "GENERAL SETTINGS"

   176 .PP

   177 .TP

   178 \fBbind = \fIa.b.c.d\fB\fR

   179 Bind listening socket and outgoing connections to this network

   180 interface address.

   181 .TP

   182 \fBip = \fIa.b.c.d\fB\fR

   183 .TP

   184 \fBip = \fIhostname\fB\fR

   185 Set the address reported to the tracker.

   186 .TP

   187 \fBport_range = \fIa-b\fB\fR

   188 Try to open a listening port in the range \fBa\fR up to

   189 and including \fBb\fR\&.

   190 .TP

   191 \fBport_random = \fIyes | no\fB\fR

   192 Open the listening port at a random position in the port range.

   193 .TP

   194 \fBcheck_hash = \fIyes | no\fB\fR

   195 Perform hash check on torrents that have finished downloading.

   196 .TP

   197 \fBdirectory = \fIdirectory\fB\fR

   198 Set the default download directory. Defaults to "./".

   199 .TP

   200 \fBsession = \fIdirectory\fB\fR

   201 Session management will be enabled and the torrent files for all open

   202 downloads will be stored in this directory. Only one instance of

   203 rtorrent can be used per session directory. An empty string will

   204 disable the session directory.

   205 .TP

   206 \fBhttp_proxy = \fIurl\fB\fR

   207 Use a http proxy. Use an empty string to disable.

   208 .TP

   209 \fBencoding_list = \fIencoding\fB\fR

   210 Add a preferred filename encoding to the list. The encodings are

   211 attempted in the order they are inserted, if none match the torrent

   212 default is used.

   213 .TP

   214 \fBencryption = \fIoption\fB,\fI\&...\fB\fR

   215 Set how rtorrent should deal with encrypted Bittorrent connections. By

   216 default, encryption is disabled, equivalent to specifying the option

   217 \fBnone\fR\&. Alternatively, any number of the following

   218 options may be specified:

   219 

   220 \fBallow_incoming\fR (allow incoming encrypted connections), 

   221 \fBtry_outgoing\fR (use encryption for outgoing connections),

   222 \fBrequire\fR (disable unencrypted handshakes), 

   223 \fBrequire_RC4\fR (also disable plaintext transmission after the

   224 initial encrypted handshake),

   225 \fBenable_retry\fR (if the initial outgoing connection fails, retry

   226 with encryption turned on if it was off or off if it was on), 

   227 \fBprefer_plaintext\fR (choose plaintext when peer offers a choice 

   228 between plaintext transmission and RC4 encryption, otherwise RC4 will be used).

   229 .TP

   230 \fBpeer_exchange = \fIyes | no\fB\fR

   231 Enable/disable peer exchange for torrents that aren't marked private. Disabled by default.

   232 .TP

   233 \fBschedule = \fIid\fB,\fIstart\fB,\fIinterval\fB,\fIcommand\fB\fR

   234 Call \fBcommand\fR every \fBinterval\fR

   235 seconds, starting from \fBstart\fR\&. An

   236 \fBinterval\fR of zero calls the task once, while a

   237 \fBstart\fR of zero calls it immediately. Currently

   238 \fBcommand\fR is forwarded to the option handler.

   239 \fBstart\fR and \fBinterval\fR may

   240 optionally use a time format, \fBdd:hh:mm:ss\fR\&. F.ex to

   241 start a task every day at \fB18:00\fR, use

   242 \fB18:00:00,24:00:00\fR\&.

   243 .TP

   244 \fBschedule_remove = \fIid\fB\fR

   245 Delete \fBid\fR from the scheduler.

   246 .TP

   247 \fBstart_tied =\fR

   248 Start torrents that are tied to filenames that have been re-added.

   249 .TP

   250 \fBstop_untied =\fR

   251 .TP

   252 \fBclose_untied =\fR

   253 .TP

   254 \fBremove_untied =\fR

   255 Stop, close or remove the torrents that are tied to filenames that

   256 have been deleted. Clear the association with the 'U' key.

   257 .TP

   258 \fBclose_low_diskspace = \fIspace\fB\fR

   259 Close any active torrents on filesystems with less than

   260 \fBspace\fR diskspace left. Use with

   261 the \fBschedule\fR option. A default scheduled event

   262 with id \fBlow_diskspace\fR is set to 500Mb.

   263 .TP

   264 \fBload = \fIfile\fB\fR

   265 .TP

   266 \fBload_verbose = \fIfile\fB\fR

   267 .TP

   268 \fBload_start = \fIfile\fB\fR

   269 .TP

   270 \fBload_start_verbose = \fIfile\fB\fR

   271 Load and possibly start a file, or possibly multiple files by using the

   272 wild-card "*". This is meant for use with

   273 \fBschedule\fR, though ensure that the

   274 \fBstart\fR is non-zero. The loaded file will be tied

   275 to the filename provided.

   276 .TP

   277 \fBimport = \fIfile\fB\fR

   278 .TP

   279 \fBtry_import = \fIfile\fB\fR

   280 Load a resource file. \fBtry_import\fR does not throw

   281 torrent::input_error exception on bad input.

   282 .TP

   283 \fBstop_on_ratio = \fImin_ratio\fB\fR

   284 .TP

   285 \fBstop_on_ratio = \fImin_ratio\fB,\fImin_upload\fB\fR

   286 .TP

   287 \fBstop_on_ratio = \fImin_ratio\fB,\fImin_upload\fB,\fImax_ratio\fB\fR

   288 Stop torrents when they reach the given upload ratio

   289 \fBmin_ratio\fR in percent. If the optional

   290 \fBmin_upload\fR is given, require a total

   291 upload amount of this many bytes as well. If the optional

   292 \fBmax_ratio\fR is given, stop the torrent

   293 when reaching this ratio regardless of the total upload

   294 amount. Exclude certain torrent by pressing 

   295 \fBShift+I\fR in the downlist list.

   296 Use with the \fBschedule\fR option.

   297 .TP

   298 \fBon_insert = \fIid\fB,\fIcommand\fB\fR

   299 .TP

   300 \fBon_erase = \fIid\fB,\fIcommand\fB\fR

   301 .TP

   302 \fBon_open = \fIid\fB,\fIcommand\fB\fR

   303 .TP

   304 \fBon_close = \fIid\fB,\fIcommand\fB\fR

   305 .TP

   306 \fBon_start = \fIid\fB,\fIcommand\fB\fR

   307 .TP

   308 \fBon_stop = \fIid\fB,\fIcommand\fB\fR

   309 .TP

   310 \fBon_hash_queued = \fIid\fB,\fIcommand\fB\fR

   311 .TP

   312 \fBon_hash_removed = \fIid\fB,\fIcommand\fB\fR

   313 .TP

   314 \fBon_hash_done = \fIid\fB,\fIcommand\fB\fR

   315 .TP

   316 \fBon_finished = \fIid\fB,\fIcommand\fB\fR

   317 Call a command on a download when its state changes. Only a subset of

   318 commands are available.

   319 .SH "THROTTLE SETTINGS"

   320 .TP

   321 \fBupload_rate = \fIKB\fB\fR

   322 .TP

   323 \fBdownload_rate = \fIKB\fB\fR

   324 Set the maximum global uploand and download rates.

   325 .TP

   326 \fBmin_peers = \fIvalue\fB\fR

   327 .TP

   328 \fBmax_peers = \fIvalue\fB\fR

   329 Set the minimum and maximum number of peers to allow in each download.

   330 .TP

   331 \fBmin_peers_seed = \fIvalue\fB\fR

   332 .TP

   333 \fBmax_peers_seed = \fIvalue\fB\fR

   334 Set the minimum nad maximum number of peers to allow while seeding, or

   335 -1 (default) to use max_peers.

   336 .TP

   337 \fBmax_uploads = \fIvalue\fB\fR

   338 Set the maximum number of simultaneous uploads per download.

   339 .TP

   340 \fBmax_uploads_div = \fIvalue\fB\fR

   341 .TP

   342 \fBmax_downloads_div = \fIvalue\fB\fR

   343 Change the divider used to calculate the max upload and download slots

   344 to use when the throttle is changed. Disable by

   345 setting \fB0\fR\&.

   346 .TP

   347 \fBmax_uploads_global = \fIvalue\fB\fR

   348 .TP

   349 \fBmax_downloads_global = \fIvalue\fB\fR

   350 Max upload and download slots allowed. Disable by

   351 setting \fB0\fR\&.

   352 .SH "TRACKER RELATED SETTINGS"

   353 .PP

   354 Tracker related settings.

   355 .TP

   356 \fBenable_trackers = \fIyes\fB\fR

   357 Set to \fBno\fR to disable all tracker requests. Useful

   358 for disabling rtorrent with the \fBschedule\fR command.

   359 .TP

   360 \fBtracker_dump = \fIfilename\fB\fR

   361 Dump tracker requests to \fBfilename\fR, disable by

   362 supplying an empty string. Only torrents loaded while

   363 \fBtracker_dump\fR contains a non-empty string will be

   364 logged at the moment, although disabling it will work as expected.

   365 .TP

   366 \fBtracker_numwant = \fInumber\fB\fR

   367 Set the numwant field sent to the tracker, which indicates how many

   368 peers we want. A negative value disables this feature.

   369 .TP

   370 \fBuse_udp_trackers = \fIyes\fB\fR

   371 Use UDP trackers. Disable if you are behind a firewall, etc, that does

   372 not allow connections to UDP trackers.

   373 .TP

   374 \fBdht = \fIdisabled|off|auto|on\fB\fR

   375 Support for querying the distributed hash table (DHT) to find peers for trackerless

   376 torrents or when all trackers are down. Set to \fBdisable\fR to completely

   377 disable DHT, \fBoff\fR (default) to enable DHT but to not start the

   378 DHT server, \fBauto\fR to automatically start and stop the DHT server

   379 as needed or \fBon\fR for permanently keeping the DHT server running.

   380 When set to automatic, the DHT server will start up when the first non-private torrent

   381 is started, and will stop 15-30 minutes after the last non-private torrent is

   382 stopped (or when rTorrent quits). For DHT to work, a session directory must be set (for

   383 saving the DHT cache).

   384 .TP

   385 \fBdht_port = \fInumber\fB\fR

   386 Set the UDP listen port for DHT. Defaults to 6881.

   387 .TP

   388 \fBdht_add_node = \fIhost[:port]\fB\fR

   389 Not intended for use in the configuration file but as one-time option in the

   390 client or on the command line to bootstrap an empty DHT node table. Contacts 

   391 the given node and attempts to bootstrap from it if it replies.

   392 The port is optional, with port 6881 being used by default.

   393 .TP

   394 \fBhttp_capath = \fIpath\fB\fR

   395 .TP

   396 \fBhttp_cacert = \fIfilename\fB\fR

   397 Set the certificates to use in http requests. See Curl's

   398 CURLOPT_CAPATH and CURLOPT_CAINFO options for further information.

   399 .SH "USER-INTERFACE SETTINGS"

   400 .PP

   401 Display related settings.

   402 .TP

   403 \fBview_add = \fIname\fB\fR

   404 Create a new view.

   405 .TP

   406 \fBview_sort = \fIname\fB\fR

   407 .TP

   408 \fBview_sort = \fIname\fB,\fIseconds\fB\fR

   409 Sort a view according the the criteria set by

   410 \fBview_sort_current\fR\&. If the optional argument is

   411 supplied, the view is not sorted if a change happened during the last

   412 \fBseconds\fR\&. This command is meant to be used with

   413 \fBschedule\fR\&.

   414 .TP

   415 \fBview_sort_new = \fIname\fB,\fI\&...\fB\fR

   416 .TP

   417 \fBview_sort_current = \fIname\fB,\fI\&...\fB\fR

   418 Set the sorting criteria for when new elements inserted or

   419 \fBview_sort\fR is called. The list can contain any

   420 number of criteria, including zero, from the following:

   421 

   422 \fBname\fR, \fBname_reverse\fR,

   423 \fBstopped\fR, \fBstarted\fR,

   424 \fBcomplete\fR, \fBincomplete\fR,

   425 \fBstate_changed\fR,

   426 \fBstate_changed_reverse\fR

   427 .TP

   428 \fBkey_layout = \fIqwerty|azerty|qwertz|dvorak\fB\fR

   429 Change the key-bindings.

   430 .SH "FILE-SYSTEM SETTINGS"

   431 .PP

   432 File-system related settings.

   433 .TP

   434 \fBmax_file_size = \fIsize\fB\fR

   435 Set the maximum size a file can have. Disable by

   436 passing \fB-1\fR\&.

   437 .TP

   438 \fBsplit_file_size = \fIsize\fB\fR

   439 Split files in a torrent larger than \fBsize\fR into

   440 seperate files. Disable by passing \fB-1\fR\&.

   441 .TP

   442 \fBsplit_suffix = \fIstring\fB\fR

   443 Set the suffix used on split files. Defaults

   444 to \fB\&.part\fR\&.

   445 .SH "DOWNLOAD SETTINGS"

   446 .PP

   447 Settings that require a download as a target, the options need to be

   448 called through f.ex \fBon_finished\fR\&.

   449 .TP

   450 \fBcreate_link = \fItype\fB,\fIpath\fB,\fIsuffix\fB\fR

   451 .TP

   452 \fBdelete_link = \fItype\fB,\fIpath\fB,\fIsuffix\fB\fR

   453 Create or delete a symbolic link. The link path is the concatenation

   454 of \fBpath\fR, the result of

   455 the \fBtype\fR on the download,

   456 and \fBsuffix\fR\&.

   457 

   458 Available types are; \fBbase_path\fR uses the base path

   459 of the download, \fBbase_filename\fR uses the base

   460 filename of the download, \fBtied\fR uses the path of

   461 the file the download is tied to, see \fBstart_tied\fR\&.

   462 .SH "ADVANCED SETTINGS"

   463 .PP

   464 This list contains settings users shouldn't need to touch, some may

   465 even cause crashes or similar if incorrectly set.

   466 .TP

   467 \fBhash_read_ahead = \fIMB\fB\fR

   468 Configure how far ahead we ask the kernel to read when doing hash

   469 checking. The hash checker uses madvise(..., MADV_WILLNEED) for the

   470 requests.

   471 .TP

   472 \fBhash_interval = \fIms\fB\fR

   473 Interval between attempts to check the hash when the chunk is not in

   474 memory, in milliseconds.

   475 .TP

   476 \fBhash_max_tries = \fItries\fB\fR

   477 Number of attempts to check the hash while using the mincore status,

   478 before forcing. Overworked systems might need lower values to get a

   479 decent hash checking rate.

   480 .TP

   481 \fBsafe_sync = \fIyes|no\fB\fR

   482 Always use MS_SYNC rather than MS_ASYNC when syncing chunks. This may

   483 be nessesary in case of filesystem bugs like NFS in linux ~2.6.13.

   484 .TP

   485 \fBmax_open_files = \fIvalue\fB\fR

   486 Number of files to simultaneously keep open. LibTorrent dynamically

   487 opens and closes files as necessary when mapping files to

   488 memory. Default is based on sysconf(_SC_OPEN_MAX).

   489 You probably only think you know what this option does, so don't touch

   490 it.

   491 .TP

   492 \fBmax_open_sockets = \fIvalue\fB\fR

   493 Number of network sockets to simultaneously keep open. This value is

   494 set to a reasonable value based on \fBsysconf(_SC_OPEN_MAX)\fR\&.

   495 .TP

   496 \fBmax_open_http = \fIvalue\fB\fR

   497 Number of sockets to simultaneously keep open. This value is set

   498 to \fB32\fR by default.

   499 .TP

   500 \fBmax_memory_usage = \fIbytes\fB\fR

   501 Set the max amount of memory space used to mapping file chunks. This

   502 may also be set using \fBulimit -m\fR where 3/4 will be

   503 allocated to file chunks.

   504 .TP

   505 \fBsend_buffer_size = \fIvalue\fB\fR

   506 .TP

   507 \fBreceive_buffer_size = \fIvalue\fB\fR

   508 Adjust the send and receive buffer size for socket.

   509 .TP

   510 \fBumask = \fI0022\fB\fR

   511 Set the umask for this process, which is applied to all files created

   512 by the program.

   513 .TP

   514 \fBcwd = \fIdirectory\fB\fR

   515 Changes the working directory of the process using

   516 \fBchdir\fR\&.

   517 .TP

   518 \fBsession_on_completion = \fIyes\fB\fR

   519 Controls if the session torrent is saved when a torrent finishes. By

   520 default on.

   521 .TP

   522 \fBsession_lock = \fIyes\fB\fR

   523 Controls if a lock file is created in the session directory on startup.

   524 .TP

   525 \fBsession_save = \fR

   526 Save the session files for all downloads.

   527 .TP

   528 \fBtos = \fIdefault|lowdelay|throughput|reliability|mincost\fB\fR

   529 .TP

   530 \fBtos = \fIhex\fB\fR

   531 Change the TOS of peer connections, by default set to

   532 \fBthroughput\fR\&. If the option is set to

   533 \fBdefault\fR then the system default TOS is used. A

   534 hex value may be used for non-standard settings.

   535 .TP

   536 \fBhandshake_log = \fIyes\fB\fR

   537 Enable logging of the peer handshake. This generates a large number of

   538 log messages, but may be useful to debug connection problems.

   539 .SH "AUTHORS"

   540 .PP

   541 

   542 Jari "Rakshasa" Sundell <[email protected]>