diff --git a/docs/config.json b/docs/config.json index 0669082d79d0d..b891e00d4875d 100644 --- a/docs/config.json +++ b/docs/config.json @@ -8,6 +8,10 @@ "title": "Introduction", "slug": "/" }, + { + "title": "Get Started with Teleport", + "slug": "/get-started/" + }, { "title": "Core Concepts", "slug": "/core-concepts/" @@ -30,36 +34,6 @@ } ] }, - { - "icon": "play", - "title": "Try out Teleport", - "entries": [ - { - "title": "Introduction", - "slug": "/try-out-teleport/introduction/" - }, - { - "title": "Linux Server", - "slug": "/try-out-teleport/linux-server/" - }, - { - "title": "Digital Ocean", - "slug": "/try-out-teleport/digitalocean/" - }, - { - "title": "Browser Labs", - "slug": "/try-out-teleport/browser-labs/" - }, - { - "title": "Docker Compose", - "slug": "/try-out-teleport/docker-compose/" - }, - { - "title": "Local Kubernetes Lab", - "slug": "/try-out-teleport/local-kubernetes/" - } - ] - }, { "icon": "success", "title": "Choose an Edition", @@ -100,11 +74,6 @@ "slug": "/choose-an-edition/teleport-enterprise/introduction/", "forScopes": ["enterprise"], "entries": [ - { - "title": "Getting Started", - "slug": "/choose-an-edition/teleport-enterprise/getting-started/", - "forScopes": ["enterprise"] - }, { "title": "HSM", "slug": "/choose-an-edition/teleport-enterprise/hsm/", @@ -589,10 +558,6 @@ "title": "Terraform Provider", "slug": "/management/guides/terraform-provider/" }, - { - "title": "Docker", - "slug": "/management/guides/docker/" - }, { "title": "EC2 Tags", "slug": "/management/guides/ec2-tags/" @@ -1592,7 +1557,7 @@ }, { "source": "/enterprise/quickstart-enterprise/", - "destination": "/choose-an-edition/teleport-enterprise/getting-started/", + "destination": "/choose-an-edition/teleport-enterprise/introduction/", "permanent": true }, { @@ -1612,7 +1577,7 @@ }, { "source": "/setup/guides/docker-compose/", - "destination": "/management/guides/docker/", + "destination": "/installation/", "permanent": true }, { @@ -1642,7 +1607,7 @@ }, { "source": "/quickstart/", - "destination": "/try-out-teleport/introduction/", + "destination": "/get-started/", "permanent": true }, { @@ -1677,7 +1642,7 @@ }, { "source": "/quickstart-docker/", - "destination": "/management/guides/docker/", + "destination": "/installation/", "permanent": true }, { @@ -1742,7 +1707,7 @@ }, { "source": "/getting-started/digitalocean/", - "destination": "/try-out-teleport/digitalocean/", + "destination": "/get-started/", "permanent": true }, { @@ -1757,7 +1722,7 @@ }, { "source": "/kubernetes-access/getting-started/local/", - "destination": "/try-out-teleport/local-kubernetes/", + "destination": "/kubernetes-access/", "permanent": true }, { @@ -1947,7 +1912,7 @@ }, { "source": "/setup/deployments/digitalocean/", - "destination": "/try-out-teleport/digitalocean/", + "destination": "/get-started/", "permanent": true }, { @@ -1997,7 +1962,7 @@ }, { "source": "/getting-started/linux-server/", - "destination": "/try-out-teleport/linux-server/", + "destination": "/get-started/", "permanent": true }, { @@ -2027,7 +1992,7 @@ }, { "source": "/enterprise/getting-started/", - "destination": "/choose-an-edition/teleport-enterprise/getting-started/", + "destination": "/choose-an-edition/teleport-enterprise/introduction/", "permanent": true }, { @@ -2097,7 +2062,7 @@ }, { "source": "/setup/guides/docker/", - "destination": "/management/guides/docker/", + "destination": "/installation/", "permanent": true }, { @@ -2252,12 +2217,12 @@ }, { "source": "/getting-started/docker-compose/", - "destination": "/try-out-teleport/docker-compose/", + "destination": "/get-started/", "permanent": true }, { "source": "/getting-started/local-kubernetes/", - "destination": "/try-out-teleport/local-kubernetes/", + "destination": "/get-started/", "permanent": true }, { @@ -2302,7 +2267,7 @@ }, { "source": "/deploy-a-cluster/teleport-enterprise/getting-started/", - "destination": "/choose-an-edition/teleport-enterprise/getting-started/", + "destination": "/choose-an-edition/teleport-enterprise/introduction/", "permanent": true }, { @@ -2322,17 +2287,17 @@ }, { "source": "/deploy-a-cluster/deployments/digitalocean/", - "destination": "/try-out-teleport/digitalocean/", + "destination": "/get-started/", "permanent": true }, { "source": "/deploy-a-cluster/open-source/", - "destination": "/try-out-teleport/linux-server/", + "destination": "/get-started/", "permanent": true }, { "source": "/getting-started/", - "destination": "/try-out-teleport/introduction/", + "destination": "/get-started/", "permanent": true }, { @@ -2397,7 +2362,7 @@ }, { "source": "/try-out-teleport/", - "destination": "/try-out-teleport/introduction/", + "destination": "/get-started/", "permanent": true }, { @@ -2484,6 +2449,41 @@ "source": "/management/guides/joining-services-kubernetes-serviceaccount/", "destination": "/management/join-services-to-your-cluster/kubernetes/", "permanent": true + }, + { + "source": "/try-out-teleport/browser-labs/", + "destination": "/get-started/", + "permanent": true + }, + { + "source": "/try-out-teleport/digitalocean/", + "destination": "/get-started/", + "permanent": true + }, + { + "source": "/try-out-teleport/docker-compose/", + "destination": "/get-started/", + "permanent": true + }, + { + "source": "/try-out-teleport/introduction/", + "destination": "/get-started/", + "permanent": true + }, + { + "source": "/try-out-teleport/local-kubernetes/", + "destination": "/get-started/", + "permanent": true + }, + { + "source": "/management/guides/docker/", + "destination": "/installation/", + "permanent": true + }, + { + "source": "/choose-an-edition/teleport-enterprise/getting-started/", + "destination": "/choose-an-edition/teleport-enterprise/introduction/", + "permanent": true } ] } diff --git a/docs/img/cloud/getting-started/session-recordings@2x.png b/docs/img/cloud/getting-started/session-recordings@2x.png index 428bc4860fcc9..7c24bfc6343c2 100644 Binary files a/docs/img/cloud/getting-started/session-recordings@2x.png and b/docs/img/cloud/getting-started/session-recordings@2x.png differ diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 7f3725c0552ef..faa7ed2e2da09 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -26,7 +26,7 @@ Let's connect to Grafana using Teleport in three steps: - A host where you will run the Teleport Application Service. -If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../try-out-teleport/introduction.mdx) or try our Teleport Application Access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). +If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../get-started.mdx) or try our Teleport Application Access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.) diff --git a/docs/pages/choose-an-edition/introduction.mdx b/docs/pages/choose-an-edition/introduction.mdx index 40831d189b49b..41e2942321c72 100644 --- a/docs/pages/choose-an-edition/introduction.mdx +++ b/docs/pages/choose-an-edition/introduction.mdx @@ -13,9 +13,8 @@ which edition is most appropriate for your use case. We provide a free, open source distribution of Teleport that enables you to get secure access to databases, Windows desktops, Kubernetes clusters, and more. -[Try out Teleport on a Linux -server](../try-out-teleport/linux-server.mdx). If you would like to take a look -at the source, visit the [Teleport GitHub +[Try out Teleport on a Linux server](../get-started.mdx). If you would like to +take a look at the source, visit the [Teleport GitHub repository](https://github.com/gravitational/teleport). ### Teleport Enterprise Cloud diff --git a/docs/pages/choose-an-edition/teleport-enterprise/getting-started.mdx b/docs/pages/choose-an-edition/teleport-enterprise/getting-started.mdx deleted file mode 100644 index 5ad8bf67411e5..0000000000000 --- a/docs/pages/choose-an-edition/teleport-enterprise/getting-started.mdx +++ /dev/null @@ -1,460 +0,0 @@ ---- -title: Get Started with Teleport Enterprise -description: Learn how to deploy your first Teleport Enterprise cluster. ---- - -This guide shows you how to get up and running with Teleport Enterprise. - -You will be deploying three Teleport services on a single host: - -- The **Auth Service** stores user accounts and your cluster configuration. It - provides authentication and authorization for every Teleport service and every - user in your cluster. - -- The **Proxy Service** routes client connection requests to the appropriate - Teleport services and serves the Teleport Web UI, which you can use to access - resources or manage the cluster. - -- The **SSH Service** is an SSH server implementation that provides seamless - access to Linux hosts in your cluster. - - SSH Service instances are called **Teleport Nodes**. When a Teleport Node - receives a connection request, the request is authenticated through the - cluster's Auth Service. - - Other Teleport services provide access to remote desktops, Kubernetes - clusters, applications, and databases. - -You will install the `teleport` binary, which runs runs all three of these -services by default. - -You will also use the following client tools: - -| Tool | Description | -| - | - | -| `tctl` | Cluster administration tool used to perform tasks such as inviting Nodes to a cluster and managing user accounts. | -| `tsh` | Allows users to authenticate and access resources via their local machine. | -| Web UI | You can use the Teleport Web UI to access resources in your cluster by navigating to the public address of your Teleport Proxy Service in your browser. | - -(!docs/pages/includes//cloud/call-to-action.mdx!) - -## Prerequisites - -- A Teleport Enterprise account. If you do not have one, use our [signup - form](https://goteleport.com/signup/enterprise/) to schedule a demo with the - Teleport Sales Team. -- A Linux machine with only port `443` open to ingress traffic. You must be able - to install and run software on the machine. Either configure access to your - machine via SSH for the initial setup (and open an SSH port in addition port - `443`) or enter the commands in this guide into an Amazon EC2 - [user data script](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html), - Google Compute Engine - [startup script](https://cloud.google.com/compute/docs/instances/startup-scripts), - or similar. -- 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). -- `python3` installed on your Linux machine. We will use this to run a simple - HTTP file server, so you can use another HTTP server if you have one - installed. - -You must also have one of the following: -- A registered domain name. -- An authoritative DNS nameserver managed by your organization, plus some means - of obtaining a TLS certificate and private key for your Teleport deployment. - If using this approach, ensure that your browser is configured to use your - organization's nameserver. - -## Step 1/5. Create DNS records - -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. - -(!docs/pages/includes/dns.mdx!) - -## Step 2/5. Run a simple web service - -Create a directory on your Linux machine called `demo-app` and run the following -command: - -```code -$ cat<>demo-app/index.html - -Welcome! - -

Welcome to your Teleport cluster!

- - -EOF -``` - -Run a simple HTTP service on port 9000 that returns your welcome page: - -```code -$ nohup python3 -m http.server 9000 --directory demo-app & -``` - -Since port 9000 is not open on your Linux host, there is currently no way to -access the web service from your local machine. We will configure Teleport to -enable you to access the web service securely. - -## Step 3/5. Set up Teleport - -### Install the `teleport` binary - -On the host where you will run your Teleport services, run the following -commands to install the `teleport` binary: - -
- -For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs -will be slightly different: - -```code -$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz.sha256 -# -$ curl -O https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz -$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz -# Verify that the checksums match -$ tar -xzf teleport-ent-v(=teleport.version=)-linux-amd64-fips-bin.tar.gz -$ cd teleport-ent -$ sudo ./install -``` - -
- -```code -$ curl https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz.sha256 -# -$ curl -O https://get.gravitational.com/teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz -$ shasum -a 256 teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz -# Verify that the checksums match -$ tar -xzf teleport-ent-v(=teleport.version=)-linux-amd64-bin.tar.gz -$ cd teleport-ent -$ sudo ./install -``` - -### Configure Teleport - -Generate a configuration file for Teleport using the `teleport configure` command. -This command requires information about a TLS certificate and private key. - -If you are exposing your Teleport host to the internet, we recommend using Let's -Encrypt to receive your key and certificate automatically. For private networks -or custom deployments, use your own private key and certificate. - -(!docs/pages/includes/tls-certificate-setup.mdx!) - -Next, configure Teleport to provide secure access to your web service. Edit your -Teleport configuration file (`/etc/teleport.yaml`) to include the following, -replacing `teleport.example.com` with the domain name of your Teleport cluster. - -```yaml -app_service: - enabled: yes - apps: - - name: "demo" - uri: "http://localhost:9000" - public_addr: "demo.teleport.example.com" -``` - -### Obtain your license file - -(!docs/pages/includes/enterprise/obtainlicense.mdx!) - -Save your license file on the host where you will install Teleport at the path, -`/var/lib/teleport/license.pem`. - -### Start Teleport - -On the host where you are running Teleport, generate a systemd unit file for -Teleport and save it in `/etc/systemd/system/teleport.service`: - -```code -$ sudo teleport install systemd -o /etc/systemd/system/teleport.service -``` - -Enable the Teleport service and start Teleport in the background: - -```code -$ sudo systemctl enable teleport -$ sudo systemctl start teleport -``` - -Confirm that the `teleport` service has started: - -``` -$ sudo systemctl status teleport -``` - -### Get information about your Teleport deployment - -You can review the logs of the Teleport service with the following command: - -```code -$ journalctl -fu teleport -``` -Run the following command to review the ports that Teleport is -listening on: - -```code -$ sudo netstat -lptne -``` - -The output should look something like this: - -```code -$ sudo netstat -lptne | grep teleport -tcp6 0 0 :::443 :::* LISTEN -0 168760 29504/teleport -tcp6 0 0 :::3022 :::* LISTEN -0 167812 29504/teleport -tcp6 0 0 :::3025 :::* LISTEN -0 168741 29504/teleport -``` - -## Step 4/5. Add a local user - -### Create a user - -Every user in a Teleport cluster must be assigned at least one role. By default, -Teleport comes with several pre-configured roles known as **presets**: - -|Role|Description| -|---|---| -|`access`| Can access resources in your infrastructure, such as Teleport Nodes, applications, and Kubernetes clusters| -|`auditor`|Can view audit logs and session recordings.| -|`editor`| Can modify cluster configuration.| - -You can see the full configurations for these roles by executing the following -command on the host running Teleport: - -```code -$ sudo tctl get roles -``` - -On the host where you are running Teleport, create a Teleport user called -`myuser` with the `access` role and the `ubuntu` login. This user can log in to -any host in your infrastructure as `ubuntu` (choose a login that matches a user -account on your Linux host): - -```code -$ sudo tctl users add --roles=access --logins=ubuntu myuser - -Signup token has been created and is valid for 1 hours. Share this URL with the user: -https://auth.example.com:3080/web/newuser/22e3acb6a0c2cde22f13bdc879ff9d2a -``` - -Navigate to the link displayed in your terminal, pick a password, and configure -second factor authentication. - -### Log in as your new user - -`tsh` is our client tool. It helps you log in to Teleport clusters and obtain -short-lived credentials. It can also be used to list resources registered with -Teleport, such as servers, applications, and Kubernetes clusters. - -Install `tsh` on your local machine: - - - - - -Run the following commands to download and run the Teleport installer: - - ```code - $ curl -O https://get.gravitational.com/teleport-ent-(=teleport.version=).pkg - # Installs on Macintosh HD - $ sudo installer -pkg teleport-ent-(=teleport.version=).pkg -target / - # Password: - # installer: Package name is teleport-ent-(=teleport.version=) - # installer: Upgrading at base path / - # installer: The upgrade was successful. - $ which teleport - # /usr/local/bin/teleport - ``` - - - - -Run the following commands to install Teleport binaries on your client system, -including `tsh`: - -(!docs/pages/includes/install-linux.mdx!) - - - - -Most `tsh` features are supported for Windows 10 1607+. The `tsh ssh` command -can be run under `cmd.exe`, PowerShell, and Windows Terminal. - -To install `tsh` on Windows, run the following commands in PowerShell: - - ```code - # Get the expected checksum for the Windows tsh package - $ $Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v(=teleport.version=)-windows-amd64-bin.zip.sha256 - # PowerShell will return the binary representation of the response content - # by default, so you need to convert it to a string - $ [System.Text.Encoding]::UTF8.getstring($Resp.Content) - # - $ curl -O teleport-v(=teleport.version=)-windows-amd64-bin.zip https://get.gravitational.com/teleport-v(=teleport.version=)-windows-amd64-bin.zip - $ certUtil -hashfile teleport-v(=teleport.version=)-windows-amd64-bin.zip SHA256 - # SHA256 hash of teleport-v(=teleport.version=)-windows-amd64-bin.zip: - # - # CertUtil: -hashfile command completed successfully. - ``` - - After you have verified that the checksums match, you can extract the archive. - The executable will be available at - `teleport-v(=teleport.version=)-windows-amd64-bin\teleport\tsh.exe`. - - ```code - $ Expand-Archive teleport-v(=teleport.version=)-windows-amd64-bin.zip - $ cd teleport-v(=teleport.version=)-windows-amd64-bin\teleport - $ .\tsh.exe version - Teleport v(=teleport.version=) git:v(=teleport.version=) go(=teleport.golang=) - ``` - - Make sure to move `tsh.exe` into your PATH. - - - -Use `tsh` to log in to your Teleport cluster as `myuser`, replacing -`auth.example.com` with the domain name you configured earlier: - -```code -$ tsh --proxy=auth.example.com login --user=myuser -``` - -Note that you can omit the `--user` flag if the `$USER` environment variable -is equal to your Teleport username. - -If successful, the `tsh login` command will retrieve a user certificate for -`myuser` and store it in the `~/.tsh/keys/` directory. - -With a certificate in place, `myuser` can now interact with the Teleport cluster. - -## Step 5/5. Access resources - -You have now completed setting up Teleport and signed in to your cluster. Now -you can use Teleport to quickly access resources. - -### Visit your demo website - -Now that you have logged in to Teleport, you can see the demo website you -started earlier. Visit `https://demo.teleport.example.com`, replacing -`teleport.example.com` with the domain name of your Teleport cluster. You can -only visit the website if you have authenticated with your cluster. - -You can use the Teleport Application Service to configure access to any web -application in your private network, including HTTP management endpoints for -popular infrastructure technologies. - -### SSH into your Node - -You also configured the Teleport SSH Service, meaning that you can easily access -your Linux machine after logging in to Teleport. - -See the logins you can use to access a Node: - -```code -$ tsh status -> Profile URL: https://teleport.example.com:443 - Logged in as: teleport-admin - Cluster: teleport.example.com - Roles: access, editor - Logins: root, ubuntu, ec2-user - Kubernetes: enabled - Valid until: 2022-04-26 04:55:59 -0400 EDT [valid for 11h38m0s] - Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -``` - -List all SSH servers connected to Teleport: - -```code -$ tsh ls -Node Name Address Labels ----------------- -------------- ------------------------------------- -mynode 127.0.0.1:3022 env=example,hostname=mynode -``` - -
- -(!docs/pages/includes/node-logins.mdx!) - -
- -SSH into your Node, replacing `mynode` with one of the Nodes listed by -the `tsh ls` command and `ubuntu` with the login on your Linux host that you -configured `myuser` to access: - -```code -$ tsh ssh ubuntu@mynode -``` - -## Next steps - -### Deploy on Kubernetes - -This guide shows you how to install Teleport Enterprise on a virtual machine. If -you are using a Kubernetes-based environment, see our [Getting Started -Guide](../../deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx) for how to -deploy Teleport on Kubernetes. - -### Configure RBAC - -The preset `access` role we assigned to a user in this guide is probably too -permissive for your environment. Read our guide to [configuring Teleport -roles](../../access-controls/guides/role-templates.mdx) to set up more granular -access controls. - -### Configure SSO - -In this guide, we created a **local user** stored on the Teleport Auth Service. -For on and offboarding users at scale, you should use one of Teleport's Single -Sign-On integrations. - -Take a look at our [Single Sign-On](../../access-controls/sso.mdx) guide to -learn the basics of integrating Teleport with SSO providers. - -You can configure any SAML- or OIDC-compliant identity provider to enable SSO -for Teleport. There are Teleport Enterprise customers who are using Oracle IDM, -SailPoint, and others. - -### Configure Access Requests - -With Teleport Access Requests you can provide your users limited access to -resources by default. Your users can then access elevated privileges on a -temporary basis, minimizing the risk that an attacker will compromise an admin -account. - -[Read our guide](../../access-controls/access-requests.mdx) to setting up Access -Requests. - -You can then take advantage of Teleport's [Access Request -plugins](../../access-controls/access-request-plugins/index.mdx) so users can -request and review Access Requests using your existing communication workflows. - -## Troubleshooting - -If Teleport services do not start, take a look at the `teleport` service's logs: - -```code -$ sudo journalctl -fu teleport -``` - -Usually the error will be reported there. Common reasons for failure are: - -- Network issues: port `443` is closed via iptables or occupied by another - process. -- Disk issues: Teleport fails to create `/var/lib/teleport` because the volume - is read-only or not accessible. - -## Getting Help - -If something is not working, please reach out to us by creating a ticket in your -[Teleport account](https://teleport.sh). Customers who -have purchased the premium support package can also ping us through your Slack -channel. - diff --git a/docs/pages/choose-an-edition/teleport-enterprise/introduction.mdx b/docs/pages/choose-an-edition/teleport-enterprise/introduction.mdx index dc98159e799cd..c0e64aa12fe72 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/introduction.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/introduction.mdx @@ -7,9 +7,6 @@ h1: Teleport Enterprise Teleport Enterprise is a commercial product built around Teleport's open source core. -For those that want to jump right in, you can play with the -[Getting Started Guide for Teleport Enterprise](getting-started.mdx). - The table below gives a quick overview of the benefits of Teleport Enterprise. | Teleport Enterprise Feature | Description | @@ -114,3 +111,16 @@ See [Moderated Sessions](../../access-controls/guides/moderated-sessions.mdx) fo ## License file Commercial Teleport subscriptions require a valid license. See [Enterprise License File](./license.mdx) for how to manage the file in your Teleport Enterprise deployment. + +## Next steps + +To get started with Teleport Enterprise, read our [deployment +guides](../../deploy-a-cluster/introduction.mdx). You will learn how to deploy a +high-availability, self-hosted Teleport cluster on your platform. + +Unless your organization requires the Enterprise-specific features we outlined +above, you can use Teleport Enterprise Cloud to achieve secure access to your +infrastructure without needing to maintain the Auth and Proxy Services. + +[Sign up for a free trial of Teleport Enterprise +Cloud](https://goteleport.com/signup/). diff --git a/docs/pages/core-concepts.mdx b/docs/pages/core-concepts.mdx index d44f4546215d8..4c3e495e3d101 100644 --- a/docs/pages/core-concepts.mdx +++ b/docs/pages/core-concepts.mdx @@ -17,7 +17,7 @@ within your infrastructure, such as Kubernetes clusters and Windows desktops. A minimal Teleport cluster consists of the **Teleport Auth Service** and **Teleport Proxy Service**. In a demo environment, you can run these two services from a single `teleport` process on a [Linux -host](./try-out-teleport/linux-server.mdx). +host](./get-started.mdx). ### Teleport Auth Service diff --git a/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx b/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx index 83286ed803f0c..44af61f3a39b9 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx @@ -618,8 +618,9 @@ $ helm --namespace cert-manager uninstall cert-manager ## Next steps -You can follow our [Getting Started with Teleport guide](../../management/guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your -Teleport cluster. +Now that you have deployed a Teleport cluster, read the [Manage +Access](../../access-controls/introduction.mdx) section to get started enrolling +users and setting up RBAC. See the [high availability section of our Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx#highavailability) for more details on high availability. diff --git a/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx b/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx index 6ca71a55245e0..a0489c3ed3c99 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx @@ -266,9 +266,10 @@ install a new version with the appropriate values. ## Next steps +Now that you have deployed a Teleport cluster, read the [Manage +Access](../../access-controls/introduction.mdx) section to get started enrolling +users and setting up RBAC. + To see all of the options you can set in the values file for the `teleport-cluster` Helm chart, consult our [reference guide](../../reference/helm-reference/teleport-cluster.mdx). - -You can follow our [Getting Started with Teleport guide](../../management/guides/docker.mdx#step-34-creating-a-teleport-user) -to finish setting up your Teleport cluster. diff --git a/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx b/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx index 46624e251ceae..5415b356406d1 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx @@ -493,7 +493,8 @@ $ helm --namespace cert-manager uninstall cert-manager ## Next steps -You can follow our [Getting Started with Teleport guide](../../management/guides/docker.mdx#step-34-creating-a-teleport-user) to finish setting up your -Teleport cluster. +Now that you have deployed a Teleport cluster, read the [Manage +Access](../../access-controls/introduction.mdx) section to get started enrolling +users and setting up RBAC. See the [high availability section of our Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx#highavailability) for more details on high availability. diff --git a/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx b/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx index df16d06ae3abd..6c6e0da7d6675 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx @@ -37,10 +37,6 @@ cluster to Teleport. - A registered domain name. This is required for Teleport to set up TLS via Let's Encrypt and for Teleport clients to verify the Proxy Service host. - A Kubernetes cluster hosted by a cloud provider, which is required for the load balancer we deploy in this guide. - -Teleport also supports Kubernetes in on-premise and air-gapped environments. If you would like to try out Teleport on your local machine, we recommend following our [Docker Compose guide](../../try-out-teleport/docker-compose.mdx). - - (!docs/pages/includes/kubernetes-access/helm-k8s.mdx!) (!docs/pages/includes/permission-warning.mdx!) diff --git a/docs/pages/desktop-access/active-directory-manual.mdx b/docs/pages/desktop-access/active-directory-manual.mdx index 69df9d98f7fb7..4be9a17ad9da6 100644 --- a/docs/pages/desktop-access/active-directory-manual.mdx +++ b/docs/pages/desktop-access/active-directory-manual.mdx @@ -179,7 +179,7 @@ certificate-based smart card authentication, and ensuring RDP is enabled. The following step requires an existing cluster. If you don't already have a Teleport cluster up and running, see our general [Getting -Started](../try-out-teleport/introduction.mdx) guide. +Started](../get-started.mdx) guide to set up a demo cluster. These steps will need to be repeated if Teleport's user certificate authority is rotated. diff --git a/docs/pages/try-out-teleport/linux-server.mdx b/docs/pages/get-started.mdx similarity index 59% rename from docs/pages/try-out-teleport/linux-server.mdx rename to docs/pages/get-started.mdx index 5b2f5d21c1756..60fd78b98887f 100644 --- a/docs/pages/try-out-teleport/linux-server.mdx +++ b/docs/pages/get-started.mdx @@ -4,9 +4,10 @@ description: This tutorial will guide you through the steps needed to install an videoBanner: 8aiVin0LvmE --- -This tutorial will guide you through the steps needed to install and run -Teleport (=teleport.version=) on a Linux host, then show you how to use -Teleport to configure access to resources. +This tutorial will show you how to install and run a demo Teleport cluster +(=teleport.version=) on a Linux host using Teleport Community Edition. Once you +deploy the cluster, you can configure RBAC, register resources, and protect your +small-scale demo environments or home lab. We will run the following Teleport services: @@ -16,15 +17,10 @@ We will run the following Teleport services: - **Teleport Proxy Service:** The cluster frontend, which handles user requests, forwards user credentials to the Auth Service, and communicates with Teleport instances that enable access to specific resources in your infrastructure. -- **Teleport Application Service:** Enables secure access to web applications in - private networks. In this tutorial, we will use Teleport to access a simple - web service. - **Teleport SSH Service:** An SSH server implementation that takes advantage of Teleport's short-lived certificates, sophisticated RBAC, session recording, and other features. -(!docs/pages/includes/permission-warning.mdx!) - (!docs/pages/includes/cloud/call-to-action.mdx!) ## Prerequisites @@ -38,23 +34,19 @@ We will run the following Teleport services: script](https://cloud.google.com/compute/docs/instances/startup-scripts), or similar. - - - This guide is not intended for local environments, e.g., a Docker container on - your workstation. For guides to trying out a containerized Teleport deployment - locally, see the following: + - - [Local Kubernetes Cluster](./local-kubernetes.mdx) - - [Docker Compose](./docker-compose.mdx) - - [Single Docker Container](../management/guides/docker.mdx) + For a quick demo environment you can use to follow this guide, consider + installing our DigitalOcean 1-Click droplet. View the installation page on + [DigitalOcean + Marketplace](https://marketplace.digitalocean.com/apps/teleport). Once your + droplet is ready, SSH into the droplet and follow the configuration wizard. -- 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) - -- `python3` installed on your Linux host. We will use this to run a simple - HTTP file server, so you can use another HTTP server if you have one - installed. +- 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) You must also have one of the following: - A registered domain name. @@ -62,71 +54,33 @@ You must also have one of the following: certificate authority. If using this approach, ensure that your browser is configured to use your organization's nameserver. - - -If you would like to try out Teleport on your local workstation—e.g., you do not -have access to DNS resources or internal public key infrastructure—we recommend -following our [Docker Compose guide](../try-out-teleport/docker-compose.mdx). - - +This guide is not intended for local deployments. If your environment doesn't +meet the prerequisites above, you can get started with Teleport by signing up +for a [free trial of Teleport Enterprise Cloud](https://goteleport.com/signup/). ## Step 1/6. 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. - -(!docs/pages/includes/dns.mdx!) +Teleport's certificate. Set up two DNS `A` records, each pointing to the IP +address of your Linux host. Assuming `teleport.example.com` is your domain name, +set up records for: -## Step 2/6. Run a simple web service +|Domain|Reason| +|---|---| +|`teleport.example.com`|Traffic to the Proxy Service from users and services.| +|`*.teleport.example.com`|Traffic to web applications registered with Teleport. Teleport issues a subdomain of your cluster's domain name to each application.| -Run the following commands to create a directory on your Linux host -called `demo-app` and add a simple HTML file to serve to clients: +## Step 2/6. Set up Teleport on your Linux host -```code -$ mkdir demo-app -$ cat<>demo-app/index.html - -Welcome! - -

Welcome to your Teleport cluster!

- - -EOF -``` +### Install Teleport -Run a simple HTTP service on port 9000 that returns your welcome page: +On your Linux host, run the following command to install the Teleport binary: ```code -$ nohup python3 -m http.server 9000 --directory demo-app & +$ curl https://goteleport.com/static/install.sh | bash -s (=teleport.version=) ``` -Since port 9000 is not open on your Linux host, there is currently no way to -access the web service from your local workstation. We will configure Teleport to -enable you to access the web service securely. - -## Step 3/6. Set up Teleport on your Linux host - -### Install Teleport - -Run the appropriate commands for your environment to install the Teleport binary -on your Linux host: - -(!docs/pages/includes/install-linux.mdx!) - -
- -Take a look at the [Installation Guide](../installation.mdx) for more options. - -
- - -(!docs/pages/includes/enterprise/obtainlicense.mdx!) - -Save your license file on the host where you will install Teleport at the path -`/var/lib/teleport/license.pem`. - - ### Configure Teleport Generate a configuration file for Teleport using the `teleport configure` command. @@ -134,30 +88,17 @@ This command requires information about a TLS certificate and private key. (!docs/pages/includes/tls-certificate-setup.mdx!) -Next, configure Teleport to provide secure access to your web service. Edit your -Teleport configuration file (`/etc/teleport.yaml`) to include the following, -replacing `teleport.example.com` with the domain name of your Teleport cluster. - -```yaml -app_service: - enabled: yes - apps: - - name: "demo" - uri: "http://localhost:9000" - public_addr: "demo.teleport.example.com" -``` - ### Start Teleport (!docs/pages/includes/start-teleport.mdx !) -You can access Teleport's Web UI via HTTPS at the domain you created earlier -(e.g., `https://teleport.example.com`). You should see a welcome screen similar -to the following: +Access Teleport's Web UI via HTTPS at the domain you created earlier (e.g., +`https://teleport.example.com`). You should see a welcome screen similar to the +following: -![Teleport Welcome Screen](../../img/quickstart/welcome.png) +![Teleport Welcome Screen](../img/quickstart/welcome.png) -## Step 4/6. Create a Teleport user and set up two-factor authentication +## Step 3/6. Create a Teleport user and set up two-factor authentication In this step, 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 @@ -191,7 +132,7 @@ Visit the provided URL in order to create your Teleport user. will get authentication errors later in this tutorial. If a user does not already exist, you can create it with `adduser ` or - use [Host user creation](../server-access/guides/host-user-creation.mdx) + use [host user creation](./server-access/guides/host-user-creation.mdx). If you do not have the permission to create new users on the Linux host, run `tctl users add teleport $(whoami)` to explicitly allow Teleport to @@ -204,9 +145,9 @@ one-time passwords (OTP) and second-factor authenticators (WebAuthn). In this guide, you will need to enroll an OTP authenticator application using the QR code on the Teleport welcome screen. -![Teleport UI Dashboard](../../img/quickstart/teleport-nodes.png) +![Teleport UI Dashboard](../img/quickstart/teleport-nodes.png) -## Step 5/6. Log in using tsh +## Step 4/6. Log in using tsh `tsh` is our client tool. It helps you log in to Teleport clusters and obtain short-lived credentials. It can also be used to list resources registered with @@ -231,7 +172,7 @@ Install `tsh` on your local workstation: If you choose to use Homebrew, you must verify that the versions of `tsh` and `tctl` are compatible with the versions you run server-side. Homebrew usually ships the latest release of Teleport, which may be incompatible with older - versions. See our [compatibility policy](../management/operations/upgrading.mdx#component-compatibility) for details. + versions. See our [compatibility policy](./management/operations/upgrading.mdx#component-compatibility) for details. @@ -243,7 +184,7 @@ Install `tsh` on your local workstation: - For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) please see our [installation page](../installation.mdx). + For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) please see our [installation page](./installation.mdx). ```code $ curl -O https://get.gravitational.com/teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz @@ -260,7 +201,7 @@ Log in to receive short-lived certificates from Teleport: ```code # Replace teleport.example.com with your Teleport cluster's public address as configured above. -$ tsh login --proxy=teleport.example.com --user=teleport-admin +$ tsh login --proxy= --user=teleport-admin > Profile URL: https://teleport.example.com:443 Logged in as: teleport-admin Cluster: teleport.example.com @@ -271,27 +212,12 @@ $ tsh login --proxy=teleport.example.com --user=teleport-admin Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` -## Step 6/6. Access resources - -Congrats! You've completed setting up Teleport and signed in to your cluster. -Now you can use Teleport to quickly access resources. - -### Visit your demo website - -Now that you have logged in to Teleport, you can see the demo website you -started earlier. Visit `https://demo.teleport.example.com`, replacing -`teleport.example.com` with the domain name of your Teleport cluster. +## Step 5/6. Access your server -You can use the Teleport Application Service to configure access to any web -application in your private network, including HTTP management endpoints for -popular infrastructure technologies. +Since You configured the Teleport SSH Service, you can easily access your Linux +host after logging in to Teleport. -### SSH into your Node - -You also configured the Teleport SSH Service, meaning that you can easily access -your Linux host after logging in to Teleport. - -See the logins you can use to access a Node: +See the logins you can use to access your server: ```code $ tsh status @@ -320,6 +246,25 @@ SSH into `mynode` as `root`: $ tsh ssh root@mynode ``` +Once you connect to your server, execute some commands in your shell so you can +view a recording of your session later. + +## Step 6/6. Play back your session + +Servers you have registered with Teleport record the commands that users execute +during their sessions so operators can play them back later to investigate +issues. + +In the Teleport Web UI, click the dropdown menu on the upper left of the screen, +then choose **Management**. click the **Activity** tab in the sidebar on the +left of the screen, then click **Session Recordings**. You will see your session +from the previous step: + +![Session +recordings](../img/cloud/getting-started/session-recordings@2x.png) + +Click **PLAY**. You will see a full recording of your session. + ## Next steps ### Add resources @@ -327,25 +272,24 @@ $ tsh ssh root@mynode Now that you know how to set up a Teleport cluster, learn how to register all of the resources in your infrastructure with Teleport: -- [Applications](../application-access/getting-started.mdx) -- [Databases](../database-access/getting-started.mdx) -- [Kubernetes clusters](../kubernetes-access/getting-started.mdx) -- [Servers](../server-access/getting-started.mdx) -- [Windows desktops](../desktop-access/getting-started.mdx) -- [Service accounts](../machine-id/introduction.mdx) (via Machine ID) +- [Applications](./application-access/getting-started.mdx) +- [Databases](./database-access/getting-started.mdx) +- [Kubernetes clusters](./kubernetes-access/getting-started.mdx) +- [Servers](./server-access/getting-started.mdx) +- [Windows desktops](./desktop-access/getting-started.mdx) +- [Service accounts](./machine-id/introduction.mdx) (via Machine ID) ### Manage your cluster You can also check out our collection of step-by-step guides for common Teleport tasks, such as: -- [Managing users](../management/admin/users.mdx) -- [Setting up single sign-on with GitHub](../access-controls/sso/github-sso.mdx) -- [Recording SSH sessions](../server-access/guides/bpf-session-recording.mdx) -- [Labeling Teleport resources](../management/admin/labels.mdx) +- [Managing users](./management/admin/users.mdx) +- [Setting up single sign-on with GitHub](./access-controls/sso/github-sso.mdx) +- [Labeling Teleport resources](./management/admin/labels.mdx) ## Further reading - How Let's Encrypt uses the [ACME protocol](https://letsencrypt.org/how-it-works/) to issue certificates. - Configuration for the `teleport` daemon relies on [systemd](https://www.freedesktop.org/wiki/Software/systemd/). For more information on how the -`teleport` service daemon is configured, see our guide on how to [Run Teleport as a Daemon](../management/admin/daemon.mdx). +`teleport` service daemon is configured, see our guide on how to [Run Teleport as a Daemon](management/admin/daemon.mdx). diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 8aebb20f0748d..1f1bba710c902 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -31,17 +31,15 @@ Client](./connect-your-client/introduction.mdx) guides for instructions. ## Try out Teleport -The fastest way to try out Teleport is to sign up for a free trial of Teleport -Enterprise Cloud and add your first resource. In our [getting started -guide](./choose-an-edition/teleport-cloud/getting-started.mdx), you will -register a local container, access it securely from your browser, record your -SSH session, and play it back. - -After getting acquainted with how Teleport enables secure access to your -infrastructure, follow our [Try out -Teleport](./try-out-teleport/introduction.mdx) guides to set up a demo Teleport -cluster in an environment that works best for you, whether this is a -browser-based lab, virtual machine, or local Kubernetes cluster. +If you are curious to see how Teleport works, you can get started by [spinning +up a demo cluster](./get-started.mdx) on a Linux server. After seeing how your +demo Teleport cluster lets you securely access a server and play back your SSH +sessions, you can configure RBAC, add resources, and protect your home lab with +Teleport. + +You can also get started right away with a production-ready Teleport cluster. +[Sign up for a free trial](https://goteleport.com/signup/) of Teleport +Enterprise Cloud. Once you are ready to learn more about Teleport, read our [Core Concepts guide](./core-concepts.mdx), which introduces the components of a Teleport diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 63cd0d77ffaed..7e434307f31d2 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -12,8 +12,8 @@ including: - `tctl` - `tbot` -If you are new to Teleport, we recommend following our -[getting started guides](./try-out-teleport/introduction.mdx). +If you are new to Teleport, we recommend following our [getting started +guide](./get-started.mdx). For best results, Teleport clients (`tsh`, `tctl`, `tbot`) should be the same major version as the cluster they are connecting to. Teleport servers are compatible @@ -82,10 +82,8 @@ information on obtaining Teleport binaries compatible with Teleport Cloud. -(!docs/pages/includes/docker-images-oss.mdx!) -For instructions on running containers with these images, see -[Getting started with Teleport using Docker](./management/guides/docker.mdx). +(!docs/pages/includes/docker-images-oss.mdx!) @@ -94,9 +92,6 @@ We provide pre-built `amd64`, `arm`, and `arm64` Docker images for every version (!docs/pages/includes/enterprise/docker-images.mdx!) -For instructions on running containers with these images, see -[Teleport Enterprise using Docker](./management/guides/docker.mdx). - diff --git a/docs/pages/management/admin/self-signed-certs.mdx b/docs/pages/management/admin/self-signed-certs.mdx index b4001d4df17f1..fe50fc72c98c0 100644 --- a/docs/pages/management/admin/self-signed-certs.mdx +++ b/docs/pages/management/admin/self-signed-certs.mdx @@ -222,7 +222,7 @@ flag](../../connect-your-client/teleport-connect.mdx#skipping-tls-certificate-ve ## Further reading -- [Configuring Teleport TLS Certs](../../try-out-teleport/linux-server.mdx#configure-teleport) +- [Configuring Teleport TLS Certs](../../get-started.mdx#configure-teleport) - [Run Teleport as a systemd Daemon](./daemon.mdx) - [Teleport Proxy Service](../../architecture/proxy.mdx) - [Teleport Authentication](../../architecture/authentication.mdx) diff --git a/docs/pages/management/admin/upgrading-the-teleport-binary.mdx b/docs/pages/management/admin/upgrading-the-teleport-binary.mdx index c969401286dd4..9c6a1a65f1de0 100644 --- a/docs/pages/management/admin/upgrading-the-teleport-binary.mdx +++ b/docs/pages/management/admin/upgrading-the-teleport-binary.mdx @@ -9,7 +9,7 @@ host without sacrificing availability.
If you are running `teleport` as a container, see -[How to Run Teleport Using Docker](../guides/docker.mdx) for information on +[How to Run Teleport Using Docker](../../installation.mdx#docker) for information on specifying a version.
diff --git a/docs/pages/management/guides.mdx b/docs/pages/management/guides.mdx index 637d6467f3124..47d9c9118275e 100644 --- a/docs/pages/management/guides.mdx +++ b/docs/pages/management/guides.mdx @@ -6,6 +6,5 @@ layout: tocless-doc - [Kubernetes Operator (Preview)](./guides/teleport-operator.mdx). How to add the Teleport Kubernetes Operator to your Kubernetes cluster. - [Terraform Provider](./guides/terraform-provider.mdx). How to configure Teleport Cloud, Open Source, and Enterprise with the Terraform Provider for Teleport. - - [Docker](./guides/docker.mdx). Getting started with Teleport Open Source using Docker. - [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to set up Teleport Node labels based on EC2 tags. - [Using Teleport's Certificate Authority with GitHub](./guides/ssh-key-extensions.mdx). Use Teleport's short-lived certificates with GitHub's Certificate Authority. diff --git a/docs/pages/management/guides/docker.mdx b/docs/pages/management/guides/docker.mdx deleted file mode 100644 index a49ed186ccff5..0000000000000 --- a/docs/pages/management/guides/docker.mdx +++ /dev/null @@ -1,376 +0,0 @@ ---- -title: How to Run Teleport Using Docker -description: This guide shows you how to run Teleport as a Docker image, including a description of our available images and how to access a Teleport container. -h1: Run Teleport using Docker ---- - -This guide will explain how to run a container using one of Teleport's Docker -images and execute commands on that container via Teleport's `tsh` client. - -Since all of Teleport's services are run from the same binary, you can -use our Docker image to run Teleport services (e.g., the Database Service or Application -Service) or explore the Auth and Proxy Services locally. In this guide, we will also show you how to join a server (in this case, an Ubuntu container) to your local Dockerized Teleport cluster. - -## Prerequisites - - - - -- Docker v(=docker.version=) or later. - - ```code - $ docker version - # Client: Docker Engine - Community - # Version: (=docker.version=) - ``` - -- The `tsh` client tool, which ships with the `teleport` binary. Visit [Download Teleport](https://goteleport.com/download/) to download `tsh`. - - - - -- A Teleport Enterprise account. If you do not have one, use our [signup - form](https://goteleport.com/signup/enterprise/) to schedule a demo with the - Teleport Sales Team. - -- Docker v(=docker.version=) or later. - - ```code - $ docker version - # Client: Docker Engine - Community - # Version: (=docker.version=) - ``` - -- The `tsh` client tool, which ships with the `teleport` binary. Visit your [Teleport account](https://teleport.sh) to download Teleport. - - - - -## Step 1/4. Pick your image - - - -(!docs/pages/includes/docker-images-oss.mdx!) - - -We provide pre-built `amd64`, `arm`, and `arm64` Docker images for every version of Teleport Enterprise. - -(!docs/pages/includes/enterprise/docker-images.mdx!) - - - - -## Step 2/4. Start Teleport - - - - -Create Teleport configs and start the process with the following `docker run` commands: - -```code -# Docker image to use. Defaults to the host architecture. Use the `--platform` -# option in `docker run` to override. -$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_oss_docker_image=) -# Create local config and data directories for Teleport, which will be mounted -# into the container. -$ mkdir -p ~/teleport/config ~/teleport/data -# Generate a sample Teleport config and write it to the local config directory. -# This container will write the config and immediately exit--this is expected. -$ docker run --hostname localhost --rm \ - --entrypoint=/usr/local/bin/teleport \ - ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml -# Start Teleport with mounted config and data directories, plus all ports -$ docker run --hostname localhost --name teleport \ - -v ~/teleport/config:/etc/teleport \ - -v ~/teleport/data:/var/lib/teleport \ - -p 3025:3025 -p 3080:3080 \ - ${TELEPORT_DOCKER_IMAGE} -``` - - - - -Create Teleport configs and start the process with the following `docker run` commands: - -```code -# For non-FIPS images we default to the host architecture, which you can -# override with the `--platform` option in `docker run`. For FIPS images -# the default architecture is amd64, which you can override by appending -# `-arm64` or `-arm` to the image tag -$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_docker_image=) - -# Create local config and data directories for Teleport, which will be mounted -# into the container. -$ mkdir -p ~/teleport/config ~/teleport/data -``` - -(!docs/pages/includes/enterprise/obtainlicense.mdx!) - -Move your `license.pem` file to `~/teleport/data`. - -```code -# Generate a sample Teleport config and write it to the local config directory. -# This container will write the config and immediately exit--this is expected. -$ docker run --hostname localhost --rm \ - --entrypoint=/usr/local/bin/teleport \ - ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml -# Start Teleport with mounted config and data directories, plus all ports -$ docker run --hostname localhost --name teleport \ - -v ~/teleport/config:/etc/teleport \ - -v ~/teleport/data:/var/lib/teleport \ - -p 3025:3025 -p 3080:3080 \ - ${TELEPORT_DOCKER_IMAGE} -``` - - - - -## Step 3/4. Creating a Teleport user - -To create a user inside your Teleport container, use `docker exec`. - -This example command will create a Teleport user called `testuser` which is allowed to log in as either `root` or `ubuntu` on the host operating system: - -```code -$ docker exec teleport tctl users add testuser --roles=editor,access --logins=root,ubuntu,ec2-user -``` - -When you run this command, Teleport will output a URL that you must open to complete the user signup process: - -```txt -User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s: -https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7 -NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access. -``` - -The Web UI will be available at the displayed URL. - -(!docs/pages/includes/insecure-certificate.mdx!) - -## Step 4/4. Try server access - -The Teleport container we spun up earlier runs the Teleport Proxy and Auth Services. You can try -accessing a server through Teleport by installing the Teleport SSH Service -on an Ubuntu Docker container. Here are the steps. - -First start an Ubuntu container: - -```code -$ docker run -it --name=example-server --hostname=example-server ubuntu:latest bash -``` -After you start your shell within the Ubuntu container, run the following commands to install the Teleport SSH Service: - - - -```code -# Docker container will start and you can install Teleport -$ apt update && apt install curl -y -# Download Teleport's PGP public key - -$ curl https://apt.releases.teleport.dev/gpg \ --o /usr/share/keyrings/teleport-archive-keyring.asc -# Source variables about OS version - -$ source /etc/os-release -# Add the Teleport APT repository for v12. You'll need to update this -# file for each major release of Teleport. -# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE' -# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'. -# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67 - -$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ -https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \ -| tee /etc/apt/sources.list.d/teleport.list > /dev/null -$ apt-get update -$ apt-get install teleport -``` - - - - -```code -# Docker container will start and you can install Teleport -$ apt update && apt install curl -y -# Download Teleport's PGP public key - -$ curl https://apt.releases.teleport.dev/gpg \ --o /usr/share/keyrings/teleport-archive-keyring.asc -# Source variables about OS version - -$ source /etc/os-release -# Add the Teleport APT repository for v12. You'll need to update this -# file for each major release of Teleport. -# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE' -# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'. -# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67 - -$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ -https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \ -| tee /etc/apt/sources.list.d/teleport.list > /dev/null -$ apt-get update -$ apt-get install teleport-ent -``` - - - - -Keep the Docker `example-server` terminal running and run a separate command -in another terminal to create a join token that the Teleport SSH Service will use to establish trust with your Teleport cluster: - -```code -$ docker exec teleport tctl nodes add -# The invite token: 02adc78db14c4958a94a78e216fba689 -# This token will expire in 30 minutes. - -# Run this on the new node to join the cluster: - -# > teleport start \ - --roles=node \ - --token=02adc78db14c4958a94a78e216fba689 \ - --ca-pin=sha256:51c0e24825fae3133da0d8659f4dd533808e2dc92c000b577c8725b6cbcb66ae \ - --auth-server=172.17.0.2:3025 - -# Please note: - -# - This invitation token will expire in 30 minutes -# - 172.17.0.2:3025 must be reachable from the new node - ``` - -Copy the full `teleport start` command and run it in the `example-server` Docker container shell. - -Open another terminal window and confirm that you joined the SSH Service to the cluster - with `tctl nodes ls` on the `teleport` container. - -```code -$ docker exec teleport tctl nodes ls -# Host UUID Public Address Labels Version -# -------------- ------------------- --------------- ------ ------- -# example-server edc6b7ae-0ae5-43... 172.17.0.3:3022 (=teleport.version=) -``` - -Issue this command, which will log in to your Teleport cluster via the Proxy Service at -`localhost`. - -```code -$ tsh login --proxy=localhost --insecure --user=testuser -``` - - -The `--insecure` flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally. - - -You will be prompted to enter the password and One-Time Passcode you created for your user `testuser`: - -```txt -Enter password for Teleport user testuser: -Enter your OTP token: -9999999 -``` - -After successfully authenticating you should see the following in your terminal: - -```text -WARNING: You are using insecure connection to Teleport proxy https://localhost:3080 -> Profile URL: https://localhost:3080 - Logged in as: testuser - Cluster: localhost - Roles: editor, access - Logins: root, ubuntu - Kubernetes: disabled - Valid until: 2021-06-10 07:15:42 -0500 CDT [valid for 12h0m0s] - Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -``` - -Running the next command will display all Teleport Nodes you're connected to: - -```code -$ tsh ls -# Node Name Address Labels -# -------------- --------------- ------ -# example-server 172.17.0.3:3022 -``` - -To SSH into the local container called `example-server`: - -```code -$ tsh ssh root@example-server -``` - -This will bring up the Linux command prompt where you can issue Bash commands, traverse the directory tree, and explore the container contents: - -```txt -root@example-server:~# -``` - -After exiting the session you can replay the interaction from the command line: - -```code -$ tsh recordings ls -# ID Type Participants Hostname Timestamp -# ------------------------------------ ---- ------------ -------------- ------------------------ -# 1da4faa9-01e9-4241-875f-4143f302c9c4 ssh testuser example-server Apr 13 2023 16:46:59 UTC -$ tsh play 1da4faa9-01e9-4241-875f-4143f302c9c4 -``` - -## Troubleshooting - -Teleport provides a container image that includes a Busybox shell. This image is not intended -for production. You will need to stop the non-debug container and start again with the -debug version to use. - -```code -# Stop teleport container -$ docker stop teleport -# Remove teleport container so another can be started with the same name -$ docker rm teleport -``` - - - - -Use the debug image with the same data and configuration. - -```code -# Debug Docker image to use. Defaults to the host architecture. Use the `--platform` -# option in `docker run` to override. -$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_oss_debug_docker_image=) -# Start Teleport with mounted config and data directories, plus all ports -$ docker run --hostname localhost --name teleport \ - -v ~/teleport/config:/etc/teleport \ - -v ~/teleport/data:/var/lib/teleport \ - -p 3025:3025 -p 3080:3080 \ - ${TELEPORT_DOCKER_IMAGE} -``` - - - - -Use the debug image with the same data and configuration. - -```code -# Debug Docker image to use. Defaults to the host architecture. Use the `--platform` -# option in `docker run` to override. -$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_debug_docker_image=) -# Start Teleport with mounted config and data directories, plus all ports -$ docker run --hostname localhost --name teleport \ - -v ~/teleport/config:/etc/teleport \ - -v ~/teleport/data:/var/lib/teleport \ - -p 3025:3025 -p 3080:3080 \ - ${TELEPORT_DOCKER_IMAGE} -``` - - - - -Now you can open a `sh` shell within the Docker container to perform any troubleshooting. - -```code -$ docker exec -it teleport sh -$ tctl status -``` - -## Next steps - -- Try out one of our [Helm Guides](../../deploy-a-cluster/helm-deployments.mdx). -- Try out one of our [Database Access Guides](../../database-access/guides.mdx). -- Learn about [Teleport Server Access](../../server-access/introduction.mdx). diff --git a/docs/pages/management/operations/proxy-peering.mdx b/docs/pages/management/operations/proxy-peering.mdx index 083f802a9240f..15a2af1463a68 100644 --- a/docs/pages/management/operations/proxy-peering.mdx +++ b/docs/pages/management/operations/proxy-peering.mdx @@ -17,8 +17,7 @@ Proxy Peering is currently in Preview. ## Prerequisites -An existing Teleport Enterprise cluster. See our [getting started guide](../../choose-an-edition/teleport-enterprise/getting-started.mdx) for help -setting up a Teleport cluster. +An existing Teleport Enterprise cluster. See [introduction to Teleport Enterprise](../../choose-an-edition/teleport-enterprise/introduction.mdx) to get started. All components in the cluster should be running Teleport `10.0` or later. See our [upgrade procedure](./upgrading.mdx) for help upgrading a Teleport cluster. diff --git a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx index 7f8fce62b7292..09d539b8af2f2 100644 --- a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx +++ b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx @@ -694,7 +694,7 @@ Normally the version of Teleport being used will match the version of the chart You can optionally override this to use a different published Teleport Docker image tag like `10.2.2` or `11`. -See [this link for information on Community Docker image versions](../../management/guides/docker.mdx#step-14-pick-your-image). +See [this link for information on Community Docker image versions](../../installation.mdx#docker). The `teleport-kube-agent` chart always runs using Teleport Community edition as it does not require any Enterprise features, so it does diff --git a/docs/pages/try-out-teleport/browser-labs.mdx b/docs/pages/try-out-teleport/browser-labs.mdx deleted file mode 100644 index 05d984bec30f9..0000000000000 --- a/docs/pages/try-out-teleport/browser-labs.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Teleport Labs -description: Try out Teleport with these hands-on, browser-based labs. -layout: tocless-doc ---- - -You can quickly try out some of Teleport's key features from your browser. - -Choose one of our [interactive learning tracks](https://play.instruqt.com/teleport/invite/imz8g1n1xzru), which are hosted by Instruqt. These labs cover: - -- Teleport server access, which makes it easier to configure onboarding, RBAC, and auditing for SSH connections to remote hosts. -- Teleport application access, which gives you secure access to your internal web applications. -- Teleport database access, to learn how to securely access and configure a remote MySQL database. -- Teleport Kubernetes access, which provides advanced RBAC controls and auditing for `kubectl` commands. diff --git a/docs/pages/try-out-teleport/digitalocean.mdx b/docs/pages/try-out-teleport/digitalocean.mdx deleted file mode 100644 index 0f5bccc7c78d9..0000000000000 --- a/docs/pages/try-out-teleport/digitalocean.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Getting started with Teleport on DigitalOcean -description: How to install Teleport on DigitalOcean? -videoBanner: voHQlSX_czE ---- - -This tutorial will guide you through quickly getting started with Teleport on -DigitalOcean with the Teleport 1-Click Droplet app. - - - -If you are looking for a manual installation, refer to our [Linux installation -guide](./linux-server.mdx). - - - -(!docs/pages/includes/cloud/call-to-action.mdx!) - -## Prerequisites -- A Fully Qualified Domain Name (FQDN). -- A two-factor authenticator app (e.g., [Google Authenticator](https://www.google.com/landing/2step/)). -- An SSH client like OpenSSH. - -## Step 1/3. Install Teleport with 1-Click - -Head over to the Teleport page on [DigitalOcean Marketplace](https://marketplace.digitalocean.com/apps/teleport) and click the “Create a Droplet” button: - -
- ![Teleport 1-Click droplet page](../../img/quickstart/digitalocean/1click-droplet-page.png) -
- -Once you click the button, DigitalOcean redirects you to the control panel to configure resources for the Teleport droplet. This step is similar to how you create a regular [droplet in DigitalOcean](https://docs.digitalocean.com/products/droplets/how-to/create/). Teleport is very lightweight, and if you are just trying out Teleport, you can select the $5 droplet. Make sure you select "SSH keys" as the SSH authentication method as it is more secure than a password. -
- ![Create a droplet](../../img/quickstart/digitalocean/create-droplet.png) -
- -It will take a few minutes before our newly created Teleport droplet is ready. Once the droplet is ready, configure your FQDN with the public IP address of the droplet as an IP address for the `A` record of your domain name. -For example, refer to the image below; we use the domain name `example.com`. The resulting domain we are using as an FQDN is `tele.example.com`, pointing to our Teleport droplet's public IP `192.168.200.200`. -
- ![Configure DNS](../../img/quickstart/digitalocean/fqdn.png) -
- -## Step 2/3. Configure Teleport -When you are ready with your FQDN, SSH to your droplet. In your first login, a wizard will guide you through the initial Teleport setup. - -``` -$ ssh root@teleport_host -********************************************************* -** Configuring Teleport ** -********************************************************* -___ -• Enter Teleport cluster name (FQDN): dodemo.teleporters.dev (replace with your FQDN) -• Enter your email address to retrieve TLS certificate from Lets Encrypt: dodemo@teleporters.dev (replace with your email address) -• Enter a username for the initial Teleport user: tadmin - -Initializing... -[+] Generating new host UUID... -[+] Updating cluster networking configuration... -[+] Generating user and host certificate authority... -[+] Enabling RBAC in OSS Teleport. Migrating users, roles and trusted clusters... -[+] Starting Auth and Proxy services... -[+] Final Checks... - -*************************************************************************** -** --- -** Teleport is configured and user tadmin has been created -** but requires a password. Open the URL link below to complete the -** setup. The link is valid for 1h: -** -** https://tele.example.com:443/web/invite/ -** -** --- -** HAPPY TELEPORTING :) -*************************************************************************** -``` - -Copy the URL link printed in this step: -`https://tele.example.com:443/web/invite/` - -This link opens up Teleport Web UI, where you will need to set a password and configure two-factor authentication to complete the user setup process. - -## Step 3/3. Complete user setup and log in to Teleport UI -Open the link copied in the previous step in the browser to complete the setup process. When the web page is ready: -1. Scan the QR code with your two-factor authentication app (e.g., Google Authenticator) -2. Set a password and enter the TOTP code generated from the two-factor authentication app. -
- ![Set up user](../../img/quickstart/digitalocean/setup-user.png) -
- -Once you set up a password and provide a valid TOTP code, the user setup process will be complete, and you will be redirected to Teleport Web UI: - -
- ![Teleport Web UI](../../img/quickstart/digitalocean/webui.png) -
- -Congrats! You've completed setting up Teleport. - -## Next steps -Finally, you are a step closer to managing secure access to your infrastructure hosted in DigitalOcean. -Teleport lets you enable [certificate-based authentication for SSH](../server-access/getting-started.mdx) access. If you want to protect public access to internal applications such as GitLab or Grafana, check out our getting started guide on [Application Access](../application-access/getting-started.mdx). - -You can also secure access to databases, DigitalOcean Marketplace apps, and Kubernetes clusters using Teleport. Below are the links to get started further: -- [Server Access](../server-access/getting-started.mdx): Single Sign-On, short-lived certificates, and audit for SSH servers. -- [Application Access](../application-access/getting-started.mdx): Secure access to internal dashboards and web applications. -- [Kubernetes Access](../kubernetes-access/getting-started.mdx): Single Sign-On, audit and unified access for Kubernetes clusters. -- [Database Access](../database-access/getting-started.mdx): Secure access to PostgreSQL, MySQL and MongoDB databases. -- [Desktop Access](../desktop-access/getting-started.mdx): Secure access to Windows Server. diff --git a/docs/pages/try-out-teleport/docker-compose.mdx b/docs/pages/try-out-teleport/docker-compose.mdx deleted file mode 100644 index 6682fef607f06..0000000000000 --- a/docs/pages/try-out-teleport/docker-compose.mdx +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Getting started with Teleport using Docker Compose -description: How to get started with Teleport Open Source Edition using Docker Compose locally. -h1: Get started with Docker Compose ---- - -This guide will help you understand how Teleport works by spinning up a demo -cluster on your local machine using Docker Compose. It will also show you how to -use Teleport with OpenSSH, Ansible, and Teleport's native client, `tsh`. - - - -This guide is intended as a local lab for educational purposes. If you would -like to set up Teleport for production usage, please see: - - - -[Getting Started on a Linux Server](../try-out-teleport/linux-server.mdx) - - - - -[Getting Started](../choose-an-edition/teleport-cloud/getting-started.mdx) - - - - -[Getting Started](../choose-an-edition/teleport-enterprise/getting-started.mdx) - - - - - -## Prerequisites - -- Docker v(=docker.version=) or later. The Teleport Docker image we use in the Docker Compose lab currently only supports `x86_64` architectures. -- [`docker-compose`](https://docs.docker.com/compose/install/) v(=docker.compose.version=) or later (or the Compose plugin for Docker). - -```code -$ docker-compose version -# docker-compose version (=docker.compose.version=), build unknown - -$ docker version -#Client: Docker Engine - Community -# Version: (=docker.version=) -``` - -## Step 1/3. Start demo lab - -Let's use `docker-compose` to start Teleport demo lab - a configured local cluster: - -```code -# Download the quick start file from our GitHub repo -$ curl -Lso teleport-lab.yml https://raw.githubusercontent.com/gravitational/teleport/v(=teleport.version=)/docker/teleport-lab.yml -# Pull the latest image and start the teleport demo lab using docker-compose -$ docker-compose -f teleport-lab.yml pull && docker-compose -f teleport-lab.yml up -d -``` - - -You can later stop the Teleport lab using: - -```code -$ docker-compose -f teleport-lab.yml down -``` - - -## Step 2/3. Explore CLI - -Let's jump into the container and explore Teleport: - -```code -# From your local terminal -$ docker exec -ti term /bin/bash -``` - - -We will run all future commands from the `term` container. - - -Welcome to Teleport Lab. With Teleport you can access servers, databases and web apps in your cluster. - -Let's Try a couple of commands to get started. -Teleport speaks SSH. You can SSH into it using OpenSSH: - -```code -# From term container -$ ssh root@luna.teleport -``` - -Teleport is a bastion server for your OpenSSH hosts. SSH into OpenSSH server and record all commands: - -```code -# From term container -$ ssh root@mars.openssh.teleport -``` - -You can also run Ansible on Teleport Nodes and OpenSSH servers: - -```code -# From term container -$ cd /etc/teleport.d/ansible && ansible all -m ping -``` - -Try Teleport's client command: `tsh`. It's like `ssh`, but with superpowers. -Find all hosts matching label `env=example` and run `hostname` command: - -```code -# From term container -$ tsh ssh root@env=example hostname -``` - -You can see Teleport's nodes registered in the cluster using `tsh ls` command: - -```code -# From term container -$ tsh ls -# Node Name Address Labels -# ------------- -------------- -------------------------- -# luna.teleport 127.0.0.1:3022 env=example, hostname=luna -``` - -## Step 3/3. Explore web UI - -Create a Teleport user called `testuser` which is allowed to log in as either operating system user `root` or `ubuntu`. - -```code -# From term container -$ tctl users add testuser --roles=editor,access --logins=root,ubuntu -``` - -Teleport will output a URL that you must open to complete the user sign-up process: - -```code -User "testuser" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h: -https://proxy.luna.teleport:443/web/invite/your-token-here -NOTE: Make sure proxy.luna.teleport:443 points at a Teleport proxy which users can access. -``` - -Port `443` on the Teleport container is published to the local host, so you can access the invitation page at `https://localhost/web/invite/your-token-here`. - -(!docs/pages/includes/insecure-certificate.mdx!) - -## Next steps - -- Learn about [Teleport Server Access](../server-access/introduction.mdx). -- Learn about [Teleport Access Controls](../access-controls/getting-started.mdx). -- Get started with [Teleport Session Recording](../server-access/guides/bpf-session-recording.mdx). -- Try out one of our [Database Access Guides](../database-access/guides.mdx). -- For Kubernetes environments, try out one of our [Helm Guides](../deploy-a-cluster/helm-deployments.mdx). - -## Under the hood - -Let's unpack some of the setup that made the demo possible. -Teleport's authentication is based on client certificates and certificate authorities. - -Here is `~/.ssh/config`, which instructs the `ssh` client to use Teleport -as a bastion server: - -``` -## Hosts with openssh suffix are OpenSSH nodes listening on port 22 as usual -Host *.openssh.teleport - ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:22 - -# Hosts without openssh suffix are Teleport Nodes listening on port 3022 -Host *.teleport !proxy.luna.teleport - ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:3022 -``` - -Ansible is set up to use ssh config above: - -``` -[defaults] -host_key_checking = True -inventory=/etc/teleport.d/ansible/hosts -remote_tmp=/tmp - -[ssh_connection] -scp_if_ssh = True -ssh_args = -F /root/.ssh/config -``` - -OpenSSH server is set up to trust Teleport's CA and uses Teleport-issued -host certificate: - -``` -TrustedUserCAKeys /mnt/shared/certs/teleport.pub -HostKey /mnt/shared/certs/mars.openssh.teleport -HostCertificate /mnt/shared/certs/mars.openssh.teleport-cert.pub -``` - -Teleport's user and role used for bot access: - -```yaml -kind: role -version: v5 -metadata: - name: bot -spec: - # SSH options used for user sessions - options: - # max_session_ttl defines the TTL (time to live) of SSH certificates - # issued to the users with this role. - max_session_ttl: 10h - - # allow section declares a list of resource/verb combinations that are - # allowed for the users of this role. by default nothing is allowed. - allow: - logins: ['root'] - node_labels: - '*': '*' ---- -kind: user -version: v2 -metadata: - name: bot -spec: - roles: ['bot'] -``` - -Our lab uses admin tool `tctl` to generate and export certs: - -```code -# Exports user CA for OpenSSH to trust. -tctl auth export --type=user | sed s/cert-authority\ // > ./teleport.pub - -# Export host CA for SSH client to trust, update some hostnames match patterns -tctl auth export --type=host | sed s/*.teleport/luna.teleport,*.luna.teleport,*.openssh.teleport/ > ./teleport-known_hosts.pub - -# Creates a user and a role in Teleport -tctl create -f /etc/teleport.d/scripts/resources.yaml - -# Create SSH cert for bot user -tctl auth sign --user=bot --format=openssh --out=bot --overwrite --ttl=10h - -# Create SSH host cert for SSH node -tctl auth sign --host=mars.openssh.teleport --format=openssh --overwrite --out=mars.openssh.teleport - -# Adds generated certs to SSH agent on start -cd /mnt/shared/certs && /usr/bin/ssh-add bot; -``` diff --git a/docs/pages/try-out-teleport/introduction.mdx b/docs/pages/try-out-teleport/introduction.mdx deleted file mode 100644 index e13905174bcdf..0000000000000 --- a/docs/pages/try-out-teleport/introduction.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Try out Teleport" -description: "See how Teleport works before you set up a full deployment" ---- - -While Teleport is designed to manage access to infrastructure with thousands of -virtual machines, Kubernetes pods, and managed services, you can get started -quickly with a demo environment. - -You can try out Teleport in browser-based labs, single-instance open source -Teleport deployments, or local, container-based Teleport clusters. - -## Browser labs - -Try out Teleport in your browser without setting up any infrastructure. Our -browser labs let you interact with an already running Teleport cluster so you -can get acquainted with Teleport's commands and capabilities: - -[Check out our browser labs](./browser-labs.mdx). - -## Demo deployments - -You can set up a small-scale Teleport deployment that you can use to manage -access to your home lab or demo project. Once you have set up your demo -deployment, you can use it to add resources, set up RBAC, and enjoy secure -access to your infrastructure: - -- [Try out Teleport on a Linux Server](./linux-server.mdx) -- [Use the 1-Click Digital Ocean Droplet for Teleport](./digitalocean.mdx) - -## Local deployments - -If you would like to try Teleport without setting up any infrastructure, but -would still like a real deployment that you can play with, check out our local -deployment labs: - -- [Docker Compose Lab](./docker-compose.mdx) -- [Local Kubernetes Lab](./local-kubernetes.mdx) diff --git a/docs/pages/try-out-teleport/local-kubernetes.mdx b/docs/pages/try-out-teleport/local-kubernetes.mdx deleted file mode 100644 index 2d14387d8cd22..0000000000000 --- a/docs/pages/try-out-teleport/local-kubernetes.mdx +++ /dev/null @@ -1,424 +0,0 @@ ---- -title: Try Teleport on a Local Kubernetes Cluster -description: Use this local demo to get started with Teleport on Kubernetes in 10 minutes. ---- - -In this guide, we will show you how to set up Teleport on a local Kubernetes -cluster. You will see how Teleport enables users to access private resources in -your cluster—all from a single ingress port—so you can manage authentication, -authorization, and audit. - -## The demo environment - -Our demo will run using minikube, which deploys Kubernetes on your local -machine. The cluster will run Kubernetes Dashboard, the official browser UI for -Kubernetes. - -While it is possible to expose the dashboard outside the cluster using the -`kubectl proxy` command, in our demo the dashboard will only be accessible via -Teleport. - -We will deploy the following Teleport components: - -- **Teleport Auth Service:** The certificate authority for your cluster. It -issues certificates and conducts authentication challenges. -- **Teleport Proxy Service:** The cluster frontend, which handles user requests, - forwards user credentials to the Auth Service, and communicates with Teleport - instances that enable access to specific resources in your infrastructure. -- **Teleport Application Service:** Enables access to Kubernetes Dashboard for - authorized end-users. - -One pod will run the Auth Service and Proxy Service, and a second pod will run -the Application Service. - -## Prerequisites - -While this guide deploys resources only on your local development machine, you -will need access to the Internet in order to pull Helm charts and container -images. - -Make sure that the following tools are installed locally: - -| Tool | Purpose | Installation link | -|---------------------------------------------------------------------|----------------------------------|---------------------------------------------------------------| -| minikube | Local Kubernetes deployment tool | [Install minikube](https://minikube.sigs.k8s.io/docs/start/) | -| Helm | Kubernetes package manager | [Install Helm](https://helm.sh/docs/intro/install/) | -| kubectl | Kubernetes admin CLI | [Install kubectl](https://kubernetes.io/docs/tasks/tools/) | -| Docker | Required minikube driver | [Get Started With Docker](https://www.docker.com/get-started) | - -You should also install a one-time passcode (OTP) application like Authy on your -mobile device. You will use this to authenticate to your Teleport cluster. - -## Step 1/4 Deploy resources - -### Start minikube - -Start minikube with the Docker driver: - -```code -$ minikube start --driver=docker -``` - -(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!) - -### Install the Teleport Auth Service and Proxy Service - -You will deploy the Auth Service and Proxy Service by installing the -`teleport-cluster` Helm chart. To do so, run the following commands: - -```code -# This is the DNS name Kubernetes will assign to the Proxy Service -$ CLUSTER_NAME="teleport-cluster.teleport-cluster.svc.cluster.local" -$ helm install teleport-cluster teleport/teleport-cluster \ - --create-namespace \ - --namespace=teleport-cluster \ - --set clusterName=${CLUSTER_NAME?} \ - --version (=teleport.version=) -$ kubectl config set-context --current --namespace teleport-cluster -``` - -Any `kubectl` commands you run will now use the `teleport-cluster` namespace. - -Verify that Teleport is running. - -```code -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -teleport-cluster-auth-57989d4cbd-4q2ds 1/1 Running 0 46s -teleport-cluster-proxy-69c9c4c986-j9v2j 1/1 Running 0 46s -``` - -### Expose the Proxy Service to your local machine - -The `teleport-cluster` service is of type `LoadBalancer`, meaning that your -platform needs to supply a load balancer to route traffic to the service. - -The `minikube tunnel` command provides a load balancer and establishes a reverse -SSH tunnel to ports on your local machine. - -Open a new terminal and run the following command to create a reverse tunnel. In -this case, the tunnel forwards port 443, so you will need to enter your -password: - -```code -$ minikube tunnel -✅ Tunnel successfully started - -📌 NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ... - -❗ The service/ingress teleport-cluster requires privileged ports to be exposed: [443] -🔑 sudo permission will be asked for it. -🏃 Starting tunnel for service teleport-cluster. -Password: -``` - -The `teleport-cluster` service should now have an external IP: - -```code -$ kubectl get services -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -teleport-cluster LoadBalancer 10.107.218.212 127.0.0.1 443:32143/TCP,3023:30618/TCP,3026:32750/TCP,3024:32406/TCP,3036:30687/TCP 6m18s -teleport-cluster-auth ClusterIP 10.107.218.220 3025/TCP,3026/TCP 6m18s -``` - -The Proxy Service enables you to manage your cluster via an HTTP API. Assign the -external IP of the load balancer to an environment variable and verify that the -HTTP API is working. The example below uses [jq](https://stedolan.github.io/jq/) -to format the API response, but you can omit it if not installed: - -```code -# Define EXTERNAL_IP, which we will use again in this guide -$ EXTERNAL_IP=$(kubectl get service teleport-cluster -o jsonpath='{ .status.loadBalancer.ingress[0].ip }') -# Define TELEPORT_PING_URL to test against -$ TELEPORT_PING_URL="https://${EXTERNAL_IP?}:443/webapi/ping" -$ curl --insecure $TELEPORT_PING_URL | jq -{ - "auth": { - "type": "local", - "second_factor": "otp", - "preferred_local_mfa": "otp", - "has_motd": false - }, - "proxy": { - "kube": { - "enabled": true, - "listen_addr": "0.0.0.0:3026" - }, - "ssh": { - "listen_addr": "[::]:3023", - "tunnel_listen_addr": "0.0.0.0:3024", - "public_addr": "teleport-cluster:443" - }, - "db": { - "mysql_listen_addr": "0.0.0.0:3036" - }, - "tls_routing_enabled": false - }, - "server_version": "8.2.0", - "min_client_version": "7.0.0" -} -``` - -
- -The `minikube tunnel` command works by executing the `ssh` binary in `PATH` to -establish a reverse tunnel from the `minikube` container to the local host. It -uses credentials managed by `minikube` to authenticate. - -If you are getting a "Connection refused" error, that probably means that the `ssh` command has failed. Try the following steps: - -- If the SSH agent is running, the `ssh` command will attempt to load keys from - the agent. If there are too many keys loaded, the `ssh` client will fail to - authenticate. Clear any keys from the SSH agent using the following command: - - ```code - $ ssh-add -D - ``` - -- Ensure that no configuration options or environment variables are conflicting - with the `ssh` command, which will resemble the following: - - ```code - $ sudo ssh -o UserKnownHostsFile=/dev/null \ - -o StrictHostKeyChecking=no \ - -N docker@127.0.0.1 \ - -p 49894 \ - -i /${HOME}/.minikube/machines/minikube/id_rsa \ - -L 443:10.98.6.171:443 \ - -L 3023:10.98.6.171:3023 \ - -L 3026:10.98.6.171:3026 \ - -L 3024:10.98.6.171:3024 \ - -L 3036:10.98.6.171:3036 - ``` - -
- - -The Teleport Proxy Service requires a TLS certificate and private key. In this -guide, Teleport runs with a self-signed certificate. For convenience, we -configure HTTP clients not to verify the certificate. - -In production setups, you will need to configure Teleport to use a certificate -from a certificate authority like Let's Encrypt. - - -### Configure DNS - -For the Proxy Service to communicate with end-users and Teleport resource -services, it needs a domain name that is resolvable both inside and outside your -Kubernetes cluster. - -Production Teleport deployments achieve this by either using a registered domain -name or an internal DNS infrastructure. For this demonstration, we will -edit the `/etc/hosts` file instead. - - -Set yourself a reminder to clean up your `/etc/hosts` -file when you are done with this guide. - - -Append an entry to your `/etc/hosts` file that maps the external IP of your -Proxy Service to the DNS name Kubernetes assigns, plus a DNS name we will use -later for Kubernetes Dashboard. - -```code -$ sudo -E bash -c "echo \"${EXTERNAL_IP?} teleport-cluster.teleport-cluster.svc.cluster.local kube-dash.teleport-cluster.teleport-cluster.svc.cluster.local\" >> /etc/hosts" -``` - -`teleport-cluster.teleport-cluster.svc.cluster.local` is the DNS name that -Kubernetes assigns to the Proxy Service. As you complete this guide, the -Application Service will make Kubernetes Dashboard available at the -`kube-dash` subdomain of the Proxy Service's domain name. - -### Deploy Kubernetes Dashboard - -Deploy Kubernetes Dashboard using the following command: - -```code -$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.4.0/aio/deploy/recommended.yaml -``` - -Verify that the dashboard and metrics scraper services are running: - -```code -$ kubectl get services -n kubernetes-dashboard -``` - -You should see output similar to: - -```text -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -dashboard-metrics-scraper ClusterIP 10.100.9.163 8000/TCP 8s -kubernetes-dashboard ClusterIP 10.100.80.65 443/TCP 8s -``` - -The `kubernetes-dashboard` service has an open HTTPS port but is not accessible -outside the cluster (i.e., it has no external IP). By enabling the Teleport -Application Service, we will alow users to securely access the dashboard. - - - -If installing the dashboard leads to an unexpected result, -check the following documentation for updated installation steps: -[Deploying the Dashboard UI](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#deploying-the-dashboard-ui). - - - -## Step 2/4 Create a user - -We will create a Teleport user who can access Kubernetes Dashboard from -outside the cluster. To do this, we will use the `tctl` administrative tool from -inside the pod that runs the Auth Service and Proxy Service. - -Run the following commands to get the name of the relevant pod and execute a -`tctl` command to create a user: - -```code -$ kubectl exec -it deployment/teleport-cluster-auth -- tctl users add --roles=access appuser -User "appuser" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h: -https://teleport-cluster.teleport-cluster.svc.cluster.local:443/web/invite/ -``` - -Next, open a browser at the URL returned by `tctl users add` command. minikube's -reverse tunnel will allow you to access the Teleport Proxy Service at -`https://teleport-cluster.teleport-cluster.svc.cluster.local:443`. - -(!docs/pages/includes/insecure-certificate.mdx!) - -![Teleport User Registration](../../img/quickstart/login.png) - -In the Teleport Web UI, enter a password and scan the QR code with your OTP -application to create your user. - -
-We recommend requiring MFA for all Teleport users. However, for -convenience while setting up your local demo, you can run the following command -to create a dynamic configuration resource that disables MFA for your demo user: - -```code -$ kubectl exec -i deployment/teleport-cluster-auth -- bash -c "cat<>/home/cp.yaml -kind: cluster_auth_preference -version: v2 -metadata: - name: cluster-auth-preference -spec: - type: local - second_factor: "off" -EOF -tctl create --force --confirm /home/cp.yaml" -``` - -
- -After signing in, you will navigate to the Teleport Web UI. - -## Step 3/4 Enable access to Kubernetes Dashboard - -We will configure the Teleport Application Service to proxy traffic to -Kubernetes Dashboard so we can access it securely from outside the cluster. - -To do so, we will generate a token that our Application Service Node can use to -register itself with the cluster, then run the Application Service with the -token, configuring it to access Kubernetes Dashboard. - -Run the following commands to generate the token, which is specific to -Kubernetes Dashboard: - -```code -# The cluster IP of Kubernetes Dashboard -$ DASH_ADDR=$(kubectl -n kubernetes-dashboard get service kubernetes-dashboard -o jsonpath="{.spec.clusterIP}") -$ kubectl exec -it deployment/teleport-cluster-auth -- tctl tokens add \ ---type=app \ ---app-name=kube-dash \ ---app-uri=https://$DASH_ADDR -The invite token: . -This token will expire in 60 minutes. -... -``` - -Copy the invite token so you can assign it to `INVITE_TOKEN` below, then launch the -Teleport Application service: - -```code -# If you need to retrieve this again you can run "tctl tokens ls" -$ INVITE_TOKEN= -$ PROXY_ADDR="$(kubectl get service teleport-cluster -o jsonpath="{.spec.clusterIP}"):443" -$ helm install teleport-kube-agent teleport/teleport-kube-agent \ - --namespace teleport-cluster \ - --set roles=app \ - --set proxyAddr=${PROXY_ADDR?} \ - --set authToken=${INVITE_TOKEN?} \ - --set "apps[0].name"="kube-dash" \ - --set "apps[0].uri"=https://${DASH_ADDR?} \ - --set insecureSkipProxyTLSVerify=true \ - --version (=teleport.version=) -``` - -
-In this `helm install` command, we use the `insecureSkipProxyTLSVerify=true` -option to prevent the Application Service from verifying the TLS certificate of -the Proxy Service. - -This is because, in our environment, the TLS certificate is -valid for `127.0.0.1`, the external IP of the Proxy Service, while the -Application Service sees the Proxy Service's cluster IP. - -Production environments must not skip TLS certificate verification. -
- - -Run the following command: - -```code -$ kubectl exec -it deployment/teleport-cluster-auth -- tctl tokens ls -``` - - - -Visit the Teleport Web UI at the following link: - -{/* This link will trigger the dead link checker, but exists for the convenience -of readers who have launched a local Application Service. */} - -{/* lint ignore no-dead-urls */} - -[Applications](https://teleport-cluster.teleport-cluster.svc.cluster.local/web/cluster/teleport-cluster.teleport-cluster.svc.cluster.local/apps) - -You will now see Kubernetes Dashboard as connected to your cluster. - -![An application connected to your Teleport cluster](../../img/connected-app.png) - -To access Kubernetes Dashboard, click "LAUNCH." If you see an authentication -form with the title, "Kubernetes Dashboard," you have successfully gained access -via Teleport on Kubernetes. - -If you want to play around with the dashboard, read the following guide: - -[Deploy and Access the Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) - -## Step 4/4 Clean up - -Now that you have successfully accessed Kubernetes Dashboard, make sure to -remove the entry you added to your `/etc/hosts` file. - -Terminate the `minikube tunnel` process you started earlier and run -`minikube delete` to tear down your demo cluster. - -## Next steps - -To see all of the options you can set in the values file for the -`teleport-cluster` and `teleport-kube-agent` Helm charts, consult our [reference -guide](../reference/helm-reference.mdx). - -Now that you have used Teleport to securely access resources in your local -Kubernetes cluster, read our guides to setting up Teleport for Kubernetes in -production. - -- Get started with Teleport on AWS EKS: [Running an HA Teleport cluster using - AWS, EKS, and Helm](../deploy-a-cluster/helm-deployments/aws.mdx) -- Manage access to your Kubernetes cluster with the Teleport Kubernetes Service: - [Connect Kubernetes Cluster to Teleport](../kubernetes-access/getting-started.mdx) -- Integrate Teleport with your SSO provider: - [Single Sign-On and Kubernetes RBAC](../kubernetes-access/controls.mdx) -- Have a Kubernetes cluster but don't want to run Teleport there? - [Kubernetes Access from Standalone Teleport](../kubernetes-access/register-clusters/static-kubeconfig.mdx)