debian/apt-p2p.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2
   3   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
   4   <!ENTITY dhfirstname "<firstname>Cameron</firstname>">
   5   <!ENTITY dhsurname   "<surname>Dale</surname>">
   6   <!-- Please adjust the date whenever revising the manpage. -->
   7   <!ENTITY dhdate      "<date>April 25, 2008</date>">
   8   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
   9        allowed: see man(7), man(1). -->
  10   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  11   <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
  12   <!ENTITY dhusername  "Cameron Dale">
  13   <!ENTITY dhucpackage "<refentrytitle>apt-p2p</refentrytitle>">
  14   <!ENTITY dhpackage   "apt-p2p">
  15
  16   <!ENTITY debian      "<productname>Debian</productname>">
  17   <!ENTITY gnu         "<acronym>GNU</acronym>">
  18   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  19 ]>
  20
  21 <refentry>
  22   <refentryinfo>
  23     <address>
  24       &dhemail;
  25     </address>
  26     <author>
  27       &dhfirstname;
  28       &dhsurname;
  29     </author>
  30     <copyright>
  31       <year>2008</year>
  32       <holder>&dhusername;</holder>
  33     </copyright>
  34     &dhdate;
  35   </refentryinfo>
  36   <refmeta>
  37     &dhucpackage;
  38
  39     &dhsection;
  40   </refmeta>
  41
  42   <refnamediv>
  43     <refname>&dhpackage;</refname>
  44
  45     <refpurpose>apt helper for peer-to-peer downloads of Debian packages</refpurpose>
  46   </refnamediv>
  47   <refsynopsisdiv>
  48     <para>Normally &dhpackage; is run from init.d using <command>twistd</command>, in which case no &dhpackage;
  49         options can be specified on the command-line, and all configuration variables are
  50         read from the default config file locations of $HOME/.apt-p2p/apt-p2p.conf and /etc/apt-p2p/apt-p2p.conf.
  51         The command is then:</para>
  52     <cmdsynopsis>
  53       <command>twistd</command> <arg choice="Req">-y /path/to/&dhpackage;</arg> <arg rep="Repeat"><option>twistd options</option></arg>
  54     </cmdsynopsis>
  55     <para>For a detailed listing of the <command>twistd</command> options, see
  56         <citerefentry><refentrytitle>twistd</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
  57     <para>&dhpackage; can also be run without <command>twistd</command> by executing:</para>
  58     <cmdsynopsis>
  59       <command>&dhpackage;</command> <arg rep="Repeat"><option>options</option></arg>
  60     </cmdsynopsis>
  61     <para>In this case, you can specify the options documented below on the command-line.</para>
  62   </refsynopsisdiv>
  63   <refsect1>
  64     <title>DESCRIPTION</title>
  65
  66
  67     <para><command>&dhpackage;</command> is a helper for downloading Debian packages files with APT.
  68         It will download any needed files from other Apt-P2P peers in a
  69         peer-to-peer manner, and so reduce the strain on the Debian mirrors.</para>
  70
  71       <refsect2>
  72         <title>APT SETUP</title>
  73
  74     <para>In order for APT to send it's requests to &dhpackage;, the sources.list entries must be modified to point to the
  75         local &dhpackage; address. Unless you have changed the default port, then adding "localhost:9977/" to the beginning
  76         of each entry should be sufficient. For example, if your sources.list contains a line like this:</para>
  77
  78     <blockquote><para>deb http://ftp.us.debian.org/debian etch main contrib non-free</para></blockquote>
  79
  80     <para>then replace it with this:</para>
  81
  82     <blockquote><para>deb http://localhost:9977/ftp.us.debian.org/debian etch main contrib non-free</para></blockquote>
  83
  84     <para>You can do the same with 'deb-src' lines as well, and &dhpackage;
  85         will be used to download and share your source packages as well.</para>
  86
  87       </refsect2>
  88       <refsect2>
  89         <title>PORT FORWARDING</title>
  90
  91     <para>It is VERY important that Apt-P2P's ports be reachable by other peers.
  92         This is needed both to share files with others, and to connect to
  93         others through the DHT to find peers for files. If you aren't
  94         accessible by others, you will not only not share anything, but your
  95         performance during downloading will be affected.</para>
  96
  97     <para>Apt-P2P uses a default port of 9977, over both TCP and UDP, for it's
  98         communication. You can change this port in the
  99         /etc/apt-p2p/apt-p2p.conf file, and use different ports for TCP and
 100         UDP, if desired. Whatever port you use, make sure to forward it
 101         through your NAT or firewall to improve your performance and share
 102         with others. Information on port forwarding can be found here:</para>
 103
 104     <para><ulink url="http://portforward.com/"></ulink></para>
 105
 106       </refsect2>
 107       <refsect2>
 108         <title>PRIVATE NETWORKS</title>
 109
 110     <para>Apt-P2P is not designed to function as a downloader for multiple
 111         clients on a private network. Apt-P2P checks the source of incoming
 112         requests and only responds to those from the localhost. For more
 113         information:</para>
 114
 115     <para><ulink url="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=481243"></ulink></para>
 116
 117       </refsect2>
 118    </refsect1>
 119   <refsect1>
 120     <title>OPTIONS</title>
 121
 122     <para>These programs follow the usual &gnu; command line syntax,
 123       with short options starting with a single dash ('-'),
 124       and long options starting with two dashes ('--').
 125       A summary of options is included below.</para>
 126
 127     <variablelist>
 128       <varlistentry>
 129         <term><option>-c <replaceable>filename</replaceable>,</option> <option>--configfile=<replaceable>filename</replaceable></option></term>
 130          <listitem>
 131           <para>the <replaceable>filename</replaceable> to use for the configuration file, options found in this
 132               file are combined with those in $HOME/.apt-p2p/apt-p2p.conf and /etc/apt-p2p/apt-p2p.conf
 133               (see <citerefentry><refentrytitle>apt-p2p.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the format of the file)</para>
 134         </listitem>
 135       </varlistentry>
 136       <varlistentry>
 137         <term><option>-l <replaceable>filename</replaceable>,</option> <option>--logfile=<replaceable>filename</replaceable></option></term>
 138          <listitem>
 139           <para>the <replaceable>filename</replaceable> to print log messages to,
 140               or '-' to log to standard output, if not specified then
 141               /var/log/apt-p2p.log will be used</para>
 142         </listitem>
 143       </varlistentry>
 144       <varlistentry>
 145         <term><option>-h</option>, <option>--help</option></term>
 146         <listitem>
 147           <para>print a help message describing the invocation of the program</para>
 148         </listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term><option>-v</option>, <option>--version</option></term>
 152         <listitem>
 153           <para>print the version of the program</para>
 154         </listitem>
 155       </varlistentry>
 156     </variablelist>
 157   </refsect1>
 158
 159   <refsect1>
 160     <title>SEE ALSO</title>
 161
 162     <para>
 163       <citerefentry><refentrytitle>apt-p2p.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>twistd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 165     </para>
 166   </refsect1>
 167   <refsect1>
 168     <title>AUTHOR</title>
 169     <para>This manual page was written by &dhusername; &lt;&dhemail;> for
 170       the &debian; system (but may be used by others).  Permission is
 171       granted to copy, distribute and/or modify this document under
 172       the terms of the &gnu; General Public License, Version 2 or any
 173       later version published by the Free Software Foundation.
 174     </para>
 175     <para>
 176       On Debian systems, the complete text of the GNU General Public
 177       License can be found in /usr/share/common-licenses/GPL.
 178     </para>
 179   </refsect1>
 180 </refentry>
 181
 182 <!-- Keep this comment at the end of the file
 183 Local variables:
 184 mode: sgml
 185 sgml-omittag:t
 186 sgml-shorttag:t
 187 sgml-minimize-attributes:nil
 188 sgml-always-quote-attributes:t
 189 sgml-indent-step:2
 190 sgml-indent-data:t
 191 sgml-parent-document:nil
 192 sgml-default-dtd-file:nil
 193 sgml-exposed-tags:nil
 194 sgml-local-catalogs:nil
 195 sgml-local-ecat-files:nil
 196 End:
 197 -->