Get Started with Teleport Enterprise

This guide shows you how to get up and running with Teleport Enterprise.

You will be deploying three Teleport services on a single host:

• The Auth Service stores user accounts and your cluster configuration. It provides authentication and authorization for every Teleport service and every user in your cluster.

• The Proxy Service routes client connection requests to the appropriate Teleport services and serves the Teleport Web UI, which you can use to access resources or manage the cluster.

• The SSH Service is an SSH server implementation that provides seamless access to Linux hosts in your cluster.

  SSH Service instances are called Teleport Nodes. When a Teleport Node receives a connection request, the request is authenticated through the cluster's Auth Service.

  Other Teleport services provide access to remote desktops, Kubernetes clusters, applications, and databases.

You will install the teleport binary, which runs runs all three of these services by default.

You will also use the following client tools:

Prerequisites

• A Teleport Enterprise account. If you do not have one, use our signup form to schedule a demo with the Teleport Sales Team.
• A Linux machine with only port 443 open to ingress traffic. You must be able to install and run software on the machine. Either configure access to your machine via SSH for the initial setup (and open an SSH port in addition port 443) or enter the commands in this guide into an Amazon EC2 user data script, Google Compute Engine startup script, or similar.
• A two-factor authenticator app such as Authy, Google Authenticator, or Microsoft Authenticator.
• python3 installed on your Linux machine. We will use this to run a simple HTTP file server, so you can use another HTTP server if you have one installed.

You must also have one of the following:

• A registered domain name.
• An authoritative DNS nameserver managed by your organization, plus some means of obtaining a TLS certificate and private key for your Teleport deployment. If using this approach, ensure that your browser is configured to use your organization's nameserver.

Step 1/5. Create DNS records

Teleport uses TLS to provide secure access to its Proxy Service and Auth Service, and this requires a domain name that clients can use to verify Teleport's certificate.

Set up two A DNS records: tele.example.com for all traffic and *.tele.example.com for web apps using Application Access. We are assuming that your domain name is example.com. Use your own subdomain instead of tele.

Tip for finding AWS zone id by the domain name.
MYIP="$(curl https://ipv4.icanhazip.com/)"
MYZONE_DNS="example.com"
MYZONE=$(aws route53 list-hosted-zones-by-name --dns-name=${MYZONE_DNS?} | jq -r '.HostedZones[0].Id' | sed s_/hostedzone/__)
The fully qualified domain name for your Teleport Proxy Service.
These commands will also create an A record for a wildcard subdomain.
MYDNS="tele.example.com"
Create a JSON file changeset for AWS.
jq -n --arg ip ${MYIP?} --arg dns ${MYDNS?} '{"Comment": "Create records", "Changes": [{"Action": "CREATE","ResourceRecordSet": {"Name": $dns, "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}},{"Action": "CREATE", "ResourceRecordSet": {"Name": ("*." + $dns), "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}}]}' > myrecords.json
Review records before applying.
cat myrecords.json | jq
Apply the records and capture change id
CHANGEID=$(aws route53 change-resource-record-sets --hosted-zone-id ${MYZONE?} --change-batch file://myrecords.json | jq -r '.ChangeInfo.Id')
Verify that change has been applied
aws route53 get-change --id ${CHANGEID?} | jq '.ChangeInfo.Status'
"INSYNC"

MYZONE="myzone"
The fully qualified domain name for your Teleport Proxy Service.
These commands will also create an A record for a wildcard subdomain.
MYDNS="tele.example.com"
MYIP="$(curl https://ipv4.icanhazip.com/)"
gcloud dns record-sets transaction start --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="*.${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction describe --zone="${MYZONE?}"
gcloud dns record-sets transaction execute --zone="${MYZONE?}"

dig tele.example.com

Step 2/5. Run a simple web service

Create a directory on your Linux machine called demo-app and run the following command:

cat<<EOF>>demo-app/index.html<!DOCTYPE html><html><head><title>Welcome!</title><head><body><h1>Welcome to your Teleport cluster!</h1></body></html>EOF

Run a simple HTTP service on port 9000 that returns your welcome page:

nohup python3 -m http.server 9000 --directory demo-app &

Since port 9000 is not open on your Linux host, there is currently no way to access the web service from your local machine. We will configure Teleport to enable you to access the web service securely.

Step 3/5. Set up Teleport

Install the teleport binary

On the host where you will run your Teleport services, run the following commands to install the teleport binary:

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-amd64-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-ent-v11.3.1-linux-amd64-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.1-linux-amd64-fips-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-ent-v11.3.1-linux-amd64-fips-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-amd64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-ent-v11.3.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.1-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-ent-v11.3.1-linux-amd64-bin.tar.gz
cd teleport-ent
sudo ./install

Configure Teleport

Generate a configuration file for Teleport using the teleport configure command. This command requires information about a TLS certificate and private key.

If you are exposing your Teleport host to the internet, we recommend using Let's Encrypt to receive your key and certificate automatically. For private networks or custom deployments, use your own private key and certificate.

If you are running Teleport on the internet, we recommend using Let's Encrypt to receive your key and certificate automatically. For private networks or custom deployments, use your own private key and certificate.

DOMAIN=tele.example.com
[email protected]
teleport configure --acme --acme-email=${EMAIL?} --cluster-name=${DOMAIN?} | \sudo tee /etc/teleport.yaml > /dev/null

proxy_service:
  enabled: "yes"
  web_listen_addr: 0.0.0.0:443
  public_addr: tele.example.com:443
  acme:
    enabled: "yes"
    email: [email protected]

sudo teleport configure -o file \    --cluster-name=tele.example.com \    --public-addr=tele.example.com:443 \    --cert-file=/var/lib/teleport/fullchain.pem \    --key-file=/var/lib/teleport/privkey.pem

Next, configure Teleport to provide secure access to your web service. Edit your Teleport configuration file (/etc/teleport.yaml) to include the following, replacing teleport.example.com with the domain name of your Teleport cluster.

app_service:
    enabled: yes
    apps:
    - name: "demo"
      uri: "http://localhost:9000"
      public_addr: "demo.teleport.example.com"

Obtain your license file

The teleport binary reads a local license file to authenticate your Teleport Enterprise account.

To obtain your license file, visit the Teleport customer dashboard and log in. Click "DOWNLOAD LICENSE KEY". You will see your current Teleport Enterprise account permissions and the option to download your license file:

Save your license file on the host where you will install Teleport at the path, /var/lib/teleport/license.pem.

Start Teleport

On the host where you are running Teleport, generate a systemd unit file for Teleport and save it in /etc/systemd/system/teleport.service:

sudo teleport install systemd -o /etc/systemd/system/teleport.service

Enable the Teleport service and start Teleport in the background:

sudo systemctl enable teleport
sudo systemctl start teleport

Confirm that the teleport service has started:

$ sudo systemctl status teleport

Get information about your Teleport deployment

You can review the logs of the Teleport service with the following command:

journalctl -fu teleport

Run the following command to review the ports that Teleport is listening on:

sudo netstat -lptne

The output should look something like this:

sudo netstat -lptne | grep teleport
tcp6       0      0 :::443                  :::*                    LISTEN
0          168760     29504/teleport    
tcp6       0      0 :::3022                 :::*                    LISTEN
0          167812     29504/teleport    
tcp6       0      0 :::3025                 :::*                    LISTEN
0          168741     29504/teleport

Step 4/5. Add a local user

Create a user

Every user in a Teleport cluster must be assigned at least one role. By default, Teleport comes with several pre-configured roles known as presets:

You can see the full configurations for these roles by executing the following command on the host running Teleport:

sudo tctl get roles

On the host where you are running Teleport, create a Teleport user called myuser with the access role and the ubuntu login. This user can log in to any host in your infrastructure as ubuntu (choose a login that matches a user account on your Linux host):

sudo tctl users add --roles=access --logins=ubuntu myuser
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

Navigate to the link displayed in your terminal, pick a password, and configure second factor authentication.

Log in as your new user

tsh is our client tool. It helps you log in to Teleport clusters and obtain short-lived credentials. It can also be used to list resources registered with Teleport, such as servers, applications, and Kubernetes clusters.

Install tsh on your local machine:

curl -O https://get.gravitational.com/teleport-ent-11.3.1.pkg
Installs on Macintosh HD
sudo installer -pkg teleport-ent-11.3.1.pkg -target /
Password:
installer: Package name is teleport-ent-11.3.1
installer: Upgrading at base path /
installer: The upgrade was successful.
which teleport
/usr/local/bin/teleport

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v11. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v11" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v11. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v11/teleport.repo")
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v11.3.1-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v11.3.1-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.1-linux-
-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v11.3.1-linux-
-bin.tar.gz
cd teleport
sudo ./install

dpkg -i ~/Downloads/teleport-ent_11.3.1_
.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_11.3.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 11.3.1 ...
Setting up teleport-ent 11.3.1 ...

rpm -i ~/Downloads/teleport-ent-11.3.1.
.rpm
warning: teleport-ent-11.3.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v11.3.1-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.1-linux-
-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v11.3.1-linux-
-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz
cd teleport-ent
sudo ./install

dpkg -i ~/Downloads/teleport-ent_11.2.1_
.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_11.2.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 11.2.1 ...
Setting up teleport-ent 11.2.1 ...

rpm -i ~/Downloads/teleport-ent-11.2.1.
.rpm
warning: teleport-ent-11.2.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.2.1-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v11.2.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v11.2.1-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v11.2.1-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

Get the expected checksum for the Windows tsh package
$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v11.3.1-windows-amd64-bin.zip.sha256
PowerShell will return the binary representation of the response content
by default, so you need to convert it to a string
[System.Text.Encoding]::UTF8.getstring($Resp.Content)
<checksum> <filename>
curl -O teleport-v11.3.1-windows-amd64-bin.zip https://get.gravitational.com/teleport-v11.3.1-windows-amd64-bin.zip
certUtil -hashfile teleport-v11.3.1-windows-amd64-bin.zip SHA256
SHA256 hash of teleport-v11.3.1-windows-amd64-bin.zip:
<checksum>
CertUtil: -hashfile command completed successfully.

Expand-Archive teleport-v11.3.1-windows-amd64-bin.zip
cd teleport-v11.3.1-windows-amd64-bin\teleport
.\tsh.exe version
Teleport v11.3.1 git:v11.3.1 go1.19

Use tsh to log in to your Teleport cluster as myuser, replacing auth.example.com with the domain name you configured earlier:

tsh --proxy=auth.example.com login --user=myuser

Note that you can omit the --user flag if the $USER environment variable is equal to your Teleport username.

If successful, the tsh login command will retrieve a user certificate for myuser and store it in the ~/.tsh/keys/<proxy> directory.

With a certificate in place, myuser can now interact with the Teleport cluster.

Step 5/5. Access resources

You have now completed setting up Teleport and signed in to your cluster. Now you can use Teleport to quickly access resources.

Visit your demo website

Now that you have logged in to Teleport, you can see the demo website you started earlier. Visit https://demo.teleport.example.com, replacing teleport.example.com with the domain name of your Teleport cluster. You can only visit the website if you have authenticated with your cluster.

You can use the Teleport Application Service to configure access to any web application in your private network, including HTTP management endpoints for popular infrastructure technologies.

SSH into your Node

You also configured the Teleport SSH Service, meaning that you can easily access your Linux machine after logging in to Teleport.

See the logins you can use to access a Node:

tsh status
> Profile URL:        https://teleport.example.com:443
  Logged in as:       teleport-admin
  Cluster:            teleport.example.com
  Roles:              access, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2022-04-26 04:55:59 -0400 EDT [valid for 11h38m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

List all SSH servers connected to Teleport:

tsh ls
Node Name        Address        Labels                                
---------------- -------------- ------------------------------------- 
mynode 127.0.0.1:3022 env=example,hostname=mynode

SSH into your Node, replacing mynode with one of the Nodes listed by the tsh ls command and ubuntu with the login on your Linux host that you configured myuser to access:

tsh ssh [email protected]

Next steps

Deploy on Kubernetes

This guide shows you how to install Teleport Enterprise on a virtual machine. If you are using a Kubernetes-based environment, see our Getting Started Guide for how to deploy Teleport on Kubernetes.

Configure RBAC

The preset access role we assigned to a user in this guide is probably too permissive for your environment. Read our guide to configuring Teleport roles to set up more granular access controls.

Configure SSO

In this guide, we created a local user stored on the Teleport Auth Service. For on and offboarding users at scale, you should use one of Teleport's Single Sign-On integrations.

Take a look at our Single Sign-On guide to learn the basics of integrating Teleport with SSO providers.

You can configure any SAML- or OIDC-compliant identity provider to enable SSO for Teleport. There are Teleport Enterprise customers who are using Oracle IDM, SailPoint, and others.

Configure Access Requests

With Teleport Access Requests you can provide your users limited access to resources by default. Your users can then access elevated privileges on a temporary basis, minimizing the risk that an attacker will compromise an admin account.

Read our guide to setting up Access Requests.

You can then take advantage of Teleport's Access Request plugins so users can request and review Access Requests using your existing communication workflows.

Troubleshooting

If Teleport services do not start, take a look at the teleport service's logs:

sudo journalctl -fu teleport

Usually the error will be reported there. Common reasons for failure are:

• Network issues: port 443 is closed via iptables or occupied by another process.
• Disk issues: Teleport fails to create /var/lib/teleport because the volume is read-only or not accessible.

Getting Help

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.