Fork me on GitHub
Teleport

Server Access Getting Started Guide

Teleport Server Access - Intro and Getting Started

Teleport Server Access - Intro and Getting Started

Length: 17:14

Getting Started

Server Access often involves managing your resources, configuring new clusters, and issuing commands through a CLI or programmatically to an API.

This guide introduces some of these common scenarios and how to interact with Teleport to accomplish them:

  1. Creating a Teleport Auth Node cluster we'll add a Teleport SSH Node to.
  2. SSH into the cluster using Teleport.
  3. Introspecting the cluster using Teleport features.
Tip
This guide also demonstrates how to configure Teleport Nodes into the Bastion pattern so that only a single Node can be accessed publicly.
Teleport Bastion
Teleport Bastion

Prerequisites

  • Two instances of your favorite Linux environment (such as Ubuntu 20.05, CentOS 8.0-1905, or Debian 10).
  • A registered Domain Name with an available subdomain like tele.example.com.
  • A Two-Factor Authentication app (such as Authy or Google Authenticator).
  • Teleport 7.1.3 installed locally.
Tip

The examples below may include the use of the sudo keyword, token UUIDs, and users with admin privileges to make following each step easier when creating resources from scratch.

Generally:

  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

Step 1/4. Create a cluster

  1. Create two new instances of your desired Linux distribution (such as Ubuntu 20.05, CentOS 8.0-1905, or Debian 10).

    The first instance will host a public-facing Auth Node tele.example.com that will serve as the Bastion Host (following the recommended Bastion-pattern). As such, leave the following ports open:

    PortServiceDescription
    3023ProxySSH port clients connect to. A proxy will forward this connection to port #3022 on the destination Node.
    3024Proxy SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server.
    443BrowserUsed to access the Teleport Web UI through a browser with HTTPS. Also used to obtain an ACME TLS (SSL) certificate.
    22Cloud ProviderUsed to initially access, configure, and provision your cloud instances. We'll configure and launch our instances then demonstrate how to use the tsh tool and Teleport in SSH mode thereafter.

    Add an A record in your domain registrar entry for the tele subdomain and map the first IP address to the tele subdomain.

    Subdomain and IP mapping
    Subdomain and IP mapping

    Your second instance will be a private resource. These are the ports you'll want to initially open:

    PortServiceDescription
    22Cloud ProviderUsed to initially access, configure, and provision your cloud instances. We'll configure and launch our instances then demonstrate how to use the tsh tool and Teleport in SSH mode thereafter.
  2. Install Teleport on each instance.

    sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
    sudo yum install teleport

    Optional: Using DNF on newer distributions

    $ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

    $ sudo dnf install teleport

  3. Configure Teleport on the Bastion Host.

    Teleport will now automatically acquire an X.509 certificate using the ACME protocol.

    Configure Teleport with TLS certs

    sudo teleport configure \ --acme [email protected] \ --cluster-name=tele.example.com \ -o file

    Run the command above on tele.example.com.

  4. Launch your Bastion Host by running:

    Launch Teleport

    sudo teleport start

    Next, we'll create a join token to add and start the second Node.

Step 2/4. Add a Node to the cluster

  1. Create a join token to add the second Node to the tele.example.com cluster. In a Bastion Host terminal run the following command:

    Let's save the token to a file

    sudo tctl tokens add --type=node | grep -oP '(?<=token:\s).*' > token.file

    Each Teleport Node can be configured into SSH mode (Teleport Node) and run as an enhanced SSH server. "Node" mode specifies that the Teleport Node will act and join as an SSH server.

    > token.file indicates that you'd like to save the output to a file name token.file.

    Tip
    This helps to minimize the direct sharing of tokens even when they are dynamically generated.
  2. Now, create a third terminal and connect to tele.example.com.

    • Save token.file to an appropriate, secure, directory you have the rights and access to read on the second instance.

    Join cluster

    sudo teleport start \ --roles=node \ --token=/path/to/token.file \ --auth-server=tele.example.com:443
    • Replace the auth-server value with the public proxy address of the machine you wish to connect to. By default, the subdomain tele.example.com will be available on port 443.
    • Supply the secured path to the new Node's token.file.
  3. Create a user to access the tele.example.com Web UI through the following command:

    sudo tctl users add tele-admin --roles=editor,access --logins=root,ubuntu,ec2-user

    This will generate an initial login link where you can set a password and set up Two-Factor Authentication for tele-admin.

    Note
    We've only given tele-admin the roles editor and access according to the Principle of Least Privilege (POLP).
  4. You should now be able to view both Nodes in the Teleport Web interface after logging in as tele-admin:

    Both Nodes in the Web UI
    Both Nodes in the Web UI

Step 3/4. SSH into the server

Now, that we've got our cluster up and running, let's see how easy it is to connect to our two Nodes.

We can use tsh to SSH into the cluster:

  1. On your local machine, log in through tsh:

    Log in through tsh

    tsh login --proxy=tele.example.com --user=tele-admin

    You'll be prompted to supply the password and One Time Passcode we set up previously.

  2. tele-admin will now see:

    Profile URL:        https://tele.example.com:443
      Logged in as:       tele-admin
      Cluster:            tele.example.com
      Roles:              access, editor
      Logins:             root, ubuntu, ec2-user
      Kubernetes:         disabled
      Valid until:        2021-04-30 06:39:13 -0500 CDT [valid for 12h0m0s]
      Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
    

    tele-admin is now logged into the tele.example.com cluster and Bastion Host Node through Teleport SSH.

  3. tele-admin can now execute the following to find the cluster's nodenames. nodenames are used for establishing SSH connections:

    Display cluster resources

    tsh ls

    The Bastion Host Node is located on the bottom line below:

    Node Name        Address        Labels                                 
    ---------------- -------------- -------------------------------------- 
    ip-172-31-35-170 ⟵ Tunnel                                              
    ip-172-31-41-144 127.0.0.1:3022 env=example, hostname=ip-172-31-41-144 
    
  4. tele-admin can SSH into the Bastion Host Node by running the following command locally:

    Use tsh to ssh into a Node

    Now, they can:

    • Connect to other Nodes in the cluster by using the appropriate IP address in the tsh ssh command.
    • Traverse the Linux file system.
    • Execute desired commands.

    All commands executed by tele-admin are recorded and can be replayed in the Teleport Web interface.

    The tsh ssh command allows one to do anything they would if they were to SSH into a server using a third-party tool. Compare the two equivalent commands:

Step 4/4. Use tsh and the unified resource catalog to introspect the cluster

  1. Now, tele-admin has the ability to SSH into other Nodes within the cluster, traverse the Linux file system, and execute commands.

    • They have visibility into all resources within the cluster due to their defined and assigned roles.
    • They can also quickly view any Node or grouping of Nodes that've been assigned a label.
  2. Execute the following command within your Bastion Host console:

    List Nodes

    sudo tctl nodes ls

    It displays the unified resource catalog with all queried resources in one view:

    Nodename         UUID                                 Address        Labels                                
    ---------------- ------------------------------------ -------------- ------------------------------------- 
    ip-172-31-35-170 4980899c-d260-414f-9aea-874feef71747                                                      
    ip-172-31-41-144 f3d2a65f-3fa7-451d-b516-68d189ff9ae5 127.0.0.1:3022 env=example,hostname=ip-172-31-41-144                            
    
  3. Note the "Labels" column on the farthest side. tele-admin can query all resources with a shared label using the command:

    Query all Nodes with a label

    tsh ls env=example
    • Customized labels can be defined in your teleport.yaml configuration file or during Node creation.
    • This is a convenient feature that allows for more advanced queries.
    • Suppose an IP address changes, an admin can quickly find the current Node with that label since it remains unchanged.
  4. tele-admin can also execute commands on all Nodes that share a label vastly simplifying repeated operations. For example, the command:

    Run the ls command on all Nodes with a label

    tsh ssh [email protected]=example ls

    will execute the ls command on each Node displaying the contents of each to the screen.

Conclusion

Note

We previously configured our Linux instances to leave port 22 open to easily configure and install Teleport. Feel free to compare Teleport SSH to your usual ssh commands.

If you'd like to further experiment with using Teleport according to the Bastion pattern:

  • Close port 22 on your second, private, Linux instance now that your Node is configured and running.
  • Optionally close port 22 on your Bastion Host.
  • You'll be able to fully connect to both the Bastion Host and the private instance using tsh ssh.

To recap, this Getting Started Guide described:

  1. How to set up and add an SSH Node to a cluster.
  2. Connect to the cluster using tsh to manage and introspect resources.

Feel free to shut down, clean up, and delete your resources or use them in further Getting Started exercises.

Next steps

Resources

Have a suggestion or can’t find something?
IMPROVE THE DOCS