=============
Tunnel Bypass
=============

.. versionadded:: 6.2

Tunnel bypass is a feature which allows customer traffic to be sent and received on
a bonder directly via a leg, bypassing the tunnel and the aggregator.

Traffic bypassing the tunnel will :abbr:`SNAT (Source Network Address
Translation)` using the leg's IP address. As a result, return traffic will
reach the bonder directly instead of via the aggregator.

For a bonder to send traffic that bypasses the tunnel, it must be classified
using packet filters on the bond's classification profile and the legs on the
bond must be configured as available for tunnel bypass. Both of these settings
can be accessed by clicking the "Tunnel Bypass" button located in the row of
bond related buttons on the bond detail page.

.. note::
    Quality of Service is only applied to tunneled traffic.

Traffic Classification
----------------------

Classification profiles are used to specify whether traffic should either enter
or bypass the tunnel. Traffic is matched using packet filters, each of which
specify a target defining where to send the traffic. The first matching filter
takes precedence over any later filters.

If traffic does not match any packet filter, the classification profile's
default target will be used to determine where to send traffic.

.. tip::
    Like Quality of Service Profiles, multiple bonds can share the same
    Classification Profile.

Leg Configuration
-----------------

In addition to being assigned a classification profile that filters traffic into tunnel bypass,
bonds must have at least one leg configured for tunnel bypass before traffic will be routed directly out a leg.
Leg tunnel bypass options are found on the `Tunnel Bypass tab <legs.html#configuring-legs>`__ of the `leg edit modal <legs.html#adding-editing-deleting-legs>`__.

|leg-tunnel-bypass|

By default, legs are configured to not carry tunnel bypass traffic.
Enabling tunnel bypass on a leg will make it a candidate for carrying tunnel bypass traffic.

.. note::
    Bandwidth Adaptation does not take affect on legs being used for tunnel bypass.

Enabled
+++++++++++

    When enabled, the bonder is permitted to use this leg to
    send traffic which bypasses the tunnel.

Priority
+++++++++++

    At most one leg is used for tunnel bypass at any given time.
    As such, a leg's priority is used to define the bond's preference for which leg to send tunnel bypass traffic through.
    Of all active legs on a bond with tunnel bypass enabled and connectivity to the aggregator,
    the leg with the lowest priority is selected for sending tunnel bypass traffic.
    If no such legs are available, tunnel bypass traffic will be sent through the tunnel.

Soft Reserve
+++++++++++++++

    A leg's tunnel bypass soft reserve is a percentage of the leg's configured speed
    to reserve for tunnel bypass traffic **in the event that** tunnel and tunnel bypass traffic are competing for bandwidth.
    The bonder will automatically use rates above this percentage (up to the leg's configured rate-limit),
    provided that it does not compete with the tunnel.
    Similarly, the bonder will use the entirety of this leg for the tunnel,
    provided that it does not compete with bypassed traffic.

Soft Reserve & Tunnel Fallback Examples
------------------------------------------

Consider a bond with two 10x10 legs,
such that tunnel bypass is enabled with a soft reserve of 70% on one leg.

|tunnel-bypass-conf|

When bypassed and tunneled traffic both saturate the bond, the bypass traffic
will be limited to 7 Mbps (70% of leg 1), while the tunnel traffic will be limited
to 13 Mbps (the remaining 30% of leg 1 and all of leg 2).

When only traffic classified for tunnel bypass is being sent or received by
the bonder, the full 10 Mbps configured on leg 1 will be used for that traffic.

When no traffic is bypassing the tunnel and all traffic is tunneled, the bonder
will bond the full 20 Mbps of both legs.

When a bonder cannot bypass the tunnel, which happens if all legs designated
for tunnel bypass go offline, bypass traffic will be treated like regular
tunnel traffic and be sent through the tunnel.
In this case, if leg 1 loses its connection to the aggregator and goes down,
traffic previously bypassing the tunnel will now go into the tunnel while leg 2
is up, since no other legs are enabled for tunnel bypass.

If no legs can reach the aggregator, the tunnel will be considered down and any
classified traffic with a tunnel target will ignore that target and continue
matching other filters.

.. |leg-tunnel-bypass| image:: /attachments/bonds/leg-tunnel-bypass.png
.. |tunnel-bypass-conf| image:: /attachments/bonds/tunnel-bypass-conf.png
