From e917230ff9396625add5fe40616ae84da6fb00cb Mon Sep 17 00:00:00 2001 From: Alexander Klizhentas Date: Fri, 26 Nov 2021 12:14:49 -0800 Subject: [PATCH] Refresh getting started guide to use TLS routing (#8988) (#9101) * Refresh getting started guide to use TLS routing Co-authored-by: Roman Tkachenko --- docs/pages/getting-started/linux-server.mdx | 60 +++++++++++++++------ docs/pages/includes/permission-warning.mdx | 21 ++++---- 2 files changed, 54 insertions(+), 27 deletions(-) diff --git a/docs/pages/getting-started/linux-server.mdx b/docs/pages/getting-started/linux-server.mdx index 19f3dc94eef8f..1714fc92920c5 100644 --- a/docs/pages/getting-started/linux-server.mdx +++ b/docs/pages/getting-started/linux-server.mdx @@ -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!) - ```code @@ -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). + + + 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 --acme-email=your-email@example.com --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 --acme-email=your-email@example.com --cluster-name=tele.example.com -o file + # Wrote config to file "/etc/teleport.yaml". Now you can start the server. Happy Teleporting! + ``` + + + + 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 + ``` + -{/* Convert to new UI component https://github.com/gravitational/next/issues/275 */} + -### 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` @@ -104,9 +122,19 @@ pointing to the IP/FQDN of the machine with Teleport installed. Start Teleport: -```code -$ sudo teleport start -``` + + + ```code + $ sudo systemctl start teleport + ``` + + + + ```code + $ sudo teleport start + ``` + + You can access Teleport's Web UI on port `443`. diff --git a/docs/pages/includes/permission-warning.mdx b/docs/pages/includes/permission-warning.mdx index ba741f472f38b..5c1b7579abd26 100644 --- a/docs/pages/includes/permission-warning.mdx +++ b/docs/pages/includes/permission-warning.mdx @@ -1,13 +1,12 @@ - - 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: +
+ 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. - + 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. +