howto/benchmark.md

-Will require a test VM (or two?) to hit the caches.
+This procedure documents various benchmarking procedures in use inside
+TPA.
 
-TODO: migrate this to a separate howto?
+[[_TOC_]]
 
-### Common procedure
+# HTTP load testing
 
- 1. punch a hole in the firewall to allow cache2 to access cache1
+## Common procedure
+
+ 1. punch a hole in the firewall to allow the test server to access
+    tested server, in case it is not public yet
 
         iptables -I INPUT -s 78.47.61.104 -j ACCEPT
         ip6tables -I INPUT -s 2a01:4f8:c010:25ff::1 -j ACCEPT
 
- 2. point the blog to cache1 on cache2 in `/etc/hosts`:
+ 2. point the test site (e.g. `blog.torproject.org`) to the tested
+    server on the test server, in `/etc/hosts`:
 
         116.202.120.172	blog.torproject.org
         2a01:4f8:fff0:4f:266:37ff:fe26:d6e1 blog.torproject.org
 
- 3. disable Puppet:
+ 3. disable Puppet on the test server:
  
         puppet agent --disable 'benchmarking requires /etc/hosts override'
 
- 4. launch the benchmark
+ 4. launch the benchmark on the test server
 
-### Siege
+## Siege
 
 Siege configuration sample:
 
@@ -44,7 +49,7 @@ proxy-port = 80
 
 Alternative is to hack `/etc/hosts`.
 
-### apachebench
+## apachebench
 
 Classic commandline:
 
@@ -52,7 +57,7 @@ Classic commandline:
 
 `-X` also doesn't work with ATS, hacked `/etc/hosts`.
 
-### bombardier
+## bombardier
 
 Unfortunately, the [bombardier package in Debian](https://tracker.debian.org/pkg/bombardier) is *not* the HTTP
 benchmarking tool but a commandline game. It's still possible to
@@ -102,7 +107,7 @@ actually *more* than 1000Mbit/s (1158.32Mbit/s). Sometimes the above
 benchmark even gives 152MB/s (1222Mbit/s), way beyond what a regular
 GigE link should be able to provide.
 
-### Other tools
+## Other tools
 
 Siege has trouble going above ~100 concurrent clients because of its
 design (and ulimit) limitations. Its interactive features are also