Documentation on the home page

templates/home.html

@@ -1,18 +1,168 @@
-<h2>dn42 peer finder</h2>
+<h1>dn42 peer finder</h1>
 
+<h2>What is this?</h2>
+
+<p>This tool allows you to find "good" peerings for dn42, by measuring the
+latency from various points in the network towards you.</p>
+
+<h2>How does it work?</h2>
+
+<p>
+  <ol>
+    <li>you enter your (Internet) IP address or hostname</li>
+    <li>various routers participating in dn42 will ping you over the Internet</li>
+    <li>after a short while, you get back all the latency results</li>
+    <li>you can then peer with people close to you (low latency)</li>
+  </ol>
+</p>
+
+<p>
 <form action="/submit" method="POST">
 Target:
 <input type="text" name="target" />
 <input type="submit" name="Launch" />
 </form>
+</p>
+
+<h2>Why look at latency?</h2>
+
+<h3>The problem of peering quality</h3>
+
+<p>Determining what is a "good" peering in dn42 is quite difficult: many
+criteria come into play, such as latency, jitter, capacity, packet loss,
+stability, or even the price your ISP will pay (peering vs. transit).</p>
+
+<p>On the other hand, a "bad" peering is easy to picture: if you are in
+Paris and peer with somebody in Australia, then you might end up doing
+Paris → Australia → Hamburg if you want to send packets to Germany.  This
+does not feel very efficient.  People usually solve this problem with
+policy routing (local preference and path-prepending).  But it's still a
+good idea to build good links and avoid terrible links.</p>
+
+<p>Of course, you need to build long-distance links sometimes.  Otherwise,
+dn42 would be made of small, independent islands.  This tool can also help
+you to choose the best long-distance links.</p>
+
+<h3>Looking at latency</h3>
+
+<p>Latency is actually a good enough indicator of "distance".  For
+instance, two machines located at the same ISP are expected to have low
+latency towards each other.  On the other hand, a latency above 200 ms
+usually indicates that the two machines are quite far away geographically
+(but not always).</p>
+
+<p>Additionally, latency can vary widely for long-distance links,
+depending on the quality of transit and peering agreements between ISPs.
+For instance, to reach a specific destination in Singapore from France, we
+have the following latency as of September 2014:</p>
+
+<table>
+  <tr>
+    <th>ISP</th>
+    <th>Latency</th>
+  </tr>
+  <tr>
+    <td>Online</td>
+    <td>177 ms</td>
+  </tr>
+  <tr>
+    <td>tetaneutral.net</td>
+    <td>264 ms</td>
+  </tr>
+  <tr>
+    <td>SFR</td>
+    <td>267 ms</td>
+  </tr>
+  <tr>
+    <td>Free</td>
+    <td>365 ms</td>
+  </tr>
+  <tr>
+    <td>OVH</td>
+    <td>402 ms</td>
+  </tr>
+</table>
+
+<p>Of course, this is only a snapshot, and reflects the situation for a
+specific source and destination.  Still, the latency more than doubles
+depending on the ISP, which in this case strongly favours a peering with
+somebody hosted by Online instead of OVH.</p>
+
+<h3>Situations this tool aims to solve</h3>
 
-<h3>Participate in the measurement network</h3>
+<p>To sum up, this tool can help in several situations:
+  <ol>
+    <li>Detecting when somebody is in the same datacenter as you, so that
+    it's mostly free to peer</li>
+    <li>When you are far from everybody, find the peering with the lowest
+    latency</li>
+  </ol>
+</p>
+
+<p>By building low-latency links in dn42, it's actually possible to have
+lower latency in dn42 than over the Internet, for the same destination
+(it's called <em>detour routing</em>).</p>
+
+
+<h2>I want to participate!</h2>
+
+<p>This tool relies on a pool of workers, all over dn42, that process
+requests, perform ping measurements, and report back the results.  You're
+welcome to add your own machines to the pool!</p>
 
 <p>You need to separately register each computer that will provide
 measurements.  Manual validation is performed for each registration.</p>
 
+<p>The contact information is free-form, and will be shown to users when
+they launch measurements.  This allows users to contact you if they want
+to peer.</p>
+
 <form action="/create/participant" method="POST">
 Machine name (required): <input type="text" name="name" /><br />
 Mean of contacting you, like IRC nick, mail address, ... (optional): <input type="text" name="contact" /><br />
 <input type="submit" name="Register" />
 </form>
+
+
+<h2>Known issues</h2>
+
+<p>
+Current limitations:
+  <ol>
+    <li>Only the average RTT is measured, we should include other simple
+    statistics (jitter, min/max RTT, packet loss)</li>
+    <li>The API is not documented (just look at the code)</li>
+  </ol>
+Unavoidable facts that cannot be fixed:
+  <ol>
+    <li>Latency measured today might be meaningless tomorrow, as routing
+    on the Internet is always changing</li>
+    <li>Low latency does not guarantee high throughput</li>
+  </ol>
+</p>
+
+
+<h2>Source code</h2>
+
+<p>The source code is available <a href="https://code.ffdn.org/zorun/peerfinder">here</a></p>
+
+
+<h2>Privacy</h2>
+
+<p>Privacy for users of this service:
+  <ol>
+    <li>Only participants in the measurement pool have access to your IP
+    address (so that they can ping you, obviously)</li>
+    <li>New participants (see below) are moderated manually</li>
+    <li>Results have an unpredicatble URL.  Of course, if you share the
+    link to the results, anybody can see them.</li>
+  </ol>
+  Privacy for participants in the measurement pool:
+  <ol>
+    <li>Users only get access to the machine name and contact information
+    you provided</li>
+    <li>In particular, users don't get access to your IP address (of
+    course, users can always use tcpdump to see where do the ping requests
+    come from)</lI>
+  </ol>
+</p>