Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 10, 2021

rtorrent (1)


rtorrent - a BitTorrent client for ncurses


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


RTORRENT(1)                                                        RTORRENT(1)

       rtorrent - a BitTorrent client for ncurses

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

       rtorrent is a BitTorrent  client  for  ncurses,  using  the  libtorrent
       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.

       Most  of  the  options below have their own default unit in addition to
       supporting B, K, M and G suffixes.

       ^q     Initiate shutdown, press again to force the  shutdown  and  skip
              sending the stop signal to trackers.

       up | down | left | right arrow keys

       ^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 to the previous screen.

       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.

       ->     View download.

       1 - 7  Change view.

       ^S     Start download.

       ^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.

       ^X     Call commands or change settings.

       ^B     Set download to perform initial seeding. Only use when  you  are
              the first and only seeder so far for the download.

       + | -  Change the priority of the download.

              Add torrent using an URL or file path. Use tab to view directory
              content and do auto-complete.

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

       U      Delete the file the torrent is tied to, and clear  the  associa-

       I      Toggle whether torrent ignores ratio settings.

       ->     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 transfering blocks.

       i      Display chunk rarity.

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

       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.

       k      Disconnect peer.

       *      Choke/Snub peer.

       -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,...

       -O key=opt
              Set any number of options, see the SETTINGS section. The options
              given  here override the resource files. Use capital -O to allow
              comma in the option.

       -p a-b Try to open a listening port in the range a up to and  including

       -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.

       bind = a.b.c.d
              Bind  listening  socket and outgoing connections to this network
              interface address.

       ip = a.b.c.d

       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

       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, if none match the tor-
              rent default is used.

       encryption = option,...
              Set how rtorrent should deal with encrypted  Bittorrent  connec-
              tions.  By default, encryption is disabled, equivalent to speci-
              fying the option none. Alternatively, any number of the  follow-
              ing options may be specified:

              allow_incoming  (allow incoming encrypted connections), try_out-
              going (use encryption for outgoing connections),  require  (dis-
              able  unencrypted  handshakes), require_RC4 (also disable plain-
              text  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.

       schedule = id,start,interval,command
              Call command every interval seconds,  starting  from  start.  An
              interval  of  zero  calls  the  task once, while a start of zero
              calls it immediately. Currently  command  is  forwarded  to  the
              option  handler.   start  and interval may optionally use a time
              format, dd:hh:mm:ss. F.ex to start a task every  day  at  18:00,
              use 18:00:00,24:00:00.

       schedule_remove = id
              Delete id from the scheduler.

       start_tied =
              Start  torrents  that  are  tied to filenames that have been re-

       stop_untied =

       close_untied =

       remove_untied =
              Stop, close or 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  sched-
              uled event with id low_diskspace is set to 500Mb.

       load = file

       load_verbose = file

       load_start = file

       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

       try_import = file
              Load  a  resource  file.  try_import   does   not   throw   tor-
              rent::input_error exception on bad input.

       stop_on_ratio = min_ratio

       stop_on_ratio = min_ratio,min_upload

       stop_on_ratio = min_ratio,min_upload,max_ratio
              Stop  torrents  when they reach the given upload ratio min_ratio
              in percent. If the optional min_upload is given, require a total
              upload  amount  of  this  many  bytes  as  well. If the optional
              max_ratio is given, stop the torrent when  reaching  this  ratio
              regardless  of  the total upload amount. Exclude certain torrent
              by pressing Shift+I in the downlist list.  Use with the schedule

       on_insert = id,command

       on_erase = id,command

       on_open = id,command

       on_close = id,command

       on_start = id,command

       on_stop = id,command

       on_hash_queued = id,command

       on_hash_removed = id,command

       on_hash_done = id,command

       on_finished = id,command
              Call a command on a download when its state changes. Only a sub-
              set of commands are available.

       upload_rate = KB

       download_rate = KB
              Set the maximum global uploand and download rates.

       min_peers = value

       max_peers = value
              Set the minimum and maximum number of peers  to  allow  in  each

       min_peers_seed = value

       max_peers_seed = value
              Set the minimum nad maximum number of peers to allow while seed-
              ing, or -1 (default) to use max_peers.

       max_uploads = value
              Set the maximum number of simultaneous uploads per download.

       max_uploads_div = value

       max_downloads_div = value
              Change the divider used to calculate the max upload and download
              slots to use when the throttle is changed. Disable by setting 0.

       max_uploads_global = value

       max_downloads_global = value
              Max upload and download slots allowed. Disable by setting 0.

       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.  Only torrents loaded while tracker_dump contains a non-
              empty string will be logged at the moment, 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.

       dht = disabled|off|auto|on
              Support  for  querying  the distributed hash table (DHT) to find
              peers for trackerless torrents or when all  trackers  are  down.
              Set  to  disable  to  completely  disable  DHT, off (default) to
              enable DHT but to not start the DHT server,  auto  to  automati-
              cally  start  and stop the DHT server as needed or on for perma-
              nently keeping the DHT server running.  When set  to  automatic,
              the  DHT server will start up when the first non-private torrent
              is started, and will stop 15-30 minutes after the last  non-pri-
              vate  torrent  is  stopped  (or when rTorrent quits). For DHT to
              work, a session directory  must  be  set  (for  saving  the  DHT

       dht_port = number
              Set the UDP listen port for DHT. Defaults to 6881.

       dht_add_node = host[:port]
              Not  intended  for use in the configuration file but as one-time
              option in the client or on the  command  line  to  bootstrap  an
              empty  DHT  node  table. Contacts the given node and attempts to
              bootstrap from it if it replies.  The  port  is  optional,  with
              port 6881 being used by default.

       http_capath = path

       http_cacert = filename
              Set  the  certificates  to use in http requests. See Curl's CUR-
              LOPT_CAPATH and CURLOPT_CAINFO options for further information.

       Display related settings.

       view_add = name
              Create a new view.

       view_sort = name

       view_sort = name,seconds
              Sort a view according the 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 inserted or
              view_sort is called. The list can contain any number  of  crite-
              ria, 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 related settings.

       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  seperate  files.
              Disable by passing -1.

       split_suffix = string
              Set the suffix used on split files. Defaults to .part.

       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  concate-
              nation of path, the result of the type on the download, and suf-

              Available types are; base_path uses the base path of  the  down-
              load, base_filename uses the base filename of the download, tied
              uses the  path  of  the  file  the  download  is  tied  to,  see

       This  list  contains  settings  users shouldn't need to touch, some may
       even cause crashes or similar if incorrectly set.

       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 val-
              ues 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 dynami-
              cally 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

       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

       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  fin-
              ishes. By default on.

       session_lock = yes
              Controls  if  a lock file is created in the session directory on

       session_save =
              Save the session files for all downloads.

       tos = default|lowdelay|throughput|reliability|mincost

       tos = hex
              Change the TOS of peer connections, by default set  to  through-
              put. 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

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

       See attributes(7) for descriptions of the following attributes:

       |Availability   | network/rtorrent |
       |Stability      | Uncommitted      |
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source   was   downloaded   from    http://rtorrent.net/downloads/rtor-

       Further information about this software can be found on the open source
       community website at https://rakshasa.github.io/rtorrent/.

BitTorrent client for ncurses
                                  07 May 2008                      RTORRENT(1)