From 98a7aaca182ce6b879329bbaeb06efca284c6220 Mon Sep 17 00:00:00 2001
From: Aldo Cortesi <aldo@nullcube.com>
Date: Fri, 5 Aug 2011 10:23:32 +1200
Subject: Documentation.

---
 README.mkd                          | 11 +++----
 doc-src/02-docstyle.css             |  9 ++++++
 doc-src/anticache.html              |  3 ++
 doc-src/clientreplay.html           |  9 ++++--
 doc-src/index.html                  |  4 ---
 doc-src/index.py                    |  1 -
 doc-src/library.html                |  2 +-
 doc-src/mitmdump.html               | 44 +++++++++++++++++++++++++++
 doc-src/mitmproxy.html              | 60 +++++++++++++++++++++++++++++++------
 doc-src/mitmproxy/encodings.html    |  0
 doc-src/mitmproxy/index.py          |  6 ----
 doc-src/mitmproxy/interception.html | 38 -----------------------
 doc-src/scripts.html                |  2 +-
 doc-src/serverreplay.html           | 15 +++++-----
 doc-src/sticky.html                 | 22 ++++++++++----
 examples/add_header.py              |  8 +++++
 examples/simple_script              |  6 ----
 examples/stickycookies              | 35 ++++++++++++++++++++++
 examples/stickycookies.py           | 34 ---------------------
 19 files changed, 188 insertions(+), 121 deletions(-)
 delete mode 100644 doc-src/mitmproxy/encodings.html
 delete mode 100644 doc-src/mitmproxy/index.py
 delete mode 100644 doc-src/mitmproxy/interception.html
 create mode 100644 examples/add_header.py
 delete mode 100755 examples/simple_script
 create mode 100755 examples/stickycookies
 delete mode 100644 examples/stickycookies.py

diff --git a/README.mkd b/README.mkd
index 764c5a36..e46ca9da 100644
--- a/README.mkd
+++ b/README.mkd
@@ -1,12 +1,13 @@
 
-__mitmproxy__ is an SSL-capable, intercepting HTTP proxy. It provides a console
-interface that allows traffic flows to be inspected and edited on the fly.
+__mitmproxy__ is an SSL-capable man-in-the-middle proxy for HTTP. It provides a
+console interface that allows traffic flows to be inspected and edited on the
+fly.
 
 __mitmdump__ is the command-line version of mitmproxy, with the same
 functionality but without the frills. Think tcpdump for HTTP.
 
-Both tools are fully documentented in the commandline __--help__ flag, and, in
-the case of __mitmproxy__, a built-in help page accessible through the __?__
+Both tools are fully documentented in the commandline _--help_ flag, and, in
+the case of __mitmproxy__, a built-in help page accessible through the _?_
 keyboard shortcut.
 
 
@@ -37,7 +38,7 @@ Requirements
 ------------
 
 * [Python](http://www.python.org) 2.6.x or 2.7.x.
-* [openssl](http://www.openssl.org/). Installed by default on most systems.
+* [openssl](http://www.openssl.org/) - installed by default on most systems.
 * [urwid](http://excess.org/urwid/) version 0.9.8 or newer.
 * The test suite uses the [pry](http://github.com/cortesi/pry) unit testing
   library.
diff --git a/doc-src/02-docstyle.css b/doc-src/02-docstyle.css
index 7a7f49a4..eee82c58 100644
--- a/doc-src/02-docstyle.css
+++ b/doc-src/02-docstyle.css
@@ -56,6 +56,13 @@ a {
     margin: 1em 0;
 }
 
+/* Keyboard shortcuts */
+#bd em {
+    font-weight: bold;
+    color: #04B404; 
+    font-style: normal;
+}
+
 #ft.doc {
     color: #aaa;
     border-top: 1px solid #aaa;
@@ -111,3 +118,5 @@ li a {
 .highlight {
     font-size: 14px;
 }
+
+
diff --git a/doc-src/anticache.html b/doc-src/anticache.html
index a4d76e47..79f0683d 100644
--- a/doc-src/anticache.html
+++ b/doc-src/anticache.html
@@ -1,4 +1,7 @@
 
+- command-line: _--anticache_ 
+- mitmproxy shortcut: _o_, then _a_
+
 When the __anticache__ option is passed to mitmproxy, it removes headers
 (__if-none-match__ and __if-modified-since__) that might elicit a
 304-not-modified response from the server. This is useful when you want to make
diff --git a/doc-src/clientreplay.html b/doc-src/clientreplay.html
index efc632f6..d4b1c3ff 100644
--- a/doc-src/clientreplay.html
+++ b/doc-src/clientreplay.html
@@ -1,11 +1,14 @@
 
+- command-line: _-c path_ 
+- mitmproxy shortcut: _c_
+
 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.
+You may want to use client-side replay in conjunction with the
+[anticache](@!urlTo("anticache.html")!@) option. 
+
 
diff --git a/doc-src/index.html b/doc-src/index.html
index 61a033be..4638b091 100644
--- a/doc-src/index.html
+++ b/doc-src/index.html
@@ -2,10 +2,6 @@
 <ul class="docindex">
     <li><a href="@!urlTo("intro.html")!@">Introduction</a></li>
     <li><a href="@!urlTo("mitmproxy.html")!@">mitmproxy</a></li>
-        <ul>
-            <li><a href="@!urlTo("mitmproxy/interception.html")!@">Interception</a></li>
-            <li><a href="@!urlTo("mitmproxy/encodings.html")!@">Dealing with encodings</a></li>
-        </ul>
     <li><a href="@!urlTo("mitmdump.html")!@">mitmdump</a></li>
     <li>Concepts</li>
     <ul>
diff --git a/doc-src/index.py b/doc-src/index.py
index f98c2dcd..05254234 100644
--- a/doc-src/index.py
+++ b/doc-src/index.py
@@ -69,7 +69,6 @@ pages = [
     Page("index.html", "docs"),
     Page("intro.html", "Introduction"),
     Page("mitmproxy.html", "mitmproxy"),
-    Directory("mitmproxy"),
     Page("mitmdump.html", "mitmdump"),
     Page("clientreplay.html", "Client-side replay"),
     Page("serverreplay.html", "Server-side replay"),
diff --git a/doc-src/library.html b/doc-src/library.html
index 5b19b61f..e2d2ff6a 100644
--- a/doc-src/library.html
+++ b/doc-src/library.html
@@ -8,5 +8,5 @@ this lets you log in to a site using your browser, and then make subsequent
 requests using a tool like __curl__, which will then seem to be part of the
 authenticated session.
 
-$!example("examples/stickycookies.py")!$
+$!example("examples/stickycookies")!$
 
diff --git a/doc-src/mitmdump.html b/doc-src/mitmdump.html
index e69de29b..4d0683ea 100644
--- a/doc-src/mitmdump.html
+++ b/doc-src/mitmdump.html
@@ -0,0 +1,44 @@
+
+__mitmdump__ is the command-line companion to mitmproxy. It provides
+tcpdump-like functionality to let you view, record, and programmatically
+transform HTTP traffic. See the _--help_ flag ouptut for complete
+documentation.
+
+
+
+## Example: saving traffic
+
+    mitmdump -w outfile
+
+Start up mitmdump in proxy mode, and write all traffic to __outfile__. 
+
+
+## Example: client replay
+
+    mitmdump -nc outfile
+
+Start mitmdump without binding to the proxy port (_-n_), then replay all
+requests from outfile (_-c filename_). Flags combine in the obvious way, so
+you can replay requests from one file, and write the resulting flows to
+another:
+
+    mitmdump -nc srcfile -w dstfile
+
+See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
+
+
+## Example: running a script
+
+    mitmdump -s examples/add_header.py
+
+This runs the __add_header.py__ example script, which simply adds a new header
+to all responses.
+
+
+## Example: scripted data transformation
+
+    mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+
+This command loads flows from __srcfile__, transforms it according to the
+specified script, then writes it back to __dstfile__.
+
diff --git a/doc-src/mitmproxy.html b/doc-src/mitmproxy.html
index da4c2a82..ef0b242d 100644
--- a/doc-src/mitmproxy.html
+++ b/doc-src/mitmproxy.html
@@ -1,16 +1,58 @@
 
 __mitmproxy__ is a console tool that allows interactive examination and
-modification of HTTP traffic. 
+modification of HTTP traffic. The _?_ shortcut key shows complete documentation
+on __mitmproxy__'s functionality.
 
-## Connection list
+
+## The interface: connection list
 
 <img src="@!urlTo("screenshots/mitmproxy.png")!@"/>
 
 
-- Looking at the connection list, we can see that we visited __gmail.com__,
-which then returned a 301 redirect.
-- The statusbar tells us that there are 11 flows in the list, and that we're
-currently using the "pretty" view mode.
-- Also visible is the __Event log__, which can be toggled on and off with the
-__v__ keyboard shortcut. This displays events like client connection
-information, errors, and script output.
+The connection list shows an index of captured flows in chronological order.
+So, in this case, we can we can see that we visited __gmail.com__, which then
+returned a 301 redirect to mail.google.com.
+
+The statusbar at the bottom tells us that there are 11 flows in the view, that
+we are using the "pretty" view mode (more on that below), and that the proxy is
+bound to port 8080 of all interfaces.
+
+Also visible is the __Event log__, which can be toggled on and off with the _v_
+keyboard shortcut. This displays events like client connection information,
+errors, and script output.
+
+
+## Example: Interception
+
+__mitmproxy__'s interception functionality lets you pause an HTTP request or
+response, inspect and modify it, and then accept it to send it on to the server
+or client. 
+
+
+### 1: Set an interception pattern
+
+<img src="@!urlTo('intercept-filt.png')!@"/>
+
+We press _i_ to set an interception pattern. In this case, the __~q__ filter
+pattern tells __mitmproxy__ to intercept all requests. For complete filter
+syntax, see the [Filter expressions](@!urlTo("filters.html")!@) section of this
+document, or the built-in help function in __mitmproxy__.
+
+### 2: Intercepted connections are indicated with a red exclamation mark:
+
+<img src="@!urlTo('intercept-mid.png')!@"/>
+
+### 3: You can now view and modify the request:
+
+<img src="@!urlTo('intercept-options.png')!@"/>
+
+In this case, we viewed the request by selecting it, pressed _e_ for "edit"
+and _m_ for "method" to change the HTTP request method.
+
+### 4: Accept the intercept to continue
+
+<img src="@!urlTo('intercept-result.png')!@"/>
+
+Finally, we press _a_ to accept the modified request, which is then sent on to
+the server. In this case, we changed the request from an HTTP GET to to
+OPTIONS, and Google's server has responded with a 405 "Method not allowed". 
diff --git a/doc-src/mitmproxy/encodings.html b/doc-src/mitmproxy/encodings.html
deleted file mode 100644
index e69de29b..00000000
diff --git a/doc-src/mitmproxy/index.py b/doc-src/mitmproxy/index.py
deleted file mode 100644
index 889f039c..00000000
--- a/doc-src/mitmproxy/index.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from countershape import Page
-
-pages = [
-    Page("interception.html", "Interception"),
-    Page("encodings.html", "Dealing with encodings"),
-]
diff --git a/doc-src/mitmproxy/interception.html b/doc-src/mitmproxy/interception.html
deleted file mode 100644
index 2f961b5f..00000000
--- a/doc-src/mitmproxy/interception.html
+++ /dev/null
@@ -1,38 +0,0 @@
-
-__mitmproxy__'s interception functionality lets you pause an HTTP request or
-response, inspect and modify it, and then accept it to send it on to the server
-or client. Because this is an interactive function, it's only present in
-__mitmproxy__, not in __mitmdump__. 
-
-
-### 1: Set an interception pattern
-
-<img src="@!urlTo('intercept-filt.png')!@"/>
-
-We press __i__ to set an interception pattern. In this case, the __~q__ filter
-pattern tells __mitmproxy__ to intercept all requests. For complete filter
-syntax, see the [Filter expressions](@!urlTo("filters.html")!@) section of this
-document, or the built-in help function in __mitmproxy__.
-
-### 2: Intercepted connections are indicated with a red exclamation mark:
-
-<img src="@!urlTo('intercept-mid.png')!@"/>
-
-### 3: You can now view and modify the request:
-
-<img src="@!urlTo('intercept-options.png')!@"/>
-
-In this case, we viewed the request by selecting it, pressed __e__ for "edit"
-and __m__ for "method" to change the HTTP request method.
-
-### 4: Accept the intercept to continue
-
-<img src="@!urlTo('intercept-result.png')!@"/>
-
-Finally, we press __a__ to accept the modified request, which is then sent on
-to the server. In this case, we changed the request from an HTTP GET to to
-OPTIONS, and Google's server has responded with a 405 "Method not allowed". 
-
-
-
-
diff --git a/doc-src/scripts.html b/doc-src/scripts.html
index 30f52ed8..2514923e 100644
--- a/doc-src/scripts.html
+++ b/doc-src/scripts.html
@@ -8,7 +8,7 @@ The script interface is simple - scripts simply read,
 modify and return a single __libmproxy.flow.Flow__ object, using the methods
 defined in the __libmproxy.script__ module. Scripts must be executable.
 
-$!example("examples/simple_script")!$
+!example("examples/simple_script")!$
 
 
 
diff --git a/doc-src/serverreplay.html b/doc-src/serverreplay.html
index 9f1ae5f2..1282be06 100644
--- a/doc-src/serverreplay.html
+++ b/doc-src/serverreplay.html
@@ -1,4 +1,7 @@
 
+- command-line: _-S path_ 
+- mitmproxy shortcut: _S_
+
 Server-side replay lets us replay server responses from a saved HTTP
 conversation.
 
@@ -8,10 +11,9 @@ Matching requests with responses
 By default, __mitmproxy__ excludes request headers when matching incoming
 requests with responses from the replay file. 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
-override this behaviour by specifying individual headers that should be
-included in matching.
+headers would naturally vary, e.g. using a different user agent. The _--rheader
+headername_ command-line option allows you to override this behaviour by
+specifying individual headers that should be included in matching.
 
 
 Response refreshing
@@ -27,8 +29,7 @@ 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__.
+You can turn off response refreshing using the _--norefresh_ argument, or using
+the _o_ options shortcut within __mitmproxy__.
 
 
diff --git a/doc-src/sticky.html b/doc-src/sticky.html
index b2636890..6208f658 100644
--- a/doc-src/sticky.html
+++ b/doc-src/sticky.html
@@ -1,5 +1,11 @@
 
-When the __stickycookie__ option is set, __mitmproxy__ will add the cookie most
+## Sticky cookies
+
+- command-line: _-t_ (sticky cookies on all requests)
+- command-line: _-T filt_ (sticky cookies on requests matching filt)
+- mitmproxy shortcut: _t_
+
+When the sticky cookie option is set, __mitmproxy__ will add the cookie most
 recently set by the server to any cookie-less request. Consider a service that
 sets a cookie to track the session after authentication. Using sticky cookies,
 you can fire up mitmproxy, and authenticate to a service as you usually would
@@ -17,8 +23,12 @@ with the secured resources.
 
 ## Sticky auth
 
-The __stickyauth__ option is analogous to the __stickycookie__ option, in that
-HTTP __Authorization__ headers are simply replayed to the server once they have
-been seen. This is enough to allow you to access a server resource using HTTP
-Basic authentication through the proxy. Note that __mitmproxy__ doesn't (yet)
-support replay of HTTP Digest authentication. 
+- command-line: _-u_ (sticky auth on all requests)
+- command-line: _-U filt_ (sticky auth on requests matching filt)
+- mitmproxy shortcut: _u_
+
+The sticky auth option is analogous to the sticky cookie option, in that HTTP
+__Authorization__ headers are simply replayed to the server once they have been
+seen. This is enough to allow you to access a server resource using HTTP Basic
+authentication through the proxy. Note that __mitmproxy__ doesn't (yet) support
+replay of HTTP Digest authentication. 
diff --git a/examples/add_header.py b/examples/add_header.py
new file mode 100644
index 00000000..dab33c8c
--- /dev/null
+++ b/examples/add_header.py
@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+"""
+    This script adds a new header to all responses.
+"""
+from libmproxy import script
+
+def response(ctx, f):
+    f.response.headers["newheader"] = ["foo"]
diff --git a/examples/simple_script b/examples/simple_script
deleted file mode 100755
index de562163..00000000
--- a/examples/simple_script
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env python
-from libmproxy import script
-
-def response(ctx, f):
-    ctx.log("processing a response")
-    f.response.headers["newheader"] = ["foo"]
diff --git a/examples/stickycookies b/examples/stickycookies
new file mode 100755
index 00000000..1ae0e113
--- /dev/null
+++ b/examples/stickycookies
@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+from libmproxy import controller, proxy
+
+class StickyMaster(controller.Master):
+    def __init__(self, server):
+        controller.Master.__init__(self, server)
+        self.stickyhosts = {}
+
+    def run(self):
+        try:
+            return controller.Master.run(self)
+        except KeyboardInterrupt:
+            self.shutdown()
+
+    def handle_request(self, msg):
+        hid = (msg.host, msg.port)
+        if msg.headers["cookie"]:
+            self.stickyhosts[hid] = msg.headers["cookie"]
+        elif hid in self.stickyhosts:
+            msg.headers["cookie"] = self.stickyhosts[hid]
+        msg._ack()
+
+    def handle_response(self, msg):
+        hid = (msg.request.host, msg.request.port)
+        if msg.headers["set-cookie"]:
+            self.stickyhosts[hid] = f.response.headers["set-cookie"]
+        msg._ack()
+
+
+ssl_config = proxy.SSLConfig(
+    "~/.mitmproxy/cert.pem"
+)
+server = proxy.ProxyServer(ssl_config, 8080)
+m = StickyMaster(server)
+m.run()
diff --git a/examples/stickycookies.py b/examples/stickycookies.py
deleted file mode 100644
index 682fa226..00000000
--- a/examples/stickycookies.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from libmproxy import controller, proxy
-
-class StickyMaster(controller.Master):
-    def __init__(self, server):
-        controller.Master.__init__(self, server)
-        self.stickyhosts = {}
-
-    def run(self):
-        try:
-            return controller.Master.run(self)
-        except KeyboardInterrupt:
-            self.shutdown()
-
-    def handle_request(self, msg):
-        hid = (msg.host, msg.port)
-        if msg.headers["cookie"]:
-            self.stickyhosts[hid] = msg.headers["cookie"]
-        elif hid in self.stickyhosts:
-            msg.headers["cookie"] = self.stickyhosts[hid]
-        msg._ack()
-
-    def handle_response(self, msg):
-        hid = (msg.request.host, msg.request.port)
-        if msg.headers["set-cookie"]:
-            self.stickyhosts[hid] = f.response.headers["set-cookie"]
-        msg._ack()
-
-
-ssl_config = proxy.SSLConfig(
-    "~/.mitmproxy/cert.pem"
-)
-server = proxy.ProxyServer(ssl_config, 8080)
-m = StickyMaster(server)
-m.run()
-- 
cgit v1.2.3