Skip to content

Commit

Permalink
Clarify the Linux Getting Started guide
Browse files Browse the repository at this point in the history
- Prerequisites: Make the requirement for a DNS server a bit
  more generalized.
- Add an admonition box directing users expecting a local
  evaluation setup to our Docker Compose guide.
- Add a bit more context around how ACME works
- Move "Configure DNS" before "Configure Teleport" to provide a
  clearer order of tasks.
- Add a bit of explanation for why a user would create DNS
  records.
- Add some explanation for how "teleport configure" sets up
  TLS.
- Add a "Start Teleport" H3 section to separate this step from
  previous ones.
- Various minor additions to add clarity.

Closes #9077 since it refers users without access to a DNS server
to the Docker Compose guide.

Closes #9083
  • Loading branch information
ptgott committed Dec 15, 2021
1 parent 913a881 commit f1aa956
Showing 1 changed file with 46 additions and 40 deletions.
86 changes: 46 additions & 40 deletions docs/pages/getting-started/linux-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,19 @@ Teleport (=teleport.version=) on Linux machines.

## Prerequisites

- A Linux machine with a port `443` open.
- A two-factor authenticator app.
- An SSH client like OpenSSH.
- Public internet deployment: a domain name. It takes 20 minutes to complete, including DNS propagation.
- Private net deployment: a domain name and a wildcard certificate e.g. `*.tele.example.com`.
- A Linux machine with a port `443` open
- A two-factor authenticator app such as [Authy](https://authy.com/download/), [Google Authenticator](https://www.google.com/landing/2step/), or [Microsoft Authenticator](https://www.microsoft.com/en-us/account/authenticator)
- An SSH client like OpenSSH
- Access to a DNS service such as Amazon Route 53 or CoreDNS

<Admonition title="Local-only setups" type="tip">
If you would like to try out Teleport on your local machine—e.g., you do not have access to a DNS server or internal public key infrastructure—we recommend following our [Docker Compose guide](./docker-compose.mdx).
</Admonition>

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

Run the following commands to install the Teleport binary on your system:

<Tabs>
<TabItem label="Amazon Linux 2/RHEL (RPM)">
```code
Expand Down Expand Up @@ -70,27 +75,49 @@ Take a look at the [Installation Guide](../installation.mdx) for more options.

(!docs/pages/includes/permission-warning.mdx!)

### Configure DNS

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. To get started, set up two `A` records for `tele.example.com` and `*.tele.example.com` pointing to the IP/FQDN of the machine with Teleport installed.

<Admonition
type="tip"
title="Tip"
>
You can use `dig` to make sure that DNS records are propagated:

```code
$ dig @$DNS_SERVER_ADDRESS tele.example.com
```
</Admonition>

### Configure Teleport

Generate a configuration file for Teleport using `teleport configure`.
Next, generate a configuration file for Teleport using the `teleport configure` command. This command requires information about a TLS certificate and private key. If your environment allows your Teleport Auth Server to be reachable via the public internet, we recommend using Let's Encrypt to generate your key and certificate automatically. Otherwise, you can use a key and certificate provided via your organization's internal public key infrastructure.

<Tabs>
<TabItem label="Public internet deployment with Let's Encrypt">
Teleport uses Acme protocol to receive automatic TLS certificates from [Letsencrypt](https://letsencrypt.org).
Teleport uses the ACME protocol to request automatic TLS certificates from Let's Encrypt, which accesses an HTTP endpoint on your Teleport host in order to complete authentication challenges.

First, set up an email to receive updates from Let's Encrypt. Use a valid DNS name for a cluster name.
Use the following command to configure Teleport:

```code
$ sudo teleport configure --acme [email protected] --cluster-name=tele.example.com -o file
# Wrote config to file "/etc/teleport.yaml". Now you can start the server. Happy Teleporting!
```

The `--acme-email` flag indicates an email address that Let's Encrypt can use for notifications, and does _not_ require the same domain name as your Teleport host.

For the `--cluster-name` flag, enter the domain name you used when creating a DNS A record earlier.

</TabItem>

<TabItem label="Private net deployment">
Place the valid private key and a certificate chain in `/var/lib/teleport/privkey.pem`
On your Teleport host, place a valid private key and a certificate chain in `/var/lib/teleport/privkey.pem`
and `/var/lib/teleport/fullchain.pem` respectively.

Configure teleport:
The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., `*.teleport.example.com`.

Configure Teleport, changing the values of the `--cluster-name` and `--public-addr` flags to match the domain name of your Teleport host.

```code
$ sudo teleport configure -o file \
Expand All @@ -103,24 +130,8 @@ Generate a configuration file for Teleport using `teleport configure`.

</Tabs>

### Configure DNS

Teleport requires a secure public endpoint for the Teleport UI and for end-users to connect to.
To get started, set up two `A` records for `tele.example.com` and `*.tele.example.com`
pointing to the IP/FQDN of the machine with Teleport installed.

<Admonition
type="tip"
title="Tip"
>
You can use `dig` to make sure that DNS records are propagated:

```code
$ dig @8.8.8.8 tele.example.com
```
</Admonition>

Start Teleport:
## Start Teleport

<Tabs>
<TabItem label="Package manager RPM/DEB">
Expand All @@ -136,30 +147,22 @@ Start Teleport:
</TabItem>
</Tabs>

You can access Teleport's Web UI on port `443`.

Replace `tele.example.com` with your domain: `https://tele.example.com/`.
You can access Teleport's Web UI via HTTPS at the domain you created earlier.

## Step 2/4. Create a Teleport user and set up two-factor authentication

In this example, we'll create a new Teleport user `teleport-admin` which is allowed to log into
SSH hosts as any of the principals `root`, `ubuntu` or `ec2-user`.
In this example, we'll create a new Teleport user `teleport-admin`, which is allowed to log into
SSH hosts as any of the principals `root`, `ubuntu`, or `ec2-user`.

```code
# tctl is an administrative tool that is used to configure Teleport's auth service.
$ tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user
```

Teleport will always enforce the use of two-factor authentication by default. It supports One-Time
Passwords (OTP) and second factor authenticators (WebAuthn). This quick start will use OTP - you'll
Passwords (OTP) and second factor authenticators (WebAuthn). This quick start will use OTPyou'll
need an OTP-compatible app that can scan a QR code.

Here's a selection of compatible two-factor authentication apps:

- [Authy](https://authy.com/download/)
- [Google Authenticator](https://www.google.com/landing/2step/)
- [Microsoft Authenticator](https://www.microsoft.com/en-us/account/authenticator)

![Teleport User Registration](../../img/quickstart/login.png)

<Admonition
Expand All @@ -177,7 +180,7 @@ Here's a selection of compatible two-factor authentication apps:

<Tabs>
<TabItem label="Mac">
[Download MacOS .pkg installer](https://goteleport.com/teleport/download?os=mac) (`tsh` client only, signed) file, double-click to run the installer.
[Download the MacOS .pkg installer](https://goteleport.com/teleport/download?os=mac) (`tsh` client only, signed) and double-click to run it.
</TabItem>

<TabItem label="Mac - Homebrew">
Expand Down Expand Up @@ -346,3 +349,6 @@ Check out our collection of step-by-step guides for common Teleport tasks.
- [Github SSO](../setup/admin/github-sso.mdx)
- [Label Nodes](../setup/admin/labels.mdx)
- [Teleport with OpenSSH](../server-access/guides/openssh.mdx)

## Further reading
- How Let's Encrypt uses the [ACME protocol](https://letsencrypt.org/how-it-works/) to issue certificates

0 comments on commit f1aa956

Please sign in to comment.