Fork me on GitHub
Teleport

Server Access Getting Started Guide

Improve
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

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 8.0.7 installed locally.

The examples below may include the use of the sudo keyword, token UUIDs, and users with elevated privileges to make following each step easier.

We recommend you follow the best practices to avoid security incidents:

  1. Avoid using sudo in production environments unless it's necessary.
  2. Create new, non-root, users and use test instances for experimenting with Teleport.
  3. You can run many Teleport's services as a non root. For example, auth, proxy, application access, kubernetes access, and database access services can run as a non-root user. Only the SSH/node service requires root access. You will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443)
  4. Follow the "Principle of Least Privilege" (PoLP) and "Zero Admin" best practices. Don't give users permissive roles when giving them more restrictive access,editor roles will do instead.
  5. Save tokens into a file rather than sharing tokens directly as strings.

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

    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

    curl https://deb.releases.teleport.dev/teleport-pubkey.asc | sudo apt-key add -
    sudo add-apt-repository 'deb https://deb.releases.teleport.dev/ stable main'
    sudo apt-get update
    sudo apt-get install teleport
    curl -O https://get.gravitational.com/teleport-v8.0.7-linux-amd64-bin.tar.gz
    tar -xzf teleport-v8.0.7-linux-amd64-bin.tar.gz
    cd teleport
    sudo ./install
    curl -O https://get.gravitational.com/teleport-v8.0.7-linux-arm-bin.tar.gz
    tar -xzf teleport-v8.0.7-linux-arm-bin.tar.gz
    cd teleport
    sudo ./install
    curl -O https://get.gravitational.com/teleport-v8.0.7-linux-arm64-bin.tar.gz
    tar -xzf teleport-v8.0.7-linux-arm64-bin.tar.gz
    cd teleport
    sudo ./install
  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

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:

ssh -J tele.example.com [email protected]

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