# Options
The mitmproxy tools share a common YAML configuration file
located at ~/.mitmproxy/config.yaml. This file controls options - typed
values that determine the behaviour of mitmproxy. The options mechanism is very
comprehensive - in fact, options control all of mitmproxy’s runtime behaviour.
Most command-line flags are simply aliases for underlying options, and
interactive settings changes made in mitmproxy and mitmweb just change
values in our runtime options store. This means that almost any facet of
mitmproxy’s behaviour can be controlled through options.
The canonical reference for options is the --options flag, which is exposed by
each of the mitmproxy tools. Passing this flag will dump an annotated YAML
configuration to console, which includes all options and their default values.
The options mechanism is extensible - third-party addons can define options that are treated exactly like mitmproxy’s own. This means that addons can also be configured through the central configuration file, and their options will appear in the options editors in interactive tools.
# Tools
Both mitmproxy and mitmweb have built-in editors that let you view and manipulate the complete configuration state of mitmproxy. Values you change interactively have immediate effect in the running instance, and can be made persistent by saving the settings out to a YAML configuration file (please see the specific tool’s interactive help for details on how to do this).
For all tools, options can be set directly by name using the --set
command-line option. Please see the command-line help (--help) for usage.
# Available Options
This list might not reflect what is actually available in your current mitmproxy
environment. For an up-to-date list please use the --options flag for each of
the mitmproxy tools.
| Name | Type | Description |
|---|---|---|
| add_upstream_certs_to_client_chain mitmproxy mitmdump mitmweb |
bool | Add all certificates of the upstream server to the certificate chain that will be served to the proxy client, as extras. Default: False |
| allow_hosts mitmproxy mitmdump mitmweb |
sequence of str | Opposite of --ignore-hosts. Default: [] |
| anticache mitmproxy mitmdump mitmweb |
bool | Strip out request headers that might cause the server to return 304-not-modified. Default: False |
| anticomp mitmproxy mitmdump mitmweb |
bool | Try to convince servers to send us un-compressed data. Default: False |
| block_global mitmproxy mitmdump mitmweb |
bool | Block connections from globally reachable networks, as defined in the IANA special purpose registries. Default: True |
| block_private mitmproxy mitmdump mitmweb |
bool | Block connections from private networks, as defined in the IANA special purpose registries. This option does not affect loopback addresses. Default: False |
| body_size_limit mitmproxy mitmdump mitmweb |
optional str | Byte size limit of HTTP request and response bodies. Understands k/m/g suffixes, i.e. 3m for 3 megabytes. Default: None |
| certs mitmproxy mitmdump mitmweb |
sequence of str | SSL certificates of the form "[domain=]path". The domain may include a wildcard, and is equal to "*" if not specified. The file at path is a certificate in PEM format. If a private key is included in the PEM, it is used, else the default key in the conf dir is used. The PEM file should contain the full certificate chain, with the leaf certificate as the first entry. Default: [] |
| ciphers_client mitmproxy mitmdump mitmweb |
optional str | Set supported ciphers for client connections using OpenSSL syntax. Default: None |
| ciphers_server mitmproxy mitmdump mitmweb |
optional str | Set supported ciphers for server connections using OpenSSL syntax. Default: None |
| client_certs mitmproxy mitmdump mitmweb |
optional str | Client certificate file or directory. Default: None |
| client_replay mitmproxy mitmdump mitmweb |
sequence of str | Replay client requests from a saved file. Default: [] |
| command_history mitmproxy mitmdump mitmweb |
bool | Persist command history between mitmproxy invocations. Default: True |
| confdir mitmproxy mitmdump mitmweb |
str | Location of the default mitmproxy configuration files. Default: ~/.mitmproxy |
| console_default_contentview mitmproxy |
str | The default content view mode. Default: auto Choices: auto, raw, hex, json, xml/html, wbxml, javascript, css, url-encoded, multipart form, image, query, protocol buffer, msgpack |
| console_eventlog_verbosity mitmproxy |
str | EventLog verbosity. Default: info Choices: error, warn, info, alert, debug |
| console_flowlist_layout mitmproxy |
str | Set the flowlist layout Default: default Choices: default, list, table |
| console_focus_follow mitmproxy mitmweb |
bool | Focus follows new flows. Default: False |
| console_layout mitmproxy |
str | Console layout. Default: single Choices: horizontal, single, vertical |
| console_layout_headers mitmproxy |
bool | Show layout component headers Default: True |
| console_mouse mitmproxy |
bool | Console mouse interaction. Default: True |
| console_palette mitmproxy |
str | Color palette. Default: solarized_dark Choices: dark, light, lowdark, lowlight, solarized_dark, solarized_light |
| console_palette_transparent mitmproxy |
bool | Set transparent background for palette. Default: True |
| console_strip_trailing_newlines mitmproxy |
bool | Strip trailing newlines from edited request/response bodies. Default: False |
| content_view_lines_cutoff mitmproxy mitmdump mitmweb |
int | Flow content view lines limit. Limit is enabled by default to speedup flows browsing. Default: 512 |
| dumper_default_contentview mitmdump |
str | The default content view mode. Default: auto Choices: auto, raw, hex, json, xml/html, wbxml, javascript, css, url-encoded, multipart form, image, query, protocol buffer, msgpack |
| dumper_filter mitmdump |
optional str | Limit which flows are dumped. Default: None |
| flow_detail mitmdump |
int | The display detail level for flows in mitmdump: 0 (almost quiet) to 3 (very verbose). 0: shortened request URL, response status code, WebSocket and TCP message notifications. 1: full request URL with response status code 2: 1 + HTTP headers 3: 2 + full response content, content of WebSocket and TCP messages. Default: 1 |
| http2 mitmproxy mitmdump mitmweb |
bool | Enable/disable HTTP/2 support. HTTP/2 support is enabled by default. Default: True |
| http2_priority mitmproxy mitmdump mitmweb |
bool | PRIORITY forwarding for HTTP/2 connections. Disabled by default to ensure compatibility with misbehaving servers. Default: False |
| ignore_hosts mitmproxy mitmdump mitmweb |
sequence of str | Ignore host and forward all traffic without processing it. In transparent mode, it is recommended to use an IP address (range), not the hostname. In regular mode, only SSL traffic is ignored and the hostname should be used. The supplied value is interpreted as a regular expression and matched on the ip or the hostname. Default: [] |
| intercept mitmproxy mitmweb |
optional str | Intercept filter expression. Default: None |
| intercept_active mitmproxy mitmweb |
bool | Intercept toggle Default: False |
| keep_host_header mitmproxy mitmdump mitmweb |
bool | Reverse Proxy: Keep the original host header instead of rewriting it to the reverse proxy target. Default: False |
| keepserving mitmdump |
bool | Continue serving after client playback, server playback or file read. This option is ignored by interactive tools, which always keep serving. Default: False |
| key_size mitmproxy mitmdump mitmweb |
int | TLS key size for certificates and CA. Default: 2048 |
| listen_host mitmproxy mitmdump mitmweb |
str | Address to bind proxy to. Default: |
| listen_port mitmproxy mitmdump mitmweb |
int | Proxy service port. Default: 8080 |
| map_local mitmproxy mitmdump mitmweb |
sequence of str | Map remote resources to a local file using a pattern of the form "[/flow-filter]/url-regex/file-or-directory-path", where the separator can be any character. Default: [] |
| map_remote mitmproxy mitmdump mitmweb |
sequence of str | Map remote resources to another remote URL using a pattern of the form "[/flow-filter]/url-regex/replacement", where the separator can be any character. Default: [] |
| mode mitmproxy mitmdump mitmweb |
str | Mode can be "regular", "transparent", "socks5", "reverse:SPEC", or "upstream:SPEC". For reverse and upstream proxy modes, SPEC is host specification in the form of "http[s]://host[:port]". Default: regular |
| modify_body mitmproxy mitmdump mitmweb |
sequence of str | Replacement pattern of the form "[/flow-filter]/regex/[@]replacement", where the separator can be any character. The @ allows to provide a file path that is used to read the replacement string. Default: [] |
| modify_headers mitmproxy mitmdump mitmweb |
sequence of str | Header modify pattern of the form "[/flow-filter]/header-name/[@]header-value", where the separator can be any character. The @ allows to provide a file path that is used to read the header value string. An empty header-value removes existing header-name headers. Default: [] |
| onboarding mitmproxy mitmdump mitmweb |
bool | Toggle the mitmproxy onboarding app. Default: True |
| onboarding_host mitmproxy mitmdump mitmweb |
str | Onboarding app domain. For transparent mode, use an IP when a DNS entry for the app domain is not present. Default: mitm.it |
| onboarding_port mitmproxy mitmdump mitmweb |
int | Port to serve the onboarding app from. Default: 80 |
| proxyauth mitmproxy mitmdump mitmweb |
optional str | Require proxy authentication. Format: "username:pass", "any" to accept any user/pass combination, "@path" to use an Apache htpasswd file, or "ldap[s]:url_server_ldap:dn_auth:password:dn_subtree" for LDAP authentication. Default: None |
| rawtcp mitmproxy mitmdump mitmweb |
bool | Enable/disable experimental raw TCP support. TCP connections starting with non-ascii bytes are treated as if they would match tcp_hosts. The heuristic is very rough, use with caution. Disabled by default. Default: False |
| readfile_filter mitmproxy mitmdump mitmweb |
optional str | Read only matching flows. Default: None |
| relax_http_form_validation mitmproxy mitmdump mitmweb |
bool | Disable HTTP form validation. Default: False |
| rfile mitmproxy mitmdump mitmweb |
optional str | Read flows from file. Default: None |
| save_stream_file mitmproxy mitmdump mitmweb |
optional str | Stream flows to file as they arrive. Prefix path with + to append. Default: None |
| save_stream_filter mitmproxy mitmdump mitmweb |
optional str | Filter which flows are written to file. Default: None |
| scripts mitmproxy mitmdump mitmweb |
sequence of str | Execute a script. Default: [] |
| server mitmproxy mitmdump mitmweb |
bool | Start a proxy server. Enabled by default. Default: True |
| server_replay mitmproxy mitmdump mitmweb |
sequence of str | Replay server responses from a saved file. Default: [] |
| server_replay_ignore_content mitmproxy mitmdump mitmweb |
bool | Ignore request's content while searching for a saved flow to replay. Default: False |
| server_replay_ignore_host mitmproxy mitmdump mitmweb |
bool | Ignore request's destination host while searching for a saved flow to replay. Default: False |
| server_replay_ignore_params mitmproxy mitmdump mitmweb |
sequence of str | Request's parameters to be ignored while searching for a saved flow to replay. Default: [] |
| server_replay_ignore_payload_params mitmproxy mitmdump mitmweb |
sequence of str | Request's payload parameters (application/x-www-form-urlencoded or multipart/form-data) to be ignored while searching for a saved flow to replay. Default: [] |
| server_replay_ignore_port mitmproxy mitmdump mitmweb |
bool | Ignore request's destination port while searching for a saved flow to replay. Default: False |
| server_replay_kill_extra mitmproxy mitmdump mitmweb |
bool | Kill extra requests during replay. Default: False |
| server_replay_nopop mitmproxy mitmdump mitmweb |
bool | Don't remove flows from server replay state after use. This makes it possible to replay same response multiple times. Default: False |
| server_replay_refresh mitmproxy mitmdump mitmweb |
bool | Refresh server replay responses by adjusting date, expires and last-modified headers, as well as adjusting cookie expiration. Default: True |
| server_replay_use_headers mitmproxy mitmdump mitmweb |
sequence of str | Request headers to be considered during replay. Default: [] |
| showhost mitmproxy mitmdump mitmweb |
bool | Use the Host header to construct URLs for display. Default: False |
| spoof_source_address mitmproxy mitmdump mitmweb |
bool | Use the client's IP for server-side connections. Combine with --upstream-bind-address to spoof a fixed source address. Default: False |
| ssl_insecure mitmproxy mitmdump mitmweb |
bool | Do not verify upstream server SSL/TLS certificates. Default: False |
| ssl_verify_upstream_trusted_ca mitmproxy mitmdump mitmweb |
optional str | Path to a PEM formatted trusted CA certificate. Default: None |
| ssl_verify_upstream_trusted_confdir mitmproxy mitmdump mitmweb |
optional str | Path to a directory of trusted CA certificates for upstream server verification prepared using the c_rehash tool. Default: None |
| ssl_version_client mitmproxy mitmdump mitmweb |
str | Set supported SSL/TLS versions for client connections. SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, which is TLS1.0+. Default: secure Choices: all, secure, SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2 |
| ssl_version_server mitmproxy mitmdump mitmweb |
str | Set supported SSL/TLS versions for server connections. SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, which is TLS1.0+. Default: secure Choices: all, secure, SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2 |
| stickyauth mitmproxy mitmdump mitmweb |
optional str | Set sticky auth filter. Matched against requests. Default: None |
| stickycookie mitmproxy mitmdump mitmweb |
optional str | Set sticky cookie filter. Matched against requests. Default: None |
| stream_large_bodies mitmproxy mitmdump mitmweb |
optional str | Stream data to the client if response body exceeds the given threshold. If streamed, the body will not be stored in any way. Understands k/m/g suffixes, i.e. 3m for 3 megabytes. Default: None |
| stream_websockets mitmproxy mitmdump mitmweb |
bool | Stream WebSocket messages between client and server. Messages are captured and cannot be modified. Default: False |
| tcp_hosts mitmproxy mitmdump mitmweb |
sequence of str | Generic TCP SSL proxy mode for all hosts that match the pattern. Similar to --ignore-hosts, but SSL connections are intercepted. The communication contents are printed to the log in verbose mode. Default: [] |
| termlog_verbosity mitmdump mitmweb |
str | Log verbosity. Default: info Choices: error, warn, info, alert, debug |
| tutorial mitmproxy mitmdump mitmweb |
bool | Toggle the mitmproxy tutorial app. Default: True |
| tutorial_host mitmproxy mitmdump mitmweb |
str | Tutorial app domain. For transparent mode, use an IP when a DNS entry for the app domain is not present. Default: tutorial.mitm.it |
| tutorial_port mitmproxy mitmdump mitmweb |
int | Port to serve the tutorial app from. Default: 80 |
| upstream_auth mitmproxy mitmdump mitmweb |
optional str | Add HTTP Basic authentication to upstream proxy and reverse proxy requests. Format: username:password. Default: None |
| upstream_bind_address mitmproxy mitmdump mitmweb |
str | Address to bind upstream requests to. Default: |
| upstream_cert mitmproxy mitmdump mitmweb |
bool | Connect to upstream server to look up certificate details. Default: True |
| view_filter mitmproxy mitmweb |
optional str | Limit the view to matching flows. Default: None |
| view_order mitmproxy mitmweb |
str | Flow sort order. Default: time Choices: time, method, url, size |
| view_order_reversed mitmproxy mitmweb |
bool | Reverse the sorting order. Default: False |
| web_debug mitmweb |
bool | Enable mitmweb debugging. Default: False |
| web_host mitmweb |
str | Web UI host. Default: 127.0.0.1 |
| web_open_browser mitmweb |
bool | Start a browser. Default: True |
| web_port mitmweb |
int | Web UI port. Default: 8081 |
| web_static_viewer mitmweb |
optional str | The path to output a static viewer. Default: |
| websocket mitmproxy mitmdump mitmweb |
bool | Enable/disable WebSocket support. WebSocket support is enabled by default. Default: True |