TCP Application Access

Teleport can provide access to any TCP-based application. This allows users to connect to applications which Teleport doesn't natively support such as SMTP servers or databases not yet natively supported by the Teleport Database Service.

Prerequisites

• A running Teleport cluster version 16.4.12 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  16.4.12
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
• TCP application to connect to. In this guide we'll use a PostgreSQL running in Docker as an example. You can also use any TCP-based application you may already have.
• Host where you will run the Teleport Application Service.

We will assume your Teleport cluster is accessible at teleport.example.com and *.teleport.example.com. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to mytenant.teleport.sh.)

Step 1/4. Start PostgreSQL container

Skip this step if you already have an application you'd like to connect to.

Start a PostgreSQL server in a Docker container:

docker run --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=<pass> -d postgres

Step 2/4. Start Teleport Application Service

Teleport Application Service requires a valid auth token to join the cluster.

tctl tokens add --type=app

tctl users add --roles=access alice

tsh login --proxy=mytenant.teleport.sh
tctl tokens add --type=app

Save the generated token in /tmp/token on the node where Application Service will run.

Now, install Teleport on the Application Service node. It must be able to reach both your Teleport Proxy and the TCP application it's going to proxy.

Install Teleport on your Linux server:

1. Assign edition to one of the following, depending on your Teleport edition:

   Edition	Value
   Teleport Enterprise Cloud	cloud
   Teleport Enterprise (Self-Hosted)	enterprise
   Teleport Community Edition	oss

2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

   Otherwise, get the version of your Teleport cluster:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

3. Install Teleport on your Linux server:

   curl https://cdn.teleport.dev/install-v16.4.12.sh | bash -s ${TELEPORT_VERSION} edition

   The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

Create the Application Service configuration file /etc/teleport.yaml with the following contents:

version: v3
teleport:
  auth_token: "/tmp/token"
  proxy_server: teleport.example.com:3080
auth_service:
  enabled: "no"
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "no"
app_service:
  enabled: "yes"
  apps:
  - name: "tcp-app"
    uri: tcp://localhost:5432

Note that the URI scheme must be tcp:// in order for Teleport to recognize this as a TCP application.

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

sudo systemctl enable teleport
sudo systemctl start teleport

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 3/4. Start app proxy

Log into your Teleport cluster and view available applications:

tsh login --proxy=teleport.example.com
tsh apps ls
Application Description   Type Public Address                   Labels----------- ------------- ---- -------------------------------- -----------tcp-app                   TCP  tcp-app.root.gravitational.io

Your TCP application should show up and be denoted with a TCP type.

Now log into the application:

tsh apps login tcp-app
Logged into TCP app tcp-app. Start the local TCP proxy for it:
  tsh proxy app tcp-app
Then connect to the application through this proxy.

Next, start a local proxy for it:

tsh proxy app tcp-app
Proxying connections to tcp-app on 127.0.0.1:55868

The tsh proxy app command will set up a listener that will proxy all connections to the target application.

Step 4/4. Connect

Once the local proxy is running, you can connect to the application using the application client you would normally use to connect to it:

psql postgres://postgres@localhost:55868/postgres

Next steps

• Learn about access controls for applications.
• Learn how to connect to TCP apps with VNet and configure VNet for custom public_addr.