Increase the concurrency of DHT requests to 8.
[quix0rs-apt-p2p.git] / debian / apt-p2p.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>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>5</manvolnum>">
11   <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
12   <!ENTITY dhusername  "Cameron Dale">
13   <!ENTITY dhucpackage "<refentrytitle>apt-p2p.conf</refentrytitle>">
14   <!ENTITY dhpackage   "apt-p2p.conf">
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-p2p/apt-p2p.conf</para></ListItem>
55         <ListItem><para>${HOME}/.apt-p2p/apt-p2p.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>UPLOAD_LIMIT = <replaceable>speed</replaceable></option></term>
98              <listitem>
99               <para>The <replaceable>speed</replaceable> to limit sending data to peers to, in KBytes/sec.
100                 Set this to 0 to not limit the upload bandwidth.
101                 (Default is 0)</para>
102             </listitem>
103           </varlistentry>
104           <varlistentry>
105             <term><option>MIN_DOWNLOAD_PEERS = <replaceable>number</replaceable></option></term>
106              <listitem>
107               <para>The minimum <replaceable>number</replaceable> of peers before the mirror is not used.
108                 If there are fewer peers than this for a file, the mirror will also be
109                 used to speed up the download. Set to 0 to never use the mirror if
110                 there are peers.                
111                 (Default is 3)</para>
112             </listitem>
113           </varlistentry>
114           <varlistentry>
115             <term><option>CACHE_DIR = <replaceable>directory</replaceable></option></term>
116              <listitem>
117               <para>The <replaceable>directory</replaceable> to store the downloaded files in.
118                 (Default is ${HOME}/.apt-p2p/cache.)</para>
119             </listitem>
120           </varlistentry>
121           <varlistentry>
122             <term><option>OTHER_DIRS = <replaceable>list</replaceable></option></term>
123              <listitem>
124               <para>The <replaceable>list</replaceable> of directories containing packages to share with others.
125                 All files in these directories will be hashed and available for everybody to download.
126                 (Default is to share only the files downloaded.)</para>
127             </listitem>
128           </varlistentry>
129           <varlistentry>
130             <term><option>LOCAL_OK = <replaceable>boolean</replaceable></option></term>
131              <listitem>
132               <para>Whether it's OK to use an IP address from a known local or private range.
133                 (Default is false)</para>
134             </listitem>
135           </varlistentry>
136           <varlistentry>
137             <term><option>REMOTE_STATS = <replaceable>boolean</replaceable></option></term>
138              <listitem>
139               <para>Whether a remote peer can access the statistics page.
140                 (Default is True)</para>
141             </listitem>
142           </varlistentry>
143           <varlistentry>
144             <term><option>UNLOAD_PACKAGES_CACHE = <replaceable>time</replaceable></option></term>
145              <listitem>
146               <para>The <replaceable>time</replaceable> of inactivity to wait for before unloading the
147                   packages cache. The packages cache uses a lot of memory, and only takes a few seconds
148                   to reload when a new request arrives. (Default is 5 minutes.)</para>
149             </listitem>
150           </varlistentry>
151           <varlistentry>
152             <term><option>KEY_REFRESH = <replaceable>time</replaceable></option></term>
153              <listitem>
154               <para>The <replaceable>time</replaceable> after which to refresh DHT keys.
155                   This should be a time slightly less than the DHT's KEY_EXPIRE value.
156                   (Default is 2.5 hours.)</para>
157             </listitem>
158           </varlistentry>
159           <varlistentry>
160             <term><option>USERNAME = <replaceable>user</replaceable></option></term>
161              <listitem>
162               <para>The <replaceable>user</replaceable> name to try and run as.
163                   Leaving this blank will try to run as current user.
164                   (Default is 'apt-p2p'.)</para>
165             </listitem>
166           </varlistentry>
167           <varlistentry>
168             <term><option>DHT = <replaceable>string</replaceable></option></term>
169              <listitem>
170               <para>The DHT implementation to use. It must be possile to do (in python) 'from
171                 &lt;DHT&gt;.DHT import DHT' to get a class that implements the IDHT interface.
172                 There should also be a similarly named section in the config file to specify
173                 the options for the DHT. (Default is 'apt_p2p_Khashmir')</para>
174             </listitem>
175           </varlistentry>
176           <varlistentry>
177             <term><option>DHT-ONLY = <replaceable>boolean</replaceable></option></term>
178              <listitem>
179               <para>Whether to only run the DHT. This can be useful for providing only a bootstrap node.
180                 (Default is false)</para>
181             </listitem>
182           </varlistentry>
183         </variablelist>
184       </refsect2>
185       <refsect2>
186         <title>apt_p2p_Khashmir</title>
187
188         <variablelist>
189           <varlistentry>
190             <term><option>PORT = <replaceable>number</replaceable></option></term>
191              <listitem>
192               <para>The <replaceable>number</replaceable> of the port to listen on for DHT (UDP) requests.
193                   (Default is to use the value specified in the DEFAULT section.)</para>
194             </listitem>
195           </varlistentry>
196           <varlistentry>
197             <term><option>BOOTSTRAP = <replaceable>list</replaceable></option></term>
198              <listitem>
199               <para>The <replaceable>list</replaceable> of bootstrap nodes to contact to join the DHT.
200                 Each node should be on a separate line, and start with the IP address or host name,
201                 followed by a colon and the port number.
202                 (Default is a list of known good nodes.)</para>
203             </listitem>
204           </varlistentry>
205           <varlistentry>
206             <term><option>BOOTSTRAP_NODE = <replaceable>boolean</replaceable></option></term>
207              <listitem>
208               <para>Whether this node is a bootstrap node.
209                 (Default is false)</para>
210             </listitem>
211           </varlistentry>
212           <varlistentry>
213             <term><option>CHECKPOINT_INTERVAL = <replaceable>time</replaceable></option></term>
214              <listitem>
215               <para>The <replaceable>time</replaceable> to wait between saves of the running state.
216                   (Default is 5 minutes.)</para>
217             </listitem>
218           </varlistentry>
219           <varlistentry>
220             <term><option>CONCURRENT_REQS = <replaceable>number</replaceable></option></term>
221              <listitem>
222               <para>The concurrent <replaceable>number</replaceable> of calls per find node/value request.
223                   (Default is 8.)</para>
224             </listitem>
225           </varlistentry>
226           <varlistentry>
227             <term><option>STORE_REDUNDANCY = <replaceable>number</replaceable></option></term>
228              <listitem>
229               <para>The <replaceable>number</replaceable> of redundant copies of a value to store in the DHT.
230                   (Default is 3.)</para>
231             </listitem>
232           </varlistentry>
233           <varlistentry>
234             <term><option>RETRIEVE_VALUES = <replaceable>number</replaceable></option></term>
235              <listitem>
236               <para>The <replaceable>number</replaceable> of values to attempt to retrieve from the DHT.
237                   Setting this to 0 will try and get all values (which could take a while if
238                   a lot of nodes have values). Setting it negative will try to get that
239                   number of results from only the closest STORE_REDUNDANCY nodes to the hash.
240                   (Default is -10000, which is a large negative number so all values from the closest
241                   STORE_REDUNDANCY nodes will be retrieved.)</para>
242             </listitem>
243           </varlistentry>
244           <varlistentry>
245             <term><option>MAX_FAILURES = <replaceable>number</replaceable></option></term>
246              <listitem>
247               <para>The <replaceable>number</replaceable> of times in a row a node can fail to
248                   respond before it's booted from the routing table.
249                   (Default is 3.)</para>
250             </listitem>
251           </varlistentry>
252           <varlistentry>
253             <term><option>MIN_PING_INTERVAL = <replaceable>time</replaceable></option></term>
254              <listitem>
255               <para>The minimum <replaceable>time</replaceable> to wait before re-pinging a node.
256                   (Default is 15 minutes.)</para>
257             </listitem>
258           </varlistentry>
259           <varlistentry>
260             <term><option>BUCKET_STALENESS = <replaceable>time</replaceable></option></term>
261              <listitem>
262               <para>The maximum <replaceable>time</replaceable> to wait before refreshing a bucket.
263                   (Default is 1 hour.)</para>
264             </listitem>
265           </varlistentry>
266           <varlistentry>
267             <term><option>LOCAL_OK = <replaceable>boolean</replaceable></option></term>
268              <listitem>
269               <para>Whether it's OK to add nodes to the routing table that use an IP address
270                 from a known local or private range.
271                 (Default is to use the value specified in the DEFAULT section.)</para>
272             </listitem>
273           </varlistentry>
274           <varlistentry>
275             <term><option>KEY_EXPIRE = <replaceable>time</replaceable></option></term>
276              <listitem>
277               <para>The <replaceable>time</replaceable> to wait before expiring unrefreshed keys.
278                   (Default is 3 hours.)</para>
279             </listitem>
280           </varlistentry>
281           <varlistentry>
282             <term><option>KRPC_TIMEOUT = <replaceable>time</replaceable></option></term>
283              <listitem>
284               <para>The <replaceable>time</replaceable> to wait before KRPC requests timeout.
285                   (Default is 9 seconds.)</para>
286             </listitem>
287           </varlistentry>
288           <varlistentry>
289             <term><option>KRPC_INITIAL_DELAY = <replaceable>time</replaceable></option></term>
290              <listitem>
291               <para>The <replaceable>time</replaceable> to start with when resending KRPC requests using exponential backoff.
292                   The request will first be resent after the delay set here.
293                   The request will be resent again after twice the delay set here, and so on.
294                   e.g. if TIMEOUT is 9 sec., and INITIAL_DELAY is 2 sec., then requests will
295                   be resent at times 0, 2 (2 sec. later), and 6 (4 sec. later), and then will
296                   timeout at 9. (Default is 2 seconds.)</para>
297             </listitem>
298           </varlistentry>
299           <varlistentry>
300             <term><option>SPEW = <replaceable>boolean</replaceable></option></term>
301              <listitem>
302               <para>Whether to log lots of info about the requests and responses in the protocol.
303                 (Default is false)</para>
304             </listitem>
305           </varlistentry>
306         </variablelist>
307      </refsect2>
308   </refsect1>
309
310   <refsect1>
311     <title>SEE ALSO</title>
312
313     <para>
314       <citerefentry><refentrytitle>apt-p2p</refentrytitle><manvolnum>8</manvolnum></citerefentry>
315     </para>
316   </refsect1>
317   <refsect1>
318     <title>AUTHOR</title>
319     <para>This manual page was written by &dhusername; &lt;&dhemail;> for
320       the &debian; system (but may be used by others).  Permission is
321       granted to copy, distribute and/or modify this document under
322       the terms of the &gnu; General Public License, Version 2 or any
323       later version published by the Free Software Foundation.
324     </para>
325     <para>
326       On Debian systems, the complete text of the GNU General Public
327       License can be found in /usr/share/common-licenses/GPL.
328     </para>
329   </refsect1>
330 </refentry>
331
332 <!-- Keep this comment at the end of the file
333 Local variables:
334 mode: sgml
335 sgml-omittag:t
336 sgml-shorttag:t
337 sgml-minimize-attributes:nil
338 sgml-always-quote-attributes:t
339 sgml-indent-step:2
340 sgml-indent-data:t
341 sgml-parent-document:nil
342 sgml-default-dtd-file:nil
343 sgml-exposed-tags:nil
344 sgml-local-catalogs:nil
345 sgml-local-ecat-files:nil
346 End:
347 -->