.. _configuration_escaper_divert_tcp:

divert_tcp
==========

This escaper forwards every TCP stream to another proxy and prepends a PROXY
Protocol v2 header first.

It behaves like a chained TCP proxy escaper, but it always prepends PROXY
Protocol v2 metadata that tells the peer which upstream target should be used.

The PPv2 Type-Values are:

* 0xE0 | Upstream Address

  Target upstream address, encoded in UTF-8 without a trailing ``\\0``.
  This field is always present. The next proxy server should connect to this upstream address.

* 0xE1 | TLS Verify Name

  TLS verification name, encoded in UTF-8 without a trailing ``\\0``.
  This is set only if the TLS handshake starts on our side.

* 0xE2 | Username

  Client username, encoded in UTF-8 without a trailing ``\\0``.
  This is set only if client authentication is enabled on our side.

* 0xE3 | Task ID

  Task ID in UUID binary format. This field is always present.

The following interfaces are supported:

* tcp connect
* http(s) forward

There is no path selection support for this escaper.

The following common keys are supported:

* :ref:`shared_logger <conf_escaper_common_shared_logger>`
* :ref:`resolver <conf_escaper_common_resolver>`, **required** only if *proxy_addr* is domain
* :ref:`resolve_strategy <conf_escaper_common_resolve_strategy>`
* :ref:`tcp_sock_speed_limit <conf_escaper_common_tcp_sock_speed_limit>`
* :ref:`bind_interface <conf_escaper_common_bind_interface>`
* :ref:`no_ipv4 <conf_escaper_common_no_ipv4>`
* :ref:`no_ipv6 <conf_escaper_common_no_ipv6>`
* :ref:`tcp_connect <conf_escaper_common_tcp_connect>`
* :ref:`happy eyeballs <conf_escaper_common_happy_eyeballs>`
* :ref:`tcp_misc_opts <conf_escaper_common_tcp_misc_opts>`
* :ref:`extra_metrics_tags <conf_escaper_common_extra_metrics_tags>`

proxy_addr
----------

**required**, **type**: :external+values:ref:`upstream str <conf_value_upstream_str>` | seq

Set the target proxy address. The default port is ``3128`` and may be omitted.

If a *seq* is used, each element must be a :external+values:ref:`weighted upstream addr <conf_value_weighted_upstream_addr>`.

proxy_addr_pick_policy
----------------------

**optional**, **type**: :external+values:ref:`selective pick policy <conf_value_selective_pick_policy>`

Set the policy used to select the next proxy address.

The key for ketama/rendezvous/jump hash is *<client-ip>[-<username>]-<upstream-host>*.

**default**: random

bind_ipv4
---------

**optional**, **type**: :external+values:ref:`ipv4 addr str <conf_value_ipv4_addr_str>`

Set the bind IP address for IPv4 sockets.

**default**: not set

bind_ipv6
---------

**optional**, **type**: :external+values:ref:`ipv6 addr str <conf_value_ipv6_addr_str>`

Set the bind IP address for IPv6 sockets.

**default**: not set

tcp_keepalive
-------------

**optional**, **type**: :external+values:ref:`tcp keepalive <conf_value_tcp_keepalive>`

Configure TCP keepalive.

User-level TCP keepalive settings are not applied.

**default**: no keepalive set

Example
-------

.. code-block:: yaml

   proxy_addr:
     - addr: divert-a.example.net:3128
       weight: 2.0
     - divert-b.example.net:3128
   proxy_addr_pick_policy: rendezvous
   resolver: default
   tcp_keepalive: 60s