Teleport

TCP Application Access (Preview)

OpenSource
Enterprise
Cloud

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 >= 12.1.1.
```
tctl version
Teleport v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```
See Installation for details.

A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.
```
tctl version
Teleport Enterprise v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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  12.1.1
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  12.1.2
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 (or CNAME for services that only provide a hostname) record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS 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.

Use the appropriate commands for your environment to install your package.

Teleport Edition

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v12. You'll need to update this
file for each major 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-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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.

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 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://[email protected]:55868/postgres

Next steps

Learn about access controls for applications.

Have a suggestion or can’t find something?

IMPROVE THE DOCS