Refresh and Update TCP documentation (#2627) (#2679)

* init client app doc

* init TCP section

* add redirect for TCP client doc

* Redis and Mysql

* finish TCP exampels

* init Draft template

* cleanup whitespace

* escape markdown image in template

* add redirect and update links

* copy edit

* Update readme.md

* fmt

Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>

* optimize png

Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>

* header cleanup and child listing

* Update docs/docs/tcp/ssh.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: cmo-pomerium <91488121+cmo-pomerium@users.noreply.github.com>
Co-authored-by: Bobby DeSimone <bobbydesimone@gmail.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: Alex Fornuto <afornuto@pomerium.com>
Co-authored-by: cmo-pomerium <91488121+cmo-pomerium@users.noreply.github.com>
Co-authored-by: Bobby DeSimone <bobbydesimone@gmail.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

docs/.vuepress/config.js

@@ -5,11 +5,8 @@ module.exports = {
     "Pomerium is a beyond-corp inspired, zero trust, open source identity-aware access proxy.",
   plugins: [
     "vuepress-plugin-element-tabs",
-    'vuepress-plugin-mermaidjs',
-    [
-      'vuepress-plugin-code-copy',
-      true
-    ],
+    "vuepress-plugin-mermaidjs",
+    ["vuepress-plugin-code-copy", true],
     [
       "check-md",
       {
@@ -32,14 +29,15 @@ module.exports = {
   ],
   markdown: {
     externalLinkSymbol: false,
-    extendMarkdown:(md) => {
-      md.use(require('markdown-it-include'), {
-        root: './docs/partials/'
-      })
+    extendMarkdown: (md) => {
+      md.use(require("markdown-it-include"), {
+        root: "./docs/partials/",
+      });
     },
   },
   themeConfig: {
     home: false,
+    activeHeaderLinks: false,
     logo: "/img/logo_white.svg",
     repo: "pomerium/pomerium",
     editLinks: true,
@@ -117,6 +115,7 @@ module.exports = {
           path: "/docs/identity-providers/",
           type: "group",
           sidebarDepth: 0,
+          initialOpenGroupIndex: 0,
           children: [
             "identity-providers/",
             "identity-providers/auth0",
@@ -130,13 +129,29 @@ module.exports = {
             "identity-providers/ping",
           ],
         },
-        "client",
+        {
+          title: "TCP Connections",
+          collapsable: false,
+          path: "/docs/tcp/",
+          type: "group",
+          sidebarDepth: 1,
+          children: [
+            "tcp/",
+            "tcp/client",
+            {
+              title: "Examples",
+              collapsable: true,
+              type: "group",
+              sidebarDepth: 0,
+              children: ["tcp/mysql", "tcp/rdp", "tcp/redis", "tcp/ssh"],
+            },
+          ],
+        },
         {
           title: "Topics",
-          collapsable: true,
+          collapsable: false,
           path: "/docs/topics/",
           type: "group",
-          collapsable: false,
           sidebarDepth: 1,
           children: [
             "topics/certificates",
@@ -146,7 +161,6 @@ module.exports = {
             "topics/kubernetes-integration",
             "topics/production-deployment",
             "topics/programmatic-access",
-            "topics/tcp-support",
             "topics/single-sign-out",
             "topics/load-balancing",
           ],
@@ -238,7 +252,7 @@ module.exports = {
             },
             "api",
             "upgrading",
-            "changelog"
+            "changelog",
           ],
         },
       ],
@@ -246,7 +260,8 @@ module.exports = {
   },
   head: [
     //Hack: Make clicking on the logo go to home url
-    ["script",
+    [
+      "script",
       {},
       `
       const logoUrlChanger = setInterval(function() {
@@ -268,7 +283,7 @@ module.exports = {
       }
       }, 1000)
 
-      `
-    ]
+      `,
+    ],
   ],
 };

docs/.vuepress/public/_redirects

@@ -65,3 +65,6 @@
 /docs/quick-start/helm.html                 /docs/install/helm.html
 /docs/quick-start/from-source.html          /docs/install/from-source.html
 /docs/quick-start/synology.html             /docs/guides/synology.html
+
+/docs/client.html                           /docs/tcp/client.html
+/docs/topics/tcp-support.html               /docs/tcp/

docs/.vuepress/theme/layouts/Draft.vue

@@ -0,0 +1,14 @@
+<template>
+  <ParentLayout />
+</template>
+
+<script>
+import ParentLayout from "@parent-theme/layouts/404.vue";
+
+export default {
+  name: "Draft",
+  components: {
+    ParentLayout,
+  },
+};
+</script>

docs/docs/tcp/client.md

@@ -38,6 +38,8 @@ The example below demonstrates a route to the SSH service on the host running th
 ::::
 :::::
 
+See the "Configure Routes" section of [TCP Support](/docs/tcp/readme.md#configure-routes) for more detailed information on TCP routes.
+
 ## TCP Client Software
 
 You can connect to this route with either the Pomerium CLI or Pomerium Desktop client.
@@ -126,7 +128,7 @@ See [Release](/docs/releases.md#pomerium-cli) to learn how to install pomerium-c
 ::::
 :::::
 
-For more examples and detailed usage information, see [TCP Support](/docs/topics/tcp-support.md)
+For more examples and detailed usage information, see [TCP Support](/docs/tcp/readme.md)
 
 ## Advanced Configuration
 
@@ -136,4 +138,4 @@ If Pomerium is listening on a port other than `443` (set with the [`address` key
 pomerium-cli tcp ssh.localhost:pomerium.io:2222 \
    --pomerium-url https://ssh.localhost.pomerium.io:8443 \
    --listen :2222
-```
+```

docs/docs/tcp/mysql.md

@@ -0,0 +1,70 @@
+---
+title: MySQL & MariaDB
+description: Tunnel MySQL connections through Pomerium
+---
+
+# Tunneled MySQL Connections
+
+This document explains how to connect to a MySQL or MariaDB database through an encrypted TCP tunnel. We use the `mysql` command line utility, but the same tunnel can be used by GUI tools.
+
+
+
+ ## Basic Connection
+
+ 1. Create a TCP tunnel, using either [`pomerium-cli`](/docs/releases.md#pomerium-cli) or the Pomerium Desktop client:
+
+    ::::: tabs
+    :::: tab pomerium-cli
+    ```bash
+    pomerium-cli tcp aService.corp.example.com:3306 --listen :3306
+    ```
+
+    :::tip --listen
+    The `--listen` flag is optional. It lets you define what port the tunnel listens on locally. If not specified, the client will choose a random available port.
+    :::
+
+    ::::
+    :::: tab Pomerium Desktop
+    ![An example connection to a MySQL service from Pomerium Desktop](./img/desktop/example-mysql-connection.png)
+
+    :::tip Local Address
+    The **Local Address** field is optional. Using it defines what port the tunnel listens on locally. If not specified, Pomerium Desktop will choose a random available port.
+    :::
+
+    ::::
+    :::::
+
+1. Initiate your MySQL connection, pointing to `localhost`:
+
+    ```bash
+    mysql -h 127.0.0.1 -u USER -p
+    ```
+
+## Allow Access from Remote Hosts:
+
+1. Your MySQL or MariaDB service may not accept connections from remote hosts. Find the `bind-address` key in the configuration files (usually located in `/etc/mysql/`) and edit it to accept remote connections. For example:
+
+    ```ini
+    # Instead of skip-networking the default is now to listen only on
+    # localhost which is more compatible and is not less secure.
+    bind-address            = 0.0.0.0
+    ```
+
+1. When connecting, you may get an error like `ERROR 1130 (HY000): Host '192.0.2.10' is not allowed to connect to this MariaDB/MySQL server`. You can create a user entry in your database for the Pomerium host:
+
+    ```sql
+    CREATE USER 'user'@'pomerium.local' IDENTIFIED BY 'some_pass';
+    GRANT ALL PRIVILEGES ON *.* TO 'user'@'pomerium.local'
+    ```
+
+    Or create a user entry with no host associated:
+
+    ```sql
+    CREATE USER 'user'@'%' IDENTIFIED BY 'some_pass';
+    GRANT ALL PRIVILEGES ON *.* TO 'user'@'%'
+    ```
+
+## More Resources
+
+- [Configuring MariaDB for Remote Client Access](https://mariadb.com/kb/en/configuring-mariadb-for-remote-client-access/)
+- [How to Allow Remote Connections to MySQL Database Server](https://linuxize.com/post/mysql-remote-access/)

docs/docs/tcp/rdp.md

@@ -0,0 +1,70 @@
+---
+title: RDP
+description: Tunnel RDP connections through Pomerium
+---
+
+# Tunneled RDP Connections
+
+Remote Desktop Protocol (**RDP**) is a standard for using a desktop computer remotely. It was released by Microsoft and is most commonly used to access Windows systems, but can be used for macOS and Linux systems as well.
+
+## Basic Connection
+
+1. Create a TCP tunnel, using either [`pomerium-cli`](/docs/releases.md#pomerium-cli) or the Pomerium Desktop client:
+
+    ::::: tabs
+    :::: tab pomerium-cli
+    ```bash
+    pomerium-cli tcp aService.corp.example.com:3389 --listen :3389
+    ```
+
+    :::tip --listen
+    The `--listen` flag is optional. It lets you define what port the tunnel listens on locally. If not specified, the client will choose a random available port.
+    :::
+
+    ::::
+    :::: tab Pomerium Desktop
+    ![An example connection to a RDP service from Pomerium Desktop](./img/desktop/example-rdp-connection.png)
+
+    :::tip Local Address
+    The **Local Address** field is optional. Using it defines what port the tunnel listens on locally. If not specified, Pomerium Desktop will choose a random available port.
+    :::
+
+    ::::
+    :::::
+
+1. Initiate your RDP connection, pointing to `localhost`. This example uses the [Remmina](https://remmina.org/) client, but the procedure should be similar for other tools:
+
+    ![A new connection profile in Remmina](./img/remmina-connection-profile.png)
+
+    ::: warning
+    The first connection attempt will initiate a redirect to authenticate you in the browser. Once you're signed in, subsequent connections will succeed. If your client isn't configured to retry the connection, you may have to reconnect manually.
+    :::
+
+
+## Always Tunnel through Pomerium
+
+Some clients, like Remmina, support running commands before and after connection. The script below (adopted from [this example](https://kgibran.wordpress.com/2019/03/13/remmina-rdp-ssh-tunnel-with-pre-and-post-scripts/) using SSH tunnels) starts and stops an instance of `pomerium-cli`:
+
+<<< @/examples/tcp/pomerium-tunnel.sh
+
+1. Save the script above to your home folder (`~/`), and make it executable:
+
+    ```bash
+    cd ~/
+    wget https://github.com/pomerium/pomerium/blob/master/examples/tcp/pomerium-tunnel.sh
+    chmod +x pomerium-tunnel.sh
+    ```
+
+1. Update your client profile to execute the script before and after the connection:
+
+    ![A connection profile in Remmina invoking a custom script](./img/remmina-connection-scripted.png)
+
+::: warning
+Flatpak versions of client software may not be able to read external scripts or programs.
+:::
+
+## More Resources
+
+- [Remote Desktop Protocol (Wikipedia)](https://en.wikipedia.org/wiki/Remote_Desktop_Protocol)
+- [Remmina (Linux)](https://remmina.org/)
+- [Microsoft Remote Desktop (macOS)](https://apps.apple.com/us/app/microsoft-remote-desktop/id1295203466?mt=12)

docs/docs/tcp/readme.md

@@ -9,8 +9,6 @@ meta:
 
 # TCP Support
 
-## About
-
 Operations and engineering teams frequently require access to lower level administrative and data protocols such as SSH, RDP, Postgres, MySQL, Redis, etc.
 
 In addition to managing HTTP based applications, Pomerium can be used to protect non-HTTP systems with the same consistent authorization policy. This is achieved by tunneling TCP over HTTP with the help of a client side command built into [`pomerium-cli`](/docs/releases.md#pomerium-cli).
@@ -24,7 +22,7 @@ To minimize issues with TCP support, Pomerium should not be placed behind anothe
 Otherwise, the HTTP proxy in front of Pomerium must know how to properly handle the `CONNECT` command and proxy it upstream.  This capability will be specific to each proxy implementation.
 :::
 
-## Configuring
+## Configure Routes
 
 TCP configuration is simple. Just specify the correct scheme and ports in your route [`to`](/reference/readme.md#to) and [`from`](/reference/readme.md#from) fields.
 
@@ -42,20 +40,21 @@ routes:
               has: "datascience@example.com"
 ```
 
-Notes:
+When creating TCP routes, note the following:
 
-* When configuring a TCP route, any HTTP specific settings such as `regex_rewrite_pattern`, or `set_request_headers` have no effect.
-* While data is encrypted from a user system to Pomerium's proxy, the underlying application protocol must also support encryption for data to be fully encrypted end-to-end.
-* The ports in `from` and `to` are independent.  Users only need to know the `from` URL to connect.  The `to` can be changed without end user participation.
+- When configuring a TCP route, any HTTP specific settings such as `regex_rewrite_pattern` or `set_request_headers` have no effect.
+- While data is encrypted from a user system to Pomerium's proxy, the underlying application protocol must also support encryption for data to be fully encrypted end-to-end. Otherwise, traffic from the Pomerium proxy service to the upstream service will be unencrypted.
+- The ports in `from` and `to` are independent.  Users only need to know the `from` URL to connect.  The `to` can be changed without end user participation.
+- The port defined in `from` does not dictate what port the tunneled traffic uses. This will always be the port defined by [`address`](/reference/readme.md#address) in your Pomerium configuration (`443` by default). The port instead differentiates multiple routes to the same hostname for different services.
 
-## Using
+## Connect to TCP Routes
 
 While HTTP routes can be consumed with just a normal browser, `pomerium-cli` must serve as a proxy for TCP routes.  It is [available](/docs/releases.md#pomerium-cli) for a variety of platforms in various formats.
 
 To connect, you normally need just the external hostname and port of your TCP route:
 
-```bash
-% pomerium-cli tcp redis.corp.example.com:6379
+```bash{1}
+pomerium-cli tcp redis.corp.example.com:6379
 5:57PM INF tcptunnel: listening on 127.0.0.1:52046
 ```
 
@@ -63,7 +62,7 @@ By default, `pomerium-cli` will start a listener on loopback on a random port.
 
 On first connection, you will be sent through a standard Pomerium HTTP authentication flow.  After completing this, your TCP connection should be established!
 
-```bash
+```bash{1}
 % redis-cli -h localhost -p 52046
 localhost:52046> keys *
 (empty array)
@@ -78,32 +77,21 @@ 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](#ssh-helper-configuration) or for sending data through a shell pipe.
 
-### SSH Helper Configuration
-
-A sample SSH ProxyCommand configuration in `ssh_config`:
-
-```
-Host *.corp.example.com
-    ProxyCommand ~/bin/pomerium-cli tcp --listen - %h:%p
-```
-
-A sample SSH command using `pomerium-cli` as a ProxyCommand:
-
-```bash
-ssh -o ProxyCommand='pomerium-cli tcp --listen - %h:%p' ssh.localhost.pomerium.io
-```
-
-More information on SSH ProxyCommand:
-
-- [https://man.openbsd.org/ssh_config.5#ProxyCommand](https://man.openbsd.org/ssh_config.5#ProxyCommand)
-- [https://www.redhat.com/sysadmin/ssh-proxy-bastion-proxyjump](https://www.redhat.com/sysadmin/ssh-proxy-bastion-proxyjump)
-
 ### Custom URL
 
-If the Pomerium proxy is not reachable through port `443` or the route is not in external DNS, a custom URL may be specified:
+If the Pomerium proxy is not reachable through port `443` or the route is not in external DNS, you can specify a custom URL:
 
 ```bash
-% pomerium-cli tcp --pomerium-url https://pomerium.corp.example.com:8443 redis.corp.example.com:6379
+pomerium-cli tcp --pomerium-url https://pomerium.corp.example.com:8443 redis.corp.example.com:6379
 ```
 
-The above command connects to `https://pomerium.corp.example.com:8443` and then requests the TCP route named `redis.corp.example.com:6379`.
+The command above connects to `https://pomerium.corp.example.com:8443` and then requests the TCP route for `redis.corp.example.com:6379`.
+
+## Service-Specific Documentation
+
+We've outlined how to use a TCP tunnel through Pomerium for several popular services that use TCP connections:
+
+- [MySQL and MariaDB](./mysql.md)
+- [RDP](./rdp.md)
+- [Redis](./redis.md)
+- [SSH](./ssh.md)

docs/docs/tcp/redis.md

@@ -0,0 +1,46 @@
+---
+title: Redis
+description: Tunnel Redis connections through Pomerium
+---
+
+# Tunneled Redis Connections
+
+Redis is a popular in-memory data structure store. It can be run locally or configured as a single or distributed standalone service.
+
+## Basic Connection
+
+ 1. Create a TCP tunnel, using either [`pomerium-cli`](/docs/releases.md#pomerium-cli) or the Pomerium Desktop client:
+
+    ::::: tabs
+    :::: tab pomerium-cli
+    ```bash
+    pomerium-cli tcp redis.corp.example.com:6379 --listen :6379
+    ```
+
+    :::tip --listen
+    The `--listen` flag is optional. It lets you define what port the tunnel listens on locally. If not specified, the client will choose a random available port.
+    :::
+
+    ::::
+
+    :::: tab Pomerium Desktop
+    ![An example connection to a Redis service from Pomerium Desktop](./img/desktop/example-redis-connection.png)
+    :::tip Local Address
+    The **Local Address** field is optional. Using it defines what port the tunnel listens on locally. If not specified, Pomerium Desktop will choose a random available port.
+    :::
+
+    ::::
+    :::::
+
+1. Initiate your Redis connection, pointing to `localhost`:
+
+    ```bash
+    redis-cli -h localhost -p 6379
+    ```
+
+This demonstrates access to a Redis server through Pomerium from the `redis-cli` tool. Pomerium Enterprise users can utilize [Service Accounts](/enterprise/service-accounts.md) to enable secure machine-to-machine communication of Redis services.
+
+## More Resources
+
+- [redis-cli](https://redis.io/topics/rediscli)
+- [Redis ACL](https://redis.io/topics/acl)

docs/docs/tcp/service-template.md

@@ -0,0 +1,57 @@
+---
+title: $SERVICE
+description: Tunnel $SERVICE connections through Pomerium
+layout: Draft
+---
+
+# Tunneled $SERVICE Connections
+
+This is a template to standardize how we document connections to popular services through a Pomerium TCP tunnel. It's not listed in the site map, so if you're not a Pomerium employee and you're reading this, you're either looking at our open-source code base, or... ¯\_(ツ)_/¯
+
+Replace the paragraph above with a brief description of the service, and/or why you would want to tunnel traffic to it.
+
+
+
+ ## Basic Connection
+
+ 1. Create a TCP tunnel, using either [`pomerium-cli`](/docs/releases.md#pomerium-cli) or the Pomerium Desktop client:
+
+    ::::: tabs
+    :::: tab pomerium-cli
+    ```bash
+    pomerium-cli tcp aService.corp.example.com:$COMMON-PORT --listen :$ANOTHER-PORT
+    ```
+
+    :::tip --listen
+    The `--listen` flag is optional. It lets you define what port the tunnel listens on locally. If not specified, the client will choose a random available port.
+    :::
+
+    ::::
+    :::: tab Pomerium Desktop
+    \![An example connection to a $SERVICE service from Pomerium Desktop](./img/desktop/example-$SERVICE-connection.png) <!-- Remove the escape \ -->
+
+    :::tip Local Address
+    The **Local Address** field is optional. Using it defines what port the tunnel listens on locally. If not specified, Pomerium Desktop will choose a random available port.
+    :::
+
+    ::::
+    :::::
+
+1. Initiate your $SERVICE connection, pointing to `localhost`:
+
+    ```bash
+    $COMMAND
+    ```
+    Optionally, if the service is accessed through GUI software, include a screenshot here. If both are commonly used, show both using tabs.
+
+## Tunnel and Connect Simultaneously
+
+If $COMMAND has a method of initiating the `pomerium-cli` tunnel as it attempts to connect, document it here.
+
+## Always Tunnel through Pomerium
+
+If the client software can be configured to automatically initiate a `pomerium-cli` tunnel when connecting, document that here.
+
+## More Resources
+
+Always include at least one or two links in a bulleted list that could help the reader.

docs/docs/tcp/ssh.md

@@ -0,0 +1,76 @@
+---
+title: SSH
+description: Tunnel SSH connections through Pomerium
+---
+
+# Tunneled SSH Connections
+
+Bad actors are constantly scanning the internet for exposed SSH services. Changing the default port obfuscates, but doesn't protect the service, and implementing and updating advanced SSH authentication can be cumbersome.
+
+By tunneling SSH connections through your Pomerium service:
+
+ - All traffic is encrypted twice (once by the Pomerium TCP connection, once by SSH itself),
+ - The SSH service can remain closed to the internet, or even restricted to only accept connections from the Pomerium proxy service
+ - Authentication and authorization is managed by Pomerium, using your IdP for identity, and can be easily managed at scale.
+
+ ## Basic Connection
+
+ 1. Create a TCP tunnel, using either [`pomerium-cli`](/docs/releases.md#pomerium-cli) or the Pomerium Desktop client:
+
+    ::::: tabs
+    :::: tab pomerium-cli
+    ```bash
+    pomerium-cli tcp aService.corp.example.com:22 --listen :2202
+    ```
+
+    :::tip --listen
+    The `--listen` flag is optional. It lets you define what port the tunnel listens on locally. If not specified, the client will choose a random available port.
+    :::
+
+    ::::
+    :::: tab Pomerium Desktop
+    ![An example connection to an SSH service from Pomerium Desktop](./img/desktop/example-ssh-connection.png)
+
+    :::tip Local Address
+    The **Local Address** field is optional. Using it defines what port the tunnel listens on locally. If not specified, Pomerium Desktop will choose a random available port.
+    :::
+
+    ::::
+    :::::
+
+1. Initiate your SSH connection, pointing to `localhost`:
+
+    ```bash
+    ssh user@localhost -p 2202
+    ```
+
+## Tunnel and Connect Simultaneously
+
+The process outlined above requires multiple steps and terminal environments (when using the CLI) or programs (when using the Desktop Client). By invoking `pomerium-cli` when the connection is made, you can streamline the process into a single connection:
+
+```bash
+ssh -o ProxyCommand='pomerium-cli tcp --listen - %h:%p' ssh.localhost.pomerium.io
+```
+
+## Always Tunnel through Pomerium
+
+Once your SSH service is configured and tested through Pomerium, you can edit your local SSH configuration file to always create a tunnel when connecting to that service:
+
+```bash
+Host aService.corp.example.com
+    ProxyCommand /usr/bin/pomerium-cli tcp --listen - %h:%p
+```
+
+You can even configure all SSH connections to your domain space to use the tunnel:
+
+```bash
+Host *.corp.example.com
+    ProxyCommand /usr/bin/pomerium-cli tcp --listen - %h:%p
+```
+
+## More Resources
+
+For more information on SSH ProxyCommand, see:
+
+- [ProxyCommand (SSH man page)](https://man.openbsd.org/ssh_config.5#ProxyCommand)
+- [SSH to remote hosts though a proxy or bastion with ProxyJump (RedHat blog)](https://www.redhat.com/sysadmin/ssh-proxy-bastion-proxyjump)

docs/docs/upgrading.md

@@ -109,7 +109,7 @@ The `administrators` configuration option has been removed.
 
 ### TCP Proxying
 
-Pomerium can now be used for non-HTTP services.  See [documentation](/docs/topics/tcp-support.md) for more details.
+Pomerium can now be used for non-HTTP services.  See [documentation](/docs/tcp/readme.md) for more details.
 
 ### Datadog Tracing
 

docs/enterprise/reference/manage.md

@@ -27,7 +27,7 @@ This value is only visible in the Console UI.
 
 `From` is the externally accessible URL for the proxied request.
 
-Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
+Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/tcp/readme.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
 
 :::warning
 

docs/guides/tcp.md

@@ -10,7 +10,7 @@ description: >-
 
 # Securing TCP based services
 
-The following guide demonstrates how to use Pomerium's [TCP Proxying](/docs/topics/tcp-support.md) support with various TCP services such as databases and other non-HTTP protocols.  It also covers integration points with them when possible.
+The following guide demonstrates how to use Pomerium's [TCP Proxying](/docs/tcp/readme.md) support with various TCP services such as databases and other non-HTTP protocols.  It also covers integration points with them when possible.
 
 The source files from this guide can be found on [GitHub](https://github.com/pomerium/pomerium/tree/master/examples/tcp/).
 

docs/reference/readme.md

@@ -1174,7 +1174,7 @@ Requires setting [Google Cloud Serverless Authentication Service Account](#googl
 
 `From` is the externally accessible URL for the proxied request.
 
-Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
+Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/tcp/readme.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
 
 :::warning
 

docs/reference/settings.yaml

@@ -1294,7 +1294,7 @@ settings:
         doc: |
           `From` is the externally accessible URL for the proxied request.
 
-          Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/topics/tcp-support.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
+          Specifying `tcp+https` for the scheme enables [TCP proxying](/docs/tcp/readme.md) support for the route. You may map more than one port through the same hostname by specifying a different `:port` in the URL.
 
           :::warning
 

examples/tcp/pomerium-tunnel.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+scriptname="$(basename $0)"
+
+if [ $# -lt 3 ]
+ then
+    echo "Usage: $scriptname start | stop  POMERIUM_ROUTE LOCAL_PORT"
+    exit
+fi
+
+case "$1" in
+
+start)
+  echo "Starting Pomerium Tunnel to $2"
+  pomerium-cli tcp $2 --listen $3 &
+  ;;
+stop)
+  echo "Stopping Pomerium tunnel to $3"
+  kill $(pgrep -f "pomerium-cli tcp $2 --listen $3")
+ ;;
+*)
+  echo "Did not understand your argument, please use start|stop"
+  ;;
+
+esac