# Server Access Getting Started Guide

You can protect a server with Teleport by running the Teleport SSH Service on the server and enrolling it in your Teleport cluster.

This guide shows you how to:

- Enroll a server in your Teleport cluster.
- SSH into a server using Teleport.
- Inspect server resources in the cluster using Teleport commands.

## How it works

The Teleport SSH Service opens a reverse SSH tunnel to the Teleport Proxy Service, and SSH client traffic uses this tunnel to connect to a server. This setup is similar to the [bastion pattern](https://goteleport.com/blog/ssh-bastion-host/).

Once a server has joined your cluster, the Teleport RBAC system enforces secure access to the server, and administrators can identify security threats using the Teleport audit log.

You can use Teleport to enable secure access to a Kubernetes node. To do so, modify your node's machine image to install and run the Teleport SSH Service as per the instructions in this guide. Do not run the SSH Service as a Kubernetes pod, as there is no guarantee that the SSH Service pod is running on a server that a user intends to access.

## Prerequisites

- A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

- The `tctl` and `tsh` clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tctl` and `tsh` clients:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* One host running a Linux environment (such as Amazon Linux, Ubuntu, CentOS Stream, or Debian). This will serve as a Teleport Node.
* To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  18.7.3
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
  ```
  If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions.

Best practices for production security

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

- Avoid using `sudo` in production environments unless it's necessary.
- Create new, non-root, users and use test instances for experimenting with Teleport.
- Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the `CAP_NET_BIND_SERVICE` capability) to make Teleport listen on a port numbered < `1024` (e.g. `443`).
- Follow the **principle of least privilege**. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in `access,editor` roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure **Access Requests** to provide temporary elevated permissions.
- When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the `history` command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

## Step 1/4. Install Teleport on your Linux host

1. Your Linux host will be a private resource. Open port 22 so you can initially access, configure, and provision your instance.

   We'll configure and launch our instance, then demonstrate how to use the `tsh` tool and Teleport in SSH mode.

2. On the host where you will run the Teleport SSH Service, follow the instructions for your environment to install Teleport.

   To install a Teleport Agent on your Linux server:

   The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

   1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://).

   2. Run your cluster's install script:

      ```
      $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
      ```

   Next, we'll create a **join token** so you can start the Teleport SSH Service and add it to your cluster.

## Step 2/4. Add a server to the cluster

### Create a join token

On your local workstation, create a join token so you can add the server to your Teleport cluster:

```
Let's save the token to a file
$ tctl tokens add --type=node --format=text > token.file
```

`--type=node` specifies that the Teleport process 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.

---

### Join your server to the cluster

On your server, save `token.file` to an appropriate, secure, directory you have the rights and access to read. Next, generate a configuration file enabling Teleport's SSH Service.

**Self-Hosted**

Change `tele.example.com` to the address of your Teleport Proxy Service. Assign the `--token` flag to the path where you saved `token.file`.

```
Generate config
$ sudo teleport node configure \
   --output=file:///etc/teleport.yaml \
   --token=/path/to/token.file \
   --proxy=tele.example.com:443
```

**Teleport Enterprise Cloud**

Change `mytenant.teleport.sh` to your Teleport Cloud tenant address. Assign the `--token` flag to the path where you saved `token.file`.

```
Generate config
$ sudo teleport node configure \
   --output=file:///etc/teleport.yaml \
   --token=/path/to/token.file \
   --proxy=mytenant.teleport.sh:443
```

The `teleport node configure` command above placed a configuration file at `/etc/teleport.yaml`. The last step is to start Teleport, pointing it at this configuration:

Configure the Teleport SSH Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport SSH Service.

**Package Manager**

On the host where you will run the Teleport SSH Service, enable and start Teleport:

```
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

**TAR Archive**

On the host where you will run the Teleport SSH Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

```
$ sudo teleport install systemd -o /etc/systemd/system/teleport.service
$ sudo systemctl enable teleport
$ sudo systemctl start teleport
```

You can check the status of the Teleport SSH Service with `systemctl status teleport` and view its logs with `journalctl -fu teleport`.

### Access the Web UI

Run the following command to create a local user that can access the Teleport Web UI:

```
$ tctl users add myuser --roles=editor,access --logins=root,ubuntu,ec2-user
```

This will generate an initial login link where you can create a password and set up multi-factor authentication for `myuser`.

---

NOTE

We've only given `myuser` the roles `editor` and `access` according to the Principle of Least Privilege.

---

You should now be able to view your server in the Teleport Web UI after logging in as `myuser`:

![Both servers in the Web UI](/docs/assets/images/teleport_ui-523637e579d919605fbb26eb17ecf072.png)

## 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 server.

We can use `tsh` to SSH into the cluster:

### Log in to the cluster

**Self-Hosted**

On your local machine, log in to your cluster through `tsh`, assigning the `--proxy` flag to the address of your Teleport Proxy Service:

```
Log in through tsh
$ tsh login --proxy=tele.example.com --user=myuser
```

**Teleport Enterprise Cloud**

On your local machine, log in to your cluster through `tsh`, assigning the `--proxy` flag to the address of your Teleport Cloud tenant:

```
Log in through tsh
$ tsh login --proxy=mytenant.teleport.sh:443 --user=myuser
```

You'll be prompted to supply the password and authentication factor we set up previously.

`myuser` will now see something similar to:

**Self-Hosted**

```
> Profile URL:      https://tele.example.com:443
Logged in as:       myuser
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

```

In this example, `myuser` is now logged into the `tele.example.com` cluster through Teleport SSH.

**Teleport Enterprise Cloud**

```
> Profile URL:        https://mytenant.teleport.sh:443
Logged in as:       myuser
Cluster:            mytenant.teleport.sh
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

```

In this example, `myuser` is now logged into the `mytenant.teleport.sh` cluster through Teleport SSH.

### Display cluster resources

`myuser` can now execute the following to find the cluster's server names, which are used for establishing SSH connections:

```
Display cluster resources
$ tsh ls
```

In this example, the bastion host 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

```

### Connect to a server

`myuser` can SSH into the bastion host server by running the following command locally:

```
Use tsh to ssh into a server
$ tsh ssh root@ip-172-31-41-144
```

Now, they can:

- Connect to other servers 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 `myuser` are recorded and can be replayed in the Teleport Web UI.

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

**tsh**

```
$ tsh ssh root@ip-172-31-41-144
```

**ssh**

To use the `ssh` client generate a SSH configuration file and postfix the cluster name after the node name.

```
$ tsh config > ssh_config_teleport
$ ssh -F ssh_config_teleport root@ip-172-31-41-144.example.teleport.sh
```

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

Now, `myuser` has the ability to SSH into other servers 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 server or grouping of servers that have been assigned a particular label.

### Display the unified resource catalog

Execute the following command within your bastion host console:

```
List servers
$ tctl nodes ls
```

This 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

```

Note the "Labels" column on the farthest side. `myuser` can query all resources with a shared label using the command:

```
Query all servers with a label
$ tsh ls env=example
```

Customized labels can be defined in your `teleport.yaml` configuration file or during server creation.

This is a convenient feature that allows for more advanced queries. If an IP address changes, for example, an admin can quickly find the current server with that label since it remains unchanged.

### Run commands on all servers with a label

`myuser` can also execute commands on all servers that share a label, vastly simplifying repeated operations. For example, the following command will execute the `ls` command on each server and display the results in your terminal:

```
Run the ls command on all servers with a label
$ tsh ssh root@env=example ls
```

## Optional: Harden your server

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

To harden your Teleport server:

- Close port `22` on your private Linux instance now that your Teleport server is configured and running.
- For self-hosted deployments, optionally close port `22` on your Proxy Service host.
- You'll be able to fully connect to the private instance and, for self-hosted deployments, the Proxy Service host, using `tsh ssh`.

## Conclusion

To recap, this guide described:

- How to set up and add an SSH server to a cluster.
- 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

- While this guide shows you how to create a local user in order to access a server, you can also enable Teleport users to authenticate through a single sign-on provider. Read the [documentation](https://goteleport.com/docs/zero-trust-access/sso.md) to learn more.
- Learn more about Teleport `tsh` through the [reference documentation](https://goteleport.com/docs/reference/cli/tsh.md#tsh-ssh).
- For a complete list of ports used by Teleport, read the [Networking Guide](https://goteleport.com/docs/reference/deployment/networking.md).

## Resources

- [Setting Up an SSH Bastion Host](https://goteleport.com/blog/ssh-bastion-host/)
- [Announcing Teleport SSH Server](https://goteleport.com/blog/announcing-teleport-ssh-server/)
- [How to SSH properly](https://goteleport.com/blog/how-to-ssh-properly/)
- Consider whether [OpenSSH or Teleport SSH](https://goteleport.com/blog/openssh-vs-teleport/) is right for you.
- [Labels](https://goteleport.com/docs/zero-trust-access/rbac-get-started/labels.md)