Documentation.

10 files changed, 79 insertions, 61 deletions

diff --git a/README.mkd b/README.mkd
index 0c190279..abd52eed 100644
--- a/README.mkd
+++ b/README.mkd
@@ -1,10 +1,9 @@
-
 __mitmproxy__ and __mitmdump__ are SSL-capable, intercepting HTTP proxies.
 
 __mitmproxy__ provides a curses interface that allows traffic to be inspected
 and edited on the fly.
 
-__mitmdump__ is a tcpdump-like tool for HTTP.
+__mitmdump__ is the command-line companion of mitmproxy - like tcpdump for HTTP.
 
 
 Capabilities
@@ -18,7 +17,6 @@ Capabilities
 - Dummy SSL certificate authority creates interception certificates on the fly.
 
 
-
 Download
 ========
 
diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html
index e69de29b..16d3f611 100644
--- a/doc-src/certinstall/windows7.html
+++ b/doc-src/certinstall/windows7.html
@@ -0,0 +1,21 @@
+
+<p> Here's a quick and easy procedure you can use for Windows 7, as long as
+the app in question uses the global Windows certificate repository. </p>
+
+<ul>
+
+    <li> Fire up MITMProxy, and configure Firefox on the Windows box to use
+    it. Browse to the target domain, and you should see a big warning about
+    an untrusted certificate. Use Firefox to export the certificate ("Add
+    Exception", "Get Certificate", then "View", tab to "Details" and click
+    "Export").  </li>
+
+    <li> From the command console, fire up <b>certmgr</b>. Select "Trusted
+    Root Certification Authorities", then on the top menu, "Action", "All
+    Tasks", and "Import". When prompted, select the certificate file you've
+    just saved from Firefox.</li>
+
+    <li> And that's it - your certificate should now be trusted for that
+    domain. Happy pentesting.</li>
+
+</ul>
diff --git a/doc-src/clientreplay.html b/doc-src/clientreplay.html
new file mode 100644
index 00000000..efc632f6
--- /dev/null
+++ b/doc-src/clientreplay.html
@@ -0,0 +1,11 @@
+
+Client-side replay does what it says on the tin: you provide a previously saved
+HTTP conversation, and mitmproxy replays the client requests one by one. Note
+that mitmproxy serializes the requests, waiting for a response from the server
+before starting the next request. This might differ from the recorded
+conversation, where requests may have been made concurrently.
+
+You may want to use client-side replay in conjunction with the __anticache__
+option. This will modify requests to remove headers (e.g.  if-modified-since)
+that might cause a server to reply with a 304-not-modified.
+
diff --git a/doc-src/faq.html b/doc-src/faq.html
index 769227bd..daca2b82 100644
--- a/doc-src/faq.html
+++ b/doc-src/faq.html
@@ -5,55 +5,5 @@
 
     Coming soon.
 
-    <p class="question">I'm pentesting an non-browser app that checks SSL
-    certificate validity. How do I make it trust the MITMProxy certificate?</p>
-
-
-    <p> Here's a quick and easy procedure you can use for Windows 7, as long as
-    the app in question uses the global Windows certificate repository. </p>
-
-    <ul>
-
-        <li> First copy the file <b>libmproxy/resources/bogus_template</b>
-        from the MITMProxy source, and edit it to include your target domain in
-        the CN parameter. The result should look like this:
-
-<pre>[ req ]
-prompt = no
-distinguished_name = req_distinguished_name
-
-[ req_distinguished_name ]
-C               = NZ
-ST              = none
-L               = none
-O               = none
-OU              = none
-CN              = target.domain.com
-emailAddress    = none</pre>
-        </li>
-
-        <li> Next, use your bogus template to generate a certificate, and
-        install it for MITMPRoxy to use:
-
-<pre>openssl req -config ./my_bogus_template -x509 -nodes -days 9999 -newkey rsa:1024 -keyout mycert -out mycert
-
-cp mycert ~/.mitmproxy/cert.pem</pre>
-        </li>
-
-        <li> Fire up MITMProxy, and configure Firefox on the Windows box to use
-        it. Browse to the target domain, and you should see a big warning about
-        an untrusted certificate. Use Firefox to export the certificate ("Add
-        Exception", "Get Certificate", then "View", tab to "Details" and click
-        "Export").  </li>
-
-        <li> From the command console, fire up <b>certmgr</b>. Select "Trusted
-        Root Certification Authorities", then on the top menu, "Action", "All
-        Tasks", and "Import". When prompted, select the certificate file you've
-        just saved from Firefox.</li>
-
-        <li> And that's it - your certificate should now be trusted for that
-        domain. Happy pentesting.</li>
-
-    </ul>
 
 </div>
diff --git a/doc-src/index.html b/doc-src/index.html
index 8110bf79..406cb6d0 100644
--- a/doc-src/index.html
+++ b/doc-src/index.html
@@ -1,11 +1,15 @@
 
 
 * [Introduction](@!urlTo("intro.html")!@)
-* [mitmproxy](@!urlTo("/mitmproxy.html")!@)
-* [mitmdump](@!urlTo("/mitmdump.html")!@)
-* [Client script API](@!urlTo("scripts.html")!@)
-* [libmproxy](@!urlTo("library.html")!@)
-* [SSL](@!urlTo("/ssl.html")!@)
+* Concepts
+    * [Client-side replay](@!urlTo("clientreplay.html")!@)
+    * [Server-side replay](@!urlTo("serverreplay.html")!@)
+    * [Sticky cookies](@!urlTo("scripts.html")!@)
+    * [Scripting API](@!urlTo("scripts.html")!@)
+    * [Anticache](@!urlTo("scripts.html")!@)
+    * [Filter expressions](@!urlTo("scripts.html")!@)
+* SSL
+    * [Overview](@!urlTo("/ssl.html")!@)
     * Browser certificate installation: 
         * [Firefox](@!urlTo("certinstall/firefox.html")!@#firefox)
         * [Chrome](@!urlTo("certinstall/chrome.html")!@#chrome)
@@ -14,6 +18,7 @@
     * System-wide certificate installation:
         * [Windows 7](@!urlTo("certinstall/windows7.html")!@#windows7)
         * [iPhone/iPad](@!urlTo("certinstall/ios.html")!@#ios)
+* [libmproxy](@!urlTo("library.html")!@)
 * Tutorials
     * Client replay: a 30 second example
     * Scripting: On-the-fly modifications to HTTP conversations [coming soon]
diff --git a/doc-src/index.py b/doc-src/index.py
index 35f55811..f3bcbffd 100644
--- a/doc-src/index.py
+++ b/doc-src/index.py
@@ -30,8 +30,8 @@ ns.example = example
 pages = [
     Page("index.html", "Index"),
     Page("intro.html", "Introduction"),
-    Page("mitmproxy.html", "mitmproxy"),
-    Page("mitmdump.html", "mitmdump"),
+    Page("clientreplay.html", "Client-side replay"),
+    Page("serverreplay.html", "Server-side replay"),
     Page("scripts.html", "External scripts"),
     Page("library.html", "libmproxy: mitmproxy as a library"),
     Page("ssl.html", "SSL"),
diff --git a/doc-src/mitmdump.html b/doc-src/mitmdump.html
deleted file mode 100644
index e69de29b..00000000
--- a/doc-src/mitmdump.html
+++ /dev/null
diff --git a/doc-src/mitmproxy.html b/doc-src/mitmproxy.html
deleted file mode 100644
index e69de29b..00000000
--- a/doc-src/mitmproxy.html
+++ /dev/null
diff --git a/doc-src/serverreplay.html b/doc-src/serverreplay.html
new file mode 100644
index 00000000..b97167a8
--- /dev/null
+++ b/doc-src/serverreplay.html
@@ -0,0 +1,34 @@
+
+Server-side replay lets us replay server responses from a saved HTTP
+conversation.
+
+Matching requests with responses
+--------------------------------
+
+By default, the __mitm*__ tools match incoming requests with responses from the
+save file based on all request parameters, except the request headers. This
+works in most circumstances, and makes it possible to replay server responses
+in situations where request headers would naturally vary, e.g. using a
+different user agent. The __--rheader__ option to both __mitmproxy__ and
+__mitmdump__ allows you to specify individual headers that should be included
+in the matching process.
+
+
+Response refreshing
+-------------------
+
+Simply replaying server responses without modification will often result in
+unexpected behaviour. For example cookie timeouts that were in the future at
+the time a conversation was recorded might be in the past at the time it is
+replayed. By default, the __mitm*__ tools refresh server responses before
+sending them to the client. The __date__, __expires__ and __last-modified__
+headers are all updated to have the same relative time offset as they had at
+the time of recording. So, if they were in the past at the time of recording,
+they will be in the past at the time of replay, and vice versa. Cookie expiry
+times are updated in a similar way.
+
+You can turn off response refreshing using the __norefresh__ option, available
+both on the command-line and using the "options" keyboard shortcut within
+__mitmproxy__.
+
+
diff --git a/todo b/todo
index db47735c..cf964cc8 100644
--- a/todo
+++ b/todo
@@ -10,5 +10,4 @@ Futures:
 Bugs:
     
     - In some circumstances, long URLs in list view are line-broken oddly.
-    - Termination sometimes hangs.
     - When a bug in mitmproxy causes a stack trace, we hang on exit.