From 3cb459d56daeae8fd2b923c27f39ca5595a50e7b Mon Sep 17 00:00:00 2001 From: Thomas Kriechbaumer Date: Thu, 17 Aug 2017 10:18:05 +0200 Subject: docs++: add individual protocol pages --- docs/features/passthrough.rst | 4 ++-- docs/features/tcpproxy.rst | 31 ------------------------------- docs/index.rst | 10 +++++++++- docs/protocols/http1.rst | 15 +++++++++++++++ docs/protocols/http2.rst | 16 ++++++++++++++++ docs/protocols/tcpproxy.rst | 31 +++++++++++++++++++++++++++++++ docs/protocols/websocket.rst | 17 +++++++++++++++++ docs/scripting/events.rst | 2 +- 8 files changed, 91 insertions(+), 35 deletions(-) delete mode 100644 docs/features/tcpproxy.rst create mode 100644 docs/protocols/http1.rst create mode 100644 docs/protocols/http2.rst create mode 100644 docs/protocols/tcpproxy.rst create mode 100644 docs/protocols/websocket.rst diff --git a/docs/features/passthrough.rst b/docs/features/passthrough.rst index 00462e9d..dbaf3506 100644 --- a/docs/features/passthrough.rst +++ b/docs/features/passthrough.rst @@ -13,7 +13,7 @@ mechanism: away. Note that mitmproxy's "Limit" option is often the better alternative here, as it is not affected by the limitations listed below. -If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcpproxy` +If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcp_proxy` feature. If you want to ignore traffic from mitmproxy's processing because of large response bodies, take a look at the :ref:`streaming` feature. @@ -88,7 +88,7 @@ Here are some other examples for ignore patterns: .. seealso:: - - :ref:`tcpproxy` + - :ref:`tcp_proxy` - :ref:`streaming` - mitmproxy's "Limit" feature diff --git a/docs/features/tcpproxy.rst b/docs/features/tcpproxy.rst deleted file mode 100644 index cba374e3..00000000 --- a/docs/features/tcpproxy.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _tcpproxy: - -TCP Proxy -========= - -In case mitmproxy does not handle a specific protocol, you can exempt -hostnames from processing, so that mitmproxy acts as a generic TCP forwarder. -This feature is closely related to the :ref:`passthrough` functionality, -but differs in two important aspects: - -- The raw TCP messages are printed to the event log. -- SSL connections will be intercepted. - -Please note that message interception or modification are not possible yet. -If you are not interested in the raw TCP messages, you should use the ignore domains feature. - -How it works ------------- - -================== ====================== -command-line ``--tcp HOST`` -mitmproxy shortcut :kbd:`O` then :kbd:`T` -================== ====================== - -For a detailed description how the hostname pattern works, please look at the :ref:`passthrough` -feature. - -.. seealso:: - - - :ref:`passthrough` - - :ref:`streaming` diff --git a/docs/index.rst b/docs/index.rst index 7cf593ff..8dba4d04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,15 @@ mitmweb config +.. toctree:: + :hidden: + :caption: Protocols + + protocols/http1 + protocols/http2 + protocols/websocket + protocols/tcpproxy + .. toctree:: :hidden: :caption: Features @@ -36,7 +45,6 @@ features/streaming features/socksproxy features/sticky - features/tcpproxy features/upstreamproxy features/upstreamcerts diff --git a/docs/protocols/http1.rst b/docs/protocols/http1.rst new file mode 100644 index 00000000..21e68785 --- /dev/null +++ b/docs/protocols/http1.rst @@ -0,0 +1,15 @@ +.. _http1_protocol: + +HTTP/1.0 and HTTP/1.1 +=========================== + +.. seealso:: + + - `RFC7230: HTTP/1.1: Message Syntax and Routing `_ + - `RFC7231: HTTP/1.1: Semantics and Content `_ + +HTTP/1.0 and HTTP/1.1 support in mitmproxy is based on our custom HTTP stack, +which takes care of all semantics and on-the-wire parsing/serialization tasks. + +mitmproxy currently does not support HTTP trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/protocols/http2.rst b/docs/protocols/http2.rst new file mode 100644 index 00000000..b3268ae5 --- /dev/null +++ b/docs/protocols/http2.rst @@ -0,0 +1,16 @@ +.. _http2_protocol: + +HTTP/2 +====== + +.. seealso:: + + - `RFC7540: Hypertext Transfer Protocol Version 2 (HTTP/2) `_ + +HTTP/2 support in mitmproxy is based on the amazing work by the python-hyper +community with the `hyper-h2 `_ +project. It fully encapsulates the internal state of HTTP/2 connections and +provides an easy-to-use event-based API. + +mitmproxy currently does not support HTTP/2 trailers - but if you want to send +us a PR, we promise to take look! diff --git a/docs/protocols/tcpproxy.rst b/docs/protocols/tcpproxy.rst new file mode 100644 index 00000000..77248573 --- /dev/null +++ b/docs/protocols/tcpproxy.rst @@ -0,0 +1,31 @@ +.. _tcp_proxy: + +TCP Proxy / Fallback +==================== + +In case mitmproxy does not handle a specific protocol, you can exempt +hostnames from processing, so that mitmproxy acts as a generic TCP forwarder. +This feature is closely related to the :ref:`passthrough` functionality, +but differs in two important aspects: + +- The raw TCP messages are printed to the event log. +- SSL connections will be intercepted. + +Please note that message interception or modification are not possible yet. +If you are not interested in the raw TCP messages, you should use the ignore domains feature. + +How it works +------------ + +================== ====================== +command-line ``--tcp HOST`` +mitmproxy shortcut :kbd:`O` then :kbd:`T` +================== ====================== + +For a detailed description how the hostname pattern works, please look at the :ref:`passthrough` +feature. + +.. seealso:: + + - :ref:`passthrough` + - :ref:`streaming` diff --git a/docs/protocols/websocket.rst b/docs/protocols/websocket.rst new file mode 100644 index 00000000..85cff3ac --- /dev/null +++ b/docs/protocols/websocket.rst @@ -0,0 +1,17 @@ +.. _websocket_protocol: + +WebSocket +========= + +.. seealso:: + + - `RFC6455: The WebSocket Protocol `_ + - `RFC7692: Compression Extensions for WebSocket `_ + +WebSocket support in mitmproxy is based on the amazing work by the python-hyper +community with the `wsproto `_ +project. It fully encapsulates WebSocket frames/messages/connections and +provides an easy-to-use event-based API. + +mitmproxy fully supports the compression extension for WebSocket messages, +provided by wsproto. diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst index 8f9463ff..9e84dacf 100644 --- a/docs/scripting/events.rst +++ b/docs/scripting/events.rst @@ -211,7 +211,7 @@ TCP Events ---------- These events are called only if the connection is in :ref:`TCP mode -`. So, for instance, TCP events are not called for ordinary HTTP/S +`. So, for instance, TCP events are not called for ordinary HTTP/S connections. .. list-table:: -- cgit v1.2.3