Fork me on GitHub
Teleport

Get started with Docker Compose

Improve

This guide will help you understand how Teleport works by spinning up a demo cluster on your local machine using Docker Compose. It will also show you how to use Teleport with OpenSSH, Ansible, and Teleport's native client, tsh.

Production deployments

This guide is intended as a local lab for educational purposes. If you would like to set up Teleport for production usage, please see:

Getting Started on a Linux Server

Prerequisites

  • Teleport v9.3.7 Open Source or Enterprise.
  • Docker v20.10.7 or later and docker-compose v1.25.0 or later.
docker-compose version

docker-compose version 1.25.0, build unknown

docker version

Client: Docker Engine - Community

Version: 20.10.7

Step 1/3. Start demo lab

Let's use docker-compose to start Teleport demo lab - a configured local cluster:

Download the quick start file from our GitHub repo

curl -Lso teleport-lab.yml https://raw.githubusercontent.com/gravitational/teleport/v9.3.7/docker/teleport-lab.yml

Start teleport demo lab using docker-compose

docker-compose -f teleport-lab.yml up -d
Note

You can later stop the Teleport lab using:

docker-compose -f teleport-lab.yml down

Step 2/3. Explore CLI

Let's jump into container with setup clients and explore Teleport:

From your local terminal

docker exec -ti term /bin/bash
Note

We will run all future commands from the term container.

Welcome to Teleport Lab. With Teleport you can access servers, databases and web apps in your cluster.

Let's Try a couple of commands to get started. Teleport speaks SSH. You can SSH into it using OpenSSH:

From term container

Teleport is a bastion server for your OpenSSH hosts. SSH into OpenSSH server and record all commands:

From term container

You can also run ansible on Teleport nodes and OpenSSH servers:

From term container

cd /etc/teleport.d/ansible && ansible all -m ping

Try Teleport's client command: tsh. It's like ssh, but with superpowers. Find all hosts matching label env=example and run hostname command:

From term container

tsh ssh [email protected]=example hostname

You can see Teleport's nodes registered in the cluster using tsh ls command:

From term container

tsh ls

Node Name Address Labels

------------- -------------- --------------------------

luna.teleport 127.0.0.1:3022 env=example, hostname=luna

Step 3/3. Explore web UI

Create a Teleport user called testuser which is allowed to log in as either operating system user root or ubuntu.

From term container

tctl users add testuser --roles=editor,access --logins=root,ubuntu

Teleport will output a URL that you must open to complete the user sign-up process:

User "testuser" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:

https://proxy.luna.teleport:443/web/invite/your-token-here

NOTE: Make sure proxy.luna.teleport:443 points at a Teleport proxy which users can access.

Port 443 on the Teleport container is published to the local host, so you can access the invitation page at https://localhost/web/invite/your-token-here.

Insecure Certificate Error

If you encounter an "Insecure Certificate Error" (or equivalent warning) that prevents the Teleport Web UI from opening, you can perform one of the following actions depending on your browser:

  • In Safari's "This Connection Is Not Private" page, click "Show Details," then click "visit this website."
  • In Firefox, click "Advanced" from the warning page, then click "Accept the Risk and Continue."
  • In Chrome's warning page, type thisisunsafe to ignore certificate validation for the Teleport Web UI.

Next steps

Under the hood

Let's unpack some of the setup that made the demo possible. Teleport's authentication is based on client certificates and certificate authorities.

Here is ssh.cfg that instructs ssh client to use Teleport as a bastion server:

## Hosts with openssh suffix are OpenSSH nodes listening on port 22 as usual
Host *.openssh.teleport
    ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:22

# Hosts without openssh suffix are Teleport nodes listening on port 3022
Host *.teleport !proxy.luna.teleport
    ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:3022

Ansible is set up to use ssh config above:

[defaults]
host_key_checking = True
inventory=/etc/teleport.d/ansible/hosts
remote_tmp=/tmp

[ssh_connection]
scp_if_ssh = True
ssh_args = -F /root/.ssh/config

OpenSSH server is set up to trust Teleport's CA and uses Teleport-issued host certificate:

TrustedUserCAKeys /mnt/shared/certs/teleport.pub
HostKey /mnt/shared/certs/mars.openssh.teleport
HostCertificate /mnt/shared/certs/mars.openssh.teleport-cert.pub

Teleport's user and role for used for bot access:

kind: role
version: v5
metadata:
  name: bot
spec:
  # SSH options used for user sessions
  options:
    # max_session_ttl defines the TTL (time to live) of SSH certificates
    # issued to the users with this role.
    max_session_ttl: 10h

  # allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. by default nothing is allowed.
  allow:
    logins: ['root']
    node_labels:
      '*': '*'
---
kind: user
version: v2
metadata:
  name: bot
spec:
  roles: ['bot']

Our lab uses admin tool tctl to generate and export certs:

Exports user CA for OpenSSH to trust.

tctl auth export --type=user | sed s/cert-authority\ // > ./teleport.pub

Export host CA for SSH client to trust, update some hostnames match patterns

tctl auth export --type=host | sed s/*.teleport/luna.teleport,*.luna.teleport,*.openssh.teleport/ > ./teleport-known_hosts.pub

Creates a user and a role in Teleport

tctl create -f /etc/teleport.d/scripts/resources.yaml

Create SSH cert for bot user

tctl auth sign --user=bot --format=openssh --out=bot --overwrite --ttl=10h

Create SSH host cert for SSH node

tctl auth sign --host=mars.openssh.teleport --format=openssh --overwrite --out=mars.openssh.teleport

Adds generated certs to SSH agent on start

cd /mnt/shared/certs && /usr/bin/ssh-add bot;