Skip to main content

Pomerium Desktop and CLI Clients

This document describes how to use Pomerium's Desktop and CLI clients to connect to TCP routes in Pomerium.

What's a TCP route?

A TCP route is for use with upstream services that don't speak HTTP — for example SSH, Redis, or MySQL. With a TCP route, the entire connection is proxied to the upstream service, rather than each individual request separately.

In Pomerium, TCP routes are denoted with a tcp+ prefix in the route's From URL.

Create a TCP route​

  1. Specify this new Route as a TCP Route by prefixing tcp+ in the From field, along with a port number
  2. Set the To field using tcp:// as the scheme, along with the address and port that the upstream service is listening on

The example below demonstrates a route to an SSH service on the host running Pomerium:

Example TCP route for SSH

tip

The port number in the route From URL is not used in the initial connection to Pomerium itself. This connection will still use port 443, unless you use a bastion host (see Advanced configuration below).

Rather, the port defined in From is part of the mapping to the individual route. In this way, you can create multiple routes that share a DNS entry, differentiated by the port to determine which route they use.

For example, suppose we have a server called augur running behind Pomerium that has a MySQL server and also listens for SSH connections. We can create routes for tcp+https://augur.example.com:22 and tcp+https://augur.example.com:3306.

See the "Configure Routes" section of TCP Support for more detailed information on TCP routes.

Access TCP routes with a client​

You can connect to this route with either the Pomerium CLI or Pomerium Desktop client.

Desktop client steps​

If you haven't, install Pomerium Desktop.

Then, add a connection by filling in the fields defined below:

  • Name: A local name for the route
  • Destination: Matches the From value of the route, without the protocol. Always include the port specified in the route, and do not include the https:// protocol.
  • Local Address: The local address and port number from which to access the service locally. If left blank, the client will choose a random port to listen to on the loopback address.
  • Tags: Customizable tags to sort and organize TCP routes

Adding a new connection in the Pomerium Desktop client

Advanced Settings​

  • Pomerium URL: The Pomerium Proxy service address. This is required if the Destination URL can't be resolved from DNS or a local hosts entry, or if the Proxy service uses a non-standard port.
  • Disable TLS Verification: Allows untrusted certificates from the Pomerium gateway
  • Client Certificates: For routes that enforce mTLS, you can set a client certificate manually or automatically search the OS certificate store for a trusted certificate (note: macOS and Windows only).

Reviewing the Advanced Settings in the Pomerium Desktop client

Pomerium CLI steps​

If you haven't, install Pomerium CLI.

Then, connect to a TCP route:

  1. Invoke pomerium-cli with the tcp option, and provide the route to your service (as defined in from in your Route specification).

    $ pomerium-cli tcp ssh.localhost.pomerium.io:22
    2023/10/02 11:29:22 listening on 127.0.0.1:53656

    You can optionally supply an address and/or port to the listen flag:

    $ pomerium-cli tcp ssh.localhost.pomerium.io:22 --listen :2222
    2023/10/02 11:30:03 listening on [::]:2222

  2. Connect to your service using the local address and port specified in the output of pomerium-cli:

    ssh 127.0.0.1 -p 2222

  3. When the connection starts, the CLI will open your browser and direct you to your Identity Provider to authenticate your session. Once authenticated, the connection will continue and you can close the browser window.

  4. In this example, since we are using SSH we can consolidate the TCP and SSH connections into a single command:

    ssh -o ProxyCommand='pomerium-cli tcp --listen - %h:%p' ssh.localhost.pomerium.io
info

For more examples and detailed usage information, see the following docs:

Advanced configuration​

If Pomerium is listening on a port other than 443 (set with the address key), the full TCP URL can be specified with a bastion host:

pomerium-cli tcp tcp+https://ssh.localhost:pomerium.io:8443/ssh.localhost.pomerium.io:2222 --listen :2222