Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refresh getting started guide to use TLS routing (#8988) #9101

Merged
merged 2 commits into from
Nov 26, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 44 additions & 16 deletions docs/pages/getting-started/linux-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,14 @@ Teleport (=teleport.version=) on Linux machines.

## Prerequisites

- A Linux machine with ports `3023`, `3024`, `3025`, and `443` open.
- A registered domain name.
- A Linux machine with a port `443` open.
- A two-factor authenticator app.
- An SSH client like OpenSSH.
- Around 20 minutes to complete; half of this may be waiting for DNS propagation.
- 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`.

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

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

<Tabs>
<TabItem label="Amazon Linux 2/RHEL (RPM)">
```code
Expand Down Expand Up @@ -70,22 +68,42 @@ Teleport (=teleport.version=) on Linux machines.

Take a look at the [Installation Guide](../installation.mdx) for more options.

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

### Configure Teleport

Generate a configuration file for Teleport using `teleport configure`.

Acme turns on automatic TLS certificates from [Let's Encrypt](https://letsencrypt.org).
<Tabs>
<TabItem label="Public internet deployment with Let's Encrypt">
Teleport uses Acme protocol to receive automatic TLS certificates from [Letsencrypt](https://letsencrypt.org).

Set up an email to receive updates from Let's Encrypt, and use a valid DNS name for a cluster name.
First, set up an email to receive updates from Let's Encrypt. Use a valid DNS name for a cluster name.

```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!
```
```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!
```
</TabItem>

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

Configure teleport:

```code
$ sudo teleport configure -o file \
--cluster-name=tele.example.com \
--public-addr=tele.example.com:443 \
--cert-file=/var/lib/teleport/fullchain.pem \
--key-file=/var/lib/teleport/privkey.pem
```
</TabItem>

{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */}
</Tabs>

### Configure domain name and obtain TLS certificates using Let's Encrypt
### 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`
Expand All @@ -104,9 +122,19 @@ pointing to the IP/FQDN of the machine with Teleport installed.

Start Teleport:

```code
$ sudo teleport start
```
<Tabs>
<TabItem label="Package manager RPM/DEB">
```code
$ sudo systemctl start teleport
```
</TabItem>

<TabItem label="Source or custom install">
```code
$ sudo teleport start
```
</TabItem>
</Tabs>

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

Expand Down
21 changes: 10 additions & 11 deletions docs/pages/includes/permission-warning.mdx
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
<Admonition type="tip" title="Tip">
The examples below may include the use of the `sudo` keyword, token UUIDs, and users with elevated privileges to make following each step easier when creating resources from scratch.

Generally:
<Details title="Before you begin: read security tips" opened={false}>
The examples below may include the use of the `sudo` keyword, token UUIDs, and users with
elevated privileges to make following each step easier.

1. We discourage using `sudo` in production environments unless it's needed.
2. You can run Teleport's auth, proxy, application access, Kubernetes access, and database access services as a non-root user - only the SSH/node service requires root access. You will, however, also need root permissions (or the `CAP_NET_BIND_SERVICE` capability) to make Teleport listen on a port numbered < 1024 (e.g. 443)
3. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
4. We encourage adherence to 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. Saving tokens into a file rather than sharing tokens directly *as strings*.
We recommend you follow the best practices to avoid security incidents:

Learn more about [Teleport Role-Based Access Control](https://goteleport.com/docs/access-controls/introduction/) best practices.
</Admonition>
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.
</Details>