Teleport Quick Start

This tutorial will guide you through the steps needed to install and run Teleport on a single node, which could be your local machine but we recommend a VM.

Prerequisites

This guide is only meant to demonstrate how to run Teleport in a sandbox or demo environment, and showcase a few basic tasks you can do with Teleport.

Step 1: Install Teleport

There are several ways to install Teleport. Take a look at the Teleport Installation page to pick the method convenient for you.

Step 2: Start Teleport

First, create a directory for Teleport to keep its data (by default it's /var/lib/teleport):

$ mkdir -p /var/lib/teleport

Now we are ready to start Teleport. Start the teleport daemon:

$ teleport start # if you are not `root` you may need `sudo`

Background Process

Avoid suspending your current shell session by running the process in the background like so: teleport start > teleport.log 2>&1 &. Access the process logs with less teleport.log.

Debugging/Verbose Output

If you encounter errors with any teleport, tsh or tctl command you can enable verbose logging with the -d, --debug flag.

By default, Teleport services bind to 0.0.0.0. If you ran Teleport without any configuration or flags you should see this output in your console or logfile:

[AUTH]  Auth service is starting on 0.0.0.0:3025
[PROXY] Reverse tunnel service is starting on 0.0.0.0:3024
[PROXY] Web proxy service is starting on 0.0.0.0:3080
[PROXY] SSH proxy service is starting on 0.0.0.0:3023
[SSH]   Service is starting on 0.0.0.0:3022

Congratulations - you are now running Teleport!

Step 3: Create a User Signup Token

We've got Teleport running but there are no users recognized by Teleport Auth yet. Let's create one for your OS user. In this example the OS user is teleport and the hostname of the node is grav-00 .

OS User Mappings

The OS user teleport must exist! On Linux, if it does not already exist, create it with adduser teleport. If you do not have the permission to create new users on the VM, run tctl users add teleport <your-username> to explicitly map teleport to an existing OS user. If you do not map to a real OS user you will get authentication errors later on in this tutorial!

# A new Teleport user will be assigned a
# mapping to an OS user of the same name
# This is the same as running `tctl users add teleport teleport`
[[email protected] ~]$ tctl users add teleport
User teleport has been created but requires a password.
Share this URL with the user to complete user setup, link is valid for 1h0m0s:
https://grav-00:3080/web/invite/3a8e9fb6a5093a47b547c0f32e3a98d4

NOTE: Make sure grav-00:3080 points at a Teleport proxy which users can access.

If you want to map to a different OS user, electric for instance, you can specify like so: tctl users add teleport electric. You can also assign multiple mappings like this tctl users add teleport electric,joe,root.

You now have a signup token for the Teleport User teleport and will need to open this URL in a web browser to complete the registration process.

Step 4: Register a User

Warning

We haven't provisioned any SSL certs for Teleport yet. Your browser will throw a warning: Your connection is not private. Click Advanced, and Proceed to [HOST_IP] (unsafe) to preview the Teleport UI.

Teleport User Registration

Teleport enforces two-factor authentication by default . If you do not already have Google Authenticator, Authy or another 2FA client installed, you will need to install it on your smart phone. Then you can scan the QR code on the Teleport login web page, pick a password and enter the two-factor token.

After completing registration you will be logged in automatically

Teleport UI Dashboard

Step 5: Log in through the CLI

Let's login using the tsh command line tool. Just as in the previous step, you will need to be able to resolve the hostname of the cluster to a network accessible IP.

Warning

For the purposes of this quickstart we are using the --insecure flag which allows us to skip configuring the HTTP/TLS certificate for Teleport proxy.

Caution: the --insecure flag does not skip TLS validation for the Auth Server. The self-signed Auth Server certificate expects to be accessed via one of a set of hostnames (ex. grav-00 ). If you attempt to access via localhost you will probably get this error: principal "localhost" not in the set of valid principals for given certificate .

To resolve this error find your hostname with the hostname command and use that instead of localhost .

Never use --insecure in production unless you terminate SSL at a load balancer. You must configure a HTTP/TLS certificate for the Proxy. Learn more in our SSL/TLS for Teleport Proxy - Production Guide

# here grav-00 is a resolvable hostname on the same network
# --proxy can be an IP, hostname, or URL
[[email protected] ~]$ tsh --proxy=grav-00 --insecure login
WARNING: You are using insecure connection to SSH proxy https://grav-00:3080
Enter password for Teleport user teleport:
Enter your OTP token:
XXXXXX
WARNING: You are using insecure connection to SSH proxy https://grav-00:3080
> Profile URL:  https://grav-00:3080
  Logged in as: teleport
  Cluster:      grav-00
  Roles:        admin*
  Logins:       teleport
  Valid until:  2019-10-05 02:01:36 +0000 UTC [valid for 12h0m0s]
  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty

* RBAC is only available in Teleport Enterprise

  https://gravitational.com/teleport/docs/enterprise

Step 6: Start A Recorded Session

At this point you have authenticated with Teleport Auth and can now start a recorded SSH session. You logged in as the teleport user in the last step so the --user is defaulted to teleport.

$ tsh ssh --proxy=grav-00 grav-00
$ echo 'howdy'
howdy
# run whatever you want here, this is a regular SSH session.

Note: The tsh client always requires the --proxy flag

Your command prompt may not look different, but you are now in a new SSH session which has been authenticated by Teleport!

Try a few things to get familiar with recorded sessions:

Sessions View

  1. Navigate to https://[HOST]:3080/web/sessions in your web browser to see the list of current and past sessions on the cluster. The session you just created should be listed.

  2. After you end a session (type $ exit in session), replay it in your browser.

  3. Join the session in your web browser.

Here we've started two recorded sessions on the node grav-00 : one via the web browser and one in the command line. Notice that there are distinct SSH sessions even though we logged in with the root user. In the next step you'll learn how to join a shared session.

Step 7: Join a Session on the CLI

One of the most important features of Teleport is the ability to share a session between users. If you joined your active session in your browser in the previous step you will see the complete session history of the recorded session in the web terminal.

Joining a session via a browser is often the easiest way to see what another user is up to, but if you have access to the proxy server from your local machine (or any machine) you can also join a session on the CLI.

# This is the recorded session you started in Step 6
$ tsh ssh --proxy=grav-00 grav-00
$ echo 'howdy'
howdy
# you might have run more stuff here...
$ teleport status
Cluster Name: grav-00
Host UUID   : a3f67090-99cc-45cf-8f70-478d176b970e
Session ID  : cd908432-950a-4493-a561-9c272b0e0ea6
Session URL : https://grav-00:3080/web/cluster/grav-00/node/a3f67090-99cc-45cf-8f70-478d176b970e/teleport/cd908432-950a-4493-a561-9c272b0e0ea6

Copy the Session ID and open a new SSH session.

%~$ tsh join -d --proxy grav-00 --insecure
cd908432-950a-4493-a561-9c272b0e0ea6
# you will be asked to re-authenticate your user
$ echo 'howdy'
howdy
# you might have run more stuff here...
$ teleport status
Cluster Name: grav-00
Host UUID   : a3f67090-99cc-45cf-8f70-478d176b970e
Session ID  : cd908432-950a-4493-a561-9c272b0e0ea6
Session URL : https://grav-00:3080/web/cluster/grav-00/node/a3f67090-99cc-45cf-8f70-478d176b970e/teleport/cd908432-950a-4493-a561-9c272b0e0ea6
$ echo "Awesome!"
# check out your shared ssh session between two CLI windows

Next Steps

Congratulations! You've completed the Teleport Quickstart.

In this guide you've learned how to install Teleport on a single-node and seen a few of the most practical features in action. When you're ready to learn how to set up Teleport for your team, we recommend that you read our Admin Guide to get all the important details. This guide will lay out everything you need to safely run Teleport in production, including SSL certificates, security considerations, and YAML configuration.

Guides

If you like to learn by doing, check out our collection of step-by-step guides for common Teleport tasks.

apartmentTeleport Enterprise

Teleport Enterprise is built around the open-source core, with premium support and additional, enterprise-grade features. It is for organizations that need to secure critical production infrastructure and meet compliance and audit requirements.

Demo Teleport Enterprise

get_appTeleport Community

Teleport Community provides modern SSH best practices out of the box for managing elastic infrastructure. Teleport Community is open-source software that anyone can download and install for free.

Star

Download Teleport Community