mitmproxy/libpathod/templates/help.html

{% extends "frame.html" %}
{% block body %}  
<!-- Text below generated with "markdown2 README.mkd" -->

<h1>Pathod</h1>

<p>Pathod is a pathological HTTP/S daemon, useful for testing and torturing client
software. At Pathod's core is a small, terse language for crafting HTTP
responses. The simplest way to use Pathod is to fire up the daemon, and specify
the respnse behaviour you want using this language in the request URL. Here's a
minimal example:</p>

<pre><code>http://localhost:9999/p/200
</code></pre>

<p>Everything below the magic "/p/" path component is a response specifier - in
this case just a vanilla 200 OK response. See the docs below to get (much)
fancier. You can also add anchors to the Pathod server that serve a fixed
response whenever a matching URL is requested:</p>

<pre><code>pathod --anchor "/foo=200"
</code></pre>

<p>Here, the part before the "=" is a regex specifying the anchor path, and the
part after is a response specifier.</p>

<p>Pathod also has a nifty built-in web interface, which exposes activity logs,
online help and various other goodies. Try it by visiting the server root:</p>

<pre><code>http://localhost:9999
</code></pre>

<h1>Specifying Responses</h1>

<p>The general form of a response is as follows:</p>

<pre><code>code[MESSAGE]:[colon-separated list of features]
</code></pre>

<p>Here's the simplest possible response specification, returning just an HTTP 200
OK message with no headers and no content:</p>

<pre><code>200
</code></pre>

<p>We can embellish this a bit by specifying an optional custom HTTP response
message (if we don't, Pathod automatically creates an appropriate one). By
default for a 200 response code the message is "OK", but we can change it like
this:</p>

<pre><code>200"YAY"
</code></pre>

<p>The quoted string here is an example of a Value Specifier, a syntax that is
used throughout the Pathod response specification language. In this case, the
quotes mean we're specifying a literal string, but there are many other fun
things we can do. For example, we can tell Pathod to generate 100k of random
ASCII letters instead:</p>

<pre><code>200@100k,ascii_letters
</code></pre>

<p>Full documentation on the value specification syntax can be found in the next
section. </p>

<p>Following the response code specifier is a colon-separateed list of features.
For instance, this specifies a response with a body consisting of 1 megabyte of
random data:</p>

<pre><code>200:b@1m
</code></pre>

<p>And this is the same response with an ETag header added:</p>

<pre><code>200:b@1m:h"Etag"="foo"
</code></pre>

<p>Both the header name and the header value are full value specifiers. Here's the
same response again, but with a 1k randomly generated header name:</p>

<pre><code>200:b@1m:h@1k,ascii_letters="foo"
</code></pre>

<p>A few specific headers have shortcuts, because they're used so often. The
shorcut for the content-type header is "c":</p>

<pre><code>200:b@1m:c"text/json"
</code></pre>

<p>That's it for the basic response definition. Now we can start mucking with the
responses to break clients. One common hard-to-test circumstance is hangs or
slow responses. Pathod has a pause operator that you can use to define
precisely when and how long the server should hang. Here, for instance, we hang
for 120 seconds after sending 50 bytes (counted from the first byte of the HTTP
response):</p>

<pre><code>200:b@1m:p120,50
</code></pre>

<p>If that's not long enough, we can tell Pathod to hang forever:</p>

<pre><code>200:b@1m:p120,f
</code></pre>

<p>Or to send all data, and then hang without disconnecting:</p>

<pre><code>200:b@1m:p120,a
</code></pre>

<p>We can also ask Pathod to hang randomly:</p>

<pre><code>200:b@1m:pr,a
</code></pre>

<p>There is a similar mechanism for dropping connections mid-response. So, we can
tell Pathod to disconnect after sending 50 bytes:</p>

<pre><code>200:b@1m:d50
</code></pre>

<p>Or randomly:</p>

<pre><code>200:b@1m:dr
</code></pre>

<p>All of these features can be combined. Here's a response that pauses twice,
once at 10 bytes and once at 20, then disconnects at 5000:</p>

<pre><code>200:b@1m:p10,10:p20,10:d5000
</code></pre>

<h1>Features</h1>

<h4>hKEY=VALUE</h4>

<p>Set a header. Both KEY and VALUE are full <em>Value Specifiers</em>. </p>

<h4>bVALUE</h4>

<p>Set the body. VALUE is a <em>Value Specifier</em>. When the body is set, Pathod will
automatically set the appropriate Content-Length header.</p>

<h4>cVALUE</h4>

<p>A shortcut for setting the Content-Type header. Equivalent to:</p>

<pre><code>h"Content-Type"=VALUE
</code></pre>

<h4>lVALUE</h4>

<p>A shortcut for setting the Location header. Equivalent to:</p>

<pre><code>h"Content-Type"=VALUE
</code></pre>

<h4>dOFFSET</h4>

<p>Disconnect after OFFSET bytes. The offset can also be "r", in which case Pathod
will disconnect at a random point in the response.</p>

<h4>pSECONDS,OFFSET</h4>

<p>Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause
forever. OFFSET can also be "r" to generate a random offset, or "a" for an
offset just after all data has been sent.</p>

<h1>Value Specifiers</h1>

<p>There are three different flavours of value specification. </p>

<h3>Literal</h3>

<p>Literal values are specified as a quoted strings: </p>

<pre><code>"foo"
</code></pre>

<p>Either single or double quotes are accepted, and quotes can be escaped with
backslashes within the string:</p>

<pre><code>'fo\'o'
</code></pre>

<h3>Files</h3>

<p>You can load a value from a specified file path. To do so, you have to specify
a <em>staticdir</em> option to Pathod on the command-line, like so: </p>

<pre><code>pathod -d ~/myassets
</code></pre>

<p>All paths are relative paths under this directory. File loads are indicated by
starting the value specifier with the left angle bracket:</p>

<pre><code>&lt;my/path
</code></pre>

<p>The path value can also be a quoted string, with the same syntax as literals:</p>

<pre><code>&lt;"my/path"
</code></pre>

<h3>Generated values</h3>

<p>An @-symbol lead-in specifies that generated data should be used. There are two
components to a generator specification - a size, and a data type. By default
Pathod assumes a data type of "bytes". </p>

<p>Here's a value specifier for generating 100 bytes:</p>

<pre><code>@100
</code></pre>

<p>You can use standard suffixes to indicate larger values. Here, for instance, is
a specifier for generating 100 megabytes:</p>

<pre><code>@100m
</code></pre>

<p>The supported suffixes are:</p>

<pre><code>b = 1024**0 (bytes)
k = 1024**1 (kilobytes)
m = 1024**2 (megabytes)
g = 1024**3 (gigabytes)
t = 1024**4 (terabytes)
</code></pre>

<p>Data types are separated from the size specification by a comma. This
specification generates 100mb of ASCII:</p>

<pre><code>@100m,ascii
</code></pre>

<p>Supported data types are:</p>

<pre><code>ascii_letters
ascii_lowercase
ascii_uppercase
digits
hexdigits
letters
lowercase
octdigits
printable
punctuation
uppercase
whitespace
ascii
bytes
</code></pre>

{% endblock %}