Skip to content

Commit 24dbc68

Browse files
mmcallistermmcallister
committed
new test file
1 parent d0df619 commit 24dbc68

File tree

1 file changed

+252
-0
lines changed

1 file changed

+252
-0
lines changed

‎docs/get-started_test_copy.mdx

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
title: "Get Started with Teleport"
3+
description: "Shows you how to set up a Teleport Enterprise (Cloud) account and protect your first resource with Teleport."
4+
tocDepth: 3
5+
---
6+
7+
## Was this helpful?
8+
9+
<ThumbsFeedback />
10+
11+
Teleport Enterprise helps organizations provide secure access to their
12+
infrastructure with minimal configuration and cluster management.
13+
14+
With Teleport Enterprise (Cloud), the Teleport Auth Service and Teleport Proxy
15+
Service are managed for you as cloud-based services. These services provide you
16+
with immediate access to a scalable and fault-tolerant certificate authority and
17+
reverse proxy that you don't need to manage or maintain. You can focus on
18+
enrolling the resources you want to protect and configuring secure role-based
19+
access for private and public networks across the globe.
20+
21+
After you start a [free trial](https://goteleport.com/signup) of Teleport
22+
Enterprise (Cloud), you can set up role-based access control (RBAC), enable
23+
single sign-on, and prevent unauthorized use of organization resources.
24+
25+
This guide explains how to register a local server with a Teleport Enterprise
26+
(Cloud) account. After you register the server, you can access it through the
27+
Teleport Web UI in a browser or using the terminal. You can also record your
28+
sessions, so you can review them later.
29+
30+
## Prerequisites
31+
32+
- A Teleport Enterprise (Cloud) account. You can sign up for a free trial at the
33+
following page:
34+
35+
https://goteleport.com/signup/
36+
37+
After you sign up, you receive an email invitation to activate your account.
38+
Use this account to authenticate your identity when you access the Teleport
39+
Enterprise (Cloud) cluster.
40+
41+
- For following this guide, Docker installed on your workstation.
42+
43+
This guide illustrates how to register a server with Teleport Enterprise Cloud
44+
using a Docker container and the Teleport SSH Service. Docker is only required
45+
for the local demo environment used in this guide. You can find installation
46+
instructions for Docker on [Docker's
47+
website](https://docs.docker.com/get-docker/). If you want to register servers
48+
in Teleport without using Docker, see the getting started guide for
49+
[server access](enroll-resources/server-access/getting-started.mdx).
50+
51+
- The `tsh` client tool. `tsh` is included in the same packages and archives as
52+
the `teleport` binary. See the [Installation Guide](installation.mdx) for how
53+
to install Teleport on your operating system.
54+
55+
This guide only requires the `tsh` client tool to access a server from a
56+
terminal. If you don't install the `tsh` client tool, you can access the
57+
server in Teleport Enterprise (Cloud) using the Web UI through your browser.
58+
59+
## Step 1/5. Spin up a server
60+
61+
To spin up a new server using Docker:
62+
63+
1. Open a terminal on your workstation.
64+
65+
1. Start a Docker container on your workstation to prepare a server that you want enroll
66+
as a resource in your Teleport Enterprise (Cloud) cluster:
67+
68+
```code
69+
$ docker run --interactive --tty ubuntu:24.04 /bin/bash
70+
```
71+
72+
This command starts a new shell session in a container running Ubuntu 24.04.
73+
74+
1. Run the following command to install `curl` and `telnet` from the package management repository:
75+
76+
```code
77+
$ apt update && apt install -y curl telnet
78+
```
79+
80+
The script that installs Teleport in this guide requires both `curl` and `telnet` to be installed.
81+
82+
Keep the new shell open in your terminal.
83+
84+
## Step 2/5. Install the Teleport SSH Service
85+
86+
To install the Teleport SSH Service on your server:
87+
88+
1. Open a browser and go to the address for your Teleport cluster. For example,
89+
if your Teleport account is `example`, open `https://example.teleport.sh`.
90+
91+
1. Sign in with the credentials you used to activate your Teleport account.
92+
93+
The first time you sign in, you are prompted to add your first resource:
94+
95+
![Add your first resource](../img/cloud/getting-started/add-my-first-resource@2x.png)
96+
97+
1. Click **Add my first resource**, and you will see the option to enroll
98+
resources in your Teleport cluster.
99+
100+
1. Type *server* in the search box to filter the list of resources:
101+
102+
![Select resource type](../img/cloud/getting-started/choose-resource@2x.png)
103+
104+
1. Click **Ubuntu 18.04+** to register the server in the Docker container.
105+
106+
After you select the resource type, the Web UI prompts you for your
107+
multi-factor authentication device, then displays a script to install and
108+
configure the Teleport SSH Service. For example:
109+
110+
![Configure resource](../img/cloud/getting-started/paste-script@2x.png)
111+
112+
1. The Teleport installation script uses `sudo`, which is not installed on your
113+
Docker container. Before copying the command to run the installation script,
114+
you need to alias `sudo` in the container terminal shell session.
115+
116+
In the terminal with the container shell session, alias `sudo` by running
117+
the following command:
118+
119+
```code
120+
$ alias sudo=""
121+
```
122+
123+
1. Copy the command to run the installation script from the Teleport Web UI and paste it
124+
into the container shell session.
125+
126+
Leave the script running in the shell. After Teleport is installed on the server,
127+
you'll see a message in the Web UI that your new Teleport instance was successfully detected:
128+
129+
![Connected successfully](../img/cloud/getting-started/successfully-connected@2x.png)
130+
131+
To continue, click **Next**.
132+
133+
1. Confirm that you want to authenticate as the `root` user and click **Next**:
134+
135+
![Choose your user](../img/cloud/getting-started/set-up-access@2x.png)
136+
137+
1. Respond to the MFA prompt again, then click **Test Connection** to verify
138+
access to the server.
139+
140+
![Start session](../img/cloud/getting-started/test-connection@2x.png)
141+
142+
## Step 3/5. Start a session
143+
144+
To start a session on the server you just added to Teleport:
145+
146+
1. Click **Start Session** to start an interactive session.
147+
148+
You should see a terminal prompt in a new browser window. Your Teleport
149+
account routes your SSH connection through the Teleport Proxy Service, which
150+
connects to your container through a reverse tunnel.
151+
Reverse tunnels allow Teleport to manage access to resources like Kubernetes
152+
clusters and remote desktops, even if these resources are running on private networks.
153+
154+
If you get an error connecting to your container, interrupt the `teleport` process in
155+
the container shell with **Ctrl-C**, then run `teleport start` to restart the process.
156+
157+
1. Execute some commands in your terminal.
158+
159+
1. Enter the `exit` command to end the remote interactive session. Close the
160+
browser tab.
161+
162+
1. In the last step of **Enroll New Resource**, click **Finish**.
163+
164+
1. Click **Browse existing resources** to see your new server listed in the Teleport Web UI.
165+
166+
## Step 4/5. Play back your session
167+
168+
As Teleport proxies SSH connections to registered servers, it records the
169+
commands that users execute during their sessions so operators can play them
170+
back later to investigate issues.
171+
172+
To play back a session in the Teleport Web UI:
173+
174+
1. Find the left sidebar and navigate to **Audit > Session Recordings**.
175+
176+
1. In the sidebar, under **Activity**, click **Session Recordings**.
177+
178+
You will see the recording for your interactive session from the previous
179+
step listed. For example:
180+
181+
![Session
182+
recordings](../img/cloud/getting-started/session-recordings@2x.png)
183+
184+
1. Click **Play** to see a full recording of your session.
185+
186+
## Step 5/5. Access the server from the command line
187+
188+
To access the server using commands in a terminal:
189+
190+
1. Open a new terminal window.
191+
192+
1. Sign in to your Teleport cluster by running the `tsh login` command with the
193+
URL of your cluster and the name of your Teleport user, assigning
194+
<Var name="example" /> to your account subdomain and <Var name="username" /> to
195+
your Teleport username:
196+
197+
```code
198+
$ tsh login --proxy=<Var name="example" />.teleport.sh --user=<Var name="username" />
199+
```
200+
201+
When prompted, authenticate using your password, authenticator app, or hardware key.
202+
The command displays information about your Teleport cluster and account. For example:
203+
204+
```code
205+
> Profile URL: https://example.teleport.sh:443
206+
Logged in as: admin@teleport.example.com
207+
Cluster: example.teleport.sh
208+
Roles: access, auditor, editor
209+
Logins: root
210+
Kubernetes: enabled
211+
Valid until: 2023-07-08 01:35:20 -0700 PDT [valid for 12h0m0s]
212+
Extensions: login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy
213+
```
214+
215+
1. List the servers your Teleport user can access.
216+
217+
```code
218+
$ tsh ls
219+
```
220+
221+
You should see the name of the container you just registered. For example:
222+
223+
```code
224+
Node Name Address Labels
225+
------------ --------- ----------------------------------------------------------------------------------------
226+
b6c1072b5af5 ⟵ Tunnel
227+
```
228+
229+
1. Access your server as the `root` user, assigning <Var name="node-name" /> to
230+
the name of the server as displayed by `tsh ls`:
231+
232+
```code
233+
$ tsh ssh root@<Var name="node-name" />
234+
```
235+
236+
## Next steps
237+
238+
This guide introduced how you can use Teleport Enterprise (Cloud) to protect your
239+
infrastructure by demonstrating how to register a server with your Teleport
240+
cluster.
241+
242+
You can provide secure access to more of your infrastructure through Teleport by
243+
deploying one or more Teleport **Agents** and configuring role-based access
244+
control for users.
245+
246+
Agents proxy traffic to all of your infrastructure resources—including servers,
247+
databases, Kubernetes clusters, cloud provider APIs, and Windows desktops.
248+
Role-based access control ensures that only authorized users are allowed access
249+
to those resources.
250+
251+
To learn more information about deploying agents, see [Deploy Teleport Agents
252+
with Terraform](admin-guides/infrastructure-as-code/terraform-starter/enroll-resources.mdx).

0 commit comments

Comments
 (0)