diff --git a/docs/pages/getting-started/linux-server.mdx b/docs/pages/getting-started/linux-server.mdx index 93b119c48419a..27f84a679982a 100644 --- a/docs/pages/getting-started/linux-server.mdx +++ b/docs/pages/getting-started/linux-server.mdx @@ -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 + + +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). + ## Step 1/4. Install Teleport on a Linux host +Run the following commands to install the Teleport binary on your system: + ```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. + + + You can use `dig` to make sure that DNS records are propagated: + + ```code + $ dig @$DNS_SERVER_ADDRESS tele.example.com + ``` + + ### 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. - 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 --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! ``` + + 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. + - 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`. -### 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. - - - You can use `dig` to make sure that DNS records are propagated: - - ```code - $ dig @8.8.8.8 tele.example.com - ``` - - -Start Teleport: +## Start Teleport @@ -136,14 +147,12 @@ Start Teleport: -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. @@ -151,15 +160,9 @@ $ tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-u ``` 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) - [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. @@ -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