diff --git a/content/docs/capabilities/tcp.mdx b/content/docs/capabilities/tcp.mdx index 18cab7cc8..bf9d94509 100644 --- a/content/docs/capabilities/tcp.mdx +++ b/content/docs/capabilities/tcp.mdx @@ -36,7 +36,7 @@ Otherwise, the HTTP proxy in front of Pomerium must know how to properly handle ::: -## Configure Routes +## Configure TCP routes TCP configuration is simple. Just specify the correct scheme and ports in your route [`to`](/docs/reference/routes/to) and [`from`](/docs/reference/routes/from) fields. @@ -89,15 +89,15 @@ localhost:52046> ::: -## Advanced Usage +## Advanced capabilities -### Listen Configuration +### Listen configuration You may specify an optional address and port for the `tcp` command to listen on. `-` specifies that STDIN and STDOUT should be directly attached to the remote TCP connection. This is useful for [SSH](tcp/examples/ssh#tunnel-and-connect-simultaneously) or for sending data through a shell pipe. -### Bastion Host +### Bastion host If the Pomerium proxy is not reachable through port `443` or the route is not in external DNS, you can use Pomerium as a bastion host using the extended TCP URL syntax in your route definition: @@ -113,7 +113,7 @@ pomerium-cli tcp tcp+https://proxy.corp.example.com:8443/redis.internal.example. The command above connects to `https://pomerium.corp.example.com:8443` and then requests the TCP route for `redis.internal.example.com:6379`. -### Client Certificates +### Client certificates If Pomerium is configured to require client certificates, you will also need to provide a client certificate and private key when invoking the `pomerium-cli` command. @@ -149,13 +149,29 @@ pomerium-cli tcp --client-cert-from-store --client-cert-subject "OU=My Departmen See the [reference page](/docs/capabilities/tcp/reference#certificate-name-filters) for more details about the certificate name filter syntax. -## Service-Specific Documentation +### Proxy chaining support -We've outlined how to use a TCP tunnel through Pomerium for several popular services that use TCP connections: +The TCP route example above uses a `to` URL with the scheme `tcp://`. For a TCP route like this, Pomerium will open a raw TCP connection to the upstream service. -- [Git](tcp/examples/git) -- [Microsoft SQL](tcp/examples/ms-sql) -- [MySQL and MariaDB](tcp/examples/mysql) -- [RDP](tcp/examples/rdp) -- [Redis](tcp/examples/redis) -- [SSH](tcp/examples/ssh) +Alternatively, you can configure a TCP route to proxy an HTTP CONNECT request to the upstream service. This is useful if you want to place another HTTP-to-TCP proxy behind Pomerium. + +To configure Pomerium to chain TCP connection requests: + +```yaml +routes: + - from: tcp+https://example.corp.com:10002 + to: http://second-proxy.example.corp.com:10003 +``` + +:::info TCP examples + +The guides below demonstrate how to proxy TCP tunnels with Pomerium to well-known services: + +- [**Git**](tcp/examples/git) +- [**Microsoft SQL**](tcp/examples/ms-sql) +- [**MySQL and MariaDB**](tcp/examples/mysql) +- [**RDP**](tcp/examples/rdp) +- [**Redis**](tcp/examples/redis) +- [**SSH**](tcp/examples/ssh) + +::: diff --git a/content/docs/capabilities/tcp/client.mdx b/content/docs/capabilities/tcp/client.mdx index e39331159..34ed88c7e 100644 --- a/content/docs/capabilities/tcp/client.mdx +++ b/content/docs/capabilities/tcp/client.mdx @@ -74,7 +74,14 @@ For example, suppose we have a server called `augur` running behind Pomerium tha ::: -See the "Configure Routes" section of [TCP Support](/docs/capabilities/tcp#configure-routes) for more detailed information on TCP routes. +:::info + +To learn about building TCP routes, see: + +- [**Configure TCP Routes**](/docs/capabilities/tcp#configure-tcp-routes) +- [**Advanced TCP usage**](/docs/capabilities/tcp#advanced-usage) + +::: ## Access TCP routes with a client diff --git a/content/docs/capabilities/tcp/examples/_service-template.mdx b/content/docs/capabilities/tcp/examples/_service-template.mdx index 21dd86a8c..61deda8e0 100644 --- a/content/docs/capabilities/tcp/examples/_service-template.mdx +++ b/content/docs/capabilities/tcp/examples/_service-template.mdx @@ -15,7 +15,7 @@ Replace the paragraph above with a brief description of the service, and/or why :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: diff --git a/content/docs/capabilities/tcp/examples/git.mdx b/content/docs/capabilities/tcp/examples/git.mdx index 1e363038c..7561c9b8c 100644 --- a/content/docs/capabilities/tcp/examples/git.mdx +++ b/content/docs/capabilities/tcp/examples/git.mdx @@ -18,7 +18,7 @@ When hosting a self-hosted Git server like [GitLab](/docs/guides/gitlab) behind ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: ## Basic Connection diff --git a/content/docs/capabilities/tcp/examples/ms-sql.mdx b/content/docs/capabilities/tcp/examples/ms-sql.mdx index fbeb30293..ab9f8b1b3 100644 --- a/content/docs/capabilities/tcp/examples/ms-sql.mdx +++ b/content/docs/capabilities/tcp/examples/ms-sql.mdx @@ -20,7 +20,7 @@ This document explains how to connect to a Microsoft SQL database through an enc ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: diff --git a/content/docs/capabilities/tcp/examples/mysql.mdx b/content/docs/capabilities/tcp/examples/mysql.mdx index 9d26f4617..b72e12e4c 100644 --- a/content/docs/capabilities/tcp/examples/mysql.mdx +++ b/content/docs/capabilities/tcp/examples/mysql.mdx @@ -18,7 +18,7 @@ This document explains how to connect to a MySQL or MariaDB database through an ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: ## Basic Connection diff --git a/content/docs/capabilities/tcp/examples/rdp.mdx b/content/docs/capabilities/tcp/examples/rdp.mdx index cc54d77ab..57659249d 100644 --- a/content/docs/capabilities/tcp/examples/rdp.mdx +++ b/content/docs/capabilities/tcp/examples/rdp.mdx @@ -19,7 +19,7 @@ Remote Desktop Protocol (**RDP**) is a standard for using a desktop computer rem ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: ## Basic Connection diff --git a/content/docs/capabilities/tcp/examples/redis.mdx b/content/docs/capabilities/tcp/examples/redis.mdx index b4b5ad1df..59809eac4 100644 --- a/content/docs/capabilities/tcp/examples/redis.mdx +++ b/content/docs/capabilities/tcp/examples/redis.mdx @@ -18,7 +18,7 @@ Redis is a popular in-memory data structure store. It can be run locally or conf ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: ## Basic Connection diff --git a/content/docs/capabilities/tcp/examples/ssh.mdx b/content/docs/capabilities/tcp/examples/ssh.mdx index 9cea5312d..0394be5e0 100644 --- a/content/docs/capabilities/tcp/examples/ssh.mdx +++ b/content/docs/capabilities/tcp/examples/ssh.mdx @@ -25,7 +25,7 @@ By tunneling SSH connections through your Pomerium service: ::: :::tip -This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-routes) for this service. +This example assumes you've already [created a TCP route](/docs/capabilities/tcp#configure-tcp-routes) for this service. ::: ## Basic Connection diff --git a/content/docs/reference/routes/to.mdx b/content/docs/reference/routes/to.mdx index fcbb31041..1f611086f 100644 --- a/content/docs/reference/routes/to.mdx +++ b/content/docs/reference/routes/to.mdx @@ -81,7 +81,27 @@ A load balancing weight may be associated with a particular upstream by appendin to: ['http://a,10', 'http://b,20'] ``` -Must be `tcp` if `from` is `tcp+https`. +### TCP routes + +You can configure Pomerium to handle a [TCP route](/docs/capabilities/tcp) in one of two different ways. + +If you specify a `to` URL with the `tcp://` scheme, Pomerium will proxy the raw TCP connection to the upstream service: + +```yaml +- from: tcp+https://tcp.example.com:3001 + to: tcp://localhost:3001 +``` + +If you specify a `to` URL with the scheme `http://` or `https://`, Pomerium will instead proxy an HTTP CONNECT request to the upstream service: + +```yaml +- from: tcp+https://tcp.example.com:3001 + to: http://second-proxy.tcp.example.com:3002 +``` + +This allows you to place Pomerium in front of another HTTP-to-TCP proxy. + +If you specify a list of multiple `to` URLs in one route, you may not include both `tcp://` and non-`tcp://` URLs. :::note