.. _configuration_escaper:

*******
Escaper
*******

The type for each escaper config is *map*, with two always required keys:

* :ref:`name <conf_escaper_common_name>`, which specify the name of the escaper.
* :ref:`type <conf_escaper_common_type>`, which specify the real type of the escaper, decides how to parse other keys.

There are many types of escaper, each with a section below.

Escapers
========

.. toctree::
   :maxdepth: 1

   comply_audit
   dummy_deny
   direct_fixed
   direct_float
   divert_tcp
   proxy_float
   proxy_http
   proxy_https
   proxy_socks5
   proxy_socks5s
   route_mapping
   route_query
   route_resolved
   route_geoip
   route_select
   route_upstream
   route_client
   route_failover
   trick_float

Common Keys
===========

This section describes the common keys, they may be used by many escapers.

.. _conf_escaper_common_name:

name
----

**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`

Set the name of the escaper.

.. _conf_escaper_common_type:

type
----

**required**, **type**: str

Set the type of the escaper.

.. _conf_escaper_common_shared_logger:

shared_logger
-------------

**optional**, **type**: ascii

Set the escaper to use a logger running on a shared thread.

**default**: not set

.. _conf_escaper_common_resolver:

resolver
--------

**type**: :ref:`metric node name <conf_value_metric_node_name>`

Set the resolver to use for this escaper.

If the specified resolver doesn't exist in configure, a default DenyAll resolver will be used.

.. _conf_escaper_common_resolve_strategy:

resolve_strategy
-----------------

**optional**, **type**: :ref:`resolve strategy <conf_value_resolve_strategy>`

Set the resolve strategy.

.. _conf_escaper_common_tcp_sock_speed_limit:

tcp_sock_speed_limit
--------------------

**optional**, **type**: :ref:`tcp socket speed limit <conf_value_tcp_sock_speed_limit>`

Set speed limit for each tcp socket.

**default**: no limit

tcp_conn_speed_limit
--------------------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use tcp_sock_speed_limit instead

tcp_conn_limit
--------------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use tcp_sock_speed_limit instead

conn_limit
----------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use tcp_sock_speed_limit instead

.. _conf_escaper_common_udp_sock_speed_limit:

udp_sock_speed_limit
--------------------

**optional**, **type**: :ref:`udp socket speed limit <conf_value_udp_sock_speed_limit>`

Set speed limit for each udp socket.

**default**: no limit

udp_relay_speed_limit
---------------------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use udp_sock_speed_limit instead

udp_relay_limit
---------------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use udp_sock_speed_limit instead

relay_limit
-----------

**deprecated**

.. versionchanged:: 1.11.8 deprecated, use udp_sock_speed_limit instead

.. _conf_escaper_common_bind_interface:

bind_interface
--------------

**optional**: **type**: :ref:`interface name <conf_value_interface_name>`

Bind the outgoing socket to a particular device like “eth0”.

**default**: not set

.. versionadded:: 1.9.9

.. _conf_escaper_common_no_ipv4:

no_ipv4
-------

**optional**, **type**: bool

Disable IPv4. This setting should be compatible with :ref:`resolve_strategy <conf_escaper_common_resolve_strategy>`.

**default**: false

.. _conf_escaper_common_no_ipv6:

no_ipv6
-------

**optional**, **type**: bool

Disable IPv6. This setting should be compatible with :ref:`resolve_strategy <conf_escaper_common_resolve_strategy>`.

**default**: false

.. _conf_escaper_common_tcp_connect:

tcp_connect
-----------

**optional**, **type**: :ref:`tcp connect <conf_value_tcp_connect>`

Set tcp connect params.

.. note:: For *direct* type escapers, the user level tcp connect params will be taken to limit the final value.

.. _conf_escaper_common_happy_eyeballs:

happy_eyeballs
--------------

**optional**, **type**: :ref:`happy eyeballs <conf_value_happy_eyeballs>`

Set the HappyEyeballs config.

**default**: default HappyEyeballs config

.. _conf_escaper_common_tcp_misc_opts:

tcp_misc_opts
-------------

**optional**, **type**: :ref:`tcp misc sock opts <conf_value_tcp_misc_sock_opts>`

Set misc tcp socket options.

**default**: not set, nodelay is default enabled

.. _conf_escaper_common_udp_misc_opts:

udp_misc_opts
-------------

**optional**, **type**: :ref:`udp misc sock opts <conf_value_udp_misc_sock_opts>`

Set misc udp socket options.

**default**: not set

.. _conf_escaper_common_default_next:

default_next
------------

**required**, **type**: str

Set the default next escaper for *route* type escapers.

.. _conf_escaper_common_pass_proxy_userid:

pass_proxy_userid
-----------------

**optional**, **type**: bool

Set if we should pass userid (username) to next proxy.

If set, the native basic auth method will be used when negotiation with next proxy, and the username field will be set
to the real username, the password field set to our package name (g3proxy if not forked).

**default**: false

.. note:: This will conflict with the real auth of next proxy.

.. _conf_escaper_common_peer_negotiation_timeout:

peer_negotiation_timeout
------------------------

**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`

Set the negotiation timeout for next proxy peers.

**default**: 10s

.. _conf_escaper_common_extra_metrics_tags:

extra_metrics_tags
------------------

**optional**, **type**: :ref:`static metrics tags <conf_value_static_metrics_tags>`

Set extra metrics tags that should be added to escaper stats and user stats already with escaper tags added.

**default**: not set