diff --git a/docs/img/use-teleport/connect-cluster.png b/docs/img/use-teleport/connect-cluster.png deleted file mode 100644 index ad0fb1af9c0d3..0000000000000 Binary files a/docs/img/use-teleport/connect-cluster.png and /dev/null differ diff --git a/docs/img/use-teleport/connect-cluster@2x.png b/docs/img/use-teleport/connect-cluster@2x.png new file mode 100644 index 0000000000000..37b49304c7355 Binary files /dev/null and b/docs/img/use-teleport/connect-cluster@2x.png differ diff --git a/docs/img/use-teleport/connect-my-computer-setup@2x.png b/docs/img/use-teleport/connect-my-computer-setup@2x.png new file mode 100644 index 0000000000000..be75cd3d2a948 Binary files /dev/null and b/docs/img/use-teleport/connect-my-computer-setup@2x.png differ diff --git a/docs/img/use-teleport/connect-my-computer-status@2x.png b/docs/img/use-teleport/connect-my-computer-status@2x.png new file mode 100644 index 0000000000000..483867567257f Binary files /dev/null and b/docs/img/use-teleport/connect-my-computer-status@2x.png differ diff --git a/docs/img/use-teleport/connect-my-computer-top-bar@2x.png b/docs/img/use-teleport/connect-my-computer-top-bar@2x.png new file mode 100644 index 0000000000000..e01dd7ea24ccf Binary files /dev/null and b/docs/img/use-teleport/connect-my-computer-top-bar@2x.png differ diff --git a/docs/img/use-teleport/connect-ui-overview.png b/docs/img/use-teleport/connect-ui-overview.png deleted file mode 100644 index 24e9430c5cd16..0000000000000 Binary files a/docs/img/use-teleport/connect-ui-overview.png and /dev/null differ diff --git a/docs/img/use-teleport/connect-ui-overview@2x.png b/docs/img/use-teleport/connect-ui-overview@2x.png new file mode 100644 index 0000000000000..3e85dd81d35f6 Binary files /dev/null and b/docs/img/use-teleport/connect-ui-overview@2x.png differ diff --git a/docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx b/docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx new file mode 100644 index 0000000000000..d6cffce65bd31 --- /dev/null +++ b/docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx @@ -0,0 +1,6 @@ +- A macOS or Linux device. +- Teleport Connect v14.1+, on the same major version or one version behind the Teleport Proxy + Service version. See [version compatibility](../../faq.mdx#version-compatibility). +- A local Teleport user: you must authenticate using credentials or passwordless login, and not with + SSO. +- Permissions to create join tokens (verb `create` for [the `token` resource](../../access-controls/reference.mdx#teleport-resources)). diff --git a/docs/pages/connect-your-client/introduction.mdx b/docs/pages/connect-your-client/introduction.mdx index 6f3cf069e402b..da9dcf982bb64 100644 --- a/docs/pages/connect-your-client/introduction.mdx +++ b/docs/pages/connect-your-client/introduction.mdx @@ -126,7 +126,7 @@ server and database access within a single window. 1. Browse and connect to all the resources your user is permitted to access: - ![An example of Teleport Connect, populated with instances](../../img/use-teleport/connect-ui-overview.png) + ![An example of Teleport Connect, populated with instances](../../img/use-teleport/connect-ui-overview@2x.png) ### Web UI diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx index ab99fff346adb..85df89a3c4e41 100644 --- a/docs/pages/connect-your-client/teleport-connect.mdx +++ b/docs/pages/connect-your-client/teleport-connect.mdx @@ -6,7 +6,7 @@ description: Using Teleport Connect Teleport Connect provides easy and secure access to SSH servers, databases, and Kubernetes clusters, with support for other resources coming in the future. -![resources tab in Teleport Connect](../../img/use-teleport/connect-cluster.png) +![resources tab in Teleport Connect](../../img/use-teleport/connect-cluster@2x.png) ## Installation & upgrade @@ -46,7 +46,7 @@ $ "Teleport Connect Setup-(=teleport.version=).exe" /S ## User interface -![user interface of Teleport Connect](../../img/use-teleport/connect-ui-overview.png) +![user interface of Teleport Connect](../../img/use-teleport/connect-ui-overview@2x.png) The top bar of Teleport Connect consists of: @@ -64,6 +64,174 @@ The top bar of Teleport Connect consists of: The **status bar** at the bottom displays **cluster breadcrumbs** in the bottom left, indicating which cluster the current tab is bound to, and the **Share Feedback** button in the bottom right. +## Connect My Computer + +Connect My Computer makes it possible to add your personal machine to a Teleport cluster in just a +couple of clicks. + +It is the easiest way to add a computer to the cluster, whether you're exploring the capabilities of +Teleport or want your computer to be available in a Teleport-powered home lab. + +Connect My Computer sets up a Teleport agent managed completely by Teleport Connect, without having +to use the terminal to get the job done and without the need for tools like `systemctl` to control +the lifecycle of the agent. + +### Prerequisites + +(!docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx!) +{/* The permission to read and update users is needed during setup but not for regular usage, +that's why it's not listed in the partial. */} +- Permissions to read and update user objects in the backend (verbs `read` and `update` for [the + `user` resource](../access-controls/reference.mdx#teleport-resources)). + +The agent runs as the current system user, not as root. Some features are thus not available, such +as logging in as other system users or [host user creation](../server-access/guides/host-user-creation.mdx). + +### Setup and usage + +To begin the setup, click on the laptop icon in the top left and select "Connect My Computer". The +new tab will guide you through an interaction-free setup. Click "Connect" to start the setup. + +![Connect My Computer in the top bar](../../img/use-teleport/connect-my-computer-top-bar@2x.png) + +The setup creates a new role in the cluster which grants access to your device as the current system +user. The role is then added to your user object. + + +The role is responsible merely for granting SSH access as your system user to the node managed by +Connect My Computer. The node is subject to RBAC like any other SSH node in the cluster. + +In practice it means that users with administrative privileges can craft another role which grants +access to the node or simply assign the Connect My Computer role to themselves. + +We recommend using Connect My Computer only in scenarios where no other user could plausibly gain +access to the node, such as when exploring a Teleport cluster as its only user or in a home lab. + + +Next, the setup downloads a Teleport agent for your platform and runs `teleport node configure` +pointed at the current cluster. Once that is done, Connect My Computer starts the agent and waits +for it to show up in the cluster as an SSH node. + +![Connect My Computer setup](../../img/use-teleport/connect-my-computer-setup@2x.png) + +After the agent joins the cluster, the tab transitions to showing the status of the agent. From +here, you can connect to the node made available by the agent, stop and start the agent, as well as +completely remove it. Manually logging out of the cluster will remove the agent as well. + +![Connect My Computer status](../../img/use-teleport/connect-my-computer-status@2x.png) + +Your computer will be shared while Teleport Connect is open. To stop sharing, close Teleport Connect +or stop the agent through the Connect My Computer tab. Sharing will resume on app restart, unless +you stop the agent before exiting. The agent stops immediately if Teleport Connect unexpectedly +crashes. + +### Agent maintenance + +The version of the agent downloaded by Teleport Connect always matches the version of Teleport +Connect. After upgrading Teleport Connect, Connect My Computer is going to automatically attempt to +download a matching agent version before launching the agent. + +Connect My Computer always stores just a single version of the agent on disk. + + + +The agent is stored at `~/Library/Caches/Teleport Connect/teleport/teleport`. + + +The agent is stored at `~/.cache/Teleport Connect/teleport/teleport` by default. The path respects +`$XDG_CACHE_HOME`. + + + +### Troubleshooting Connect My Computer + +#### Accessing agent logs + +After the setup is done, open the Connect My Computer tab and from the three dots menu within the +tab choose "Open agent logs directory". + + + +The logs are stored at `~/Library/Application Support/Teleport Connect/agents//logs`. + + +The logs are stored at `~/.config/Teleport Connect/agents//logs`. + + + +#### The Connect My Computer icon is not visible in the top bar + +The icon is visible only if your setup satisfies the following requirements: + +(!docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx!) + +#### The Connect My Computer tab says that the agent is running, but the computer is not visible in the cluster + +Click "Connect" in the Connect My Computer tab. If the error message in the new tab says "access +denied", it likely means that there's a role assigned to your cluster user which denies access to +the Connect My Computer node, either by denying the specific login or access to the node itself +through fields like `node_labels`. To resolve this problem, inspect the role list in the Management +section of the Web UI. First, check what roles are assigned to your user object and then inspect +each role. Look for a role with broad `deny` rules. + +If the error message mentions a node or a tunnel not being found, it means that while the cluster +has a cached view of the agent, the agent did not join the cluster just yet. Wait for a couple of +seconds and try connecting to the node again. If the problem persists, check [the agent logs](#accessing-agent-logs). + +#### Connect My Computer does not work after changing system username + +The system username that was in use at the time of configuring Connect My Computer is persisted in +the Connect My Computer role for the given cluster user. To regain access to the Connect My Computer +node, add the new system username under the `logins` section of the role. The role can be identified +by its name following the format `connect-my-computer-`. + +Another solution is to [restart the setup](#restarting-the-setup). + +#### The agent cannot join the cluster and the logs say the token has expired or was not found + +In that scenario, the agent emits logs like these when starting up: + +```text +INFO [PROC:1] Joining the cluster with a secure token. pid:54364.1 service/connect.go:460 +INFO [AUTH] Attempting registration via proxy server. auth/register.go:279 +ERRO [PROC:1] Can not join the cluster as node, the token expired or not found. Regenerate the token and try again. pid:54364.1 service/connect.go:106 +``` + +During the setup, Connect My Computer creates [a join token](../agents/join-services-to-your-cluster/join-token.mdx) +that is valid for up to five minutes. If the logs say that the token has expired, it most likely +means that the initial attempt to join the cluster has failed and you started another one after more +than five minutes. + +To resolve this problem, remove the agent and [perform the setup again](#restarting-the-setup). + +#### Restarting the setup + +Since Teleport nodes are completely stateless, in case of problems with starting the agent or +joining the cluster you may attempt to run the setup again. Either click "Retry" if the setup has +failed or choose "Remove agent" from the three dots menu within the Connect My Computer tab after +the agent was successfully configured. + +#### Preventing user access to Connect My Computer + +If you wish to prevent cluster users from using Connect My Computer, make sure they don't have +permissions to create new join tokens. This is controlled by the `create` verb for the `token` +resource. Either deny this permission explicitly or do not grant it in the first place. See [Access +Controls Reference Documentation](../access-controls/reference.mdx#teleport-resources) for more +details. Denying this permission will hide the icon in the top bar. + +Users who already set up agents will still be able to manage those agents, even after the denying +them permissions to create join tokens. This is to ensure that a malicious admin is not able to make +a user set up an agent and then lock the user out of removing the agent. + +To instantly revoke access to agents that have already joined the cluster, look for nodes labeled +with the `teleport.dev/connect-my-computer/owner` label and then [place +locks](../access-controls/guides/locking.mdx) on those nodes. + +```code +$ tctl nodes ls -v --query='labels["teleport.dev/connect-my-computer/owner"] != ""' +$ tctl lock --server-id= --message="Using Connect My Computer is forbidden" +``` + ## Connecting to an SSH server 1. Open a tab with cluster resources by clicking on the plus symbol at the right end of the tab bar.