==========
TCP proxy
==========

The TCP proxy is a performance-enhancing proxy that greatly increases
throughput in some circumstances. It is helpful when bonding diverse
types of Internet connections, such as ADSL with cable, or when a
connection has high jitter or varying bandwidth. In these situations,
the congestion control feature of TCP often reduces the available
throughput on the bond to a small fraction of the expected throughput.

For example, suppose a bond has a 50 Mbps cable connection and a 15 Mbps
DSL connection. You would expect to see bonded speeds of 60 Mbps or
more. However, depending on the delay and stability of the legs, a
single TCP download may get only 30 Mbps—about half the expected
throughput. The TCP proxy allows a single TCP flow to see the expected
60 Mbps throughput.

The proxy is completely transparent. It requires no configuration on
clients. SSL and other encryption protocols are fully supported. UDP
traffic is ignored.

The proxy intercepts connections from clients and forwards them to a
process on the bonder or aggregator. The data stream is split into a
number of parallel connections over the bond, then combined into the
original stream by the remote node and sent to the destination host.

By default, when the proxy is enabled, all outgoing HTTP and HTTPS
connections use the proxy, including those from the bonder itself.
Incoming HTTP and HTTPS connections to hosts behind the bonder use the
proxy, but incoming connections to the bonder itself are *not* proxied.
This allows the bonder's firewall to filter traffic based on the source
IP address of the incoming connections.


Limitations
------------

The TCP proxy should not be enabled if the bond provides acceptable
performance, due to the following disadvantages:

#. Node CPU and memory loads are increased. Using the TCP proxy
   approximately doubles the CPU used by the node.
#. Latency is increased by a small amount. For this reason, avoid
   enabling ports used by interactive applications (for example, port
   3389 for RDP, 22 for SSH, or 5432 for PostgreSQL).
#. The number of simultaneous sessions is limited. See the "File
   descriptor limit" field below.
#. Troubleshooting network issues becomes more complicated. For example,
   without the TCP proxy, a web browser contacting a non-existent web
   server will eventually show a timeout error. But with the TCP proxy,
   the web browser instead shows a message about a protocol error or
   connection reset.
#. TCP urgent data is not supported. The only well-known protocol to use
   urgent data is Telnet.
#. TCP proxy doesn't work with `private
   WAN <../private-wan/index.html>`__ in versions up to and including
   2016.2.
#. Speed tests from within the management server do not use the TCP
   proxy. If you proxy ports between 32768 and 61000, TCP speed tests
   may not work at all.
#. Outgoing connections that originate on the bonder itself and are bound
   to the bonder's connected IP for a CPE NAT IP will not work through the
   TCP proxy. For example, suppose a bonder has the following configuration:

   * Connected IP 172.16.0.1/24
   * CPE NAT IP 192.0.2.120 with destination NAT IP of 172.16.0.1
     (i.e., the bonder itself)

   In this configuration, connections that originate on the bonder and
   are sourced from 172.16.0.1 that go through the TCP proxy will not work.
   This is a limitation of the TCP proxy and will not affect customer traffic.
   Disabling the :ref:`automatic-source-ip` option on the bonder will circumvent
   this issue if it prevents the bonder from being able to get updates or
   make other TCP requests.
#. TCP Proxy traffic between two bonders on the same aggregator does not work if
   either bond has the TCP proxy enabled.
#. TCP Proxy does not currently support IPv6 traffic.



Configuration options
----------------------

The following configuration options are available on the bond edit page.

Enable TCP proxy
^^^^^^^^^^^^^^^^^

This value is set when `automatically tuning a
bond <performance-tuning/automatic-bond-tuning.html>`__.

When checked, enables the TCP proxy. When enabling the proxy, existing
TCP connections are ignored; only new connections are proxied. When
disabling the proxy, all TCP connections through the proxy are closed.

TCP ports to proxy
^^^^^^^^^^^^^^^^^^^

The TCP ports to send to the proxy. Enter integers separated by commas,
with ranges separated by colons, and without spaces. For example, to
proxy ports 80, 443, and 8000 to 8080, enter 80,443,8000:8080.

Concurrency
^^^^^^^^^^^^

The number of concurrent parallel connections to use between the bonder
and aggregator.

To find the optimal value for this field, run a series of TCP bond speed
tests, varying the concurrency level. Select the lowest concurrency
level that reaches the speed you expect the bond to support.

Values between 4 and 12 are common; values above 16 may actually
decrease performance increase the risk of connections being closed
unexpectedly.

Advanced options
^^^^^^^^^^^^^^^^^

The following fields are visible after you click "Show advanced".

Bridge congestion control algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The TCP congestion control algorithm defines the behaviour of proxied
TCP connections. Currently, there are 14 different algorithms to choose
from when configuring a bond on the management server.
The recommended is BBR.

#. CUBIC
#. BIC
#. CDG
#. Datacenter TCP
#. Hamilton TCP
#. Hybla
#. Illinois
#. Low priority
#. Reno
#. Scalable TCP
#. Vegas
#. Veno
#. Westwood
#. Yeah TCP
#. BBR

For more information on this topic and the various algorithms refer
to https://en.wikipedia.org/wiki/TCP_congestion_control

Depending on the type of traffic going over a bond, it's possible that a
different algorithm could decrease performance, while others might
improve it. If the bond's performance seems to decrease after changing
this field, try restoring the recommended algorithm BBR.

File descriptor limit
^^^^^^^^^^^^^^^^^^^^^^

The number of file descriptors the proxy processes can open. This is
used to avoid exhausting the system-wide file descriptor limit on
aggregators.

This value affects how many sessions the proxy can support at one time.
To find the number of sessions allowed by the file descriptor limit,
divide the limit by the concurrency value + 1. For example, if the file
descriptor limit is 16384 and concurrency is 4, the proxy will not
support more than about 3200 connections even if the CPU and other
resources are capable of handling that many sessions. When the proxy
reaches its file descriptor limit, new connections are not accepted but
existing connections continue uninterrupted.

When changing this value, existing sessions are closed and the proxy is
restarted.

