<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Cameron</firstname>">
  <!ENTITY dhsurname   "<surname>Dale</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>April 17, 2005</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
  <!ENTITY dhusername  "Cameron Dale">
  <!ENTITY dhucpackage "<refentrytitle>bittorrent-downloader.bittornado</refentrytitle>">
  <!ENTITY dhpackage   "bittorrent-downloader">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2006</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>

  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>download files using a scatter-gather network</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>btdownloadheadless</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>URL</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btdownloadheadless</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>filename</replaceable></arg>
    </cmdsynopsis>
   <cmdsynopsis>
      <command>btdownloadcurses</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>URL</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btdownloadcurses</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>filename</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btdownloadgui</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>URL</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btdownloadgui</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>filename</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btlaunchmany</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>directory</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>btlaunchmanycurses</command> <arg rep="Repeat"><option>options</option></arg> <arg choice="req"><replaceable>directory</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents briefly the options available to the &dhpackage; commands.</para>

    <para>This manual page was written for the &debian; distribution
      because the original program does not have a manual page.</para>

    <para><command>btdownloadheadless</command>, <command>btdownloadcurses</command>, <command>btdownloadgui</command>,
      <command>btlaunchmany</command>, and <command>btlaunchmanycurses</command> are all programs that allow a user to download files using
      bittorrent, a peer to peer, scatter-gather network protocol. They all share a common set of options, shown below. For
      more information on how to run them, and their program-specific options, see their individual man pages.</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <para>These programs follow the usual &gnu; command line syntax,
      with long options starting with two dashes (`--').  A summary of
      options is included below.</para>

    <variablelist>
      <varlistentry>
        <term><option>--max_uploads <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>number</replaceable> of uploads to allow at once (defaults to 7)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--keepalive_interval <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> to pause between sending keepalives (defaults to 120.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--download_slice_size <replaceable>bytes</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>bytes</replaceable> to query for per request (defaults to 16384)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upload_unit_size <replaceable>bytes</replaceable></option></term>
        <listitem>
          <para>when limiting the upload rate, the number of <replaceable>bytes</replaceable> to send at a time (defaults to 1460)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--request_backlog <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>number</replaceable> of requests to keep in a single pipe at once (defaults to 10)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_message_length <replaceable>length</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>length</replaceable> prefix encoding you'll accept over the wire.
	    Larger values will get the connection dropped. (defaults to 8388608)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--ip <replaceable>ip</replaceable></option></term>
        <listitem>
          <para>the <replaceable>ip</replaceable> to report you have to the tracker (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--minport <replaceable>port</replaceable></option></term>
        <listitem>
          <para>the minimum <replaceable>port</replaceable> to listen on (defaults to 10000)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--maxport <replaceable>port</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>port</replaceable> to listen on (defaults to 60000)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--random_port</option> 0|1</term>
        <listitem>
          <para>whether to choose randomly inside the port range (instead of counting up linearly from min to max) (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--responsefile <replaceable>file</replaceable></option></term>
        <listitem>
          <para>the <replaceable>file</replaceable> the server response was stored in, as an alternative to --url. If this option is used,
	    no filename or URL should be present on the command line. (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--url <replaceable>URL</replaceable></option></term>
        <listitem>
          <para>the <replaceable>URL</replaceable> to get the torrent file from, as an alternative to --responsefile. If this option is used,
	    no filename or URL should be present on the command line. (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--crypto_allowed</option> 0|1</term>
        <listitem>
          <para>whether to allow the client to accept encrypted connections.
            (defaults to 1 if python-crypto is installed, 0 otherwise)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--crypto_only</option> 0|1</term>
        <listitem>
          <para>whether to only create or allow encrypted connections. (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--crypto_stealth</option> 0|1</term>
        <listitem>
          <para>whether to prevent all non-encrypted connection attempts; will result
          in an effectively firewalled state on older trackers. (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--selector_enabled</option> 0|1</term>
        <listitem>
          <para>whether to enable the file selector and fast resume function (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--expire_cache_data <replaceable>days</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>days</replaceable> after which you wish to expire old cache data (0 = disabled) (defaults to 10)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--priority</option> -1|0|1|2[,-1|0|1|2 ...]</term>
        <listitem>
          <para>a list of file priorities, separated by commas. There must be one per file. 0 = highest,
	    1 = normal, 2 = lowest, -1 = download disabled. Order is based
	    on the file/torrent order as shown by btshowmetainfo. For example, to download only
	    the third of four files use: --priority -1,-1,2,-1 (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--saveas <replaceable>filename</replaceable></option></term>
        <listitem>
          <para>the local <replaceable>filename</replaceable> to save the file as, null indicates query user (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--timeout <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> to wait between closing sockets which nothing has been received on
	    (defaults to 300.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--timeout_check_interval <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> to wait between checking if any connections have timed out (defaults to 60.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_slice_length <replaceable>length</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>length</replaceable> slice to send to peers, larger requests are ignored (defaults to 131072)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_rate_period <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the maximum number of <replaceable>seconds</replaceable> to use in guessing what the current rate estimate represents (defaults to 20.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--bind <replaceable>ip</replaceable>|<replaceable>hostname</replaceable>[,<replaceable>ip</replaceable>|<replaceable>hostname</replaceable> ...]</option></term>
        <listitem>
          <para>a comma-separated list of <replaceable>ips</replaceable> and <replaceable>hostnames</replaceable> to bind to locally (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--ipv6_enabled</option> 0|1</term>
        <listitem>
          <para>whether to allow the client to connect to peers via IPv6 (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--ipv6_binds_v4</option> 0|1</term>
        <listitem>
          <para>set if an IPv6 server socket won't also field IPv4 connections (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--upload_rate_fudge <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the time equivalent in <replaceable>seconds</replaceable> of writing to kernel-level TCP buffer, for rate adjustment (defaults to
	    5.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--tcp_ack_fudge <replaceable>overhead</replaceable></option></term>
        <listitem>
          <para>how much TCP ACK download <replaceable>overhead</replaceable> to add to upload rate calculations (0 = disabled)
	    (defaults to 0.029999999999999999)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--display_interval <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> between updates of displayed information (defaults to 0.5)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--rerequest_interval <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> between requesting more peers (defaults to 300)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--min_peers <replaceable>number</replaceable></option></term>
        <listitem>
          <para>make tracker requests every --rerequest_interval until this <replaceable>number</replaceable> has been reached, then switch to the standard longer interval (defaults to 20)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--http_timeout <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> to wait before assuming that an http connection
	    has timed out (defaults to 60)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_initiate <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the <replaceable>number</replaceable> of peers at which to stop initiating new connections (defaults to 40)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--check_hashes</option> 0|1</term>
        <listitem>
          <para>whether to check hashes on disk (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_upload_rate <replaceable>kB/s</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>kB/s</replaceable> to upload at (0 = no limit, -1 = automatic) (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_download_rate <replaceable>kB/s</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>kB/s</replaceable> to download at (0 = no limit) (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--alloc_type</option> normal|background|pre-allocate|sparse</term>
        <listitem>
          <para>the allocation type (may be 'normal', 'background', 'pre-allocate' or 'sparse') (defaults to 'normal')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--alloc_rate <replaceable>MiB/s</replaceable></option></term>
        <listitem>
          <para>the rate (in <replaceable>MiB/s</replaceable>) to allocate space at using background allocation (defaults to 2.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--buffer_reads</option> 0|1</term>
        <listitem>
          <para>whether to buffer disk reads (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--write_buffer_size <replaceable>space</replaceable></option></term>
        <listitem>
          <para>the maximum amount of <replaceable>space</replaceable> to use for buffering disk writes (in megabytes, 0 = disabled)
	    (defaults to 4)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--breakup_seed_bitfield</option> 0|1</term>
        <listitem>
          <para>whether to send an incomplete bitfield and then 'have' messages, in
	    order to get around stupid ISP manipulation (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--snub_time <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> to wait for data to come in over a connection before assuming it's
	    semi-permanently choked (defaults to 30.0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--spew</option> 0|1</term>
        <listitem>
          <para>whether to display diagnostic info to stdout. This option is not very useful when using the curses or gui interfaces. (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--rarest_first_cutoff <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the <replaceable>number</replaceable> of downloads at which to switch from random to rarest first (defaults to 2)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--rarest_first_priority_cutoff <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the <replaceable>number</replaceable> of peers which need to have a piece before other partials take priority over
	    rarest first (defaults to 5)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--min_uploads <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the <replaceable>number</replaceable> of uploads to fill out to with extra optimistic unchokes (defaults to 4)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_files_open <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the maximum <replaceable>number</replaceable> of files to keep open at a time, 0 means no limit (defaults to 50)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--round_robin_period <replaceable>seconds</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>seconds</replaceable> between the client switching upload targets (defaults to 30)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--super_seeder</option> 0|1</term>
        <listitem>
          <para>whether to use special upload-efficiency-maximizing routines (only for dedicated seeds)
	    (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--security</option> 0|1</term>
        <listitem>
          <para>whether to enable extra security features intended to prevent abuse (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--max_connections <replaceable>number</replaceable></option></term>
        <listitem>
          <para>the absolute maximum <replaceable>number</replaceable> of peers to connect with (0 = no limit) (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--auto_kick</option> 0|1</term>
        <listitem>
          <para>whether to allow the client to automatically kick/ban peers that send bad data (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--double_check</option> 0|1</term>
        <listitem>
          <para>whether to double-check data being written to the disk for errors (may increase CPU load)
	    (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--triple_check</option> 0|1</term>
        <listitem>
          <para>whether to thoroughly check data being written to the disk (may slow disk access)
	    (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--lock_files</option> 0|1</term>
        <listitem>
          <para>whether to lock files the client is working with (defaults to 1)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--lock_while_reading</option> 0|1</term>
        <listitem>
          <para>whether to lock access to files being read (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--auto_flush <replaceable>minutes</replaceable></option></term>
        <listitem>
          <para>the number of <replaceable>minutes</replaceable> between automatic flushes to disk (0 = disabled) (defaults to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--dedicated_seed_id <replaceable>code</replaceable></option></term>
         <listitem>
          <para>the <replaceable>code</replaceable> to send to a tracker, identifying as a dedicated seed (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--save_options</option> 0|1</term>
	<listitem>
	  <para>whether to save the current options as the new default configuration
	    for the current program (defaults to 0)</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>The single torrent downloaders:
      <citerefentry><refentrytitle>btdownloadheadless</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btdownloadcurses</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btdownloadgui</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The multiple torrent downloaders:
      <citerefentry><refentrytitle>bittorrent-multi-downloader</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btlaunchmany</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btlaunchmanycurses</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The bittorrent tracker:
      <citerefentry><refentrytitle>bttrack</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The torrent file creators: 
      <citerefentry><refentrytitle>btmakemetafile</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btmaketorrentgui</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btcompletedir</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btcompletedirgui</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The torrent file modifiers:
      <citerefentry><refentrytitle>btcopyannounce</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btreannounce</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btrename</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btsethttpseeds</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>

    <para>The torrent file displayer:
      <citerefentry><refentrytitle>btshowmetainfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>This manual page was written by &dhusername; &lt;&dhemail;> (based on the original man pages written by Micah Anderson &lt;micah@debian.org>) for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the &gnu; General Public License, Version 2 or any
      later version published by the Free Software Foundation.
    </para>
    <para>
      On Debian systems, the complete text of the GNU General Public
      License can be found in /usr/share/common-licenses/GPL.
    </para>
  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
