![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
TCP Application Access
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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.2.1 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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
.)
Teleport assigns a subdomain to each application you configure for Application
Access. For example, if you enroll Grafana as a resource, Teleport assigns the resource
to the grafana.teleport.example.com
subdomain.
If you host the Teleport cluster on your own network, you should update your DNS configuration to account for application subdomains. You can update DNS in one of two ways:
- Create a single DNS address (A) or canonical name (CNAME) record using wildcard substitution
for the subdomain name. For example, create a DNS record with the name
*.teleport.example.com
. - Create a separate DNS address (A) or canonical name (CNAME) record for each application subdomain.
Modifying DNS ensures that the certificate authority—for example, Let's Encrypt—can issue a certificate for each subdomain and that clients can verify Teleport hosts regardless of the application they are accessing.
If you use the Teleport cloud platform, no DNS updates are needed because your Teleport cluster automatically provides the subdomains and signed TLS certificates for your applications under your tenant address.
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
To generate one, log into your Cloud tenant and run the following command:
tsh login --proxy=mytenant.teleport.shtctl 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:
-
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
-
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.comTELEPORT_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.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install-v16.2.1.sh | bash -s ${TELEPORT_VERSION} editionThe 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.
On the host where you will run your Teleport instance, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleport
On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo 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.comtsh apps lsApplication 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-appLogged 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-appProxying 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
.