Skip to main content
Version: vNext (upcoming release)

Build TCP Routes

Now that you’ve built several routes, it's time to proxy TCP connections with Pomerium.

Specifically,  we’ll create a Redis service and route users to it with a TCP connection.

Before You Start

Make sure you’ve completed the following tutorials:

Each tutorial builds on the same configuration files. In this tutorial, you’ll build routes to several services and proxy TCP connections to these services with Pomerium CLI.

Background

When replacing a traditional VPN, there are often non-HTTP based applications you still need to reach. Pomerium can provide the same type of protection to these services with Pomerium CLI, a client-side application to proxy TCP connections.

In this tutorial, you’ll secure a backend Redis service behind Pomerium and access it by connecting to it with a TCP route.

Pomerium’s CLI client comes with a tcp command that you can use to secure this connection.

Prerequisites

To complete this tutorial, you need:

  • Pomerium CLI to proxy TCP connections between end-users and services behind Pomerium
  • mkcert to generate a locally trusted Certificate Authority and certificates (for development purposes only)
note

For this tutorial, install Pomerium CLI to your system instead of using the Pomerium CLI Docker Image.

Test Pomerium CLI

Once you’ve installed Pomerium CLI, test the installation by running pomerium-cli:

$ pomerium-cli
Usage:
pomerium-cli [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
k8s commands for the kubernetes credential plugin
tcp creates a TCP tunnel through Pomerium
version version

Flags:
-h, --help help for pomerium-cli
-v, --version version for pomerium-cli

Use "pomerium-cli [command] --help" for more information about a command.

If you see this output, success!

Configure locally-trusted certificates

Next, you will generate locally trusted certificates with mkcert.

Install mkcert:

mkcert -install

This command will install mkcert and generate a rootCA.pem file in your system’s trust store.

Generate wildcard certificates:

`mkcert "*.localhost.pomerium.io"`

This command will generate the following certificates in your project’s root directory:

  • _wildcard.localhost.pomerium.io.pem
  • _wildcard.localhost.pomerium.io-key.pem

Update Pomerium configuration

In your Pomerium configuration file, add the certificates key:

config.yaml
certificates:
- cert: /pomerium/cert.pem
key: /pomerium/key.pem

Mount wildcard certificates

In your Docker Compose file, bind mount your wildcard certificates as a volume in the Pomerium service:

docker-compose.yaml
services:
pomerium:
image: cr.pomerium.com/pomerium/pomerium:latest
volumes:
# Mount your wildcard certificates:
- ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/key.pem:ro
- ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443

Add TCP connections

Add Redis to Docker Compose

Next, add your services in Docker Compose:

docker-compose.yaml
redis:
image: redis:latest
expose:
- 6379

Configure a TCP route

Add the Redis route to your service in your Pomerium configuration file using the tcp syntax:

config.yaml
- from: tcp+https://redis.localhost.pomerium.io:6379
to: tcp://redis:6379
policy:
- allow:
or:
- domain:
is: example.com

Connect with Pomerium CLI

Now, use Pomerium CLI’s tcp command to connect to the Redis service

$ pomerium-cli tcp redis.localhost.pomerium.io:6379 --listen localhost:6379

2023/10/02 12:20:05 listening on 127.0.0.1:6379

Start the Redis client:

$ redis-cli info
# Server
redis_version:7.0.5
redis_git_sha1:00000000
redis_git_dirty:0
redis_build_id:d9291579292e26e3
redis_mode:standalone
os:Linux 6.3.13-linuxkit aarch64
arch_bits:64
monotonic_clock:POSIX clock_gettime
multiplexing_api:epoll
atomicvar_api:c11-builtin
gcc_version:10.2.1
process_id:1
process_supervised:no
run_id:e4c843df14511765f0e6284690be2f10c6b39e28
tcp_port:6379
server_time_usec:1696349965506132
uptime_in_seconds:75
uptime_in_days:0
hz:10
configured_hz:10
lru_clock:1851149
executable:/data/redis-server
config_file:
io_threads_active:0

Summary

In this tutorial, you secured a TCP connection to Redis. To secure the connection, you used the pomerium-cli tcp command.

At this point, we’ve done all we can do with a hosted Pomerium instance in a Dockerized environment. You now know all the necessary basics for running Pomerium itself, so let’s take it out of Docker and into the wild!

In the next tutorial, we will turn to Google Cloud Platform (GCP) to spin up a Virtual Machine instance, register a domain using Cloud Domains, and wire it up with Cloud DNS. This way, you can self-host your own domain and Pomerium.