Welcome to the Quick Start Guide for Teleport Enterprise.
The goal of this document is to show off the basic capabilities of Teleport.
There are three types of services Teleport nodes can run: nodes
, proxies
and auth servers
.
sshd
daemon you may be familiar
with. When a node receives a connection request, the request is authenticated
through the cluster's auth server.The teleport
daemon runs all three of these services by default. This Quick
Start Guide will be using this default behavior to create a cluster and
interact with it using Teleport's client-side tools:
Tool | Description |
---|---|
tctl | Cluster administration tool used to invite nodes to a cluster and manage user accounts. |
tsh | Allows users to authenticate and access resources via their local machine. tsh 's ssh functionality is similar in principle to OpenSSH's ssh . Users can login into remote SSH nodes, list and search for nodes in a cluster, securely upload/download files, etc. |
browser | You can use your web browser to login into any Teleport node by opening https://<proxy-host>:3080 . |
You will need to have access to the customer portal to download the software. You will also need three computers: two servers and one client (probably a laptop) to complete this tutorial. Let's assume the servers have the following DNS names and IPs:
Server Name | IP Address | Purpose |
---|---|---|
"auth.example.com" | 10.1.1.10 | This server will be used to run all three Teleport services: auth, proxy and ssh. |
"node.example.com" | 10.1.1.11 | This server will only run the SSH service. |
This Quick Start Guide assumes that both servers are running a systemd-based
Linux distribution such as Debian, Ubuntu or a RHEL derivative. The node.example.com must be able to connect to the auth.example.com 3025
port and the auth.example.com must be able to connect to the 3022 port on node.example.com.
The instructions below describe how to install Teleport Enterprise directly onto your test system. You can also run Teleport Enterprise using Docker if you don't want to install Teleport Enterprise binaries straight away.
To start using Teleport Enterprise, you will need to Download the binaries and the license file from the customer portal. After downloading the binary tarball, run:
$ tar -xzf teleport-ent-v6.0.0-linux-amd64-bin.tar.gz
$ cd teleport-ent
teleport
and tctl
binaries to a bin directory (we suggest /usr/local/bin
) on the auth server.teleport
binary to a bin directory on the node server.tsh
binary to a bin directory on the client computer.The Teleport license file contains a X.509 certificate and the corresponding private key in PEM format.
Download the license file from the customer portal
and save it as /var/lib/teleport/license.pem
on the auth server.
Next, download the systemd service unit file from examples directory
on Github and save it as /etc/systemd/system/teleport.service
on both servers.
# run this on both servers:
$ sudo systemctl daemon-reload
$ sudo systemctl enable teleport
Save the following configuration file as /etc/teleport.yaml
on the auth.example.com:
teleport:
nodename: auth.example.com
auth_token: dogs-are-much-nicer-than-cats
auth_servers: [ "localhost:3025" ]
proxy_service:
# enable the proxy service
enabled: true
auth_service:
# enable the auth service:
enabled: true
tokens:
# this static token is used for other nodes to join this Teleport cluster
- proxy,node:dogs-are-much-nicer-than-cats
# this token is used to establish trust with other Teleport clusters
- trusted_cluster:trains-are-superior-to-cars
# by default, local authentication will be used with 2FA
authentication:
second_factor: otp
# SSH is also enabled on this node:
ssh_service:
enabled: "yes"
Start the Teleport service and confirm the service has started. After it has started you can get the Certificate Authority (CA) pin that has been generated.
$ sudo systemctl start teleport
# confirm Teleport started
$ sudo systemctl status teleport
# after successful start retrieve the CA pin for using in the node
$ sudo tctl status
Cluster teleport
Version 6.0
Host CA never updated
User CA never updated
Jwt CA never updated
CA pin sha256:58b1c5cb8885d84ce08f3e3a47acb33d49841f12dd7648c0c1dd31bd501628
Save the following configuration file as /etc/teleport.yaml
on the node.example.com:
!!! note "Note"
Make sure to replace the ca_pin with the above tctl status
output and the right auth server address.
teleport:
nodename: node.example.com
auth_token: dogs-are-much-nicer-than-cats
# you can also use auth server's IP, i.e. "10.1.1.10:3025"
auth_servers: [ "auth.example.com:3025" ]
# Set the ca_pin value so it can verify the Teleport server
ca_pin: sha256:58b1c5cb8885d84ce08f3e...
# enable ssh service and disable auth and proxy:
ssh_service:
enabled: true
auth_service:
enabled: false
proxy_service:
enabled: false
# run this on node server:
$ sudo systemctl start teleport
# Confirm node has started successfully and connected
$ sudo systemctl status teleport
You can review the logs of the Teleport service with journalctl -fu teleport
and see its current status
with sudo systemctl status teleport
.
You can use netstat -lptne
to review the port that Teleport is
listening on on TCP/IP ports. On auth.example.com, it should
look something like this:
$ auth.example.com ~: sudo netstat -lptne
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address State User PID/Program name
tcp6 0 0 :::3024 LISTEN 0 337/teleport
tcp6 0 0 :::3025 LISTEN 0 337/teleport
tcp6 0 0 :::3080 LISTEN 0 337/teleport
tcp6 0 0 :::3022 LISTEN 0 337/teleport
tcp6 0 0 :::3023 LISTEN 0 337/teleport
and node.example.com should look something like this:
$ node.example.com ~: sudo netstat -lptne
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address State User PID/Program name
tcp6 0 0 :::3022 LISTEN 0 337/teleport
See troubleshooting section at the bottom if something is not working.
This portion of the Quick Start Guide should be performed on the auth server, i.e. on auth.example.com
Every user in a Teleport cluster must be assigned at least one role. By
default, Teleport comes with one pre-configured role called "admin". You can
see it's definition by executing sudo tctl get roles/admin > admin-role.yaml
.
The output will look like this (re-formatted here to use compact YAML representation for brevity):
kind: role
metadata:
name: admin
spec:
allow:
logins:
- '{{internal.logins}}'
- root
node_labels:
'*': '*'
app_labels:
'*': '*'
kubernetes_groups:
- '{{internal.kubernetes_groups}}'
kubernetes_labels:
'*': '*'
kubernetes_users:
- '{{internal.kubernetes_users}}'
rules:
- resources: [role]
verbs: [list, create, read, update, delete]
- resources: [auth_connector]
verbs: [list, create, read, update, delete]
- resources: [user]
verbs: [list, create, read, update, delete]
- resources: [session]
verbs: [list, read]
- resources: [event]
verbs: [list, read]
- resources: [trusted_cluster]
verbs: [list, create, read, update, delete]
- resources: [token]
verbs: [list, create, read, update, delete]
deny: {}
options:
forward_agent: true
max_session_ttl: 30h0m0s
port_forwarding: true
version: v3
Pay attention to the allow/logins field in the role definition: by default, this
role only allows SSH logins as [email protected]
.
Ignore {{internal.logins}}
"allowed login" for now. It exists for
compatibility purposes when upgrading existing open source Teleport
clusters.
You probably want to replace "root" with something else. Let's assume there will be a local UNIX account called "admin" on all hosts. In this case you can dump the role definition YAML into admin-role.yaml file and update "allow/logins" to look like this:
allow:
logins: [admin]
See the Kubernetes Guide and Application Guide for enabling access to additional resources.
Then send it back into Teleport:
$ sudo tctl create -f admin-role.yaml
Now, lets create a new Teleport user "joe" with "admin" role:
$ sudo tctl users add --roles=admin joe
Signup token has been created and is valid for 1 hours. Share this URL with the user:
https://auth.example.com:3080/web/newuser/22e3acb6a0c2cde22f13bdc879ff9d2a
Share the generated sign-up URL with Joe and let him pick a password and configure the second factor authentication. We recommend Google Authenticator which is available for both Android and iPhone.
To update user's roles, dump the user resource into a file:
$ sudo tctl get users/joe > joe.yaml
Edit the YAML file and update the "roles" array. Then, re-insert it back:
$ sudo tctl create -f joe.yaml
Joe now has a local account on a Teleport cluster. The local account is good for administrative purposes but regular users of Teleport Enterprise should be using a Single Sign-On (SSO) mechanism.
But first, lets see how Joe can log into the Teleport cluster. He can do this on his client laptop:
$ tsh --proxy=auth.example.com --insecure login --user=joe
Note that "--user=joe" part can be omitted if $USER
environment variable is "joe".
Notice that tsh
client always needs --proxy
flag because all client connections
in Teleport always must to go through an SSH proxy, sometimes called an "SSH bastion".
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. Your browser will
throw a warning Your connection is not private. Click Advanced, and Proceed to 0.0.0.0 (unsafe)
to preview the Teleport UI.
Never use --insecure
in production unless you terminate SSL at a load balancer. This will
apply to most cloud providers (AWS, GCP and Azure). You must configure a HTTP/TLS certificate for the Proxy.
This process has been made easier with Let's Encrypt. We've instructions here.
If successful, tsh login
command will receive Joe's user certificate and will
store it in ~/.tsh/keys/<proxy>
directory.
With a certificate in place, Joe can now interact with the Teleport cluster:
# SSH into any host behind the proxy:
$ tsh ssh node.example.com
# See what hosts are available behind the proxy:
$ tsh ls
# Log out (this will remove the user certificate from ~/.tsh)
$ tsh logout
The local account is good for administrative purposes but regular users of Teleport Enterprise should be using a Single Sign-On (SSO) mechanism that use SAML or OIDC protocols.
Take a look at the SSH via Single Sign-on chapter to learn the basics of integrating Teleport with SSO providers. We have the following detailed guides for configuring SSO providers:
Any SAML-compliant provider can be configured with Teleport by following the same steps. There are Teleport Enterprise customers who are using Oracle IDM, SailPoint and others.
We provide pre-built Docker images for every version of Teleport Enterprise. These images are hosted on quay.io.
We currently only offer Docker images for x86_64
architectures.
You will need a recent version of Docker installed to follow this section of the quick start guide.
This setup will not let you 'SSH into' the node that is running Teleport without additional configuration.
This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are automatically rebuilt every night. These nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
Image name | Community or Enterprise? | Teleport version | Image automatically updated? | Image base |
---|---|---|---|---|
quay.io/gravitational/teleport-ent:6.0 | Enterprise | The latest version of Teleport Enterprise 6.0 | Yes | Ubuntu 20.04 |
quay.io/gravitational/teleport-ent:6.0-fips | Enterprise FIPS | The latest version of Teleport Enterprise 6.0 FIPS | Yes | Ubuntu 20.04 |
quay.io/gravitational/teleport-ent:6.0.0 | Enterprise | The version specified in the image's tag (i.e. 6.0.0) | No | Ubuntu 20.04 |
quay.io/gravitational/teleport-ent:6.0.0-fips | Enterprise FIPS | The version specified in the image's tag (i.e. 6.0.0) | No | Ubuntu 20.04 |
For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently quay.io/gravitational/teleport-ent:6
.
You will need a recent version of docker-compose
installed to follow this section of the quick start guide.
The easiest way to start Teleport Enterprise quickly is to use docker-compose
with our teleport-ent-quickstart.yml
file:
# download the quickstart file from our Github repo
curl -Lso teleport-ent-quickstart.yml https://raw.githubusercontent.com/gravitational/teleport/master/docker/teleport-ent-quickstart.yml
# start teleport quickstart using docker-compose
docker-compose -f teleport-ent-quickstart.yml up
docker-compose
quickstart will automatically create a config file for you at ./docker/teleport/config/teleport.yaml
/etc/teleport/teleport.yaml
teleport
using this config file, with Teleport's data directory set to ./docker/teleport/data
and mounted under /var/lib/teleport
license.pem
) from the current directory into the Docker containerdocker-compose
will output Teleport's logs to the console for you to observe.docker-compose -f teleport-ent-quickstart.yml up -d
docker-compose -f teleport-ent-quickstart.yml down
If you'd prefer to complete these steps manually, here's some sample docker run
commands:
# create local config and data directories for teleport, which will be mounted into the container
mkdir -p ~/teleport/config ~/teleport/data
# download your license file from the Gravitational dashboard and put it in the correct directory
# the file needs to be named license.pem
cp ~/downloads/downloaded-license.pem ~/teleport/data/license.pem
# generate a sample teleport config and write it to the local config directory
# this container will write the config and immediately exit - this is expected
docker run --hostname localhost --rm \
--entrypoint=/bin/sh \
-v ~/teleport/config:/etc/teleport \
quay.io/gravitational/teleport-ent:6 -c "teleport configure > /etc/teleport/teleport.yaml"
# change the path to the license file in the sample config
sed -i 's_/path/to/license-if-using-teleport-enterprise.pem_/var/lib/teleport/license.pem_g' ~/teleport/config/teleport.yaml
# start teleport with mounted license, config and data directories, plus all ports
docker run --hostname localhost --name teleport \
-v ~/teleport/config:/etc/teleport \
-v ~/teleport/data:/var/lib/teleport \
-p 3023:3023 -p 3025:3025 -p 3080:3080 \
quay.io/gravitational/teleport-ent:6
To create a user inside your Teleport Enterprise container, use docker exec
.
This example command will create a Teleport user called testuser
which has the admin
role. Feel free to change these to suit your needs.
docker exec teleport tctl users add testuser --roles=admin
When you run this command, Teleport will output a URL which you must open to complete the user signup process:
User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s:
https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7
NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.
You can now follow this guide from "Adding Users" onwards to create your user and log into Teleport Enterprise.
If Teleport services do not start, take a look at the syslog:
$ sudo journalctl -fu teleport
Usually the error will be reported there. Common reasons for failure are:
3025
is closed via iptables.3025
or 3022
are occupied by another process./var/lib/teleport
because the volume is read-only or not accessible.If something is not working, please reach out to us by creating a ticket in your customer portal. Customers who have purchased the premium support package can also ping us through your Slack channel.