Skip to main content
Version: 17.x (unreleased)

Introduction to Teleport Clients

This guide covers the basics of authenticating to Teleport and accessing resources. It's written for end-users of resources protected by Teleport, and includes links to more detailed documentation at the end.

Client tools​

tsh​

tsh lets you authenticate to Teleport and list and connect to resources. After downloading and installing tsh, sign in to your Teleport cluster:

Authenticate to Teleport as a local user with tsh login by assigning user to your Teleport username:

$ tsh login --proxy=teleport.example.com --user=user
Enter password for Teleport user alice:
Tap any security key
> Profile URL:        https://teleport.example.com:443
  Logged in as:       alice
  Cluster:            example.com
  Roles:              access, requester
  Logins:             ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2022-11-01 22:37:05 -0500 CDT [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy

Teleport Connect​

The Teleport Connect app provides all the same access to resources as tsh in a friendly graphic user interface. After downloading and installing Teleport Connect, you can log in and initiate sessions for server and database access within a single window.

  1. Click CONNECT to connect to the Teleport cluster:

    A new instance of Teleport Connect

  2. Provide the address of your Teleport Cluster (e.g. https://example.teleport.sh) and click NEXT.

  3. Teleport Connect will ask you for your username, password, and MFA.

    If Teleport is integrated with an external Identity Provider (IdP), you might be prompted to authenticate with that service in a browser window.

  4. Browse and connect to all the resources your user is permitted to access:

Web UI​

Teleport provides a web interface for users to interact with Teleport, e.g., by accessing resources or creating Access Requests. This is usually found at the same URL used to connect to Teleport with (e.g. https://example.teleport.sh), but you should confirm the Web UI URL with the team that manages your Teleport deployment.

The Web UI provides similar access to resources as Teleport Connect, and additional access to to Request and Activity logs for users with the right permissions.

Protocols​

Server access (ssh)​

tsh ls lists the servers you have access to through Teleport:

$ tsh ls
Node Name           Address         Labels
------------------- --------------- ----------------------------
server1.example.com 192.0.2.24:3022 access=servers,hostname=server1
server2.example.com 192.0.2.32:3022 access=servers,hostname=server2

To connect to a server:

$ tsh ssh ubuntu@server1.example.com
ubuntu@server1:~$

Kubernetes access (kubectl)​

To see the Kubernetes clusters that you can access via Teleport, run the following command:

$ tsh kube ls
 Kube Cluster Name Labels                      Selected
 ----------------- --------------------------- --------
 mycluster         env=dev

To log in to the cluster, run the following command, changing mycluster to the name of a Kubernetes cluster as it was listed in tsh kube ls:

$ tsh kube login mycluster
Logged into kubernetes cluster "mycluster". Try 'kubectl version' to test the
connection.

When you log in to your Teleport cluster via tsh kube login, tsh updates your kubeconfig to point to your chosen Kubernetes cluster. You can then run kubectl commands against your cluster.

Transferring files​

tsh scp will let you transfer files to servers behind Teleport:

$ tsh scp some-file.ext server.example.com:
some-file.ext   7% |███████                | (25/342 MB, 2.9 MB/s) [9s:1m48s]

Database Access​

tsh db ls will list the databases available to your user:

$ tsh db ls
Name                                               Description Allowed Users   Labels  Connect
-----------------------------------------------    ----------- --------------- ------- -------------------------
myelastic                                                      [alice elastic] env=dev
mysql-server1 (user: alice, db: teleport_example)              [alice elastic] env=dev tsh db connect mysql-server1

To connect to a database server through tsh, you'll need a local client for that database. For example, to connect to a MySQL or MariaDB database, you'll need the MySQL CLI client:

$ tsh db connect --db-user=alice --db-name=teleport_example mysql-server1

In this example, teleport_example is a pre-existing database on the MySQL server:

SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| teleport_example   |
+--------------------+
4 rows in set (0.09 sec)

For other connection types, or to connect a graphic database client, you can create a local tunnel to point your software to:

$ tsh proxy db myelastic --db-user=alice --tunnel
Started authenticated tunnel for the Elasticsearch database "myelastic" in cluster "example.come" on 192.0.2.58:52669.

Use one of the following commands to connect to the database:

  * interactive SQL connection:

  $ elasticsearch-sql-cli http://localhost:52669/

  * run single request with curl:

  $ curl http://localhost:52669/

Database certificate renewed: valid until 2022-11-02T06:11:50Z [valid for 9h55m0s]

Desktop access​

Desktop access is available through the Teleport Web UI.

  1. In your browser, navigate to your Teleport cluster (for example, https://example.teleport.sh).
  2. From the menu on the right, select Desktops.
  3. Next to the desktop you want to access, click CONNECT. Select or type in a username available to your Teleport user.
  4. Teleport will open a new browser tab or window and begin the RDP session. Note that you may need to wait a moment for Teleport to log you in as the specified user.

Next steps​

This guide covers the basic installation and access of Teleport for end users, but the rest of the Connect your Client section provides more detailed information.

  • tsh is the CLI tool for accessing resources through Teleport. With it, you can authenticate to Teleport, list available services, and connect to them either directly or through proxy tunnels.

    Learn more about it from Using the tsh Command Line Tool.

  • Teleport Connect is a graphic utility for connecting to resources through Teleport. You use it to connect to servers, databases, and Kubernetes clusters. See Using Teleport Connect.