rtorrent/doc/rtorrent.1

.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "RTORRENT" "1" "05 July 2006" "BitTorrent client for ncurses" ""

.SH NAME
rtorrent \- a BitTorrent client for ncurses
.SH SYNOPSIS

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

.SH "DESCRIPTION"
.PP
\fBrtorrent\fR is a BitTorrent client for ncurses,
using the \fBlibtorrent\fR library. The client
and library is written in C++ with emphasis on speed and
efficiency, while delivering equivalent features to those found
in GUI based clients in an ncurses client.
.SH "KEYBOARD CONTROL"
.PP
.SS "GLOBAL KEYS"
.TP
\fB^q\fR
Initiate shutdown, press again to force the shutdown and
skip sending the stop signal to trackers.
.TP
\fBup | down\fR
Select item.
.TP
\fB<-\fR
Go back to the previous screen.
.TP
\fBa | s | d\fR
Increase the upload throttle by 1/5/50 KB.
.TP
\fBA | S | D\fR
Increase the download throttle by 1/5/50 KB.
.TP
\fBz | x | c\fR
Decrease the upload throttle by 1/5/50 KB.
.TP
\fBZ | X | C\fR
Decrease the download throttle by 1/5/50 KB.
.SS "MAIN VIEW KEYS"
.TP
\fB->\fR
View download.
.TP
\fB1 - 7\fR
Change view.
.TP
\fB^S\fR
Start download.
.TP
\fB^D\fR
Stop an active download, or remove a stopped download.
.TP
\fB^K\fR
Close a torrent and its files.
.TP
\fB^R\fR
Initiate hash check of torrent.
.TP
\fB^O\fR
Change the destination directory of the download. The
torrent must be closed.
.TP
\fB+ | -\fR
Change the priority of the download.
.TP
\fBbackspace\fR
Add torrent using an URL or file path. Use
\fBtab\fR to view directory content and do
auto-complete.
.TP
\fBl\fR
View log. Exit by pressing the space-bar.
.TP
\fB^P\fR
Call commands or change settings.
.TP
\fBU\fR
Delete the file the torrent is tied to, and clear the association.
.TP
\fBI\fR
Toggle whether torrent ignores ratio settings.
.SS "DOWNLOAD VIEW KEYS"
.TP
\fB->\fR
View torrent file list. Use the space-bar to change the
file priority and \fB*\fR to change the
priority of all files.
.TP
\fB1 | 2\fR
Adjust max uploads.
.TP
\fB3 | 4\fR
Adjust min peers.
.TP
\fB5 | 6\fR
Adjust max peers.
.TP
\fBu\fR
Display transfering blocks.
.TP
\fBi\fR
Display chunk rarity.
.TP
\fBo\fR
Display the tracker list. Cycle the trackers in a group
with the space-bar.
.TP
\fBp\fR
View peer and torrent information.
.TP
\fBt | T\fR
Initiate tracker request. Use capital T to force the request, ignoring
the "min interval" set by the tracker.
.TP
\fBk\fR
Disconnect peer.
.TP
\fB*\fR
Choke/Snub peer.
.SH "OPTIONS"
.TP
\fB-b \fIa.b.c.d\fB\fR
Bind listening socket and outgoing connections to this network
interface address.
.TP
\fB-d \fIdirectory\fB\fR
Set the default download directory. Defaults to "./".
.TP
\fB-h\fR
Display help and exit.
.TP
\fB-i \fIa.b.c.d\fB\fR
Set the address reported to the tracker.
.TP
\fB-n\fR
Don't load ~/.rtorrent.rc on startup.
.TP
\fB-o key1=opt1,...\fR
.TP
\fB-O key=opt\fR
Set any number of options, see the SETTINGS section. The options given
here override the resource files. Use capital \fB-O\fR
to allow comma in the option.
.TP
\fB-p \fIa-b\fB\fR
Try to open a listening port in the range \fBa\fR up to
and including \fBb\fR\&.
.TP
\fB-s \fIdirectory\fB\fR
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.
.SH "GENERAL SETTINGS"
.PP
.TP
\fBmax_peers = \fIvalue\fB\fR
Set the maximum number of peers to allow in each download.
.TP
\fBmin_peers = \fIvalue\fB\fR
Set the minimum number of peers to try to connect to in each download.
.TP
\fBmax_uploads = \fIvalue\fB\fR
Set the maximum number of simultaneous uploads per download.
.TP
\fBdownload_rate = \fIKB\fB\fR
Set the maximum global download rate.
.TP
\fBupload_rate = \fIKB\fB\fR
Set the maximum global upload rate.
.TP
\fBbind = \fIa.b.c.d\fB\fR
Bind listening socket and outgoing connections to this network
interface address.
.TP
\fBip = \fIa.b.c.d\fB\fR
.TP
\fBip = \fIhostname\fB\fR
Set the address reported to the tracker.
.TP
\fBport_range = \fIa-b\fB\fR
Try to open a listening port in the range \fBa\fR up to
and including \fBb\fR\&.
.TP
\fBport_random = \fIyes | no\fB\fR
Open the listening port at a random position in the port range.
.TP
\fBcheck_hash = \fIyes | no\fB\fR
Perform hash check on torrents that have finished downloading.
.TP
\fBdirectory = \fIdirectory\fB\fR
Set the default download directory. Defaults to "./".
.TP
\fBsession = \fIdirectory\fB\fR
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.
.TP
\fBhttp_proxy = \fIurl\fB\fR
Use a http proxy. Use an empty string to disable.
.TP
\fBencoding_list = \fIencoding\fB\fR
Add a preferred filename encoding to the list. The encodings are
attempted in the order they are inserted, if none match the torrent
default is used.
.TP
\fBschedule = \fIid\fB,\fIstart\fB,\fIinterval\fB,\fIcommand\fB\fR
Call \fBcommand\fR every \fBinterval\fR
seconds, starting from \fBstart\fR\&. An
\fBinterval\fR of zero calls the task once, while a
\fBstart\fR of zero calls it immediately. Currently
\fBcommand\fR is forwarded to the option handler.
\fBstart\fR and \fBinterval\fR may
optionally use a time format, \fBdd:hh:mm:ss\fR\&. F.ex to
start a task every day at \fB18:00\fR, use
\fB18:00:00,24:00:00\fR\&.
.TP
\fBschedule_remove = \fIid\fB\fR
Delete \fBid\fR from the scheduler.
.TP
\fBstart_tied =\fR
Start torrents that are tied to filenames that have been re-added.
.TP
\fBstop_untied =\fR
.TP
\fBclose_untied =\fR
.TP
\fBremove_untied =\fR
Stop, close or remove the torrents that are tied to filenames that
have been deleted. Clear the association with the 'U' key.
.TP
\fBclose_low_diskspace = \fIspace\fB\fR
Close any active torrents on filesystems with less than
\fBspace\fR diskspace left. Use with
\fBschedule\fR\&.
.TP
\fBstop_on_ratio = \fImin_ratio\fB\fR
.TP
\fBstop_on_ratio = \fImin_ratio\fB,\fImin_upload\fB\fR
.TP
\fBstop_on_ratio = \fImin_ratio\fB,\fImin_upload\fB,\fImax_ratio\fB\fR
Stop torrents when they reach the given upload ratio
\fBmin_ratio\fR in percent. If the optional
\fBmin_upload\fR is given, require a total
upload amount of this many bytes as well. If the optional
\fBmax_ratio>\fR is given, stop the torrent
when reaching this ratio regardless of the total upload
amount. Exclude certain torrent by pressing 
\fBShift+I\fR in the downlist list.
Use with \fBschedule\fR\&.
.TP
\fBload = \fIfile\fB\fR
.TP
\fBload_verbose = \fIfile\fB\fR
.TP
\fBload_start = \fIfile\fB\fR
.TP
\fBload_start_verbose = \fIfile\fB\fR
Load and possibly start a file, or possibly multiple files by using the
wild-card "*". This is meant for use with
\fBschedule\fR, though ensure that the
\fBstart\fR is non-zero. The loaded file will be tied
to the filename provided.
.TP
\fBimport = \fIfile\fB\fR
.TP
\fBtry_import = \fIfile\fB\fR
Load a resource file. \fBtry_import\fR does not throw
torrent::input_error exception on bad input.
.SH "USER-INTERFACE SETTINGS"
.PP
Display related settings.
.TP
\fBview_add = \fIname\fB\fR
Create a new view.
.TP
\fBview_sort = \fIname\fB\fR
.TP
\fBview_sort = \fIname\fB,\fIseconds\fB\fR
Sort a view according the the criteria set by
\fBview_sort_current\fR\&. If the optional argument is
supplied, the view is not sorted if a change happened during the last
\fBseconds\fR\&. This command is meant to be used with
\fBschedule\fR\&.
.TP
\fBview_sort_new = \fIname\fB,\fI\&...\fB\fR
.TP
\fBview_sort_current = \fIname\fB,\fI\&...\fB\fR
Set the sorting criteria for when new elements inserted or
\fBview_sort\fR is called. The list can contain any
number of criteria, including zero, from the following:

\fBname\fR, \fBname_reverse\fR,
\fBstopped\fR, \fBstarted\fR,
\fBcomplete\fR, \fBincomplete\fR,
\fBstate_changed\fR,
\fBstate_changed_reverse\fR
.TP
\fBview_filter = \fIname\fB,\fI\&...\fB\fR
Set a list of filter to apply when new new downloads are added and
when \fBview_sort\fR is called. All filters must
match for the download to be included.

\fBstopped\fR, \fBstarted\fR,
\fBcomplete\fR, \fBincomplete\fR,
.TP
\fBkey_layout = \fIquerty|azerty\fB\fR
Change the key-bindings.
.SH "ADVANCED SETTINGS"
.PP
This list contains settings users shouldn't need to touch.
.TP
\fBhash_read_ahead = \fIMB\fB\fR
Configure how far ahead we ask the kernel to read when doing hash
checking. The hash checker uses madvise(..., MADV_WILLNEED) for the
requests.
.TP
\fBhash_interval = \fIms\fB\fR
Interval between attempts to check the hash when the chunk is not in
memory, in milliseconds.
.TP
\fBhash_max_tries = \fItries\fB\fR
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.
.TP
\fBmax_open_files = \fIvalue\fB\fR
Number of files to simultaneously keep open. Libtorrent dynamically
opens and closes files when mapping files to memory. Defaults to 128.
.TP
\fBmax_open_sockets = \fIvalue\fB\fR
Number of sockets to simultaneously keep open. This value is set to be
\fBsysconf(_SC_OPEN_MAX) - 256\fR at startup. This
gives the client 128 sockets to use as it wishes.
.TP
\fBsend_buffer_size = \fIvalue\fB\fR
.TP
\fBreceive_buffer_size = \fIvalue\fB\fR
Adjust the send and receive buffer size for socket.
.TP
\fBumask = \fI0644\fB\fR
Set the umask for this process, which is applied to all files created
by the program.
.TP
\fBworking_directory = \fIdirectory\fB\fR
Changes the working directory of the process using
\fBchdir\fR\&.
.TP
\fBsession_on_completion = \fIyes\fB\fR
Controls if the session torrent is saved when a torrent finishes. By
default on.
.TP
\fBsession_lock = \fIyes\fB\fR
Controls if a lock file is created in the session directory on startup.
.TP
\fBsession_save = \fR
Save the session files for all downloads.
.TP
\fBuse_udp_trackers = \fIyes\fB\fR
Use UDP trackers. Disable if you are behind a firewall etc that does
not allow connections to UDP trackers.
.TP
\fBenable_trackers = \fIyes\fB\fR
Set to \fBno\fR to disable tracker requests.
.TP
\fBtracker_dump = \fIfilename\fB\fR
Dump tracker requests to \fBfilename\fR, disable by
supplying an empty string. Only torrents loaded while
\fBtracker_dump\fR contains a non-empty string will be
logged at the moment, although disabling it will work as expected.
.TP
\fBtos = \fIdefault|lowdelay|throughput|reliability|mincost\fB\fR
Change the TOS of peer connections, by default set to
\fBthroughput\fR\&. If the option is set to
\fBdefault\fR then the system default TOS is used.
.SH "AUTHORS"
.PP

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