debian/apt-dht.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>February 17, 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-dht</refentrytitle>">
  14   <!ENTITY dhpackage   "apt-dht">
  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-dht.conf and /etc/apt-dht/apt-dht.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 twistd options, see
  56         <citerefentry><refentrytitle>twistd</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
  57     <para>&dhpackage; can also be run without twistd 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     <para>This manual page documents briefly the options available to the &dhpackage; command.</para>
  67
  68     <para><command>&dhpackage;</command> is a helper for downloading Debian packages files with APT.
  69         It will download any needed files from other Apt-DHT peers in a
  70         bittorrent-like manner, and so reduce the strain on the Debian mirrors.</para>
  71
  72     <para>In order for APT to send it's requests to &dhpackage;, the source.list entries must be modified to point to the
  73         local &dhpackage; address. Unless you have changed the default port, then adding "localhost:9977/" to the beginning
  74         of each entry should be sufficient. For example, if your sources.list contains a line like this:</para>
  75
  76     <para>deb http://ftp.us.debian.org/debian etch main contrib non-free</para>
  77
  78     <para>then replace it with this:</para>
  79
  80     <para>deb http://localhost:9977/ftp.us.debian.org/debian etch main contrib non-free</para>
  81
  82     <para>The port can be changed in the &dhpackage; config file in /etc/&dhpackage;/&dhpackage;.conf,
  83         but it defaults to 9977.</para>
  84   </refsect1>
  85   <refsect1>
  86     <title>OPTIONS</title>
  87
  88     <para>These programs follow the usual &gnu; command line syntax,
  89       with short options starting with a single dash (`-'),
  90       and long options starting with two dashes (`--').
  91       A summary of options is included below.</para>
  92
  93     <variablelist>
  94       <varlistentry>
  95         <term><option>-c <replaceable>filename</replaceable>,</option> <option>--configfile=<replaceable>filename</replaceable></option></term>
  96          <listitem>
  97           <para>the <replaceable>filename</replaceable> to use for the configuration file, options found in this
  98               file are combined with those in ${HOME}/.apt-dht/apt-dht.conf and /etc/apt-dht/apt-dht.conf
  99               (see <citerefentry><refentrytitle>apt-dht.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for the format of the file)</para>
 100         </listitem>
 101       </varlistentry>
 102       <varlistentry>
 103         <term><option>-l <replaceable>filename</replaceable>,</option> <option>--logfile=<replaceable>filename</replaceable></option></term>
 104          <listitem>
 105           <para>the <replaceable>filename</replaceable> to print log messages to,
 106               or `-' to log to standard output, if not specified then
 107               /var/log/apt-dht.log will be used</para>
 108         </listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term><option>-h</option>, <option>--help</option></term>
 112         <listitem>
 113           <para>print a help message describing the invocation of the program</para>
 114         </listitem>
 115       </varlistentry>
 116       <varlistentry>
 117         <term><option>-v</option>, <option>--version</option></term>
 118         <listitem>
 119           <para>print the version of the program</para>
 120         </listitem>
 121       </varlistentry>
 122     </variablelist>
 123   </refsect1>
 124
 125   <refsect1>
 126     <title>SEE ALSO</title>
 127
 128     <para>
 129       <citerefentry><refentrytitle>apt-dht.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 130       <citerefentry><refentrytitle>twistd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 131     </para>
 132   </refsect1>
 133   <refsect1>
 134     <title>AUTHOR</title>
 135     <para>This manual page was written by &dhusername; &lt;&dhemail;> for
 136       the &debian; system (but may be used by others).  Permission is
 137       granted to copy, distribute and/or modify this document under
 138       the terms of the &gnu; General Public License, Version 2 or any
 139       later version published by the Free Software Foundation.
 140     </para>
 141     <para>
 142       On Debian systems, the complete text of the GNU General Public
 143       License can be found in /usr/share/common-licenses/GPL.
 144     </para>
 145   </refsect1>
 146 </refentry>
 147
 148 <!-- Keep this comment at the end of the file
 149 Local variables:
 150 mode: sgml
 151 sgml-omittag:t
 152 sgml-shorttag:t
 153 sgml-minimize-attributes:nil
 154 sgml-always-quote-attributes:t
 155 sgml-indent-step:2
 156 sgml-indent-data:t
 157 sgml-parent-document:nil
 158 sgml-default-dtd-file:nil
 159 sgml-exposed-tags:nil
 160 sgml-local-catalogs:nil
 161 sgml-local-ecat-files:nil
 162 End:
 163 -->