[Docs] Update 'Using Teleport Connect' for Linux & Windows (#16770)

* pre-update edits

* update for multiple OSes

Also adjusted line breaks assuming a 100char cutoff.

* add insecure flag for Windows

* Apply suggestions from code review

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>

* Update docs/pages/connect-your-client/teleport-connect.mdx

* Update docs/pages/connect-your-client/teleport-connect.mdx

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>

* Apply suggestions from code review

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

* don't use markdown's auto-iteration

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
This commit is contained in:
Alex Fornuto 2022-10-03 12:09:48 -05:00 committed by GitHub
parent ae99259f41
commit efaf97e872
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 87 additions and 22 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 429 KiB

After

Width:  |  Height:  |  Size: 242 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 428 KiB

After

Width:  |  Height:  |  Size: 250 KiB

View file

@ -11,10 +11,31 @@ other resources such as Kubernetes clusters and applications coming in the futur
## Installation & upgrade
Head over to the [Downloads](https://goteleport.com/download/) page to download the most recent
version of Teleport Connect. As of now, Teleport Connect supports macOS only. Double-click the
downloaded `.dmg` file and drag the Teleport Connect icon to the Applications folder.
version. Teleport Connect supports macOS, Linux, and Windows.
<Tabs>
<TabItem label="macOS">
Double-click the downloaded `.dmg` file and drag the Teleport Connect icon to the Applications folder.
To upgrade Teleport Connect to a newer version, drag the new version to the Applications folder.
</TabItem>
<TabItem label="Linux">
Download the DEB (Debian-based distros) or RPM (RHEL-based distros) package and install it using
your package manager. Repeat the process for in-place upgrades.
You can also download the project as a `tar.gz` file to extract and run it in place:
```code
$ tar -xf teleport-(=teleport.version=)-linux-*.tar.gz
```
</TabItem>
<TabItem label="Windows">
Download and run the installer `.exe` file. It will install and open Teleport Connect without
further user input.
Repeat the process with newer versions to upgrade.
</TabItem>
</Tabs>
## User interface
@ -22,35 +43,34 @@ To upgrade Teleport Connect to a newer version, drag the new version to the Appl
The top bar of Teleport Connect consists of:
- The **profile selector** (the top right), which allows you to switch between profiles on different Teleport
clusters as well as log in or out of the clusters.
- The **profile selector** (the top right), which allows you to switch between profiles on different
Teleport clusters as well as log in or out of the clusters.
- The **connection list** (the top left) showing recent connections, allowing you to seamlessly switch
between them.
- The **command bar** (in the middle), which launches any command you input in a new terminal tab.
- The **cluster selector** (to the left of the command bar), which shows up only if you have set up Trusted Clusters and there are leaf clusters
connected to the root cluster. It lets you browse leaf cluster resources. It also changes
which cluster the commands in the command bar are going to target.
- The **cluster selector** (to the left of the command bar), which shows up only if you have set up
Trusted Clusters and there are leaf clusters connected to the root cluster. It lets you browse
leaf cluster resources. It also changes which cluster the commands in the command bar are going to target.
## 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.
You can also press `Cmd + T` to achieve the same result.
You can also press `Ctrl/Cmd + T` to achieve the same result.
2. Look for the SSH server you want to connect to and click the Connect button to the right.
3. Select or enter the SSH user you wish to log in as and press `Enter`.
4. A new tab will open with a shell session on the chosen server.
Alternatively, you can type `tsh ssh` into the command bar and the autocompletion will help you
connect to a server.
Alternatively, you can type `tsh ssh` into the command bar in the Teleport Connect window, and the autocompletion will help
you connect to a server.
## Connecting to a database
1. Open a tab with cluster resources by clicking on the plus symbol at the end of the tab bar. You
can also press `Cmd + T` to achieve the same result.
can also press `Ctrl/Cmd + T` to achieve the same result.
2. Select the Databases section.
3. Look for the database server you wish to connect to and click the Connect button to the right.
4. Select or enter the database user you with to use and press `Enter`.
5. A new tab will open with a new connection established between your device and the database
server.
5. A new tab will open with a new connection established between your device and the database server.
This connection will remain active until you click the Close Connection button or close Teleport
Connect. The port number will persist between app restarts—you can set up your favorite client
@ -64,8 +84,8 @@ Connect with GUI section.
### With a CLI client
The database connection tab shows the command that can be used to connect to the database. You can
modify the database name of the connection and then click the Run button to open a new
terminal tab with that command executed.
modify the database name of the connection and then click the Run button to open a new terminal tab
with that command executed.
## Connecting to multiple clusters
@ -74,7 +94,7 @@ your first cluster, open the profile selector at the top right and click the *+A
button. You can switch between active profiles in multiple ways:
- Click at the profile selector button at the top right.
- Open the profile selector with a shortcut (`Cmd + I`).
- Open the profile selector with a shortcut (`Ctrl/Cmd + I`).
- Using the connection list at the top left to select a connection will automatically switch you to
the right profile.
@ -97,18 +117,45 @@ cluster. This can help if you encounter a bug which renders the user interface p
It might also help if you have issues with connecting to an active cluster that don't happen in the
Web UI.
<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 under `~/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.
</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.
</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.
</TabItem>
</Tabs>
### Submitting an issue
To submit an issue, click the Submit Feedback button at the bottom right (the speech bubble symbol)
and follow the *Submit a Bug* link.
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.
<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.
</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.
</TabItem>
<TabItem label="Windows">
Be sure to attach logs, which can be found under `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.
</TabItem>
</Tabs>
### Updating local shell environment
@ -119,9 +166,11 @@ see them only after you restart the app.
### Insecure mode
You can open Teleport Connect in insecure mode, which skips HTTPS certificate verification when
talking to a Teleport Proxy Service. This is useful in test environments or for demo purposes. We do
not recommend using this mode in production.
talking to a Teleport Proxy Service. This is useful in test environments or for demo purposes. We
do not recommend using this mode in production.
<Tabs>
<TabItem label="macOS">
To launch the app in insecure mode, open a terminal first. From there you can launch the app in one
of two ways:
@ -132,3 +181,19 @@ $ open -a "Teleport Connect" --args --insecure
# Passing the flag to the executable directly:
$ /Applications/Teleport\ Connect.app/Contents/MacOS/Teleport\ Connect --insecure
```
</TabItem>
<TabItem label="Linux">
From a terminal, open Teleport Connect with the `--insecure` flag:
```code
$ teleport-connect --insecure
````
</TabItem>
<TabItem label="Windows">
From the Command Prompt, open Teleport Connect with the `--insecure` flag:
```code
$ "%LocalAppData%\Programs\teleport-connect\Teleport Connect.exe" --insecure
````
</TabItem>
</Tabs>