Skip to content

[v14] Reword Troubleshooting section in Connect docs #33201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ravicious merged 1 commit into from
Oct 10, 2023
Merged

[v14] Reword Troubleshooting section in Connect docs #33201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 38 additions & 20 deletions docs/pages/connect-your-client/teleport-connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,27 +263,39 @@ The changes will take effect at the next launch.

## Troubleshooting

Logging out of a cluster, closing the app and logging in again resets all app state related to that
cluster. This can help if you encounter a bug which renders the user interface partially unusable.
It might also help if you have issues with connecting to an active cluster that don't happen in the
Web UI.
Resetting the app state might help with UI crashes caused by Teleport Connect getting into an
abnormal state. This might happen after downgrading Teleport Connect or performing substantial
server-side changes. Those UI crashes typically manifest as a blank window or an Internal Error
alert.

To reset the state related to a particular cluster:

1. Log out of the cluster.
1. Close Teleport Connect.
1. Open Teleport Connect, then log back in to the cluster.

To completely wipe all app state:

1. Close Teleport Connect.
1. Remove the internal `tsh` folder and the `app_state.json` file to log out of all clusters and
clear all remembered tabs and connections.

<Tabs>
<TabItem label="macOS">
To force the app to log you out of all clusters, close the app and remove the `~/Library/Application
Support/Teleport Connect/tsh` folder. Removing the file `~/Library/Application
Support/Teleport Connect/app_state.json` will clear all remembered tabs and connections.
```code
$ rm -rf ~/Library/Application\ Support/Teleport\ Connect/{tsh,app_state.json}
```
</TabItem>
<TabItem label="Linux">
To force the app to log you out of all clusters, close the app and remove the `~/.config/Teleport
Connect/tsh` folder. Removing the file `/.config/Teleport Connect/app_state.json` will clear
all remembered tabs and connections.
```code
$ rm -rf ~/.config/Teleport\ Connect/{tsh,app_state.json}
```
</TabItem>
<TabItem label="Windows">
To force the app to log you out of all clusters, close the app and remove the
`C:\Users\%UserName%\AppData\Roaming\Teleport Connect\tsh` folder. Removing the file
`C:\Users\%UserName%\AppData\Roaming\Teleport Connect\app_state.json` will clear all remembered tabs
and connections.
```code
$ rmdir /s /q C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\tsh
$ del C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\app_state.json
```
</TabItem>
</Tabs>

Expand All @@ -294,16 +306,20 @@ and follow the *Submit a Bug* link.

<Tabs>
<TabItem label="macOS">
Be sure to attach logs, which can be found under `~/Library/Application Support/Teleport Connect/logs`.
The version of the app can be found in the app menu under the About Teleport Connect menu item.
Be sure to attach logs, which can be found in the app menu under Help -> Open Logs Directory. The
logs are stored in `~/Library/Application Support/Teleport Connect/logs`.

The app version can be found in the app menu under Teleport Connect -> About Teleport Connect.

To get more detailed logs, run Teleport Connect with the `--connect-debug` flag:

(!docs/pages/connect-your-client/includes/launch-connect-with-flags-macos.mdx flags="--connect-debug"!)
</TabItem>
<TabItem label="Linux">
Be sure to attach logs, which can be found under `~/.config/Teleport Connect/logs`. The app version
can be found by pressing `Alt` to access the app menu, then -> Help -> About Teleport Connect.
Be sure to attach logs, which can be found by pressing `Alt` to access the app menu, then Help ->
Open Logs Directory. The logs are stored in `~/.config/Teleport Connect/logs`.

The app version can be found under Help -> About Teleport Connect.

To get more detailed logs, run Teleport Connect with the `--connect-debug` flag:

Expand All @@ -312,10 +328,12 @@ $ teleport-connect --connect-debug
````
</TabItem>
<TabItem label="Windows">
Be sure to attach logs, which can be found under `C:\Users\%UserName%\AppData\Roaming\Teleport Connect\logs`.
Be sure to attach logs, which can be found by pressing `Alt` to access the app menu, then Help ->
Open Logs Directory. The logs are stored in `C:\Users\%UserName%\AppData\Roaming\Teleport
Connect\logs`.
You may need to adjust File Explorer to [view hidden files and folders](https://support.microsoft.com/en-us/search?query=how%20to%20view%20hidden%20files%20in%20windows%2010).
The app version can be found by pressing `Alt` to access the app menu -> Help -> About Teleport Connect.

The app version can be found under Help -> About Teleport Connect.

To get more detailed logs, open Teleport Connect from the Command Prompt with the `--connect-debug` flag:

Expand Down