enabling-tcp-routing.html.md.erb

---
title: Enabling and Configuring TCP Routing
owner: CF for VMs Networking
---

<div class="quick-links">
  <ul>
    <li><a href="#overview">Overview of TCP Routing</a></li>
    <li><a href="#architecture">TCP Routing Architecture</a></li>
    <li><a href="#prerequisites">Prerequisites for Enabling TCP Routing</a></li>
    <% if not vars.platform_code == "CF" %>
    <li><a href="#config-tcp">Enable TCP Routing</a></li>
    <% end %>
    <li><a href="#post-deploy">Configure TCP Routing After Deploying <%= vars.app_runtime_abbr %></a></li>
      <ul>
        <li><a href="#configure-domain">Configure <%= vars.app_runtime_abbr %> with Your TCP Domain</a></li>
        <li><a href="#configure-quota">Configure a Quota for TCP Routes</a></li>
      </ul>
    <li><a href="#create-tcp-routes">Create a TCP Route</a></li>
    <li><a href="#modify-ports">Modify TCP Port Reservations</a></li>
    <% if not vars.platform_code == "CF" %>
    <li><a href="#disable-tcp">Disable TCP Routing</a></li>
    <% end %>
  </ul>
</div>

This topic describes what TCP routing is and how to enable it in your <%= vars.app_runtime_full %>
(<%= vars.app_runtime_abbr %>) deployment.


## <a name="overview"></a> Overview of TCP Routing

TCP routing enables developers to run apps that serve requests on non-HTTP TCP protocols.
You can use TCP routing to comply with regulatory requirements to terminate TLS as close
to apps as possible so that packets are not decrypted before reaching the app level.


## <a name="architecture"></a> TCP Routing Architecture

The diagram below shows the layers of network address translation that occur in <%= vars.app_runtime_abbr %>
in support of TCP routing.

![Route Ports](./images/route_ports.png)

The following is an example workflow that includes route ports, back end ports, and app ports:

1. A developer creates a TCP route for their app based on a TCP domain and a route port, and
maps this route to one or more apps. For more information, see [Create a Route]
(../devguide/deploy-apps/routes-domains.html#create-route) in _Configuring Routes and Domains_.

1. Clients make requests to the route. DNS resolves the domain name to the load balancer.

1. The load balancer listens on the port and forwards requests for the domain to the TCP
routers. The load balancer must listen on a range of ports to support multiple TCP route
creation. Additionally, <%= vars.app_runtime_abbr %> must be configured with this range,
so that the platform knows which ports can be reserved when developers create TCP routes.

1. The TCP router can be dynamically configured to listen on the port when the route is mapped
to an app. The domain the request was originally sent to is no longer relevant to the routing
of the request to the app. The TCP router keeps a dynamically updated record of the back
ends for each route port. The back ends represent instances of an app mapped to the route.
The TCP router chooses a back end using a round-robin load balancing algorithm for each new
TCP connection from a client. Because the TCP router is protocol-agnostic, it does not recognize
individual requests, only TCP connections. All client requests transit the same connection
to the selected back end until the client or back end closes the connection. Each subsequent
connection triggers the selection of a back end.

1. Because containers each have their own private network, the TCP router does not have direct
access to app containers. When a container is created for an app instance, a port on the Diego
Cell VM is randomly chosen and iptables are configured to forward requests for this port to
the internal interface on the app container. The TCP router then receives a mapping of the
route port to the Diego Cell IP and port.

1. By default, the Diego Cell only routes requests to port `8080`, the app port, on the app
container internal interface. The app port is the port on which apps must listen. Developers
can use the Cloud Controller API to update the ports an app can receive requests on. For more
information, see [Configuring Apps to Listen on Custom Ports (Beta)](../devguide/custom-ports.html).


## <a name="prerequisites"></a> Prerequisites for Enabling TCP Routing

<%= vars.mutual_tls_tcp %>

Before enabling TCP routing, you must set up networking requirements. To set up networking
requirements:

1. Choose a domain from which your developers are to create TCP routes for their apps. For
example, create a domain which is similar to your app domain but prefixed by the TCP subdomain,
such as `tcp.APP-DOMAIN.com`, where `APP-DOMAIN` is the name of your app domain.

1. Configure DNS to resolve this domain name to the IP address of a highly-available load
balancer that can forward traffic for the domain to the TCP routers. For more information,
see [Domains](../devguide/deploy-apps/routes-domains.html#domains) in _Configuring Routes
and Domains_. If you are operating an environment that does not require high availability,
configure DNS to resolve the TCP domain name you have chosen directly to a single instance
of the TCP router.

1. (Optional) Choose IP addresses for the TCP routers and configure your load balancer to
forward requests for the domain you chose in the first step above to these addresses. Skip
this step if you have configured DNS to resolve the TCP domain name to an instance of the
TCP router. <%= vars.tcp_iaas %>

1. (Optional) Decide how many TCP routes you want to support. For each TCP route, you must
reserve a port. Configure your load balancer to forward the range of ports to the TCP routers.
Skip this step if you have configured DNS to resolve the TCP domain name to an instance of
the TCP router. For more information about configuring port reservations, see [Modify TCP
Port Reservations](#modify-ports) below.

1. <%= partial vars.tcp_port %>


<% if not vars.platform_code == "CF" %>
## <a name="config-tcp"></a> Enable TCP Routing

<%= partial "/#{vars.platform_code.downcase}/core/#{vars.current_major_version.sub('.','-')}/configure-tcp-routing" %>

<% end %>


## <a name="post-deploy"></a> Configure TCP Routing After Deploying <%= vars.app_runtime_abbr %>

After you enable TCP routing and deploy <%= vars.app_runtime_abbr %>, you must add the TCP
shared domain and configure org quotas to enable developers to create TCP routes. To do this,
you must use the Cloud Foundry Command Line Interface (cf CLI) and have an admin user account.

For more information about the cf CLI, see [Using the Cloud Foundry Command Line Interface
(cf CLI)](../cf-cli/index.html).

### <a name="configure-domain"></a> Configure <%= vars.app_runtime_abbr %> with Your TCP Domain

After deploying <%= vars.app_runtime_abbr %>, you must configure <%= vars.app_runtime_abbr %>
with the domain that you configured in [Prerequisites for Enabling TCP Routing](#prerequisites).
This is the domain from which developers create TCP routes.

To configure <%= vars.app_runtime_abbr %> with your TCP domain:

1. List your router groups by running:

    ```
    cf router-groups
    ```
    You should see `default-tcp` as a response.

1. Create a shared domain and associate it with the `default-tcp` router group by running:

    ```
    cf create-shared-domain tcp.APP-DOMAIN.com --router-group default-tcp
    ```
    Where `APP-DOMAIN` is the name of your app domain.

1. Verify that `TCP` appears under `type` next to your TCP domain by running:

    ```
    cf domains
    ```

### <a name="configure-quota"></a> Configure a Quota for TCP Routes

Since TCP route ports are a limited resource in some environments, quotas are configured
to allow creation of zero TCP routes by default. After you deploy <%= vars.app_runtime_abbr %>,
you can increase the maximum number of TCP routes for all orgs or for particular orgs and
spaces. Because you reserve a route port for each TCP route, you manage the quota for route
ports using the `--reserved-route-ports` cf CLI command option. For more information, see
[Creating and Modifying Quota Plans](quota-plans.html).

You can configure quotas for TCP routes in the following ways:

* If you have a default quota that applies to all orgs, you can update it to configure the
number of route ports that can be reserved by each org by running:

    ```
    cf update-quota QUOTA --reserved-route-ports NUMBER-OF-ROUTE-PORTS
    ```
    Where:
    * `QUOTA` is the maximum number of TCP routes you want to allocate to all orgs.
    * `NUMBER-OF-ROUTE-PORTS` is the number of route ports you want to allow each org to
    reserve.

* To create a new quota that governs the number of route ports that can be created in a
particular org:
    1. Target the org for which you want to create the quota by running:

        ```
        cf target -o ORG-NAME
        ```
        Where `ORG-NAME` is the name of the org for which you want to create the quota.
    1. Run:

        ```
        cf create-quota QUOTA --reserved-route-ports NUMBER-OF-ROUTE-PORTS
        ```
        Where:
        * `QUOTA` is the maximum number of TCP routes you want to allocate to particular orgs.
        * `NUMBER-OF-ROUTE-PORTS` is the number of route ports you want to allow each org to
        reserve.

* To create a new quota that governs the number of route ports that can be created in a
particular space:
    1. Target the space for which you want to create the quota by running:

        ```
        cf target -s SPACE-NAME
        ```
        Where `SPACE-NAME` is the name of the space for which you want to create the quota.
    1. Run:

        ```
        cf create-space-quota QUOTA --reserved-route-ports NUMBER-OF-ROUTE-PORTS
        ```
        Where:
        * `QUOTA` is the maximum number of TCP routes you want to allocate to a particular
        space.
        * `NUMBER-OF-ROUTE-PORTS` is the number of route ports you want to allow the space
        to reserve.


## <a name="create-tcp-route"></a> Create a TCP Route

For information about creating a TCP route, see [Create a TCP Route with a Port]
(../devguide/deploy-apps/routes-domains.html#create-route-with-port) in _Configuring Routes
and Domains_.


## <a name="modify-ports"></a> Modify TCP Port Reservations

After deploying <%= vars.app_runtime_abbr %>, you can modify the range of ports available
for TCP routes using `cf curl` commands, as demonstrated with the commands below. These
commands require you to have an admin user account with the `routing.router_groups.read`
and `routing.router_groups.write` scopes.

1. In a terminal window, view the `reservable_ports` by running:

    ```
    cf curl /routing/v1/router_groups
    ```
    Record the `guid` from the output.

1. To configure a new port, run:

    ```
    cf curl /routing/v1/router_groups/GUID
    ```
    Where `GUID` is the GUID you recorded in the previous step.
    <br>
    <br>
    To configure multiple ports, enter a comma-separated list of ports or port ranges by
    running:

    ```
    cf curl \
    -X PUT -d '{"reservable_ports":"PORTS-OR-PORT-RANGES"}' \
    /routing/v1/router_groups/f7392031-a488-4890-8835-c4a038a3bded
    ```
    Where `PORTS-OR-PORT-RANGES` is a comma-separated list of ports or port ranges. For
    example, `"reservable_ports":"1024-1199,1234-1248,1312"`.

<p class="note"><strong>Note:</strong> Do not enter <code>reservable_ports</code> that conflict
  with other TCP router instances or ephemeral port ranges. <%= vars.company_name %> recommends
  using port ranges within <code>1024-2047</code> and <code>18000-32767</code> on default
  installations. Check which ports are available on the TCP router VMs to verify that no
  additional ports are in use. For more information, see <a href="https://github.com/cloudfoundry/routing-release/issues/184">
  TCP router fails to configure routes when there is a port conflict with a local process</a>
  in the Routing Release repository on GitHub.</p>


<% if not vars.platform_code == "CF" %>
## <a name="disable-tcp"></a> Disable TCP Routing

<%= partial "/#{vars.platform_code.downcase}/core/#{vars.current_major_version.sub('.','-')}/disable-tcp-routing-procedure" %>

<% end %>