debian/apt-dht.conf.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>5</manvolnum>">
  11   <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
  12   <!ENTITY dhusername  "Cameron Dale">
  13   <!ENTITY dhucpackage "<refentrytitle>apt-dht.conf</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>configuration file for &dhpackage;</refpurpose>
  46   </refnamediv>
  47
  48   <refsect1>
  49     <title>DESCRIPTION</title>
  50
  51     <para>Configuration information for &dhpackage; is searched for in the following order, with later
  52       entries overriding former ones:
  53       <OrderedList>
  54         <ListItem><para>/etc/apt-dht/apt-dht.conf</para></ListItem>
  55         <ListItem><para>${HOME}/.apt-dht/apt-dht.conf</para></ListItem>
  56         <ListItem><para>the location specified by the config-file parameter</para></ListItem>
  57       </OrderedList>
  58     </para>
  59
  60   </refsect1>
  61   <refsect1>
  62     <title>FORMAT</title>
  63
  64     <para>&dhpackage; has a structure similar to Microsoft Windows INI files.
  65         The configuration file consists of sections, led by a ``[section]'' header and followed
  66         by ``name = value'' or ``name: value'' entries, with continuations in the style of RFC 822
  67         (values can span multiple lines by starting the subsequent lines with one or more spaces).
  68         Some values indicate times, in which case a suffix of 'd' for
  69         days, 'h' for hours, 'm' for minutes, and 's' for seconds can be used.
  70         Boolean values can be '1', 'yes', 'true', and 'on' to evaluate to True,
  71         or '0', 'no', 'false', and 'off' to evaluate to false.
  72         Note that leading whitespace is removed from values, and case is not important.
  73         Lines beginning with "#" or ";" are ignored and may be used to provide comments.</para>
  74
  75   </refsect1>
  76   <refsect1>
  77     <title>VARIABLES</title>
  78       <para>There are 2 required sections in the config file. The first is the DEFAULT section, providing
  79         variables for the configuration of the main application. The second is the section that provides
  80         variables for the configuration of the DHT.</para>
  81
  82       <refsect2>
  83         <title>DEFAULT</title>
  84
  85         <variablelist>
  86           <varlistentry>
  87             <term><option>PORT = <replaceable>number</replaceable></option></term>
  88              <listitem>
  89               <para>The <replaceable>number</replaceable> of the port to listen on for requests.
  90                   The main application will use this TCP port to listen for requests from APT, and
  91                   for uploads to other peers. If a port is not specified for the DHT, it will also
  92                   use this UDP port to listen for DHT requests.
  93                   (Default is 9977.)</para>
  94             </listitem>
  95           </varlistentry>
  96           <varlistentry>
  97             <term><option>CACHE_DIR = <replaceable>directory</replaceable></option></term>
  98              <listitem>
  99               <para>The <replaceable>directory</replaceable> to store the downloaded files in.
 100                 (Default is ${HOME}/.apt-dht/cache.)</para>
 101             </listitem>
 102           </varlistentry>
 103           <varlistentry>
 104             <term><option>OTHER_DIRS = <replaceable>list</replaceable></option></term>
 105              <listitem>
 106               <para>The <replaceable>list</replaceable> of directories containing packages to share with others.
 107                 All files in these directories will be hashed and available for everybody to download.
 108                 (Default is to share only the files downloaded.)</para>
 109             </listitem>
 110           </varlistentry>
 111           <varlistentry>
 112             <term><option>LOCAL_OK = <replaceable>boolean</replaceable></option></term>
 113              <listitem>
 114               <para>Whether it's OK to use an IP addres from a known local or private range.
 115                 (Default is false)</para>
 116             </listitem>
 117           </varlistentry>
 118           <varlistentry>
 119             <term><option>DHT = <replaceable>string</replaceable></option></term>
 120              <listitem>
 121               <para>The DHT implementation to use. It must be possile to do (in python)
 122                 ``from &lt;DHT&gt;.DHT import DHT'' to get a class that implements the IDHT interface.
 123                 There should also be a similarly named section below to specify the options for the DHT.
 124                 (Default is `apt_dht_Khashmir')</para>
 125             </listitem>
 126           </varlistentry>
 127           <varlistentry>
 128             <term><option>DHT-ONLY = <replaceable>boolean</replaceable></option></term>
 129              <listitem>
 130               <para>Whether to only run the DHT. This can be useful for providing only a bootstrap node.
 131                 (Default is false)</para>
 132             </listitem>
 133           </varlistentry>
 134         </variablelist>
 135       </refsect2>
 136       <refsect2>
 137         <title>apt_dht_Khashmir</title>
 138
 139         <variablelist>
 140           <varlistentry>
 141             <term><option>PORT = <replaceable>number</replaceable></option></term>
 142              <listitem>
 143               <para>The <replaceable>number</replaceable> of the port to listen on for DHT (UDP) requests.
 144                   (Default is to use the value specified in the DEFAULT section.)</para>
 145             </listitem>
 146           </varlistentry>
 147           <varlistentry>
 148             <term><option>BOOTSTRAP = <replaceable>list</replaceable></option></term>
 149              <listitem>
 150               <para>The <replaceable>list</replaceable> of bootstrap nodes to contact to join the DHT.
 151                 Each node should be on a separate line, and start with the IP address or host name,
 152                 followed by a colon and the port number.
 153                 (Default is a list of known good nodes.)</para>
 154             </listitem>
 155           </varlistentry>
 156           <varlistentry>
 157             <term><option>BOOTSTRAP_NODE = <replaceable>boolean</replaceable></option></term>
 158              <listitem>
 159               <para>Whether this node is a bootstrap node.
 160                 (Default is false)</para>
 161             </listitem>
 162           </varlistentry>
 163           <varlistentry>
 164             <term><option>K = <replaceable>number</replaceable></option></term>
 165              <listitem>
 166               <para>The <replaceable>number</replaceable> of the Kademlia "K" constant.
 167                   It should be an even number.
 168                   (Default is 8.)</para>
 169             </listitem>
 170           </varlistentry>
 171           <varlistentry>
 172             <term><option>HASH_LENGTH = <replaceable>number</replaceable></option></term>
 173              <listitem>
 174               <para>The <replaceable>number</replaceable> of bits in the hash to use.
 175                   (Default is 160.)</para>
 176             </listitem>
 177           </varlistentry>
 178           <varlistentry>
 179             <term><option>CHECKPOINT_INTERVAL = <replaceable>time</replaceable></option></term>
 180              <listitem>
 181               <para>The <replaceable>time</replaceable> to wait between saves of the running state.
 182                   (Default is 15 minutes.)</para>
 183             </listitem>
 184           </varlistentry>
 185           <varlistentry>
 186             <term><option>CONCURRENT_REQS = <replaceable>number</replaceable></option></term>
 187              <listitem>
 188               <para>The concurrent <replaceable>number</replaceable> of calls per find node/value request.
 189                   (Default is 4.)</para>
 190             </listitem>
 191           </varlistentry>
 192           <varlistentry>
 193             <term><option>STORE_REDUNDANCY = <replaceable>number</replaceable></option></term>
 194              <listitem>
 195               <para>The <replaceable>number</replaceable> of redundant copies of a value to store in the DHT.
 196                   (Default is 3.)</para>
 197             </listitem>
 198           </varlistentry>
 199           <varlistentry>
 200             <term><option>MAX_FAILURES = <replaceable>number</replaceable></option></term>
 201              <listitem>
 202               <para>The <replaceable>number</replaceable> of times in a row a node can fail to
 203                   respond before it's booted from the routing table.
 204                   (Default is 3.)</para>
 205             </listitem>
 206           </varlistentry>
 207           <varlistentry>
 208             <term><option>MIN_PING_INTERVAL = <replaceable>time</replaceable></option></term>
 209              <listitem>
 210               <para>The minimum <replaceable>time</replaceable> to wait before re-pinging a node.
 211                   (Default is 15 minutes.)</para>
 212             </listitem>
 213           </varlistentry>
 214           <varlistentry>
 215             <term><option>BUCKET_STALENESS = <replaceable>time</replaceable></option></term>
 216              <listitem>
 217               <para>The maximum <replaceable>time</replaceable> to wait before refreshing a bucket.
 218                   (Default is 1 hour.)</para>
 219             </listitem>
 220           </varlistentry>
 221           <varlistentry>
 222             <term><option>KEINITIAL_DELAY = <replaceable>time</replaceable></option></term>
 223              <listitem>
 224               <para>The <replaceable>time</replaceable> to wait after startup before starting the key expirer.
 225                   (Default is 15 seconds.)</para>
 226             </listitem>
 227           </varlistentry>
 228           <varlistentry>
 229             <term><option>KE_DELAY = <replaceable>time</replaceable></option></term>
 230              <listitem>
 231               <para>The <replaceable>time</replaceable> to wait between runs of the key expirer.
 232                   (Default is 20 minutes.)</para>
 233             </listitem>
 234           </varlistentry>
 235           <varlistentry>
 236             <term><option>KE_AGE = <replaceable>time</replaceable></option></term>
 237              <listitem>
 238               <para>The <replaceable>time</replaceable> to wait before expiring unrefreshed keys.
 239                   (Default is 1 hour.)</para>
 240             </listitem>
 241           </varlistentry>
 242           <varlistentry>
 243             <term><option>SPEW = <replaceable>boolean</replaceable></option></term>
 244              <listitem>
 245               <para>Whether to log lots of info about the requests and responses in the protocol.
 246                 (Default is false)</para>
 247             </listitem>
 248           </varlistentry>
 249         </variablelist>
 250      </refsect2>
 251   </refsect1>
 252
 253   <refsect1>
 254     <title>SEE ALSO</title>
 255
 256     <para>
 257       <citerefentry><refentrytitle>apt-dht</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 258     </para>
 259   </refsect1>
 260   <refsect1>
 261     <title>AUTHOR</title>
 262     <para>This manual page was written by &dhusername; &lt;&dhemail;> for
 263       the &debian; system (but may be used by others).  Permission is
 264       granted to copy, distribute and/or modify this document under
 265       the terms of the &gnu; General Public License, Version 2 or any
 266       later version published by the Free Software Foundation.
 267     </para>
 268     <para>
 269       On Debian systems, the complete text of the GNU General Public
 270       License can be found in /usr/share/common-licenses/GPL.
 271     </para>
 272   </refsect1>
 273 </refentry>
 274
 275 <!-- Keep this comment at the end of the file
 276 Local variables:
 277 mode: sgml
 278 sgml-omittag:t
 279 sgml-shorttag:t
 280 sgml-minimize-attributes:nil
 281 sgml-always-quote-attributes:t
 282 sgml-indent-step:2
 283 sgml-indent-data:t
 284 sgml-parent-document:nil
 285 sgml-default-dtd-file:nil
 286 sgml-exposed-tags:nil
 287 sgml-local-catalogs:nil
 288 sgml-local-ecat-files:nil
 289 End:
 290 -->