mirror of
https://github.com/gravitational/teleport
synced 2024-10-20 01:03:40 +00:00
[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:
parent
ae99259f41
commit
efaf97e872
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 |
|
@ -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>
|
Loading…
Reference in a new issue