Skip to main content
Version: 16.x

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.5.4 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@example.com
    tctl status
    Cluster  teleport.example.com
    Version  16.5.4
    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.)

Application Access and DNS

Once the Teleport Application Service is proxying traffic to your web application, the Teleport Proxy Service makes the application available at the following URL:

https://<APPLICATION_NAME>.<TELEPORT_DOMAIN>

For example, if your Teleport domain name is teleport.example.com, the application named my-app would be available at https://my-app.teleport.example.com. The Proxy Service must present a TLS certificate for this domain name that browsers can verify against a certificate authority.

If you are using Teleport Enterprise (Cloud), DNS records and TLS certificates for this domain name are provisioned automatically. If you are self-hosting Teleport, you must configure these yourself:

  1. Create either:

    • A DNS A record that associates a wildcard subdomain of your Teleport Proxy Service domain, e.g., *.teleport.example.com, with the IP address of the Teleport Proxy Service.
    • A DNS CNAME record that associates a wildcard subdomain of your Proxy Service domain, e.g., *.teleport.example.com, with the domain name of the Teleport Proxy Service.

  2. Ensure that your system provisions TLS certificates for Teleport-registered applications. The method to use depends on how you originally set up TLS for your self-hosted Teleport deployment, and is outside the scope of this guide.

    In general, the same system that provisions TLS certificates signed for the web address of the Proxy Service (e.g., teleport.example.com) must also provision certificates for the wildcard address used for applications (e.g., *.teleport.example.com).

Take care not to create DNS records that map the Teleport cluster subdomain of a registered application to the application's own host, as attempts to navigate to the application will fail.

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.

Install Teleport on your Linux server:

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

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

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

On the host where you will run your Teleport instance, enable and start Teleport:

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​