diff --git a/content/18.x b/content/18.x index 8d0b22f..c26faf4 160000 --- a/content/18.x +++ b/content/18.x @@ -1 +1 @@ -Subproject commit 8d0b22f75dbecaeb1696a3be7a4cf5059d53a793 +Subproject commit c26faf44eec446da51382192781d830a6bfbb766 diff --git a/docs/get-started_test_copy.mdx b/docs/get-started_test_copy.mdx new file mode 100644 index 0000000..89aefe4 --- /dev/null +++ b/docs/get-started_test_copy.mdx @@ -0,0 +1,252 @@ +--- +title: "Get Started with Teleport" +description: "Shows you how to set up a Teleport Enterprise (Cloud) account and protect your first resource with Teleport." +tocDepth: 3 +--- + +## Was this helpful? + + + +Teleport Enterprise helps organizations provide secure access to their +infrastructure with minimal configuration and cluster management. + +With Teleport Enterprise (Cloud), the Teleport Auth Service and Teleport Proxy +Service are managed for you as cloud-based services. These services provide you +with immediate access to a scalable and fault-tolerant certificate authority and +reverse proxy that you don't need to manage or maintain. You can focus on +enrolling the resources you want to protect and configuring secure role-based +access for private and public networks across the globe. + +After you start a [free trial](https://goteleport.com/signup) of Teleport +Enterprise (Cloud), you can set up role-based access control (RBAC), enable +single sign-on, and prevent unauthorized use of organization resources. + +This guide explains how to register a local server with a Teleport Enterprise +(Cloud) account. After you register the server, you can access it through the +Teleport Web UI in a browser or using the terminal. You can also record your +sessions, so you can review them later. + +## Prerequisites + +- A Teleport Enterprise (Cloud) account. You can sign up for a free trial at the + following page: + + https://goteleport.com/signup/ + + After you sign up, you receive an email invitation to activate your account. + Use this account to authenticate your identity when you access the Teleport + Enterprise (Cloud) cluster. + +- For following this guide, Docker installed on your workstation. + + This guide illustrates how to register a server with Teleport Enterprise Cloud + using a Docker container and the Teleport SSH Service. Docker is only required + for the local demo environment used in this guide. You can find installation + instructions for Docker on [Docker's + website](https://docs.docker.com/get-docker/). If you want to register servers + in Teleport without using Docker, see the getting started guide for + [server access](enroll-resources/server-access/getting-started.mdx). + +- The `tsh` client tool. `tsh` is included in the same packages and archives as + the `teleport` binary. See the [Installation Guide](installation.mdx) for how + to install Teleport on your operating system. + + This guide only requires the `tsh` client tool to access a server from a + terminal. If you don't install the `tsh` client tool, you can access the + server in Teleport Enterprise (Cloud) using the Web UI through your browser. + +## Step 1/5. Spin up a server + +To spin up a new server using Docker: + +1. Open a terminal on your workstation. + +1. Start a Docker container on your workstation to prepare a server that you want enroll +as a resource in your Teleport Enterprise (Cloud) cluster: + + ```code + $ docker run --interactive --tty ubuntu:24.04 /bin/bash + ``` + + This command starts a new shell session in a container running Ubuntu 24.04. + +1. Run the following command to install `curl` and `telnet` from the package management repository: + + ```code + $ apt update && apt install -y curl telnet + ``` + + The script that installs Teleport in this guide requires both `curl` and `telnet` to be installed. + + Keep the new shell open in your terminal. + +## Step 2/5. Install the Teleport SSH Service + +To install the Teleport SSH Service on your server: + +1. Open a browser and go to the address for your Teleport cluster. For example, + if your Teleport account is `example`, open `https://example.teleport.sh`. + +1. Sign in with the credentials you used to activate your Teleport account. + + The first time you sign in, you are prompted to add your first resource: + + ![Add your first resource](../img/cloud/getting-started/add-my-first-resource@2x.png) + +1. Click **Add my first resource**, and you will see the option to enroll + resources in your Teleport cluster. + +1. Type *server* in the search box to filter the list of resources: + + ![Select resource type](../img/cloud/getting-started/choose-resource@2x.png) + +1. Click **Ubuntu 18.04+** to register the server in the Docker container. + + After you select the resource type, the Web UI prompts you for your + multi-factor authentication device, then displays a script to install and + configure the Teleport SSH Service. For example: + + ![Configure resource](../img/cloud/getting-started/paste-script@2x.png) + +1. The Teleport installation script uses `sudo`, which is not installed on your + Docker container. Before copying the command to run the installation script, + you need to alias `sudo` in the container terminal shell session. + + In the terminal with the container shell session, alias `sudo` by running +the following command: + + ```code + $ alias sudo="" + ``` + +1. Copy the command to run the installation script from the Teleport Web UI and paste it +into the container shell session. + + Leave the script running in the shell. After Teleport is installed on the server, + you'll see a message in the Web UI that your new Teleport instance was successfully detected: + + ![Connected successfully](../img/cloud/getting-started/successfully-connected@2x.png) + + To continue, click **Next**. + +1. Confirm that you want to authenticate as the `root` user and click **Next**: + + ![Choose your user](../img/cloud/getting-started/set-up-access@2x.png) + +1. Respond to the MFA prompt again, then click **Test Connection** to verify + access to the server. + + ![Start session](../img/cloud/getting-started/test-connection@2x.png) + +## Step 3/5. Start a session + +To start a session on the server you just added to Teleport: + +1. Click **Start Session** to start an interactive session. + + You should see a terminal prompt in a new browser window. Your Teleport + account routes your SSH connection through the Teleport Proxy Service, which + connects to your container through a reverse tunnel. + Reverse tunnels allow Teleport to manage access to resources like Kubernetes + clusters and remote desktops, even if these resources are running on private networks. + + If you get an error connecting to your container, interrupt the `teleport` process in + the container shell with **Ctrl-C**, then run `teleport start` to restart the process. + +1. Execute some commands in your terminal. + +1. Enter the `exit` command to end the remote interactive session. Close the + browser tab. + +1. In the last step of **Enroll New Resource**, click **Finish**. + +1. Click **Browse existing resources** to see your new server listed in the Teleport Web UI. + +## Step 4/5. Play back your session + +As Teleport proxies SSH connections to registered servers, it records the +commands that users execute during their sessions so operators can play them +back later to investigate issues. + +To play back a session in the Teleport Web UI: + +1. Find the left sidebar and navigate to **Audit > Session Recordings**. + +1. In the sidebar, under **Activity**, click **Session Recordings**. + + You will see the recording for your interactive session from the previous + step listed. For example: + + ![Session + recordings](../img/cloud/getting-started/session-recordings@2x.png) + +1. Click **Play** to see a full recording of your session. + +## Step 5/5. Access the server from the command line + +To access the server using commands in a terminal: + +1. Open a new terminal window. + +1. Sign in to your Teleport cluster by running the `tsh login` command with the + URL of your cluster and the name of your Teleport user, assigning + to your account subdomain and to + your Teleport username: + + ```code + $ tsh login --proxy=.teleport.sh --user= + ``` + + When prompted, authenticate using your password, authenticator app, or hardware key. + The command displays information about your Teleport cluster and account. For example: + + ```code + > Profile URL: https://example.teleport.sh:443 + Logged in as: admin@teleport.example.com + Cluster: example.teleport.sh + Roles: access, auditor, editor + Logins: root + Kubernetes: enabled + Valid until: 2023-07-08 01:35:20 -0700 PDT [valid for 12h0m0s] + Extensions: login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy + ``` + +1. List the servers your Teleport user can access. + + ```code + $ tsh ls + ``` + + You should see the name of the container you just registered. For example: + + ```code + Node Name Address Labels + ------------ --------- ---------------------------------------------------------------------------------------- + b6c1072b5af5 ⟵ Tunnel + ``` + +1. Access your server as the `root` user, assigning to + the name of the server as displayed by `tsh ls`: + + ```code + $ tsh ssh root@ + ``` + +## Next steps + +This guide introduced how you can use Teleport Enterprise (Cloud) to protect your +infrastructure by demonstrating how to register a server with your Teleport +cluster. + +You can provide secure access to more of your infrastructure through Teleport by +deploying one or more Teleport **Agents** and configuring role-based access +control for users. + +Agents proxy traffic to all of your infrastructure resources—including servers, +databases, Kubernetes clusters, cloud provider APIs, and Windows desktops. +Role-based access control ensures that only authorized users are allowed access +to those resources. + +To learn more information about deploying agents, see [Deploy Teleport Agents +with Terraform](admin-guides/infrastructure-as-code/terraform-starter/enroll-resources.mdx). diff --git a/src/components/ThumbsFeedback.module.css b/src/components/ThumbsFeedback.module.css new file mode 100644 index 0000000..a12dbb7 --- /dev/null +++ b/src/components/ThumbsFeedback.module.css @@ -0,0 +1,38 @@ +.feedbackForm { + z-index: 10; + position: relative; + padding: 1rem 0; +} + +.svgContainer { + display: flex; + flex-direction: column; + align-items: center; + text-align: center; +} + +.feedbackTitle { + font-size: 1.25rem; /* Slightly larger font size */ + font-weight: bold; + margin-bottom: 0.5rem; + color: var(--color-darkest); +} + +.buttonContainer { + display: flex; + justify-content: center; + gap: 1rem; +} + +.feedbackButton { + font-size: 1.5rem; + background: none; + border: none; + cursor: pointer; +} + +.feedbackMessage { + margin-top: 1rem; + color: green; +} + diff --git a/src/components/ThumbsFeedback.tsx b/src/components/ThumbsFeedback.tsx new file mode 100644 index 0000000..8923200 --- /dev/null +++ b/src/components/ThumbsFeedback.tsx @@ -0,0 +1,57 @@ +import React, { useState } from 'react'; +import styles from './ThumbsFeedback.module.css'; + +// Define gtag on window object for TypeScript +declare global { + interface Window { + gtag: (...args: any[]) => void; + } +} + +const ThumbsFeedback = () => { + const [submitted, setSubmitted] = useState(false); + + const handleFeedback = (type: 'up' | 'down') => { + if (typeof window !== 'undefined' && typeof window.gtag === 'function') { + window.gtag('event', 'feedback', { + event_category: 'Thumbs', + event_label: type, + value: 1, + }); + } + + setSubmitted(true); + }; + + if (submitted) { + return
Thanks for the feedback!
; + } + + return ( +
+
+

Was this page helpful?

+
+ + + +
+
+
+ ); +}; + +export default ThumbsFeedback; + diff --git a/src/theme/DocItem/Layout/index.tsx b/src/theme/DocItem/Layout/index.tsx index 7082457..b88a6ba 100644 --- a/src/theme/DocItem/Layout/index.tsx +++ b/src/theme/DocItem/Layout/index.tsx @@ -13,6 +13,7 @@ import DocBreadcrumbs from "@theme/DocBreadcrumbs"; import Unlisted from "@theme/ContentVisibility/Unlisted"; import NavbarMobileSidebarToggle from "@theme/Navbar/MobileSidebar/Toggle"; import type { Props } from "@theme/DocItem/Layout"; +import ThumbsFeedback from '@site/src/components/ThumbsFeedback'; import styles from "./styles.module.css"; @@ -65,6 +66,7 @@ export default function DocItemLayout({ children }: Props): JSX.Element { {docTOC.desktop &&
{docTOC.desktop}
} + ); } diff --git a/src/theme/MDXComponents/index.tsx b/src/theme/MDXComponents/index.tsx index ba95a1e..e230788 100644 --- a/src/theme/MDXComponents/index.tsx +++ b/src/theme/MDXComponents/index.tsx @@ -15,6 +15,7 @@ import MDXLi from "@theme/MDXComponents/Li"; import MDXImg from "@theme/MDXComponents/Img"; import Mermaid from "@theme/Mermaid"; import Command, { CommandLine, CommandComment } from "/src/components/Command"; +import ThumbsFeedback from "/src/components/ThumbsFeedback"; import Snippet from "/src/components/Snippet"; import { Var } from "/src/components/Variables"; import type { MDXComponentsObject } from "@theme/MDXComponents"; @@ -47,6 +48,7 @@ const MDXComponents: MDXComponentsObject = { snippet: Snippet, ul: MDXUl, Var: (props) => , // needed to circumvent props mismatch in types +ThumbsFeedback, }; export default MDXComponents;