-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Clarify the Linux Getting Started guide
- 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
Showing
1 changed file
with
46 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -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 \ | ||
|
@@ -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"> | ||
|
@@ -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 OTP—you'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 | ||
|
@@ -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"> | ||
|
@@ -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 |