From fe4c371001c0c9f1895e3ed6dea7506617b5e3cb Mon Sep 17 00:00:00 2001
From: Aldo Cortesi <aldo@corte.si>
Date: Tue, 15 May 2018 10:07:09 +1200
Subject: docs: split out tool documentation

---
 docs/src/content/_index.md             |   3 +
 docs/src/content/overview-tools.md     | 105 ---------------------------------
 docs/src/content/tools-mitmdump.md     |  70 ++++++++++++++++++++++
 docs/src/content/tools-mitmproxy.md    |  18 ++++++
 docs/src/content/tools-mitmweb.md      |  23 ++++++++
 docs/src/layouts/partials/sidebar.html |   3 +
 6 files changed, 117 insertions(+), 105 deletions(-)
 delete mode 100644 docs/src/content/overview-tools.md
 create mode 100644 docs/src/content/tools-mitmdump.md
 create mode 100644 docs/src/content/tools-mitmproxy.md
 create mode 100644 docs/src/content/tools-mitmweb.md

(limited to 'docs/src')

diff --git a/docs/src/content/_index.md b/docs/src/content/_index.md
index 44d41611..cd368df0 100644
--- a/docs/src/content/_index.md
+++ b/docs/src/content/_index.md
@@ -8,6 +8,9 @@ menu:
 
 # Introduction
 
+The mitmproxy project's tools are a set of front-ends that expose common
+underlying functionality.
+
 **mitmproxy** is an interactive man-in-the-middle proxy for HTTP and HTTPS
 with a console interface.
 
diff --git a/docs/src/content/overview-tools.md b/docs/src/content/overview-tools.md
deleted file mode 100644
index 0200e899..00000000
--- a/docs/src/content/overview-tools.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: "Tools"
-menu: "overview"
-menu:
-    overview:
-        weight: 3
----
-
-# Overview
-
-You should think of the mitmproxy project's tools as a set of front-ends that
-expose the same underlying functionality. We aim to have feature parity across
-all of our tooling, and all tools share a common configuration mechanism and
-most command-line options.
-
-## mitmproxy
-
-{{< figure src="/screenshots/mitmproxy.png" >}}
-
-**mitmproxy** is a console tool that allows interactive examination and
-modification of HTTP traffic. It differs from mitmdump in that all flows are
-kept in memory, which means that it's intended for taking and manipulating
-small-ish samples. Use the `?` shortcut key to view, context-sensitive
-documentation from any **mitmproxy** screen.
-
-
-## mitmweb
-
-{{< figure src="/screenshots/mitmweb.png" >}}
-
-**mitmweb** is mitmproxy's web-based user interface that allows
-interactive examination and modification of HTTP traffic. Like
-mitmproxy, it differs from mitmdump in that all flows are kept in
-memory, which means that it's intended for taking and manipulating
-small-ish samples.
-
-{{% note %}}
-Mitmweb is currently in beta. We consider it stable for all features
-currently exposed in the UI, but it still misses a lot of mitmproxy's
-features.
-{{% /note %}}
-
-
-## mitmdump
-
-**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 output for complete
-documentation.
-
-
-### Example: Saving traffic
-
-{{< highlight bash  >}}
-mitmdump -w outfile
-{{< / highlight >}}
-
-Start up mitmdump in proxy mode, and write all traffic to **outfile**.
-
-### Filtering saved traffic
-
-{{< highlight bash  >}}
-mitmdump -nr infile -w outfile "~m post"
-{{< / highlight >}}
-
-Start mitmdump without binding to the proxy port (`-n`), read all flows
-from infile, apply the specified filter expression (only match POSTs),
-and write to outfile.
-
-### Client replay
-
-{{< highlight bash  >}}
-mitmdump -nc outfile
-{{< / highlight >}}
-
-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:
-
-{{< highlight bash  >}}
-mitmdump -nc srcfile -w dstfile
-{{< / highlight >}}
-
-See the [client-side replay]({{< relref "overview-features#client-side-replay"
->}}) section for more information.
-
-### Running a script
-
-{{< highlight bash  >}}
-mitmdump -s examples/add_header.py
-{{< / highlight >}}
-
-This runs the **add_header.py** example script, which simply adds a new
-header to all responses.
-
-### Scripted data transformation
-
-{{< highlight bash  >}}
-mitmdump -ns examples/add_header.py -r srcfile -w dstfile
-{{< / highlight >}}
-
-This command loads flows from **srcfile**, transforms it according to
-the specified script, then writes it back to **dstfile**.
-
diff --git a/docs/src/content/tools-mitmdump.md b/docs/src/content/tools-mitmdump.md
new file mode 100644
index 00000000..fb6a6c0c
--- /dev/null
+++ b/docs/src/content/tools-mitmdump.md
@@ -0,0 +1,70 @@
+---
+title: "mitmdump"
+menu: "tools"
+menu:
+    tools:
+        weight: 2
+---
+
+## mitmdump
+
+**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 output for complete
+documentation.
+
+
+### Example: Saving traffic
+
+{{< highlight bash  >}}
+mitmdump -w outfile
+{{< / highlight >}}
+
+Start up mitmdump in proxy mode, and write all traffic to **outfile**.
+
+### Filtering saved traffic
+
+{{< highlight bash  >}}
+mitmdump -nr infile -w outfile "~m post"
+{{< / highlight >}}
+
+Start mitmdump without binding to the proxy port (`-n`), read all flows
+from infile, apply the specified filter expression (only match POSTs),
+and write to outfile.
+
+### Client replay
+
+{{< highlight bash  >}}
+mitmdump -nc outfile
+{{< / highlight >}}
+
+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:
+
+{{< highlight bash  >}}
+mitmdump -nc srcfile -w dstfile
+{{< / highlight >}}
+
+See the [client-side replay]({{< relref "overview-features#client-side-replay"
+>}}) section for more information.
+
+### Running a script
+
+{{< highlight bash  >}}
+mitmdump -s examples/add_header.py
+{{< / highlight >}}
+
+This runs the **add_header.py** example script, which simply adds a new
+header to all responses.
+
+### Scripted data transformation
+
+{{< highlight bash  >}}
+mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+{{< / highlight >}}
+
+This command loads flows from **srcfile**, transforms it according to
+the specified script, then writes it back to **dstfile**.
+
diff --git a/docs/src/content/tools-mitmproxy.md b/docs/src/content/tools-mitmproxy.md
new file mode 100644
index 00000000..6505fac4
--- /dev/null
+++ b/docs/src/content/tools-mitmproxy.md
@@ -0,0 +1,18 @@
+---
+title: "mitmproxy"
+menu: "tools"
+menu:
+    tools:
+        weight: 1
+---
+
+## mitmproxy
+
+{{< figure src="/screenshots/mitmproxy.png" >}}
+
+**mitmproxy** is a console tool that allows interactive examination and
+modification of HTTP traffic. It differs from mitmdump in that all flows are
+kept in memory, which means that it's intended for taking and manipulating
+small-ish samples. Use the `?` shortcut key to view, context-sensitive
+documentation from any **mitmproxy** screen.
+
diff --git a/docs/src/content/tools-mitmweb.md b/docs/src/content/tools-mitmweb.md
new file mode 100644
index 00000000..a3205377
--- /dev/null
+++ b/docs/src/content/tools-mitmweb.md
@@ -0,0 +1,23 @@
+---
+title: "mitmweb"
+menu: "tools"
+menu:
+    tools:
+        weight: 3
+---
+
+## mitmweb
+
+{{< figure src="/screenshots/mitmweb.png" >}}
+
+**mitmweb** is mitmproxy's web-based user interface that allows
+interactive examination and modification of HTTP traffic. Like
+mitmproxy, it differs from mitmdump in that all flows are kept in
+memory, which means that it's intended for taking and manipulating
+small-ish samples.
+
+{{% note %}}
+Mitmweb is currently in beta. We consider it stable for all features
+currently exposed in the UI, but it still misses a lot of mitmproxy's
+features.
+{{% /note %}}
diff --git a/docs/src/layouts/partials/sidebar.html b/docs/src/layouts/partials/sidebar.html
index 5ea41c12..2dbec23a 100644
--- a/docs/src/layouts/partials/sidebar.html
+++ b/docs/src/layouts/partials/sidebar.html
@@ -8,6 +8,9 @@
     <p class="menu-label"> Overview </p>
     {{ partial "sidemenu" (dict "ctx" . "menuname" "overview") }}
 
+    <p class="menu-label">Tools</p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "tools") }}
+
     <p class="menu-label">Core concepts</p>
     {{ partial "sidemenu" (dict "ctx" . "menuname" "concepts") }}
 
-- 
cgit v1.2.3


From 2db223decbf2aecb80aa3adc96643e84100bbb22 Mon Sep 17 00:00:00 2001
From: Aldo Cortesi <aldo@corte.si>
Date: Tue, 15 May 2018 10:34:55 +1200
Subject: docs: console key binding docs and example

---
 docs/src/content/tools-mitmproxy.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

(limited to 'docs/src')

diff --git a/docs/src/content/tools-mitmproxy.md b/docs/src/content/tools-mitmproxy.md
index 6505fac4..d3f05aef 100644
--- a/docs/src/content/tools-mitmproxy.md
+++ b/docs/src/content/tools-mitmproxy.md
@@ -16,3 +16,21 @@ kept in memory, which means that it's intended for taking and manipulating
 small-ish samples. Use the `?` shortcut key to view, context-sensitive
 documentation from any **mitmproxy** screen.
 
+### Key binding configuration
+
+Mitmproxy's key bindings can be customized through in the
+`~/.mitmproxy/keys.yaml` file. This file consists of a sequence of maps, with
+the following keys:
+
+* `key` (**mandatory**): The key to bind.
+* `cmd` (**mandatory**): The command to execute when the key is pressed.
+* `context`: A list of contexts in which the key should be bound. By default this is **global** (i.e. the key is bound everywhere). Valid contexts are `chooser`, `commands`, `dataviewer`, `eventlog`, `flowlist`, `flowview`, `global`, `grideditor`, `help`, `keybindings`, `options`.
+* `help`: A help string for the binding which will be shown in the key binding browser.
+
+#### Example
+
+{{< example src="examples/keys.yaml" lang="yaml" >}}
+
+
+
+
-- 
cgit v1.2.3


From 56010ebcb7e3ac175441c6f2d1cbdf12067092ca Mon Sep 17 00:00:00 2001
From: Aldo Cortesi <aldo@corte.si>
Date: Tue, 15 May 2018 10:46:30 +1200
Subject: docs: clarify binary packaage admonition

---
 docs/src/content/overview-installation.md | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/content/overview-installation.md b/docs/src/content/overview-installation.md
index d69805db..62762db4 100644
--- a/docs/src/content/overview-installation.md
+++ b/docs/src/content/overview-installation.md
@@ -51,19 +51,18 @@ command line. The console interface is not supported on native Windows.
 
 ## Self-contained Pre-built Binary Packages
 
-For some platforms we provide pre-built binary packages containing
-ready-to-run executables. This includes a self-contained Python 3
-environment, a recent OpenSSL that support ALPN and HTTP/2, and other
-dependencies that would otherwise we cumbersome to compile and install.
-
-Please be advised that we do not update these binaries after the initial
-release. This means we do not include security-related updates of our
-dependencies in already released mitmproxy versions. If there is a
-severe issue, we might consider releasing a bugfix release of mitmproxy
-and corresponding binary packages.
-
-We only support the latest version of mitmproxy with bugfix and security
-updates through regular minor releases.
+For some platforms we provide pre-built binary packages containing ready-to-run
+executables. This includes a self-contained Python 3 environment, a recent
+OpenSSL that support ALPN and HTTP/2, and other dependencies that would
+otherwise we cumbersome to compile and install.
+
+Dependencies in the binary packages are frozen on release, and can't be updated
+in situ. This means that we necessarily capture any bugs or security issues that
+may be present. We don't generally release new binary packages simply to update
+dependencies (though we may do so if we become aware of a really serious issue).
+If you use our binary packages, please make sure you update regularly to ensure
+that everything remains current.
+
 
 ## Docker Images
 
-- 
cgit v1.2.3