Fork me on GitHub

Teleport

TCP Application Access (Preview)

Improve

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 in Database Access.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 10.1.2.

    tctl version

    Teleport v10.1.2 go1.18

    tsh version

    Teleport v10.1.2 go1.18

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 10.1.2, which you can download by visiting the customer portal.

    tctl version

    Teleport v10.1.2 go1.18

    tsh version

    Teleport v10.1.2 go1.18

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 9.3.10. To download these tools, visit the Downloads page.

    tctl version

    Teleport v9.3.10 go1.18

    tsh version

    Teleport v9.3.10 go1.18

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 10.1.2

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 9.3.10

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

  • 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.)

Application Access and DNS

Teleport assigns a subdomain to each application you have configured for Application Access (e.g., grafana.teleport.example.com), so you will need to ensure that a DNS A record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS A record for each subdomain or a single record with a wildcard subdomain such as *.teleport.example.com. This way, your certificate authority (e.g., Let's Encrypt) can issue a certificate for each subdomain, enabling clients to verify your Teleport hosts regardless of the application they are accessing.

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.

To generate one, run the following command on your Auth Service node:

tctl tokens add --type=app

Next, create a Teleport user with the access role that will allow it to connect to cluster applications:

tctl users add --roles=access alice

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.

Download Teleport's PGP public key

sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \ -o /usr/share/keyrings/teleport-archive-keyring.asc

Source variables about OS version

source /etc/os-release

Add the Teleport APT repository for v10. You'll need to update this

file for each major (breaking) release of Teleport.

Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-apt-repos/main.go#L26

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v10" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport
sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport

Optional: Using DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v10.1.2-linux-amd64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.1.2-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v10.1.2-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.1.2-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.1.2-linux-arm-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.1.2-linux-arm-bin.tar.gz
shasum -a 256 teleport-v10.1.2-linux-arm-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.1.2-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.1.2-linux-arm64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.1.2-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v10.1.2-linux-arm64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.1.2-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Using this APT repo may result in breaking upgrades upon "apt upgrade" as all major versions will be

published under the same component. We recommend following the instructions in the

"Debian/Ubuntu (DEB)" tab instead.

Download Teleport's PGP public key

sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \ -o /usr/share/keyrings/teleport-archive-keyring.asc

Add the Teleport APT repository

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport

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

teleport:
  auth_token: "/tmp/token"
  auth_servers:
  - 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.

Start Teleport:

teleport start

Step 3/4. Start app proxy

Log into your Teleport cluster and view available applications:

tsh login --proxy=teleport.example.com
tsh app 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 app 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://[email protected]:55868/postgres

Next steps